PtComboBox

A text field with a list of choices

Class hierarchy:

PtWidgetPtBasicPtContainerPtCompoundPtComboBox

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

PhAB icon:

PtComboBox button in PhAB

Public header:

<photon/PtComboBox.h>

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
You must click a button to see the list.

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


Note: 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 pointer, either click on an item or drag the pointer down the list and release the button when the correct item is highlighted. You can select only one item. If you drag the pointer, the list can scroll.

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.

Keyboard actions

The keyboard actions depend on which part of the PtComboBox has focus. If the text widget has focus, the keyboard actions are:

Key Action
Set the text to the previous item in the list
Set the text to the next item in the list
Alt- Display the list, highlighting the item corresponding to the current text

The Alt- action occurs only if Pt_COMBOBOX_ALT_DOWN is set in the widget's Pt_ARG_CBOX_FLAGS.

If the list has focus, the keyboard actions are:

Key Action
Enter Select the current item (see Current item in the description of PtGenList)
Move to the previous item
Move to the next item
Pg Up Move to the previous page
Pg Dn Move to the next page
Home Move to the first item
End Move to the last item

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:

New resources:

Resource C type Pt type Default
Pt_ARG_CBOX_BUTTON_WIDTH unsigned short Scalar 13
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_ARG_CBOX_TEXT_FILL_COLOR unsigned long Scalar Pg_LGRAY
Pt_CB_CBOX_ACTIVATE PtCallback_t * Link NULL
Pt_CB_CBOX_CLOSE PtCallback_t * Link NULL

Pt_ARG_CBOX_BUTTON_WIDTH

C type Pt type Default
unsigned short Scalar 13

The width of the drop button, in pixels.

Pt_ARG_CBOX_FLAGS

C type Pt type Default
unsigned long Flag 0

Possible values:

Pt_COMBOBOX_ALT_DOWN
Enable the Alt- keychord, which displays the list and highlights the item corresponding to the current text.
Pt_COMBOBOX_MAX_WIDTH
Make the combo box size itself to fit the longest list item.
Pt_COMBOBOX_OPEN (read-only)
If this bit is set, the list is currently open.
Pt_COMBOBOX_STATIC
Make the list field static and remove the drop button. If this bit is off, the list field is visible only when the drop button is pressed.
Pt_COMBOBOX_TOP
Place the list field above the text field. If this bit is off, the list field is placed below the text field. 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_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_ARG_CBOX_TEXT_FILL_COLOR

C type Pt type Default
unsigned long Scalar Pg_LGRAY

The fill color of the text area.

Pt_CB_CBOX_ACTIVATE

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.
cbdata
NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_CBOX_CLOSE

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked when you close 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
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.
cbdata
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:

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 PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
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_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget 2
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_COLUMNS PtText
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_POSITION PtText
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EDIT_MASK PtText
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
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_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_ITEMS PtList
Pt_ARG_LABEL_BALLOON PtLabel
Pt_ARG_LABEL_FLAGS PtLabel &=~Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_IMAGE PtLabel
Pt_ARG_LABEL_TYPE PtLabel Blocked by this class.
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
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_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_MODIFY_ITEMS PtList
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_ALWAYS
Pt_ARG_ROW_LAYOUT_DATA PtWidget
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_STYLE PtBasic
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_IMAGE_SPACING PtLabel
Pt_ARG_TEXT_STRING PtLabel
Pt_ARG_TEXT_SUBSTRING PtText
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
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_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic Behaves as for PtText.
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED 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_OUTBOUND PtWidget
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.