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