---

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.

PhAB icon:

Public header:

<photon/PtComboBox.h>

Description:

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

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.

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:

• Pt_CB_ACTIVATE
• Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED
• Pt_CB_MODIFY_VERIFY
• Pt_CB_MOTION_NOTIFY
• Pt_CB_MOTION_VERIFY

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

• Pt_CB_LIST_INPUT
• Pt_CB_SELECTION

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_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_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	17

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:

• 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	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.

---