.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.StaticBox:

==========================================================================================================================================
|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 possible to create them as children of :ref:`wx.StaticBox`  itself and doing this is strongly recommended and avoids several different repainting problems that could happen when creating the other windows as siblings of the box. 

So the recommended way to create static box and the controls inside it 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...



Creating the windows with the static box parent (i.e.  ``panel``   in the example above) as parent still works but can result in refresh and repaint problems. 

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





         



.. seealso:: :ref:`wx.StaticText`, :ref:`wx.StaticBoxSizer`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>StaticBox</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.StaticBox_inheritance.png" alt="Inheritance diagram of StaticBox" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.StaticBox.html" title="A static box is a rectangle drawn around other windows to denote a logical grouping of items." alt="" coords="54,315,157,344"/> <area shape="rect" id="node2" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="61,237,149,267"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="61,160,150,189"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,112"/> <area shape="rect" id="node5" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,88,35"/> <area shape="rect" id="node6" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.staticbox.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/wx.staticbox.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.staticbox.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.StaticBox.__init__`                                                   Default constructor.
:meth:`~wx.StaticBox.Create`                                                     Creates the static box for two-step construction.
:meth:`~wx.StaticBox.Enable`                                                     Enables or disables the box without affecting its label window, if any.
:meth:`~wx.StaticBox.GetBordersForSizer`                                         Returns extra space that may be needed for borders within a StaticBox.
:meth:`~wx.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.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, label="", pos=DefaultPosition, size=DefaultSize, style=0, name=StaticBoxNameStr)`
      
      Constructor, creating and showing a static box.                  
      
      
      
      
      :param `parent`: Parent window. Must not be ``None``.   
      :type `parent`: wx.Window
      :param `id`: Window identifier. The value ``wx.ID_ANY`` indicates a default value.   
      :type `id`: wx.WindowID
      :param `label`: Text to be displayed in the static box, the empty string for no label.   
      :type `label`: string
      :param `pos`: Window position. If `wx.DefaultPosition`       is specified then a default position is chosen.   
      :type `pos`: wx.Point
      :param `size`: Checkbox size. If `wx.DefaultSize`       is specified then a default size is chosen.   
      :type `size`: wx.Size
      :param `style`: 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).   
      :type `style`: long
      :param `name`: Window name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`Create`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






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

      Creates the static box for two-step construction.                  

      See :ref:`wx.StaticBox`  for further details.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `label`: 
      :type `label`: string
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long
      :param `name`: 
      :type `name`: string




      :rtype: `bool`








   .. method:: Enable(self, enable=True)

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

      :ref:`wx.StaticBox`  overrides :meth:`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 :ref:`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 :meth:`Enable`   to not actually disable this window itself has two possibly unexpected consequences: 



      - The box retains its enabled status, i.e. :meth:`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.  


                 


      :param `enable`: 
      :type `enable`: bool




      :rtype: `bool`








   .. method:: GetBordersForSizer(self)

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

      :rtype: `tuple`







      :returns: 

         ( `borderTop`, `borderOther` ) 








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: :ref:`wx.VisualAttributes`