MYTUI > Curses RAD Tool | www.myqueue.net

The Line Editor is a one-line text editor allowing the user to enter and edit a single line of plain text like names, phone numbers etc. It is one of the most frequently widgets.

A line editor can have a box around it by setting the box mode with MYLEDITsetBoxMode(). By default the box is turned off. You can also select a display attribute for the box with MYLEDITsetBoxAttrib().

You can change the edit flag with MYLEDITsetDisplayOnly() to turn the line editor into a read-only field.

By changing the hide flag with MYLEDITsetInvisible() or MYLEDITsetVisible(), it can be hidden from or redisplayed on the form window.

By changing the echo mode with MYLEDITsetEchoMode(), it can be used as a "write-only" field, for inputs such as passwords.

The length of the text is constrained to maximum text length. It can be set with MYLEDITsetMaxLength(). The text is displayed within the area constrained to display length, which can be specified with MYLEDITsetDispLength().

The text can be constrained to the format type with MYLEDITsetType(), so MYTUI will do some basic validations for you.

You can change the text with MYLEDITprintf() or MYLEDITsetText(). The text can be retrieved with MYLEDITgetText().And, line editor can also return the respective value with methods such as MYLEDITgetIntValue(), MYLEDITgetDoubleValue() etc. by the text type, besides only returning the text string.

You can change the display attribute of the text for two statuses (either gains or loses focus) with MYLEDITsetAttrib().

At last, the hint information can set with MYLEDITsetHint(). MYTUI will display it in the form window��s status bar when the line editor gains the focus to prompt the user what to do.

1.1.1. Look & Feel

Here are some typical line editors:

The first one is a normal editor, the second one has a box and is set into ��PASSWORD�� mode and the last one has its echo turned off.

1.1.2. Key Bindings

Key Binding	Function
Left	Move the cursor one character to the left.
Ctrl+b	Move the cursor one character to the left.
Right	Move the cursor one character to the right.
Ctrl+f	Move the cursor one character to the right.
Ctrl+a	Move the cursor to the beginning. Note that Home key will not always work.
Home
Ctrl+e	Move the cursor to the end. Note that End key will not always work.
End
Ctrl+d	Deletes the character to the right of the cursor.
Delete	Deletes the character to the right of the cursor.
Ctrl+h	Deletes the character to the left of the cursor.
Backspace	Deletes the character to the left of the cursor.
Escape	Cancel editing, discard any changes and restore the original content and notify the form to escape.

Note: At present only overwrite mode works for line editor, no insert mode. So each character from your input will overwrite the character at the cursor position.

1.1.3. Callbacks

1.1.3.1. PreProcess Function

It will be called immediately after the line editor 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 line editor. The prototype is:

int (*PreProcess)(long Hwin, long Hledit);

Where Hwin is the handle of the form window and Hledit is the handle of the line editor.

NOTE: If it returns a non-zero value, the line editor will still be activated.

1.1.3.2. PostProcess Function

It is called immediately before the line editor loses the focus (by pressing Tab/Enter/Up/Down key). It is often called to validate the user��s inputs. The prototype is:

int (*PostProcess)(long Hwin, long Hledit);

Where Hwin is the handle of the form window and Hledit is the handle of the line editor.

NOTE: If it returns a non-zero value, MYTUI will consider the user��s inputs is wrong and refuse to move out.

1.1.3.3. Input Callback Function

It is called whenever a printable character (excepts key bindings described in Line Editor��s Key Bindings) received. It is often used as a input filter. For example, you can employ it to convert the inputs to upper/lower case. The prototype is:

chtype (*InputCallback)(long Hwin, long Hledit, chtype input);

Where Hwin is the handle of the form window and Hledit is the handle of the line editor, input is the character input by the user. It should return a character to MYTUI.

The figure below illustrates what happens when a line editor is activated and how three callbacks are triggered.

1.2. Attributes

1.2.1. Editor Name

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

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

1.2.2. Position

The relative position (Y, X) or (Row, Col) to the upper left corner of the form window��s work area where:

Y (Row): Vertical position of the line editor

X (Col): Horizontal position of the line editor

They are based from a start point of (0,0). They can be set with method MYLEDITsetPos().

Note: this position doesn��t include the box if there is one.

1.2.3. Box Mode

The box style of the line editor is 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 line editor will have a box around it.

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

1.2.4. Box Attribute

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

A_NORMAL Normal display (no highlight)

A_STANDOUT Best highlighting mode of the terminal.

A_UNDERLINE Underlining

A_REVERSE Reverse video

A_BLINK Blinking

A_DIM Half bright

A_BOLD Extra bright or bold

A_PROTECT Protected mode

A_INVIS Invisible or blank mode

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 MYLEDITsetBoxAttrib().

1.2.5. Format Type (or Text Type)

The format type of the text. This provides a build-in validating mechanism for the inputted text. It can greatly save coding time and complexity as its validation covers most ordinary used data types. So what you need to do in the postprocess function will be more simple. At last, it also provides some shortcut function for converting text into the value that meets your expectation. Here is a list of the supported types:

1. LEDIT_TYPE_STRING: Normal String. No data validating for this type. This is the default value if not specified.

2. LEDIT_TYPE_STR_ALPHA: Alphabetic characters. Each character must be an alphabetic letter, either in upper or lower case. That is, any letter A-Z or a-z.

3. LEDIT_TYPE_STR_DIGIT: Decimal digital characters. Each character must be a decimal digit (0 through 9).

4. LEDIT_TYPE_STR_XDIGIT: Hexadecimal digital characters. Each character must be a hexadecimal digit, i.e. one of 0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F.

5. LEDIT_TYPE_STR_ALNUM: Alphabetic number characters. Each character must be an alphanumeric letter. That is, any letter A-Z or a-z, or any digit 0-9.

6. LEDIT_TYPE_INT_B2: Integer (Base 2). The text can be converted to an integer value according to base 2 without an overflow or underflow occurring. Each character must be either ��0�� or ��1��. For example, ��010111001��.

7. LEDIT_TYPE_INT_B8: Integer (Base 8). The text can be converted to an integer value according to base 8 without an overflow or underflow occurring. Each character must be any letter 0-7. For example, ��701645��.

8. LEDIT_TYPE_INT_B10: Integer (Base 10). The text can be converted to an integer value according to base10 without an overflow or underflow occurring. Each character must be any decimal digit (0-9). For example, ��801695��.

9. LEDIT_TYPE_INT_B16: Integer (Base 16). The text can be converted to an integer value according to base16 without an overflow or underflow occurring. Each character must be any hexadecimal digital letter.

10. LEDIT_TYPE_UINT_B2: Unsigned Integer (Base 2). The text can be converted to an unsigned integer value according to base 2 without an overflow or underflow occurring. Each character must be either ��0�� or ��1��.

11. LEDIT_TYPE_UINT_B8: Unsigned Integer (Base8). The text can be converted to an unsigned integer value according to base 8 without an overflow or underflow occurring. Each character must be any letter 0-7.

12. LEDIT_TYPE_UINT_B10: Unsigned Integer (Base 10). The text can be converted to an unsigned integer value according to base10 without an overflow or underflow occurring. Each character must be any decimal digit (0-9).

13. LEDIT_TYPE_UINT_B16: Unsigned Integer (Base 16). The text can be converted to an unsigned integer value according to base16 without an overflow or underflow occurring. Each character must be any hexadecimal digital letter.

14. LEDIT_TYPE_DOUBLE: Double Float. The text can be converted to an double value without an overflow or underflow occurring.

15. LEDIT_TYPE_DATE1: Date. The text must be a date formatted as a string in ��YYYYMMDD�� format.

16. LEDIT_TYPE_DATE2: Date. The text must be a date formatted as a string in ��YYYY-MM-DD�� format.

17. LEDIT_TYPE_DATE3: Date. The text must be a date formatted as a string in ��YYYY/MM/DD�� format.

18. LEDIT_TYPE_DATE4: Date. The text must be a date formatted as a string in ��MM/DD/YYYY�� format.

19. LEDIT_TYPE_DATE5: Date. The text must

MYTUI

Rapid TUI Application Development

APIs for Line Editor Widget

1.1. Introduction