NAME
Tui - Text user interface toolkitSYNSOPSIS
#!/usr/bin/perl
use Curses;
use Tui;
Tui::init;
Tui::background;
refresh;
Tui::msgbox("Title","Message");
my ($label) = new Tui::Label("Label",2,2);
my ($entry) = new Tui::Entryfield("Name",2,4,20,20);
my ($ok) = new Tui::Button("OK",18,5);
my ($form) = new Tui::Form("A form",1,1,27,10,1);
$form->add($label,$entry,$ok);
my ($result,$widgetno) = $form->run;
my ($name) = $entry->data;
endwin;
print "your name is $name\n";GENERAL FUNCTIONS
Described here are some general functions which can be used in a script. They're also used within the other objects.
Tui::init
Initializes some stuff needed for operating the Tui toolkit.
Tui::background
Tui::drawbox
Draws a box.
- Input Parameters
-
1 x1,y1 topleft coordinate 3 x2,y2 bottomright coordinate 4 color 6 style raised or lowered 7 window (defaults to stdscr) 8 keepclear, if true doesn't clear inside - Output Parameters
-
1 none
Tui::xyprint
Prints a line on a certain position in a certain color.
- Input Parameters
-
1 x coordinate where to print 2 y coordinate where to print 3 line, the text to print 4 color, (defaults to 1) 5 bold, flag whether to use bold - Output Parameters
-
1
Tui::vscrollbar
Draws a vertical scrollbar
- Input Parameters
-
1 x coordinate at the top 2 y coordinate at the top 3 height, the height 4 total, the total of the scale 5 pos, position of thumbnail within the scale 6 color (defaults to 1) 7 win (defaults to stdscr) - Output Parameters
-
1 none
Tui::hscrollbar
Draws a horizontal scrollbar
- Input Parameters
-
1 x coordinate at the left 2 y coordinate at the left 3 length, the length 4 total, the total of the scale 5 pos, position of thumbnail within the scale 6 color (defaults to 1) 7 win (defaults to stdscr) - Output Parameters
-
1 none
Tui::getkey
Retrieves the keycode and key.
- Input Parameters
-
1 none - Output Parameters
-
1 key, contains the actual key 2 keycode, contains a code for special keys - Keycodes
-
1 home 2 insert 3 delete 4 end 5 pageup 6 pagedown 7 up 8 down 9 right 10 left 11 backspace 12 M-q 13 M-b 14..M-d 15 M-v 16 M-< 17 M-> 18 M-h 19 M-x 20 M-f 21 M-i 22 M-w 23 M-a 24 M-e 50 M-enter 200 $key gives the keypress as a character
Tui::msgbox
Draws a message box with an OK button.
Tui::yesnobox
Draws a dialog with Yes and No buttons.
Tui::okcancelbox
Draws a dialog box with OK and Cancel buttons
Tui::entrybox
Provide a simple dialog to enter a string.
- Input Paramters
-
1 title 2 label text 3 prompt 4 length of the entrypart (defaults to 20) 5 maxlength of the entry (defaults to 20) 6 whether it is a password (* will be echoed) 7 whether to use a cancel button 8 default text (optional) - Ouput Parameters
-
if no cancel button : 1 the entry otherwise 1 the entry 2 result (1 = ok, 0 is cancel pressed)
CLASS Tui::Widget
an abstract class from which all other widgets are derived
Tui::Widget::new
Constructor
Tui::Widget::exitonaltx
Sets the flag that will make the widget exit when alt-X is pressed
Tui::Widget::exitonalth
Sets the flag that will make the widget exit when alt-H is pressed
Tui::Widget::exitonaltenter
Sets the flag that will make the widget exit when alt-enter is pressed
Tui::Widget::exitonenter
Sets the flag that will make the widget exit when enter is pressed
Tui::Widget::setwin
Sets $self->{win} to a supplied window.
Tui::Widget::runnable
returns whether this widget is runnable, labels and boxes are not.
CLASS Tui::Label
Provides a label widget. It can contain several newlines as long as it fits within the provided coordinates.
Inherits from "CLASS Tui::Widget".
Tui::Label::new
Constructor of this class.
- Input Paramters
-
1 text which is to be printed 2,3 x,y coordinates 4 color (defaults to 1) - Ouput Parameters
-
1 reference to object
Tui::Label::draw
Draws the widget.
Tui::Label::runnable
Returns whether widget is runnable.
CLASS Tui::Box
A box, does nothing besides being boxlike;)
Inherits from "CLASS Tui::Widget".
Tui::Box::new
Constructor for the box widget
- Input Paramters
-
1 x coordinate of left top 2 y coordinate of left top 3 number of columns 4 number of rows 5 color 6 style (raised or lowered) - Ouput Parameters
-
1
Tui::Box::draw
Draws the box
CLASS Tui::Button
A pushbutton widget.
Inherits from "CLASS Tui::Widget".
Tui::Button::new
Constructor of the Button widget.
- Input Paramters
-
1 text of label 2 x coordinate 3 y coordinate - Ouput Parameters
-
1 reference to object
Tui::Button::draw
Draws the actual button widget.
- Input Paramters
-
1 boolean whether the widget has the focus 2 boolean whether it is pushed - Ouput Parameters
-
1 reference to object
Tui::Button::push
Pushes the button, prints it depressed, waits a bit and then redraws it.
Tui::Button::run
Actually run the widget
CLASS Tui::Checkbox
This widget provides a checkbox
Inherits from "CLASS Tui::Widget".
Tui::Checkbox::new
Constructor of the checkbox widget.
- Input Paramters
-
1 label to be used 2 x coordinate 3 y coordinate 4 if true, the checkbox will be checked - Ouput Parameters
-
1 reference to the object
Tui::Checkbox::draw
Draw the checkbox widget
Tui::Checkbox::select
Toggles the checkbox
Tui::Checkbox::run
Runs the checkbox widget
Tui::Checkbox::data
Returns a boolean whether the checkbox is checked
CLASS Tui::Radiobutton
A radiobutton widget
Inherits from "CLASS Tui::Widget".
Tui::Radiobutton::new
Radiobutton widget constructor
Tui::Radiobutton::setgroup
Sets the group to which this radiobutton belongs
Tui::Radiobutton::draw
Draws the widget
- Input Paramters
-
1 boolean whether the widget has the focus - Ouput Parameters
-
1 refernece to the object
Tui::Radiobutton::select
Select the radio button, also unsets the selected one in the radiogroup
Tui::Radiobutton::isselected
Returns whether this radiobutton is selected.
Tui::Radiobutton::set
Set the button to on or off
Tui::Radiobutton::run
Run the radiobutton widget, it makes no sense to use this on its own. You need a radiogroup with it to make any use of it.
Tui::Radiobutton::data
Retrieve whether this button was selected.
CLASS Tui::Radiogroup
A class to group radiobuttons together
Doesn't inherit from anything.
Tui::Raduigroup::new
Constructor for the radiogroup widget
- Input Parameters
-
1 list of readiobutton widgets to add to group - Output Parameters
-
1 reference to the object
Tui::Radiogroup::add
Add radiobuttons to the group.
- Input Parameters
-
1 list of radiobuttons to add to the group - Output Parameters
-
1 reference to the object
Tui::Radiogroup::set
Set a certain radiobutton within the group as selected.
- Input Parameters
-
1 index of the radiobutton to be selected - Output Parameters
-
1 reference to the object
Tui::Radiogroup::redraw
Redraws the radiobuttons within the group
Tui::Radiogroup::data
Return the index of the radiobutton that is selected.
CLASS Tui::Listbox
This is a listbox widget. It will draw scrollbars if need be (and allowed).
Inherits from "CLASS Tui::Widget".
Tui::Listbox::new
Constructor for the listbox widget.
- Input Paramters
-
1 label to print in the top 2 x coordinate of lefttop 3 y coordinate of lefttop 4 columns of the box 5 rows of the box - Ouput Parameters
-
1 reference to the object
Tui::Listbox::add
Add some entried to the listbox.
Tui::Listbox::setscrollbars
Turns both scrollbars on or off (they'll only be drawn if necessary)
Tui::LIstbox::sethscrollbar
Turns the horizontal scrollbar on or off
- Input Paramters
-
1 boolean whether to turn the scrolbar on or off - Ouput Parameters
-
1 refernece to the object
Tui::LIstbox::setvscrollbar
Turns the vertical scrollbar on or off
- Input Paramters
-
1 boolean whether to turn the scrolbar on or off - Ouput Parameters
-
1 refernece to the object
Tui::Listbox::setdrawbox
Turns on or off the drawing of a box.
Tui::Listbox::setwraparound
Sets whether the widget will wrap around or not. Defaults to off.
Tui::Listbox::set
Set the selected entry
Tui::Listbox::reset
Clears the contents of the list box
Tui::Listbox::run
Runs the listbox widget
Tui::Listbox::data
Returns the index of the selected entry
CLASS Tui::Mlistbox
This widget is very much like the listbox widget, except that it allows multiple selections.
Inherits from "CLASS Tui::Listbox".
Tui::Mlistbox::new
Constructor for the multiple selection listbox widget.
(inherited from "CLASS Tui::Listbox").
- Input Paramters
-
1 label to print in the top 2 x coordinate of lefttop 3 y coordinate of lefttop 4 columns of the box 5 rows of the box - Ouput Parameters
-
1 reference to the object
Tui::Mlistbox::add
Add some entried to the multiple selction listbox.
Tui::Mlistbox::set
Set the entries which are to be selected.
- Input Paramters
-
1 list of indeces that are to be selected - Ouput Parameters
-
1 reference to the object
Tui::Mlistbox::draw
Draws the multiple selction listbox widget
- Input Parameters
-
1 boolean whether the widget has the focus - Output Parameters
-
1 reference to the object
Tui::Mlistbox::run
Runs the multiple selection listbox widget
Tui::Mlistbox::data
Return a list of indeces of the selected entries
CLASS Tui::Dropbox
This widget is sometimes also known als a combobox. When it recieved the focus, a listbox will dropdown where the user can make a choice. The only restriction is that the dropbox MUST fit into the Form where it is used when used within a form.
Inherits from "CLASS Tui::Widget".
Tui::Dropbox::new
Contructor for the dropbox widget
- Input Paramters
-
1 x coordinate of the left top 2 y coordinate of the left top 3 width of the widget 4 heigth of the dropbox (defaults to 6) - Ouput Parameters
-
1 reference to the object
Tui::Dropbox::add
Adds a list of entries to the dropbox
Tui::Dropbox::setwraparound
Sets whether the widget will wrap around or not. Defaults to off.
Tui::Dropbox::set
Set the selction in the dropbox.
Tui::Dropbox::setscrollbars
Turns on or off both scrollbars (they're on by default but will only be drawn if needed).
- Input Parameters
-
1 boolean whether to turn them on or off - Output Parameters
-
1 reference to the object
Tui::Dropbox::sethscrollbar
Turn on or off the horizontal scrollbar (it's on by default)
Tui::Dropbox::setvscrollbar
Turn on or off the vertical scrollbar (it's on by default)
Tui::Dropbox::draw
Draws the dropbox widget
- Input Parameters
-
1 boolean indicating whether this widget has the focus - Output Parameters
-
1 reference to the object
Tui::Dropbox::run
Runs the dropbox widget
Tui::Dropbox::data
Returns the index of the selected entry
CLASS Tui::Entryfield
A widget for entering text. The entered line can be longer than would fit in the widget, it'll scroll as need be.
Inherits from "CLASS Tui::Widget".
Tui::Entryfield::new
Constructor
- Input Paramters
-
1 label to print before entryfield 2 x coordinate 3 y coordinate 4 length of the widget 5 maximum length of the text 6 default text - Ouput Parameters
-
1 reference to the object
Tui::Entryfield::set
This will set the default text of the entryfield widget.
Tui::Entryfield::draw
Acutally draws the widget.
Tui::Entryfield::drawtext
This draws the actual text.
Tui::Entryfield::run
Runs the widget.
Tui::Entryfield::data
Retrieve the data entered in the widget.
CLASS Tui::Passwordfield
A widget for entering passwords. Provides pretty much the same functionality as the Entryfield widgets, except that entered characters are shown with a '*'.
Inherits from "CLASS Tui::Entryfield".
Tui::Passwordfield::new
Constructor
- Input Paramters
-
1 label to print before entryfield 2 x coordinate 3 y coordinate 4 length of the widget 5 maximum length of the text 6 default text - Ouput Parameters
-
1 reference to the object
CLASS Tui::Spinner
This widget is a spinner, it contains a value and can be in-/decreased with the cursor keys.
Inherits from "CLASS Tui::Widget".
Tui::Spinner::new
Constructo for the spinner widget.
- Input Paramters
-
1 label 2 x coordinate 3 y coordinate 4 width 5 value - Ouput Parameters
-
1 reference to object
Tui::Spinner::setstep
Sets the step value of a spinner widget.
Tui::Spinner::setlimits
Sets the floor and ceiling value of a spinner widget.
Tui::Spinner:set
Set the value of the spinner.
Tui::Spinner::data
Retireves the value of the widget
Tui::Spinner::draw
Actually draws the widget.
Tui::Spinner::run
Runs the spiner widget
CLASS Tui::Viewarea
This is a widget that'll show some text. The text can be larger than the widget, it provides scrollbars if need be.
Inherits from "CLASS Tui::Widget".
Tui::Viewarea::new
Constructor for the viewarea widget.
- Input Paramters
-
1 x coordinate of left top 2 y coordinate of left top 3 number of collumns 4 number of rows 5 boolean whether to draw a border - Ouput Parameters
-
1 reference to the object
Tui::Viewarea::set
Sets the text of the viewarea widget
- Input Paramters
-
1 text in 1 string, it'll be split on newlines - Ouput Parameters
-
1 reference to the object
Tui::Viewarea::sethscrollbar
Turns horizontal scrollbar on or off.(defaults to on)
Tui::Viewarea::setvscrollbar
Turns vertical scrollbar on or off.(defaults to on)
Tui::Viewarea::setpos
Turns on or off the position (percent) indicator for the widget It defaults to on.
Tui::Viewarea::draw
Draws the viewarea widget.
Tui::Viewarea::movecursor
Moves the cursor a supplied amount.
Tui::Viewarea::run
Actually runs the widget.
CLASS Tui::Editarea
This widget is a small editor. It provides some basic editor functionality. The following keys are supported:
cursor keys : movement
alt-a : beginning of line
alt-e : end of line
backspace : delete the character before the cursor
alt-d : delete the character at the cursor
tab : move on to the next widgetInherits from "CLASS Tui::Widget".
Tui::Editarea::new
Constructor for the Editarea widget
- Input Paramters
-
1 x coordinate of left top 2 y coordinate of left top 3 number of collumns 4 number of rows 5 whether to draw a border - Ouput Parameters
-
1 reference to object
Tui::Editarea::set
Sets the default text in the editarea.
Tui::Editarea::sethscrollbar
Turns horizontal scrollbar on or of (defaults to on)
Tui::Editarea::setvscrollbar
Turns vertical scrollbar on or of (defaults to on)
Tui::Editarea::setpos
Turn on or off the position indicator (on by default)
Tui::Editarea::data
Returns the text as 1 string
Tui::Editarea::draw
Draws the editarea widget.
- Input Parameters
-
1 boolean whether the widget has the focus 3 boolean whether to NOT clear the inside (just redraw the border and scrollbars) - Output Parameters
-
1
Tui::Editarea::redrawtext
Redraws the text, not the box and possible scrollbars.
Tui::Editarea::adjustxspo
Adjust xpos and xstart if needed. Makes sure that the current cursor position is within the view
Tui::Editarea::insertnewline
Insert a newline at the cursor.
- Input Parameters
-
1 x coordinate 2 y coordinate 3 boolean whether to leave xpos and ypos (for fute extension) - Output Parameters
-
1 reference to the object
Tui::Editarea::insertchar
Insert a character at the cursor taking into account the insertmode
Tui::Editarea::backspace
Delete the character before the cursor
Tui::Editarea::delchar
Delete a character at the cursor
Tui::Editarea::movecursor
Move the cursor within the editarea according to 2 delta's
Tui::Editarea::run
Actuall run the editarea widget
CLASS Tui::Menu
A sub menu widget. This is used by "CLASS Tui::Menubar".
Inherits from "CLASS Tui::Widget".
Tui::Menu::new
Constructor for the menu widget, this is actually meant as a sub menu.
- Input Paramters
-
1 x coordinate of the left top 2 y coordinate of the left top 3 window of the parent 4 list of entries to put in menu - Ouput Parameters
-
1 reference to the object
Tui::Menu::draw
Draws the Menu widget. You shouldn't need to call this, the run method will.
Tui::Menu::run
Actually runs the sub menu.
- Input Paramters
-
1 none - Ouput Parameters
-
1 result of the window which can be 1 of the following 1 entry was selected 2 menu is closed now 3 we moved right 4 we moved left 2 last chosen entry
Tui::Menu::hide
Hide the submenu. You shouldn't need to call this normally.
CLASS Tui::Menubar
The name says it all, this is a menubar.
Inherits from "CLASS Tui::Widget".
Tui::Menubar::new
Constructor for the menubar widget.
- Input Paramters
-
1 x coordinate of left top (default 0) 2 y coordinate of left top (default 0) 3 cols (default whole screen width) - Ouput Parameters
-
1 reference to the object
Tui::Menubar::add
Adds a menu to the menubar.
- Input Paramters
-
1 name of the submenu 2..N list of entries in the submenu - Ouput Parameters
-
1 reference to the object
Tui::Menubar::reset
Clears all the menus in the bar.
Tui::Menubar::draw
Draws the menubar.
- Input Paramters
-
1 boolean whether the menubar has the focus 2 index of the menu that is opened (and there's no focus) - Ouput Parameters
-
1 reference to the object
Tui::Menubar::openmenu
Opens a submenu
- Input Paramters
-
1 none - Ouput Parameters
-
1 result that came back from the submenu 2 entry that came back from the submenu
Tui::Menubar::run
Runs the menubar, basically keeps running it until you make a choice.
- Input Paramters
-
1 none - Ouput Parameters
-
1 index of the menu you chose from 2 index of the entry within the sub menu
CLASS Tui::Form
Class which provides a dialog form. Widgets can be added to it after which it can be run. When it exits, the content of the widgets can be retrieved.
Tui::Form::new
Tui::Form contructor
- Input Paramters
-
1 title of the form 2 x coordinate of left top 3 y coordinate of left top 4 number of collumns 5 number of rows 6 boolean whether to center window 7 boolean whether to exit on alt-enter (default false) 8 boolean whether to exit on alt-x (default false) 9 boolean whether to exit on alt-h (default false) - Ouput Parameters
-
1 reference to object
Tui::Form::add
Add widgets to a form. The order in which they are added also sets the tab order. The first widget to be added gets the focus first. (unless Tui::Form::setfocus is used).
Tui::Form::setfocus
Sets the initial focus to the widget as supplied by index
- Input Paramters
-
1 index of the widget to get initial focus - Ouput Parameters
-
1 reference to the object
Tui::From::draw
Draw a form, draws the form and makes each widget draw itself.
Tui::Form::xyprint
Prints a string in a form.
- Input Paramters
-
1 text 2 x coordinate 3 y coordinate 4 color 5 boolean whether to do it bold - Ouput Parameters
-
1 reference tot he object
Tui::Form::xyprintchar
Prints a character in a form.
- Input Paramters
-
1 character 2 x coordinate 3 y coordinate 4 color 5 boolean whether to do it bold - Ouput Parameters
-
1 reference tot he object
Tui::From::getwin
Returns the window in which th form operates.
Tui::From::run
Runs the form.
- Input Paramters
-
1 boolean whether to leave the dialog after run returns. - Ouput Parameters
-
1 resultcode 2 widgetnumber The result can be anyone of : 8 enter pressed 9 alt-x pressed 10 alt-h pressed 11 alt-enter pressed
Tui::Form::hide
Hide the form dialog.
AUTHOR
Written by Ronald F. Lens ( ronald@ronaldlens.com )
HOMEPAGE
The home page is at http://www.ronaldlens.com/tui.html
TODO
Finish pod documentation, perhaps a tutorial.
Document the code more itself (don't know whether I'll understand it
myself in time;).
Navigating between the widgets with cursor keys where possible.
Clean up the code (there is a lot of duplicate code)
Make use of hardware scrolling in windows.
Use the panel library, overlapping windows!
Dialog builder.
Get the code to live through a use strict;)HISTORY
- Version 0.3 August 20th, 1999
-
Added "CLASS Tui::Menu" and "CLASS Tui::Menubar" classes
- Version 0.4 August 20th, 1999
-
Added Tui_Form_xyprint and Tui_Form_xyprintchar method
Added Tui_Form_setfocus method.
Added a lot of poddocs.
Fixed some small bugs in the default dailogs (they didn't return the correct values)
- Version 0.2 August 19th, 1999
-
Added Tui_Listbox_reset method.
Fixed some bugs with misspelled variable names.
- Version 0.1 August 17th, 1999
-
Finished initial version, added lots of poddoc.