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