MYTUI

CONTENT

 

1.1. Introduction 1

1.1.1. Look & Feel 2

1.1.2. Key Bindings 2

1.1.3. Callbacks 2

1.2. Attributes 2

1.2.1. Button Name 2

1.2.2. Position 2

1.2.3. Box Mode 3

1.2.4. Box Attribute 3

1.2.5. Text 3

1.2.6. Text Attribute (Normal) 3

1.2.7. Text Attribute (Focus) 3

1.2.8. Hide Flag 4

1.2.9. Edit Flag 4

1.2.10. Callback Functions 4

1.2.11. Shared Object Name 4

1.2.12. Hint Information 4

1.3. Methods (in alphabetic order) 4

1.3.1. MYBUTTONregCallback: register the callback function 4

1.3.2. MYBUTTONsetAttrib: set display attribute for the label text 4

1.3.3. MYBUTTONsetBoxAttrib: set display attribute for the box 5

1.3.4. MYBUTTONsetBoxMode: set the push button¡¯s box mode 5

1.3.5. MYBUTTONsetDisplayOnly: set the push button read only 5

1.3.6. MYBUTTONsetEditable: set the line editor editable 6

1.3.7. MYBUTTONsetHint: set the hint information 6

1.3.8. MYBUTTONsetInvisible: hide the line editor from the form 6

1.3.9. MYBUTTONsetPos: set push button¡¯s position within the form 6

1.3.10. MYBUTTONsetText: set push button¡¯s text 7

1.3.11. MYBUTTONsetVisible: make the push button visible 7

 

1.1. Introduction

The Push Button provides a command button. It is rectangular with a box around it and typically displays a text label describing its action.

It is perhaps the most commonly used widget in any user interface. Push a button to command the computer to perform some action, or to answer a question. Typical buttons are OK, Apply, Cancel, Close, Yes, No and Help.

The text label can be changed with method MYBUTTONsetText().You can change the display attribute of the text for two different statuses (either gains or loses focus) with MYBUTTONsetAttrib().

By default a push button has a box around it, you can set the box mode with MYBUTTONsetBoxMode(). You can also select a display attribute for the box with MYBUTTONsetBoxAttrib().

By changing the edit flag with MYBUTTONsetDisplayOnly() or MYBUTTONsetEditable(), it can be disabled or enabled again.

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

At last, the hint information can set with MYBUTTONsetHint(). MYTUI will display it in the form window¡¯s status bar when the push button gains the focus to prompt the user what to do.

1.1.1. Look & Feel

Here are some typical buttons:

1.1.2. Key Bindings

It is simple. Just press Space or Enter key to activate it. If your callback function returns 0, then the focus will be moved to the next widget by MYTUI.

1.1.3. Callbacks

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

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

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.

It can be registered with method MYBUTTONregCallback().

1.2. Attributes

1.2.1. Button Name

A push button must have its unique name within all children widgets of the form window. It must be assigned when creating the push button 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:

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

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

1.2.3. Box Mode

The box style of the push button 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 push button will have a box around it.

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

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>):

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

1.2.5. Text

The text label of the push button. The text length is limited to the bytes otherwise it will be truncated.

The default value is ¡°Button¡±. It can be set with method MYBUTTONsetText().

1.2.6. Text Attribute (Normal)

This is the display attribute for the text when the push button is inactive (that is, if it 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 MYBUTTONsetAttrib().

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

1.2.7. Text Attribute (Focus)

This is the display attribute for the text when the push button is active (that is, if it is the current widget within the form window). See also Box Attribute for the available values.

The default value is A_NORMAL|A_REVERSE. It can be set with method MYBUTTONsetAttrib().

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

1.2.8. Hide Flag

It controls whether the push button should be visible or invisible from the form window. It can be set with MYBUTTONsetVisible() and MYBUTTONsetInvisble().

1.2.9. Edit Flag

It controls whether the push button should be disabled or enabled. An editable push button can gain the focus, otherwise it can only stay there.

By default push button is editable. This attribute can be set with method MYBUTTONsetEditable() and MYBUTTONsetDisplayOnly().

1.2.10. Callback Functions

See also Callbacks. It can set with method MYBUTTONregCallback().

1.2.11. 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 push button¡¯s callback functions. The callback functions must be compiled and linked into the designated shared object.

1.2.12. Hint Information

It holds the text that will be displayed in the form window¡¯s status bar (if there is one) when the push button gains the focus. Its length must be limited to 80 bytes otherwise it will be truncated.

The default value is ¡°Push Button¡± and it can be set with method MYBUTTONsetHint().

1.3. Methods (in alphabetic order)

1.3.1. MYBUTTONregCallback: register the callback function

The prototype is:

It registers the callback function for the push button. Hwin is the handle of the form window, Hobj is the handle of the push button and Callback is the customized function conforms to the respective prototype of the interface. Refer to Callback Functions 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.2. MYBUTTONsetAttrib: set display attribute for the label text

The prototype is:

It sets the display attribute for the push button¡¯s text. Hwin is the handle of the form window, Hobj is the handle of the push button, Attrib is the attribute used to display label text when the push button is not the current widget, AttribFocus is the attribute used when the push button gains the focus (the current widget). See also Text Attribute (Normal) and Text Attribute (Focus).

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

Note: this routine should be called before calling MYWINdraw().

1.3.3. MYBUTTONsetBoxAttrib: set display attribute for the box

The prototype is:

It sets the display attribute for the push button¡¯s box if there is one. Hwin refers to the form window, Hobj refers to the push button and Attrib is the attribute to be set. Refer to Box Attribute for the description about the attribute.

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

Note: this routine should be called before calling MYWINdraw().

1.3.4. MYBUTTONsetBoxMode: set the push button¡¯s box mode

The prototype is:

It sets the style for the push button¡¯s box if there is one. Hwin refers to the form window, Hobj refers to the push button and BoxMode is the mode to be set. See also Box Mode 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().

Note: this routine should be called before calling MYWINdraw().

1.3.5. MYBUTTONsetDisplayOnly: set the push button read only

The prototype is:

It sets the push button read only. Hwin refers to the form window, Hobj refers to the push button. A read only push button cannot gain focus. See also Edit Flag 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().

Note: this routine will fail if it is called from the push button¡¯s callback function while the button is the current widget.

1.3.6. MYBUTTONsetEditable: set the line editor editable

The prototype is:

It sets the push button editable. Hwin refers to the form window, Hobj refers to the push button. See also Edit Flag 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().

Note: this routine will fail if it is called from the push button¡¯s callback function while the button is the current widget.

1.3.7. MYBUTTONsetHint: set the hint information

The prototype is:

It sets the hint information for the push button. Hwin refers to the form window, Hobj refers to the push button and Hint is the information to be set. See also Hint Information.

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 push button¡¯s callback function while the button is the current widget.

1.3.8. MYBUTTONsetInvisible: hide the line editor from the form

The prototype is:

It hides the push button from the form window, that is, make it invisible. Hwin refers to the form window and Hobj refers to the push buttonr to be hidden. See also Hide Flag for details.

It can be made visible again by call routine MYBUTTONsetVisible().

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

Note: it should not be called from the push button¡¯s callback function while the button is the current widget.

1.3.9. MYBUTTONsetPos: set push button¡¯s position within the form

The prototype is:

It sets the push button¡¯s relative position to the form window¡¯s work area. Hwin refers to the form window, Hobj refers to the push button and (Y, X) is the position to be set. Refer to Position for the description of position.

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: it should be issued before calling MYWINdraw().

Note2: The actual values will not always be what you have input. They might be adjusted to fit the form window¡¯s size.

1.3.10. MYBUTTONsetText: set push button¡¯s text

The prototype is:

It sets the push button¡¯s text. Hwin refers to the form window, Hobj refers to the push button and Text is the string to be set. See also Text 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().

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

1.3.11. MYBUTTONsetVisible: make the push button visible

The prototype is:

It redisplays the push button to the form window, that is, make it visible. Hwin refers to the form window and Hobj refers to the push button to be displayed. See also Hide Flag for details.

It can be made invisible again by call routine MYBUTTONsetInvisible().

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

Note: it should not be called from the push button¡¯s callback function while the push button is the current widget.