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