wxPython/src/_aui_docstrings.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _aui_docstrings.i
   3 // Purpose:     Docstrings for the wxAUI classes.  These are in a separate
   4 //              file because we have SWIG scan the .h files directly.
   5 //
   6 // Author:      Robin Dunn
   7 //
   8 // Created:     7-July-2006
   9 // RCS-ID:      $Id$
  10 // Copyright:   (c) 2006 by Total Control Software
  11 // Licence:     wxWindows license
  12 /////////////////////////////////////////////////////////////////////////////
  13
  14
  15 DocStr(wxFrameManager,
  16 "FrameManager manages the panes associated with it for a particular
  17 `wx.Frame`, using a pane's `PaneInfo` information to determine each
  18 pane's docking and floating behavior. FrameManager uses wxWidgets'
  19 sizer mechanism to plan the layout of each frame. It uses a
  20 replaceable `DockArt` class to do all drawing, so all drawing is
  21 localized in one area, and may be customized depending on an
  22 application's specific needs.
  23 ",
  24
  25 "
  26 FrameManager works as follows: The programmer adds panes to the
  27 class, or makes changes to existing pane properties (dock position,
  28 floating state, show state, etc.). To apply these changes,
  29 FrameManager's `Update` function is called. This batch processing
  30 can be used to avoid flicker, by modifying more than one pane at a
  31 time, and then \"committing\" all of the changes at once by calling
  32 `Update`.
  33
  34 Panes can be added quite easily::
  35
  36     text1 = wx.TextCtrl(self, -1)
  37     text2 = wx.TextCtrl(self, -1)
  38     self._mgr.AddPane(text1, wx.LEFT, \"Pane Caption\")
  39     self._mgr.AddPane(text2, wx.BOTTOM, \"Pane Caption\")
  40     self._mgr.Update()
  41
  42
  43 Later on, the positions can be modified easily. The following will
  44 float an existing pane in a tool window::
  45
  46     self._mgr.GetPane(text1).Float();
  47
  48
  49 **Layers, Rows and Directions, Positions**
  50
  51 Inside wx.aui the docking layout is figured out by checking several
  52 pane parameters. Four of these are important for determining where a
  53 pane will end up:
  54
  55     * **Direction**: Each docked pane has a direction, Top, Bottom,
  56       Left, Right, or Center. This is fairly self-explanatory. The
  57       pane will be placed in the location specified by this variable.
  58
  59     * **Position**: More than one pane can be placed inside of a
  60       \"dock.\"  Imagine two panes being docked on the left side of a
  61       window. One pane can be placed over another.  In proportionally
  62       managed docks, the pane position indicates it's sequential
  63       position, starting with zero. So, in our scenario with two panes
  64       docked on the left side, the top pane in the dock would have
  65       position 0, and the second one would occupy position 1.
  66
  67     * **Row**: A row can allow for two docks to be placed next to each
  68       other. One of the most common places for this to happen is in
  69       the toolbar. Multiple toolbar rows are allowed, the first row
  70       being in row 0, and the second in row 1. Rows can also be used
  71       on vertically docked panes.
  72
  73     * **Layer**: A layer is akin to an onion. Layer 0 is the very
  74       center of the managed pane. Thus, if a pane is in layer 0, it
  75       will be closest to the center window (also sometimes known as
  76       the \"content window\"). Increasing layers \"swallow up\" all
  77       layers of a lower value. This can look very similar to multiple
  78       rows, but is different because all panes in a lower level yield
  79       to panes in higher levels. The best way to understand layers is
  80       by running the AUI sample in the wxPython demo.
  81 ");
  82
  83 DocStr(wxFrameManager::wxFrameManager,
  84 "Constructor.
  85
  86     :param managed_wnd: Specifies the `wx.Window` which should be
  87         managed.  If not set in the call to this constructor then
  88         `SetManagedWindow` should be called later.
  89
  90     :param flags: Specifies options which allow the frame management
  91         behavior to be modified.
  92 ",
  93 "
  94 Valid flags are:
  95
  96     ==============================  =================================
  97     AUI_MGR_ALLOW_FLOATING          Panes can be undocked and floated
  98     AUI_MGR_ALLOW_ACTIVE_PANE       The last pane clicked on will be
  99                                     considered the active pane and will
 100                                     be highlighted.
 101     AUI_MGR_TRANSPARENT_DRAG        If the platform supports it the panes
 102                                     will be partially transparent while
 103                                     dragging.
 104     AUI_MGR_TRANSPARENT_HINT        If the platform supports it the
 105                                     hint used to show where the pane can
 106                                     be docked will be partially transparent.
 107     AUI_MGR_TRANSPARENT_HINT_FADE   Should the transparent hint be faded
 108                                     into view.
 109     AUI_MGR_DEFAULT                 The default flags.
 110     ==============================  =================================
 111 ");
 112
 113 DocStr(wxFrameManager::UnInit,
 114 "UnInit uninitializes the framework and should be called before a
 115 managed frame is destroyed. UnInit is usually called in the managed
 116 window's destructor.
 117 ", "");
 118
 119 DocStr(wxFrameManager::SetFlags,
 120 "SetFlags is used to specify the FrameManager's behavioral
 121 settings. The flags parameter is described in the docs for `__init__`
 122 ", "");
 123
 124 DocStr(wxFrameManager::GetFlags,
 125 "GetFlags returns the current FrameManager's flags.
 126 ", "");
 127
 128 DocStr(wxFrameManager::SetManagedWindow,
 129 "SetManagedWindow is called to specify the window which is to be
 130 managed by the FrameManager.  It is normally a `wx.Frame` but it is
 131 possible to also allow docking within any container window.  This only
 132 needs to be called if the window was not given to the manager in the
 133 constructor.
 134 ", "");
 135
 136 DocStr(wxFrameManager::GetManagedWindow,
 137 "GetManagedWindow returns the window currently being managed by the
 138 FrameManager.
 139 ", "");
 140
 141 DocStr(wxFrameManager::SetArtProvider,
 142 "SetArtProvider instructs FrameManager to use the art provider
 143 specified for all drawing calls. This allows plugable look-and-feel
 144 features. The previous art provider object, if any, will be destroyed
 145 by FrameManager.
 146
 147 :note: If you wish to use a custom `DockArt` class to override drawing
 148     or metrics then you shoudl derive your class from the `PyDockArt`
 149     class, which has been instrumented for reflecting virtual calls to
 150     Python methods.
 151 ", "");
 152
 153 DocStr(wxFrameManager::GetArtProvider,
 154 "GetArtProvider returns the current art provider being used.
 155 ", "");
 156
 157
 158 DocAStr(wxFrameManager::GetAllPanes,
 159 "GetAllPanes(self) -> list",
 160 "GetAllPanes returns a list of `PaneInfo` objects for all panes managed
 161 by the frame manager.
 162 ", "");
 163
 164
 165 DocStr(wxFrameManager::InsertPane,
 166 "InsertPane is used to insert either a previously unmanaged pane window
 167 into the frame manager, or to insert a currently managed pane
 168 somewhere else. InsertPane will push all panes, rows, or docks aside
 169 and insert the window into the position specified by
 170 ``insert_location``.  Because ``insert_location`` can specify either a pane,
 171 dock row, or dock layer, the ``insert_level`` parameter is used to
 172 disambiguate this. The parameter ``insert_level`` can take a value of
 173 ``AUI_INSERT_PANE``, ``AUI_INSERT_ROW`` or ``AUI_INSERT_DOCK``.
 174 ", "");
 175
 176 DocStr(wxFrameManager::DetachPane,
 177 "DetachPane tells the FrameManager to stop managing the pane specified
 178 by window. The window, if in a floated frame, is reparented to the
 179 frame managed by FrameManager.
 180 ", "");
 181
 182 DocStr(wxFrameManager::SavePerspective,
 183 "SavePerspective saves the entire user interface layout into an encoded
 184 string, which can then be stored someplace by the application.  When a
 185 perspective is restored using `LoadPerspective`, the entire user
 186 interface will return to the state it was when the perspective was
 187 saved.
 188 ", "");
 189
 190 DocStr(wxFrameManager::LoadPerspective,
 191 "LoadPerspective loads a saved perspective. If ``update`` is ``True``,
 192 `Update` is automatically invoked, thus realizing the saved
 193 perspective on screen.
 194 ", "");
 195
 196 DocStr(wxFrameManager::Update,
 197 "Update shoudl be called called after any number of changes are made to
 198 any of the managed panes.  Update must be invoked after `AddPane` or
 199 `InsertPane` are called in order to \"realize\" or \"commit\" the
 200 changes. In addition, any number of changes may be made to `PaneInfo`
 201 structures (retrieved with `GetPane` or `GetAllPanes`), but to realize
 202 the changes, Update must be called. This construction allows pane
 203 flicker to be avoided by updating the whole layout at one time.
 204 ", "");
 205
 206
 207 //----------------------------------------------------------------------
 208
 209 DocStr(wxPaneInfo,
 210 "PaneInfo specifies all the parameters for a pane for the
 211 `FrameManager`. These parameters specify where the pane is on the
 212 screen, whether it is docked or floating, or hidden. In addition,
 213 these parameters specify the pane's docked position, floating
 214 position, preferred size, minimum size, caption text among many other
 215 parameters.
 216 ", "");
 217
 218 DocStr(wxPaneInfo::IsOk,
 219 "IsOk returns ``True`` if the PaneInfo structure is valid.
 220 ", "");
 221
 222 DocStr(wxPaneInfo::IsFixed,
 223 "IsFixed returns ``True`` if the pane cannot be resized.
 224 ", "");
 225
 226 DocStr(wxPaneInfo::IsResizable,
 227 "IsResizeable returns ``True`` if the pane can be resized.
 228 ", "");
 229
 230 DocStr(wxPaneInfo::IsShown,
 231 "IsShown returns ``True`` if the pane should be drawn on the screen.
 232 ", "");
 233
 234 DocStr(wxPaneInfo::IsFloating,
 235 "IsFloating returns ``True`` if the pane is floating.
 236 ", "");
 237
 238 DocStr(wxPaneInfo::IsDocked,
 239 "IsDocked returns ``True`` if the pane is docked.
 240 ", "");
 241
 242 DocStr(wxPaneInfo::IsToolbar,
 243 "IsToolbar returns ``True`` if the pane contains a toolbar.
 244 ", "");
 245
 246 DocStr(wxPaneInfo::IsTopDockable,
 247 "IsTopDockable returns ``True`` if the pane can be docked at the top of
 248 the managed frame.
 249 ", "");
 250
 251 DocStr(wxPaneInfo::IsBottomDockable,
 252 "IsBottomDockable returns ``True`` if the pane can be docked at the
 253 bottom of the managed frame.
 254 ", "");
 255
 256 DocStr(wxPaneInfo::IsLeftDockable,
 257 "IsLeftDockable returns ``True`` if the pane can be docked on the left
 258 of the managed frame.
 259 ", "");
 260
 261 DocStr(wxPaneInfo::IsRightDockable,
 262 "IsRightDockable returns ``True`` if the pane can be docked on the
 263 right of the managed frame.
 264 ", "");
 265
 266 DocStr(wxPaneInfo::IsFloatable,
 267 "IsFloatable returns ``True`` if the pane can be undocked and displayed
 268 as a floating window.
 269 ", "");
 270
 271 DocStr(wxPaneInfo::IsMovable,
 272 "IsMoveable returns ``True`` if the docked frame can be undocked or moved
 273 to another dock position.
 274 ", "");
 275
 276 DocStr(wxPaneInfo::HasCaption,
 277 "HasCaption returns ``True`` if the pane displays a caption.
 278 ", "");
 279
 280 DocStr(wxPaneInfo::HasGripper,
 281 "HasGripper returns ``True`` if the pane displays a gripper.
 282 ", "");
 283
 284 DocStr(wxPaneInfo::HasBorder,
 285 "HasBorder returns ``True`` if the pane displays a border.
 286 ", "");
 287
 288 DocStr(wxPaneInfo::HasCloseButton,
 289 "HasCloseButton returns ``True`` if the pane displays a button to close
 290 the pane.
 291 ", "");
 292
 293 DocStr(wxPaneInfo::HasMaximizeButton,
 294 "HasMaximizeButton returns ``True`` if the pane displays a button to
 295 maximize the pane.
 296 ", "");
 297
 298 DocStr(wxPaneInfo::HasMinimizeButton,
 299 "HasMinimizeButton returns ``True`` if the pane displays a button to
 300 minimize the pane.
 301 ", "");
 302
 303 DocStr(wxPaneInfo::HasPinButton,
 304 "HasPinButton returns ``True`` if the pane displays a button to float
 305 the pane.
 306 ", "");
 307
 308 DocStr(wxPaneInfo::Name,
 309 "Name sets the name of the pane so it can be referenced in lookup
 310 functions.
 311 ", "");
 312
 313 DocStr(wxPaneInfo::Caption,
 314 "Caption sets the caption of the pane.
 315 ", "");
 316
 317 DocStr(wxPaneInfo::Left,
 318 "Left sets the pane dock position to the left side of the frame.
 319 ", "");
 320
 321 DocStr(wxPaneInfo::Right,
 322 "Right sets the pane dock position to the right side of the frame.
 323 ", "");
 324
 325 DocStr(wxPaneInfo::Top,
 326 "Top sets the pane dock position to the top of the frame.
 327 ", "");
 328
 329 DocStr(wxPaneInfo::Bottom,
 330 "Bottom sets the pane dock position to the bottom of the frame.
 331 ", "");
 332
 333 DocStr(wxPaneInfo::Centre,
 334 "Centre sets the pane to the center position of the frame.
 335 ", "");
 336
 337 DocStr(wxPaneInfo::Center,
 338 "Center sets the pane to the center position of the frame.
 339 ", "");
 340
 341 DocStr(wxPaneInfo::Direction,
 342 "Direction determines the direction of the docked pane.
 343 ", "");
 344
 345 DocStr(wxPaneInfo::Layer,
 346 "Layer determines the layer of the docked pane.
 347 ", "");
 348
 349 DocStr(wxPaneInfo::Row,
 350 "Row determines the row of the docked pane.
 351 ", "");
 352
 353 DocStr(wxPaneInfo::Position,
 354 "Position determines the position of the docked pane.
 355 ", "");
 356
 357
 358
 359 DocStr(wxPaneInfo::MaxSize,
 360 "MaxSize sets the maximum size of the pane.
 361 ", "");
 362
 363 DocStr(wxPaneInfo::BestSize,
 364 "BestSize sets the ideal size for the pane.
 365 ", "");
 366
 367 DocStr(wxPaneInfo::MinSize,
 368 "MinSize sets the minimum size of the pane.
 369 ", "");
 370
 371 DocStr(wxPaneInfo::FloatingPosition,
 372 "FloatingPosition sets the position of the floating pane.
 373 ", "");
 374
 375 DocStr(wxPaneInfo::FloatingSize,
 376 "FloatingSize sets the size of the floating pane.
 377 ", "");
 378
 379
 380
 381 DocStr(wxPaneInfo::Fixed,
 382 "Fixed forces a pane to be fixed size so that it cannot be resized.
 383 ", "");
 384
 385 DocStr(wxPaneInfo::Resizable,
 386 "Resized allows a pane to be resized if resizable is true, and forces
 387 it to be a fixed size if resizeable is false.
 388 ", "");
 389
 390 DocStr(wxPaneInfo::Dock,
 391 "Dock indicates that a pane should be docked.
 392 ", "");
 393
 394 DocStr(wxPaneInfo::Float,
 395 "Float indicates that a pane should be floated.
 396 ", "");
 397
 398 DocStr(wxPaneInfo::Hide,
 399 "Hide indicates that a pane should be hidden.
 400 ", "");
 401
 402 DocStr(wxPaneInfo::Show,
 403 "Show indicates that a pane should be shown.
 404 ", "");
 405
 406 DocStr(wxPaneInfo::CaptionVisible,
 407 "CaptionVisible indicates that a pane caption should be visible.
 408 ", "");
 409
 410 DocStr(wxPaneInfo::PaneBorder,
 411 "PaneBorder indicates that a border should be drawn for the pane.
 412 ", "");
 413
 414 DocStr(wxPaneInfo::Gripper,
 415 "Gripper indicates that a gripper should be drawn for the pane..
 416 ", "");
 417
 418 DocStr(wxPaneInfo::CloseButton,
 419 "CloseButton indicates that a close button should be drawn for the
 420 pane.
 421 ", "");
 422
 423 DocStr(wxPaneInfo::MaximizeButton,
 424 "MaximizeButton indicates that a maximize button should be drawn for
 425 the pane.
 426 ", "");
 427
 428 DocStr(wxPaneInfo::MinimizeButton,
 429 "MinimizeButton indicates that a minimize button should be drawn for
 430 the pane.
 431 ", "");
 432
 433 DocStr(wxPaneInfo::PinButton,
 434 "PinButton indicates that a pin button should be drawn for the pane.
 435 ", "");
 436
 437 DocStr(wxPaneInfo::DestroyOnClose,
 438 "DestroyOnClose indicates whether a pane should be detroyed when it is
 439 closed.
 440 ", "");
 441
 442 DocStr(wxPaneInfo::TopDockable,
 443 "TopDockable indicates whether a pane can be docked at the top of the
 444 frame.
 445 ", "");
 446
 447 DocStr(wxPaneInfo::BottomDockable,
 448 "BottomDockable indicates whether a pane can be docked at the bottom of
 449 the frame.
 450 ", "");
 451
 452 DocStr(wxPaneInfo::LeftDockable,
 453 "LeftDockable indicates whether a pane can be docked on the left of the
 454 frame.
 455 ", "");
 456
 457 DocStr(wxPaneInfo::RightDockable,
 458 "RightDockable indicates whether a pane can be docked on the right of
 459 the frame.
 460 ", "");
 461
 462 DocStr(wxPaneInfo::Floatable,
 463 "Floatable indicates whether a frame can be floated.
 464 ", "");
 465
 466 DocStr(wxPaneInfo::Movable,
 467 "Movable indicates whether a frame can be moved.
 468 ", "");
 469
 470 DocStr(wxPaneInfo::Dockable,
 471 "Dockable indicates whether a pane can be docked at any position of the
 472 frame.
 473 ", "");
 474
 475 DocStr(wxPaneInfo::DefaultPane,
 476 "DefaultPane specifies that the pane should adopt the default pane
 477 settings.
 478 ", "");
 479
 480 DocStr(wxPaneInfo::CentrePane,
 481 "CentrePane specifies that the pane should adopt the default center
 482 pane settings.
 483 ", "");
 484
 485 DocStr(wxPaneInfo::CenterPane,
 486 "CenterPane specifies that the pane should adopt the default center
 487 pane settings.
 488 ", "");
 489
 490 DocStr(wxPaneInfo::ToolbarPane,
 491 "ToolbarPane specifies that the pane should adopt the default toolbar
 492 pane settings.
 493 ", "");
 494
 495 DocStr(wxPaneInfo::SetFlag,
 496 "SetFlag turns the property given by flag on or off with the
 497 option_state parameter.
 498 ", "");
 499
 500 DocStr(wxPaneInfo::HasFlag,
 501 "HasFlag returns ``True`` if the the property specified by flag is
 502 active for the pane.
 503 ", "");
 504
 505
 506 //---------------------------------------------------------------------------
 507
 508 DocStr(wxDockArt,
 509 "DockArt is an art provider class which does all of the drawing for
 510 `FrameManager`.  This allows the library caller to customize or replace the
 511 dock art and drawing routines by deriving a new class from `PyDockArt`. The
 512 active dock art class can be set via `FrameManager.SetArtProvider`.
 513 ", "");
 514
 515 DocStr(wxDefaultDockArt,
 516 "DefaultDockArt is the type of art class constructed by default for the
 517 `FrameManager`.","");
 518