ScrollingList(3W)
NAME
ScrollingList − scrolling list widget
SYNOPSIS
#include <Xol/OpenLook.h>
#include <Xol/ScrollingL.h>
. . .
ANCESTRY
Core-Composite-Constraint-Manager-ScrolledWindow
DESCRIPTION
The ScrollingList widget provides a list of items that the user can scroll through and choose. The application can make the choice of items exclusive, or allow the user to make mulitple choices. It can also enable the user to edit items within the list.
Components
Each ScrollingList widget has the following parts:
• border
• current item
• current item border
• items
• scrollbar
• view
If the application allows the list to be edited in place (in the view), the ScrollingList widget uses the following component:
• editable text field
Figure 1 Scrolling List Components
Editable ScrollingList
The application can choose whether to allow the end user to edit the items in a scrolling list. The editable text field is the interface for entering the new item, and is described later. Other aspects of the user interface for editing are controlled by the application. For example, the application can attach a menu to the scrolling list to allow the end user to select where a new item is to be inserted, and can employ pop-up windows to gather additional information about a new item.
Figure 2 Editable Scrolling List Additional Components
Subwidgets
The ScrollingList contains one subwidget, a TextField provided automatically, and accessible through the XtNtextfield resource.
Figure 3 ScrollingList Subwidgets
ScrollingList
|
|
TextField
(XtNtextField)
Editable TextField
The application can request that the ScrollingList widget manage part of the visual aspect of changing an existing item in the view. The TextField subwidget implements this editable text field. The ScrollingList widget manages the TextField widget as follows:
Opening/closing – The application asks the ScrollingList widget to "open" and "close" the editable text field. Opening the editable text field widget maps it and positions it so that, as the end user types in the name of a new or changed item, the name lines up with the existing item names. Closing the editable text field widget unmaps it. (As described below, there may be times when the widget is unmapped yet still open.)
Editing – If an existing item is being edited, the application requests the editable text field to overlay the item.
Insertion – If a new item is being inserted, the application requests items to be scrolled down in the view to accommodate the editable text field.
Mapping – The ScrollingList widget maps and unmaps the editable text field widget; the application does not.
Scrolling – If the end user scrolls the list while the editable text field is still open, the ScrollingList widget scrolls it with the rest of the items. If it has to be scrolled out of the view, it is scrolled out entirely, causing it to be unmapped but not closed. The application should not try to remap the child since it will be remapped when the list is scrolled back again.
Setting/selecting – If the end user attempts to make a selection or set a current item, the editable text field is automatically closed.
The application is responsible for handling the verification callbacks of the editable text field and for telling the ScrollingList widget to add a new item or change an existing item as a result of the user input.
Selectable Scrolling List
The application can choose whether to allow the end user to select items from a scrolling list. If items can be selected, they can be copied elsewhere as text, and may be deletable ("cut").
Deleting Selected Items
The end user can delete selected items. The ScrollingList widget provides some deletion capabilities through the selection mechanisms (see the discussion under "Selecting and Operating on the Items" below), and the application can provide other capabilities, such as with a pop-up menu choice. The application verifies that each selected item can be deleted; it is responsible for providing feedback to the end user for any items it will not delete. The ScrollingList widget updates the view to remove any deleted items.
Virtual List
The ScrollingList widget "virtualizes" the list to allow the application to use list data structures best suited to its needs. The ScrollingList widget provides routines the application uses to build and maintain a version of the list for the ScrollingList widget to use. With these routines, the application:
– adds new items to the list;
– deletes items from the list;
– marks items as changed;
– shifts the view to show a particular item;
– and opens and closes the editable text field for a new or changed item.
The application is responsible for defining callbacks that the ScrollingList widgets invoke when the end user attempts to change a Current item, or cuts items from the list. Each item is identified by the item name that is shown in the view for the end user, a token assigned by the ScrollingList widget that uniquely identifies the item, and an attributes bit-vector that identifies if the item is a current item.
Item Order
The list is assumed to have an order defined by the application. As it adds items, the application tells the ScrollingList widget where to insert them: either before an item already in the list or at the end of the list.
The application may change the content of a list at any time, including while it is displayed. The widget updates the view, if necessary, to reflect the changed list. To avoid unnecessary updates to the view when several changes need to be made, the application can instruct the ScrollingList widget to avoid updates until the changes are finished.
Setting Current Item
The end user can make one or more of the items a current item, as determined by the application, by:
– pressing SELECT over it,
– or moving the input focus inside the border and typing the first letter of the item’s name.
Either of these actions causes a callback to the application, which can decide if the item should be made a current item, remain a current item, or be changed to a regular item, depending on the current state of the item and the needs of the application. Thus, the application can make the scrolling list behave as a set of exclusive or nonexclusive items.
Pressing SELECT also starts a selection, as described below.
Selecting Items
The ScrollingList widget allows selection operations on the items. Items that are moved or copied from the view are treated as a newline-separated list of text items, in the order they appear in the scrolling list, with no leading or trailing blanks on any item.
Selecting a single item
Clicking SELECT on an item selects it and deselects any other active selection on the screen.
Selecting other items
Clicking ADJUST on an item toggles its state, making an unselected item selected and a selected item unselected.
Wipe-through selection, with SELECT
Pressing and dragging SELECT over items selects them and deselects any other active selection on the screen. The selection starts with the item where SELECT is pressed and extends to the item where SELECT is released. If the pointer moves above or below the view, the view scrolls additional items into the view, selecting them as well. The rate at which items scroll into the view is the same as when pressing SELECT on the up or down arrows of the Scrollbar. The pointer can move out of the view to the left or right without interrupting the selection.
Wipe-through selection, with ADJUST"
Pressing and dragging ADJUST marks the bounds of a selection the same way as pressing and dragging SELECT, except that the items covered are "toggled". (Previously selected items are deselected and previously unselected items are selected.)
Copying items
Pressing COPY copies any selected items to the clipboard and deselects them.
Cutting items
Pressing CUT moves any selected items to the clipboard and deletes them from the list. This operation is allowed only if the scrolling list is editable.
Coloration
On a monochrome display, the ScrollingList widget indicates that it has input focus by inverting foreground and background colors. When an editable Text Field has input focus, it shows that it has input focus by showing an active caret.
On color displays, the ScrollingList widget shows that the current item has input focus by filling the background of the current item with the input focus color set in the XtNinputFocusColor resource. When a selected item has input focus, the label is drawn with the input focus color. When an item is both selected and current, it shows that it has input focus by drawing the text of the label in the input focus color. When an editable TextField has input focus, it shows that it has input focus by showing an active caret in the input focus color.
EXCEPTIONS:
If the input focus color is the same as either the background, foreground, or font color, then revert to the monochrome coloration scheme. The Scrollbar subwidgets inherit their and colors from the ScrollingList parent at initialization time. If the colors are subsequently changed in the parent, the subwidgets’ colors ahange also.
the coloration of the ScrollingList widget.
Figure 4 ScrollingList Coloration
Figure 5 Selected Item and Unselected Item Coloration
Keyboard Traversal
The default value of the XtNtraversalOn resource is True.
The ScrollingList widget responds to the following keyboard navigation keys:
—NEXT_FIELD moves to the next traversable widget in the window
—PREV_FIELD moves to the previous traversable widget in the window
—NEXTWINDOW moves to the next window in the application
—PREVWINDOW moves to the previous window in the application
—NEXTAPP moves to the first window in the next application
—PREVAPP moves to the first window in the previous application
—MOVEUP moves the input focus up one line
—MOVEDOWN moves the input focus down one line
—PANESTART moves the input focus to the first item in the pane
—PANEEND moves the input focus to the last item in the pane
—SCROLLUP scrolls up one item in the list
—SCROLLDOWN scrolls down one item in the list
—SCROLLTOP scrolls to the first item in the list
—SCROLLBOTTOM scrolls to the last item in the list
—PAGEUP scrolls up one page so that the first item visible is the last item visible in the pane
—PAGEDOWN scrolls down one page so that the last item visible is the first item visible in the pane
When an Editable Text Field is in the ScrollingList, the keyboard traversal keys defined for TextField widgets apply.
The SELECTKEY selects the Current Item and unselects any other active selection on the screen. The ADJUSTKEY toggles the Current Item’s state, making an unselected Item selected and a selected Item unselected.
Note that the scrolling keys of interest are defined with in the ScrollingList and traversal to the Scrollbar is not necessary to manipulate the ScrollingList.
Scrolling List Activation Types
Activation Type: Expected Results:
OL_MENUKEY Scrolling List menu if one was created by application
Keyboard Mnemonic Display
The ScrollingList widget displays the mnemonic accelerator for each item as part of its label. If the mnemonic character is in the label, then that character is displayed/highlighted according to the value returned by OlQueryMnemonicDisplay(). If the mnemonic character is not in the label, it is displayed to the right of the label in parentheses and highlighted according to the value returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parentheses is truncated as a unit.
RESOURCES
Table 1 ScrollingList Resource Set
Name Type Default Access
XtNancestorSensitive- Boolean TRUE G
XtNapplAddItem OlApplAddItemProc NULL G
XtNapplDeleteItem OlApplDeleteItemProc NULL G
XtNapplEditClose OlApplEditCloseProc NULL G
XtNapplEditOpen OlApplEditOpenProc NULL G
XtNapplTouchItem OlApplTouchItemProc NULL G
XtNapplUpdateView OlApplUpdateViewProc NULL G
XtNapplViewItem OlApplViewItemProc NULL G
XtNbackground- Pixel XtDefaultBackground SGI
XtNbackgroundPixmap- Pixmap (n/a) SGI
XtNborderColor- Pixel XtDefaultForeground SGI
XtNborderPixmap- Pixmap (n/a) SGI
XtNconsumeEvent- XtCallbackList NULL SGIO
XtNdepth- int (parent’s) GI
XtNdestroyCallback- XtCallbackList NULL SI
XtNfont XFontStruct∗ (OPEN LOOK font) SI
XtNfontColor Pixel XtDefaultForeground SGI
XtNforeground- Pixel XtDefaultForeground SGI
XtNheight- Dimension (calculated) SGI
XtNinputFocusColor- Pixel Black SGI
XtNlistPane Widget (none) G
XtNmappedWhenManaged- Boolean TRUE SGI
XtNprefMaxWidth Dimension 0 SGI
XtNprefMinWidth Dimension 0 SGI
XtNrecomputeWidth Boolean TRUE SGI
XtNreferenceName- String NULL GI
XtNreferenceWidget- Widget NULL SGI
XtNselectable Boolean TRUE SGI
XtNsensitive- Boolean TRUE GIO
XtNtextField Widget (none) G
XtNtraversalOn Boolean TRUE SGI
XtNuserData- XtPointer NULL SGI
XtNuserDeleteItems XtCallbackList NULL SI
XtNuserMakeCurrent XtCallbackList NULL SI
XtNviewHeight Dimension (none) SI
XtNwidth- Dimension (calculated) SGI
XtNx- Position 0 SGI
XtNy- Position 0 SGI
Access: S = XtSetValues G = XtGetValues
I = init time O = other access
† see resources(3W)
OlListItem Structure
Several of the resources defined below use the following OlListItem structure:
typedef struct _OlListItem {
OlDefine label_type;
XtPointer label;
XImage ∗glyph;
OlBitMask attr;
XtPointer user_data;
unsigned char mnemonic;
} OlListItem;
label_type – identifies the type of label to display for the Item in the view. It can have one of the values:
OL_STRING for a text label;
OL_IMAGE for an image label.
Note: Only text labels are supported in this version of the ScrollingList widget, so the only value allowed is OL_STRING. Any other legal values generate an error message that tells the application programmer that the value is not yet supported. Any illegal values generate a different error message.
label – is what to display for the Item in the view. The type of the value of this member depends on the value of the label_type member:
OL_STRING for a String
OL_IMAGE for a XImage∗
glyph – is currently unused.
attr – defines attributes of the Item. It is a 32-bit vector with the field:
OL_LIST_ATTR_APPL available for application use. This field consists of the low-order 16 bits, to be used as the application sees fit.
OL_LIST_ATTR_CURRENT if the Item is a current item.
Other bit values are defined but should not be used by the application.
mnemonic – is a single character that is used as a mnemonic accelerator for keyboard traversal.
OlListToken Structure
The ScrollingList widget identifies each item with a "token" of type OlListToken. The ScrollingList widget assigns the token when an item is added by the application, and the application uses the token in later references to the item. A zero value is allowed in some contexts where an OlListToken is expected, as a way to refer to no item.
As a convenience to the application, the macro OlListItemPointer(token) converts an OlListToken value into a pointer to the corresponding OlListItem. The application can change the values of the OlListItem members, but should let the ScrollingList widget know that they have changed, using the XtNapplTouchItem routine. No checking is done for incorrect OlListToken arguments to the OlListItemPointer macro.
The OlListToken value can be coerced into the type caddr_t and back without loss of precision.
XtNapplAddItem
class:XtCApplAddItemtype:OlApplAddItemProcdefault:NULLNULL’u’access:GG’u’
Action: points to the routine the application should use when it adds a new item to the list.
OlApplAddItemProc is defined as:
typedef OlListToken (∗OlApplAddItemProc)(Widget widget,
OlListToken parent,
OlListToken reference,
OlListItem item);
Synopsis:
OlApplAddItemProc applAddItem;
OlListToken parent, reference, token;
Widget widget;
OlListItem item;
XtVaGetValues(widget, XtNapplAddItem, &applAddItem, NULL);
token = (∗applAddItem)(widget, parent, reference, item);
widget – identifies the ScrollingList widget instance.
parent – should be set to 0, for compatibility with future changes.
reference – identifies an item before which to insert the new item. This value can be zero to append the new item to the list.
item – describes the new item.
The content of the OlListItem structure is copied by the ScrollingList widget into space that it maintains; however, the data pointed to by the label and glyph members are not copied. The application can access the copied data directly, using the OlListItemPointer() macro to get a pointer to the OlListItem structure for the item.
If it changes the data, the application should use the XtNapplTouchItem routine to let the ScrollingList widget know the data has changed.
If mapped and if allowed by the application (see XtNapplUpdateView ), the ScrollingList widget updates the view if the new item will be in the view. The view is changed as little as possible: if the new item is in the upper half of the view, the items above it are scrolled up and the top item is scrolled off; if the new item is in the lower half of the view, the items below it are scrolled down and the bottom item is scrolled off.
This routine is also used to build the item list from scratch.
XtNapplDeleteItem
class:XtCApplDeleteItemtype:OlApplDeleteItemProcdefault:NULLNULL’u’access:GG’u’
Action: points to the routine the application should call when it deletes an item from the list.
OlApplDeleteItemProc is defined as:
typedef void (∗OlApplDeleteItemProc)(Widget widget,
OlListToken token);
Synopsis:
OlApplDeleteItemProc applDeleteItem;
OlListToken token;
Widget widget;
XtVaGetValues(widget, XtNapplDeleteItem, &applDeleteItem, NULL);
widget – identifies the ScrollingList widget instance.
token – identifies the deleted item.
If mapped and if allowed by the application (see XtNapplUpdateView ), the ScrollingList widget updates the view if the deleted item was visible.
The view is changed as little as possible:
If the deleted item was in the upper half of the view, items above it are scrolled down and an item is scrolled in from the top;
If the deleted item was in the lower half of the view, items below it are scrolled up and an item is scrolled in from the bottom.
If the view is already at the top or bottom, the additional item is scrolled in from the other end, if possible.
XtNapplEditClose
class:XtCApplEditClosetype:OlApplEditCloseProcdefault:NULLNULL’u’access:GG’u’
Action: points to to the routine the application should call when the user has finished editing an item in the view.
OlApplEditCloseProc is defined as:
typedef void (∗OlApplEditCloseProc)(Widget widget);
Synopsis:
OlApplEditCloseProc applEditCloseProc;
Widget widget;
XtVaGetValues(widget, XtNapplEditCloseProc, &applEditCloseProc, NULL);
widget – identifies the ScrollingList widget instance.
When this routine is called, the ScrollingList widget unmaps the editable text field widget, scrolling up the items below it if they had been scrolled down to allow an insert.
The application is responsible for calling the XtNapplAddItem routine to add the new item, or calling the XtNapplTouchItem routine to mark the item as changed.
To avoid unnecessary updates to the view, the application should add the new item ( XtNapplAddItem) or mark the changed item ( XtNapplTouchItem) before closing the editable text field. A later call to the XtNapplEditClose routine without an intervening call to the XtNapplEditOpen routine is ignored.
If mapped, the ScrollingList widget updates the view, even if the application had halted updates (see XtNapplUpdateView ). If the application had halted updates, they will continue to be halted afterwards.
XtNapplEditOpen
class:XtCApplEditClosetype:OlApplEditOpenProcdefault:NULLNULL’u’access:GG’u’
Action: points to the routine the application should use when it wants to allow the end user to insert a new item or change an existing item in the view.
OlApplEditOpenProc is defined as:
typedef void (∗OlApplEditOpenProc)(Widget widget,
Boolean insert,
OlListToken reference);
Synopsis:
OlApplEditOpenProc ApplEditOpenProc;
Widget widget;
Boolean insert;
Widget reference;
XtVaGetValues(widget, XtNapplEditOpenProc, &applEditOpenProc, NULL);
widget – identifies the ScrollingList widget instance.
insert – tells whether items should be scrolled down to make room for inserting a new item. A value of FALSE implies that an item is being edited in place and no items are to be scrolled.
reference – identifies an item before which a new item is to be inserted ( insert is TRUE) or identifies the item that is being changed ( insert is FALSE ). If insert is TRUE, this value can be zero to append a new item at the end of the list. If insert is FALSE, this value must refer to an existing item. The referenced item does not have to be in the view (see below).
If a new item is being inserted, the ScrollingList widget makes room for the editable text field by scrolling down the referenced item and any items below it. If the referenced item is not in the view, it is automatically made visible just as if the application had called the XtNapplViewItem routine first. The XtNapplEditOpen routine can be called again before an intervening call to the XtNapplEditClose routine. The effect is as if the XtNapplEditClose routine was called, but without multiple updates to the view. For example, this allows the application to let the end user insert several new items in succession: the editable text field moves down as each item is inserted, but is never removed from the view.
If mapped, the ScrollingList widget updates the view, even if the application had halted updates (see XtNapplUpdateView ). If the application had halted updates, they will continue to be halted afterwards.
XtNapplTouchItem
class:XtCApplTouchItemtype:OlApplTouchItemProcdefault:NULLNULL’u’access:GG’u’
Action: points to the routine the application should use when it changes an item in the list.
OlApplTouchItemProc is defined as:
typedef void (∗OlApplTouchItemProc)(Widget widget,
OlListToken token);
Synopsis:
OlApplTouchItemProc applTouchItemProc;
Widget widget;
OlListToken token;
XtVaGetValues(widget, XtNapplTouchItemProc, &applTouchItemProc, NULL);
widget – identifies the ScrollingList widget instance.
token – identifies the item that has changed.
If mapped and if allowed by the application (see XtNapplUpdateView ), the ScrollingList widget updates the view if the changed item is visible.
XtNapplUpdateView
class:XtCApplUpdateViewtype:OlApplUpdateViewProcdefault:NULLNULL’u’access:GG’u’
Action: points to a routine the application can call to keep the ScrollingList widget from updating the view, or to let it again update the view. OlApplUpdateViewProc is defined as:
typedef void (∗OlApplUpdateViewProc)(Widget widget,
Boolean ok);
Synopsis:
OlApplUpdateViewProc applUpdateViewProc;
Widget widget;
Boolean tok;
XtVaGetValues(widget, XtNapplUpdateViewProc, &applUpdateViewProc, NULL);
ok– is either TRUE or FALSE, depending on whether the ScrollingList can update the View as it changes, or not, respectively.
From the time the XtNapplUpdateView routine is called with a FALSE argument until it is called with a TRUE argument, the ScrollingList does not update the view in response to application-made changes, unless:
– the application opens or closes the editable text field (see XtNapplEditOpen and XtNapplEditClose );
– the end user manipulates the list by scrolling it, selecting an item, cutting, etc.
The ScrollingList widget updates the view once for each of these exceptions, each time an exception occurs. An application should use this routine to bracket a set of changes to avoid spurious changes to the view. This routine is not needed if only one change is made to the list. The following example illustrates the use of the XtNapplUpdateView routine.
/∗
∗ Stop view updates.
∗/
(∗applUpdateView)(widget, FALSE);
/∗
∗ Make some changes.
∗/
(∗applDeleteItem)(widget, ...);
(∗applDeleteItem)(widget, ...);
(∗applDeleteItem)(widget, ...);
(∗applAddItem)(widget, ...);
(∗applTouchItem)(widget, ...);
/∗
∗ Allow the view to be updated again.
∗/
(∗applUpdateView)(widget, TRUE);
XtNapplViewItem
class:XtCApplViewItemtype:OlApplViewItemProcdefault:NULLNULL’u’access:GG’u’
Action: points to a routine the application can call when it wants a particular item placed in the view.
OlApplViewItemProc is defined as:
typedef void (∗OlApplViewItemProc)(Widget widget,
OlListToken token);
Synopsis:
OlApplViewItemProc applViewItemProc;
Widget widget;
OlListToken token;
XtVaGetValues(widget, XtNapplViewItemProc, &applViewItemProc, NULL);
widget – identifies the ScrollingList widget instance.
token – identifies the item to move into the view.
The item is moved into the view in a way that minimizes the change to the view. If the item is currently in the view, nothing is changed. If scrolling the list up or down brings the item into the view while keeping at least one previously viewed item in the view, the list is scrolled. Otherwise, the item is placed at the top of the view, or as close to the top as possible if there aren’t enough items in the current Level to fill the view below it. If mapped and if allowed by the application (see XtNapplUpdateView ), the ScrollingList widget updates the view.
XtNfont
class:XtCFonttype:XFontStruct∗default:(OPEN LOOK font)(OPEN LOOK font)’u’access:SISI’u’
Action: identifies the font to be used to display the label Values: any valid return from XLoadQueryFont()
Default: the font specified by the XtNolDefaultFont application resource.
Note: The default value points to a cached font structure. An application should not expect to get this value with a call to XtGetValues() and use it reliably thereafter.
XtNfontColor
class:XtCFontColortype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’
Action: specifies the font color.
Values: any pixel value valid for the current display, or
any name from the rgb.txt file
is used for the font.
XtNforeground
class:XtCForegroundtype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’
Action: specifies the foreground color.
XtNlistPane
class:XtCReadOnlytype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: returns the ListPane child of the ScrollingList.
XtNprefMaxWidth
class:XtCPrefMaxWidthtype:Dimensiondefault:00’u’access:SGISGI’u’
XtNprefMinWidth
class:XtCPrefMinWidthtype:Dimensiondefault:00’u’access:SGISGI’u’
Action: controls dynamic resizing.
Values: 0 ≤ XtNprefMaxWidth
0 ≤ XtNprefMinWidth
If the value of these resources is specified as zero, then the static sizing behavior is preserved (which is the default). However, if these are specified as non-zero, then the width of the ScrollingList will be no less than XtNprefMinWidth and no greater than XtNprefMaxWidth, regardless of the length of the items inside. Items which are longer than the XtNprefMaxWidth, will automatically be marked with a caret, indicating that they are not completely visible.
If the programmer wishes to set the List to a single width, then XtNprefMinWidth should equal XtNprefMaxWidth, thus forcing the ScrollingList width to a particular size.
XtNrecomputeWidth
class:XtCRecomputeWidthtype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: controls how the ScrollingList widget should respond to requests to resize itself.
Values: TRUE – the ScrollingList shrinks the view of the content in the corresponding direction to absorb the change in the ScrollingList widget’s size. FALSE – the ScrollingList does not shrink the view in that direction.
This resource, together with the XtNviewWidth and XtNviewHeight resources, are typically used to set a preferred dimension in a direction that should not be scrolled.
XtNselectable
class:XtCSelectabletype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: controls whether the end user can select items in the scrolling list.
Values: TRUE – items can be selected with SELECT and ADJUST and copied with the COPY key. Items may be deleted with the CUT key, although the application can stop some or all selected items from being deleted. FALSE – items cannot be selected and the COPY and CUT keys have no effect.
XtNtextField
class:XtCTextFieldtype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: widget ID of the TextField class editable text field widget
This value is available once the ScrollingList widget has been created. The ScrollingList widget resets the following values before returning from each invocation of the XtNapplEditOpen routine:
Table 2 Editable Text Field Reset Values
Editable TextField Reset Values
Name Class Value
XtNwidth XtCWidth width available in View
XtNstring XtCString name of Item to be changed
XtNtraversalOn
class:XtCTraversalOntype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: specifies whether or not this widget is selectable during traversal.
Values: TRUE, FALSE
XtNuserDeleteItems
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’
Action: defines the callbacks issued when the end user tries to delete items from the list.
Currently, the only way the ScrollingList widget handles deletions is through a cut operation.
The call_data parameter points to a structure OlListDelete that looks like:
typedef struct _OlListDelete {
OlListToken ∗tokens
Cardinal num_tokens;
} OlListDelete;
tokens – is a list identifying the items to be deleted. The application is expected to act on each item separately, calling the XtNapplDeleteItem routine to delete each from the list. The application may refuse to delete some or all of the items, and is responsible for providing any feedback to the end-user.
num_tokens – is the number of items to delete.
XtNuserMakeCurrent
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’
Action: defines the callbacks issued when the end user presses SELECT over an item.
The call_data parameter is the OlListToken value that identifies the item. The application is expected to decide if the current item status of this item should change. The attributes member of the OlListItem structure for this item is not automatically changed by the ScrollingList widget.
XtNviewHeight
class:XtCViewHeighttype:Dimensiondefault:(none)(none)’u’access:SISI’u’
Action: gives the preferred height of the view as the number of items to show.
Values: 0 ≤ XtNviewHeight
If a nonzero value is given, the corresponding XtNheight resource is computed by converting this number to pixels and adding any padding or border thickness. In this case, any value given in the XtNheight resource is overwritten. If a zero value is given in the XtNviewHeight resource, the XtNheight resource is used as an estimate. The view is sized to show an integral number of items, such that the overall height of the ScrollingList widget is less than or equal to XtNheight, if possible. However, the view is always large enough to show at least one item, and is no shorter than the minimum scroll bar size. If neither the XtNviewHeight resource nor the XtNheight resource is set, or both are set to zero, the view is made as small as possible, limited as described above.
Version 3.0.1 — Last change: June 92