interface/wx/frame.h

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