©wdesigner User’s Manual

for MYTUI1.2

Fan Xiaohua

2006.04

Content

1.Why ©wdesigner?

©wdesigner is a WYSIWYG (What You See is What You Get) development tool of MYTUI. It is the most complete RAD tool to develop text-based UI applications under UNIX/LINUX environments.

You can directly use standard MYTUI SDK to develop applications instead of ©wdesigner, but that will become a time-consuming and boring task, especially for large-scale systems. You have to define all attributes of widgets and forms, register callback functions in C/C++ source files without extracting them into special resource containers. The disadvantages are obvious:

First, you have to spend considerable time on UI details before implementing your core business logic. For extreme worse situations (complicated UI with simple business logic), almost all your work will be wasted on these static attributes.

Second, the application has poor maintainability because resources are “solidified” in your application. Even a tiny adjustment such as changing the position of a widget will lead to the complete recompiling of the overall application or relevant modules, though it has nothing to do with the business logic.

©wdesigner resolves all these problems. It separates the management of static attributes from the whole development cycle. Instead of defining attributes by directly calling SDK functions, these resources are contained in a special file named TRF (TUI Resource File). ©wdesigner provides the WYSIWYG interface for managing resources. MYTUI automatically create forms and widgets by reading static information from the file at runtime. Your source codes will become quite compact and legible.

©wdesigner can also generate C/C++ codes for you to quickly setup the frame of your application.

2.Introduction to MYTUI Widgets

2.1.MYTUI Widget Hierarchy

Widgets are the elements that make up a user interface. Here is the hierarchy tree used to implement widgets:

2.1.1.MYTUI Root

See the dashed line frame in the above figure.

Strictly speaking, it is not a real widget. However to let your application work, you should first initialize it. Only one root exists so you needn’t to create it like doing that for other widgets. ©wdesigner doesn’t care about it , we will not describe it in this manual.

2.1.2.Form Window

The form window is a container that can hold an arbitrary number of children or widgets(label, push button, line editor, etc.). 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 the 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 hands over 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.

For how to define a form window with ©wdesigner, please refer to Define a Form Window.

2.1.3.Widgets in a Form Window …

Here is a figure shows these widgets’s typical appearances and layouts (except the popup menu and pull down menu):

2.2.TRF file

TRF means MYTUI Resource File. It is a form container that saves all the static attributes/initial values of a form window and its widgets.

Each TRF file can only defines one form. And, the file name must be in the form like XXX.trf where XXX is the form name. Otherwise ©wdesigner will not save your editings.

2.3.Widget Naming Constraints

2.3.1.Widget Name vs. Widget Handle

Each form and widget has its own name and this name is a ‘static’ attribute. Whether a form is in running status or not, its name will not change. Handle is also used by MYTUI to refer to a window or a widget because it is more convenient and efficient than using the name. However, handles are meaningful only when a form is running, they are dynamically generated when the form is started from a TRF (see TRF file) or the widgets are created by explicitly calling MYTUInewObj() function. At the same time, no two handles have the same value.

As you cannot directly manipulate a form window or widget by its name, you must first call MYTUIgetHandleByName() function to get its handle. If you employ ©wdesigner to develop MYTUI applications, then naming is very critical for defining forms and widgets. You should plan a good mnemonic for the names of widgets in your TRF files.

2.3.2.Naming Constraints

Each form window has its unique form name to identify it from other forms. Within a form, you should also give each widget a unique name. That is, two widget belong to two different forms can have the same name without confliction.

2.4.Callback Functions

It is also an important task you should pay more attention to define callbacks for your forms and their widgets. ©wdesigner can automatically construct skeleton codes for your application by these functions together with other attributes. So you must be familiar with each widget’s callback functions.

2.4.1.Callbacks of the Form Window

2.4.1.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.

NOTE: If it returns a non-zero value, MYTUI will consider it as an error and immediately close the form and return.

2.4.1.2.Escape Callback Function

It is called when a 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.

NOTE: If it returns a non-zero value, MYTUI will consider the user doesn’t want to exit and continue traversing the form.

2.4.1.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.

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.

2.4.2.Callbacks of Line Editor

2.4.2.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.

2.4.2.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.

2.4.2.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.

2.4.3.Callbacks of Push Button

It is simple, only postprocess function is available for the push button widget.

2.4.3.1.PostProcess Function

It is called immediately before the push button loses the focus (by pressing Enter/Space key). It is often called to perform some actions. The prototype is:

int (*Callback)(long Hwin, long Hbutton);

Where Hwin is the handle of the form window and Hbutton is the handle of the push button.

NOTE: If it returns zero value, MYTUI will consider the callback is successfully executed and the focus will be moved to the next available widget. Otherwise the cursor will still be focused on the push button.

2.4.4.Callbacks of Combobox

2.4.4.1.PreProcess Function

It is called immediately after the combobox 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 combobox or other widgets. The prototype is:

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

Where Hwin is the handle of the form window and Hcombox is the handle of the comboxbox.

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

2.4.4.2.PostProcess Function

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

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

Where Hwin is the handle of the form window and Hcombox is the handle of the comboxbox.

NOTE: If it returns a non-zero value, MYTUI will consider an error occurs and refuse to move the cursor out.

2.4.5.Callbacks of Pull Down/Popup Menu

You can define a callback function for each menu item of the menu. No preprocess or postprocess functions available.

2.4.5.1.Menu Item Callback Function

It is called whenever a menu item is activated (by pressing Enter key). The prototype is:

int (*Callback)(long Hwin, long Hmenu, long Hsubmenu, long Hitem);

Where Hwin is the handle of the form window, Hmenu is the handle of the pull down or popup menu, Hsubmenu is the handle of the current submenu and Hitem is the handle of the current menu item on the submenu.

2.4.6.Callbacks of List Box

2.4.6.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:

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

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.

2.4.6.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:

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

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.

2.4.6.3.Select Callback Function

It is called whenever a 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:

int (*SelectCallback)(long Hwin, long Hlist);

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

2.4.7.Callbacks of Data Grid

2.4.7.1.PostProcess Function

It is called immediately when the data grid is to lose the focus (by pressing Tab key). It is often called to validate the user’s inputs. The prototype is:

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

Where Hwin is the handle of the form window and Hdgrid is the handle of the data grid.

NOTE: If it returns a non-zero value, MYTUI will consider validating fails and refuse to hand out the focus.

2.4.7.2.Delete PreProcess Function

It is called whenever a row is to be deleted (by pressing Ctrl+y key). It is often used to get the user’s confirm before really deleting the current row. The prototype is:

int (*DeletePreProcess)(long Hwin, long Hdgrid, int Line);

Where Hwin is the handle of the form window, Hdgrid is the handle of the data grid and Line the the index of the line to be deleted.

NOTE: If it returns a non-zero value, MYTUI will consider the user doesn’t want to delete the row and end the action. That means no rows are deleted.

2.4.7.3.Insert PostProcess Function

It is executed whenever a row is to be inserted (by pressing Ctrl+n or Ctrl+e key). It is often called to get the user’s confirm before inserting a new row. The prototype is:

int (*InsertPostProcess)(long Hwin, long Hdgrid, int Line);

Where Hwin is the handle of the form window, Hdgrid is the handle of the data grid and Line the the index of the line to be inserted.

NOTE: If it returns a non-zero value, MYTUI will consider the user doesn’t want to insert a row and end the action. That means no rows are inserted.

2.4.7.4.Field’s PostProcess Function

Fields are also called columns. Each field can be specified a postprocess function that applies to all cells in this column. It is called when the relevant cells are activated (See also Define Fields (Columns) for details). The prototype is:

int (*FieldPostProcess)(long Hwin, long Hdgrid, int Line, int Col);

Where Hwin is the handle of the form window, Hdgrid is the handle of the data grid and (Line,Col) indicates which cell is activated.

NOTE: If it returns a non-zero value, MYTUI will consider the post processing failed and cancel all changes made in the postprocess function.

2.5.Key Bindings

Before starting ©wdesigner, you should know how to operate typical widgets and form with key bindings. Actually, ©wdesigner is also developed with MYTUI SDK, each dialog window for editing a widget is a MYTUI form window contains a series of widgets.

2.5.1.Line Editor’s Key Bindings

For any other printable characters, ©wdesigner will consider them as normal inputs.

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.

2.5.2.ComboBox’s Key Bindings

The combobox widget consists of a line editor and a drawdown list box. When entry of the combobox has the input focus, if the line editor of the combobox is read-only( this is the default case), you can press Space key to pop up the drawdown list box