locana.rb - a graphical user interface (GUI)
for Ruby that runs on Windows 95/NT/2000/Me/XP and Tk
Locana is Sanskrit for enlightening or
eye.
Locana is a collection of classes and
methods allowing you to easily add a graphical user interfaces (GUI) to
your applets that run on any supported platform as mswin32, or Tk. Locana is easy to extend.
Locana is a GUI interface for Ruby. It
actually draws widgets using a few basic methods from a native GUI via a
GUI Binding. The ultimate goal is to write applets using Locana that run on any platform.
Currently Locana runs on the following
platforms:
- mswin32 - runs on Windows 95/98/Me/NT/2000/XP. See locana_gui_mswin32.rb
for details.
- Tk - runs on any machine that has Tk installed. See locana_gui_tk.rb for
details.
Planned platforms:
- xlib - this will be in the next release
Author: Michael Davis, mdavis@locana.org
Copyright: (C) 2000, 2001, 2002 Seva Inc. and Seva Software - www.sevasoftware.com
Home page: www.locana.org
License: Same as Ruby
Download: www.locana.org/locana_download.html
Installation on unix based systems:
% tar -zxvf locana_0_83.tar.gz
% cd locana_0_83
% ruby install.rb # you will likely need root access for this
Installation on MS Windows based systems:
% run locana_0_83.exe # follow the prompts, Ruby must be installed before this will work
Testing:
% ruby tst/tst_locana.rb
Documentation - The documentation is located in locana_0_83/doc. Just open
locana_0_83/doc/index.html in your favorite browser. The documentation can
be recreated using the following command:
ruby create_docs.rb
FYI, rdoc is required. See http://rdoc.sourceforge.net/index.html.
Planned Releases: www.locana.org/locana.html#PlannedReleases
Support - how to ask questions, submit bug
reports, and submit enhancement requests
Versions - an overview of prior releases
History - a detailed list of changes
FAQ - Frequently Asked Questions
Samples:
- The following two samples do almost exactly the same thing, they both open
a window with a button that changes color during an on_mouse_over event,
however, the code that drives them is very different.
- tst/hello_world.rb
- tst/hello_world2.rb
Screen shots:
Status:
- Working.
- Tested on the following platforms:
- mswin32 - Windows 2000 using cygwin with Ruby 1.6.5
- mswin32 - Windows XP using a windows version of Ruby 1.6.8
- mswin32 - Windows 95 using cygwin with Ruby 1.6.8 for windows
- tk - Linux RedHat 6.2 with Ruby 1.6.8
- tk - FreeBSD 4.2 with Ruby 1.6.8.
Testing:
- tst/tst_locana.rb that creates some Locana objects that provides some nice
examples of using Locana.
- applets/applets.rb this opens a window allowing you to run the other
applets interactively.
- applets/notepad.rb shows a basic notepad for editing and creating text
files.
- applets/config_editor.rb this allows to view the content of the config
files. There are two of them .locana/windows.cf and .locana/locana.cf. The
later contains any config settings used by the applets via the config_get() and config_put() methods. The former
contains the position of all moved and resized windows so the next time you
open an applet, the position and size of the windows are automatically
remembered.
- applets/calculator.rb shows a basic calculator.
- applets/calculator1.rb shows how to use the :pos attribute.
- applets/calculator2.rb shows how to use the :sticky, :above, :below,
:before, :after attributes with groups or containers.
- applets/calculator3.rb shows how to use the :sticky, :above, :below,
:before, :after attributes without groups or containers.
- applets/calculator4.rb shows how to combine a GUI created with the GUI
builder with ruby code from a separate source file. The GUI is stored in
calculator4.ls and can be viewed/edited with the GUI builder and the Ruby
code for the calculator is stored in a class in calculator4.rb.
Locana creates and uses two config
files:
- Locana::CONFIG_FILE_PATH/locana.cf (i.e. ~/.locana/locana.cf) => this
contains configuration information save by applets. The applets use this to
store things like turning off the balloon help. You can use this file by
calling config_get() and config_put() to store and
retrieve information that you want to remember between calls to your
applet.
- Locana::CONFIG_FILE_PATH/windows.cf (i.e. ~/.locana/locana.cf) => this
contains the positions and sizes of windows. Locana automatically records the position
and size of windows in this config file and uses this information when
opening the window. This allows the user to move and window and Locana will automatically remember the
new position. This can be disabled for all windows by calling Lobject.global(:gAutoSavePos) or by
setting :gAutoSavePos => false in a theme. This can be turned on/off for
individual windows by setting the :auto_save attribute (false for off and
true for on).
Here is a brief overview of Locana
classes:
- Lwindow - this creates a top level
window. It is based on the Lframe
class. The Lframe class support
scrollbars and adding objects into the borders. This class is defined in
l_window.rb.
- Lcontainer- this contains other
objects. It is based on the Lobject
class. This class is defined in l_container.rb.
- Lbutton - this is a push button. It
is based on the Lobject class and is
drawn to the native GUI. This class is defined in l_button.rb.
- Lcalendar - this is a calendar that
allows you to interactively select a date. This is a Lgroup that contains everything it needs
to allow you to interactively select a date. This class is built using only
Locana classes (it does not rely on
the GUI Binding) and is based on the Lgroup class. See the Lcalendar class in locana_calendar.rb
for details.
- Lcheckbox - this is a check box
that can be checked on or off. It is based on the Lobject class and is drawn to the native
GUI. This class is defined in l_checkbox.rb.
- Lcombobox - this is based on Ltextbox class with a Lbutton_pixmap and popup listbox
window of values you can select from. This allows you to type in a value or
select from a drop down pick list. This class is created from other Locana classes. This class is defined in
l_combobox.rb.
- Ldatebox - this is a date (Time class) with buttons to
increment/decrement and open the Lcalendar. This is based on the Lspinner class with a Lbutton_pixmap to open the
calendar. The Lspinner buttons can
be clicked on to subtract one day, add one day, and open a Lcalendar object allowing you to
interactively select a date. This class is built using only Locana classes (does not rely on the GUI
Binding). See the Ldatebox class in
locana_calendar.rb for details.
- Leditbox - this a multi-line edit
box similar to the Ltextbox class.
Ltextbox is basically a single line
edit box. It is based on the Lobject
class and is drawn to the GUI. This class is defined in l_editbox.rb.
- Levent - this class provides event
handling for Locana. Messages or
events from the operating system and/or GUI Binding are transformed into a
Levent object to make accessing events
consistent across the different GUI Bindings. This class is defined in
l_event.rb.
- Lframe - this is a collection of other
Locana objects and supports scrollbars
and menubars. It is based on the Lcontainer class. This class is
defined in l_frame.rb.
- Lgroup - another name for Lframe. Logically, I use this class to
contain other Locana objects and the
Lframe class for objects that draw
directly into the GUI. This class is defined in l_frame.rb.
- Limage - this class allows you to add
images (.jpg and .gif) to a Lcontainer. You can add the on_click event to images so they
can act like buttons. It is based on the Lobject class and is drawn in the native
GUI. This class is defined in l_image.rb.
- Llabel - this class displays text in a
Lcontainer. It is based on the Lobject class and is drawn to the native
GUI. This class is defined in l_label.rb.
- Lline - this class draws a line. It is
based on the Lobject class and is
drawn to the native GUI. This class is defined in l_others.rb.
- Llistbox - this is a list of items
that can be selected. A vertical scroll bar is displayed if all of the
items can’t be seen. It allows you to select one or more items in the
list. It is based on the Lframe class.
This class is defined in l_listbox.rb.
- Lmenu - this class allows you to add
menu items and sub-menus to menu bars and popup menus. It is bases on the
Lcontainer class. This class is
defined in l_menu.rb.
- Lmenubar - this class allows you to
add a menu bar to any Lframe object.
It is based on the Lcontainer
class. This class is defined in l_menu.rb.
- Lmenu_popup - this class allows
you to add a popup style menu to any Lcontainer object. It is based on the
Lcontainer class. This class is
defined in l_menu.rb.
- Lobject - this is the base class for
all Locana objects. This class is
defined in l_object.rb. It contains methods that are common to all Locana objects.
- Lpassword - this is a Ltextbox that displays ’*’
rather than characters. This class is defined in l_textbox.rb.
- Lspinner - this is based on the Ltextbox class with two Lbutton_pixmaps
to increment/decrement the value in the textbox. This class is built using
other Locana classes (does not rely on
the GUI Binding). This class is defined in l_spinner.rb.
- Lradiobox - this is a radiobox that
can be selected/deselected. Selecting a radiobox will automatically
deselect all other radiobox objects in the same Lcontainer. You can select a radiobox
by clicking on it. If there are other radiobox Object in the same Lcontainer, then only one can be
selected at a time. In other words, clicking on one radiobox automatically
turns off all other radioboxes in the Lcontainer. It is based on the Lobject class and is drawn to the native
GUI. This class is defined in l_radiobox.rb.
- Ltabgroup - this is a collection of
Ltabpage objects. This class is
built using only Locana classes (does
not rely on a GUI Binding) and is based on the Lcontainer class. This class is
defined in l_tabgroup.rb.
- Ltabpage - this is a collection of
other Locana objects. Similar to a
group except that there is a button automatically added for each tabpage
that you can click on to bring the tabpage to the front of other tabpages.
These can only be added to a Ltabgroup object. This class is built
using only Locana classes (does not
rely on a GUI Binding) and is based on the Lframe class. This class is defined in
l_tabgroup.rb.
- Ltextbox - this is a textbox or
input box allowing you type characters into the textbox. You can limit the
number of characters typed into a textbox by setting the max_size attribute. It is based
on the Lobject class and is drawn to
the native GUI. This class is defined in l_textbox.rb.
See initialize() in the Lobject class
in l_object.rb for a description of supported attributes. See bind() in the
Lobject class in l_event.rb for a
description of all supported events.
Locana has a GUI builder that allows
you to build applets interactively. The GUI builder is written in 100% Ruby
using only Locana. It allows you to
create, edit, save, and delete Locana
objects. See locana_builder.rb for details.
Locana and the Locana GUI builder have been designed to
allow the following choices for creating applets:
- write code using Ruby and Locana. Most
of the applets supplied with Locana
use this technique.
- use the GUI Builder to create the entire applet. Presently, Ruby support
for this option is fairly limited at this time since all events are strings
that are evaled at run-time.
- use the GUI Builder to create and maintain the UI and load a ruby module
containing all the code you need for your applet. The calculator4.rb applet
is a good example of this. This allows you to separate the GUI from the
code and use the GUI builder for easy maintenance and use the full power of
Ruby to write code. The nice thing about this implementation is that you
can export an object created in the GUI Builder directly into Ruby code and
you can save an object creating in Ruby code that can be edited in the GUI
Builder. As long as you understand the relationship between binding proc
objects or String objects to events
(see Lobject.bind() for details) you
can easily change from one design choice to another (writing Ruby code or
using the GUI builder).
I tend to prefer writing code rather than designing with the GUI Builder.
That is why most of the applets supplied with Locana were created as Ruby applets using
Locana (the first option above). If
you are familiar with Ruby and are willing to learn how to use Locana then option 1 is a good choice.
Beginners to Ruby or Locana or
individuals that don’t enjoy writing code will likely prefer using
the GUI Builder. The GUI Builder is is easier in many respects for creating
and managing GUI’s but is more challenging when trying when trying to
add complex code to your applet. In other words, the GUI Builder is great
for GUI but not so great for writing code.
Debug - this describes how debug() statements are used in Locana. Debug is information that printed
when running your ruby program with the -d option. Locana’s implementation of debug
allows you to set a debug_level and see messages pertaining to that level.
The higher the debug level, the more debug messages you will see. See
debug.rb for more details. Here are the debug_levels supported:
10 - show high level stuff like creating, opening, closing, and deleting locana objects
11 - show details such as method_missing, attribute reference and assignment, finding objects, etc.
13 - used in the GUI Binding, shows high level stuff like creating and deleting native widget objects
14 - reports every event passed to Locana by the GUI Binding
15 - used in the GUI Binding, reports events at the widget level, this could be a lot of debug
Debug Examples:
- Show basic high level Locana messages:
ruby -d applets.rb debug_level 11
- Show Locana messages plus all GUI
Binding messages :
ruby -d applets.rb debug_level 13
- Show above plus all Locana events:
ruby -d applets.rb debug_level 14
- Show above plus all GUI Binding events (a lot of debug):
ruby -d applets.rb debug_level 15
- Show all messages pertaining only to specific objects :obj1 and :obj2
ruby -d applets.rb debug_level 15 debug_filter "ojb1|obj2"
