CrossPlatform GUI Programming with wxWidgets [Electronic resources] نسخه متنی

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 Chapter 9 for more information on UI update events.

wxWindow Events




wxWindow and all its derived classes generate the events listed 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).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.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.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.