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 resizable 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, resizable frames.
  93     To create a frame which cannot 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 @c 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         Process a @c wxEVT_CLOSE_WINDOW event when the frame is being
 122         closed by the user or programmatically (see wxWindow::Close).
 123         The user may generate this event clicking the close button
 124         (typically the 'X' on the top-right of the title bar) if it's present
 125         (see the @c wxCLOSE_BOX style). See wxCloseEvent.
 126     @event{EVT_ICONIZE(func)}
 127         Process a @c wxEVT_ICONIZE event. See wxIconizeEvent.
 128     @event{EVT_MENU_OPEN(func)}
 129         A menu is about to be opened. See wxMenuEvent.
 130     @event{EVT_MENU_CLOSE(func)}
 131         A menu has been just closed. See wxMenuEvent.
 132     @event{EVT_MENU_HIGHLIGHT(id, func)}
 133         The menu item with the specified id has been highlighted: used to show
 134         help prompts in the status bar by wxFrame. See wxMenuEvent.
 135     @event{EVT_MENU_HIGHLIGHT_ALL(func)}
 136         A menu item has been highlighted, i.e. the currently selected menu item has changed.
 137         See wxMenuEvent.
 138     @endEventTable
 139
 140     @library{wxcore}
 141     @category{managedwnd}
 142
 143     @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
 144 */
 145 class wxFrame : public wxTopLevelWindow
 146 {
 147 public:
 148     /**
 149         Default constructor.
 150     */
 151     wxFrame();
 152
 153     /**
 154         Constructor, creating the window.
 155
 156         @param parent
 157             The window parent. This may be @NULL. If it is non-@NULL, the frame will
 158             always be displayed on top of the parent window on Windows.
 159         @param id
 160             The window identifier. It may take a value of -1 to indicate a default value.
 161         @param title
 162             The caption to be displayed on the frame's title bar.
 163         @param pos
 164             The window position. The value wxDefaultPosition indicates a default position,
 165             chosen by either the windowing system or wxWidgets, depending on platform.
 166         @param size
 167             The window size. The value wxDefaultSize indicates a default size, chosen by
 168             either the windowing system or wxWidgets, depending on platform.
 169         @param style
 170             The window style. See wxFrame class description.
 171         @param name
 172             The name of the window. This parameter is used to associate a name with
 173             the item, allowing the application user to set Motif resource values for
 174             individual windows.
 175
 176         @remarks For Motif, MWM (the Motif Window Manager) should be running for
 177                  any window styles to work (otherwise all styles take effect).
 178
 179         @see Create()
 180     */
 181     wxFrame(wxWindow* parent, wxWindowID id,
 182             const wxString& title,
 183             const wxPoint& pos = wxDefaultPosition,
 184             const wxSize& size = wxDefaultSize,
 185             long style = wxDEFAULT_FRAME_STYLE,
 186             const wxString& name = wxFrameNameStr);
 187
 188     /**
 189         Destructor. Destroys all child windows and menu bar if present.
 190
 191         See @ref overview_windowdeletion for more info.
 192     */
 193     virtual ~wxFrame();
 194
 195     /**
 196         Centres the frame on the display.
 197
 198         @param direction
 199             The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
 200     */
 201     void Centre(int direction = wxBOTH);
 202
 203     /**
 204         Used in two-step frame construction.
 205         See wxFrame() for further details.
 206     */
 207     bool Create(wxWindow* parent, wxWindowID id, const wxString& title,
 208                 const wxPoint& pos = wxDefaultPosition,
 209                 const wxSize& size = wxDefaultSize,
 210                 long style = wxDEFAULT_FRAME_STYLE,
 211                 const wxString& name = wxFrameNameStr);
 212
 213     /**
 214         Creates a status bar at the bottom of the frame.
 215
 216         @param number
 217             The number of fields to create. Specify a
 218             value greater than 1 to create a multi-field status bar.
 219         @param style
 220             The status bar style. See wxStatusBar for a list of valid styles.
 221         @param id
 222             The status bar window identifier. If -1, an identifier will be chosen
 223             by wxWidgets.
 224         @param name
 225             The status bar window name.
 226
 227         @return A pointer to the status bar if it was created successfully, @NULL
 228                 otherwise.
 229
 230         @remarks The width of the status bar is the whole width of the frame
 231                  (adjusted automatically when resizing), and the height
 232                  and text size are chosen by the host windowing system.
 233
 234         @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
 235     */
 236     virtual wxStatusBar* CreateStatusBar(int number = 1, long style = wxSTB_DEFAULT_STYLE,
 237                                          wxWindowID id = 0,
 238                                          const wxString& name = wxStatusBarNameStr);
 239
 240     /**
 241         Creates a toolbar at the top or left of the frame.
 242
 243         @param style
 244             The toolbar style. See wxToolBar for a list of valid styles.
 245         @param id
 246             The toolbar window identifier. If -1, an identifier will be chosen
 247             by wxWidgets.
 248         @param name
 249             The toolbar window name.
 250
 251         @return A pointer to the toolbar if it was created successfully, @NULL
 252                 otherwise.
 253
 254         @remarks
 255             By default, the toolbar is an instance of wxToolBar.
 256             To use a different class, override OnCreateToolBar().
 257             When a toolbar has been created with this function, or made
 258             known to the frame with wxFrame::SetToolBar(), the frame will
 259             manage the toolbar position and adjust the return value from
 260             wxWindow::GetClientSize() to reflect the available space for
 261             application windows.
 262             Under Pocket PC, you should always use this function for creating
 263             the toolbar to be managed by the frame, so that wxWidgets can
 264             use a combined menubar and toolbar.
 265             Where you manage your own toolbars, create a wxToolBar as usual.
 266
 267         @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
 268     */
 269     virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
 270                                      wxWindowID id = wxID_ANY,
 271                                      const wxString& name = wxToolBarNameStr);
 272
 273     /**
 274         Returns the origin of the frame client area (in client coordinates).
 275         It may be different from (0, 0) if the frame has a toolbar.
 276     */
 277     virtual wxPoint GetClientAreaOrigin() const;
 278
 279     /**
 280         Returns a pointer to the menubar currently associated with the frame (if any).
 281
 282         @see SetMenuBar(), wxMenuBar, wxMenu
 283     */
 284     virtual wxMenuBar* GetMenuBar() const;
 285
 286     /**
 287         Returns a pointer to the status bar currently associated with the frame
 288         (if any).
 289
 290         @see CreateStatusBar(), wxStatusBar
 291     */
 292     virtual wxStatusBar* GetStatusBar() const;
 293
 294     /**
 295         Returns the status bar pane used to display menu and toolbar help.
 296
 297         @see SetStatusBarPane()
 298     */
 299     int GetStatusBarPane() const;
 300
 301     /**
 302         Returns a pointer to the toolbar currently associated with the frame (if any).
 303
 304         @see CreateToolBar(), wxToolBar, SetToolBar()
 305     */
 306     virtual wxToolBar* GetToolBar() const;
 307
 308     /**
 309         Virtual function called when a status bar is requested by CreateStatusBar().
 310
 311         @param number
 312             The number of fields to create.
 313         @param style
 314             The window style. See wxStatusBar for a list
 315             of valid styles.
 316         @param id
 317             The window identifier. If -1, an identifier will be chosen by
 318             wxWidgets.
 319         @param name
 320             The window name.
 321
 322         @return A status bar object.
 323
 324         @remarks An application can override this function to return a different
 325                  kind of status bar. The default implementation returns
 326                  an instance of wxStatusBar.
 327
 328         @see CreateStatusBar(), wxStatusBar.
 329     */
 330     virtual wxStatusBar* OnCreateStatusBar(int number, long style,
 331                                            wxWindowID id,
 332                                            const wxString& name);
 333
 334     /**
 335         Virtual function called when a toolbar is requested by CreateToolBar().
 336
 337         @param style
 338             The toolbar style. See wxToolBar for a list
 339             of valid styles.
 340         @param id
 341             The toolbar window identifier. If -1, an identifier will be chosen by
 342             wxWidgets.
 343         @param name
 344             The toolbar window name.
 345
 346         @return A toolbar object.
 347
 348         @remarks An application can override this function to return a different
 349                  kind of toolbar. The default implementation returns an
 350                  instance of wxToolBar.
 351
 352         @see CreateToolBar(), wxToolBar.
 353     */
 354     virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
 355                                        const wxString& name);
 356
 357     /**
 358         Simulate a menu command.
 359
 360         @param id
 361             The identifier for a menu item.
 362     */
 363     bool ProcessCommand(int id);
 364
 365     /**
 366         Tells the frame to show the given menu bar.
 367
 368         @param menuBar
 369             The menu bar to associate with the frame.
 370
 371         @remarks If the frame is destroyed, the menu bar and its menus will be
 372                  destroyed also, so do not delete the menu bar
 373                  explicitly (except by resetting the frame's menu bar to
 374                  another frame or @NULL).
 375                  Under Windows, a size event is generated, so be sure to
 376                  initialize data members properly before calling SetMenuBar().
 377                  Note that on some platforms, it is not possible to call this
 378                  function twice for the same frame object.
 379
 380         @see GetMenuBar(), wxMenuBar, wxMenu.
 381     */
 382     virtual void SetMenuBar(wxMenuBar* menuBar);
 383
 384     /**
 385         Associates a status bar with the frame.
 386
 387         If @a statusBar is @NULL, then the status bar, if present, is detached from
 388         the frame, but @e not deleted.
 389
 390         @see CreateStatusBar(), wxStatusBar, GetStatusBar()
 391     */
 392     virtual void SetStatusBar(wxStatusBar* statusBar);
 393
 394     /**
 395         Set the status bar pane used to display menu and toolbar help.
 396         Using -1 disables help display.
 397     */
 398     void SetStatusBarPane(int n);
 399
 400     /**
 401         Sets the status bar text and redraws the status bar.
 402
 403         @param text
 404             The text for the status field.
 405         @param number
 406             The status field (starting from zero).
 407
 408         @remarks Use an empty string to clear the status bar.
 409
 410         @see CreateStatusBar(), wxStatusBar
 411     */
 412     virtual void SetStatusText(const wxString& text, int number = 0);
 413
 414     /**
 415         Sets the widths of the fields in the status bar.
 416
 417         @param n
 418             The number of fields in the status bar. It must be the
 419             same used in CreateStatusBar.
 420         @param widths_field
 421             Must contain an array of n integers, each of which is a status field width
 422             in pixels. A value of -1 indicates that the field is variable width; at
 423             least one field must be -1. You should delete this array after calling
 424             SetStatusWidths().
 425
 426         @remarks The widths of the variable fields are calculated from the total
 427                  width of all fields, minus the sum of widths of the
 428                  non-variable fields, divided by the number of variable fields.
 429
 430         @beginWxPerlOnly
 431         In wxPerl this method takes the field widths as parameters.
 432         @endWxPerlOnly
 433     */
 434     virtual void SetStatusWidths(int n, const int* widths_field);
 435
 436     /**
 437         Associates a toolbar with the frame.
 438     */
 439     virtual void SetToolBar(wxToolBar* toolBar);
 440
 441
 442     void PushStatusText(const wxString &text, int number = 0);
 443     void PopStatusText(int number = 0);
 444
 445 };
 446