MYTUI

CONTENT

 

1.1. Introduction 1

1.1.1. Look & Feel 2

1.1.2. Key Bindings 2

1.1.3. Callbacks 3

1.2. Attributes 3

1.2.1. List Box Name 3

1.2.2. Selection Mode 4

1.2.3. Selection Indicator 4

1.2.4. Prefix Characters 4

1.2.5. Position 4

1.2.6. Dimensions (Lines, Cols) 4

1.2.7. Box Mode 4

1.2.8. Box Attribute 5

1.2.9. Items 5

1.2.10. Item Attribute (Normal) 5

1.2.11. Item Attribute (Focus) 5

1.2.12. Hide Flag 5

1.2.13. Edit Flag 6

1.2.14. Callback Functions 6

1.2.15. Shared Object Name 6

1.3. Methods (in alphabetic order) 6

1.3.1. MYLISTBOXaddItem: Add an item to the list box 6

1.3.2. MYLISTBOXgetItem: get the specified item and its selection status 7

1.3.3. MYLISTBOXgetItemNumber: return the number of items 7

1.3.4. MYLISTBOXgetSelectSet: get the subset of selected items 7

1.3.5. MYLISTBOXregPostProcess: register the postprocess function 7

1.3.6. MYLISTBOXregPreProcess: register the preprocess function 8

1.3.7. MYLISTBOXregSelectCallback: register the select callback 8

1.3.8. MYLISTBOXremoveAll: delete all items from the list box 8

1.3.9. MYLISTBOXremoveItem: remove an item from the list box 8

1.3.10. MYLISTBOXsetAttrib: set display attribute for the items 9

1.3.11. MYLISTBOXsetBoxAttrib: set display attribute for the box 9

1.3.12. MYLISTBOXsetBoxMode: set the list box¡¯s box mode 9

1.3.13. MYLISTBOXsetBracketChar: set prefix characters ans selection indicator 10

1.3.14. MYLISTBOXsetDisplayOnly: set the list box read-only 10

1.3.15. MYLISTBOXsetEditable: set the line editor editable 10

1.3.16. MYLISTBOXsetInvisible: hide the list box from the form 11

1.3.17. MYLISTBOXsetItemSelect: set the item to be selected 11

1.3.18. MYLISTBOXsetItemUnselect: set the item to be unselected 11

1.3.19. MYLISTBOXsetMultiSelect: set the list box into multi-selection mode 12

1.3.20. MYLISTBOXsetPosSize: set position and size for the list box 12

1.3.21. MYLISTBOXsetSingleSelect: set the list box into single selection mode 12

1.3.22. MYLISTBOXsetVisible: make the list box visible 13

 

1.1. Introduction

The List Box provides a list of selectable, read-only items. It is a single-column list, items can be scrolled in both vertical and horizontal directions.

Depends on the Selection Mode, you can control how the items are selected with method MYLISTBOXsetMultiSelect() or MYLISTBOXsetSingleSelect(). For single selection mode, there must be one and only one item is selected at one time, for multi-selection mode, either no item or at least one item may be selected.

Each item is prefixed with two Prefix Charaters (left/right prefix character, ¡®[]¡¯ by default) and a Selection Indicator character that displayed between the two prefix characters. If the item is selected, then it is indicated with the indicator character, otherwise a space character is displayed. You can change the prefix characters and the indicator with MYLISTBOXsetBracketChar().

A line editor can have a box around it by setting the Box Mode with MYLISTBOXsetBoxMode(). By default the box is turned on. You can also select a display attribute for the box with MYLISTBOXsetBoxAttrib().

You can change the Edit Flag with MYLISTBOXsetDisplayOnly() to turn the list box into a read-only widget, or make it active again with MYLISTBOXsetEditable().

By changing the Hide Flag with MYLISTBOXsetInvisible() or MYLISTBOXsetVisible(), it can be hidden from or redisplayed on the form window.

Items can be appended to the list box with MYLISTBOXaddItem(), and you can delete a item with MYLISTBOXremoveItem(), or clear the list box with MYLISTBOXremoveAll(). The display attribute for items can be set with MYLISTBOXsetAttrib().

An item can be set selected with MYLISTBOXsetItemSelect(), or unselected with MYLISTBOXsetItemUnselect(). For multi-selection mode, you can know which items are selected with MYLISTBOXgetSelectSet().

1.1.1. Look & Feel

Here are two typical list boxes:

 

The left one is a single selection list box which the selection indication is ¡®#¡¯, the right one is a multi selection list box, where the indicator is ¡®*¡¯. Both lists can be scrolled vertically since the items number is greater than the height.

1.1.2. Key Bindings

Key Binding	Function
Left	Scroll all list items left horizontally.
Right	Scroll all list items right horizontally.
Up	Move cursor up to the previous item
Down	Move cursor down to the next item
Ctrl+b	Move cursor backward one page
Ctrl+f	Move cursor forward one page
Home	Move cursor to the first item (home). Note that Home key will not always work.
Ctrl+e	Move cursor to the end item. Note that End key will not always work.
End
Ctrl+a	Make all list items selected. Only applicable to the multi-select list box.
Ctrl+u	Make all list items unselected. Only applicable to the multi-select list box.
Space	Make the current item toggling between selected/unselected status

1.1.3. Callbacks

1.1.3.1. PreProcess Function

It is called immediately after the list box is activated but before waiting the user¡¯s first response. Usually it is used to perform some initializations, such as setting initial value for the list box. The prototype is:

Where Hwin is the handle of the form window and Hlist is the handle of the list box.

NOTE: Even if it returns a non-zero value, the list box will still be activated.

1.1.3.2. PostProces Function

It is called immediately before the list box loses the focus (by pressing Tab key).  It is often called to validate the user¡¯s inputs. The prototype is:

Where Hwin is the handle of the form window and Hlist is the handle of the list box.

NOTE: If it returns a non-zero value, MYTUI will consider the user¡¯s selections are wrong and refuse to move out.

1.1.3.3. Select Callback Function

It is called whenever an item is selected or unselected (by pressing space key). It is often used as a trigger to perform some actions that rely on the status of the items. The prototype is:

Where Hwin is the handle of the form window and Hlist is the handle of the list box.

1.2. Attributes

1.2.1. List Box Name

A list boxr must have its unique name within all children widgets of the form window. It must be assigned when creating the list box with method MYWINnewObj() and can be changed with MYWINsetObjName().

Note: the maximum length of the name is 32 bytes.

1.2.2. Selection Mode

It holds the selection mode of the list box, which must either be single-selection mode or multi-selection mode. For the single selection mode, only one item is selected at any time, otherwise arbitrary number of selected items is permitted, include zero.

The default value is single-selection mode. It can be set with method MYLISTBOXsetSingleSelect() or MYLISTBOXsetMultiSelect().

1.2.3. Selection Indicator

It is the character between the Prefix Characters to indicate that the item is selected. For items not selected, only a space character displayed between the prefix characters. It must be a printable character.

For single selection mode, the default character is ¡®#¡¯; for multi-selection mode, the default value is ¡®*¡¯. It can be set by method MYLISTBOXsetBracketChar() together with the Prefix Characters.

1.2.4. Prefix Characters

It is a string of two characters prefixed to each item with the Selection Indicator character between them to display the selecting status for the item. They must be printable characters.

The default value is ¡°[]¡± for single selection mode and ¡°()¡± for multi-selection mode. It can be set with by method MYLISTBOXsetBracketChar() together with the Selection Indicator.

1.2.5. Position

This is the relative position (Y, X) or (Row, Col) to the upper left corner of the form window¡¯s work area where:

They are based from a start point of (0,0). The default value is (1,1). They can be set with method MYLISTBOXsetPosSize().

Note1: this position doesn¡¯t include the box if there is one.

Note2: it is limited to the actual size of the form window's work area. So it will not always be what you have expected. It might be adjusted to fit the work area's size.

1.2.6. Dimensions (Lines, Cols)

This defines the list box¡¯s size (Lines, Cols). It doesn¡¯t include the box if there is one.

By default the list box is created to be the same size of the form¡¯s work area. They can be then adjusted with method MYLISTBOXsetPosSize().

Note: it is limited to the actual size of the form window's work area. So it will not always be what you have expected. It might be adjusted to fit the work area's size.

1.2.7. Box Mode

It defines the box style of the list box if there is one. At present, there are three modes available:

1.       WINBOX_NONE: No box.

2.       WINBOX_SL or WINBOX_DL: They have the same effect. The list box will have a box around it.

WINBOX_SL is the default value if no value specified. It can be set with method MYLISTBOXsetBoxMode().

1.2.8. Box Attribute

It specifies the display attribute of the box if there is one. It can either be one of the following attributes or the combination of them (defined in <curses.h>):

Where A_NORMAL, A_UNDERLINE, A_REVERSE are the most frequently used attributes with A_NORMAL being the default value. The box attribute can be set with method MYLISTBOXsetBoxAttrib().

1.2.9. Items

It is an array of text with each one represents an item by order.

By default no items defined. You can add an item to the end with method MYLISTBOXaddItem(), or delete an item with method MYLISTBOXremoveItem().

A list box can hold a maximum of 4096 items.

1.2.10. Item Attribute (Normal)

This is the display attribute for the text of the non-current items or when the list box is not the current widget within the form window. See also Box Attribute for the available values.

The default value is A_NORMAL. It can be set with method MYLISTBOXsetAttrib().

Note: it must be set together with Item Attribute (Focus).

1.2.11. Item Attribute (Focus)

This is the display attribute for the text of the current item when the list box is the current widget within the form window. See also Box Attribute for the available values.

The default value is A_NORMAL|A_UNDERLINE. It can be set with method MYLISTBOXsetAttrib().

Note: it must be set together with Item Attribute (Normal).

1.2.12. Hide Flag

It controls whether the list box should be visible or hidden from the form window. It can be set with MYLISTBOXsetInvisible() and MYLISTBOXsetVisible().

1.2.13. Edit Flag

It controls whether the list box should be editable or read-only. An editable list box can receive user¡¯s input and gain the focus, otherwise it can only display items.

By default list box is editable. This attribute can be set with method MYLISTBOXsetEditable() and MYLISTBOXsetDisplayOnly().

1.2.14. Callback Functions

1.2.14.1. PreProcess Function

See also PreProcess Function. It can be set with method MYLISTBOXregPreProcess().

1.2.14.2. PostProcess Function

See also PostProcess Function. It can set with method MYLISTBOXregPostProcess().

1.2.14.3. Select Callback

See also Select Callback Function. It can se set with method MYLISTBOXregSelectCallback().

1.2.15. Shared Object Name

This attribute is necessary only when you are using ©wdesigner and the dynamic linking mode is adopted for the callback functions. Otherwise it is meaningless.

It specifies which shared object hosts the list box¡¯s callback functions. The callback functions must be compiled and linked into the designated shared object.

 

1.3. Methods (in alphabetic order)

1.3.1. MYLISTBOXaddItem: Add an item to the list box

The prototype is:

It append a item to the list box. Hwin is the handle of the form window, Hobj refers to the list box and Text is the string to be appended. See also Items.

Zero is returned upon successful completion, otherwise a non-zero integer is returned from which more information can be retrieved by application mytuierr or routine MYTUIgetErrMsgByCode().

Note1: Any control characters, carriage return/line feed characters and tab characters in the string will be replaced with spaces.

Note2: it should not be called from the list box¡¯s callback functions while the list box is the current widget..

1.3.2. MYLISTBOXgetItem: get the specified item and its selection status

The prototype is:

It gets the text of the specified item and returns its selection status. Hwin is the handle of the form window, Hobj refers to the list box, index specifies the item, Text is the string to contain the result text and ret is the pointer of the return code. See also Items.

On success, the selection status is returned (either 0 or 1, where 0 means the item is not selected and 1 indicates it is selected) and the return code is set to zero, otherwise, the return code contains a non-zero error code from which more information can be retrieved by application mytuierr or routine MYTUIgetErrMsgByCode().

1.3.3. MYLISTBOXgetItemNumber: return the number of items

The prototype is:

It returns the number of items. Hwin is the handle of the form window, Hobj refers to the list box and ret is the pointer of the return code. See also Items.

On success, the total number of items is returned and the return code is set to zero, otherwise, the return code contains a non-zero error code from which more information can be retrieved by application mytuierr or routine MYTUIgetErrMsgByCode().

1.3.4. MYLISTBOXgetSelectSet: get the subset of selected items

The prototype is:

It returns the subset of selected items. Hwin is the handle of the form window, Hobj refers to the list box, Select is the array to hold the indexes of selected items and Num is the pointer of the number of selected items. See also Items,

Zero is returned upon successful completion, otherwise a non-zero integer is returned from which more information can be retrieved by application mytuierr or routine MYTUIgetErrMsgByCode().

For single selection mode, the subset will contain only one element and number is set to be 1.

Note: the caller is responsible to ensure Select is big enough to hold the indexes otherwise segment fault may occur.

1.3.5. MYLISTBOXregPostProcess: register the postprocess function

The prototype is:

It registers the postprocess function for the list box. Hwin is the handle of the form window, Hobj is the handle of the list box and PostProcess is the customized function conforms to the respective prototype of the interface. Refer to PreProcess Function for details.

Zero is returned upon successful completion, otherwise a non-zero integer is returned from which more information can be retrieved by application mytuierr or routine MYTUIgetErrMsgByCode().

1.3.6. MYLISTBOXregPreProcess: register the preprocess function

The prototype is: