CONTENT
1.3. Methods (in alphabetic order)
1.3.1. MYWINdraw: draw the form window
1.3.2. MYWINgetObjHandleByName: get the
widget¡¯s handle
1.3.3. MYWINgetObjNameByHandle: get the
widget¡¯s name
1.3.4. MYWINgetObjPos: get the widget¡¯s
position
1.3.5. MYWINgetPrivateAddr: get the pointer
of user¡¯s private data
1.3.6. MYWINgetWorkArea: get the work area¡¯s
position and size
1.3.7. MYWINnewObj: create a new widget
1.3.8. MYWINrefresh: refresh the form window
1.3.9. MYWINregEscapeCallback: register the
ESCAPE callback
1.3.10. MYWINregPostProcess: register the
postprocess function
1.3.11. MYWINregPreProcess: register the
preprocess function
1.3.12. MYWINsetBoxAttrib: set window box¡¯s
attribute.
1.3.13. MYWINsetBoxMode: set the window box¡¯s
mode
1.3.14. MYWINsetExitOn: send a signal to
close the form window
1.3.15. MYWINsetFocus: set the focus to a
widget
1.3.16. MYWINsetInitialStatus: set initial
text for the status bar
1.3.17. MYWINsetObjName: set a new name for
the widget
1.3.18. MYWINsetPosAndSize: set position
& size for the winfow
1.3.19. MYWINsetPrivateAddr: save the address
of private data
1.3.20. MYWINsetStatus: set text for the
status bar
1.3.21. MYWINsetStatusAlign: set text
alignment for the status bar
1.3.22. MYWINsetStatusAttrib: set status
bar¡¯s display attribute
1.3.23. MYWINsetStatusMode: set the status
bar¡¯s mode
1.3.24. MYWINsetTitle: set text for the title
bar
1.3.25. MYWINsetTitleAlign: set text
alignment for the title bar
1.3.26. MYWINsetTitleAttrib: set title bar¡¯s
display attribute
1.3.27. MYWINsetTitleMode: set the title
bar¡¯s mode
1.3.28. MYWINstart: start to run the form
window
1.1. Introduction
MYTUI Window is the container to accommodate all widget. It should be created before creating any widget. It provides geometry management for its children and traversing control when the form is activated. In fact, each MYTUI application is a combination of a series of form window.
All form windows are modal dialog window. MYTUI doesn¡¯t support modeless form. Only one form is active at the same time and it requires the user to respond before continuing the program. When a modal form is displayed on the screen, it intercepts the control, so the user has no access to any parent or sibling of other forms.
A typical MYTUI application is designed to use a sequence (not cascade) of modal forms. That is to say, one form is activated by another form¡¯s widgets, it then automatically returns the control to that form when it is closed.
A typical form window has an OK and Cancel button. User press OK button to implement a task or activate another form, or press Cancel button to close the form and return to the last form.
1.1.1. Look & Feel
Typically a form window consists of a box (frame), a title bar, the work area and a status bar. The work area is necessary while others are optional. All widgets are limited to reside in the work area. Refer to attributes for details.
1.1.2. Key Bindings
|
Key Binding |
Function |
|
Tab |
Move the focus to the next widget within the form |
|
Enter |
Move the focus to the next widget within the form. Inapplicable to data grid, scroll window, pull down menu and list box. |
|
Up |
Move the focus to the last widget within the form. Inapplicable to data grid, scroll window, pull down/popup menu and list box. |
|
Down |
Move the focus to the next widget within the form. Inapplicable to data grid, scroll window, pull down menu and list box. |
|
Left |
Move the focus to the last widget within the form. Only applicable to and push button. |
|
Right |
Move the focus to the next widget within the form. Only applicable to combobox and push button |
|
Escape |
Escape from the form. |
1.1.3. Callbacks
1.1.3.1. PreProcess Function
It is called immediately after the form is activated but before waiting the user¡¯s first response. Usually this function performs some initializations, such as setting initial values for widgets. The prototype is:
int (*PreProcess)(long Hwin);
Where Hwin is the handle of the form window. This callback should be registered by routine MYWINregPreProcess().
NOTE: If it returns a non-zero value, MYTUI will consider it as an error and immediately close the form and return.
1.1.3.2. Escape Callback Function
It is called when Escape key is detected while traversing the form window¡¯s widgets. By default, MYTUI will immediately end the traversing and return to the caller that activates the form. This callback gives you a chance to decide if you really want to close the form. For example, you can implement a callback popping up a simple dialog box to ask the user. The prototype is:
int (*EscapeCallback)(long Hwin);
Where Hwin is the handle of the form window. This callback should be registered by routine MYWINregEscapeCallback().
NOTE: If it returns a non-zero value, MYTUI will consider the user doesn¡¯t want to exit and continue traversing the form.
1.1.3.3. PostProcess Function
It is called immediately when a exit signal received from the user (usually issued by calling MYWINsetExitOn() somewhere) before ending the traversing and return to the caller. It is often called to perform final clearing work. The prototype is:
int (*PostProcess)(long Hwin);
Where Hwin is the handle of the form window. This callback should be registered by routine MYWINregPostProcess().
NOTE: If it returns a non-zero value, MYTUI will consider the user doesn¡¯t want to exit and continue traversing the form.
The figure below illustrates what happens when a form is activated and how three callbacks are triggered.
1.2. Attributes
1.2.1. Form Name
Each form has its unique name to differentiate it from other forms. It must be assigned when created with method MYTUInewWin() and cannot be changed since it is referred to get the window¡¯s handle at runtime.
Note: the maximum length of the name is 32 bytes.
1.2.2. Position
The absolute position (Y, X) or (Row, Col) of the upper left corner of the form window. Note that this position is relative to the upper-left of the screen where:
Y (Row): Vertical position of the upper left corner.
X (Col): Horizontal position of the upper left corner.
They are based from a start point of (0,0). They can be set with method MYWINsetPosAndSize()
1.2.3. Size
The window¡¯s size (Lines, Cols) includes the window¡¯s box. They can set with method MYWINsetPosAndSize().
1.2.4. Box Mode
The box style of the form window. At present, there are three modes available:
1. NONE: No box.
2. BOX_SL or BOX_DL: They have the same effect. The window will have a box around it.
BOX_SL is the default value if no value specified. It can be set with method MYWINsetBoxMode().
1.2.5. Box Attribute
The display attribute of the window 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 MYWINsetBoxAttrib().
1.2.6. Title Mode
It defines the style of the title bar. The title bar is always on the top of the form window. Available modes are:
1. WINTITLE_NONE: No title bar.
2. WINTITLE_BORDER: the title will be displayed on the top border of the form window. Here is the visual effect:
3. WINTITLE_LINE_B: the title bar will be separated by a line from the work area. This is the default case. See the following figure:
4. WINTITLE_LINE_NB: No separators between the tile title bar and the work area. See the figure below:
It can be set with method MYWINsetTitleMode().
1.2.7. Title Attribute
The display attribute of the title bar (if there is one). See also Box Attribute.
A_REVERSE is the default value. It can be set with method MYWINsetTitleAttrib().
1.2.8. Title Alignment
The alignment attribute of the text within the title bar. There are three options available:
1. ALIGN_LEFT: text is left-aligned within the title bar
2. ALIGN_CENTER: text is centered within the title bar.
3. ALIGN_RIGHT: text is right-aligned within the title bar.
ALIGN_CENTER is the default value. It can be set with method MYWINsetTitleAlign().
1.2.9. Title Text
The title bar¡¯s content. The text length is limited to the terminal's width (global variable COLS) otherwise it will be truncated.
The default text is ¡°Unknown Title¡±. It can be set with method MYWINsetTitle().
1.2.10. Status Mode
The style of the status bar. The status bar is always on the bottom of the form window. Available modes are:
1. WINSTATUS_NONE: No status bar on the form window.
2. WINSTATUS_LINE_B: the status bar is separate from the work area by a line. Here is a figure showing the visual effect:
3. WINSTATUS_LINE_NB: No separators between the work area and the status bar. Here is a figure showing the visual effect:
WINSTATUS_LINE_B is the default value. It can be set with method MYWINsetStatusMode().
1.2.11. Status Attribute
The display attribute of the status bar (if there is one). See also Box Attribute.
A_NORMAL is the default value. It can be set with method MYWINsetStatusAttrib ().
1.2.12. Status Alignment
The alignment attribute of the text within the status bar. Available options are the same as Title Alignment.
ALIGN_LEFT is the default value. It can be set with method MYWINsetStatusAlign().
1.2.13. Status Text
The status bar¡¯s content. The text length is limited to the terminal's width (global variable COLS) otherwise it will be truncated.
The default text is ¡°Welcome to Fan's Studio¡±. It can be set with method MYWINsetStatus().
1.2.14. Callback Functions
1.2.14.1. PreProcess Function
See also PreProcess Function. It can be set with method MYWINregPreProcess().
1.2.14.2. PostProcess Function
See also PostProcess Function. It can set with method MYWINregPostProcess().