File: l_event.rb

l_event.rb - this contains the Levent class and all event related events for the Lobject class. This class is used for event handling.

Author: Michael Davis, mdavis@locana.org

Home page: www.locana.org

License: Same as Ruby

This defines and sometimes creates all events used by Locana.

Status:

Working.

To do:

none planned

History

7/12/03 Added :border to the event when mouse over, mouse move, and button clicks occur in the border of an object so you can tell if the event occurred in the border area or client area. Added :on_open_listbox and :on_close_listbox for the Lcombobox object. Added the :on_scroll event for Lscrollbar objects. Added support for resizing objects via the new :allow_sizing attribute.
5/09/03 renamed from locana_event.rb to l_event.rb
12/10/02 all events are now prefixed with on_ so they can be more easily identified.
5/13/02 moved this code from locana.rb into it’s own module to simplify locana.rb.

This class supports event handling for Locana. Each GUI binding will translate operating system and/or GUI events into the Levent class and then trigger() the event.

Events allow you to bind your Ruby code to events or messages from the GUI Binding. Here is a list of possible components of the Levent structure:

:ievent - the symbol specifying the event or message such as :on_mouse_move, :on_after_update
:x - mouse x position relative to the screen left, also the new x position during the :on_move event
:y - mouse y position relative to the screen top, also the new y position during the :on_move event
:new_w - new w during :on_resize
:new_h - new h during :on_resize
:keycode - key code (decimal value) from a :on_key_press/:on_key_release event, you can call Levent.keychar() to get the ACSII representation of the keycode for :on_key_press and :on_key_release events
:value - value associated with the event for :on_change, :on_before_update, and :on_after_update events
:shift_key - true only when the shift key is pressed during the event
:ctrl_key - true only when the ctrl key is pressed during the event
:alt_key - true only when the alt key is pressed during the event
:meta_key - true only when the meta key is pressed during the event

Most events are started by the GUI binding. Here is the process flow:

Each GUI binding forwards all events to Levent.trigger_gui_event. This determines the object associated with the event, prepares an Levent object and calls lobject.trigger() for the object.
The lobject.trigger method may skip the event or redirect the event if requested. It then calls the appropriate event method for the object such as on_key_press().
All of the default object event methods defined in Lobject such as on_key_press() then call process_event(). As a result, all events should pass through the process_event() method for Lobject provided trigger() does not skip or redirect the event.
The lobject.process_event() method checks to see if a Proc object has been assigned to the object and calls the Proc object if it exists.
The whole process works great as long you remember to call super when creating explicit event methods for your Locana objects.

An event binding (also referred to as a callback) can be any of the following:

String - for example:
```
  b_obj.on_click  = 'puts event' or
  b_obj.on_click  = %q{puts event}
```
Strings are valuable because they can be viewed and edited in the GUI builder. The disadvantage to strings is that local variables defined where the event is declared are not always available to the string.
Proc object - for example:
```
  b_obj.on_click  = proc{|levent| puts levent}
```
The event is a proc object that is called when the event occurs. The advantage to using a proc object is greater flexibility. The proc object is executed in the scope of the parent window and has access to any local variables defined with the Proc object. Proc objects are more flexible to work with, however, the event binding is lost if you save the object. You will have to re-create your event bindings at run-time.
Block - for example:
```
  b_obj.on_click{|levent| puts levent}
```
When the event occurs, the levent (Levent object) is yielded to the block. This should be exactly the same as the prior example using a proc object. This may be the simplest approach but the event binding is lost when you save the object.
Singleton method - for example:
```
  def b_obj.on_click(event); super; end
```
All events eventually call a method just like this. If you define a singleton method for an event, make sure you call super during the processing of the event unless you want to purposefully short circuit many of the built-in aspects of Locana event handling.

Methods added to an object based on the Lobject class or one of the classes bases on the Lobject class. Here is an example:

  class My_button < Lbutton
    def on_key press(levent=nil, &block)
       return bind(:on_next_object, block) if (block)  # this necessary to support Blocks the same as Proc objects
       super     # this is important to the overall process
    end
  end

When Locana starts up a method is added for each of the following events to the Lobject class provided the method has not been explicitly defined below. In other words, the Lobject class will have a method for each of the supported events. The event method takes exactly one parameter that can be either nil, a Hash, or a Levent object. The block is optional.

Supported events:

:on_mouse_ldn => "when the left mouse button is clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_lup => "when the left mouse button is released, event[:x] and event[:y] contain the mouse position.",
:on_mouse_ldbl => "when the left mouse button is double clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_rdn => "when the right mouse button is clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_rup => "when the right mouse button is released, event[:x] and event[:y] contain the mouse position.",
:on_mouse_rdbl => "when the right mouse button is double clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_mdn => "when the middle mouse button is clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_mup => "when the middle mouse button is released, event[:x] and event[:y] contain the mouse position.",
:on_mouse_mdbl => "when the middle mouse button is double clicked, event[:x] and event[:y] contain the mouse position.",
:on_mouse_move => "when the mouse moves, event[:x] and event[:y] contain the mouse position.",
:on_mouse_over => "once, when the mouse enters the border or client area of the object.",
:on_mouse_out => "once, when the mouse leaves the border or client area of the object.",
:on_mouse_over_border => "once, when the mouse enters the border area of the object.",
:on_mouse_out_border => "once, when the mouse leaves the border area of the object.",
:on_key_press => "a key was pressed, levent[:keycode] contains the ASCII key code of the key that was pressed.",
:on_key_release => "a key was released, levent[:keycode] contains the ASCII key code of the key that was pressed.",
:on_move => "the window object has moved or changed location, event[:x] & event[:y] contain the location, Lwindow objects only.",
:on_resize => "the object has been resized, event[:new_w] & event[:new_h] contain the new width and height, respectively, Lwindow objects only.",
:on_change => "the state or value of an object has changed, this occurs immediately after the change occurs, it triggers the before_update event. It is created during the on mlb_release event (for listbox, combobox, checkbox, radiobox) and during the :on_key_press event (for textbox, editbox, password).",
:on_enter => "the user has entered this object, in other words, this object is getting the keyboard focus. This is automatically triggered by the on_mouse_ldn event, calling set_focus, or the on_next_object or on_prev_object events. The GUI Binding creates this only for window objects. Locana creates it for all other objects during the on_tab_key and on_mouse_ldn events.",
:on_exit => "automatically triggered when the focus leaves this object, this occurs by clicking on another object or tabbing out of the object, the GUI Binding creates this only for window objects. Locana automatically triggers this event for all other objects during the on_enter event of another object receiving the focus.",
:on_click => "automatically triggered when the left mouse button is released over an object or the enter key is pressed and a button has the focus.",
:on_scroll => "when a frame has a scrollbar, the :on_scroll event is triggered every time the scroller button is moved.",
:on_next_object => "triggered during the on_tab_key event or the on_enter_key event. Locana automatically gives the next object the keyboard focus.",
:on_prev_object => "triggered during the on_tab_key when the shift key is pressed (a back-tab or shift-tab). Locana automatically gives the previous object the keyboard focus.",
:on_paint_border => "triggered by the GUI Binding when the objects border needs to be painted. This method should paint the border area of the object.",
:on_paint_client => "triggered by the GUI Binding when the objects client area needs to be painted. This method should paint the client area of the object.",
:on_error => "triggered when an error is raised, the default action is to call process_error() which prints the error to stderr and opens a msgbox showing you the error.",
:on_timer => "triggered when you have set a timer and it expires and the timer is not associated with a block (in the later case, the block is called and the event is not triggered).",
:on_undo => "triggered when the user presses the escape key in a textbox, combobox, datebox, or editbox, this will reverts the :value of the object back to the :on_before_update value.",
:on_escape_key => "this event is automatically triggered when the escape key is released (:on_key_release event), it allows you to easily redefine what the escape key does. The default is to undo (call the :on_undo event) if the content of the object or control has changed since entering it.",
:on_enter_key => "this event is automatically triggered when the enter key is released (:on_key_release event), it allows you to easily redefine what the enter key does. The default moves the focus to the next object by triggering the on_next_object event. The button object calls the :on_click event. ",
:on_tab_key => "this event is automatically triggered when the tab key is released (:on_key_release event), it allows you to easily redefine what the tab key does. The default is to move the keyboard focus to the next object by triggering the on_next_focus event, if the shift key is pressed, the moves the keyboard focus to the previous object by triggering the on_prev_focus event.",
:on_left_key => "this event is automatically triggered when the left arrow key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_right_key => "this event is automatically triggered when the right arrow key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_down_key => "this event is automatically triggered when the down arrow key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_up_key => "this event is automatically triggered when the up arrow key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_pagedown_key => "this event is automatically triggered when the page down key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_pageup_key => "this event is automatically triggered when the page up key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_home_key => "this event is automatically triggered when the home key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_end_key => "this event is automatically triggered when the end key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_insert_key => "this event is automatically triggered when the insert key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_delete_key => "this event is automatically triggered when the delete key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_backspace_key => "this event is automatically triggered when the backspace key is pressed (:on_key_press event), it allows you to easily redefine what this event does. The default is to do nothing.",
:on_cut => "this event is automatically triggered during on the on_key_press of ctrl-delete_key, shift-delete_key, or ctrl-x.",
:on_copy => "this event is automatically triggered during on the on_key_press of ctrl-insert_key or ctrl-c.",
:on_paste => "this event is automatically triggered during on the on_key_press of shift-insert_key or ctrl-v.",
:on_load => "triggered when opening a Lwindow object after the window is loaded into memory and before the window is drawn, opened, or prepared. Only supported for Lwindow objects.",
:on_open => "triggered when opening a Lwindow object after the window is prepare and just before it is drawn or opened. Only supported for Lwindow objects.",
:on_show => "triggered when opening a Lwindow object after the window is drawn or opened. Also triggered when showing a hidden window via the show() method. Only supported for Lwindow objects.",
:on_hide => "triggered just before closing or hiding the window has started. Only supported for Lwindow objects.",
:on_close => "triggered immediately after closing a Lwindow object. It is safe to cancel this event by calling raise CancelEvent. Only supported for Lwindow objects.",
:on_unload => "triggered after the Lwindow object has been closed and removed from memory. Only supported for Lwindow objects.",
:on_after_update => "the value in this object has been updated. Generally, this will always be paired with on_exit (unless the enter key is pressed and the action is to remain on this object). The on_exit event triggers this event when the object is dirty.",
:on_before_update => "the value in this object is about to change. This is triggered the first time the value is this object changes after it received the focus.",
:on_open_listbox => "this opens the listbox associated with the combobox. It is triggered whenever the listbox needs to be opened.",
:on_close_listbox => "this closes the listbox associated with the combobox. It is triggered whenever the listbox needs to be closed."

Thank you for taking the time to visit this web page. I trust you found the information contained in this page useful.
Please email any questions, concerns, or issues with this web site to webmaster@sevasoftware.com.
Please remember Seva Software when your company would benefit from an experienced database architect and software engineer.