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