interface/frame.h

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