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 wxframe_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     @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     @library{wxcore}
 110     @category{managedwnd}
 111
 112     @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
 113 */
 114 class wxFrame : public wxTopLevelWindow
 115 {
 116 public:
 117     //@{
 118     /**
 119         Constructor, creating the window.
 120
 121         @param parent
 122             The window parent. This may be @NULL. If it is non-@NULL, the frame will
 123             always be displayed on top of the parent window on Windows.
 124         @param id
 125             The window identifier. It may take a value of -1 to indicate a default
 126         value.
 127         @param title
 128             The caption to be displayed on the frame's title bar.
 129         @param pos
 130             The window position. The value wxDefaultPosition indicates a default position,
 131         chosen by
 132             either the windowing system or wxWidgets, depending on platform.
 133         @param size
 134             The window size. The value wxDefaultSize indicates a default size, chosen by
 135             either the windowing system or wxWidgets, depending on platform.
 136         @param style
 137             The window style. See wxFrame.
 138         @param name
 139             The name of the window. This parameter is used to associate a name with the
 140         item,
 141             allowing the application user to set Motif resource values for
 142             individual windows.
 143
 144         @remarks For Motif, MWM (the Motif Window Manager) should be running for
 145                  any window styles to work (otherwise all styles take
 146                  effect).
 147
 148         @see Create()
 149     */
 150     wxFrame();
 151     wxFrame(wxWindow* parent, wxWindowID id,
 152             const wxString& title,
 153             const wxPoint& pos = wxDefaultPosition,
 154             const wxSize& size = wxDefaultSize,
 155             long style = wxDEFAULT_FRAME_STYLE,
 156             const wxString& name = "frame");
 157     //@}
 158
 159     /**
 160         Destructor. Destroys all child windows and menu bar if present.
 161     */
 162     ~wxFrame();
 163
 164     /**
 165         Centres the frame on the display.
 166
 167         @param direction
 168             The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
 169     */
 170     void Centre(int direction = wxBOTH);
 171
 172     /**
 173         Used in two-step frame construction. See wxFrame()
 174         for further details.
 175     */
 176     bool Create(wxWindow* parent, wxWindowID id,
 177                 const wxString& title,
 178                 const wxPoint& pos = wxDefaultPosition,
 179                 const wxSize& size = wxDefaultSize,
 180                 long style = wxDEFAULT_FRAME_STYLE,
 181                 const wxString& name = "frame");
 182
 183     /**
 184         Creates a status bar at the bottom of the frame.
 185
 186         @param number
 187             The number of fields to create. Specify a
 188             value greater than 1 to create a multi-field status bar.
 189         @param style
 190             The status bar style. See wxStatusBar for a list
 191             of valid styles.
 192         @param id
 193             The status bar window identifier. If -1, an identifier will be chosen by
 194             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,
 208                                          long style = 0,
 209                                          wxWindowID id = -1,
 210                                          const wxString& name = "statusBar");
 211
 212     /**
 213         Creates a toolbar at the top or left of the frame.
 214
 215         @param style
 216             The toolbar style. See wxToolBar for a list
 217             of valid styles.
 218         @param id
 219             The toolbar window identifier. If -1, an identifier will be chosen by
 220             wxWidgets.
 221         @param name
 222             The toolbar window name.
 223
 224         @return A pointer to the toolbar if it was created successfully, @NULL
 225                  otherwise.
 226
 227         @remarks By default, the toolbar is an instance of wxToolBar (which is
 228                  defined to be a suitable toolbar class on each
 229                  platform, such as wxToolBar95). To use a different
 230                  class, override OnCreateToolBar().
 231
 232         @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(),
 233              GetToolBar()
 234     */
 235     virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
 236                                      wxWindowID id = -1,
 237                                      const wxString& name = "toolBar");
 238
 239     /**
 240         Returns the origin of the frame client area (in client coordinates). It may be
 241         different from (0, 0) if the frame has a toolbar.
 242     */
 243     wxPoint GetClientAreaOrigin() const;
 244
 245     /**
 246         Returns a pointer to the menubar currently associated with the frame (if any).
 247
 248         @see SetMenuBar(), wxMenuBar, wxMenu
 249     */
 250     wxMenuBar* GetMenuBar() const;
 251
 252     /**
 253         Returns a pointer to the status bar currently associated with the frame (if
 254         any).
 255
 256         @see CreateStatusBar(), wxStatusBar
 257     */
 258     wxStatusBar* GetStatusBar() const;
 259
 260     /**
 261         Returns the status bar pane used to display menu and toolbar help.
 262
 263         @see SetStatusBarPane()
 264     */
 265     int GetStatusBarPane();
 266
 267     /**
 268         Returns a pointer to the toolbar currently associated with the frame (if any).
 269
 270         @see CreateToolBar(), wxToolBar, SetToolBar()
 271     */
 272     wxToolBar* GetToolBar() const;
 273
 274     /**
 275         Virtual function called when a status bar is requested by CreateStatusBar().
 276
 277         @param number
 278             The number of fields to create.
 279         @param style
 280             The window style. See wxStatusBar for a list
 281             of valid styles.
 282         @param id
 283             The window identifier. If -1, an identifier will be chosen by
 284             wxWidgets.
 285         @param name
 286             The window name.
 287
 288         @return A status bar object.
 289
 290         @remarks An application can override this function to return a different
 291                  kind of status bar. The default implementation returns
 292                  an instance of wxStatusBar.
 293
 294         @see CreateStatusBar(), wxStatusBar.
 295     */
 296     virtual wxStatusBar* OnCreateStatusBar(int number, long style,
 297                                            wxWindowID id,
 298                                            const wxString& name);
 299
 300     /**
 301         Virtual function called when a toolbar is requested by CreateToolBar().
 302
 303         @param style
 304             The toolbar style. See wxToolBar for a list
 305             of valid styles.
 306         @param id
 307             The toolbar window identifier. If -1, an identifier will be chosen by
 308             wxWidgets.
 309         @param name
 310             The toolbar window name.
 311
 312         @return A toolbar object.
 313
 314         @remarks An application can override this function to return a different
 315                  kind of toolbar. The default implementation returns an
 316                  instance of wxToolBar.
 317
 318         @see CreateToolBar(), wxToolBar.
 319     */
 320     virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
 321                                        const wxString& name);
 322
 323     /**
 324         Simulate a menu command.
 325
 326         @param id
 327             The identifier for a menu item.
 328     */
 329     void ProcessCommand(int id);
 330
 331     /**
 332         This function sends a dummy @ref overview_wxsizeevent "size event" to the frame
 333         forcing it to reevaluate its children positions. It is sometimes useful to call
 334         this function after adding or deleting a children after the frame creation or
 335         if a child size changes.
 336         Note that if the frame is using either sizers or constraints for the children
 337         layout, it is enough to call wxWindow::Layout directly and
 338         this function should not be used in this case.
 339     */
 340     void SendSizeEvent();
 341
 342     /**
 343         Tells the frame to show the given menu bar.
 344
 345         @param menuBar
 346             The menu bar to associate with the frame.
 347
 348         @remarks If the frame is destroyed, the menu bar and its menus will be
 349                  destroyed also, so do not delete the menu bar
 350                  explicitly (except by resetting the frame's menu bar to
 351                  another frame or @NULL).
 352
 353         @see GetMenuBar(), wxMenuBar, wxMenu.
 354     */
 355     void SetMenuBar(wxMenuBar* menuBar);
 356
 357     /**
 358         Associates a status bar with the frame.
 359
 360         @see CreateStatusBar(), wxStatusBar, GetStatusBar()
 361     */
 362     void SetStatusBar(wxStatusBar* statusBar);
 363
 364     /**
 365         Set the status bar pane used to display menu and toolbar help.
 366         Using -1 disables help display.
 367     */
 368     void SetStatusBarPane(int n);
 369
 370     /**
 371         Sets the status bar text and redraws the status bar.
 372
 373         @param text
 374             The text for the status field.
 375         @param number
 376             The status field (starting from zero).
 377
 378         @remarks Use an empty string to clear the status bar.
 379
 380         @see CreateStatusBar(), wxStatusBar
 381     */
 382     virtual void SetStatusText(const wxString& text, int number = 0);
 383
 384     /**
 385         Sets the widths of the fields in the status bar.
 386
 387         @param n
 388             The number of fields in the status bar. It must be the
 389             same used in CreateStatusBar.
 390         @param widths
 391             Must contain an array of n integers, each of which is a status field width
 392             in pixels. A value of -1 indicates that the field is variable width; at
 393         least one
 394             field must be -1. You should delete this array after calling
 395         SetStatusWidths.
 396
 397         @remarks The widths of the variable fields are calculated from the total
 398                  width of all fields, minus the sum of widths of the
 399                  non-variable fields, divided by the number of variable
 400                  fields.
 401     */
 402     virtual void SetStatusWidths(int n, int* widths);
 403
 404     /**
 405         Associates a toolbar with the frame.
 406     */
 407     void SetToolBar(wxToolBar* toolBar);
 408 };
 409