What it Locana?

Locana is a GUI for Ruby. It runs on Windows 95/NT/2000/XP and Tk. It draws all the widgets using a few basic methods from a GUI binding (mswin32, tk, etc.). It is mostly written in Ruby. There is a small DLL for Windows written in C for accessing Window functions and a small module written in C for Tk for connecting to a Tk/TCL interpreter.

??/??/2003 - Changes for version 0.84:

• Llistbox - shift selection with :multiple and :extended listboxes is now working properly.

10/15/2003 - Changes for version 0.83:

• 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 works with windows 95, 2000 and XP. All known issues with Windows 95 and XP have been fixed.
• 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 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:
  • 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.

05/08/2002 - Changes for version 0.82:

• The HTML GUI binding is not working in version 0.82.
• Added Lmenu object. This adds a menu bar to windows and pop-up menus to windows when the set :state=>:popup.
• Added Ldatebox and Lcalendar objects.
• 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 the Lspinner object.
• Created Ltimer class for handling timers and deleted timer_start() and timer_cancel() methods from Lobject.
• Created Lballoon class and moved balloon help from the methods in Lobject to its own class.
• Created a Ldisplay class. This new class the parent to all Lwindow object. If Lwindow objects are opened without a parent, a default display is created and used as the parent to the window. This is mostly done to eliminate the special case Lwindow objects had by not having a parent.
• Added support for themes and styles, these allow you easily change the look and feel of an applet just by changing the theme external to your applet.
• 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, 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. Valid values are :top, :middle, or :bottom
  • :ipadx and :ipady - allows you add a little extra spacing along the borders of window and group objects
  • :otype - This is used to provided additional characteristics for the object. Lmenu supports :menubar (main menu bar), :popup (pop-up menu), :checkbox (this menu item has a checkbox), :radiobox (this menu item has a radiobox), and :separator (a line separating menu items). Lwindow supports :modal (the window becomes a modal dialog box) and :topmost (the window will always be on top of the display). Llistbox supports :single (the default, a single item can be selected), :multiple(many items can be selected), :extended(many items can be selected when using the control/shift key). Lcombobox supports :allow_any_value (any value can be typed into the combobox), the default is that only value in the :text attribute (listbox) can be typed into the combobox.
  • :autoselect - When true entering an object will automatically select (highlight) the text in the textbox. Use false to disable the auto-select feature. The default is true (:autoselect is enabled) for Ltextbox, Lpassword, Lcombobox, and Ldatebox objects and false for the Leditbox object. Not supported for other classes.
  • :auto_save - Applies only to Lwindow objects. Set to true if you would have the size and position saved in the config file for reuse the next time the window is opened, this is the default. Set to false to not save the window’s size and position. You can override the default by setting :gAutoSavePos in a theme.
  • :bitmap - applies only to button objects so buttons can be displayed using pixmaps. Currently on pixmap is supported. The unix utility ‘bitmap’ will allow you to create and edit pixmaps.
• Enhanced the buttons used by combobox, datebox, and spinner objects to take advantage of the new Lpixmap class for a cleaner more polished look and feel.
• Added support for :width=>’75%’ and :height=>’50%’ (the quotes are required). This tells object to use 75% of the parents width and 50% of the parents height.
• Added support for typing all characters into the Lcombobox object. The textbox is filled with the first matching element in the listbox. When a matching element is not found, you will get beeped and the new character is ignored.
• Added select_text() so you can highlight text in the textbox, editbox/textarea, and password classes.
• Added config_get() and config_put() to retrieve save values to a config file (~/.locana/locana.cf).
• Re-designed the relationship between Locana and the GUI binding:
  • The external interface did not change much, but the internals changed a lot.
  • Eliminated the entire LWB_object classes improving performance using less memory. This really simplified the internals of Locana.
  • All attributes are now referenced and updated using methods rather than by using method_missing(). This allows you to more easily customize Locana.
  • Renamed many of the modules so they more accurately reflect their contents.
• Re-designed how events are handled:
  • Each event is now a method that can be defined in addition to assigning a proc object to an event
  • All event symbols (names) now start with :on_. This means things like :key_press is now :on_key_press.
  • Added :on_escape_key event so you can easily re-define the escape key. The default is to undo any current changes to the object with keyboard focus. I use in the applets to exit a pop-up window.
  • Added :on_enter_key event so you can easily re-define the enter key. The default is to do nothing with one exception, button objects call the :on_click event.
  • Added :on_tab_key event so you can easily re-define the tab key. The default is to move to the next object. If the shift key is pressed them moves to the previous object.
    • Changed the following event names
      • :on_mlb_down to :on_mouse_ldn
      • :on_mlb_up to :on_mouse_lup
      • :on_mlb_dblclk to :on_mouse_ldbl
      • :on_mrb_down to :on_mouse_rdn
      • :on_mrb_up to :on_mouse_rup
      • :on_mrb_dblclk to :on_mouse_rdbl
• Lots of bug fixes for Tk and mswin32.
• These enhancements cause you to change any code you have created using Locana:
  • Changed Lobject to Lobject and LWB_object to LGobject. If you are using Locana, you will need to change any references for Lobject to Lobject, Lwindow to Lwindow, Lgroup to Lgroup, etc. (for all objects).
  • Changed attribute :type to :otype because references like o.type was accessing the type of the object and not the :type attribute.
  • Changed the msgbox() method from (I did not like having to always specify a title for quick messages):

      msgbox(msg_title, msg_text, msg_type=:ok, msg_icon=nil, msg_default=nil)  # open a message box
    

    to:

      msgbox(msg_text, msg_type=:ok, msg_icon=nil, msg_title=nil, msg_default=nil)  # open a message box
    

    If you are using Locana, you will need to change any calls you are making to msgbox() to accommodate the new position of the msg_title. Sorry about that.

• Here are the changes to the GUI Builder:
  • Enhanced the GUI builder to support the new Locana features.
  • Added a menu editor to the GUI Builder so you can add, edit, and delete menubars and popup-menu using a simple text based editor.
  • Added a pop-up menus to the GUI Builder to allow quicker access to some functions like push back, bring front, cut, copy, paste, new, etc.
  • Added cut/copy/paste of objects to the GUI Builder so objects can be easily moved from one group/window to another.

3/03/2002 - Changes for version 0.81:

• Added :startx, :starty, :spanw, :spanh attributes allowing you more precise control over the position of new objects.
• Added a Locana module to provide direct access to Locana objects. This provides cleaner access to many Locana objects.
• Changed strings to symbols. In other words, all object attributes are now symbols. I.e. ‘value’ is now :value, ‘text’ is now :text, etc..
• Eliminated the x,y,w,h parameters in the initialize method.
• Added the following attributes as an alternative to the :pos attribute (these are ignored these if :pos is specified):
  • :sticky => ‘allows you to ‘stick’ the object to one or more of it’s parents borders. Any combination of nsew can be used. ‘n’ is the top border, ’s’ is the bottom border, ‘w’ is the left border, ‘e’ is the right border.’,
  • :above => ‘Lobject.name will place this object above Lobject.name. The x value will default to Lobject.x. When set to :prev, this object will be placed above the previously added object. This is ignored for the first object in a group or window.’,
  • :below => ‘Lobject.name will place this object below Lobject.name. The x value will default to Lobject.x. When set to :prev, this object will be placed below the previously added object. This is ignored for the first object in a group or window.’,
  • :before => ‘Lobject.name will place this object before Lobject.name. The y value will default to Lobject.y. When set to :prev, this object will be placed before the previously added object. This is ignored for the first object in a group or window.’,
  • :after => ‘Lobject.name will place this object after Lobject.name. The y value will default to Lobject.y. When set to :prev, this object will be placed after the previously added object. This is ignored for the first object in a group or window.’,
  • :padx => ‘allows you specify the number of pixels to add (or pad) to the left and right of the object.’,
  • :pady => ‘allows you specify the number of pixels to add (or pad) to the top and bottom of the object.’,
• Added methods for creating objects such as button(), group(), textbox() etc. These allow you add objects to windows using a simpler and cleaner syntax.
• Changed how blocks provided with the Lobject.new() are executed from using eval() to using instance_eval(). This supports the above syntax but also changes the context where the block is executed. You no longer have direct access local variables inside the block. See the description of bind() for more details.
• Added method_missing() to allow you to reference objects by name, reference and assign attributes using the attribute name (such as object_name.text = ’’ is equivalent to object_name.attr[:name}), and event binding assignment using the event name (such as object_name.on_click = proc{}). For example:
• Simplified the event handler by moving Levent.process_event to an instance method of Lobject. This allows you to easily trap the for any object type. The widget bindings now have to support :on_change. The :on_enter and :on_exit must be supported for all objects, not just windows. The :next_object and :prev_object events are now returned by the widget binding when pressing the tab and enter keys telling locana to set the keyboard focus to the next or previous object. The Levent object now consists of an object, event, Hash of event values associated with the event. A method_missing method has been added to Levent so things like event.x, and event.key_code will still work properly. The ‘on_action’ event is now :on_click.

1/30/2002 - First official release version 0.80.