diff --git a/Ansi_readme.md b/Ansi_readme.md index 2279172..f06def8 100644 --- a/Ansi_readme.md +++ b/Ansi_readme.md @@ -62,15 +62,15 @@ Here is a list of all implemented functions with a brief explanation Here is a list of the included functions mapped in the Ansi table, each function is described in details later on this document. -- `Ansi.GetClearCharacters()` -- `Ansi.GetCursorDown()` -- `Ansi.GetCursorLeft()` -- `Ansi.GetCursorMove()` -- `Ansi.GetCursorRight()` -- `Ansi.GetCursorUp()` -- `Ansi.GetDeleteCharacters()` -- `Ansi.GetDeleteLines()` -- `Ansi.GetInsertBlankLines()` +- [Ansi.GetClearCharacters()](#ansi_getclearcharacters) +- [Ansi.GetCursorDown()](#ansi_getcursordirection) +- [Ansi.GetCursorLeft()](#ansi_getcursordirection) +- [Ansi.GetCursorMove()](#ansi_getcursordirection) +- [Ansi.GetCursorRight()](#ansi_getcursordirection) +- [Ansi.GetCursorUp()](#ansi_getcursordirection) +- [Ansi.GetDeleteCharacters()](#ansi_getdeletecharacters) +- [Ansi.GetDeleteLines()](#ansi_getdeletelines) +- [Ansi.GetInsertBlankLines()](#ansi_getinsertblanklines) - `Ansi.GetRndBGColor()` - `Ansi.GetRndFgColor()` - `Ansi.Set()` @@ -333,6 +333,7 @@ The following command switch on the ANSI mode and set the terminal size to the d --- + ## Ansi.GetDeleteLines(lines) Returns the escape sequence to delete `lines` rows. @@ -347,6 +348,7 @@ Returns the escape sequence to delete `lines` rows. --- + ## Ansi.GetInsertBlankLines(lines) Returns the escape sequence to insert `lines` blank rows. @@ -361,6 +363,7 @@ Returns the escape sequence to insert `lines` blank rows. --- + ## Ansi.GetClearCharacters(chars) Returns a string with the ANSI escape sequence needed to clear `chars` characters. @@ -389,6 +392,7 @@ Returns the escape sequence to insert `chars` characters. --- + ## Ansi.GetDeleteCharacters(chars) Returns the escape sequence to delete `chars` characters. @@ -418,6 +422,7 @@ Returns the escape sequence to move the cursor to (`row`, `column`). --- + ## Ansi.GetCursorUp(n) // Ansi.GetCursorDown(n) // Ansi.GetCursorLeft(n) // Ansi.GetCursorRight(n) Returns the escape sequence needed to move the cursor by the specified number of characters. @@ -616,156 +621,195 @@ Creates a new, empty, `TermApp` object. ## Term.App:\_DrawHeader() -Utility method used to draw the application's header. +**Utility method** used to draw the application's header. + +--- ## Term.App:SetStatus(txt) Sets the status line with the given text. -INPUT -txt : text to print in the status line +**INPUT** + +- `txt` : (STR) Text to print in the status line + +--- ## Term.App:ClearStatus(txt) Clears the status line. +--- + ## Term.App:SetInfo(txt) Sets the info line with the given text. -INPUT -txt : text to print in the informations line +**INPUT** -## Term.App:ClearInfo(txt) +- `txt` : (STR) Text to print in the informations line + +--- + +## Term.App:ClearInfo() Clears the informations line. +--- + ## Term.App:SetWarning(txt) Sets the warnings line with the given text. -INPUT -txt : text to print in the warnings line +**INPUT** -## Term.App:ClearWarning(txt) +- `txt` : (STR) Text to print in the warnings line + +--- + +## Term.App:ClearWarning() Clears the warnings line. +--- + ## Term.App:\_DrawStatus(txt) -Prints the current status message if 'txt' is not specified, otherwise -replaces the message with 'txt' and prints it. +**Utility method** that prints the current status message if `txt` is not specified, otherwise replaces the message with `txt` and prints it. -INPUT -txt : NIL or the message to print in the status line. +**INPUT** + +- `txt` : (NIL|STR) `NIL` or the message to print in the status line. + +--- ## Term.App:\_DrawInfo(txt) -Prints the current info message if 'txt' is not specified, otherwise -replaces the message with 'txt' and prints it. +**Utility method** that prints the current info message if `txt` is not specified, otherwise replaces the message with `txt` and prints it. -INPUT -txt : NIL or the message to print in the informations line. +**INPUT** + +- `txt` : (NIL|STR) `NIL` or the message to print in the informations line. + +--- ## Term.App:\_DrawWarning(txt) -Prints the current warning message if 'txt' is not specified, otherwise -replaces the message with 'txt' and prints it. +**Utility method** that prints the current warning message if 'txt' is not specified, otherwise replaces the message with 'txt' and prints it. -INPUT -txt : NIL or the message to print in the warnings line. +**INPUT** + +- `txt` : (NIL|STR) `NIL` or the message to print in the warnings line. + +--- ## Term.App:\_DrawMenuState(txt) -Prints the current menu's state if 'txt' is not specified, otherwise -replaces the message with 'txt' and prints it. +**Utility method** that prints the current menu's state if 'txt' is not specified, otherwise replaces the message with 'txt' and prints it. -INPUT -txt : NIL or the message to print in menu's state line. +**INPUT** + +- `txt` : (NIL|STR) `NIL` or the message to print in menu's state line. + +--- ## Term.App:MenuAdd(name, items) -Used to define a menu. +This method is used to define an application menu. -INPUT -name : menu's name -items : a table used to define submenus with the following fields: -command : the command string to type to recall this item -description : the item description to print in the menu -callback : callback to a function execute or a name of a submenu +**INPUT** -NOTES -If 'command' is an empty string the description is interpreted as a -menu header. +- `name` : (STR) The menu's name +- `items` : (TABLE) It's a table used to define the sub-menus, each entry must have the following fields: +- - `command` : (STR) The command string to type to recall this item +- - `description` : (STR) The item description to print in the menu +- - `callback` : (FUNC|STR) It's a callback to a function to execute when this item is selected, or a name of a submenu. + +**NOTES** + +If `command` is an empty string the description is interpreted as a menu header. + +--- ## Term.App:\_FixedWidth(txt, size, align) -Utility method to format the given to a defined 'size' and the passed -'align'ment by adding spaces. -If the string does not fit into the specified size it will be trunkated but -'«' and '»' symbols will be used as a visual feedback for the user. +**Utility method** to format the given `txt` to a defined `size` and the passed +`align`ment by adding spaces. +If the string does not fit into the specified size it will be trunkated but the characters `«` and/or `»` will be used as a visual feedback for the user. -INPUT -txt : text to process -size : target size -align : text alignment -\-1 : left aligned -0 : centered -1 : right aligned +**INPUT** -OUTPUT -result : the processed text +- `txt` : (STR) The text to process +- `size` : (STR) Target string size +- `align` : (NUM) Text alignment (`-1`: left aligned, `0`: centered, `1`: right aligned). + +**OUTPUT** + +- `result` : (STR) The processed text + +--- ## Term.App:alignNumber(value, decimals, size) -Returns the number 'value' as a string, right aligned, with a length of -'size' characters and 'decimals' decimal numbers. +Returns the number `value` as a string, right aligned, with a length of `size` characters and `decimals` decimal numbers. -INPUT -value : the value to format -decimals : number of decimal places -size : total size in characters +**INPUT** -OUTPUT -result : the processed 'value' as a string +- `value` : (NUM) The value to format and return as a string +- `decimals` : (NUM) Number of decimal places +- `size` : (NUM) Target converted string width in characters + +**OUTPUT** + +- `result` : (STR) The processed `value` number as a string + +--- ## Term.App:\_DrawMenuItems(menuEntry) -Utility method to draw the menu items of the given menu entry. +**Utility method** to draw the menu items of the given menu entry. -INPUT -menuEntry : the name of the menu to draw. +**INPUT** + +- `menuEntry` : (STR) The name of the menu to draw. + +--- ## Term.App:ShowMessage(txt, waitkey, wordwrap) This method is used to show a message to the user. -INPUT -txt : the message to display -waitkey : True to wait for a keypress before continuing -wordwrap : True to enable the wordwrap for the text to display +**INPUT** + +- `txt` : (STR) The message to display +- `waitkey` : (BOOL) Set to `True` to wait for a keypress before continuing +- `wordwrap` : (BOOL) Set to `True` to enable the wordwrap for the text to display + +--- ## Term.App:GridView(data, columns, headers, positions, callback, info, formats) Display data in a scrollable grid. -INPUT -data : a table of all columns, each column with its data records -columns : a table with the column's names -headers : a table with the column headers -positions : a table with the column positions -callback : callback function to execute when a row is selected -info : custom information text -formats : optional table used to format the columns +**INPUT** + +- `data` : (TABLE) This is a table of all columns, each column with its data records +- `columns` : (TABLE) This is a table with the column's names (field names) +- `headers` : (TABLE) A table with the column headers (displayed column's names) +- `positions` : (TABLE) A table with the column horizontal positions +- `callback` : (FUNC) A callback function to execute when a row is selected +- `info` : (STR) Custom informative text +- `formats` : (TABLE) Optional table used to format the columns + +**NOTES** -NOTES To align a column name to the right add as first character the symbol '>'. -``` -Adding an additional position to the table 'positions' you can delimit the +Adding an additional position to the table `positions` you can delimit the last column size. Keys used to navigate the grid are hardcoded: +```plain s/S : Down one line/one page w/W : Up one line/one page d/D : Left one character/one column @@ -775,65 +819,82 @@ Keys used to navigate the grid are hardcoded: Q : Exit the grid view ``` +--- + ## Term.App:ShowInput(txt, req) Shows an input requester. -INPUT -txt : the text to print as explanation of the request -req : the prompt text +**INPUT** -OUTPUT -answer : the user's typed text +- `txt` : (STR) The text to print as explanation of the request +- `req` : (STR) The prompt text + +**OUTPUT** + +- `answer` : (STR) The user's typed text + +--- ## Term.App:ShowMenu(menuEntry) Method used to show a menu and to handle the user's input. -INPUT -menuEntry : name of the menu to print +**INPUT** + +- `menuEntry` : (STR) Name of the menu to print + +--- ## Term.App:Progress(txt, vcurr, vmax) Method used to show and update a progress bar in the status line. -INPUT -txt : text to display at the left of the progress bar -vcurr : current value -vmax : max value +**INPUT** + +- `txt` : (STR) Text to display at the left of the progress bar +- `vcurr` : (NUM) Current value +- `vmax` : (NUM) Maximum value + +--- ## Term.App:Start(menuEntry) -Starts the application showing the menu entry specified as its first -menu. +Starts the application showing the menu entry specified as its first menu. -INPUT -menuEntry : the name of the first menu to display. +**INPUT** -## CHANGE LOG +- `menuEntry` : (STR) The name of the first menu to display. -1.7 -Moved some internal docs into a separated Ansi.readme file that also +--- + +# CHANGE LOG + +- 1.7 +- - Moved some internal docs into a separated Ansi.readme file that also contains the documentation. -Fixed 'Term.SetTermSize()' function that was not complete. -1.6 -Replaced all DebugPrint with ConsolePrint -Replaced all DebugPrompt with ConsolePrompt -Fixed Term.GetSize() that was not initializing correctly the terminal +- - Fixed `Term.SetTermSize()` function that was not complete. +- 1.6 +- - Replaced all `DebugPrint` with `ConsolePrint` +- - Replaced all `DebugPrompt` with `ConsolePrompt` +- - Fixed `Term.GetSize()` that was not initializing correctly the terminal size under Linux systems. -1.5 -Updated the .Test() function and added the GridView() control. -Fixed a bug in Term.Print() that was causing an infinite loop. -1.4 -Term.App:\_FixedWidth(txt, size, align) -Added support for center alignment -1.3 -Several improvements in terminal functions -1.2 -Added Ansi.Set(value, termSize) Terminal size is used by the drawing +- 1.5 +- - Updated the `.Test()` function and added the `GridView()` control. +- - Fixed a bug in `Term.Print()` that was causing an infinite loop. +- 1.4 +- - In `Term.App:\_FixedWidth(txt, size, align)` was added support for center alignment +- 1.3 +- - Several improvements in terminal functions +- 1.2 +- - Added `Ansi.Set(value, termSize)`, Terminal size is used by the drawing functions and the wordwrap functions. -Added Ansi.Draw() to draw lines. -Removed Ansi.Draw() and replaced with specific functions to draw +- - Added `Ansi.Draw()` to draw lines. +- - Removed `Ansi.Draw()` and replaced with specific functions to draw lines, empty boxes and filled boxes. -1.1 -Added a check to avoid error printing non-UTF8 characters. \ No newline at end of file +- 1.1 +- - Added a check to avoid error printing non-UTF8 characters. + +--- + +---