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

Non-Static Controls

Non-static controls, such as wxButton and wxListBox, respond to mouse and keyboard input. We'll describe the basic ones here; more advanced controls are described in Chapter 12. You can also download others (see Appendix E) or create your own.

wxButton

A wxButton is a control that looks like a physical push button with a text label, and it is one of the most common elements of a user interface. It may be placed on a dialog box or panel, or almost any other window. A command event is generated when the user clicks on the button.

Here's a simple example of creating a button:

#include "wx/button.h"
wxButton* button = new wxButton(panel, wxID_OK, wxT("OK"),
wxPoint(10, 10), wxDefaultSize);

Figure 4-12 shows how a button with the default size looks on Windows XP.

wxWidgets obtains the default button size by calling the static function wxButton::GetDefaultSize, calculated appropriately for each platform, but you can let wxWidgets size the button to just fit the label by passing the style wxBU_EXACTFIT.

wxButton Styles

Table 4-17 lists the specific window styles for wxButton.

wxButton Events

wxButton generates a wxCommandEvent propagating event, as shown in Table 4-18.

wxButton Member Functions

These are the major wxButton functions.

SetLabel and GetLabel are accessors for the button label. You can use an ampersand to indicate that the following letter is a mnemonic on Windows and GTK+.

SetDefault sets this button to be the default button on the parent window, so pressing the Enter key activates this button.

wxButton Labels

You can use an ampersand in the button label to indicate that the next letter is an underlined mnemonic (or "access key"), so that the user can press that key instead of clicking on the button. The mnemonic only works on Windows and GTK+; on other platforms, the ampersand will simply be stripped from the label and ignored.

On some systems, notably GTK+, standard buttons such as OK and New are displayed with special graphics in line with the native look and feel for that platform. wxWidgets maps some of its standard window identifiers to these stock buttons, but it also permits the application to substitute a custom label should the need arise.

The recommended usage is as follows. When using a stock button identifier, and you want wxWidgets to supply the label, just supply the identifier and not the label (or an empty string for the label). For example:

wxButton* button = new wxButton(this, wxID_OK);

wxWidgets will substitute the correct standard label on all platforms. For example, on Windows and Mac OS X, the string "&OK" will be used. On GTK+, the stock OK button will be used. However, if you supply a label that is different from the stock label, wxWidgets will use that label. For example:

wxButton* button = new wxButton(this, wxID_OK, wxT("&Apply"));

This will result in the "Apply" label being displayed on all platforms, overriding the standard identifier.

You can get the stock button label for a given identifier with wxGetStockLabel (include wx/stockitem.h), passing the identifier, true (if you want menu codes to be included), and an optional accelerator string to append.

Table 4-19 shows the stock button identifiers and their corresponding labels.

wxBitmapButton

A bitmap button is like a normal text button, but it shows a bitmap instead of text. A command event is generated when the user clicks on the button.

Here's a simple example of creating a bitmap button:

#include "wx/bmpbuttn.h"
wxBitmap bitmap(wxT("print.xpm"), wxBITMAP_TYPE_XPM);
wxBitmapButton* button = new wxBitmapButton(panel, wxID_OK,
bitmap, wxDefaultPosition, wxDefaultSize, wxBU_AUTODRAW);

Figure 4-13 shows the result under Windows.

A bitmap button can be supplied with a single bitmap (optionally with transparency information), and wxWidgets will draw all button states using this bitmap. If the application needs more control, additional bitmaps for the selected state, unpressed focused state, and grayed-out state may be supplied.

XPM is a good choice of bitmap format for buttons because it supports transparency and can be included into C++ code, but you can load them from other formats too, such as JPEG, PNG, GIF, and BMP.

wxBitmapButton Styles

Table 4-20 lists the specific window styles for wxBitmapButton.

wxBitmapButton Events

wxBitmapButton generates wxCommandEvent propagating events, identical to wxButton.

wxBitmapButton Member Functions

These are the major wxBitmapButton functions.

SetBitmapLabel and GetBitmapLabel are accessors for the main button label bitmap. You can also use SetBitmapFocus, SetBitmapSelected, and SetBitmapDisabled and their corresponding getters for more precise control of the button in different states.

SetDefault sets this button to be the default button on the parent window, so pressing the Enter key will activate the button.

wxChoice

The choice control consists of a read-only text area that reflects the selection of a drop-down list box. The list box is hidden until the user presses a button on the control to reveal the list of strings.

To create a choice control, pass the usual parent window, identifier, position, size, and style parameters, plus an array of strings to populate the list. For example:

#include "wx/choice.h"
wxArrayString strings;
strings.Add(wxT("One"));
strings.Add(wxT("Two"));
strings.Add(wxT("Three"));
wxChoice* choice = new wxChoice(panel, ID_COMBOBOX,
wxDefaultPosition, wxDefaultSize, strings);

On most platforms, the look is similar to wxComboBox (see Figure 4-14), except that the user cannot edit the text. On GTK+, wxChoice is a button with a drop-down menu. You may like to use a read-only wxComboBox to get the benefit of the scrolling drop-down list.

wxChoice Styles

There are no special styles for wxChoice.

wxChoice Events

wxChoice generates wxCommandEvent propagating events, as shown in Table 4-21.

wxChoice Member Functions

All wxChoice functions are described by wxControlWithItems: Clear, Delete, FindString, GetClientData, GetClientObject, SetClientData, SetClientObject, GetCount, GetSelection, SetSelection, GetString, SetString, GetStringSelection, SetStringSelection, Insert, and IsEmpty.

wxComboBox

The combo box is a combination of a list box and a single-line text field, and it allows you to set and get the text of the text field independently of the list box. The text field can be read-only, in which case it behaves very much like wxChoice. Normally, the list box is hidden until the user presses a button on the control to reveal the list of strings. This makes for a very compact way of allowing the user to enter text and also to choose from a list of existing options.

To create a combo box, pass the usual parent window, identifier, position, size, and style parameters, plus the initial text and an array of strings to populate the list. For example:

#include "wx/combobox.h"
wxArrayString strings;
strings.Add(wxT("Apple"));
strings.Add(wxT("Orange"));
strings.Add(wxT("Pear"));
strings.Add(wxT("Grapefruit"));
wxComboBox* combo = new wxComboBox(panel, ID_COMBOBOX,
wxT("Apple"), wxDefaultPosition, wxDefaultSize,
strings, wxCB_DROPDOWN);

The result on Windows is shown in Figure 4-14 with the drop-down list activated.

wxComboBox Styles

Table 4-22 lists the specific window styles for wxComboBox.

wxComboBox Events

wxComboBox generates wxCommandEvent propagating events, described in Table 4-23.

wxComboBox Member Functions

These are the major wxComboBox functions. Please refer also to the wxControlWithItems member functions from earlier in this chapter.

Copy copies the selected text onto the clipboard from the text field. Cut does the same, and it also deletes the selected text. Paste copies text from the clipboard into the text field.

GetInsertionPoint returns the insertion point for the combo box's text field (a long integer representing the position), and SetInsertionPoint sets it. Use SetInsertionPointEnd to set the insertion point at the end of the text field.

GetLastPosition returns the last position in the text field.

GetValue returns the value of the text field, and SetValue sets it. For a combo box with the wxCB_READONLY style, the string must be in the combo box choices list; otherwise, the call is ignored in release mode, and it displays an alert in debug mode.

SetSelection with two arguments selects the text in the combo box text field between two given positions. Replace replaces the text between two given positions with specified text. Remove removes the text between two given positions.

See also the following functions from wxControlWithItems: Clear, Delete, FindString, GetClientData, GetClientObject, SetClientData, SetClientObject, GetCount, GetSelection, SetSelection, GetString, SetString, GetStringSelection, SetStringSelection, Insert, and IsEmpty.

wxCheckBox

A check box is a control that normally has two states: on or off. It is represented by a box containing a cross or tick if checked, with a label to the left or right of the check box. Optionally, it can have a third state, called the mixed or undetermined state, which can be used to indicate that the item does not apply (for example, a component in an installer that is always installed and therefore cannot be selected or deselected).

Here's a simple example of creating a check box:

#include "wx/checkbox.h"
wxCheckBox* checkbox = new wxCheckBox(panel, ID_CHECKBOX,
wxT("&Check me"), wxDefaultPosition, wxDefaultSize);
checkBox->SetValue(true);

Figure 4-15 shows how this looks on Windows.

A check box with the wxCHK_3STATE style looks like Figure 4-16 on Windows.

wxCheckBox Styles

Table 4-24 lists the specific window styles for wxCheckBox.

wxCheckBox Events

wxCheckBox generates wxCommandEvent propagating events, described in Table 4-25.

wxCheckBox Member Functions

These are the major wxCheckBox functions.

SetLabel and GetLabel are accessors for the check box label. You can use an ampersand to indicate that the following letter is the mnemonic (or "access key") on Windows and GTK+.

GetValue and SetValue get and set the boolean state. Use Get3StateValue or Set3StateValue to get and set one of wxCHK_UNCHECKED, wxCHK_CHECKED, or wxCHK_UNDETERMINED.

Is3State can be used to determine whether the check box is a three-state check box.

IsChecked returns true if the check box is checked.

wxListBox and wxCheckListBox

A wxListBox is used to select one or more of a list of strings, numbered from zero. The strings are displayed in a scrolling box, with the selected strings marked in reverse video. A list box can be single-selection: if an item is selected, the previous selection is removed. In a multiple-selection list box, clicking an item toggles the item on or off independently of other selections.

Here's an example of creating a single-selection list box:

#include "wx/listbox.h"
wxArrayString strings;
strings.Add(wxT("First string"));
strings.Add(wxT("Second string"));
strings.Add(wxT("Third string"));
strings.Add(wxT("Fourth string"));
strings.Add(wxT("Fifth string"));
strings.Add(wxT("Sixth string"));
wxListBox* listBox = new wxListBox(panel, ID_LISTBOX,
wxDefaultPosition, wxSize(180, 80), strings, wxLB_SINGLE);

Figure 4-17 shows what this looks like under Windows.

wxCheckListBox is derived from wxListBox and inherits its functionality, but in addition, it can display a check box next to each item label. Include wx/checklst.h to use this class. Figure 4-18 shows a wxCheckListBox on Windows.

If you have a lot of items to display, consider using wxVListBox. This is a virtual list box that displays data directly from a source that you specify by deriving a new class and implementing the functions OnDrawItem and OnMeasureItem. Its event macros are the same as for wxListBox. sample (in samples/htlbox), with custom separators drawn by an overridden OnDrawSeparator function.

wxListBox and wxCheckListBox Styles

Table 4-26 lists the specific window styles for wxListBox and wxCheckListBox.

wxListBox and wxCheckListBox Events

wxListBox and wxCheckListBox generate wxCommandEvent propagating events, described in Table 4-27.

wxListBox Member Functions

These are the major wxListBox functions.

Deselect deselects an item in the list box.

GetSelections fills a wxArrayInt array with the positions of the currently selected items and returns it.

InsertItems inserts the given number of strings before the specified position. Pass either the number of items, a C++ array of wxStrings, and the insertion position, or a wxArrayString object and the insertion position.

Selected returns true if the given item is selected.

Set clears the list box and adds the given strings to it. Pass either the number of items, a C++ array of wxStrings, and an optional array of void* client data, or a wxArrayString object and an optional array of void* client data.

SetFirstItem sets the specified item to be the first visible item.

SetSelection and SetStringSelection take an integer or string item and an optional boolean for the selection state, defaulting to TRue.

See also the wxControlWithItems functions: Clear, Delete, FindString, GetClientData, GetClientObject, SetClientData, SetClientObject, GetCount, GetSelection, GetString, SetString, GetStringSelection, Insert, and IsEmpty.

wxCheckListBox Member Functions

In addition to wxListBox's functions, wxCheckListBox has the following functions.

Check takes an item index and boolean and checks or unchecks the item.

IsChecked returns TRue if the given item is checked, and false otherwise.

wxRadioBox

A radio box is used to select an item from a number of mutually exclusive buttons. It is displayed as a vertical column or horizontal row of labeled buttons, within a static box, which may have a label.

The way that the buttons are laid out depends on two constructor parameters: the major dimension, and the orientation style, which can be wxRA_ SPECIFY_COLS (the default) or wxRA_SPECIFY_ROWS. The major dimension is the number of rows or columns. For example, eight buttons laid out with a major dimension of two and the wxRA_SPECIFY_COLS style will have two columns and four rows. Changing to wxRA_SPECIFY_ROWS will give the radio box two rows and four columns.

Here's an example of creating a radio box with three columns:

#include "wx/radiobox.h"
wxArrayString strings;
strings.Add(wxT("&One"));
strings.Add(wxT("&Two"));
strings.Add(wxT("T&hree"));
strings.Add(wxT("&Four "));
strings.Add(wxT("F&ive "));
strings.Add(wxT("&Six "));
wxRadioBox* radioBox = new wxRadioBox(panel, ID_RADIOBOX,
wxT("Radiobox"), wxDefaultPosition, wxDefaultSize,
strings, 3, wxRA_SPECIFY_COLS);

The constructor specifies that the buttons should be laid out in three columns. On Windows, this produces the result shown in Figure 4-20.

wxRadioBox Styles

wxRadioBox can have the window styles listed in Table 4-28 in addition to those described for wxWindow. Specifying a different major dimension changes the button ordering.

wxRadioBox Events

wxRadioBox generates wxCommandEvent propagating events, as shown in Table 4-29.

wxRadioBox Member Functions

These are the major wxRadioBox functions.

Enable with an index and a boolean enables or disables a specified button.

FindString returns the index of a button matching the given string, or wxNOT_FOUND if no match was found.

GetCount returns the number of buttons in the radio box.

GetString and SetString are accessors for the label of the specified button. GetLabel and SetLabel set the radio box label.

GetSelection returns the zero-based index of the selected radio button. GetStringSelection returns the label of the selected button. SetSelection and SetStringSelection set the selection without generating a command event.

Show shows or hides an individual button or the whole radio box.

wxRadioButton

A radio button usually denotes one of several mutually exclusive options. It has a text label next to a button, which is normally round in appearance.

It has two states: on or off. You can create a group of mutually exclusive radio buttons by specifying wxRB_GROUP for the first in the group. The group ends when another radio button group is created, or when there are no more controls. You can also create other types of control within a group.

You might use a group of radio buttons instead of a radio box when the layout is slightly more complex: for example, you may have an extra description or other control next to each radio button. Or you may use radio buttons simply to avoid the static box that wxRadioBox provides.

Here's a simple example of a group of two radio buttons.

#include "wx/radiobut.h"
wxRadioButton* radioButton1 = new wxRadioButton (panel,
ID_RADIOBUTTON1, wxT("&Male"), wxDefaultPosition,
wxDefaultSize, wxRB_GROUP);
radioButton1->SetValue(true);
wxRadioButton* radioButton2 = new wxRadioButton (panel,
ID_RADIOBUTTON2, wxT("&Female"));
// Sizer code to group the buttons horizontally
wxBoxSizer* sizer = new wxBoxSizer(wxHORIZONTAL);
sizer->Add(radioButton1, 0, wxALIGN_CENTER_VERTICAL|wxALL, 5);
sizer->Add(radioButton2, 0, wxALIGN_CENTER_VERTICAL|wxALL, 5);
parentSizer->Add(sizer, 0, wxALIGN_CENTER_VERTICAL|wxALL, 5);

On Windows, this will create the controls shown in Figure 4-22.

wxRadioButton Styles

Table 4-30 lists the specific window styles for wxRadioButton.

wxRadioButton Events

wxRadioButton generates wxCommandEvent propagating events, which are described in Table 4-31.

wxRadioButton Member Functions

GetValue and SetValue get and set the boolean state.

wxScrollBar

A wxScrollBar is a control that represents a horizontal or vertical scrollbar. It is distinct from the two scrollbars that some windows provide automatically, but the two types of scrollbar share the way events are received. A scrollbar has the following main attributes: range, thumb size, page size, and position.

The range is the total number of units associated with the view represented by the scrollbar. For a table with 15 columns, the range would be 15.

The thumb size is the number of units that are currently visible. For the table example, the window might be sized so that only 5 columns are currently visible, in which case the application would set the thumb size to 5. When the thumb size becomes the same as or greater than the range, the scrollbar will automatically be hidden on most platforms.

The page size is the number of units that the scrollbar should scroll when paging through the data.

The scrollbar position is the current thumb position.

To create a scrollbar control, pass the usual parent window, identifier, position, size, and style parameters. For example:

#include "wx/scrolbar.h"
wxScrollBar* scrollBar = new wxScrollBar(panel, ID_SCROLLBAR,
wxDefaultPosition, wxSize(200, 20), wxSB_HORIZONTAL);

Under Windows, this will look like the control in Figure 4-22.

After creation, call SetScrollbar to set its properties. For more information on using this function, see the description of wxScrolledWindow earlier in this chapter.

wxScrollBar Styles

Table 4-32 lists the specific window styles for wxScrollBar.

wxScrollBar Events

wxScrollBar generates wxScrollEvent propagating events. You can use EVT_ COMMAND_SCROLL... macros with window identifiers when intercepting scroll events from controls, or EVT_SCROLL... macros without window identifiers for intercepting scroll events from the receiving windowexcept for this, the macros behave exactly the same. Use EVT_SCROLL(func) to respond to all scroll events. For a comprehensive list of scroll event macros, please see Table I-1 in Appendix I, "Event Classes and Macros," and also see the reference manual.

wxScrollBar Member Functions

These are the major wxScrollBar functions.

Getrange returns the length of the scrollbar.

GetPageSize returns the number of scroll units that will be scrolled when the user pages up or down. Often it is the same as the thumb size.

GetThumbPosition and SetThumbPosition are accessors for the current position of the scrollbar thumb.

GetThumbLength returns the thumb or "view" size.

SetScrollbar sets the scrollbar properties. It takes the position in scroll units, thumb size, range, page size, and optional boolean to specify whether the control will be refreshed.

wxSpinButton

wxSpinButton has two small up and down (or left and right) arrow buttons. It is often used next to a text control for incrementing and decrementing a value. Portable programs should try to use wxSpinCtrl instead as wxSpinButton is not implemented for all platforms.

The range supported by this control (and wxSpinCtrl) depends on the platform but is at least -32768 to 32767.

To create a wxSpinButton control, pass the usual parent window, identifier, position, size, and style parameters. For example:

#include "wx/spinbutt.h"
wxSpinButton* spinButton = new wxSpinButton(panel, ID_SPINBUTTON,
wxDefaultPosition, wxDefaultSize, wxSP_VERTICAL);

On Windows, the result is the control shown in Figure 4-23.

wxSpinButton Styles

Table 4-33 lists the specific window styles for wxSpinButton.

wxSpinButton Events

wxSpinButton generates wxSpinEvent propagating events, as shown in Table 4-34.

wxSpinButton Member Functions

These are the major wxSpinButton functions.

GetMax returns the maximum permissible value.

GetMin returns the minimum permissible value.

GetValue returns the current spin button value, and SetValue sets the current spin value.

SetRange sets the minimum and maximum values.

wxSpinCtrl

wxSpinCtrl combines a wxTextCtrl and a wxSpinButton into one control. When you click on the up and down arrow buttons, the value displayed in the text control will be incremented or decremented, and you can also type integers directly into the text control.

To create a wxSpinCtrl control, pass the usual parent window, identifier, position, size, and style parameters. The following code creates a spin control with a range of zero to 100 and an initial value of 5.

#include "wx/spinctrl.h"
wxSpinCtrl* spinCtrl = new wxSpinCtrl(panel, ID_SPINCTRL,
wxT("5"), wxDefaultPosition, wxDefaultSize, wxSP_ARROW_KEYS,
0, 100, 5);

On Windows, this will look like the control in Figure 4-24.

wxSpinCtrl Styles

Table 4-35 lists the specific window styles for wxSpinCtrl.

wxSpinCtrl Events

wxSpinCtrl generates wxSpinEvent propagating events as shown in Table 4-36. You can also use EVT_TEXT to intercept text updates with a wxCommandEvent handler.

wxSpinCtrl Member Functions

These are the major wxSpinCtrl functions.

GetMax returns the maximum permissible value.

GetMin returns the minimum permissible value.

GetValue returns the current integer spin button value, and SetValue sets the current spin value.

SetRange sets the minimum and maximum values.

wxSlider

A slider is a control with a handle that can be moved back and forth to change the value.

To create a wxSlider control, pass the usual parent window, identifier, position, size, and style parameters. The following code creates a slider control with a range of zero to 40 and an initial position of 16.

#include "wx/slider.h"
wxSlider* slider = new wxSlider(panel, ID_SLIDER, 16, 0, 40,
wxDefaultPosition, wxSize(200, -1),
wxSL_HORIZONTAL|wxSL_AUTOTICKS|wxSL_LABELS);

On Windows, this creates the control shown in Figure 4-25.

wxSlider Styles

Table 4-37 lists the specific window styles for wxSlider.

wxSlider Events

wxSlider generates wxCommandEvent propagating events, as shown in Table I-1 in Appendix I.

wxSlider Member Functions

These are the major wxSlider functions.

ClearSel clears the selection for a slider with wxSL_SELRANGE on Windows. ClearTicks clears the ticks on Windows.

GetLineSize and SetLineSize are accessors for the number of units incremented or decremented when the arrow buttons are clicked. GetPageSize and SetPageSize are accessors for the number of units paged when clicking either side of the thumb.

GetMax returns the maximum permissible value.

GetMin returns the minimum permissible value.

GetSelEnd and GetSelStart return the selection end and start points; use SetSelection to set the selection. These functions are only implemented on Windows.

GetThumbLength and SetThumbLength are accessors for the slider thumb size.

GetTickFreq and SetTickFreq are accessors for the tick frequency on Windows. Use SetTick to set a tick position on Windows.

GetValue returns the current slider value, and SetValue sets the slider value.

SetRange sets the minimum and maximum values.

wxTextCtrl

The text control enables text to be displayed and edited, either as a single-line or a multi-line control. Some simple styling and formatting is supported on some platforms (Windows, GTK+, and Mac OS X via setting and getting text attributes using the wxTextAttr class.

To create a text control, pass the usual parent window, identifier, position, size, and style parameters, plus the initial text. For example, to create a multi-line text control:

#include "wx/textctrl.h"
wxTextCtrl* textCtrl = new wxTextCtrl(panel, ID_TEXTCTRL,
wxEmptyString, wxDefaultPosition, wxSize(240, 100),
wxTE_MULTILINE);

On Windows, this will create the control shown in Figure 4-26.

Multi-line text controls always store text as a sequence of lines separated by \n characters, using Unix newlines even on non-Unix platforms. As a result, you can ignore the differences between platforms, but at a price: indices such as those returned by GetInsertionPoint or GetSelection cannot be used as indices into the string returned by GetValue as they're going to be slightly off for platforms using \r\n as the separator as Windows does.

Instead, if you need to obtain a substring between the two indices obtained from the control with the help of the functions mentioned previously, you should use Getrange. The indices themselves can only be passed to other methods, such as SetInsertionPoint or SetSelection. Never use the indices returned by multi-line text controls as indices into the string it contains, but only as arguments to be passed back to other wxTextCtrl methods.

Multi-line text controls support setting styles: you can set colors and fonts for individual characters. Note that under Windows, the wxTE_RICH style is required for style support. To use the styles, you can either call SetDefaultStyle before inserting the text or call SetStyle later to change the style of the text already in the control. The first method is much more efficient.

In either case, if the style doesn't specify some of the attributes, the values of the default style will be used. If there is no default style, the attributes of the text control itself are used.

In the following code, the second call to SetDefaultStyle doesn't change the text foreground color (which stays red), while the last one doesn't change the background color (which stays gray):

text->SetDefaultStyle(wxTextAttr(*wxRED));
text->AppendText(wxT("Red text\n"));
text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
text->AppendText(wxT("Red on gray text\n"));
text->SetDefaultStyle(wxTextAttr(*wxBLUE);
text->AppendText(wxT("Blue on gray text\n"));

wxTextCtrl Styles

Table 4-39 lists the specific window styles for wxTextCtrl.

wxTextCtrl Events

wxTextCtrl generates wxCommandEvent propagating events, as described in Table 4-40.

wxTextCtrl Member Functions

These are the major wxTextCtrl functions.

AppendText appends the given text to the end of the text control, and WriteText writes the text at the current insertion point. SetValue clears and then sets the value, after which IsModified returns false. You can pass strings with newlines for a multi-line text control. Be aware that these functions send text update events.

GetValue returns the entire contents of the control, possibly with newlines for a multi-line control. GetLineText gets just one line from a multi-line control. Getrange gets the text between two positions.

Copy copies the selected text onto the clipboard from the text field. Cut does the same, and it also deletes the selected text. Paste copies text from the clipboard into the text field. You can use CanCopy, CanCut, and CanPaste in UI update event handlers.

Clear clears the text in the control. Note that this will generate a text update event.

DiscardEdits resets the internal "modified" flag as if the current edits had been saved.

EmulateKeyPress inserts the character that would have been inserted if the given key event had occurred in the text control.

GetdefaultStyle and SetDefaultStyle are accessors for the font currently used for new text. GetStyle returns the style at the given position in the text, and SetStyle sets the style for the given range.

GetInsertionPoint and SetInsertionPoint get and set the current insertion point for new text. GetLastPosition returns the last position in the control, and SetInsertionPointEnd sets the insertion point at the end of the text.

GetLineLength returns the length of the specified line in characters.

GetNumberOfLines returns the number of lines of text in the control.

GetStringSelection returns the text currently selected in the control, or an empty string if there is no selection. GetSelection returns the current selection span in two pointers to long integers. SetSelection selects the text range indicated by two long integers representing positions in the text.

IsEditable returns TRue if the contents may be edited. Call SetEditable to make the control read-only or writeable. IsModified returns TRue if the user has modified the text. IsMultiline returns true if the control is multi-line.

LoadFile loads text from a file into the control, and SaveFile saves the contents as a file.

PositionToXY converts a pixel position to character position and line number, whereas XYToPosition goes the other way.

Remove removes the text in the given span. Replace replaces the text in the given span.

ShowPosition makes the line containing the given position visible.

Undo undoes the last edit, and Redo redoes the last edit. This may do nothing on some platforms. You can use CanUndo and CanRedo to test whether these operations can be applied to the control's text (but not whether the platform supports undo/redo).

wxToggleButton

wxToggleButton is a button that stays pressed when clicked. In other words, it is similar to wxCheckBox in functionality but looks like a wxButton.

Here's a simple example of creating a toggle button:

#include "wx/tglbtn.h"
wxToggleButton* toggleButton = new wxToggleButton(panel, ID_TOGGLE,
wxT("&Toggle label"), wxDefaultPosition, wxDefaultSize);
toggleButton->SetValue(true);

Figure 4-27 shows how a toggle button looks on Windows in the toggled state.

wxToggleButton Styles

There are no specific wxToggleButton styles.

wxToggleButton Events

wxToggleButton generates wxCommandEvent propagating events, described in Table 4-41.

wxToggleButton Member Functions

These are the major wxToggleButton functions.

SetLabel and GetLabel are accessors for the button label. You can use an ampersand to indicate that the following letter is the mnemonic (or "access key"), used on Windows and GTK+.

GetValue and SetValue get and set the boolean state.