wxPython/wx/py/wxd/Frames.py

   1 """Decorator classes for documentation and shell scripting.
   2 """
   3
   4 __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
   5 __cvsid__ = "$Id$"
   6 __revision__ = "$Revision$"[11:-2]
   7
   8
   9 # These are not the real wxPython classes. These are Python versions
  10 # for documentation purposes. They are also used to apply docstrings
  11 # to the real wxPython classes, which are SWIG-generated wrappers for
  12 # C-language classes.
  13
  14
  15 from Base import Object
  16 import Parameters as wx
  17 from Window import TopLevelWindow, Window
  18
  19
  20 class Frame(TopLevelWindow):
  21     """A frame is a window whose size and position can (usually) be
  22     changed by the user. It usually has thick borders and a title bar,
  23     and can optionally contain a menu bar, toolbar and status bar. A
  24     frame can contain any window that is not a frame or dialog.
  25
  26     A frame that has a status bar and toolbar created via the
  27     CreateStatusBar/CreateToolBar functions manages these windows, and
  28     adjusts the value returned by GetClientSize to reflect the
  29     remaining size available to application windows.
  30
  31     An application should normally define a CloseEvent handler for the
  32     frame to respond to system close events, for example so that
  33     related data and subwindows can be cleaned up."""
  34
  35     def __init__(self, parent, id, title, pos=wx.DefaultPosition,
  36                  size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE,
  37                  name=wx.PyFrameNameStr):
  38         """Create a Frame instance.
  39
  40         parent - The window parent.  This may be None.  If it is not
  41         None, the frame will always be displayed on top of the parent
  42         window on Windows.
  43
  44         id - The window identifier. It may take a value of -1 to
  45         indicate a default value.
  46
  47         title - The caption to be displayed on the frame's title bar.
  48
  49         pos - The window position. A value of (-1, -1) indicates a
  50         default position, chosen by either the windowing system or
  51         wxWindows, depending on platform.
  52
  53         size - The window size. A value of (-1, -1) indicates a
  54         default size, chosen by either the windowing system or
  55         wxWindows, depending on platform.
  56
  57         style - The window style.
  58
  59         name - The name of the window. This parameter is used to
  60         associate a name with the item, allowing the application user
  61         to set Motif resource values for individual windows."""
  62         pass
  63
  64     def Create(self, parent, id, title, pos=wx.DefaultPosition,
  65                size=wx.DefaultSize, style=wx.DEFAULT_FRAME_STYLE,
  66                name=wx.PyFrameNameStr):
  67         """Create a Frame instance."""
  68         pass
  69
  70     def Command(self, id):
  71         """Simulate a menu command; id is a menu item identifier."""
  72         pass
  73
  74     def CreateStatusBar(self, number=1, style=wx.ST_SIZEGRIP, id=-1,
  75                         name=wx.PyStatusLineNameStr):
  76         """Create a status bar at the bottom of frame.
  77
  78         number - The number of fields to create. Specify a value
  79         greater than 1 to create a multi-field status bar.
  80
  81         style - The status bar style. See wx.StatusBar for a list of
  82         valid styles.
  83
  84         id - The status bar window identifier. If -1, an identifier
  85         will be chosen by wxWindows.
  86
  87         name - The status bar window name.
  88
  89         The width of the status bar is the whole width of the frame
  90         (adjusted automatically when resizing), and the height and
  91         text size are chosen by the host windowing system.
  92
  93         By default, the status bar is an instance of wx.StatusBar."""
  94         pass
  95
  96     def CreateToolBar(self, style=wx.NO_BORDER | wx.TB_HORIZONTAL,
  97                       id=-1, name=wx.PyToolBarNameStr):
  98         """Create a toolbar at the top or left of frame.
  99
 100         style - The toolbar style. See wxToolBar for a list of valid
 101         styles.
 102
 103         id - The toolbar window identifier. If -1, an identifier will
 104         be chosen by wxWindows.
 105
 106         name - The toolbar window name.
 107
 108         By default, the toolbar is an instance of wx.ToolBar (which is
 109         defined to be a suitable toolbar class on each platform, such
 110         as wx.ToolBar95).
 111
 112         When a toolbar has been created with this function, or made
 113         known to the frame with wx.Frame.SetToolBar, the frame will
 114         manage the toolbar position and adjust the return value from
 115         wx.Window.GetClientSize to reflect the available space for
 116         application windows."""
 117         pass
 118
 119     def DoGiveHelp(self, text, show):
 120         """Show help text (typically in the statusbar).
 121
 122         show is False if you are hiding the help, True otherwise.
 123
 124         Meant to be overridden if a derived frame wants to do
 125         something else with help text from menus and etc.  The default
 126         implementation simply calls Frame.SetStatusText."""
 127         pass
 128
 129     def GetClientAreaOrigin(self):
 130         """Return origin of frame client area (in client coordinates).
 131
 132         It may be different from (0, 0) if the frame has a toolbar."""
 133         pass
 134
 135     def GetMenuBar(self):
 136         """Return menubar currently associated with frame (if any)."""
 137         pass
 138
 139     def GetStatusBar(self):
 140         """Return status bar currently associated with frame (if any)."""
 141         pass
 142
 143     def GetStatusBarPane(self):
 144         """Return status bar pane used to display menu/toolbar help."""
 145         pass
 146
 147     def GetToolBar(self):
 148         """Return toolbar currently associated with frame (if any)."""
 149         pass
 150
 151     def PopStatusText(self, number=0):
 152         """Redraw status bar with previous status text.
 153
 154         number - The status field (starting from zero)."""
 155         pass
 156
 157     def ProcessCommand(self, id):
 158         """Process menu command; return True if processed.
 159
 160         id is the menu command identifier."""
 161         pass
 162
 163     def PushStatusText(self, text, number=0):
 164         """Set status bar text and redraw status bar, remembering
 165         previous text.
 166
 167         text - The text for the status field.
 168
 169         number - The status field (starting from zero).
 170
 171         Use an empty string to clear the status bar."""
 172         pass
 173
 174     def SendSizeEvent(self):
 175         """Send a dummy size event to the frame forcing it to
 176         reevaluate its children positions. It is sometimes useful to
 177         call this function after adding or deleting a children after
 178         the frame creation or if a child size changes.
 179
 180         Note that if the frame is using either sizers or constraints
 181         for the children layout, it is enough to call Frame.Layout()
 182         directly and this function should not be used in this case."""
 183         pass
 184
 185     def SetMenuBar(self, menubar):
 186         """Show the menu bar in the frame.
 187
 188         menuBar - The menu bar to associate with the frame.
 189
 190         If the frame is destroyed, the menu bar and its menus will be
 191         destroyed also, so do not delete the menu bar explicitly
 192         (except by resetting the frame's menu bar to another frame or
 193         NULL).
 194
 195         Under Windows, a call to Frame.OnSize is generated, so be sure
 196         to initialize data members properly before calling SetMenuBar.
 197
 198         Note that it is not possible to call this function twice for
 199         the same frame object."""
 200         pass
 201
 202     def SetStatusBar(self, statBar):
 203         """Associate a status bar with the frame."""
 204         pass
 205
 206     def SetStatusBarPane(self, n):
 207         """Set the status bar pane used to display menu and toolbar
 208         help.  Using -1 disables help display."""
 209         pass
 210
 211     def SetStatusText(self, text, number=0):
 212         """Set status bar text and redraw status bar.
 213
 214         text - The text for the status field.
 215
 216         number - The status field (starting from zero).
 217
 218         Use an empty string to clear the status bar."""
 219         pass
 220
 221     def SetStatusWidths(self, choices):
 222         """Sets the widths of the fields in the status bar.
 223
 224         choices - a Python list of integers, each of which is a status
 225         field width in pixels. A value of -1 indicates that the field
 226         is variable width; at least one field must be -1.
 227
 228         The widths of the variable fields are calculated from the
 229         total width of all fields, minus the sum of widths of the
 230         non-variable fields, divided by the number of variable fields."""
 231         pass
 232
 233     def SetToolBar(self, toolbar):
 234         """Associate a toolbar with the frame."""
 235         pass
 236
 237
 238 class LayoutAlgorithm(Object):
 239     """LayoutAlgorithm implements layout of subwindows in MDI or SDI
 240     frames.  It sends a wx.CalculateLayoutEvent event to children of
 241     the frame, asking them for information about their size.  For MDI
 242     parent frames, the algorithm allocates the remaining space to the
 243     MDI client window (which contains the MDI child frames).  For SDI
 244     (normal) frames, a 'main' window is specified as taking up the
 245     remaining space.
 246
 247     Because the event system is used, this technique can be applied to
 248     any windows, which are not necessarily 'aware' of the layout
 249     classes.  However, you may wish to use wx.SashLayoutWindow for
 250     your subwindows since this class provides handlers for the
 251     required events, and accessors to specify the desired size of the
 252     window.  The sash behaviour in the base class can be used,
 253     optionally, to make the windows user-resizable.
 254
 255     LayoutAlgorithm is typically used in IDE (integrated development
 256     environment) applications, where there are several resizable
 257     windows in addition to the MDI client window, or other primary
 258     editing window.  Resizable windows might include toolbars, a
 259     project window, and a window for displaying error and warning
 260     messages.
 261
 262     When a window receives an OnCalculateLayout event, it should call
 263     SetRect in the given event object, to be the old supplied
 264     rectangle minus whatever space the window takes up.  It should
 265     also set its own size accordingly.
 266     SashLayoutWindow.OnCalculateLayout generates an OnQueryLayoutInfo
 267     event which it sends to itself to determine the orientation,
 268     alignment and size of the window, which it gets from internal
 269     member variables set by the application.
 270
 271     The algorithm works by starting off with a rectangle equal to the
 272     whole frame client area.  It iterates through the frame children,
 273     generating OnCalculateLayout events which subtract the window size
 274     and return the remaining rectangle for the next window to process.
 275     It is assumed (by SashLayoutWindow.OnCalculateLayout) that a
 276     window stretches the full dimension of the frame client, according
 277     to the orientation it specifies.  For example, a horizontal window
 278     will stretch the full width of the remaining portion of the frame
 279     client area.  In the other orientation, the window will be fixed
 280     to whatever size was specified by OnQueryLayoutInfo.  An alignment
 281     setting will make the window 'stick' to the left, top, right or
 282     bottom of the remaining client area.  This scheme implies that
 283     order of window creation is important.  Say you wish to have an
 284     extra toolbar at the top of the frame, a project window to the
 285     left of the MDI client window, and an output window above the
 286     status bar.  You should therefore create the windows in this
 287     order: toolbar, output window, project window.  This ensures that
 288     the toolbar and output window take up space at the top and bottom,
 289     and then the remaining height in-between is used for the project
 290     window.
 291
 292     LayoutAlgorithm is quite independent of the way in which
 293     OnCalculateLayout chooses to interpret a window's size and
 294     alignment.  Therefore you could implement a different window class
 295     with a new OnCalculateLayout event handler, that has a more
 296     sophisticated way of laying out the windows.  It might allow
 297     specification of whether stretching occurs in the specified
 298     orientation, for example, rather than always assuming
 299     stretching. (This could, and probably should, be added to the
 300     existing implementation).
 301
 302     The algorithm object does not respond to events, but itself
 303     generates the following events in order to calculate window sizes:
 304     EVT_QUERY_LAYOUT_INFO(func), EVT_CALCULATE_LAYOUT(func)."""
 305
 306     def __init__(self):
 307         """Create a LayoutAlgorithm instance."""
 308         pass
 309
 310     def LayoutFrame(self, frame, mainWindow=wx.NULL):
 311         """Lay out the children of a normal frame.
 312
 313         mainWindow is set to occupy the remaining space.  This
 314         function simply calls LayoutWindow()."""
 315         pass
 316
 317     def LayoutMDIFrame(self, frame, rect=wx.NULL):
 318         """Lay out the children of an MDI parent frame.
 319
 320         If rect is non-NULL, the given rectangle will be used as a
 321         starting point instead of the frame's client area.
 322
 323         The MDI client window is set to occupy the remaining space."""
 324         pass
 325
 326     def LayoutWindow(self, parent, mainWindow=wx.NULL):
 327         """Lay out the children of a normal frame or other window.
 328
 329         mainWindow is set to occupy the remaining space.  If this is
 330         not specified, then the last window that responds to a
 331         calculate layout event in query mode will get the remaining
 332         space (that is, a non-query OnCalculateLayout event will not
 333         be sent to this window and the window will be set to the
 334         remaining size)."""
 335         pass
 336
 337
 338 class MDIChildFrame(Frame):
 339     """"""
 340
 341     def __init__(self):
 342         """"""
 343         pass
 344
 345     def Create(self):
 346         """"""
 347         pass
 348
 349     def Activate(self):
 350         """"""
 351         pass
 352
 353     def Maximize(self):
 354         """"""
 355         pass
 356
 357     def Restore(self):
 358         """"""
 359         pass
 360
 361
 362 class MDIClientWindow(Window):
 363     """"""
 364
 365     def __init__(self):
 366         """"""
 367         pass
 368
 369     def Create(self):
 370         """"""
 371         pass
 372
 373
 374 class MDIParentFrame(Frame):
 375     """"""
 376
 377     def __init__(self):
 378         """"""
 379         pass
 380
 381     def Create(self):
 382         """"""
 383         pass
 384
 385     def ActivateNext(self):
 386         """"""
 387         pass
 388
 389     def ActivatePrevious(self):
 390         """"""
 391         pass
 392
 393     def ArrangeIcons(self):
 394         """"""
 395         pass
 396
 397     def Cascade(self):
 398         """"""
 399         pass
 400
 401     def GetActiveChild(self):
 402         """"""
 403         pass
 404
 405     def GetClientWindow(self):
 406         """"""
 407         pass
 408
 409     def GetToolBar(self):
 410         """"""
 411         pass
 412
 413     def Tile(self):
 414         """"""
 415         pass
 416
 417
 418 class MiniFrame(Frame):
 419     """"""
 420
 421     def __init__(self):
 422         """"""
 423         pass
 424
 425     def Create(self):
 426         """"""
 427         pass
 428
 429
 430 class SplashScreen(Frame):
 431     """"""
 432
 433     def __init__(self):
 434         """"""
 435         pass
 436
 437     def GetSplashStyle(self):
 438         """"""
 439         pass
 440
 441     def GetSplashWindow(self):
 442         """"""
 443         pass
 444
 445     def GetTimeout(self):
 446         """"""
 447         pass
 448
 449
 450 class SplashScreenWindow(Window):
 451     """"""
 452
 453     def __init__(self):
 454         """"""
 455         pass
 456
 457     def GetBitmap(self):
 458         """"""
 459         pass
 460
 461     def SetBitmap(self):
 462         """"""
 463         pass
 464
 465
 466 class StatusBar(Window):
 467     """"""
 468
 469     def __init__(self):
 470         """"""
 471         pass
 472
 473     def Create(self):
 474         """"""
 475         pass
 476
 477     def GetBorderX(self):
 478         """"""
 479         pass
 480
 481     def GetBorderY(self):
 482         """"""
 483         pass
 484
 485     def GetFieldRect(self):
 486         """"""
 487         pass
 488
 489     def GetFieldsCount(self):
 490         """"""
 491         pass
 492
 493     def GetStatusText(self):
 494         """"""
 495         pass
 496
 497     def PopStatusText(self):
 498         """"""
 499         pass
 500
 501     def PushStatusText(self):
 502         """"""
 503         pass
 504
 505     def SetFieldsCount(self):
 506         """"""
 507         pass
 508
 509     def SetMinHeight(self):
 510         """"""
 511         pass
 512
 513     def SetStatusText(self):
 514         """"""
 515         pass
 516
 517     def SetStatusWidths(self):
 518         """"""
 519         pass