wxformlist

wxformlist
	Chapter 11. The wxWidgets-based (WXWN) Components

wxformlist

Description

A wxformlist object is a box on a form that contains a list separate items, one or more of which can be selected.

Type Tags

wxformcontrol

Object Value

Properties

Property Type Description

_ type(*) This property is provided for use by the user to attach any object of any type to the type in which this property is provided.

__ type(*) This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property.

backgroundrgb rgb Gives the color of the background of the list control.

captureable boolean Specifies whether or not the control events can be captured by the form when the controlcapture() method is called.

enabled boolean Specifies whether or not the control is enabled.

focusable boolean Specifies whether or not the control can have the input focus. For wxformlist objects this is always .true

font wxfont This is a reference to the wxfont object that describes how the text in the list control is formatted.

form wxform Specifies the wxform object to which this list control belongs.

height integer Gives the height of the list control, in pixels.

itemcount integer Gives the number of items in the list control.

left integer Gives the position of the left side of the list control relative to the left side of the form, in pixels.

name string The name of the wxformlist object.

next type(wxformcontrol) Specifies the next wxformcontrol on the same form.

ondoubleclick event An event that is triggered when the list control receives a double-click. The event handling function will receive the following parameters: (wxformlist me[, type(*) reference]). The reference is only passed if it is provided by the user.

ongotfocus event An event that is triggered when the list control receives input focus. The event handling function will receive the following parameters: (wxformlist me[, type(*) reference]). The reference is only passed if it is provided by the user.

onlostfocus event An event that is triggered when the list control loses input focus. The event handling function will receive the following parameters: (wxformlist me[, type(*) reference]). The reference is only passed if it is provided by the user.

onmouse

event

An event that is triggered each time a mouse event occurs that matches the bits set in the onmousemask property. The onmouse event handling function should be defined as follows: function onmouse(type(wxformcontrol) control, integer etype, integer keys, integer x, integer y, type(*) reference) where:

etype is the bit (defined as for onmousemask) showing what sort of event it is.
keys is a collection of bits showing key positions:
Key Type Bit Value
shift down 0x00010000
ctrl down 0x00020000
alt down 0x00040000
meta down 0x00080000
x and y are the position of the mouse event
reference is the (optional) reference object in the wxformlist.onmouse.reference

onmousemask integer Holds the mask that decides which mouse events are captured and sent to the onmouse event handler.

onselectionchange event An event which is triggered when what is selected in the list control changes. The event handling function will receive the following parameters: (wxformlist me[, type(*) reference]). The reference is only passed if it is provided by the user.

selectiontype

string

A string which indicates the way in which the user selects items in the list. selectiontype contains one of the following values:

"single" — The user can select one item from the list. Selecting an item automatically deselects any previously selected item.
"multiple" — The user can select any number of items from the list, where clicking an item toggles its selection state.
"extended" — The user can select any number of items from the list, where combining mouse control with special keys (such as shift or control) allows multiple items to be selected in one action.

textrgb rgb Gives the color of the text in the list control.

tooltip string Contains the test that is displayed as a tooltip for the control.

top integer Gives the position of the top edge of the list control relative to the top edge of the form, in pixels.

type type Specifies the wxformlist type object.

visible boolean Specifies whether or not the control is visible.

width integer Gives the width of the list control, in pixels.

Methods

delete()

Description

Deletes (removes) items from a list control. The wxformlist object itself is returned, to allow multiple methods to be put into one expression.

Prototype

wxformlistvar.delete ( integer , … )

`Parameters`

Parameter	Default value	Type name	Description
	None	integer	The 1-based index into the list of an item to delete.
…	None

`deleteall()`

`Description`

Deletes (removes) all items from a list control. The wxformlist object itself is returned, to allow multiple methods to be put into one expression.

`Prototype`

wxformlistvar.deleteall ()

`Parameters`

None

`getselected()`

`Description`

Searches a list control for the next selected item after a specified start point. The return value is the 1-based index of the first selected item which is equal to or greater than the specified start point, or is .nul if there is no such selected item.

`Prototype`

wxformlistvar.getselected ( integer firstitem )

`Parameters`

Parameter	Default value	Type name	Description
firstitem	None	integer	The 1-based index of the first item to search for selection.

`insert()`

`Description`

Adds items to a list control. The wxformlist object itself is returned, to allow multiple methods to be put into one expression.

`Prototype`

wxformlistvar.insert ( integer firstitem, string , … )

`Parameters`

Parameter	Default value	Type name	Description
firstitem	The current value of the `itemcount` property plus one - i.e. the end of the list.	integer	The 1-based index into the list to show the position to place the first of the items to be inserted.
	None	string	The string to be added as an item at position `firstitem`.
…	None

`isselected()`

`Description`

Determines whether or not a specified item in a list control is currently selected. The method returns .true if the item is selected, or .false otherwise.

`Prototype`

wxformlistvar.isselected ( integer item )

`Parameters`

Parameter	Default value	Type name	Description
item	None	integer	The 1-based index into the list of an item for which the selection state should be determined.

`remove()`

`Description`

Removes the control from the form. If any object has a reference to the control, those references will no longer be valid. It is not safe to attempt to use a control after this method has been called.

`Prototype`

wxformlistvar.remove ()

`Parameters`

None

`select()`

`Description`

Selects or deselects an item in a list control. The wxformlist object itself is returned, to allow multiple methods to be put into one expression.

`Prototype`

wxformlistvar.select ( integer item, boolean select )

`Parameters`

Parameter	Default value	Type name	Description
item	None	integer	The 1-based index of the item to select or deselect.
select	`.true`	boolean	Determines whether to select (`.true`) the item, or deselect (`.false`) it. It is an error to try to deselect an item in a list control with a `selectiontype` setting of "single"

`setbackgroundrgb()`

`Description`

Sets the background color of the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression. It is an error to specify both the rgb argument and one or more of the red, green or blue arguments.

`Prototype`

wxformlistvar.setbackgroundrgb ( integer rgb, integer red, integer green, integer blue )

`Parameters`

Parameter	Default value	Type name	Description
rgb	The current value of the `backgroundrgb` property	integer	The new background color of the list control. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object.
red	The current value of the `backgroundrgb.red` property	integer	The red component in the new background color of the list control. This must be between 0 and 255 inclusive.
green	The current value of the `backgroundrgb.green` property	integer	The green component in the new background color of the list control. This must be between 0 and 255 inclusive.
blue	The current value of the `backgroundrgb.blue` property	integer	The blue component in the new background color of the list control. This must be between 0 and 255 inclusive.

`setcaptureable()`

`Description`

This method is used to determine whether the events for the control can be captured and passed to the form or not. By default, events can be captured.

`Prototype`

wxformlistvar.setcaptureable ( boolean captureable )

`Parameters`

Parameter	Default value	Type name	Description
captureable	None	boolean	Sets whether or not the events for this control can be captured by the form using the `controlcapture()` method of the form.

`setenabled()`

`Description`

Sets the enabled state of the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setenabled ( boolean enabled )

`Parameters`

Parameter	Default value	Type name	Description
enabled	None	boolean	The desired enabled state for the list control.

`setfocus()`

`Description`

Sets focus to the control, provided that it is not invisible or disabled. If this is called for a form that is not yet in a container, then nothing will happen except that the focuscontrol of the wxform object will be set. Once the form is placed in a container, the control will get focus and the ongotfocus event will fire.

`Prototype`

wxformlistvar.setfocus ()

`Parameters`

None

`setfont()`

`Description`

Sets the font to be used for the text in the listbox control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setfont ( wxfont font )

`Parameters`

Parameter	Default value	Type name	Description
font	None	wxfont	The wxfont object that will be used to format the text in the listbox control.

`setname()`

`Description`

Sets the name of the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setname ( string name )

`Parameters`

Parameter	Default value	Type name	Description
name	None	string	The new name for the list control.

`setnext()`

`Description`

Sets the position of the control in the z-order and tab order.

`Prototype`

wxformlistvar.setnext ( type(wxformcontrol) next )

`Parameters`

Parameter	Default value	Type name	Description
next	None	type(wxformcontrol)	Calling the method with the value `.nul` sets a control to be the last one in the ring (the one before form.firstcontrol) and so has the highest z-order, and passing any other control as the argument puts the target control immediately below the one specified as the parameter. The visible stacking of controls on a form is such that the earliest in the ring is the furthest back in the z-order.

`setonmousemask()`

`Description`

Sets the mask that is used to decide which mouse events will be trapped for the control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setonmousemask ( integer onmousemask )

`Parameters`

Parameter Default value Type name Description

onmousemask

None

integer

The definition of which events should be handled by the onmouse event handler. The onmousemask is made up of bits:

Event Type	Bit Value
left button down	0x00000001
left button up	0x00000002
left button double click	0x00000004
middle button down	0x00000010
middle button up	0x00000020
middle button dbl click	0x00000040
right button down	0x00000100
right button up	0x00000200
right button dbl click	0x00000400
motion	0x00001000

`setposition()`

`Description`

Sets the size and/or position of the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setposition ( integer left, integer top, integer width, integer height )

`Parameters`

Parameter	Default value	Type name	Description
left	The current value of the `left` property	integer	The new position of the left side of the list control on the form.
top	The current value of the `top` property	integer	The new position of the top edge of the list control on the form.
width	The current value of the `width` property	integer	The new width of the list control on the form.
height	The current value of the `height` property	integer	The new height of the list control on the form.

`settextrgb()`

`Description`

Sets the color of the text in the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression. It is an error to specify both the rgb argument and one or more of the red, green or blue arguments.

`Prototype`

wxformlistvar.settextrgb ( integer rgb, integer red, integer green, integer blue )

`Parameters`

Parameter	Default value	Type name	Description
rgb	The current value of the `textrgb` property	integer	The new color of the text in the control. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object.
red	The current value of the `textrgb.red` property	integer	The red component in the new text color of the control. This must be between 0 and 255 inclusive.
green	The current value of the `textrgb.green` property	integer	The green component in the new text color of the control. This must be between 0 and 255 inclusive.
blue	The current value of the `text.blue` property	integer	The blue component in the new text color of the control. This must be between 0 and 255 inclusive.

`settooltip()`

`Description`

Sets the text for the tooltip associated with the control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.settooltip ( string tooltip )

`Parameters`

Parameter	Default value	Type name	Description
tooltip	None	string	The new text to set for the tooltip.

`setvisible()`

`Description`

Sets the visibility of the list control. The wxformlist object itself is returned, to allow multiple setting methods to be put into one expression.

`Prototype`

wxformlistvar.setvisible ( boolean visible )

`Parameters`

Parameter	Default value	Type name	Description
visible	None	boolean	The desired visibility of the list control.

`wxformlist[]`

`Get`

`Subscripts`

A numeric value giving the 1-based index of an item in the list.

`Description`

Retrieves the text of the specified item.

`Set`

`Subscripts`

A numeric value giving the 1-based index of an item in the list.

`Description`

Sets the text of the specified item.

`Set Reference`

Attempting to set a reference to an object is not supported.


wxformgrid		wxformoption