A frame is a window which contains subwindows of various kinds. It has a title bar and, optionally, a menu bar, and a status line. Depending on the platform, the frame has further menus or buttons relating to window movement, sizing, closing, etc. Most of these events are handled by the host system without need for special handling by the application. However, the application should normally define an wxFrame::OnClose handler for the frame so that related data and subwindows can be cleaned up.
A frame may contain the subwindows wxCanvas, wxPanel and wxTextWindow.
Some of the MS Windows issues of Multiple Document Interface (MDI) versus Single Document Interface (SDI) frames are covered in the user manual.
wxFrame::wxFrame
wxFrame::~wxFrame
wxFrame::Centre
wxFrame::Command
wxFrame::Create
wxFrame::CreateStatusLine
wxFrame::Fit
wxFrame::GetMenuBar
wxFrame::GetTitle
wxFrame::GetToolBar
wxFrame::Iconize
wxFrame::Iconized
wxFrame::LoadAccelerators
wxFrame::Maximize
wxFrame::OnActivate
wxFrame::OnClose
wxFrame::OnMenuCommand
wxFrame::OnMenuSelect
wxFrame::OnSize
wxFrame::SetIcon
wxFrame::SetMenuBar
wxFrame::SetStatusText
wxFrame::SetStatusWidths
wxFrame::SetTitle
wxFrame::SetToolBar
wxFrame::StatusLineExists
void wxFrame(wxFrame *parent, char *title, int x = -1, int y = -1,
int width = -1, int height = -1,
long style = wxSDI | wxDEFAULT_FRAME, char *name = "frame")
Constructor. The parent parameter can be NULL or an existing frame; if an existing frame is used under MS Windows, the child frame is always on top of the parent, and will be iconized when the parent is iconized.
If title is non-NULL, it is placed on the window frame.
The style parameter may be a combination of the following, using the bitwise 'or' operator.
wxICONIZE | Display the frame iconized (minimized) (Windows only). |
wxCAPTION | Puts a caption on the frame (Windows and XView only). |
wxDEFAULT_FRAME | Defined as (wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | wxSYSTEM_MENU | wxCAPTION). |
wxMDI_CHILD | Specifies a Windows MDI (multiple document interface) child frame. |
wxMDI_PARENT | Specifies a Windows MDI (multiple document interface) parent frame. |
wxMINIMIZE | Identical to wxICONIZE. |
wxMINIMIZE_BOX | Displays a minimize box on the frame (Windows and Motif only). |
wxMAXIMIZE | Displays the frame maximized (Windows only). |
wxMAXIMIZE_BOX | Displays a maximize box on the frame (Windows and Motif only). |
wxSDI | Specifies a normal SDI (single document interface) frame. |
wxSTAY_ON_TOP | Stay on top of other windows (Windows only). |
wxSYSTEM_MENU | Displays a system menu (Windows and Motif only). |
wxTHICK_FRAME | Displays a thick frame around the window (Windows and Motif only). |
wxRESIZE_BORDER | Displays a resizeable border around the window (Motif only). |
wxTINY_CAPTION_HORIZ | Under MS Windows, displays a small horizontal caption if USE_ITSY_BITSY is set to 1 in wx_setup.h and the Microsoft ItsyBitsy library has been compiled. Use instead of wxCAPTION. |
wxTINY_CAPTION_VERT | Under MS Windows, displays a small vertical caption if USE_ITSY_BITSY is set to 1 in wx_setup.h and the Microsoft ItsyBitsy library has been compiled. Use instead of wxCAPTION. |
For Motif, the MWM (the Motif Window Manager) should be running for any styles to work (otherwise all styles take effect).
The name parameter is used to associate a name with the item, allowing the application user to set Motif resource values for individual windows.
See MDI versus SDI for a discussion of how the MS Windows Multiple Document Interface convention is supported..
void ~wxFrame(void)
Destructor. Destroys all child windows and menu bar if present.
void Centre(int direction = wxBOTH)
Centres the frame on the display. The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
void Command(int id)
Simulate a menu command. id is the identifier for a menu item.
void Create(wxFrame *parent, char *title, int x = -1, int y = -1,
int width = -1, int height = -1,
long style = wxSDI | wxDEFAULT_FRAME, char *name = "frame")
Used in two-step frame construction. See wxFrame::wxFrame for further details.
void CreateStatusLine(int number = 1)
Creates a status line at the bottom of the frame. The width of the status line is the whole width of the frame (adjusted automatically when resizing), and the height and text size are chosen by the host system.
The default is to create one field the width of the frame; specify a value between 1 and 5 to create a multi-field status line.
See also wxFrame::SetStatusText.
void Fit(void)
Reize the frame to just fit around the subwindows. If a frame has only one subwindow, that subwindow will be resized by the default wxFrame::OnSize member to fit inside the frame.
wxMenuBar * GetMenuBar(void)
Returns a pointer to the menubar currently associated with the frame (if any).
char * GetTitle(void)
Gets a temporary pointer to the frame title. See wxFrame::SetTitle.
wxWindow * GetToolBar(void)
Under Windows only, gets the window to be used as a toolbar for this MDI parent window.
void Iconize(Bool iconize)
If TRUE, iconizes the frame; if FALSE, shows and restores it.
Bool Iconized(void)
Returns TRUE if the frame is iconized.
void LoadAccelerators(char *resource)
Loads keyboard accelerators for this frame (Windows only). Accelerator tables map keystrokes onto control and menu identifiers, so the programmer does not have to explicitly program this correspondence.
See the hello demo (hello.cpp and hello.rc) for an example of accelerator usage. This is a fragment from hello.rc:
#define HELLO_LOAD_FILE 111 menus_accel ACCELERATORS { "^L", HELLO_LOAD_FILE }If you call LoadAccelerators, you need to override wxFrame::OnActivate to do nothing.
void Maximize(Bool maximize)
Maximizes the frame if maximize is TRUE, otherwise restores it (MS Windows only).
void OnActivate(Bool active)
Called when a window is activated or deactivated (MS Windows only). If the window is being activated, active is TRUE, else it is FALSE.
If you call wxFrame::LoadAccelerators, you need to override this function e.g.
void OnActivate(Bool) {};
Bool OnClose(void)
Sent to the frame when the user has tried to close the window using the window manager (X) or system menu (Windows). If TRUE is returned by OnClose, the frame will be deleted by the system, otherwise the attempt will be ignored. Derive your own class to handle this message; the default handler returns FALSE.
This member is a good place to delete other frames which are conceptually or actually subframes of this frame, since if all frames are not deleted, the application cannot exit. This is the top-level OnClose handler for the 'hello' demo:
Bool MyFrame::OnClose(void) { if (subframe) delete subframe; return TRUE; }When quitting the application from inside the application, for example from a menu item, call the frame's OnClose member before deleting the frame. wxWindows then causes the application to exit without further ado. For example:
// Intercept menu commands void MyFrame::OnMenuCommand(int id) { switch (id) { ... case HELLO_QUIT: { if (OnClose()) delete this; break; } ... } }
void OnMenuCommand(int id)
Sent to the window when an item on the window's menu has been chosen. Derive your own frame class to handle this message. For example:
// Intercept menu commands void MyFrame::OnMenuCommand(int id) { switch (id) { case HELLO_LOAD_FILE: { char *s = wxFileSelector("Load text file", NULL, NULL, NULL, "*.txt"); if (s) frame->text_window->LoadFile(s); break; } case HELLO_QUIT: { if (OnClose()) delete this; break; } case HELLO_PRINT_EPS: { wxPostScriptDC dc(NULL, TRUE); if (dc.Ok()) { dc.StartDoc("Hello printout"); dc.StartPage(); Draw(dc, TRUE); dc.EndPage(); dc.EndDoc(); } break; } case HELLO_ABOUT: { (void)wxMessageBox("wxWindows GUI library demo", "About wxHello", wxOK|wxCENTRE); break; } } }
void OnMenuSelect(int id)
Sent to the window when an item on the window's menu has been selected (i.e. the cursor is on the item, but the left button has not been released). Derive your own frame class to handle this message.
The default OnMenuSelect member puts the menu item help string on the status line, if a status line has been created.
This function is called under MS Windows and Motif, but not XView.
void OnSize(int w, int h)
Called when the user or application resizes the frame. The parameters give the total size of the frame. The default OnSize member looks for a single subwindow, and if one is found, resizes it to fit inside the frame. Override this member if more complex behaviour is required (for example, if there are several subwindows).
void SetIcon(wxIcon * icon)
Sets the icon for this frame, deleting any existing one. The icon is now 'owned' by the frame and will be deleted on frame deletion, so do not delete the icon yourself.
Note an important difference between XView and MS Windows behaviour. In MS Windows, the title of the frame is the icon label, wrapping if necessary for a long title. If the frame title changes, the icon label changes. In XView, the icon label cannot be changed once the icon has been associated with the frame. Also, there is no wrapping, and icon labels must therefore be short.
The best thing to do to accommodate both situations is to have the frame title set to a short string when setting the icon. Then, set the frame title to the desired text. In XView, the icon will keep its short text. In MS Windows, the longer (probably more meaningful) title will be shown.
Instead of using wxFrame::SetIcon under Windows, you can add the following lines to your MS Windows resource file:
wxSTD_MDIPARENTFRAME ICON icon1.ico wxSTD_MDICHILDFRAME ICON icon2.ico wxSTD_FRAME ICON icon3.icowhere icon1.ico will be used for the MDI parent frame, and icon2.ico will be used for MDI child frames, and icon3.ico will be used for non-MDI frames.
If these icons are not supplied, and wxFrame::SetIcon is not called either, then the following defaults apply if you have included wx.rc.
wxDEFAULT_FRAME ICON std.ico wxDEFAULT_MDIPARENTFRAME ICON mdi.ico wxDEFAULT_MDICHILDFRAME ICON child.icoYou can replace std.ico, mdi.ico and child.ico with your own defaults for all your wxWindows application. Currently they show the same icon.
Note: a wxWindows application linked with subsystem equal to 4.0 (i.e. marked as a Windows 95 application) doesn't respond properly to wxFrame::SetIcon. To work around this until a solution is found, mark your program as a 3.5 application. This will also ensure that Windows provides small icons for the application automatically.
See also wxIcon.
void SetMenuBar(wxMenuBar *menuBar)
Tells the frame to show the given menu bar. If the frame is destroyed, the menu bar and its menus will be destroyed also, so do not delete the menu bar explicitly (except by resetting the frame's menu bar to another frame or NULL).
Under MS Windows, a call to wxFrame::OnSize is generated, so be sure to initialize data members properly before calling SetMenuBar.
void SetStatusText(char * text, int number = 0)
Sets the status line text and redraws the status line. Use an empty (not NULL) string to clear the status line. Optionally use number to specify a field in the status line, starting from zero and consistent with the number of fields specified in wxFrame::CreateStatusLine.
void SetStatusWidths(int n, int *widths)
Sets the widths of the fields in the status line. n must be the same used in CreateStatusLine. widths must contain an array of n integers, each of which is a status field width in pixels. A value of -1 indicates that the field is variable width; at least one field must be -1.
The widths of the variable fields are calculated from the total width of all fields, minus the sum of widths of the non-variable fields, divided by the number of variable fields.
Windows only.
void SetTitle(char * title)
Sets the frame title. See wxFrame::GetTitle.
void SetToolBar(wxWindow *toolbar)
Under Windows only, sets the window to be used as a toolbar for this MDI parent window. It is necessary since wxWindows does not provide general functionality for application management of an MDI client area.
When the frame is resized, the toolbar is resized to be the width of the frame client area, and the toolbar height is kept the same.
The parent of the toolbar must be this frame, which must itself have been created as an MDI parent frame.
Please note that SDI frames and MDI child windows must have their toolbars managed by the application.
Bool StatusLineExists(void)
Returns TRUE if the status line has previously been created. See wxFrame::CreateStatusLine, wxFrame::SetStatusText.