PtComboBox

`PtComboBox`

A text field with a list of choices

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtCompound --> PtComboBox

For more information, see the diagram of the widget hierarchy.

Description:

The PtComboBox class provides a widget that's built from two exported subordinate widgets: PtList and PtText.

PtComboBox

A PtComboBox widget provides a text-entry area and a list of choices.

You can type in the text field or choose a predefined entry from the list. The list can be either:

Static: Always present above or below the text field.
Dropping: The user must click a button to see the list.

The widget behaves like a PtList or PtText widget, depending on which part has focus.

You can't specify the selection mode for the list; Pt_ARG_SELECTION_MODE is blocked. The list always uses Pt_BROWSE_MODE.

To select an item using the mouse, either click on an item or drag the the pointer down the list and release the mouse button when the correct item is highlighted. You can select only one item. If you drag the mouse, the list can be scrolled.

A blocking mechanism lets PtComboBox block the inheritance of certain resources from its subordinate widgets. This prevents any actions that would negatively affect the look and behavior of a PtComboBox widget. For more information, see the "Exported subordinate children" section.

Callbacks

The following callbacks are associated with the text part of the PtComboBox and are invoked as described for PtText:

The following callbacks are associated with the list part of the PtComboBox and are invoked as described for PtList:

PtComboBox also defines the following callbacks for the list:

Pt_CB_CBOX_ACTIVATE
Pt_CB_CBOX_CLOSE

New resources:

Resource	C type	Pt type	Default
Pt_ARG_CBOX_BUTTON_BORDER_WIDTH	`unsigned short`	Scalar	2
Pt_ARG_CBOX_BUTTON_BOT_BORDER_COLOR	`unsigned long`	Scalar	Pg_WHITE
Pt_ARG_CBOX_BUTTON_COLOR	`unsigned long`	Scalar	Pg_GREY
Pt_ARG_CBOX_BUTTON_TOP_BORDER_COLOR	`unsigned long`	Scalar	Pg_DGREY
Pt_ARG_CBOX_BUTTON_WIDTH	`unsigned short`	Scalar	17
Pt_ARG_CBOX_FLAGS	`unsigned long`	Flag	0
Pt_ARG_CBOX_MAX_VISIBLE_COUNT	`unsigned short`	Scalar	0
Pt_ARG_CBOX_SEL_ITEM	`unsigned short`	Scalar	0
Pt_CB_CBOX_ACTIVATE	`PtCallback_t *`	Link	NULL
Pt_CB_CBOX_CLOSE	`PtCallback_t *`	Link	NULL

Pt_ARG_CBOX_BUTTON_BORDER_WIDTH

C type	Pt type	Default
`unsigned short`	Scalar	2

The width of the drop button border.

Pt_ARG_CBOX_BUTTON_BOT_BORDER_COLOR

C type	Pt type	Default
`unsigned long`	Scalar	Pg_WHITE

The bottom border color of the drop button.

Pt_ARG_CBOX_BUTTON_COLOR

C type	Pt type	Default
`unsigned long`	Scalar	Pg_GREY

The fill color of the drop button.

Pt_ARG_CBOX_BUTTON_TOP_BORDER_COLOR

C type	Pt type	Default
`unsigned long`	Scalar	Pg_DGREY

The top border color of the drop button.

Pt_ARG_CBOX_BUTTON_WIDTH

C type	Pt type	Default
`unsigned short`	Scalar	17

The width of the drop button.

Pt_ARG_CBOX_FLAGS

C type	Pt type	Default
`unsigned long`	Flag	0

Possible values:

Pt_COMBOBOX_STATIC: Make the list field is made static and remove the drop button. If this bit is off, the list field is visible only when the drop button is pressed. Default is not set.
Pt_COMBOBOX_TOP: Place the list field above the text field. If this bit is off, the list field will be placed below the text field. Note: if there isn't enough space between the text field and the edge of the screen the list may appear on the opposite side of the text field.
Pt_COMBOBOX_OPEN (read-only): If this bit is set (1), it indicates that the list is currently open.
Pt_COMBOBOX_MAX_WIDTH: Make the combo box size itself to fit the longest list item.

Pt_ARG_CBOX_MAX_VISIBLE_COUNT

C type	Pt type	Default
`unsigned short`	Scalar	0

The maximum number of list items that may be visible before scrollbars appear. If this is 0, the entire list is displayed without scrollbars.

You can use either this resource or Pt_ARG_VISIBLE_COUNT to control the size of the list, but you shouldn't use them both.

Pt_ARG_CBOX_SEL_ITEM

C type	Pt type	Default
`unsigned short`	Scalar	0

An index into Pt_ARG_ITEMS that indicates which list item is currently selected.

Pt_CB_CBOX_ACTIVATE

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of callbacks that the widget invokes when the list is activated (i.e opened).

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_CBOX_ACTIVATE.
event: The event that caused the activation.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_CBOX_CLOSE

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of callbacks that are invoked when the user closes the combobox's list.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_CBOX_CLOSE.
event: The event that caused the closure.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

Exported subordinate children:

Unless the resources are already defined in PtComboBox, the PtComboBox class uses the resources of its exported subordinate children, PtList and PtText.

The PtComboBox class "inherits" all the resources of its exported subordinate children, with the exception of the following, which are blocked:

Pt_ARG_SELECTION_MODE (defined in PtGenList and inherited by PtList) - browse mode is always used.
Pt_ARG_SELECTION_INDEXES (defined in PtList) - PtComboBox replaces this with Pt_ARG_CBOX_SEL_ITEM because you can select only one item from the list.

Where PtComboBox and one of its exported subordinate children both define resources having the same name, the resource defined in PtComboBox takes precedence.

Inherited resources:

If PtComboBox modifies an inherited resource, the "Default override" column indicates the new value. If PtComboBox inherits a resource from one of its exported subordinate children, the default value assigned by the subordinate widget is inherited too; the "Default override" column shows this default value.

Resource	Inherited from	Default override
Pt_ARG_ACCEL_KEY	`PtLabel`	Blocked by this class.
Pt_ARG_ANCHOR_FLAGS	`PtContainer`
Pt_ARG_ANCHOR_OFFSETS	`PtContainer`
Pt_ARG_AREA	`PtWidget`
Pt_ARG_BALLOON_COLOR	`PtLabel`
Pt_ARG_BALLOON_FILL_COLOR	`PtLabel`
Pt_ARG_BALLOON_POSITION	`PtLabel`
Pt_ARG_BANDWIDTH_THRESHOLD	`PtBasic`	Not used by this class.
Pt_ARG_BALLOON_COLOR	`PtGenList`
Pt_ARG_BALLOON_FILL_COLOR	`PtGenList`
Pt_ARG_BITMAP_CURSOR	`PtWidget`
Pt_ARG_BORDER_WIDTH	`PtWidget`	2
Pt_ARG_BOT_BORDER_COLOR	`PtBasic`
Pt_ARG_COLOR	`PtBasic`
Pt_ARG_COLUMNS	`PtText`
Pt_ARG_CONTAINER_FLAGS	`PtContainer`
Pt_ARG_CURSOR_COLOR	`PtWidget`
Pt_ARG_CURSOR_POSITION	`PtText`
Pt_ARG_CURSOR_TYPE	`PtWidget`
Pt_ARG_DATA	`PtWidget`
Pt_ARG_DIM	`PtWidget`
Pt_ARG_EDIT_MASK	`PtText`
Pt_ARG_EFLAGS	`PtWidget`	Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR	`PtBasic`	Pg_TRANSPARENT
Pt_ARG_FILL_PATTERN	`PtBasic`
Pt_ARG_FLAGS	`PtWidget`	\|=Pt_HIGHLIGHTED \| Pt_SET `&=~`Pt_GETS_FOCUS
Pt_ARG_HELP_TOPIC	`PtWidget`
Pt_ARG_HIGHLIGHT_ROUNDNESS	`PtBasic`
Pt_ARG_HORIZONTAL_ALIGNMENT	`PtLabel`
Pt_ARG_ITEMS	`PtList`
Pt_ARG_LABEL_BALLOON	`PtLabel`
Pt_ARG_LABEL_DATA	`PtLabel`
Pt_ARG_LABEL_FLAGS	`PtLabel`	`&=~`Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_TYPE	`PtLabel`	Blocked by this class.
Pt_ARG_LINE_SPACING	`PtLabel`	Blocked by this class.
Pt_ARG_LIST_BALLOON	`PtList`
Pt_ARG_LIST_COLUMN_ATTR	`PtGenList`
Pt_ARG_LIST_COLUMN_POS	`PtGenList`
Pt_ARG_LIST_FLAGS	`PtGenList`
Pt_ARG_LIST_FONT	`PtGenList`
Pt_ARG_LIST_ITEM_COUNT	`PtGenList`
Pt_ARG_LIST_SB_RES	`PtGenList`
Pt_ARG_LIST_SCROLL_RATE	`PtGenList`
Pt_ARG_LIST_SEL_COUNT	`PtGenList`
Pt_ARG_LIST_SPACING	`PtList`
Pt_ARG_LIST_TOTAL_HEIGHT	`PtGenList`
Pt_ARG_MARGIN_BOTTOM	`PtLabel`
Pt_ARG_MARGIN_HEIGHT	`PtBasic`	2
Pt_ARG_MARGIN_LEFT	`PtLabel`
Pt_ARG_MARGIN_RIGHT	`PtLabel`
Pt_ARG_MARGIN_TOP	`PtLabel`
Pt_ARG_MARGIN_WIDTH	`PtBasic`	2
Pt_ARG_MAX_LENGTH	`PtText`
Pt_ARG_MODIFY_ITEMS	`PtList`
Pt_ARG_POS	`PtWidget`
Pt_ARG_RESIZE_FLAGS	`PtWidget`	Pt_RESIZE_XY_ALWAYS
Pt_ARG_SCROLLBAR_WIDTH	`PtGenList`	17
Pt_ARG_SELECTION_FILL_COLOR	`PtGenList`
Pt_ARG_SELECTION_INDEXES	`PtList`	Blocked by this class; see Pt_ARG_CBOX_SEL_ITEM
Pt_ARG_SELECTION_MODE	`PtGenList`	Blocked by this class; browse mode is always used.
Pt_ARG_SELECTION_RANGE	`PtText`
Pt_ARG_SELECTION_TEXT_COLOR	`PtGenList`
Pt_ARG_TEXT_CURSOR_WIDTH	`PtText`
Pt_ARG_TEXT_FLAGS	`PtText`
Pt_ARG_TEXT_FONT	`PtLabel`
Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR	`PtText`
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR	`PtText`
Pt_ARG_TEXT_STRING	`PtLabel`
Pt_ARG_TEXT_SUBSTRING	`PtText`
Pt_ARG_TOP_BORDER_COLOR	`PtBasic`
Pt_ARG_TOP_ITEM_POS	`PtGenList`
Pt_ARG_TRANS_PATTERN	`PtBasic`
Pt_ARG_UNDERLINE_TYPE	`PtLabel`	Blocked by this class.
Pt_ARG_UNDERLINE1	`PtLabel`	Blocked by this class.
Pt_ARG_UNDERLINE2	`PtLabel`	Blocked by this class.
Pt_ARG_USER_DATA	`PtWidget`
Pt_ARG_VERTICAL_ALIGNMENT	`PtLabel`
Pt_ARG_VISIBLE_COUNT	`PtGenList`	See below.
Pt_CB_ACTIVATE	`PtBasic`	Behaves as for `PtText`.
Pt_CB_ARM	`PtBasic`
Pt_CB_BALLOONS	`PtContainer`
Pt_CB_BLOCKED	`PtWidget`
Pt_CB_DESTROYED	`PtWidget`
Pt_CB_DISARM	`PtBasic`
Pt_CB_FILTER	`PtContainer`
Pt_CB_GOT_FOCUS	`PtBasic`
Pt_CB_HOTKEY	`PtWidget`
Pt_CB_LIST_INPUT	`PtList`
Pt_CB_LOST_FOCUS	`PtBasic`
Pt_CB_MENU	`PtBasic`
Pt_CB_MODIFY_NOTIFY	`PtText`
Pt_CB_MODIFY_VERIFY	`PtText`
Pt_CB_MOTION_NOTIFY	`PtText`
Pt_CB_MOTION_VERIFY	`PtText`
Pt_CB_RAW	`PtWidget`
Pt_CB_REALIZED	`PtWidget`
Pt_CB_REPEAT	`PtBasic`
Pt_CB_RESIZE	`PtContainer`
Pt_CB_SCROLL_MOVE	`PtGenList`
Pt_CB_SELECTION	`PtList`
Pt_CB_TEXT_CHANGED	`PtText`
Pt_CB_UNREALIZED	`PtWidget`

Pt_ARG_VISIBLE_COUNT: Set this resource to a nonzero value to resize the list to a multiple of the item height. If the number of items is less than this resource, blank items are displayed at the end of the list; if the number of items is greater than this resource, a scrollbar is displayed.
You can use either this resource or Pt_ARG_CBOX_MAX_VISIBLE_COUNT to control the size of the list, but you shouldn't use them both.

Convenience functions:

The PtComboBox widget and its exported subordinate PtList and PtText children define various convenience functions that make it easier to use the combo box once it's been created. Here's a brief overview:

PtComboBoxListOpen(): Open a combobox list.
PtComboBoxListClose(): Close an open combobox list.
PtListAddItems(): Adds one or more items to the list at a specified position.
PtListDeleteAllItems(): Removes all the items from the list.
PtListDeleteItems(): Deletes items in the list by name.
PtListDeleteItemPos(): Deletes a range of items by position.
PtListItemExists(): Determines whether or not an item exists within the list.
PtListItemPos(): Determines the position of an item within the list.
PtListRemovePositions(): Deletes items at specified positions.
PtListReplaceItemPos(): Replaces items by position number.
PtListReplaceItems(): Replaces items by item text.
PtTextGetSelection(): Gets the selected range from a PtText widget.
PtTextModifyText(): Modifies the contents of a PtText widget.
PtTextSetSelection(): Sets the selected range for a PtText widget.

QNX Community Resources