Logo Search packages:      
Sourcecode: wxwindows2.4 version File versions

Sizers.py

00001 """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 <pobrien@orbtech.com>"
__cvsid__ = "$Id: Sizers.py,v 1.1.2.1 2003/04/09 17:43:17 RD Exp $"
__revision__ = "$Revision: 1.1.2.1 $"[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


00056 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."""

00132     def __init__(self):
        """Must be defined by subclasses."""
        pass

00136     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

00146     def Clear(self, delete_windows=False):
        """Remove all items from this sizer.

        If delete_windows is True, destroy any window items."""
        pass

00152     def DeleteWindows(self):
        """Destroy windows associated with this sizer."""
        pass

00156     def Destroy(self):
        """Destroy the sizer."""
        pass

00160     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

00166     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

00174     def GetChildren(self):
        """Return list of SizerItem instances."""
        pass

00178     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

00186     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

00194     def GetPosition(self):
        """Return the current position of the sizer."""
        pass

00198     def GetPositionTuple(self):
        """Return the current position of the sizer as a tuple."""
        pass

00202     def GetSize(self):
        """Return the current size of the sizer."""
        pass

00206     def GetSizeTuple(self):
        """Return the current size of the sizer as a tuple."""
        pass

00210     def Hide(self, item):
        """Hide item (sizer or window).  To make a sizer item
        disappear on-screen, use Hide() followed by Layout()."""
        pass

00215     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

00223     def IsShown(self, item):
        """Return True if item (sizer or window) is shown."""
        pass

00227     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

00234     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

00242     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

00255     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

00261     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

00271     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

00280     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

00285     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

00291     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

00297     def ShowItems(self, show):
        """Recursively call Show() on all sizer items."""
        pass


00302 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."""

00307     def __init__(self):
        """Create a PySizer instance.  Override in subclass."""
        pass


00312 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."""

00316     def __init__(self, orient=wx.HORIZONTAL):
        """Create BoxSizer instance.

        orient is either wx.VERTICAL or wx.HORIZONTAL"""
        pass

00322     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00326     def GetOrientation(self):
        """Return orientation: wx.VERTICAL or wx.HORIZONTAL."""
        pass

00330     def RecalcSizes(self):
        """Recalculate sizes, then set the size of its children
        (calling SetSize if child is a window).  Do not call directly."""
        pass

00335     def SetOrientation(self, orient):
        """Set orientation to either wx.VERTICAL or wx.HORIZONTAL."""
        pass


00340 class StaticBoxSizer(BoxSizer):
    """Like BoxSizer, but adds a static box around the sizer.  Note
    that the static box has to be created separately."""

00344     def __init__(self, box, orient=wx.HORIZONTAL):
        """Create StaticBoxSizer instance.

        box - instance of wx.StaticBox

        orient - either wx.VERTICAL or wx.HORIZONTAL"""
        pass

00352     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00356     def GetStaticBox(self):
        """Return the static box associated with the sizer."""
        pass

00360     def RecalcSizes(self):
        """Recalculate sizes, then set the size of its children
        (calling SetSize if child is a window).  Do not call directly."""
        pass


00366 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."""

00372     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

00382     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00386     def GetCols(self):
        """Return the number of columns in the grid."""
        pass

00390     def GetHGap(self):
        """Return the horizontal gap (in pixels) between cells."""
        pass

00394     def GetRows(self):
        """Return the number of rows in the grid."""
        pass

00398     def GetVGap(self):
        """Return the vertical gap (in pixels) between cells."""
        pass

00402     def RecalcSizes(self):
        """Recalculate sizes, then set the size of its children
        (calling SetSize if child is a window).  Do not call directly."""
        pass

00407     def SetCols(self, cols):
        """Set the number of columns in the grid."""
        pass

00411     def SetHGap(self, gap):
        """Set the horizontal gap (in pixels) between cells."""
        pass

00415     def SetRows(self, rows):
        """Sets the number of rows in the grid."""
        pass

00419     def SetVGap(self, gap):
        """Set the vertical gap (in pixels) between cells."""
        pass


00424 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."""

00430     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

00440     def AddGrowableCol(self, idx):
        """Specify that column idx (starting from zero) should expand
        if there is extra space available to the sizer."""
        pass

00445     def AddGrowableRow(self, idx):
        """Specify that row idx (starting from zero) should expand if
        there is extra space available to the sizer."""
        pass

00450     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00454     def RecalcSizes(self):
        """Recalculate sizes, then set the size of its children
        (calling SetSize if child is a window).  Do not call directly."""
        pass

00459     def RemoveGrowableCol(self, idx):
        """Specify that column idx is no longer growable."""
        pass

00463     def RemoveGrowableRow(self, idx):
        """Specify that row idx is no longer growable."""
        pass


00468 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."""

00473     def __init__(self, nb):
        """Create a NotebookSizer instance for notebook."""
        pass

00477     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00481     def GetNotebook(self):
        """Return the notebook associated with the sizer."""
        pass

00485     def RecalcSizes(self):
        """Recalculate size.  Do not call directly."""
        pass


00490 class SizerItem(Object):
    """SizerItem class.  Wrapper for items managed by a sizer."""

00493     def __init__(self, this):
        """Create a SizerItem instance.  You don't normally create one
        directly."""
        pass

00498     def CalcMin(self):
        """Calculate minimum size.  Do not call directly."""
        pass

00502     def DeleteWindows(self):
        """Recursively destroy windows associated with this SizerItem."""
        pass

00506     def GetBorder(self):
        """Return border width."""
        pass

00510     def GetFlag(self):
        """Return flag value."""
        pass

00514     def GetOption(self):
        """Return option value."""
        pass

00518     def GetPosition(self):
        """Return wx.Point instance representing position relative to
        the client area."""
        pass

00523     def GetRatio(self):
        """Return a floating point aspect ratio (width/height).  If
        wx.SHAPED flag is used item will maintain ratio when resized."""
        pass

00528     def GetSize(self):
        """Return wx.Size instance with size."""
        pass

00532     def GetSizer(self):
        """If IsSizer() return the sizer; otherwise return None."""
        pass

00536     def GetUserData(self):
        """Return a wx.PyUserData object."""
        pass

00540     def GetWindow(self):
        """If IsWindow() return the window; otherwise return None."""
        pass

00544     def IsShown(self):
        """Return True if item is shown."""
        pass

00548     def IsSizer(self):
        """Return True if SizerItem represents a sizer."""
        pass

00552     def IsSpacer(self):
        """Return True if SizerItem represents a spacer."""
        pass

00556     def IsWindow(self):
        """Return True if SizerItem represents a window."""
        pass

00560     def SetBorder(self, border):
        """Set border width for item."""
        pass

00564     def SetDimension(self, pos, size):
        """Set position and size for item."""
        pass

00568     def SetFlag(self, flag):
        """Set flag for item."""
        pass

00572     def SetInitSize(self, x, y):
        """Set initial size of item."""
        pass

00576     def SetOption(self, option):
        """Set option for item."""
        pass

00580     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

00585     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

00590     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

00595     def SetSizer(self, sizer):
        """Set sizer associated with SizerItem."""
        pass

00599     def SetWindow(self, window):
        """Set window associated with SizerItem."""
        pass

00603     def Show(self, show):
        """Is show is True, show item, otherwise hide item."""
        pass

Generated by  Doxygen 1.6.0   Back to index