Base Window Classes

It's worth mentioning base classes that you may or may not be able use directly but that implement a lot of functionality for derived classes. Use the API reference for these (and other) base classes as well as the reference for the derived classes to get a full understanding of what's available.

wxWindow

wxWindow is both an important base class and a concrete window class that you can instantiate. However, it's more likely that you will derive classes from it (or use pre-existing derived classes) than use it on its own.

As we've seen, a wxWindow may be created either in one step, using a non-default constructor, or two steps, using the default constructor followed by Create. For one-step construction, you use this constructor:

 wxWindow(wxWindow* parent,     wxWindowID id,     const wxPoint& pos = wxDefaultPosition,     const wxSize& size = wxDefaultSize,     long style = 0,     const wxString& name = wxT("panel")); 

For example:

 wxWindow* win  = new wxWindow(parent, wxID_ANY,     wxPoint(100, 100), wxSize(200, 200)); 

wxWindow Styles

Each window class may add to the basic styles defined for wxWindow, listed in Table 4-1. Not all native controls support all border styles, and if no border is specified, a default style appropriate to that class will be used. For example, on Windows, most wxControl-derived classes use wxSUNKEN_BORDER by default, which will be interpreted as the border style for the current theme. An application may suppress the default border by using a style such as wxNO_BORDER.

Table 4-1. Basic Window Styles

wxSIMPLE_BORDER	Displays a thin border around the window.
wxDOUBLE_BORDER	Displays a double border.
wxSUNKEN_BORDER	Displays a sunken border, or control border consistent with the current theme.
wxRAISED_BORDER	Displays a raised border.
wxSTATIC_BORDER	Displays a border suitable for a static control. Windows only.
wxNO_BORDER	Displays no border. This overrides any attempt wxWidgets makes to add a suitable border.
wxtrANSPARENT_WINDOW	Specifies a transparent window (one that doesn't receive paint events). Windows only.
wxTAB_TRAVERSAL	Use this to enable tab traversal for non-dialog windows.
wxWANTS_CHARS	Use this to indicate that the window wants to get all char/key eventseven for keys like Tab or Enter, which are used for dialog navigation and which wouldn't be generated without this style.
wxFULL_REPAINT_ON_RESIZE	By default on Windows, wxWidgets won't repaint the entire client area during a resize. This style ensures that the whole client area will be invali-dated during a resize.
wxVSCROLL	Enables a vertical scrollbar.
wxHSCROLL	Enables a horizontal scrollbar.
wxALWAYS_SHOW_SB	If a window has scrollbars, disables them instead of hiding them when they are not needed (when the size of the window is big enough to not require the scrollbars to navigate it). This style is currently only implemented for Windows and wxUniversal.
wxCLIP_CHILDREN	On Windows only, used to eliminate flicker caused by a window erasing the background of its children.

Table 4-2 lists extra styles that cannot be accommodated in the regular style and that are set using wxWindow::SetExtraStyle.

Table 4-2. Basic Extra Window Styles

wxWS_EX_VALIDATE_RECURSIVELY	By default, Validate, transferDataToWindow, and transferDataFromWindow only work on direct children of the window. Set this style to make them recursively descend into all subwindows.
wxWS_EX_BLOCK_EVENTS	wxCommandEvents and the objects of derived classes are forwarded to the parent window and so on recursively by default. Using this style for the given window enables you to block this propagation at this window to prevent the events from being propagated further upwards. Dialogs have this style on by default, but note that if SetExtraStyle is called by the application, it may be reset.
wxWS_EX_TRANSIENT	Don't use this window as an implicit parent for other windows. This must be used with tran-sient windows; otherwise, there is the risk of creating a dialog or frame with this window as a parent, which would lead to a crash if the parent were destroyed before the child.
wxWS_EX_PROCESS_IDLE	This window should always process idle events, even if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
wxWS_EX_PROCESS_UI_UPDATES	This window should always process UI update events, even if the mode set by wxUpdateUIEvent:: SetMode is wxUPDATE_UI_PROCESS_SPECIFIED. See Chapter 9 for more information on UI update events.

wxWindow Events

wxWindow and all its derived classes generate the events listed in Table 4-3. Events generated by mouse, keyboard, or joystick input are covered in Chapter 6.

Table 4-3. wxWindow Events

EVT_WINDOW_CREATE(func)	Processes a wxEVT_CREATE propagating event, generated when the underlying window has just been created. Handlers take a wxWindowCreateEvent object.
EVT_WINDOW_DESTROY(func)	Processes a wxEVT_DELETE propagating event, generated when the window is about to be destroyed. Handlers take a wxWindowDestroyEvent object.
EVT_PAINT(func)	Processes a wxEVT_PAINT event, generated when the window needs updating. Handlers take a wxPaintEvent object.
EVT_ERASE_BACKGROUND(func)	Processes a wxEVT_ERASE_BACKGROUND event, generated when the window background needs updating. Handlers take a wxEraseEvent object.
EVT_MOVE(func)	Processes a wxEVT_MOVE event, generated when the window moves. Handlers take a wxMoveEvent object.
EVT_SIZE(func)	Processes a wxEVT_SIZE event, generated when the window is resized. Handlers take a wxSizeEvent object.
EVT_SET_FOCUS(func) EVT_KILL_FOCUS(func)	Processes wxEVT_SET_FOCUS and wxEVT_KILL_ FOCUS events, generated when the keyboard focus is gained or lost for this window. Handlers take a wxFocusEvent object.
EVT_SYS_COLOUR_CHANGED(func)	Processes a wxEVT_SYS_COLOUR_CHANGED event, generated when the user changed a color in the control panel (Windows only). Handlers take a wxSysColourChangedEvent object.
EVT_IDLE(func)	Processes a wxEVT_IDLE event, generated in idle time. Handlers take a wxIdleEvent object.
EVT_UPDATE_UI(func)	Processes a wxEVT_UPDATE_UI event, generated in idle time to give the window a chance to update itself.

wxWindow Member Functions

Because wxWindow is the base class for all other window classes, it has the largest number of member functions. We can't describe them all here in detail, so instead we present a summary of some of the most important functions. Browsing them should give you a good idea of the general capabilities of windows, and you can refer to the reference manual for details of parameters and usage.

CaptureMouse captures all mouse input, and ReleaseMouse releases the capture. This is useful in a drawing program, for example, so that moving to the edge of the canvas scrolls it rather than causing another window to be activated. Use the static function GetCapture to retrieve the window with the current capture (if it's within the current application), and HasCapture to determine if this window is capturing input.

Centre (Center), CentreOnParent (CenterOnParent), and CentreOnScreen (CenterOnScreen) center the window relative to the screen or the parent window.

ClearBackground clears the window by filling it with the current background color.

ClientToScreen and ScreenToClient convert between coordinates relative to the top-left corner of this window, and coordinates relative to the top-left corner of the screen.

Close generates a wxCloseEvent whose handler usually tries to close the window. Although the default close event handler will destroy the window, calling Close may not actually close the window if a close event handler has been provided that doesn't destroy the window.

ConvertDialogToPixels and ConvertPixelsToDialog convert between dialog and pixel units, which is useful when basing size or position on font size in order to give more portable results.

Destroy destroys the window safely. Use this function instead of the delete operator because different window classes can be destroyed differently. Frames and dialogs are not destroyed immediately when this function is called but are added to a list of windows to be deleted on idle time, when all pending events have been processed. This prevents problems with events being sent to non-existent windows.

Enable enables or disables the window and its children for input. Some controls display themselves in a different color when disabled. Disable can be used instead of passing false to Enable.

FindFocus is a static function that can be used to find the window that currently has the keyboard focus.

FindWindow can be used with an identifier or a name to find a window in this window's hierarchy. It can return a descendant or the parent window itself. If you know the type of the window, you can use wxDynamicCast to safely cast to the correct type, returning either a pointer to that type or NULL:

 MyWindow* window = wxDynamicCast(FindWindow(ID_MYWINDOW), MyWindow); 

Fit resizes the window to fit its children. This should be used with sizer-based layout. FitInside is similar, but it uses the virtual size (useful when the window has scrollbars and contains further windows).

Freeze and Thaw are hints to wxWidgets that display updates between these two function calls should be optimized. For example, you could use this when adding a lot of lines to a text control separately. Implemented for wxTextCtrl on GTK+, and all windows on Windows and Mac OS X.

GetAcceleratorTable and SetAcceleratorTable get and set the accelerator table for this window.

GetBackgroundColour and SetBackgroundColour are accessors for the window background color, used by the default wxEVT_ERASE_BACKGROUND event. After setting the color, you will need to call Refresh or ClearBackground to show the window with the new color. SetOwnBackgroundColour is the same as SetBackgroundColour but the color is not inherited by the window's children.

GetBackgroundStyle and SetBackgroundStyle are accessors for the window background style. By default, the background style is wxBG_STYLE_SYSTEM, which tells wxWidgets to draw the window background with whatever style is appropriate, whether a texture drawn according to the current theme (for example, wxDialog), or a solid color (for example, wxListBox). If you set the style to wxBG_STYLE_COLOUR, wxWidgets will use a solid color for this window. If you set it to wxBG_STYLE_CUSTOM, wxWidgets will suppress the default background drawing, and the application can paint it from its erase or paint event handler. If you want to draw your own textured background, then setting the style to wxBG_STYLE_CUSTOM is recommended for flicker-free refreshes.

GetBestSize returns the minimal size for the window in pixels (as implemented for each window by DoGetBestSize). This is a hint to the sizer system not to resize the window so small that it cannot be viewed or used properly. For example, for a static control, it will be the minimum size such that the control label is not truncated. For windows containing subwindows (typically wxPanel), the size returned by this function will be the same as the size the window would have had after calling Fit.

GetCaret and SetCaret are accessors for the wxCaret object associated with the window.

GetClientSize and SetClientSize are accessors for the size of the client area in pixels. The client area is the region within any borders and window decorations, inside which you can draw or place child windows.

GetCursor and SetCursor are accessors for the cursor associated with the window.

GeTDefaultItem returns a pointer to the child button that is the default for this window, or NULL. The default button is the one activated by pressing the Enter key. Use wxButton::SetDefault to set the default button.

GeTDropTarget and SetDropTarget are accessors for the wxDropTarget object which handles dropped data objects for this window. Drag and drop is covered in Chapter 11, "Clipboard and Drag and Drop."

GetEventHandler and SetEventHandler are accessors for the first event handler for the window. By default, the event handler is the window itself, but you can interpose a different event handler. You can also use PushEventHandler and PopEventHandler to set up a handler chain, with different handlers dealing with different events. wxWidgets will search along the chain for handlers that match incoming events (see Chapter 3, "Event Handling").

GetExTRaStyle and SetExtraStyle are accessors for the "extra" style bits. Extra styles normally start with wxWS_EX_.

GetFont and SetFont are accessors for the font associated with this window. SetOwnFont is the same as SetFont, except that the font is not inherited by the window's children.

GetForegroundColour and SetForegroundColour are accessors for the window foreground color, whose meaning differs according to the type of window. SetOwnForegroundColour is the same as SetOwnForegroundColour but the color is not inherited by the window's children.

GetHelpText and SetHelpText are accessors for the context-sensitive help string associated with the window. The text is actually stored by the current wxHelpProvider implementation, and not in the window.

GetId and SetId are accessors for the window identifier.

GetLabel returns the label associated with the window. The interpretation of this value depends on the particular window class.

GetName and SetName are accessors for the window name, which does not have to be unique. The window name has no special significance to wxWidgets, except under Motif where it is the resource name for the window.

GetParent returns a pointer to the parent window.

GetPosition returns the position of the top-left corner of the window in pixels, relative to its parent.

Getrect returns a wxRect object (see Chapter 13, "Data Structure Classes") representing the size and position of the window in pixels.

GetSize and SetSize retrieve and set the outer window dimensions in pixels.

GetSizer and SetSizer are accessors for the top-level sizer used for arranging child windows on this window.

GetTextExtent gets the dimensions of the string in pixels, as it would be drawn on the window with the currently selected font.

GetToolTip and SetToolTip are accessors for the window tooltip object.

GetUpdateRegion returns the portion of the window that currently needs refreshing (since the last paint event was handled).

GetValidator and SetValidator are accessors for the optional wxValidator object associated with the window, to handle transfer and validation of data. See Chapter 9 for more about validators.

GetVirtualSize returns the virtual size of the window in pixels, as determined by setting the scrollbar dimensions.

GetWindowStyle and SetWindowStyle are accessors for the window style.

InitDialog sends a wxEVT_INIT_DIALOG event to initiate transfer of data to the window.

IsEnabled indicates whether the window is enabled or disabled.

IsExposed indicates whether a point or a part of the rectangle is in the update region.

IsShown indicates whether the window is shown.

IsTopLevel indicates whether the window is top-level (a wxFrame or a wxDialog).

Layout invokes the sizer-based layout system if there is a sizer associated with the window. See Chapter 7 for more about sizers.

Lower sends a window to the bottom of the window hierarchy, while Raise raises the window above all other windows. This works for top-level windows and child windows.

MakeModal disables all the other top-level windows in the application so that the user can only interact with this window.

Move moves the window to a new position.

MoveAfterInTabOrder moves the tab order of this window to a position just after the window passed as argument, and MoveBeforeInTabOrder is the same but moves the tab order in front of the window argument.

PushEventHandler pushes an event handler onto the event stack for this window, and PopEventHandler removes and returns the top-most event handler on the event handler stack. RemoveEventHandler finds a handler in the event handler stack and removes it.

PopupMenu shows a menu at the specified position.

Refresh and RefreshRect causes a paint event (and optionally an erase event) to be sent to the window.

SetFocus gives the window the current keyboard focus.

SetScrollbar sets the properties for a built-in scrollbar.

SetSizeHints allows specification of the minimum and maximum window sizes, and window size increments, in pixels. This is applicable to top-level windows only.

Show shows or hides the window; Hide is equivalent to passing false to Show.

transferDataFromWindow and transferDataToWindow transfer data from and to the window. By default, these call validator functions, but they can be overridden by the application.

Update immediately repaints the invalidated area of the window.

UpdateWindowUI sends wxUpdateUIEvents to the window to give the window (and application) a chance to update window elements, such as toolbars as menu items.

Validate validates the current values of the child controls using their validators.

wxControl

wxControl derives from wxWindow and is the abstract base class for controls: windows that display items of data and usually respond to mouse clicks or keyboard input by sending command events.

wxControlWithItems

wxControlWithItems is an abstract base class for some wxWidgets controls that contain several items, such as wxListBox, wxCheckListBox, wxChoice, and wxComboBox. The use of this intermediate class ensures that a consistent API is used across several controls that have similar functionality.

The items in a wxControlWithItems have string labels and, optionally, client data associated with them. Client data comes in two different flavors: either simple untyped (void*) pointers, which are stored by the control but not used in any way by it, or typed pointers (wxClientData*). These typed pointers are owned by the control, meaning that the typed client data will be deleted when an item is deleted or when the entire control is cleared (for example, when it is destroyed). All items in the same control must have client data of the same type: either all typed or all untyped (if it has any at all). The client data type is determined by the first call to Append, SetClientData, or SetClientObject. To work with typed client data, you should derive a class from wxClientData containing the data you want to store, and pass it to Append or SetClientObject.

wxControlWithItems Member Functions

Append adds a single item or an array of items to the control. When adding a single item, you can also associate typed or untyped data with the item by passing a second argument. For example:

 wxArrayString strArr; strArr.Add(wxT("First string")); strArr.Add(wxT("Second string")); controlA->Append(strArr); controlA->Append(wxT("Third string")); controlB->Append(wxT("First string"), (void *) myPtr); controlC->Append(wxT("First string"), new MyTypedData(1)); 

Clear clears all items from the controls (deleting all typed client data).

Delete removes an item (and its typed client data) using a zero-based position.

FindString returns the zero-based index to the item matching a string, or wxNOT_FOUND if no item was found.

GetClientData and GetClientObject return a pointer to the client data associated with the specified item (if any). SetClientData and SetClientObject can be used to set the data for a specified item.

GetCount returns the number of items in the control.

GetSelection returns the index of the selected item, or wxNOT_FOUND if none was selected. SetSelection sets the index of the selected item.

GetString returns the item label at the given position; SetString sets an item's label.

GetStringSelection returns the label of the selected item or an empty string if no item is selected; SetStringSelection sets the selection. To avoid an assertion, first check that the string is available in the control using FindString.

Insert inserts an item (with or without client data) at a specified position in the control.

IsEmpty returns TRue if the control has no items, and false otherwise.