interface/wx/frame.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        frame.h
   3 // Purpose:     interface of wxFrame
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFrame
  11
  12     A frame is a window whose size and position can (usually) be changed by the user.
  13
  14     It usually has thick borders and a title bar, and can optionally contain a
  15     menu bar, toolbar and status bar. A frame can contain any window that is not
  16     a frame or dialog.
  17
  18     A frame that has a status bar and toolbar, created via the CreateStatusBar() and
  19     CreateToolBar() functions, manages these windows and adjusts the value returned
  20     by GetClientSize() to reflect the remaining size available to application windows.
  21
  22     @remarks An application should normally define an wxCloseEvent handler for the
  23              frame to respond to system close events, for example so that related
  24              data and subwindows can be cleaned up.
  25
  26
  27     @section frame_defaultevent Default event processing
  28
  29     wxFrame processes the following events:
  30
  31     @li @c wxEVT_SIZE: if the frame has exactly one child window, not counting the
  32         status and toolbar, this child is resized to take the entire frame client area.
  33         If two or more windows are present, they should be laid out explicitly either
  34         by manually handling @c wxEVT_SIZE or using sizers;
  35     @li @c wxEVT_MENU_HIGHLIGHT: the default implementation displays the help string
  36         associated with the selected item in the first pane of the status bar, if there is one.
  37
  38
  39     @beginStyleTable
  40     @style{wxDEFAULT_FRAME_STYLE}
  41            Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxRESIZE_BORDER |
  42            wxSYSTEM_MENU |  wxCAPTION |  wxCLOSE_BOX |  wxCLIP_CHILDREN.
  43     @style{wxICONIZE}
  44            Display the frame iconized (minimized). Windows only.
  45     @style{wxCAPTION}
  46            Puts a caption on the frame. Notice that this flag is required by
  47            wxMINIMIZE_BOX, wxMAXIMIZE_BOX and wxCLOSE_BOX on most systems as
  48            the corresponding buttons cannot be shown if the window has no title
  49            bar at all. I.e. if wxCAPTION is not specified those styles would be
  50            simply ignored.
  51     @style{wxMINIMIZE}
  52            Identical to wxICONIZE. Windows only.
  53     @style{wxMINIMIZE_BOX}
  54            Displays a minimize box on the frame.
  55     @style{wxMAXIMIZE}
  56            Displays the frame maximized. Windows and GTK+ only.
  57     @style{wxMAXIMIZE_BOX}
  58            Displays a maximize box on the frame. Notice that under wxGTK
  59            wxRESIZE_BORDER must be used as well or this style is ignored.
  60     @style{wxCLOSE_BOX}
  61            Displays a close box on the frame.
  62     @style{wxSTAY_ON_TOP}
  63            Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT.
  64     @style{wxSYSTEM_MENU}
  65            Displays a system menu containing the list of various windows
  66            commands in the window title bar. Unlike wxMINIMIZE_BOX,
  67            wxMAXIMIZE_BOX and wxCLOSE_BOX styles this style can be used without
  68            wxCAPTION, at least under Windows, and makes the system menu
  69            available without showing it on screen in this case. However it is
  70            recommended to only use it together with wxCAPTION for consistent
  71            behaviour under all platforms.
  72     @style{wxRESIZE_BORDER}
  73            Displays a resizeable border around the window.
  74     @style{wxFRAME_TOOL_WINDOW}
  75            Causes a frame with a small title bar to be created; the frame does
  76            not appear in the taskbar under Windows or GTK+.
  77     @style{wxFRAME_NO_TASKBAR}
  78            Creates an otherwise normal frame but it does not appear in the
  79            taskbar under Windows or GTK+ (note that it will minimize to the
  80            desktop window under Windows which may seem strange to the users
  81            and thus it might be better to use this style only without
  82            wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if the
  83            window manager supports _NET_WM_STATE_SKIP_TASKBAR hint.
  84     @style{wxFRAME_FLOAT_ON_PARENT}
  85            The frame will always be on top of its parent (unlike wxSTAY_ON_TOP).
  86            A frame created with this style must have a non-@NULL parent.
  87     @style{wxFRAME_SHAPED}
  88            Windows with this style are allowed to have their shape changed
  89            with the SetShape() method.
  90     @endStyleTable
  91
  92     The default frame style is for normal, resizeable frames.
  93     To create a frame which can not be resized by user, you may use the following
  94     combination of styles:
  95
  96     @code
  97         wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxMAXIMIZE_BOX)
  98     @endcode
  99
 100     See also the @ref overview_windowstyles.
 101
 102     @beginExtraStyleTable
 103     @style{wxFRAME_EX_CONTEXTHELP}
 104            Under Windows, puts a query button on the caption. When pressed,
 105            Windows will go into a context-sensitive help mode and wxWidgets
 106            will send a wxEVT_HELP event if the user clicked on an application
 107            window. Note that this is an extended style and must be set by
 108            calling SetExtraStyle before Create is called (two-step
 109            construction). You cannot use this style together with
 110            wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use
 111            wxDEFAULT_FRAME_STYLE  ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the
 112            frames having this style (the dialogs don't have a minimize or a
 113            maximize box by default)
 114     @style{wxFRAME_EX_METAL}
 115            On Mac OS X, frames with this style will be shown with a metallic
 116            look. This is an extra style.
 117     @endExtraStyleTable
 118
 119     @beginEventEmissionTable
 120     @event{EVT_CLOSE(func)}
 121         The frame is being closed by the user or programmatically (see wxWindow::Close).
 122         The user may generate this event clicking the close button
 123         (typically the 'X' on the top-right of the title bar) if it's present
 124         (see the @c wxCLOSE_BOX style). See wxCloseEvent.
 125     @event{EVT_ICONIZE(func)}
 126         Process a @c wxEVT_ICONIZE event. See wxIconizeEvent.
 127     @event{EVT_MENU_OPEN(func)}
 128         A menu is about to be opened. See wxMenuEvent.
 129     @event{EVT_MENU_CLOSE(func)}
 130         A menu has been just closed. See wxMenuEvent.
 131     @event{EVT_MENU_HIGHLIGHT(id, func)}
 132         The menu item with the specified id has been highlighted: used to show
 133         help prompts in the status bar by wxFrame. See wxMenuEvent.
 134     @event{EVT_MENU_HIGHLIGHT_ALL(func)}
 135         A menu item has been highlighted, i.e. the currently selected menu item has changed.
 136         See wxMenuEvent.
 137     @endEventTable
 138
 139     @library{wxcore}
 140     @category{managedwnd}
 141
 142     @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
 143 */
 144 class wxFrame : public wxTopLevelWindow
 145 {
 146 public:
 147     /**
 148         Default constructor.
 149     */
 150     wxFrame();
 151
 152     /**
 153         Constructor, creating the window.
 154
 155         @param parent
 156             The window parent. This may be @NULL. If it is non-@NULL, the frame will
 157             always be displayed on top of the parent window on Windows.
 158         @param id
 159             The window identifier. It may take a value of -1 to indicate a default value.
 160         @param title
 161             The caption to be displayed on the frame's title bar.
 162         @param pos
 163             The window position. The value wxDefaultPosition indicates a default position,
 164             chosen by either the windowing system or wxWidgets, depending on platform.
 165         @param size
 166             The window size. The value wxDefaultSize indicates a default size, chosen by
 167             either the windowing system or wxWidgets, depending on platform.
 168         @param style
 169             The window style. See wxFrame class description.
 170         @param name
 171             The name of the window. This parameter is used to associate a name with
 172             the item, allowing the application user to set Motif resource values for
 173             individual windows.
 174
 175         @remarks For Motif, MWM (the Motif Window Manager) should be running for
 176                  any window styles to work (otherwise all styles take effect).
 177
 178         @see Create()
 179     */
 180     wxFrame(wxWindow* parent, wxWindowID id,
 181             const wxString& title,
 182             const wxPoint& pos = wxDefaultPosition,
 183             const wxSize& size = wxDefaultSize,
 184             long style = wxDEFAULT_FRAME_STYLE,
 185             const wxString& name = wxFrameNameStr);
 186
 187     /**
 188         Destructor. Destroys all child windows and menu bar if present.
 189
 190         See @ref overview_windowdeletion for more info.
 191     */
 192     virtual ~wxFrame();
 193
 194     /**
 195         Centres the frame on the display.
 196
 197         @param direction
 198             The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
 199     */
 200     void Centre(int direction = wxBOTH);
 201
 202     /**
 203         Used in two-step frame construction.
 204         See wxFrame() for further details.
 205     */
 206     bool Create(wxWindow* parent, wxWindowID id, const wxString& title,
 207                 const wxPoint& pos = wxDefaultPosition,
 208                 const wxSize& size = wxDefaultSize,
 209                 long style = wxDEFAULT_FRAME_STYLE,
 210                 const wxString& name = wxFrameNameStr);
 211
 212     /**
 213         Creates a status bar at the bottom of the frame.
 214
 215         @param number
 216             The number of fields to create. Specify a
 217             value greater than 1 to create a multi-field status bar.
 218         @param style
 219             The status bar style. See wxStatusBar for a list of valid styles.
 220         @param id
 221             The status bar window identifier. If -1, an identifier will be chosen
 222             by wxWidgets.
 223         @param name
 224             The status bar window name.
 225
 226         @return A pointer to the status bar if it was created successfully, @NULL
 227                 otherwise.
 228
 229         @remarks The width of the status bar is the whole width of the frame
 230                  (adjusted automatically when resizing), and the height
 231                  and text size are chosen by the host windowing system.
 232
 233         @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
 234     */
 235     virtual wxStatusBar* CreateStatusBar(int number = 1, long style = wxSTB_DEFAULT_STYLE,
 236                                          wxWindowID id = 0,
 237                                          const wxString& name = wxStatusLineNameStr);
 238
 239     /**
 240         Creates a toolbar at the top or left of the frame.
 241
 242         @param style
 243             The toolbar style. See wxToolBar for a list of valid styles.
 244         @param id
 245             The toolbar window identifier. If -1, an identifier will be chosen
 246             by wxWidgets.
 247         @param name
 248             The toolbar window name.
 249
 250         @return A pointer to the toolbar if it was created successfully, @NULL
 251                 otherwise.
 252
 253         @remarks
 254             By default, the toolbar is an instance of wxToolBar.
 255             To use a different class, override OnCreateToolBar().
 256             When a toolbar has been created with this function, or made
 257             known to the frame with wxFrame::SetToolBar(), the frame will
 258             manage the toolbar position and adjust the return value from
 259             wxWindow::GetClientSize() to reflect the available space for
 260             application windows.
 261             Under Pocket PC, you should always use this function for creating
 262             the toolbar to be managed by the frame, so that wxWidgets can
 263             use a combined menubar and toolbar.
 264             Where you manage your own toolbars, create a wxToolBar as usual.
 265
 266         @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
 267     */
 268     virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
 269                                      wxWindowID id = wxID_ANY,
 270                                      const wxString& name = wxToolBarNameStr);
 271
 272     /**
 273         Returns the origin of the frame client area (in client coordinates).
 274         It may be different from (0, 0) if the frame has a toolbar.
 275     */
 276     virtual wxPoint GetClientAreaOrigin() const;
 277
 278     /**
 279         Returns a pointer to the menubar currently associated with the frame (if any).
 280
 281         @see SetMenuBar(), wxMenuBar, wxMenu
 282     */
 283     virtual wxMenuBar* GetMenuBar() const;
 284
 285     /**
 286         Returns a pointer to the status bar currently associated with the frame
 287         (if any).
 288
 289         @see CreateStatusBar(), wxStatusBar
 290     */
 291     virtual wxStatusBar* GetStatusBar() const;
 292
 293     /**
 294         Returns the status bar pane used to display menu and toolbar help.
 295
 296         @see SetStatusBarPane()
 297     */
 298     int GetStatusBarPane() const;
 299
 300     /**
 301         Returns a pointer to the toolbar currently associated with the frame (if any).
 302
 303         @see CreateToolBar(), wxToolBar, SetToolBar()
 304     */
 305     virtual wxToolBar* GetToolBar() const;
 306
 307     /**
 308         Virtual function called when a status bar is requested by CreateStatusBar().
 309
 310         @param number
 311             The number of fields to create.
 312         @param style
 313             The window style. See wxStatusBar for a list
 314             of valid styles.
 315         @param id
 316             The window identifier. If -1, an identifier will be chosen by
 317             wxWidgets.
 318         @param name
 319             The window name.
 320
 321         @return A status bar object.
 322
 323         @remarks An application can override this function to return a different
 324                  kind of status bar. The default implementation returns
 325                  an instance of wxStatusBar.
 326
 327         @see CreateStatusBar(), wxStatusBar.
 328     */
 329     virtual wxStatusBar* OnCreateStatusBar(int number, long style,
 330                                            wxWindowID id,
 331                                            const wxString& name);
 332
 333     /**
 334         Virtual function called when a toolbar is requested by CreateToolBar().
 335
 336         @param style
 337             The toolbar style. See wxToolBar for a list
 338             of valid styles.
 339         @param id
 340             The toolbar window identifier. If -1, an identifier will be chosen by
 341             wxWidgets.
 342         @param name
 343             The toolbar window name.
 344
 345         @return A toolbar object.
 346
 347         @remarks An application can override this function to return a different
 348                  kind of toolbar. The default implementation returns an
 349                  instance of wxToolBar.
 350
 351         @see CreateToolBar(), wxToolBar.
 352     */
 353     virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
 354                                        const wxString& name);
 355
 356     /**
 357         Simulate a menu command.
 358
 359         @param id
 360             The identifier for a menu item.
 361     */
 362     bool ProcessCommand(int id);
 363
 364     /**
 365         Tells the frame to show the given menu bar.
 366
 367         @param menuBar
 368             The menu bar to associate with the frame.
 369
 370         @remarks If the frame is destroyed, the menu bar and its menus will be
 371                  destroyed also, so do not delete the menu bar
 372                  explicitly (except by resetting the frame's menu bar to
 373                  another frame or @NULL).
 374                  Under Windows, a size event is generated, so be sure to
 375                  initialize data members properly before calling SetMenuBar().
 376                  Note that on some platforms, it is not possible to call this
 377                  function twice for the same frame object.
 378
 379         @see GetMenuBar(), wxMenuBar, wxMenu.
 380     */
 381     virtual void SetMenuBar(wxMenuBar* menuBar);
 382
 383     /**
 384         Associates a status bar with the frame.
 385
 386         If @a statusBar is @NULL, then the status bar, if present, is detached from
 387         the frame, but @e not deleted.
 388
 389         @see CreateStatusBar(), wxStatusBar, GetStatusBar()
 390     */
 391     virtual void SetStatusBar(wxStatusBar* statusBar);
 392
 393     /**
 394         Set the status bar pane used to display menu and toolbar help.
 395         Using -1 disables help display.
 396     */
 397     void SetStatusBarPane(int n);
 398
 399     /**
 400         Sets the status bar text and redraws the status bar.
 401
 402         @param text
 403             The text for the status field.
 404         @param number
 405             The status field (starting from zero).
 406
 407         @remarks Use an empty string to clear the status bar.
 408
 409         @see CreateStatusBar(), wxStatusBar
 410     */
 411     virtual void SetStatusText(const wxString& text, int number = 0);
 412
 413     /**
 414         Sets the widths of the fields in the status bar.
 415
 416         @param n
 417             The number of fields in the status bar. It must be the
 418             same used in CreateStatusBar.
 419         @param widths_field
 420             Must contain an array of n integers, each of which is a status field width
 421             in pixels. A value of -1 indicates that the field is variable width; at
 422             least one field must be -1. You should delete this array after calling
 423             SetStatusWidths().
 424
 425         @remarks The widths of the variable fields are calculated from the total
 426                  width of all fields, minus the sum of widths of the
 427                  non-variable fields, divided by the number of variable fields.
 428
 429         @beginWxPerlOnly
 430         In wxPerl this method takes the field widths as parameters.
 431         @endWxPerlOnly
 432     */
 433     virtual void SetStatusWidths(int n, const int* widths_field);
 434
 435     /**
 436         Associates a toolbar with the frame.
 437     */
 438     virtual void SetToolBar(wxToolBar* toolBar);
 439 };
 440