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