Phoenix Logo

phoenix_title wx.StaticBox

A static box is a rectangle drawn around other windows to denote a logical grouping of items.

Note that while the previous versions required that windows appearing inside a static box be created as its siblings (i.e. use the same parent as the static box itself), since wxWidgets 2.9.1 it is also possible to create them as children of wx.StaticBox itself and you are actually encouraged to do it like this if compatibility with the previous versions is not important.

So the new recommended way to create static box is:

def CreateControls(self):

    panel = wx.Panel(self)
    box = wx.StaticBox(panel, wx.ID_ANY, "StaticBox")

    text = wx.StaticText(box, wx.ID_ANY, "This window is a child of the staticbox")

    # Other code...

While the compatible

box = wx.StaticBox(panel, wx.ID_ANY, "StaticBox")

text = wx.StaticText(panel, wx.ID_ANY, "This window is a child of the panel")

# Other code...

Also note that there is a specialized wx.Sizer class ( wx.StaticBoxSizer) which can be used as an easier way to pack items into a static box.


class_hierarchy Class Hierarchy

Inheritance diagram for class StaticBox:


appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


method_summary Methods Summary

__init__ Default constructor.
Create Creates the static box for two-step construction.
Enable Enables or disables the box without affecting its label window, if any.
GetBordersForSizer Returns extra space that may be needed for borders within a StaticBox.
GetClassDefaultAttributes  

api Class API



class wx.StaticBox(Control)

Possible constructors:

StaticBox()

StaticBox(parent, id=ID_ANY, label="", pos=DefaultPosition,
          size=DefaultSize, style=0, name=StaticBoxNameStr)

A static box is a rectangle drawn around other windows to denote a logical grouping of items.


Methods



__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.



__init__ (self, parent, id=ID_ANY, label=””, pos=DefaultPosition, size=DefaultSize, style=0, name=StaticBoxNameStr)

Constructor, creating and showing a static box.

Parameters:
  • parent (wx.Window) – Parent window. Must not be None.
  • id (wx.WindowID) – Window identifier. The value wx.ID_ANY indicates a default value.
  • label (string) – Text to be displayed in the static box, the empty string for no label.
  • pos (wx.Point) – Window position. If wx.DefaultPosition is specified then a default position is chosen.
  • size (wx.Size) – Checkbox size. If wx.DefaultSize is specified then a default size is chosen.
  • style (long) – Window style. There are no StaticBox-specific styles, but generic ALIGN_LEFT, ALIGN_CENTRE_HORIZONTAL and ALIGN_RIGHT can be used here to change the position of the static box label when using wxGTK (these styles are ignored under the other platforms currently).
  • name (string) – Window name.

See also

Create





Create(self, parent, id=ID_ANY, label="", pos=DefaultPosition, size=DefaultSize, style=0, name=StaticBoxNameStr)

Creates the static box for two-step construction.

See wx.StaticBox for further details.

Parameters:
  • parent (wx.Window) –
  • id (wx.WindowID) –
  • label (string) –
  • pos (wx.Point) –
  • size (wx.Size) –
  • style (long) –
  • name (string) –
Return type:

bool



Enable(self, enable=True)

Enables or disables the box without affecting its label window, if any.

wx.StaticBox overrides wx.Window.Enable in order to avoid disabling the control used as a label, if this box is using one. This is done in order to allow using a wx.CheckBox, for example, label and enable or disable the box according to the state of the checkbox: if disabling the box also disabled the checkbox in this situation, it would make it impossible for the user to re-enable the box after disabling it, so the checkbox stays enabled even if box->Enable(false) is called.

However with the actual behaviour, implemented in this overridden method, the following code (shown using C++11 only for convenience, this behaviour is not C++11-specific):

# NOTE: wxPython doesn't yet support using a control in place of the label...
check = wx.CheckBox(parent, wx.ID_ANY, "Use the box")
box = wx.StaticBox(parent, wx.ID_ANY, check)
check.Bind(wx.EVT_CHECKBOX, lambda evt: box.Enable(evt.IsChecked()))

does work as expected.

Please note that overriding Enable to not actually disable this window itself has two possibly unexpected consequences:

  • The box retains its enabled status, i.e. IsEnabled still returns True, after calling Enable(false) .
  • The box children are enabled or disabled when the box is, which can result in the loss of their original state. E.g. if a box child is initially disabled, then the box itself is disabled and, finally, the box is enabled again, this child will end up being enabled too (this wouldn’t happen with any other parent window as its children would inherit the disabled state from the parent instead of being really disabled themselves when it is disabled). To avoid this problem, consider using wx.wxEVT_UPDATE_UI to ensure that the child state is always correct or restoring it manually after re-enabling the box.
Parameters:enable (bool) –
Return type:bool


GetBordersForSizer(self)

Returns extra space that may be needed for borders within a StaticBox.

Return type:tuple
Returns:( borderTop, borderOther )


static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters:variant (WindowVariant) –
Return type: wx.VisualAttributes