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