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