wxPython/wx/py/wxd/Sizers.py

   1 """Decorator classes for documentation and shell scripting.
   2
   3 Sizer is the abstract base class used for laying out subwindows in a
   4 window.  You cannot use Sizer directly; instead, you will have to use
   5 one of the sizer classes derived from it.  Currently there are
   6 BoxSizer, StaticBoxSizer, NotebookSizer, GridSizer, and FlexGridSizer.
   7
   8 The layout algorithm used by sizers in wxPython is closely related to
   9 layout in other GUI toolkits, such as Java's AWT, the GTK toolkit or
  10 the Qt toolkit.  It is based upon the idea of the individual
  11 subwindows reporting their minimal required size and their ability to
  12 get stretched if the size of the parent window has changed.  This will
  13 most often mean, that the programmer does not set the original size of
  14 a dialog in the beginning, rather the dialog will assigned a sizer and
  15 this sizer will be queried about the recommended size.  The sizer in
  16 turn will query its children, which can be normal windows, empty space
  17 or other sizers, so that a hierarchy of sizers can be constructed.
  18 Note that wxSizer does not derive from wxWindow and thus do not
  19 interfere with tab ordering and requires very little resources
  20 compared to a real window on screen.
  21
  22 What makes sizers so well fitted for use in wxPython is the fact that
  23 every control reports its own minimal size and the algorithm can
  24 handle differences in font sizes or different window (dialog item)
  25 sizes on different platforms without problems.  If e.g. the standard
  26 font as well as the overall design of Motif widgets requires more
  27 space than on Windows, the initial dialog size will automatically be
  28 bigger on Motif than on Windows.
  29
  30 If you wish to create a sizer class in wxPython you should derive the
  31 class from PySizer in order to get Python-aware capabilities for the
  32 various virtual methods.
  33 """
  34
  35 __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
  36 __cvsid__ = "$Id$"
  37 __revision__ = "$Revision$"[11:-2]
  38
  39
  40 # These are not the real wxPython classes. These are Python versions
  41 # for documentation purposes. They are also used to apply docstrings
  42 # to the real wxPython classes, which are SWIG-generated wrappers for
  43 # C-language classes.
  44
  45
  46 from Base import Object
  47 import Parameters as wx
  48
  49 try:
  50     True
  51 except NameError:
  52     True = 1==1
  53     False = 1==0
  54
  55
  56 class Sizer(Object):
  57     """Sizer is the abstract base class used for laying out subwindows
  58     in a window. You shouldn't use Sizer directly; instead, you should
  59     use one of the sizer classes derived from it.
  60
  61     If you wish to create a sizer class in wxPython you should derive
  62     the class from PySizer in order to get Python-aware capabilities
  63     for the various virtual methods.
  64
  65     Placing a child sizer in a sizer allows you to create hierarchies
  66     of sizers (typically a vertical box as the top sizer and several
  67     horizontal boxes on the level beneath).
  68
  69     When you place a window in a sizer the window's initial size
  70     (either set explicitly by the user or calculated internally when
  71     using wxDefaultSize) is interpreted as the minimal and in many
  72     cases also the initial size.  This is particularly useful in
  73     connection with SetSizeHints.
  74
  75     Adding spacers to sizers gives more flexibility in the design of
  76     dialogs.  Imagine for example a horizontal box with two buttons at
  77     the bottom of a dialog: you might want to insert a space between
  78     the two buttons and make that space stretchable using the
  79     proportion flag and the result will be that the left button will
  80     be aligned with the left side of the dialog and the right button
  81     with the right side - the space in between will shrink and grow
  82     with the dialog.
  83
  84     Several methods (Add, Insert, Prepend) take the following
  85     parameters:
  86
  87     proportion - Used only by BoxSizer to indicate if a child of a
  88     sizer can change its size in the main orientation of the BoxSizer,
  89     where 0 stands for not changeable and a value of more than zero is
  90     interpreted relative to the value of other children of the same
  91     BoxSizer.  For example, you might have a horizontal BoxSizer with
  92     three children, two of which are supposed to change their size
  93     with the sizer.  Then the two stretchable windows would each get a
  94     value of 1 to make them grow and shrink equally with the sizer's
  95     horizontal dimension.
  96
  97     flag - This parameter can be used to set a number of flags which
  98     can be combined using the binary OR operator |.  Two main
  99     behaviours are defined using these flags.  One is the border
 100     around a window: the border parameter determines the border width
 101     whereas the flags given here determine where the border may be
 102     (wx.TOP, wx.BOTTOM, wx.LEFT, wx.RIGHT or wx.ALL).  The other flags
 103     determine the child window's behaviour if the size of the sizer
 104     changes.  However this is not - in contrast to the proportion flag
 105     - in the main orientation, but in the respectively other
 106     orientation.  So if you created a BoxSizer with the wx.VERTICAL
 107     option, these flags will be relevant if the sizer changes its
 108     horizontal size.  A child may get resized to completely fill out
 109     the new size (using either wx.GROW or wx.EXPAND), it may get
 110     proportionally resized (wx.SHAPED), it may get centered
 111     (wx.ALIGN_CENTER or wx.ALIGN_CENTRE) or it may get aligned to
 112     either side (wx.ALIGN_LEFT and wx.ALIGN_TOP are set to 0 and thus
 113     represent the default, wx.ALIGN_RIGHT and wx.ALIGN_BOTTOM have
 114     their obvious meaning).  With proportional resize, a child may
 115     also be centered in the main orientation using
 116     wx.ALIGN_CENTER_VERTICAL (same as wx.ALIGN_CENTRE_VERTICAL) and
 117     wx.ALIGN_CENTER_HORIZONTAL (same as wx.ALIGN_CENTRE_HORIZONTAL)
 118     flags.  Finally, you can also specify wx.ADJUST_MINSIZE flag to
 119     make the minimal size of the control dynamically adjust to the
 120     value returned by its GetAdjustedBestSize() method - this allows,
 121     for example, for correct relayouting of a static text control even
 122     if its text is changed during run-time.
 123
 124     border - Determines the border width, if the flag parameter is set
 125     to any border.  A border is not a visible element, but rather a
 126     margin of empty space surrounding the item.
 127
 128     userData - Allows an extra object to be attached to the sizer
 129     item, for use in derived classes when sizing information is more
 130     complex than the option and flag parameters will allow."""
 131
 132     def __init__(self):
 133         """Must be defined by subclasses."""
 134         pass
 135
 136     def Add(self, item, proportion=0, flag=0, border=0,
 137             userData=wx.NULL):
 138         """Add item to sizer.
 139
 140         item - window, sizer, or spacer.  Spacer is specified with a
 141         (width, height) tuple or wx.Size representing the spacer size.
 142
 143         Call Layout() to update the layout on-screen after adding."""
 144         pass
 145
 146     def Clear(self, delete_windows=False):
 147         """Remove all items from this sizer.
 148
 149         If delete_windows is True, destroy any window items."""
 150         pass
 151
 152     def DeleteWindows(self):
 153         """Destroy windows associated with this sizer."""
 154         pass
 155
 156     def Destroy(self):
 157         """Destroy the sizer."""
 158         pass
 159
 160     def Fit(self, window):
 161         """Resize window to match sizer's minimal size; return size.
 162
 163         This is commonly done in the constructor of the window itself."""
 164         pass
 165
 166     def FitInside(self, window):
 167         """Resize window virtual size to match sizer's minimal size.
 168
 169         This will not alter the on screen size of the window, but may
 170         cause the addition/removal/alteration of scrollbars required
 171         to view the virtual area in windows which manage it."""
 172         pass
 173
 174     def GetChildren(self):
 175         """Return list of SizerItem instances."""
 176         pass
 177
 178     def GetMinSize(self):
 179         """Return the minimal size of the sizer.
 180
 181         This is either the combined minimal size of all the children
 182         and their borders or the minimal size set by SetMinSize,
 183         whichever is larger."""
 184         pass
 185
 186     def GetMinSizeTuple(self):
 187         """Return the minimal size of the sizer as a tuple.
 188
 189         This is either the combined minimal size of all the children
 190         and their borders or the minimal size set by SetMinSize,
 191         whichever is larger."""
 192         pass
 193
 194     def GetPosition(self):
 195         """Return the current position of the sizer."""
 196         pass
 197
 198     def GetPositionTuple(self):
 199         """Return the current position of the sizer as a tuple."""
 200         pass
 201
 202     def GetSize(self):
 203         """Return the current size of the sizer."""
 204         pass
 205
 206     def GetSizeTuple(self):
 207         """Return the current size of the sizer as a tuple."""
 208         pass
 209
 210     def Hide(self, item):
 211         """Hide item (sizer or window).  To make a sizer item
 212         disappear on-screen, use Hide() followed by Layout()."""
 213         pass
 214
 215     def Insert(self, before, item, proportion=0, flag=0, border=0,
 216                userData=wx.NULL):
 217         """Same as Add, but inserts item into list of items (windows,
 218         subsizers or spacers) owned by this sizer.
 219
 220         Call Layout() to update the layout on-screen after inserting."""
 221         pass
 222
 223     def IsShown(self, item):
 224         """Return True if item (sizer or window) is shown."""
 225         pass
 226
 227     def Layout(self):
 228         """Force layout of children anew.
 229
 230         Use after adding or removing a child (window, other sizer, or
 231         spacer) from the sizer while keeping the current dimension."""
 232         pass
 233
 234     def Prepend(self, item, proportion=0, flag=0, border=0,
 235                 userData=wx.NULL):
 236         """Same as Add, but prepends item to beginning of list of
 237         items (windows, subsizers or spacers) owned by this sizer.
 238
 239         Call Layout() to update the layout on-screen after prepending."""
 240         pass
 241
 242     def Remove(self, item):
 243         """Remove item from the sizer.
 244
 245         item - sizer, window, or index of item in the sizer, typically
 246         0 for the first item.
 247
 248         Does not cause any layout or resizing to take place, and does
 249         not delete the child itself.  Call Layout() to update the
 250         layout on-screen after removing child.
 251
 252         Return True if child found and removed, False otherwise."""
 253         pass
 254
 255     def SetDimension(self, x, y, width, height):
 256         """Force sizer to take the given dimension and thus force
 257         items owned by sizer to resize themselves according to the
 258         rules defined by the parameter in the Add and Prepend methods."""
 259         pass
 260
 261     def SetItemMinSize(self, item, width, height):
 262         """Set minimal size of item.
 263
 264         item - sizer, window, or index of item in the sizer, typically
 265         0 for the first item.
 266
 267         The item will be found recursively in the sizer's descendants.
 268         Enables application to set size of item after initialization."""
 269         pass
 270
 271     def SetMinSize(self, size):
 272         """Set minimal size.
 273
 274         Normally, sizer will calculate minimal size based on how much
 275         space its children need.  After calling this method,
 276         GetMinSize will return the minimal size as requested by its
 277         children or the minimal size set here, whichever is larger."""
 278         pass
 279
 280     def SetSizeHints(self, window):
 281         """Set (and Fit) minimal size of window to match sizer's
 282         minimal size.  Commonly called in the window's init."""
 283         pass
 284
 285     def SetVirtualSizeHints(self, window):
 286         """Set minimal size of window virtual area to match sizer's
 287         minimal size.  For windows with managed scrollbars this will
 288         set them appropriately."""
 289         pass
 290
 291     def Show(self, item, show=True):
 292         """Show or hide item (sizer or window).  To make item
 293         disappear or reappear on-screen, use Show() followed by
 294         Layout()."""
 295         pass
 296
 297     def ShowItems(self, show):
 298         """Recursively call Show() on all sizer items."""
 299         pass
 300
 301
 302 class PySizer(Sizer):
 303     """If you wish to create a custom sizer class you should derive
 304     the class from PySizer in order to get Python-aware capabilities
 305     for the various virtual methods."""
 306
 307     def __init__(self):
 308         """Create a PySizer instance.  Override in subclass."""
 309         pass
 310
 311
 312 class BoxSizer(Sizer):
 313     """A box sizer is used to lay out a rather simple geometry,
 314     typically a row or column or several hierarchies of either."""
 315
 316     def __init__(self, orient=wx.HORIZONTAL):
 317         """Create BoxSizer instance.
 318
 319         orient is either wx.VERTICAL or wx.HORIZONTAL"""
 320         pass
 321
 322     def CalcMin(self):
 323         """Calculate minimum size.  Do not call directly."""
 324         pass
 325
 326     def GetOrientation(self):
 327         """Return orientation: wx.VERTICAL or wx.HORIZONTAL."""
 328         pass
 329
 330     def RecalcSizes(self):
 331         """Recalculate sizes, then set the size of its children
 332         (calling SetSize if child is a window).  Do not call directly."""
 333         pass
 334
 335     def SetOrientation(self, orient):
 336         """Set orientation to either wx.VERTICAL or wx.HORIZONTAL."""
 337         pass
 338
 339
 340 class StaticBoxSizer(BoxSizer):
 341     """Like BoxSizer, but adds a static box around the sizer.  Note
 342     that the static box has to be created separately."""
 343
 344     def __init__(self, box, orient=wx.HORIZONTAL):
 345         """Create StaticBoxSizer instance.
 346
 347         box - instance of wx.StaticBox
 348
 349         orient - either wx.VERTICAL or wx.HORIZONTAL"""
 350         pass
 351
 352     def CalcMin(self):
 353         """Calculate minimum size.  Do not call directly."""
 354         pass
 355
 356     def GetStaticBox(self):
 357         """Return the static box associated with the sizer."""
 358         pass
 359
 360     def RecalcSizes(self):
 361         """Recalculate sizes, then set the size of its children
 362         (calling SetSize if child is a window).  Do not call directly."""
 363         pass
 364
 365
 366 class GridSizer(Sizer):
 367     """A grid sizer lays out its children in a two-dimensional table
 368     where all cells have the same size: the width of each cell is the
 369     width of the widest child, the height of each cell is the height
 370     of the tallest child.  See also the FlexGridSizer."""
 371
 372     def __init__(self, rows=1, cols=0, vgap=0, hgap=0):
 373         """Create a GridSizer instance.
 374
 375         rows and cols - the number of rows and columns in the grid; if
 376         either is zero, it will be calculated as the number of
 377         children in the sizer, allowing the sizer grow dynamically.
 378
 379         vgap and hgap - extra space between all cells, in pixels."""
 380         pass
 381
 382     def CalcMin(self):
 383         """Calculate minimum size.  Do not call directly."""
 384         pass
 385
 386     def GetCols(self):
 387         """Return the number of columns in the grid."""
 388         pass
 389
 390     def GetHGap(self):
 391         """Return the horizontal gap (in pixels) between cells."""
 392         pass
 393
 394     def GetRows(self):
 395         """Return the number of rows in the grid."""
 396         pass
 397
 398     def GetVGap(self):
 399         """Return the vertical gap (in pixels) between cells."""
 400         pass
 401
 402     def RecalcSizes(self):
 403         """Recalculate sizes, then set the size of its children
 404         (calling SetSize if child is a window).  Do not call directly."""
 405         pass
 406
 407     def SetCols(self, cols):
 408         """Set the number of columns in the grid."""
 409         pass
 410
 411     def SetHGap(self, gap):
 412         """Set the horizontal gap (in pixels) between cells."""
 413         pass
 414
 415     def SetRows(self, rows):
 416         """Sets the number of rows in the grid."""
 417         pass
 418
 419     def SetVGap(self, gap):
 420         """Set the vertical gap (in pixels) between cells."""
 421         pass
 422
 423
 424 class FlexGridSizer(GridSizer):
 425     """A flex grid sizer lays out its children in a two-dimensional
 426     table where all cells in one row have the same height and all
 427     cells in one column have the same width, but all cells are not
 428     necessarily the same height and width, as in the GridSizer."""
 429
 430     def __init__(self, rows=1, cols=0, vgap=0, hgap=0):
 431         """Create a GridSizer instance.
 432
 433         rows and cols - the number of rows and columns in the grid; if
 434         either is zero, it will be calculated as the number of
 435         children in the sizer, allowing the sizer grow dynamically.
 436
 437         vgap and hgap - extra space between all cells, in pixels."""
 438         pass
 439
 440     def AddGrowableCol(self, idx):
 441         """Specify that column idx (starting from zero) should expand
 442         if there is extra space available to the sizer."""
 443         pass
 444
 445     def AddGrowableRow(self, idx):
 446         """Specify that row idx (starting from zero) should expand if
 447         there is extra space available to the sizer."""
 448         pass
 449
 450     def CalcMin(self):
 451         """Calculate minimum size.  Do not call directly."""
 452         pass
 453
 454     def RecalcSizes(self):
 455         """Recalculate sizes, then set the size of its children
 456         (calling SetSize if child is a window).  Do not call directly."""
 457         pass
 458
 459     def RemoveGrowableCol(self, idx):
 460         """Specify that column idx is no longer growable."""
 461         pass
 462
 463     def RemoveGrowableRow(self, idx):
 464         """Specify that row idx is no longer growable."""
 465         pass
 466
 467
 468 class NotebookSizer(Sizer):
 469     """NotebookSizer works with a notebook to determine the size of
 470     the biggest page and report an adjusted minimal size to a more
 471     toplevel sizer.  Do not add children to a NotebookSizer."""
 472
 473     def __init__(self, nb):
 474         """Create a NotebookSizer instance for notebook."""
 475         pass
 476
 477     def CalcMin(self):
 478         """Calculate minimum size.  Do not call directly."""
 479         pass
 480
 481     def GetNotebook(self):
 482         """Return the notebook associated with the sizer."""
 483         pass
 484
 485     def RecalcSizes(self):
 486         """Recalculate size.  Do not call directly."""
 487         pass
 488
 489
 490 class SizerItem(Object):
 491     """SizerItem class.  Wrapper for items managed by a sizer."""
 492
 493     def __init__(self, this):
 494         """Create a SizerItem instance.  You don't normally create one
 495         directly."""
 496         pass
 497
 498     def CalcMin(self):
 499         """Calculate minimum size.  Do not call directly."""
 500         pass
 501
 502     def DeleteWindows(self):
 503         """Recursively destroy windows associated with this SizerItem."""
 504         pass
 505
 506     def GetBorder(self):
 507         """Return border width."""
 508         pass
 509
 510     def GetFlag(self):
 511         """Return flag value."""
 512         pass
 513
 514     def GetOption(self):
 515         """Return option value."""
 516         pass
 517
 518     def GetPosition(self):
 519         """Return wx.Point instance representing position relative to
 520         the client area."""
 521         pass
 522
 523     def GetRatio(self):
 524         """Return a floating point aspect ratio (width/height).  If
 525         wx.SHAPED flag is used item will maintain ratio when resized."""
 526         pass
 527
 528     def GetSize(self):
 529         """Return wx.Size instance with size."""
 530         pass
 531
 532     def GetSizer(self):
 533         """If IsSizer() return the sizer; otherwise return None."""
 534         pass
 535
 536     def GetUserData(self):
 537         """Return a wx.PyUserData object."""
 538         pass
 539
 540     def GetWindow(self):
 541         """If IsWindow() return the window; otherwise return None."""
 542         pass
 543
 544     def IsShown(self):
 545         """Return True if item is shown."""
 546         pass
 547
 548     def IsSizer(self):
 549         """Return True if SizerItem represents a sizer."""
 550         pass
 551
 552     def IsSpacer(self):
 553         """Return True if SizerItem represents a spacer."""
 554         pass
 555
 556     def IsWindow(self):
 557         """Return True if SizerItem represents a window."""
 558         pass
 559
 560     def SetBorder(self, border):
 561         """Set border width for item."""
 562         pass
 563
 564     def SetDimension(self, pos, size):
 565         """Set position and size for item."""
 566         pass
 567
 568     def SetFlag(self, flag):
 569         """Set flag for item."""
 570         pass
 571
 572     def SetInitSize(self, x, y):
 573         """Set initial size of item."""
 574         pass
 575
 576     def SetOption(self, option):
 577         """Set option for item."""
 578         pass
 579
 580     def SetRatio(self, ratio):
 581         """Set a floating point aspect ratio (width/height).  If
 582         wx.SHAPED flag is used item will maintain ratio when resized."""
 583         pass
 584
 585     def SetRatioSize(self, size):
 586         """Set a floating point aspect ratio (width/height).  If
 587         wx.SHAPED flag is used item will maintain ratio when resized."""
 588         pass
 589
 590     def SetRatioWH(self, width, height):
 591         """Set a floating point aspect ratio (width/height).  If
 592         wx.SHAPED flag is used item will maintain ratio when resized."""
 593         pass
 594
 595     def SetSizer(self, sizer):
 596         """Set sizer associated with SizerItem."""
 597         pass
 598
 599     def SetWindow(self, window):
 600         """Set window associated with SizerItem."""
 601         pass
 602
 603     def Show(self, show):
 604         """Is show is True, show item, otherwise hide item."""
 605         pass