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.

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:

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

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:

Pt_ARG_CBOX_BUTTON_BORDER_WIDTH

The width of the drop button border.

Pt_ARG_CBOX_BUTTON_BOT_BORDER_COLOR

The bottom border color of the drop button.

Pt_ARG_CBOX_BUTTON_COLOR

The fill color of the drop button.

Pt_ARG_CBOX_BUTTON_TOP_BORDER_COLOR

The top border color of the drop button.

Pt_ARG_CBOX_BUTTON_WIDTH

The width of the drop button.

Pt_ARG_CBOX_FLAGS

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

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

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

Pt_CB_CBOX_ACTIVATE

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

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.

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.