Welcome to Locana.org

Locana is a GUI interface or GUI toolkit for the Ruby programming language. Locana requires the Ruby programming language.

Locana draws widgets such as text boxes, list boxes, edit boxes, buttons, check boxes, radio buttons, and combo boxes using a small set of methods defined in a GUI binding that talks directly to a GUI such as Windows and Tk. It also supports borders, menubars, popup menus, and automatic scrollbars etc.. It currently runs in Windows XP/2000/NT/ME/98/95 and on Tk.

Locana comes with a GUI Builder that allows you to create applets interactively.

Locana is freeware, open source, and is released under the same license as Ruby and requires the Ruby programming language.

Screen shots:

• overview of the software
• running on MS Windows
• running on Tk on linux

Download

More detailed information about Locana can be found at http://www.sevasoftware.com/locana.

The mswin32 implementation of Locana includes a DLL that hooks directly into Microsoft DLL's. This means several things, 1) Locana should run on any Windows (95/98/me/2000/XP) platform; 2) you don't need to install any additional software (other than Locana and Ruby of course) for Locana to run on Windows; 3) there is nothing to compile because the DLL is provided with the windows installer of Locana.

The Tk implementation of Locana basically creates a TCL/Tk interpreter and sends TCL/Tk commands through the interpreter. This is similar to how Ruby/TK was created but is much simpler (I only implemented a sub-set of Tk). You will have to install or make sure Tk is installed before Locana will run using Tk. I have tested it on FreeBSD, Linux, and Windows 2000 (with Tk). You can change the GUI by setting an environment variable called locana_binding=tk for Tk or locana_binding=mswin32 for the windows version. This allows you choose the GUI even if more than one is available.

Current Release

Release 0.83, released on 10/10/2003, click here to download:

• The HTML GUI binding is not working in version 0.83. It may be a while before it gets any more attention.
• Locana has been redesigned to create all widgets using a very basic set of commands from the native GUI.
  • Here are the pros this design:
    • greatly simplified the GUI interface
    • simplified testing
    • streamlined the relationship between Locana and the GUI by reducing the amount of data stored for each object and basically eliminated most prior native GUI overhead
    • more consistent look and feel with a lot less issues to test and work around
    • you can more easily change and control the look and feel of any object and more easily create new objects
    • allowed me to easily track mouse activity over the border of an object so you can resize objects
    • everything runs much faster
  • The cons:
    • objects may not have the look and feel of the native GUI
• Added support for a File Browser (see notepad.rb for an example) and a Color Browser (see the locana_builder.rb, double click on one of the color attributes).
• Added the Lborder class with several borders. You should be able to easily add your own borders.
• Added the Lscrollbar class. The Lframe class automatically detects if scrollbars are needed, creates them, and manages them for you. You can easily override the default action by trapping the :on_scroll event.
• Added the Lcontainer class. This can contain other Locana objects and is the base class for the Lframe class.
• Added the ability to change/set the mouse cursor.
• The Lframe class is now based on the Lcontainer class and support scrollbars and other objects in one or more of it's four borders.
• The Llistbox and Leditbox classes are now based on the Lframe class so they can support scrollbars.
• The Leditbox and Ltextbox class can now cut, copy, and paste to/from the clipboard.
• Menus can support font and color attributes. Menubars can be added to any Lframe object and popup style menus can be added to any Lcontainer object.
• The mswin32 GUI Binding now reports a list of all available fonts.
• The mswin32 GUI Binding uses a small DLL that is provided with the GUI Binding eliminating the need to compile any code. It works well using the Windows version of Ruby.
• Added the following GUI Binding methods that you can call to customize your objects:
  • Locana_gui::draw_point(frame_id, color, x, y) - not supported in Tk
  • Locana_gui::draw_line(frame_id, color, x1, y1, x2, y2, thickness=1, style=:solid)
  • Locana_gui::draw_rectangle(frame_id, color, x1, y1, x2, y2, thickness=1, style=:solid)
  • Locana_gui::draw_ellipse(frame_id, color, x1, y1, x2, y2, thickness=1, fill=nil)
  • Locana_gui::draw_circle(frame_id, color, x, y, r, thickness=1, fill=nil)
  • Locana_gui::draw_text(frame_id, fg, bg, string, x, y, font_id=nil, accelerator=nil) #, justify=:left, align=:top)
• Added a separate download for Windows users that includes a Windows style installer and a pre-build DLL (no more code to compile) that works much better on all Windows platforms. Also adds the GUI Builder, documentation, and applets to the Start Button in Programs/SeveSoftware/Locana and Programs/SevaSoftware/Applets.
• Added the following attributes:
  • :mouse_cursor - allows you to set the cursor for an object
  • :allow_sizing - when true, the user can click on the border of this object and re-size it. Locana will track mouse movements over the border of the object, automatically change the mouse cursor, and allow you to resize while clicking and dragging in the border.
  • :allow_dragging - when true, the user can click on this object and drag it around in the window/group.
  • :allow_dragging_parent - When true, the user can click on this object and drag it's parent around in it's parent window/group.
  • :min_width - the minimum width in pixels of the object. This is only used when resizing the object to keep it from getting too small.
  • :min_height - the minimum height in pixels of the object. This is only used when resizing the object to keep it from getting too small.
  • :tab_order - this used be :tab, the :tab attribute is no longer supported
  • :max_size - this used to be :maxsize, the :maxsize attribute is no longer supported
  • :fg_disabled - text or foreground color when the object is disabled.
  • :bg_disabled - background color when the object is disabled. The default is the object background color.
  • :fg_highlight - text or foreground color when the object is highlighted.
  • :bg_highlight - background color when the object is highlighted.
• Added the following events:
  • :on_timer - when a timer is started without a block, the timer will trigger this event when the timer matures.
  • :on_scroll - when a frame has a scrollbar, the :on_scroll event is raised every time the scroller is moved.
  • :on_paint_border - the objects border area needs to be painted.
  • :on_paint_client - the objects client area needs to be painted.
  • :on_open_listbox - this opens the listbox associated with the combobox.
  • :on_close_listbox - this closes the listbox associated with the combobox.
• Added the following events that automatically created during the on_key_release event:
  • :on_escape_key - called when the escape key is released, it allows you to easily redefine the escape key.
  • :on_enter_key - called when the enter key is released, it allows you to easily redefine the enter key.
  • :on_tab_key - called when the tab key is released, it allows you to easily redefine the tab key. The default is to move the keyboard focus to the next object, if the CTRL key is pressed, the moves the keyboard focus to the previous object.
  • :on_f1_key - called during on the on_key_release of the F1 key.
  • :on_f2_key - called during on the on_key_release of the F2 key.
  • :on_f3_key - called during on the on_key_release of the F3 key.
  • :on_f4_key - called during on the on_key_release of the F4 key.
  • :on_f5_key - called during on the on_key_release of the F5 key.
  • :on_f6_key - called during on the on_key_release of the F6 key.
  • :on_f7_key - called during on the on_key_release of the F7 key.
  • :on_f8_key - called during on the on_key_release of the F8 key.
  • :on_f9_key - called during on the on_key_release of the F9 key.
  • :on_f10_key - called during on the on_key_release of the F10 key.
  • :on_f11_key - called during on the on_key_release of the F11 key.
  • :on_f12_key - called during on the on_key_release of the F12 key.
• Added the following events that automatically created during the on_key_press event:
  • :on_alt_key - called when the alt key is pressed, the default action is to activate/deactivate the menubar.
  • :on_left_key - called when the left arrow key is pressed.
  • :on_right_key - called when the right arrow key is pressed.
  • :on_down_key - called when the down arrow key is pressed.
  • :on_up_key - called when the up arrow key is pressed.
  • :on_pagedown_key - called when the page down key is pressed.
  • :on_pageup_key - called when the page up key is pressed.
  • :on_home_key - called when the home key is pressed.
  • :on_end_key - called when the end key is pressed.
  • :on_insert_key - called when the insert key is pressed.
  • :on_delete_key - called when the delete key is pressed.
  • :on_backspace_key - called when the backspace key is pressed.
  • :on_cut - called during on the on_key_press of ctrl-delete_key, shift-delete_key, or ctrl-x.
  • :on_copy - called during on the on_key_press of ctrl-insert_key or ctrl-c.
  • :on_paste - called during on the on_key_press of shift-insert_key or ctrl-v.
• Changes to the Applets:
  • changed the name of unify.rb to kaya.rb
  • added a notepad.rb applet
  • enhanced all the applets work a little better and have a more consistent look and feel
  • added better theme support for some objects
  • enhanced the timer applet to support multiple timers
• Changes that could impact any current code:
  • track down the .locana directory and remove it. I should be in your home directory.
  • opening a pop-up menu has changed from popup_menu.show(x,y) to popup_menu.show_menu(x,y).
  • changed :on_mlb_down to :on_mouse_ldn
  • changed :on_mlb_up to :on_mouse_lup
  • changed :on_mlb_dblclk to :on_mouse_ldbl
  • changed :on_mrb_down to :on_mouse_rdn
  • changed :on_mrb_up to :on_mouse_rup
  • changed :on_mrb_dblclk to :on_mouse_rdbl
  • changed :tab to :tab_order
  • changed :maxsize to :max_size
  • changed :type to :otype
  • changed object[:attribute] = new_value, before this release, this would assign new_value to the attribute and get applied to the object. With this release, this just records the attribute in the object but does not apply it nor will this change get saved. Use object.attribute = new_value instead.
  • These changes will be automatically applied to any objects saved in *.ls (Lstore) files.
  • The HStore class changed with the release. If you have objects in a LStore (or HStore) you will see an error when opening the file with the GUI Builder. You will need to run hstore/hstore_compact.rb to update the HStore.

Planned Releases

Planned for Release 0.84:

• Add a GUI Binding for xlib.
• Add Ltree object, a tree is similar to a Llistbox object except each visible object that can be expanded will have a '+' so it can be expanded and each visible expanded object will have a '-' so it can be collapsed

Planned for Future Releases of Locana:

• Add syntax highlighting to the editbox.
• Add a text editor applet.
• Add support for DBI in the Lobject class and the HStore object.
• Add an applet that interfaces to CVS.
• Add Ltoolbar object allowing you to add dragable toolbars that can be docked into the edge or border area of a window
• Add Lprogress_meter object showing how much of a task has been completed and how much still remains to be done
• Add support for a datasheet object, a datasheet is a collection of rows and columns where you define the appearance of each column and each row is an array of columns
• Update all the applets to take advantage the new data sheet object

Prior Releases

Release 0.82 was unofficially released on 5/31/2003, click here to download:

• Added Limage object allowing support for .jpg and .gif images.
• Added Lmenu object allowing menu bars and pop-up menus.
• Added Lcombobox object allowing menu bars and pop-up menus.
• Added Ltabgroup and Ltabpage objects. A tabgroup is a collection of tabpage objects. A tabpage is a group where a button is added for each tabpage allowing you to select which tabpage you are currently viewing. Only one tabpage in a tabgroup is visible at a time.
• Added Ldatebox and Lcalendar objects.
• Added the following attributes:
  • :vscroll - adds a vertical scroll bar to the right edge of the object. The editbox and listbox support this attributes.
  • :hscroll - adds a horizontal scroll bar to the bottom edge of the object. The editbox and listbox support this attributes.
  • :fg - foreground or text color of the object
  • :bg - background color of the object
  • :bcolor - color of the border for this object
  • :font - an array of font attributes for this object [name, size, weight, style]
  • :font_name - name of the font
  • :font_size - size of the font
  • :font_style - style of the font. Possible values are :bold, :italic, :normal (the default), :underline
  • :justify - how text is justified horizontally inside this object. Valid values are :left, :center, or :right
  • :align - how test is justified vertically inside this object. Va lid values are :top, :middle, or :bottom
  • :auto_select - this is supported by Ltextbox, and Lcombobox and allows the text to auto-selected for highlighted for text replacement when entering the object. The default is true. Set to false to disable the :auto_select feature for an individual object.
  • :width=>'75%' (the quotes are required) - tells object to use 75% of the parents width.
  • :height=>'50%' (the quotes are required) - tells object to use 50% of the parents height.
  • :ipadx and :ipady to allow you add a little extra spacing along the borders of window and group objects.
  • :type - is used to contain additional info about object. For example, Lmenu supports :checkbox and :radiobox as menu items, Lcombobox support :allow_any_value, and Lwindow supports :modal and :topmost.
• Added timer_start() that allows you create methods that are run at periodic intervals.
• Completed the changes to the GUI Builder. This includes many bug fixes in the Tk and mswin32 widget bindings, the combobox objects, and GUI Builder. Added menu bar and tab group.
• Added :mouse_over and :mouse_out events. Added Lcalendar and Ldatebox objects. Added balloon help. Balloon help is a pop-up help message when the mouse is over an object for more than 3 seconds and the object has a :help attribute.
• Added support for themes and styles allowing you to specify object attribute using an external config or theme file. This makes it easy to customize or change the look and feel of any applets using Locana.
• Added config_get and config_put allowing to store and retrieve per used data similar to Windows Registry. The size of windows are automatically added to the config file so the size and position of windows are remembered.
• Updated the GUI Builder to support all the new attributes.
• Added the following new applets:
  • reminders.rb - pop-up reminders
  • todos.rb - track a list of todos with support for priority and dates started/completed
  • timer.rb - track multiple projects and start/stop a timer to help track the time you invest in each project
  • notes.rb - sticky post-it notes for your computer
  • kaya.rb - a nice blending of the above applets
  • notepad.rb - allows you to open and edit text files
• Added the following modules and split locana.rb into several smaller modules:
  • locana_colors.rb - contains all supported color names (symbols) and a color selector window.
  • locana_event.rb - contains all things related to events such as the Levent class and Lobject.process_event method.
  • locana_fonts.rb - contains all things related to fonts. This is mainly used for determining the exact of the object so the prepare() function will work properly..
  • locana_image_support.rb - contains methods needed for image support.
  • locana_object.rb - contains all things related Lobject and most objects based on the Lobject class. When an object is based on other locana objects, such as Lmenu, Lcombobox, Ldate, etc., they are placed in their own module.
  • locana_prepare.rb - contains all things related to positioning objects when the :pos attribute is not used. This includes support for the :sticky, :before, :after, :above, :below, :width, :height, :padx, :pady attributes.
  • locana_combobox.rb - contains the Lcombobox object.
  • locana_databox.rb - contains the Ldatebox and Lcalendar objects.
  • locana_menu.rb - contains Lmenu object supporting both pop-up menus and the menubar.
  • locana_tabgroup.rb - contains Ltabgroup and Ltabpage objects.
  • locana_themes.rb - contains all methods used to add support for themes and :style attribute.

Release 0.81 for Ruby, released on 3/20/2002, click here to download:

• Added an applets directory containing several little applets that provide some good examples of how to use Locana. Currently, there are four versions of a simple calculator each showing a different way to put objects into a window.
• Added an HTML widget binding and a HTTP server. Start the HTTP server (locana_server.rb) and you can run Ruby applets with Locana using a web browser. Ruby and Locana only need to be installed on the computer running locana_server.
• Converted the x,y,w,h parameters to an attribute. You can now position objects using the new :pos=>[x,y,w,h] attribute. X and y is the position of the object in pixels within its parent. W and h are optional and specify the size of the object. This makes it easy to add new layout managers to Locana in the future.
• Added the following new object attributes allowing greater flexibility for putting objects in a window:
  • :sticky => 'nsew' allows you to 'stick' the object to one or more of it's parents borders. Any combination of nsew can be used
  • :above => :object_name will place the object directly above :object_name
  • :below => :object_name will place the object directly below :object_name
  • :before => :object_name will place the object directly before :object_name
  • :after => :object_name will place the object directly after :object_name
  • :spanw => :object_name will cause this objects width to match :object_name.x + :object_name.w
  • :spanh => :object_name will cause this objects height to match :object_name.y + :object_name.h
  • :startx => object_name will cause this objects x to match :object_name.x
  • :starty => :object_name will cause this objects y to match :object_name.y
  • There are examples of the using new attributes in tst_locana.rb (click on the 'Test packing' or 'Test spanning' buttons) and the four calculator.rb applets available from applets.rb (click the applets.rb link provided above).
• All attribute names and object names have been converted from strings to symbols. For example 'text'=>'test this', 'value'=>3 is now :test=>'test this', :value=>3.
• Added a module called Locana making it easier/simpler to access many of the Locana objects.
• Added a missing_method() that supports a lot of new possibilities. For example, you can change an attribute of an object using: :object_name.value = 5. Where value is the :value attribute (or any attribute) of an object. Events are also supported, for example: :object_name.after_update = proc{|event| print 'do something with the after_update event'}.
• Better object spacing for Tk.
• GUI builder changes to support all of the newly added attributes.
• Updated the screen shots were added to locana.org.
• Added a new 'export' feature the GUI builder that lets you create windows using the GUI Builder and then export the window as Ruby code that will run independent of the GUI builder. A nice aspect of this enhancement is that it allows you experiment with the new attributes interactively and then export the window and see the actual Ruby code.
• Added applets/calculator4.rb. This is the same basic calculator applet but it calls a window in calculator.loc (created with the GUI builder). It shows how to blend your Ruby code with a UI created using the GUI builder. Applets/calculator4.rb contains a class with several methods called from the window in calculator4.loc.