MYTUI

CONTENT

 

1.1. Introduction 1

1.1.1. Look & Feel 2

1.1.2. Key Bindings 2

1.2. Attributes 3

1.2.1. Scroll Window Name 3

1.2.2. Position 3

1.2.3. Size (Lines, Cols) 3

1.2.4. Box Mode 3

1.2.5. Box Attribute 3

1.2.6. Maximum Lines 4

1.2.7. Text 4

1.2.8. Text Attribute (Normal) 4

1.2.9. Text Attribute (Focus) 4

1.2.10. Hide Flag 4

1.2.11. Edit Flag 5

1.3. Methods (in alphabetic order) 5

1.3.1. MYSWINDOWaddText: append a line to the scroll window 5

1.3.2. MYSWINDOWclear: clear the scroll window 5

1.3.3. MYSWINDOWexec: run a command in the scroll window 5

1.3.4. MYSWINDOWload: load a text file into the scroll window 6

1.3.5. MYSWINDOWlog: append a line of text with the formatted string 6

1.3.6. MYSWINDOWlogHex: display binary data in hexadecimal mode 6

1.3.7. MYSWINDOWlogTime: display current broken-down time in the scroll window 7

1.3.8. MYSWINDOWsave: save the content into a text file 7

1.3.9. MYSWINDOWsetAttrib: set display attribute for the text 8

1.3.10. MYSWINDOWsetBoxAttrib: set display attribute for the box 8

1.3.11. MYSWINDOWsetBoxMode: set the scroll window¡¯s box mode 8

1.3.12. MYSWINDOWsetDisplayOnly: set the scroll window read only 9

1.3.13. MYSWINDOWsetEditable: set the scroll window editable 9

1.3.14. MYSWINDOWsetInvisible: hide the scroll window from the form 9

1.3.15. MYSWINDOWsetMaxLines: set maximum lines for the scroll window 9

1.3.16. MYSWINDOWsetPosSize: set position and size for the scroll window 10

1.3.17. MYSWINDOWsetVisible: make the scroll window visible 10

 

1.1. Introduction

It is a text box with the content can be horizontally and vertically scrolled. Each line contains a single line of text. It is usually used as a log window as text can be only appended at the end in order.

A scroll window can have a box around it by setting the box mode with MYSWINDOWsetBoxMode(). By default the box is turned on. You can also select a display attribute for the box with MYSWINDOWsetBoxAttrib().

You can change the Eedit Flag with MYSWINDOWsetDisplayOnly() to turn the scroll window into a read-only widget.

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

Text can only be appended line by line with function MYSWINDOWaddText(), MYSWINDOWlog() or MYSWINDOWlogHex(). Each line is read only, there are no ways to change its content.

You can customize the display attributes of the text for two statuses (current line and non-current lines) with MYSWINDOWsetAttrib().

The lines number of the text is constrained to Maximum Lines. It can be set with MYSWINDOWsetMaxLines(). If one line¡¯s length is greater than the width of the scroll window, you can scroll the text vertically with function MYSWINDOWsetLeftPos().

The scroll window can be regarded as a text file viewer: you can load a file with MYSWINDOWload(), save the content into a text file with MYSWINDOWsave(). The scroll window can also be cleared with MYSWINDOWclear().

MYTUI also provides a convenient function MYSWINDOWexec() to run a command and redirect its output into the scroll window.

1.1.1. Look & Feel

The above example is captured from the output of command ¡°ps ¨Cef¡± by function MYSWINDOWexec().

1.1.2. Key Bindings

Key Binding	Function
Left	Scroll the scroll window¡¯s content one column left.
Right	Scroll the scroll window¡¯s content one column right.
Up	Scroll the scroll window¡¯s current line one line up.
Down	Scroll the scroll window¡¯s current line one line down.
Ctrl+b	Scroll the scroll window¡¯s current line one page up.
Ctrl+f	Scroll the scroll window¡¯s current line one page down.
Ctrl+a	Move cursor to the first line (home). Note that Home key will not always work.
Home
Ctrl+e	Move cursor to the end line. Note that End key will not always work.
End
¡®s¡¯	Save the content into a file. MYTUI will prompt you to specify the file name.
¡®l¡¯	Load a text file¡¯s content into the scroll window.
¡®c¡¯	Clear the scroll window¡¯s content.

 

1.2. Attributes

1.2.1. Scroll Window Name

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

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

1.2.3. Size (Lines, Cols)

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

By default the scroll window is created to be the same size of the form¡¯s work area. They can be adjusted later with method MYSWINDOWsetPosSize().

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.4. Box Mode

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

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

1.2.5. 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 (all 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 MYSWINDOWsetBoxAttrib().

1.2.6. Maximum Lines

The maximum lines permitted for the text

The default value is 4096 lines. It can be adjusted with method MYSWINDOWsetMaxLines(). Note this value must be less than 100000.

1.2.7. Text

It is an array of lines appended in order.

By default no text defined. You can append a line to the end with method MYSWINDOWaddText(), MYSWINDOWlog(), MYSWINDOWlogHex() or MYSWINDOWlogTime(). You cannot delete a specified line, but you can clear all lines with MYSWINDOWclear().

A scroll window can hold a maximum of 100000 lines.

1.2.8. Text Attribute (Normal)

This is the display attribute for the text of the non-current lines or when the scroll window 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 MYSWINDOWsetAttrib().

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

1.2.9. Text Attribute (Focus)

This is the display attribute for the text of the current line when the scroll window 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 MYSWINDOWsetAttrib().

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

1.2.10. Hide Flag

It controls whether the scroll window should be visible or invisible from the form window. It can be set with MYSWINDOWsetVisible() and MYSWINDOWsetInvisible().

1.2.11. Edit Flag

It controls whether the scroll window should be editable or read-only. An editable scroll window can gain the focus, otherwise it can only display text.

By default scroll window is editable. This attribute can be set with method MYSWINDOWsetEditable() and MYSWINDOWsetDisplayOnly().

 

1.3. Methods (in alphabetic order)

1.3.1. MYSWINDOWaddText: append a line to the scroll window

The prototype is:

It appends a line of text to the scroll window. Hwin refers to the form window, Hobj refers to the scroll window and Text is the string to be appended. The cursor will move to this new line. 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.

Note2: if the lines number already reaches the limitation (see also Maximum Lines), this method will fail.

Note3: it is the basis function of method MYSWINDOWload(), MYSWINDOWlog(), MYSWINDOWlogHex().

1.3.2. MYSWINDOWclear: clear the scroll window

The prototype is:

It clears the scroll window (delete all lines). Hwin refers to the form window, Hobj refers to the scroll window. 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().

1.3.3. MYSWINDOWexec: run a command in the scroll window

The prototype is:

It runs a program or command in the scroll window, the standard output from the command will be redirected to the scroll window. Hwin refers to the form window, Hobj refers to the scroll window and Command is the a pointer to a null-terminated string containing a shell command line. 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().

1.3.4. MYSWINDOWload: load a text file into the scroll window

The prototype is:

It loads the content of a text file into the scroll window and move the cursor to the last line. Hwin refers to the form window, Hobj refers to the scroll window and fileName points to the name of the text file to be loaded. 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 text file will be replaced with spaces.

Note2: the content of the scroll window will be cleared before loading the text file.

Note3: if the lines of the text file exceed the limitation (the maximum lines), the exceeding part will be ignored.

1.3.5. MYSWINDOWlog: append a line of text with the formatted string

The prototype is:

It appends a new line of text according to the specified format. Hwin is the handle of the form window, Hobj is the handle of the scroll window and format string specifies how subsequent arguments are converted for the text. Refer to the standard C function printf() for details of format.

It is delivered to replace function MYSWINDOWaddText() in the more flexible way and save codes for you.

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.6. MYSWINDOWlogHex: display binary data in hexadecimal mode

The prototype is:

It displays binary data in hexadecimal mode to the scroll window. Hwin refers to the form window, Hobj refers to the scroll window, buf points to the binary data to be displayed and Length is the length of binary data. It is useful for debugging non-printable data. See also Text for details.

Each line appended to the scroll window displays 16 bytes of data. Each line is divided into three parts:

1.       data offset: shows the current byte offset of the character at the beginning of the line to form the beginning of the data;

2.       Hexadecimal Representation: shows the hexadecimal value of each binary byte as a two character field, separated from the next byte by a space (' ').

3.       ASCII Representation: provides the view of printable characters. Non printable characters are shown with a period character ('.').

Here is an example:

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.7. MYSWINDOWlogTime: display current broken-down time in the scroll window

The prototype is:

It displays the current time (which is a representation separated into year, month, day, etc.) as a line appended to the scroll window. Hwin refers to the form window, Hobj refers to the scroll window. The time is represented in the form like:

The abbreviations for the days of the week  are  `Sun',  `Mon',  `Tue', `Wed',  `Thu',  `Fri', and `Sat'.  The abbreviations for the months are `Jan', `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug',  `Sep',  `Oct', `Nov',  and  `Dec'.

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.8. MYSWINDOWsave: save the content into a text file

The prototype is:

It saves all lines of the scroll window into the specified text file. Hwin refers to the form window, Hobj refers to the scroll window and fileName points to the name of the text file to be saved. 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().

Note: the text file will be truncated to zero length if it already exists before saving the content.

1.3.9. MYSWINDOWsetAttrib: set display attribute for the text

The prototype is:

It sets the display attribute for the scroll window¡¯s content. Hwin is the handle of the form window, Hobj is the handle of the scroll window, Attrib is the attribute used to display non-current lines , AttribFocus is the attribute used to display the current line. 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.10. MYSWINDOWsetBoxAttrib: set display attribute for the box

The prototype is:

It sets the display attribute for the scroll window¡¯s box if there is one. Hwin refers to the form window, Hobj refers to the scroll window 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.11. MYSWINDOWsetBoxMode: set the scroll window¡¯s box mode

The prototype is:

It sets the style for the scroll window¡¯s box if there is one. Hwin refers to the form window, Hobj refers to the scroll window 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.12. MYSWINDOWsetDisplayOnly: set the scroll window read only

The prototype is:

It sets the scroll window read only. Hwin refers to the form window, Hobj refers to the scroll window. A read only scroll window 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().

1.3.13. MYSWINDOWsetEditable: set the scroll window editable

The prototype is:

It sets the scroll window editable. Hwin refers to the form window, Hobj refers to the scroll window. 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().

1.3.14. MYSWINDOWsetInvisible: hide the scroll window from the form

The prototype is:

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

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

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.15. MYSWINDOWsetMaxLines: set maximum lines for the scroll window

The prototype is:

It sets the maximum lines for the scroll window. Hwin refers to the form window, Hobj refers to the scroll window and MaxLines is the value to be set. See also Maximum Lines 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: you cannot call this function if the scroll window already has lines of text.

Note2: if MaxLines is greater than 100000, then only 100000 is set to the scroll window.

1.3.16. MYSWINDOWsetPosSize: set position and size for the scroll window

The prototype is:

It sets the position relative to the work area of the form window and the size for the scroll window. Hwin refers to the form window, Hobj refers to the scroll window, (Y, X) is the position and (Height, Width) is the scroll window¡¯s size (doesn¡¯t includes the box). Refer to Position and Size for description of position and size.

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 (widgets are limited to the size of the work area of the form window).

1.3.17. MYSWINDOWsetVisible: make the scroll window visible

The prototype is:

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

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

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