X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/eb6a4098a0f2e9ae55e72ad960b3dfc134d177c9..d14a1e28567de23c586bc80017073d0c39f8d18f:/wxPython/wx/py/wxd/Sizers.py diff --git a/wxPython/wx/py/wxd/Sizers.py b/wxPython/wx/py/wxd/Sizers.py new file mode 100644 index 0000000000..918a80b7c2 --- /dev/null +++ b/wxPython/wx/py/wxd/Sizers.py @@ -0,0 +1,605 @@ +"""Decorator classes for documentation and shell scripting. + +Sizer is the abstract base class used for laying out subwindows in a +window. You cannot use Sizer directly; instead, you will have to use +one of the sizer classes derived from it. Currently there are +BoxSizer, StaticBoxSizer, NotebookSizer, GridSizer, and FlexGridSizer. + +The layout algorithm used by sizers in wxPython is closely related to +layout in other GUI toolkits, such as Java's AWT, the GTK toolkit or +the Qt toolkit. It is based upon the idea of the individual +subwindows reporting their minimal required size and their ability to +get stretched if the size of the parent window has changed. This will +most often mean, that the programmer does not set the original size of +a dialog in the beginning, rather the dialog will assigned a sizer and +this sizer will be queried about the recommended size. The sizer in +turn will query its children, which can be normal windows, empty space +or other sizers, so that a hierarchy of sizers can be constructed. +Note that wxSizer does not derive from wxWindow and thus do not +interfere with tab ordering and requires very little resources +compared to a real window on screen. + +What makes sizers so well fitted for use in wxPython is the fact that +every control reports its own minimal size and the algorithm can +handle differences in font sizes or different window (dialog item) +sizes on different platforms without problems. If e.g. the standard +font as well as the overall design of Motif widgets requires more +space than on Windows, the initial dialog size will automatically be +bigger on Motif than on Windows. + +If you wish to create a sizer class in wxPython you should derive the +class from PySizer in order to get Python-aware capabilities for the +various virtual methods. +""" + +__author__ = "Patrick K. O'Brien " +__cvsid__ = "$Id$" +__revision__ = "$Revision$"[11:-2] + + +# These are not the real wxPython classes. These are Python versions +# for documentation purposes. They are also used to apply docstrings +# to the real wxPython classes, which are SWIG-generated wrappers for +# C-language classes. + + +from Base import Object +import Parameters as wx + +try: + True +except NameError: + True = 1==1 + False = 1==0 + + +class Sizer(Object): + """Sizer is the abstract base class used for laying out subwindows + in a window. You shouldn't use Sizer directly; instead, you should + use one of the sizer classes derived from it. + + If you wish to create a sizer class in wxPython you should derive + the class from PySizer in order to get Python-aware capabilities + for the various virtual methods. + + Placing a child sizer in a sizer allows you to create hierarchies + of sizers (typically a vertical box as the top sizer and several + horizontal boxes on the level beneath). + + When you place a window in a sizer the window's initial size + (either set explicitly by the user or calculated internally when + using wxDefaultSize) is interpreted as the minimal and in many + cases also the initial size. This is particularly useful in + connection with SetSizeHints. + + Adding spacers to sizers gives more flexibility in the design of + dialogs. Imagine for example a horizontal box with two buttons at + the bottom of a dialog: you might want to insert a space between + the two buttons and make that space stretchable using the + proportion flag and the result will be that the left button will + be aligned with the left side of the dialog and the right button + with the right side - the space in between will shrink and grow + with the dialog. + + Several methods (Add, Insert, Prepend) take the following + parameters: + + proportion - Used only by BoxSizer to indicate if a child of a + sizer can change its size in the main orientation of the BoxSizer, + where 0 stands for not changeable and a value of more than zero is + interpreted relative to the value of other children of the same + BoxSizer. For example, you might have a horizontal BoxSizer with + three children, two of which are supposed to change their size + with the sizer. Then the two stretchable windows would each get a + value of 1 to make them grow and shrink equally with the sizer's + horizontal dimension. + + flag - This parameter can be used to set a number of flags which + can be combined using the binary OR operator |. Two main + behaviours are defined using these flags. One is the border + around a window: the border parameter determines the border width + whereas the flags given here determine where the border may be + (wx.TOP, wx.BOTTOM, wx.LEFT, wx.RIGHT or wx.ALL). The other flags + determine the child window's behaviour if the size of the sizer + changes. However this is not - in contrast to the proportion flag + - in the main orientation, but in the respectively other + orientation. So if you created a BoxSizer with the wx.VERTICAL + option, these flags will be relevant if the sizer changes its + horizontal size. A child may get resized to completely fill out + the new size (using either wx.GROW or wx.EXPAND), it may get + proportionally resized (wx.SHAPED), it may get centered + (wx.ALIGN_CENTER or wx.ALIGN_CENTRE) or it may get aligned to + either side (wx.ALIGN_LEFT and wx.ALIGN_TOP are set to 0 and thus + represent the default, wx.ALIGN_RIGHT and wx.ALIGN_BOTTOM have + their obvious meaning). With proportional resize, a child may + also be centered in the main orientation using + wx.ALIGN_CENTER_VERTICAL (same as wx.ALIGN_CENTRE_VERTICAL) and + wx.ALIGN_CENTER_HORIZONTAL (same as wx.ALIGN_CENTRE_HORIZONTAL) + flags. Finally, you can also specify wx.ADJUST_MINSIZE flag to + make the minimal size of the control dynamically adjust to the + value returned by its GetAdjustedBestSize() method - this allows, + for example, for correct relayouting of a static text control even + if its text is changed during run-time. + + border - Determines the border width, if the flag parameter is set + to any border. A border is not a visible element, but rather a + margin of empty space surrounding the item. + + userData - Allows an extra object to be attached to the sizer + item, for use in derived classes when sizing information is more + complex than the option and flag parameters will allow.""" + + def __init__(self): + """Must be defined by subclasses.""" + pass + + def Add(self, item, proportion=0, flag=0, border=0, + userData=wx.NULL): + """Add item to sizer. + + item - window, sizer, or spacer. Spacer is specified with a + (width, height) tuple or wx.Size representing the spacer size. + + Call Layout() to update the layout on-screen after adding.""" + pass + + def Clear(self, delete_windows=False): + """Remove all items from this sizer. + + If delete_windows is True, destroy any window items.""" + pass + + def DeleteWindows(self): + """Destroy windows associated with this sizer.""" + pass + + def Destroy(self): + """Destroy the sizer.""" + pass + + def Fit(self, window): + """Resize window to match sizer's minimal size; return size. + + This is commonly done in the constructor of the window itself.""" + pass + + def FitInside(self, window): + """Resize window virtual size to match sizer's minimal size. + + This will not alter the on screen size of the window, but may + cause the addition/removal/alteration of scrollbars required + to view the virtual area in windows which manage it.""" + pass + + def GetChildren(self): + """Return list of SizerItem instances.""" + pass + + def GetMinSize(self): + """Return the minimal size of the sizer. + + This is either the combined minimal size of all the children + and their borders or the minimal size set by SetMinSize, + whichever is larger.""" + pass + + def GetMinSizeTuple(self): + """Return the minimal size of the sizer as a tuple. + + This is either the combined minimal size of all the children + and their borders or the minimal size set by SetMinSize, + whichever is larger.""" + pass + + def GetPosition(self): + """Return the current position of the sizer.""" + pass + + def GetPositionTuple(self): + """Return the current position of the sizer as a tuple.""" + pass + + def GetSize(self): + """Return the current size of the sizer.""" + pass + + def GetSizeTuple(self): + """Return the current size of the sizer as a tuple.""" + pass + + def Hide(self, item): + """Hide item (sizer or window). To make a sizer item + disappear on-screen, use Hide() followed by Layout().""" + pass + + def Insert(self, before, item, proportion=0, flag=0, border=0, + userData=wx.NULL): + """Same as Add, but inserts item into list of items (windows, + subsizers or spacers) owned by this sizer. + + Call Layout() to update the layout on-screen after inserting.""" + pass + + def IsShown(self, item): + """Return True if item (sizer or window) is shown.""" + pass + + def Layout(self): + """Force layout of children anew. + + Use after adding or removing a child (window, other sizer, or + spacer) from the sizer while keeping the current dimension.""" + pass + + def Prepend(self, item, proportion=0, flag=0, border=0, + userData=wx.NULL): + """Same as Add, but prepends item to beginning of list of + items (windows, subsizers or spacers) owned by this sizer. + + Call Layout() to update the layout on-screen after prepending.""" + pass + + def Remove(self, item): + """Remove item from the sizer. + + item - sizer, window, or index of item in the sizer, typically + 0 for the first item. + + Does not cause any layout or resizing to take place, and does + not delete the child itself. Call Layout() to update the + layout on-screen after removing child. + + Return True if child found and removed, False otherwise.""" + pass + + def SetDimension(self, x, y, width, height): + """Force sizer to take the given dimension and thus force + items owned by sizer to resize themselves according to the + rules defined by the parameter in the Add and Prepend methods.""" + pass + + def SetItemMinSize(self, item, width, height): + """Set minimal size of item. + + item - sizer, window, or index of item in the sizer, typically + 0 for the first item. + + The item will be found recursively in the sizer's descendants. + Enables application to set size of item after initialization.""" + pass + + def SetMinSize(self, size): + """Set minimal size. + + Normally, sizer will calculate minimal size based on how much + space its children need. After calling this method, + GetMinSize will return the minimal size as requested by its + children or the minimal size set here, whichever is larger.""" + pass + + def SetSizeHints(self, window): + """Set (and Fit) minimal size of window to match sizer's + minimal size. Commonly called in the window's init.""" + pass + + def SetVirtualSizeHints(self, window): + """Set minimal size of window virtual area to match sizer's + minimal size. For windows with managed scrollbars this will + set them appropriately.""" + pass + + def Show(self, item, show=True): + """Show or hide item (sizer or window). To make item + disappear or reappear on-screen, use Show() followed by + Layout().""" + pass + + def ShowItems(self, show): + """Recursively call Show() on all sizer items.""" + pass + + +class PySizer(Sizer): + """If you wish to create a custom sizer class you should derive + the class from PySizer in order to get Python-aware capabilities + for the various virtual methods.""" + + def __init__(self): + """Create a PySizer instance. Override in subclass.""" + pass + + +class BoxSizer(Sizer): + """A box sizer is used to lay out a rather simple geometry, + typically a row or column or several hierarchies of either.""" + + def __init__(self, orient=wx.HORIZONTAL): + """Create BoxSizer instance. + + orient is either wx.VERTICAL or wx.HORIZONTAL""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def GetOrientation(self): + """Return orientation: wx.VERTICAL or wx.HORIZONTAL.""" + pass + + def RecalcSizes(self): + """Recalculate sizes, then set the size of its children + (calling SetSize if child is a window). Do not call directly.""" + pass + + def SetOrientation(self, orient): + """Set orientation to either wx.VERTICAL or wx.HORIZONTAL.""" + pass + + +class StaticBoxSizer(BoxSizer): + """Like BoxSizer, but adds a static box around the sizer. Note + that the static box has to be created separately.""" + + def __init__(self, box, orient=wx.HORIZONTAL): + """Create StaticBoxSizer instance. + + box - instance of wx.StaticBox + + orient - either wx.VERTICAL or wx.HORIZONTAL""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def GetStaticBox(self): + """Return the static box associated with the sizer.""" + pass + + def RecalcSizes(self): + """Recalculate sizes, then set the size of its children + (calling SetSize if child is a window). Do not call directly.""" + pass + + +class GridSizer(Sizer): + """A grid sizer lays out its children in a two-dimensional table + where all cells have the same size: the width of each cell is the + width of the widest child, the height of each cell is the height + of the tallest child. See also the FlexGridSizer.""" + + def __init__(self, rows=1, cols=0, vgap=0, hgap=0): + """Create a GridSizer instance. + + rows and cols - the number of rows and columns in the grid; if + either is zero, it will be calculated as the number of + children in the sizer, allowing the sizer grow dynamically. + + vgap and hgap - extra space between all cells, in pixels.""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def GetCols(self): + """Return the number of columns in the grid.""" + pass + + def GetHGap(self): + """Return the horizontal gap (in pixels) between cells.""" + pass + + def GetRows(self): + """Return the number of rows in the grid.""" + pass + + def GetVGap(self): + """Return the vertical gap (in pixels) between cells.""" + pass + + def RecalcSizes(self): + """Recalculate sizes, then set the size of its children + (calling SetSize if child is a window). Do not call directly.""" + pass + + def SetCols(self, cols): + """Set the number of columns in the grid.""" + pass + + def SetHGap(self, gap): + """Set the horizontal gap (in pixels) between cells.""" + pass + + def SetRows(self, rows): + """Sets the number of rows in the grid.""" + pass + + def SetVGap(self, gap): + """Set the vertical gap (in pixels) between cells.""" + pass + + +class FlexGridSizer(GridSizer): + """A flex grid sizer lays out its children in a two-dimensional + table where all cells in one row have the same height and all + cells in one column have the same width, but all cells are not + necessarily the same height and width, as in the GridSizer.""" + + def __init__(self, rows=1, cols=0, vgap=0, hgap=0): + """Create a GridSizer instance. + + rows and cols - the number of rows and columns in the grid; if + either is zero, it will be calculated as the number of + children in the sizer, allowing the sizer grow dynamically. + + vgap and hgap - extra space between all cells, in pixels.""" + pass + + def AddGrowableCol(self, idx): + """Specify that column idx (starting from zero) should expand + if there is extra space available to the sizer.""" + pass + + def AddGrowableRow(self, idx): + """Specify that row idx (starting from zero) should expand if + there is extra space available to the sizer.""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def RecalcSizes(self): + """Recalculate sizes, then set the size of its children + (calling SetSize if child is a window). Do not call directly.""" + pass + + def RemoveGrowableCol(self, idx): + """Specify that column idx is no longer growable.""" + pass + + def RemoveGrowableRow(self, idx): + """Specify that row idx is no longer growable.""" + pass + + +class NotebookSizer(Sizer): + """NotebookSizer works with a notebook to determine the size of + the biggest page and report an adjusted minimal size to a more + toplevel sizer. Do not add children to a NotebookSizer.""" + + def __init__(self, nb): + """Create a NotebookSizer instance for notebook.""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def GetNotebook(self): + """Return the notebook associated with the sizer.""" + pass + + def RecalcSizes(self): + """Recalculate size. Do not call directly.""" + pass + + +class SizerItem(Object): + """SizerItem class. Wrapper for items managed by a sizer.""" + + def __init__(self, this): + """Create a SizerItem instance. You don't normally create one + directly.""" + pass + + def CalcMin(self): + """Calculate minimum size. Do not call directly.""" + pass + + def DeleteWindows(self): + """Recursively destroy windows associated with this SizerItem.""" + pass + + def GetBorder(self): + """Return border width.""" + pass + + def GetFlag(self): + """Return flag value.""" + pass + + def GetOption(self): + """Return option value.""" + pass + + def GetPosition(self): + """Return wx.Point instance representing position relative to + the client area.""" + pass + + def GetRatio(self): + """Return a floating point aspect ratio (width/height). If + wx.SHAPED flag is used item will maintain ratio when resized.""" + pass + + def GetSize(self): + """Return wx.Size instance with size.""" + pass + + def GetSizer(self): + """If IsSizer() return the sizer; otherwise return None.""" + pass + + def GetUserData(self): + """Return a wx.PyUserData object.""" + pass + + def GetWindow(self): + """If IsWindow() return the window; otherwise return None.""" + pass + + def IsShown(self): + """Return True if item is shown.""" + pass + + def IsSizer(self): + """Return True if SizerItem represents a sizer.""" + pass + + def IsSpacer(self): + """Return True if SizerItem represents a spacer.""" + pass + + def IsWindow(self): + """Return True if SizerItem represents a window.""" + pass + + def SetBorder(self, border): + """Set border width for item.""" + pass + + def SetDimension(self, pos, size): + """Set position and size for item.""" + pass + + def SetFlag(self, flag): + """Set flag for item.""" + pass + + def SetInitSize(self, x, y): + """Set initial size of item.""" + pass + + def SetOption(self, option): + """Set option for item.""" + pass + + def SetRatio(self, ratio): + """Set a floating point aspect ratio (width/height). If + wx.SHAPED flag is used item will maintain ratio when resized.""" + pass + + def SetRatioSize(self, size): + """Set a floating point aspect ratio (width/height). If + wx.SHAPED flag is used item will maintain ratio when resized.""" + pass + + def SetRatioWH(self, width, height): + """Set a floating point aspect ratio (width/height). If + wx.SHAPED flag is used item will maintain ratio when resized.""" + pass + + def SetSizer(self, sizer): + """Set sizer associated with SizerItem.""" + pass + + def SetWindow(self, window): + """Set window associated with SizerItem.""" + pass + + def Show(self, show): + """Is show is True, show item, otherwise hide item.""" + pass