Non-Static Controls

team bbl


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.

Figure 4-12. A wxButton


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.

Table 4-17. wxButton Styles

wxBU_LEFT

Left-justifies the label. Windows and GTK+ only.

wxBU_TOP

Aligns the label to the top of the button. Windows and GTK+ only.

wxBU_RIGHT

Right-justifies the bitmap label. Windows and GTK+ only.

wxBU_BOTTOM

Aligns the label to the bottom of the button. Windows and GTK+ only.

wxBU_EXACTFIT

Creates the button as small as possible instead of making it the standard size.

wxNO_BORDER

Creates a flat button. Windows and GTK+ only.


wxButton Events

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

Table 4-18. wxButton Events

EVT_BUTTON(id, func)

Processes a wxEVT_COMMAND_BUTTON_CLICKED event, generated when the user leftclicks on a wxButton.


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.

Table 4-19. Stock Button Identifiers

Stock Button Identifier

Stock Button Label

wxID_ADD

"Add"

wxID_APPLY

"&Apply"

wxID_BOLD

"&Bold"

wxID_CANCEL

"&Cancel"

wxID_CLEAR

"&Clear"

wxID_CLOSE

"&Close"

wxID_COPY

"&Copy"

wxID_CUT

"Cu&t"

wxID_DELETE

"&Delete"

wxID_FIND

"&Find"

wxID_REPLACE

"Rep&lace"

wxID_BACKWARD

"&Back"

wxID_DOWN

"&Down"

wxID_FORWARD

"&Forward"

wxID_UP

"&Up"

wxID_HELP

"&Help"

wxID_HOME

"&Home"

wxID_INDENT

"Indent"

wxID_INDEX

"&Index"

wxID_ITALIC

"&Italic"

wxID_JUSTIFY_CENTER

"Centered"

wxID_JUSTIFY_FILL

"Justified"

wxID_JUSTIFY_LEFT

"Align Left"

wxID_JUSTIFY_RIGHT

"Align Right"

wxID_NEW

"&New"

wxID_NO

"&No"

wxID_OK

"&OK"

wxID_OPEN

"&Open"

wxID_PASTE

"&Paste"

wxID_PREFERENCES

"&Preferences"

wxID_PRINT

"&Print"

wxID_PREVIEW

"Print previe&w"

wxID_PROPERTIES

"&Properties"

wxID_EXIT

"&Quit"

wxID_REDO

"&Redo"

wxID_REFRESH

"Refresh"

wxID_REMOVE

"Remove"

wxID_REVERT_TO_SAVED

"Revert to Saved"

wxID_SAVE

"&Save"

wxID_SAVEAS

"Save &As..."

wxID_STOP

"&Stop"

wxID_UNDELETE

"Undelete"

wxID_UNDERLINE

"&Underline"

wxID_UNDO

"&Undo"

wxID_UNINDENT

"&Unindent"

wxID_YES

"&Yes"

wxID_ZOOM_100

"&Actual Size"

wxID_ZOOM_FIT

"Zoom to &Fit"

wxID_ZOOM_IN

"Zoom &In"

wxID_ZOOM_OUT

"Zoom &Out"


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.

Figure 4-13. A wxBitmapButton


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.

Table 4-20. wxBitmapButton Styles

wxBU_AUTODRAW

If this is specified, the button will be drawn automatically using the label bitmap only, providing a 3D-look border. If this style is not specified, the button will be drawn without borders and using all provided bitmaps. Windows and Mac OS only.

wxBU_LEFT

Left-justifies the bitmap label. Ignored on Mac OS.

wxBU_TOP

Aligns the bitmap label to the top of the button. Ignored on Mac OS.

wxBU_RIGHT

Right-justifies the bitmap label. Ignored on Mac OS.

wxBU_BOTTOM

Aligns the bitmap label to the bottom of the button. Ignored on Mac OS.


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.

Figure 4-14. A wxComboBox


wxChoice Styles

There are no special styles for wxChoice.

wxChoice Events

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

Table 4-21. wxChoice Events

EVT_CHOICE(id, func)

Processes a wxEVT_COMMAND_CHOICE_SELECTED event, generated by a wxChoice control when the user selects an item in the list.


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.

Table 4-22. wxComboBox Styles

wxCB_SIMPLE

Creates a combo box with a permanently displayed list. Windows only.

wxCB_DROPDOWN

Creates a combo box with a drop-down list.

wxCB_READONLY

Same as wxCB_DROPDOWN but only the strings specified as the combo box choices can be selected, and it is impossible to select a string that is not in the choices list, even from application code.

wxCB_SORT

Creates a combo box whose items are always sorted alphabetically.


wxComboBox Events

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

Table 4-23. wxComboBox Events

EVT_TEXT(id, func)

Processes a wxEVT_COMMAND_TEXT_UPDATED event, generated by the wxComboBox control when its text is edited.

EVT_COMBOBOX(id, func)

Processes a wxEVT_COMMAND_COMBOBOX_SELECTED event, generated by a wxComboBox control when the user selects an item in the list.


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.

Figure 4-15. A wxCheckBox


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

Figure 4-16. A three-state wxCheckBox


wxCheckBox Styles

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

Table 4-24. wxCheckBox Styles

wxCHK_2STATE

Create a two-state check box. This is the default.

wxCHK_3STATE

Create a three-state check box.

wxCHK_ALLOW_3RD_STATE_FOR_USER

By default, a user can't set a three-state check box to the third state. It can only be done from code. Using this style enables the user to set the check box to the third state by clicking.

wxALIGN_RIGHT

Makes the check box appear to the right of the label.


wxCheckBox Events

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

Table 4-25. wxCheckBox Events

EVT_CHECKBOX(id, func)

Processes a wxEVT_COMMAND_CHECKBOX_ CLICKED event, generated when the user checks or unchecks a wxCheckBox control.


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.

Figure 4-17. A wxListBox


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.

Figure 4-18. A wxCheckListBox


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.

wxHtmlListBox is derived from wxVListBox and offers an easy way to display complex items. wxHtmlListBox obtains HTML fragments from the OnGetItem function, which your derived class must override. Figure 4-19 shows the wxWidgets wxHtmlListBox sample (in samples/htlbox), with custom separators drawn by an overridden OnDrawSeparator function.

Figure 4-19. The wxHtmlListBox sample


wxListBox and wxCheckListBox Styles

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

Table 4-26. wxListBox and wxCheckListBox Styles

wxLB_SINGLE

Single-selection list.

wxLB_MULTIPLE

Multiple-selection list: the user can toggle multiple items on and off.

wxLB_EXTENDED

Extended-selection list: the user can select multiple items using the Shift key and the mouse or special key combinations.

wxLB_HSCROLL

Create a horizontal scrollbar if contents are too wide. Windows only.

wxLB_ALWAYS_SB

Always show a vertical scrollbar.

wxLB_NEEDED_SB

Only create a vertical scrollbar if needed.

wxLB_SORT

The list box contents are sorted in alphabetical order.


wxListBox and wxCheckListBox Events

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

Table 4-27. wxListBox Events

EVT_LISTBOX(id, func)

Processes a wxEVT_COMMAND_LISTBOX_SELECTED event, generated by a wxListBox control when the user selects an item in the list.

EVT_LISTBOX_DCLICK(id, func)

Processes a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, generated by a wxListBox control when the user double-clicks on an item in the list.

EVT_CHECKLISTBOX (id, func)

Processes a wxEVT_COMMAND_CHECKLISTBOX_ TOGGLED event, generated by a wxCheckListBox control when the user checks or unchecks an item.


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.

Figure 4-20. A wxRadioBox


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.

Table 4-28. wxRadioBox Styles

wxRA_SPECIFY_ROWS

The major dimension parameter refers to the maximum number of rows.

wxRA_SPECIFIY_COLS

The major dimension parameter refers to the maximum number of columns.


wxRadioBox Events

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

Table 4-29. wxRadioBox Events

EVT_RADIOBOX(id, func)

Processes a wxEVT_COMMAND_RADIOBOX_ SELECTED event, generated by a wxRadioBox control when the user clicks on a radio button.


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.

Figure 4-21. A pair of radio buttons


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.

Figure 4-22. A wxScrollBar


wxRadioButton Styles

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

Table 4-30. wxRadioButton Styles

wxRB_GROUP

Marks the beginning of a new group of radio buttons.

wxRB_USE_CHECKBOX

Displays a check box button instead of a radio button (Palm OS only).


wxRadioButton Events

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

Table 4-31. wxRadioButton Events

EVT_RADIOBUTTON(id, func)

Processes a wxEVT_COMMAND_ RADIOBUTTON_ SELECTED event, generated by a wxRadioButton control when a user clicks on it.


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.

Table 4-32. wxScrollBar Styles

wxSB_HORIZONTAL

Specifies a horizontal scrollbar.

wxSB_VERTICAL

Specifies a vertical scrollbar.


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.

Figure 4-23. A wxSpinButton


wxSpinButton Styles

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

Table 4-33. wxSpinButton Styles

wxSP_HORIZONTAL

Specifies a horizontal spin button. This style is not supported in wxGTK.

wxSP_VERTICAL

Specifies a vertical spin button.

wxSP_ARROW_KEYS

The user can use arrow keys to change the value.

wxSP_WRAP

The value wraps at the minimum and maximum.


wxSpinButton Events

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

Table 4-34. wxSpinButton Events

EVT_SPIN(id, func)

Handles a wxEVT_SCROLL_THUMBTRACK event, generated whenever the up or down arrows are clicked.

EVT_SPIN_UP(id, func)

Handles a wxEVT_SCROLL_LINEUP event, generated when the up arrow is clicked.

EVT_SPIN_DOWN(id, func)

Handles a wxEVT_SCROLL_LINEDOWN event, generated when the down arrow is clicked.


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.

Figure 4-24. A wxSpinCtrl


wxSpinCtrl Styles

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

Table 4-35. wxSpinCtrl Styles

wxSP_ARROW_KEYS

The user can use arrow keys to change the value.

wxSP_WRAP

The value wraps at the minimum and maximum.


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.

Table 4-36. wxSpinCtrl Events

EVT_SPIN(id, func)

Handles a wxEVT_SCROLL_THUMBTRACK event, generated whenever the up or down arrow is clicked.

EVT_SPIN_UP(id, func)

Handles a wxEVT_SCROLL_LINEUP event, generated when the up arrow is clicked.

EVT_SPIN_DOWN(id, func)

Handles a wxEVT_SCROLL_LINEDOWN event, generated when the down arrow is clicked.

EVT_SPINCTRL(id, func)

Handles all events generated for the wxSpinCtrl.


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.

Figure 4-25. A wxSlider


wxSlider Styles

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

Table 4-37. wxSlider Styles

wxSL_HORIZONTAL

Displays the slider horizontally.

wxSL_VERTICAL

Displays the slider vertically.

wxSL_AUTOTICKS

Displays tick marks.

wxSL_LABELS

Displays minimum, maximum, and value labels.

wxSL_LEFT

Displays ticks on the left if it's a vertical slider.

wxSL_RIGHT

Displays ticks on the right if it's a vertical slider.

wxSL_TOP

Displays ticks on the top if it's a horizontal slider. The default is to display them along the bottom.

wxSL_SELRANGE

Enables the user to select a range on the slider. Windows only.


wxSlider Events

wxSlider generates wxCommandEvent propagating events, as shown in Table 4-38, but if you need finer control, you can use EVT_COMMAND_SCROLL_... with wxScrollEvent handlers; see Table I-1 in Appendix I.

Table 4-38. wxSlider Events

EVT_SLIDER(id, func)

Processes a wxEVT_COMMAND_SLIDER_UPDATED event,generated by a wxSlider control when the user moves the slider.


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.

Figure 4-26. A multiline wxTextCtrl


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.

Table 4-39. wxTextCtrl Styles

wxTE_PROCESS_ENTER

The control will generate the event wxEVT_COMMAND_TEXT_ENTER. Otherwise, pressing the Enter key is either processed internally by the control or used for navigation between dialog controls.

wxTE_PROCESS_TAB

The control will receive wxEVT_CHAR events when Tab is pressednormally, the Tab key is used for passing to the next control in a dialog instead.

wxTE_MULTILINE

The text control supports multiple lines.

wxTE_PASSWORD

Text will be echoed as asterisks.

wxTE_READONLY

The text will not be user-editable.

wxTE_RICH

Uses a rich text control under Windows. This enables the control to store more than 64KB of text in the control; the vertical scrollbar is only shown when needed. This style is ignored under other platforms.

wxTE_RICH2

Uses a rich text control version 2.0 or 3.0 under Windows; the vertical scrollbar is always shown. This style is ignored on other platforms.

wxTE_AUTO_URL

Highlight URLs and generate wxTextUrlEvents when mouse events occur over them. On Windows this requires wxTE_RICH. Windows and GTK+ only.

wxTE_NOHIDESEL

By default, the Windows text control doesn't show the selection when it doesn't have focususe this style to force it to always show the selection. Ignored under other platforms.

wxHSCROLL

A horizontal scrollbar will be created and used so that text won't be wrapped. No effect under GTK+.

wxTE_LEFT

The text in the control will be left justified (the default).

wxTE_CENTRE

The text in the control will be centered.

wxTE_RIGHT

The text in the control will be right justified.

wxTE_DONTWRAP

Same as the wxHSCROLL style.

wxTE_LINEWRAP

Wrap lines that are too long to be shown entirely at any position. Currently only supported under wxUniversal.

wxTE_WORDWRAP

Wrap lines that are too long to be shown entirely at word boundaries only. Currently only supported under wxUniversal.

wxTE_NO_VSCROLL

Removes the vertical scrollbar. No effect on GTK+.


wxTextCtrl Events

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

Table 4-40. wxTextCtrl Events

EVT_TEXT(id, func)

Processes a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text is changed.

EVT_TEXT_ENTER(id, func)

Processes a wxEVT_COMMAND_TEXT_ENTER event, generated when the user presses the Enter key. Note that you must use wxTE_PROCESS_ENTER style when creating the control if you want it to generate such events.

EVT_TEXT_MAXLEN(id, func)

Processes a wxEVT_COMMAND_TEXT_MAXLEN event, generated when the user tries to enter more characters into it than the limit previously set with SetMaxLength. Windows and GTK+ only.


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.

Figure 4-27. A wxToggleButton


wxToggleButton Styles

There are no specific wxToggleButton styles.

wxToggleButton Events

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

Table 4-41. wxToggleButton Events

EVT_TOGGLEBUTTON(id, func)

Processes a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event, generated when the user clicks the button.


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.

    team bbl



    Cross-Platform GUI Programming with wxWidgets
    Cross-Platform GUI Programming with wxWidgets
    ISBN: 0131473816
    EAN: 2147483647
    Year: 2005
    Pages: 262

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net