RBCURSE Tutorial
Prev:   Next: Buttons

The following is a simple introduction to rbcurse 1.1.x, a ruby ncurses windowing toolkit to create “graphical” user interfaces for terminals or character based interfaces. For more details, please refer examples in the examples folder of the distribution. The github page is here. Check the various branches.


It is best to have ruby 1.9.1 (latest) installed. If you are using 1.8.7 and you face any issues, please report. If you use both versions, you will have to install both gems under both version. (sudo is for OS X machines)

rbcurse can be installed as follows:

sudo gem install ncurses

Usually this gives a problem. If so, please download the ncurses-0.9.1.gem from here.

sudo gem install --local ncurses-0.9.1.gem

Please run the examples to ensure that ncurses itself is functional. You may also try http://trickyco.de/tag/ncurses. Now you may install rbcurse, preferably version 1.1.2 or higher.

sudo gem install rbcurse

Please try out some examples, preferable test2.rb in the examples directory.

cd examples
ruby test2.rb

Here’s a screenshot of test2.rb. At this point, you have a working version of rbcurse.

Basic Setup

The following are the minimal requires for a program. Since rbcurse logs internally, a logger must be instantiated. rwidget contains some basic widgets such as field, button and label.

require 'ncurses'
require 'logger'
require 'rbcurse'
require 'rbcurse/rwidget'

Curses setup

This initializes colors, keys and various other setting such as delay, cbreak etc so that control and other keys may be used.


Creating a root window

Typically for an application, you wish to start with a full screen. We use the window class for that.

@window = VER::Window.root_window

A window may be written to as follows. The parameters are row, column, string to print, color, and attributes. Other colors that have been created include: errorcolor, promptcolor, reversecolor. See colormap.rb.

@window.printstring 0, 30, "Demo of Ruby Curses Widgets - rbcurse", $normalcolor, 'reverse'

Attributes are: bold, reverse, normal and underline. blink is present but does not work. underline does not work on a few terminals.

Note that only static text is written directly to a window. This text could get overwritten or erased by another field or print statement. What that means is that for most other purposes a label is recommended. A labels color or text or attribute or alignment or position can be changed at any time, whereas static text cannot be changed.

The other function of a form is to accept keyboard input in the outer loop and despatch it to the form. The window takes care of decoding function keys and multiple key codes, meta or escape combinations, so a form or component never has to decode.

  while((ch = @window.getchar()) != KEY_F1 )

The above accepts all keys, but exits on an F1. Remember to call window.destroy at the end, so that all ncurses windows, panels etc may be destroyed. This is essential when one window creates another window as not releasing panels could result in a crash.


Typically we want more control over what is printed. We want user entry and navigation. Thus one or more forms may be created using a window. A form uses a window to write to. It is a container for various components.

  @form = Form.new @window

Within the outer loop, the form handles each key, sending it to the relevant component for further handling.


Only if a key is unhandled by the focused component, does the form process it. Actions may be mapped to keystrokes caught by all components and the Form too. Actions may be bound to Form events, too. (XXX)

Form events include ENTER and LEAVE. These actually apply to all components of a form. This allows us to attach an action to all fields of a form on entry and exit of that component. This can be used to change the background of the label of the focused field as in test2.rb, or to save values to a structure etc.

  @form.bind(:ENTER) { |f|   f.label && f.label.bgcolor = 'red' if f.respond_to? :label}
  @form.bind(:LEAVE) { |f|  f.label && f.label.bgcolor = 'black'   if f.respond_to? :label}


A label is a dynamic piece of text. Its may be changed in many ways once created. Changed can be triggered from other fields.

  colorlabel = Label.new @form, {'text' => "Select a color:", "row" => 2, "col" => 10, "color"=>"cyan", "mnemonic" => 'S'}

In the example, a mnemonic has been set. Alt-s will put the focus on the field or widget that this focus has been attached to using label_for. Other settings are self-explanatory. A label may be multi-line, is may be aligned right or left or center, any of its attributes may be changed at any time, including location (although that’s rare, but mentioned to emphasize that unlike ncurses, all widgets may be created or modified at any time).

Fields (Text fields)

An entry field may be created as follows.

    field = Field.new @form do
      name   "Name"
      row  5 
      col  12 
      display_length  30
      set_label Label.new @form, {'text' => "Name", 'color'=>'cyan','mnemonic'=> 'N'}

The above shows some very basic settings of a field. There are plenty more which are used in the examples, such as test2.rb. This example shows creating a label along with the field. The label is automatically attached to the field, so that the mnemonic key puts focus onto the field. A label may be attached later, too. Other widgets may not have a set_label, so label_for may be used to attach to them.

The above has been put together in prog1.rb in which several fields are created in a loop. You may traverse using tab and back-tab as well as the mnemonics. Not much else you can do since this is the very basic screen.

Other Field properties

Field has many properties, some of them are mentioned here.

For example of usage of these properties, see test2.rb


Prev: Home Next: Buttons