Ruby-FLTK API Reference
Last updated September 9, 2001

0. Introduction

One of the goals of the Ruby-FLTK project is to retain close 
compatibility with the underlying C++ API. Whenever possible, 
the Ruby function signatures are identical to those in C++. 
This allows Ruby users to rely on the C++ API reference in 
most cases.

Another goal of the project is to provide a better API than 
the original. This is done by providing additional signatures 
to existing methods, adding duplicate names for some methods, 
adding some new methods, and adding entirely new classes.

1. Widget Hierarchy and Naming

1.1 Widget Hierarchy

Ruby-FLTK (with FLTK-1.0.11) provides this hierarchy of widgets:

 Widget
  Box
  Browser_
   Browser
    HoldBrowser
    MultiBrowser
    SelectBrowser
  Button
   CheckButton
   LightButton
   RadioButton
   RepeatButton
   ReturnButton
   RoundButton
  Chart
  Clock
  Free
  Group
   ColorChooser
   Pack
   Scroll
   Tabs
   Tile
   Window
    DoubleWindow
	GlWindow
	MenuWindow
	OverlayWindow
	SingleWindow
  Input_
   Input
    FloatInput
    IntInput
	MultilineInput
	SecretInput
   Output
    MultilineOutput
  Menu_
   Choice
   MenuBar
   MenuButton
  Positioner
  Timer
  Valuator
   Adjuster
   Counter
   Dial
   Roller
   Slider
    Scrollbar
    ValueSlider
   ValueInput
   ValueOutput
   
There is also one class which is not a widget:

 MenuItem

1.2 Terminology and Other GUI Toolkits

Different GUI toolkits use different names for the same widgets. To 
ease the transition from other toolkits, here is a list of some 
common widget names and their Ruby-FLTK names:

 Canvas:        n/a (closest is DoubleWindow)
 Checkbox:      CheckButton
 ComboBox:      n/a (closest is Choice or maybe MenuButton)
 Component:     Widget
 Container:     Group
 Control:       Widget
 Dialog:        Window
 Frame (Java):  Window
 Frame (GTK+):  Box
 HBox:          Pack
 Label:         Box
 Listbox:       Browser
 Packer:        n/a (closest is Pack or Group)
 PasswordField: SecretInput
 PropertySheet: Tabs
 PushButton:    Button
 ScrollPane:    Scroll
 Splitter:      Tile
 Static:        Box (text only)
 Table          Browser
 TextArea:      MultilineInput or MultilineOutput
 TextField:     Input
 VBox:          Pack
 
FLTK uses constant enumerated value for several concepts that are 
classes in other toolkits. These include:

 Colors
 Cursors
 Events
 Fonts


2. Alphabetical Class Reference

See also the Module Reference section

* Adjuster
  This is an unusual widget which shows three stacked double-arrow boxes
  that are adjustment buttons. One adjusts by units, another by tens, and 
  the third by hundreds. It looks best if either width=3*height or 
  height=3*width
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. 
    The label is never displayed.
    
  Methods:
   soft(value)
   value = soft
    These methods control the "soft" flag, which can be set to zero or 
    one (one is soft mode). In soft mode (the default), the user is 
    allowed to drag the value outside the range.
  
* Box
  This widget consists of an optional drawn border, and an optional text 
  label. It can be used to simply display some text, or to draw a visible 
  frame around other widgets.
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. 
    **NOTE** The C++ constructor that allows you to pass a boxtype is 
    not supported. You must call boxtype after the object is created.
    
  Methods:
   (none)

* Browser
  This is a read-only list widget. It supports multiple columns, and 
  automatic scrollbars. Also see HoldBrowser and MultiBrowser.

* Browser_
  This is an abstract base class used by all the Browser classes. If you 
  are creating your own list widget, this might be the best starting 
  point.

* Button
  Provides standard push button functionality, and also serves as the 
  base class for other button types. By default, the callback will be 
  invoked whenever the button is clicked (released after being pressed).
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. 
    The label (if any) is displayed as the button text. If an & appears 
    in the label, the following letter will be used as a shortcut.
  
  Methods:
   clear
    Puts this button in an "unset" state. If this is a push button, it 
    will appear normal (not-pressed). Mostly useful for subclasses.
   down_box(boxtype)
   boxtype = down_box
    Gets or sets the boxtype used when the button is pressed. Only useful 
    to create custom button appearances.
   set
    Puts this button in a "set" state. If this is a push button, it 
    will appear pressed. Mostly useful for subclasses.
   setonly
    Puts this button in a "set" state, AND clears all other radio buttons 
    within the same Group. This should always be used for radio buttons.
   shortcut(key)
   key = shortcut
    Gets or sets the shortcut key for this button, overriding any & letter 
    used in the label. Usually the shortcut would be a lower-case ascii 
    letter, but shift flags can be masked in, such as: (FLTK::ALT | 'a').
    A value of zero disables the shortcut.
   button_type(t)
   t = button_type
    Gets or sets the button type. Legal values are:
       - 0                      normal
       - FLTK::TOGGLE_BUTTON    value is inverted
       - FLTK::RADIO_BUTTON     used by the setonly method
   value(v)
   v = value
    Gets or sets the button value, which is one (pressed/set), or zero 
    (not-pressed/unset). [We should probably drop this, and recommend 
    using clear, set, and set? instead. kbs]
   when(wh)
   wh = when
    Gets or sets the current when setting of this button. The default is 
    FLTK::WHEN_RELEASED. Other legal values are zero (no callbacks), and
    FLTK::WHEN_CHANGED (when the button is pressed or released).
   

* Chart
  Displays line, pie, and bar charts.

* CheckButton
  Standard checkbox that allows the user to toggle a value.

* Choice
  Allows the user to choose one item from a list, but the list is only 
  displayed when the user presses the Choice widget. Similar to a 
  drop-down listbox.

* Clock
  Displays a simple, round, analog clock that updates each second.
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. 
    The label is never displayed.
  
  Methods:
   h = hour
    Returns the current hour (0..23) displayed by this clock, which does
    not have to be the system time.
   m = minute
    Returns the current minute (0..59) displayed by this clock, which does
    not have to be the system time.
   s = second
    Returns the current second (0..59) displayed by this clock, which does
    not have to be the system time.
   value(ticks)
   value(h,m,s)
   ticks = value
    Gets or sets the current time displayed by this clock. To set the time ,
    either pass in a standard UNIX time value, or hours/minutes/seconds as 
    described above. Returns a standard UNIX time value.
   
* ColorChooser
  Standard RGB color chooser widget.

* Counter
  Widget that displays a value, with arrows on either side that allow the 
  user to adjust the value.

* Dial
  Displays a round knob that can display a value, and/or allow a user to 
  modify that value.

* DoubleWindow
  A double-buffered Window, useful for holding widgets that use a lot of 
  primative drawing. Uses operating system double-buffering where available 
  (Xdbe). If your output is flickering or slow, try using a DoubleWindow.

* FloatInput
  Subclass of Input that restricts the user to entering legal floating point 
  values. 

* Free
  [I don't think we should support this class. kbs]

* Gl_Window
  An OpenGL Window. Should be useful for 3-D drawing, shading, lighting, etc.

* Group
  Container of other widgets. This is the base class for Pack and Window 
  widgets, and would be used as the base class for any custom widgets that 
  actually consist of multiple widgets hooked together.
  
  It contains a single "resizable" widget, which may be nil. The rules for 
  how the resizable widget affects other widgets are somewhat complex, so 
  see the C++ FLTK documentation for details and examples.

* Hold_Browser
  This is a normal single-selection listbox, which allows multiple columns.
  Also see Browser.

* Input
  Standard single-line text entry widget.

* Input_
  Base class for all the Input (and Output) widgets. Useful for subclassing.

* IntInput
  Subclass of Input that restricts the user to entering legal decimal values 
  (or hex as 0xABC).

* LightButton
  Looks like a push button with a light on it. Acts like a checkbox, so the 
  light toggles on and off with each click of the button.

* Menu_
  A container of MenuItems, used as the subclass of Choice, MenuBar, and 
  MenuButton.

* MenuBar
  Standard menubar widget. Height should be 30 to display correctly with the 
  default font. [I don't think this is fully implemented yet. kbs]

* MenuButton
  A button that pops up a menu. A menubar usually consists of MenuButtons.

* MenuItem
  Represents a single choice that might appear in any menu, including the text 
  label, shortcut, callback, type, font, size, and color. [I don't think this 
  is fully implemented yet. kbs]
  
* MenuWindow
  Container used for popup menus.

* MultiBrowser
  Standard multi-select list box, that also allows multiple columns. Also 
  see Browser.

* MultilineInput
  Standard multi-line text editor, supporting newlines and tabs. [Does this 
  do word-wrapping? I think so? kbs]

* MultilineOutput
  Read-only multiline text display, supporting tabs and newlines.

* Output
  Single-line text output. Allows the user to copy data out of it, unlike 
  a simple Box.

* OverlayWindow
  A double-buffered window that supports an image being overlaid on top of it. 
  The overlaid image will use hardware support, if possible, to avoid having 
  to redraw the material underneath. 

* Pack
  Contains a horizontal or vertical stack of widgets. Makes them all the same 
  width (or height), and ensures that they do not overlap by setting their 
  positions, and can set fixed spacing between the widgets. Packs can be 
  nested to provide fairly complex layouts.

* Positioner
  Allows 2-D input, but doesn't seem to be useful, according to the C++ docs.

* RadioButton
  Simple radio button, implemented as a RoundButton that automatically sets the 
  type to FLTK::RADIO_BUTTON, and automatically sizes itself to match the text 
  label.

* RepeatButton
  A push button that generates repeating callbacks when it is held down.

* ReturnButton
  A push button that includes a return-arrow image, and which invokes its 
  callback when the Enter key is pressed.

* Roller
  An adjustment widget that looks something like a mouse wheel.

* RoundButton
  Looks like a radio button, but by default behaves like a push button. See 
  also RadioButton.

* Scroll
  A container widget that has scrollbar support. Makes it very easy to add 
  scrollbars to a dialog or any other widget that needs to display more 
  information that will fit on a screen.
  
* Scrollbar
  Standard scrollbar widget (horizontal or vertical). See also Scroll.

* SecretInput
  Subclass of input that displays asterisks (*) instead of the actual 
  characters being input. Useful for passwords.

* SelectBrowser
  Presents a list of items, and allows the user to select one, BUT as soon as 
  the mouse is released, the item is unselected. This behavior is similar to 
  Macintosh menus. See also HoldBrowser.

* SingleWindow
  Standard, unbuffered Window. Normally this is identical to Window, but on 
  some systems, double-buffering might be the default, so this class is 
  available to prevent double-buffering.

* Slider
  Similar to a scroll bar without the arrow buttons, this widget contains a 
  sliding knob. It can be used to adjust a value. Also see Scrollbar.

* Tabs
  Container used to create a tab-folder interface, like the ones often found 
  in configuration dialogs. Each child (usually a Group) becomes a card, and 
  the child's label is shown on the tab. This class manages the hide() and 
  show() calls for each child. Looks best with a boxtype of FLTK::THIN_UP_BOX 
  or FLTK::FLAT_BOX.

* Tile
  Container that allows its children to be resized by dragging the border 
  between them. It does not draw the border, so the children must specify 
  reasonable boxtypes to get the borders to look good. The borders between 
  ANY children are resizable, so a typical use of this would be to contain 
  just two child Groups.

* Timer
  [I don't think we should support this widget. kbs]

* Valuator
  Base class for various widgets that control a floating point value. See also 
  Adjuster, Counter, Dial, Roller, Slider, ValueInput, ValueOutput.

* ValueInput
  Displays a value and allows the user to edit it, or adjust it by dragging 
  the mouse around. See the C++ docs.

* ValueOutput
  Displays a value and allows the user to adjust it by dragging the mouse 
  around. See the C++ docs.

* ValueSlider
  This is a Slider that also contains a box that displays the current value, 
  either above or to the left of the slider.

* Widget
  Abstract base class for all the widget classes. 
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero.
    The use of label is determined by the subclass.
    
  Methods:
   activate
    Puts this widget into an active state, where it gets events.
   active
    Returns one if this widget is active, meaning it is getting events, or 
    zero if it is inactive. See also active_r().
   active_r
    Returns one if this widget and all its parents are active, meaning 
    they are getting events. See also active().
   align(a)
   a = align
    Gets or sets the alignment flag, used by subclasses to determine 
    where and how to display the label. The default is FLTK::ALIGN_CENTER.
   argument
   box(boxtype)
   boxtype = box
    Gets or sets the boxtype. This type determines what type of border 
    is drawn around this widget, and whether the background will be 
    erased or not. The default is FLTK::NO_BOX, which erases the 
    background but does not draw a border.
   callback(data=nil, &block)
   block = callback
    Gets or sets a callback block for this widget. How the callback is 
    used depends on the subclass, but typically it is called when the 
    widget is clicked or changed. The data will be passed as the 
    argument to the callback block when it is invoked. See the samples.
   changed
    Returns a flag (zero or one) indicating whether this widget has been 
    "changed" by the user. This is only used by subclasses. See also 
    set_changed() and clear_changed().
   clear_changed
    Clears the changed flag (to zero). See changed().
   clear_output
    Restores this widget to normal (non-"output") state, which means it 
    will be active. See also output() and set_output().
   color(c)
   c = color
    Gets or sets the color used to draw the background of the box for 
    this widget. Defaults to FLTK::GRAY, but can be any FLTK color.
   contains(widget)
    Returns one if this widget contains (or is) the passed widget.
    Otherwise returns zero.
   damage
    Returns a bitmask that can be used as a hint during draw(). Only 
    used by subclasses. [For this to be useful, we also need to expose 
    the protected method that sets the damage bits. kbs]
   deactivate
    Puts this widget into an inactive state, where it is still redrawn, 
    but does not get any events. Window objects may not be deactivated.
   default_callback
    [I don't think we implement this. kbs]
   do_callback
   do_callback(widget,data=nil)
    Invokes the callback block for this widget or the specified widget, 
    passing the data if given.
   draw
    Called by the system when this widget needs to draw itself. This 
    method should be overridden by custom widgets. Generally, draw()
    should NOT be called directly. If you need a widget to redraw itself, 
    you should call redraw() instead.
   h
    Returns the current height. Valid even if the widget is not shown.
   handle(et)
    Called by the system when an event is available for this widget. 
    The eventtype (e.g. FLTK::DRAG) is passed. Other event information 
    can be retrieved by calling FLTK module methods like FLTK::event_x().
    Custom widgets should override this if they are interested in 
    handling specific events. handle() MUST return true if the event 
    was handled and should not be passed to other widgets, or false 
    if the event should be offered to other widgets. Generally, you 
    would not call handle() directly.
   hide
    Make this widget non-visible. Do not call this unless the parent is 
    visible (see visible_r()). Automatically calls redraw on this widget 
    and/or its parent, as needed.
   inside
    Returns one if this widget is contained by (or is) the passed widget.
    Otherwise returns zero.
   label(text)
   text = label
    Gets or sets the label of this widget, which may be displayed in or 
    next to the widget. The actual use is determined by the subclass.
   labelcolor(c)
   c = labelcolor
    Gets or sets the color used to draw the label text. The default is 
    FLTK::BLACK.
   labelfont(f)
   f = labelfont
    Gets or sets the font used to draw the label text. The default is a 
    san-serif font like Helvetica or Arial.
   labelsize(pts)
   pts = labelsize
    Gets or sets the point size used for the label text. The default is 
    14 points.
   labeltype(n)
   n = labeltype
    Gets or sets the label type, such as embossed. The default of 
    FLtk::NORMAL_LABEL prints the label as normal text [This is not 
    well documented in C++ and we probably don't support it correctly  
    yet. kbs]
   output
    Returns whether this widget is in "output" state, which means it is 
    not active. Supposedly useful for display-only scrollbars.
   parent
    Returns the parent widget, which is usually a Group or Window. Will 
    return nil if this widget has no parent.
   position(left,top)
    Shortcut for resize(left,top,w(),h()).
   redraw
    Marks this widget as needing to be redrawn. Later, the system will 
    invoke this widget's draw() method.
   resize(left,top,width,height)
    Set the window position and size. By default, does not automatically 
    force a redraw, to allow optimizations. This method is always called 
    by the system to perform resize operations, so may be overridden in 
    subclasses if you wish to detect or restrict resizing.
   selection_color(c)
   c = selection_color
    Gets or sets a secondary widget color, which is often used to 
    indicate a selected state. 
   set_changed
    Sets the changed flag (to one). See changed().
   set_output
    Puts this widget in an "output" state, which means it is not active. 
    Supposedly useful for display-only scrollbars.
   show
    Make this widget visible. Do not call this unless the parent is 
    visible (see visible_r()). Automatically calls redraw on this widget 
    and/or its parent, as needed.
   size
    Shortcut for resize(x(),y(),width,height).
   take_focus
    Attempts to make this the focus widget. Sends an FLTK::FOCUS event. 
    Returns one if this widget accepted the focus.
   takesevents
    Shortcut for (active() && visible() && !output()).
   user_data(data)
   data = user_data
    Gets or sets the user data associated with the callback. See callback().
   visible
    Returns one if this widget is set to be visible, even if its parent is 
    not visible. Also see visible_r()
   visible_r
    Returns one if this widget is set to be visible, AND all of its parents 
    are visible. Also see visible()
   w
    Returns the current width. Valid even if the widget is not shown.
   when(wh)
   wh = when
    Gets or sets the "when" bits that control when callbacks are invoked. 
    This is only used by subclasses.
   window
    Returns the enclosing Window of this widget. This is not necessarily 
    the direct parent, and will be a Window, not a Group. If this widget 
    is a Window, it will return the parent, not itself. If this is the 
    top-level Window, it will return nil.
   x
    Returns the left edge, relative to the enclosing Window. See window().
   y
    Returns the top edge, relative to the enclosing Window. See window().
   

* Window
  This widget is used for both top-level and popup (child) windows, and 
  modal and modeless dialogs. It is drawn with standard decorations for 
  your operating system--title bar, close button, etc.
  
  Constructors:
   new()
   new(label)
   new(width,height)
   new(width,height,label)
   new(left,top,width,height)
   new(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. The label is 
    shown in the title bar. These create a top-level window, which is 
    hidden by default. 
   popup()
   popup(label)
   popup(width,height)
   popup(width,height,label)
   popup(left,top,width,height)
   popup(left,top,width,height,label)
    The defaults for left, top, width, and height are zero. The label is 
    shown in the title bar. These create a popup (child) window, which is 
    shown by default. 

  Methods:
   border(value)
   value = border
    This is a flag to indicate to the operating system whether or not to 
    draw a border. Generally, it has no effect after the window has been 
    shown. The default is to have borders.
   clear_border
    Shortcut to clear the border flag, before the window has been shown.
   wnd = current
    Returns the window which is currently the target of drawing operations. 
    Rarely useful.
   cursor(aCursor, fgColor, bgColor)
    Sets the cursor for this window. aCursor is one of the FLTK::CURSOR_Xxx 
    values. The colors are used in X, but not in Win32.
   free_position
    Tells the operating system that when this window is next shown, it may 
    be positioned anywhere. [I'm not sure how one would use this--kbs]
   fullscreen
    Attempts to enlarge the window to take up the entire usable screen area, 
    if the operating system or window manager supports that.
   fullscreen_off(left,top,width,height)
    Turns off fullscreen mode, and invokes resize(left,top,width,height).
   hide
    Removes the window from the visible display. Has no effect if the
    window is not currently shown.
   hotspot(x,y,offscreen=0)
   hotspot(widget,offscreen=0)
    Positions this window such that the current position of the mouse will 
    be at either the specified position within this window, or at the 
    center of the specified widget (which might be this window). If 
    offscreen is specified, the window may extend beyond the edge of the 
    screen if the operating system or window manager allows it.
   iconize
    Reduces this window to an icon, as supported by the operating system. 
    May be called on iconized windows with no effect. If called on a 
    window that is not shown, it will become shown as well as iconized.
    Iconized windows are considered to be not visible, and calling show 
    will restore them. Events are generated for HIDE and SHOW operations. 
    The icon displayed may be set using xclass.
   iconlabel(text)
   text = iconlabel
    Get or set the label to be shown when this window is iconized.
   label(text)
   text = label
    Get or set the text that appears in the window title bar.
   make_current
    Establishes this window as the current target of drawing routines.
    [I'm not sure how one would use this--kbs]
   value = modal
    Returns one if this window is modal, zero if not. See set_modal.
   value = non_modal
    Returns one if this window is modal OR non-modal. See set_non_modal.
   resize(left,top,width,height)
    Change the size and position of the window. If shown, the operating 
    system may reject the request and invoke resize with other parameters.
    This method may be overridden if you want to handle external rezise 
    requests, such as to snap the window size to specific multiples.
   set_modal
    Puts this window into a modal state, where no other windows in the 
    same program will get any events. If there are multiple modal windows 
    in an app, the last one shown will get the events. Modal windows are 
    always on top. There seems to be no way to return a modal window to 
    normal mode.
   set_non_modal
    Puts this window into a non-modal state, which is visually on top, but 
    non-modal from an event standpoint. There are three possible states:
      normal
      non-modal - on top
      modal     - on top AND get all events
    There seems to be no way to return a non-modal window to normal mode.
   show
    If a window has never been shown, or has been hidden, or has been 
    iconized, make it visible. Also, whether it was already shown or not, 
    bring it to the top. May be called repeatedly without harm.
   shown
    Returns one if this window is shown, zero otherwise. Iconified windows 
    will return one for shown, but zero for visible.
   size_range(minW,minH,maxW=0,maxH=0,dw=0,dh=0,aspect=0)
    Only for top-level windows, this sets restrictions for how this window 
    may be resized. If maxW or maxH are zero, the window can be as large 
    as the screen in that dimension. dw and dh specific step increments, 
    but are ignored under Win32. aspect is a flag (one or zero) that 
    requests the current aspect ratio be maintained, but is ignored on 
    most systems. The default behavior if this method is not called is:
      - If this window's resizable is nil, the window cannot be resized
      - The default minimum is 100x100
      - If the resizable has a dimension of zero, this window will not 
        be able to be resized in that direction
   xclass(text)
   text = xclass
    Gets or sets the string used to tell the system what type of window 
    this is. Seems to be useless under Win32. See the C++ docs for details 
    of how this works under X.

3. Alphabetical Module Reference

* Drawable
  This module can be included in any widget, to provide a nice set of 
  methods to perform drawing. The raw FLTK:: drawing methods expect all 
  drawing coordinates to be relative to the Window that contains the 
  widget. These Drawable methods all expect coordinates relative to the 
  widget that is doing the drawing, which is much more natural.
  
  Generally, drawing methods should only be called from inside a draw() 
  method.
  
  Methods:
   clear
    Fills the entire widget area with FL_GRAY
   clip_box(left,right,width,height)
    Restrict output to the specified rectangle. If there is already a 
    clip_box, it will be intersected with this rectangle.
   color(c)
    Sets the foreground color for future drawing
   fill(c)
    Fills the entire widget area with the specified color
   line(x1,y1,x2,y2)
    Draws a line from (x1,y1) to (x2,y2), in the current color and style.
   line_style(style, width = 0, dashes = nil)
    Sets the current line style and width. style is a mask to control
    both the line and cap styles. If width is zero, the system default is 
    used, which is nicer than a width of one. dashes is an array that 
    contains alternating lengths of the dash and the gap. However, dashes 
    is not supported by Win32. You must set the line style BEFORE setting 
    the color.
   not_clipped(left,right,width,height)
   not_clipped?(left,right,width,height)
    Returns zero if this rectangle is entirely outside the clipping area. 
    May return one or two if it is partially or entirely inside.
   pie(left,right,width,height,a1,a2)
    Draws any fraction of a filled circle, in the foreground color. The 
    circle will be sized to fit inside the specified rectangle. a1 is the 
    start angle, in degrees, where zero is at the bottom. a2 is the end 
    angle, which determines how much pie to draw.
   point(x,y)
    Draws a single point at these coordinates, in the current color.
   pop_clip
    Restores the previous clipping area. See also push_clip. Calls to 
    push_clip and pop_clip MUST be matched.
   push_clip(left,top,width,height)
    Intersects this rectangle with the current clipping rectangle, and 
    pushes the result onto a stack. See also pop_clip.
   push_no_clip
    Pushes an empty clipping area (no clipping) onto the stack. See also 
    pop_clip.
   rect(left,top,width,height)
    Draws a one pixel border inside this rectangle, in the current color.
   rectf(left,top,width,height)
    Fills the specified rectangle with the current color
   text_draw(text,x,y,width=nil,height=nil,align=nil)
    Draws the specified text in the current font. If width and height are 
    specified, this is a multi-line text draw supporting newlines and tabs. 
    Otherwise, the default alignment will cause the text to be drawn ABOVE 
    the passed y value.
   text_width(text, n = nil)
    Returns the pixel width of the specified text, in the current font. 
    [I don't think we should support passing 'n'. kbs]


* FLTK
  All the Ruby-FLTK classes, modules, and methods are contained within the 
  FLTK module. Typically an app would require 'fltk', and then refer to any 
  FLTK entities as FLTK::Xxx. As an alternative, you can also include FLTK, 
  which would allow you to refer to any FLTK entities directly, without 
  the FLTK:: qualifier.

  Methods:
   check
    Should be called by handle() methods that take a long time to run. This 
    processes user input (such as mouse movement), calls idle and timer 
    methods, and refreshes the screen. See also wait() and ready().
   ready
    Similar to check() but does not refresh the screen or call callbacks.
   run
    Starts the main Ruby-FLTK event loop. This method will not return until 
    all top-level windows have been hidden. By default, pressing ESC will 
    hide a window.
   wait(max=0.0)
    Similar to check, but instead of returning immediately you can specify 
    a maximum number of seconds (or fractions) to wait. As long as there are 
    no pending events, idle callbacks, or timer callbacks, it will continue 
    to wait until the specified time has elapsed.
    
