dialogs.rb

# Author

    Jeff Clement, Bluesine
    http://www.bluesine.com/archives/software/ruby

# Synopsis

    require "dialogs"
    dlg=Dialogs::Dialog.new("Sample Application")
    dlg.msgbox("Hello World")
    dlg.infobox("Good-bye")
    dlg.clean
    # a complete example is included with distribution.

# Description

Class `Dialog` is a simple interface to the Unix Dialog program by Savio Lam and Stuart Herbert. I think Dialog is an awesome way of building simple user interfaces. This library is written to look similar to the Python wrapper for Dialog written by Robb Schecter.

# Instance Methods

`Dialog#initialize(title)`

  Takes one parameter defining the title of the application ( will be on the top of all Dialog windows ). Also does a quick search to find location of Dialog program.

`Dialog#clear`

  Clears the screen by calling 'Dialog --clear'. This will not reset things like the background color.

  `d.clear()`

`Dialog#superclear`

  Clears the screen by calling 'Dialog --clear'. Then calling 'clear' and finally 'stty sane'. This will make sure the terminal is cleaned up and working.

  `d.superclear()`

`Dialog#msgbox (text, height=10, width=40)`

  Display a simple message box of given width and height (in characters) on the screen.

  `d.msgbox("This is a test")`

`Dialog#yesno (text, height=10, width=40)`

  Display a yesno box prompting user with a question. Returns true if the user selects yes or false otherwise.

  `isGreat=d.yesno("Is this great?")`

`Dialog#inputbox (text, init='', height=10, width=40)`

  Display a input box with a text prompt given an initial string. Returns array with [ERRNUM, [USERINPUT]].

  `name=d.inputbox("What is your name?")[1][0]`

`Dialog#textbox (file, height=20, width=60)`

  Display a given file in a textbox.

  `d.textbox("/etc/passwd")`

`Dialog#menu (text, items, height=15, width=60)`

  Display a menu from a list of items. Will return an array of the form [ERRNUM, CHOOSENOBJECT]. The objects can be of anytype as long as they have a valid to_s method (ie. not limited to strings!)

  `favColor=d.menu("Favorite color", %w{red green blue orange})[1]`

`Dialog#checklist (text, items, selected=[], height=15, width=60)`

  Display a list of items ( of any type ) as a series of checkboxes. Returns array with [ERRNUM, [CHECKED ITEM1, CHECKED ITEM2...]]. The optional array selected defines default values (any objects which appear in the list are checked).

  `favColors=d.checklist("Favorite color(s)", %w{red green blue orange},'red')`

`Dialog#radiolist (text, items, selected=nil, height=15, width=60)`

  Display a list of items ( of any type ) as a series of radioboxes. Returns array with [ERRNUM, CHECKEDITEM]. The optional selected value defines the default object (if any).

  `favColor=d.radiolist("Favorite color", %w{red green blue orange},'red')`

`Dialog#scrollbox(title, text, height=20, width=60)`

  Display large multiline messages using a textbox by writing text to a tempfile and calling textbox function. Requires a title. If passed an Array it will write each element to it's own line. Otherwise it will just write to object to the file directly using it's own to_s function.

  `d.scrollbox("Title", "Hello\nWorld\n123")`

# ToDo

- implement some reasonable version of the gauge
- better documentation
- proper terminal dimensions

# License

This software is distributed under the Bluesine public license. See included LICENSE file or <URL:http://www.bluesine.com/license>.

# Version Info

$Id: dialogs.rb,v 1.1 2001/01/01 23:28:35 jsc Exp jsc $