Class
Lobject 		Home
In: locana.rb locana/l_event.rb locana/l_object_prepare.rb locana/l_object_themes.rb locana/l_object.rb
Parent: Hash

Lobject is the base class for all Locana objects. It is based on the Hash class because an object is a collection of working attributes that are stored in the Hash. Basically, the object is a collection of working attributes including attributes gathered from themes and inherited from parent objects. All objects have two set of attributes, the first is the working attribute described above. It contains all stored attributes and all inherited attributes from themes and parent objects. The second set is called stored attributes. These are attributes directly specified for this object and are saved. These are stored in an instance variable called @oattr. Supported object attributes:

There are two ways to put or place widgets or objects into a window or group:

  1. Use the :pos attribute and put the object at a specific location in the window. It uses an array of four points [x,y,w,h]. The w and h are optional and will default to size of the object.
  2. You can provide a combination of the following (similar to Tk’s pack):
    • :sticky - is any combination of ‘news’. Here are some basic rules:
      • :n binds to the top border and centers left to right
      • :e binds to the right border and centers top to bottom
      • :w binds to the left border and centers top to bottom
      • :s binds to the bottom border and centers left to right
      • :nw binds to the top left border
      • :ew will span the width of the parent and centers top to bottom
      • :ns will span the height of the parent and centers left to right
      • :news will span the width and height of the parent
      • :c will center the object in it’s parent, unless another sticky setting is used with the :c
      • if :above, :below, :before, :after are used with centering then centering is done with remaining space
    • :padx - the number of horizontal pixels to add before and after the object
    • :pady - the number of vertical pixels to add above and below the object
    • :ipadx - the number of pixels to add (or pad) to the inside edge of the left/right border of the object
    • :ipady - the number of pixels to add (or pad) to the inside edge of the top/bottom border of the object
    • :above=>:object_name - position above another object with a name of :object_name. The x of the two objects will be the same (before the padx attribute is applied).
    • :below=>:object_name - position above below object with a name of :object_name. The x of the two objects will be the same (before the padx attribute is applied).
    • :before=>:object_name - position before another object with a name of :object_name. The y of the two objects will be the same (before the pady attribute is applied).
    • :after=>:object_name - position before another object with a name of :object_name. The y of the two objects will be the same (before the pady attribute is applied).
    • :startx=>:object_name - set the x of this object to :object_name.x.
    • :starty=>:object_name - set the y of this object to :object_name.y.
    • :spanw=>:object_name - set the w of this object to :object_name.x + :object_name.w.
    • :spanh=>:object_name - set the h of this object to :object_name.y + :object_name.h.

    The :above, :below, :before, :after attributes allow you to position or arrange an object relative to another object. These attributes will override the :sticky attribute in most situations. There is a window called :TestPacking in tst_locana.rb that shows many combinations of :sticky and these attributes. You can place a object :after=>:object1 and :below=>:object2. In this case, your object will use the x of :object2 and the y of :object1. You can set :above, :below, :before, :after => :prev to arrange the object relative to the previously added object.

    :spanw, :spanh, :startx, :starty allow you to position or arrange an object relative to other objects. These settings will override the :sticky :above, :below, :before, and :after attributes.

    Here are the rules for w/h in order of precedence: :pos[2/3]>0, :width/:height>0, :spanw/:spanh>0, :sticky=>:ew, pixel size of object. Here are the rules for x/y in order of precedence: :pos[0/1], :startx, :starty, :before, :after, :above, :below, :sticky, sticky=>:nw in parent.

  3. If you don’t provide :pos or :sticky, the default is :sticky=>:nw using the objects default pixel size.
Methods

activate_menubar, activate_popup, bind, determine_mouse_cursor_for_sizing, event, fire, get_binding, get_bindings, is_position_inside_object?, is_prepared?, new, on_after_update, on_alt_key, on_backspace_key, on_before_update, on_change, on_click, on_close, on_copy, on_cut, on_delete_key, on_down_key, on_end_key, on_enter, on_enter_key, on_error, on_error_print_error, on_escape_key, on_exit, on_f10_key, on_f11_key, on_f12_key, on_f1_key, on_f2_key, on_f3_key, on_f4_key, on_f5_key, on_f6_key, on_f7_key, on_f8_key, on_f9_key, on_help, on_hide, on_home_key, on_insert_key, on_key_press, on_key_release, on_left_key, on_load, on_mouse_ldbl, on_mouse_ldn, on_mouse_lup, on_mouse_mdbl, on_mouse_mdn, on_mouse_move, on_mouse_move_object, on_mouse_mup, on_mouse_out, on_mouse_out_border, on_mouse_over, on_mouse_over_border, on_mouse_rdbl, on_mouse_rdn, on_mouse_resize_object, on_mouse_rup, on_move, on_next_object, on_open, on_pagedown_key, on_pageup_key, on_paste, on_prev_object, on_resize, on_right_key, on_scroll, on_show, on_tab_key, on_timer, on_undo, on_unload, on_up_key, prepare, prepare_internal_lobject, prepare_lobject, prepare_object, process_event, reprepare, reprepare_all, trigger, trigger_on_mouse_move,
Attributes

 [RW]  name
 [RW]  parent
Included modules

Locana
Public Class methods
on_error_print_error(lobject, lerror, error_message, call_stack, ievent, levent) src

Prints the content of levent to $stderr.

new(name, attr=nil, &block) src

Creates a new object. FYI, @oattr is the original attribute supplied by the caller, self is a collection of working attributes for the object including inherited attributes, internal Locana attributes, attributes gathered from themes, and the object attributes (@oattr) are also added.

Example: (see tst/tst_locana.rb for more examples) 

    win = Lwindow.new('TestEditBox', :pos=>[60, 60, 0, 0], :text=>'Test EditBox') {
       label('label1', :pos=>[10, 5, 0, 0], :label=>'Type some text')
       textbox('t_text1', :pos=>[10, 30, 200, 0])
       button('b_ok', :pos=>[260, 260, 0, 0], :text => 'Ok')
       # bind a print statement to the after_update event for the textbox object
       t_text1.bind(:on_after_update, %q{print "after update, new value: '#{event.value}'\n"})
       b_ok.on_click = "close()" # this button will close the form
       save('locana.ls')  # save this window object
    }

Example2: 

    win = Locana::window('TestEditBox', :pos=>[60, 60, 0, 0], :text=>'Test EditBox') {
       label('label1', :pos=>[10, 5, 0, 0], :label=>'Type some text')
    }
Public Instance methods
determine_mouse_cursor_for_sizing(levent) src

Returns the mouse cursor used for sizing based on the location of the mouse when it is over a border. The on_mouse_move and on_mouse_over_border calls this to determine which mouse cursor to use based on the border involved with the event when :allow_sizing is turned on.

is_position_inside_object?(lx, ly) src

Returns true if lx and ly are inside the objects border or client area.

bind(ievent, proc_object=nil, &block) src

This binds Ruby code to an event. The Ruby code is executed when the event occurs. The following three examples are different ways to accomplish this (they are all exactly the same): 

 b_obj.bind(:on_click, proc{|levent| puts levent})
 b_obj.on_click  = proc{|levent| puts levent}
 b_obj.on_click{|levent| puts levent}
 def b_obj.on_click(levent)
    super
    #puts levent
 end

FYI: Some unix keyboards don’t report Shift Tab such that Tk will interpret it. Use xev to show how keys are interpreted. Here is a possible fix for this issue: 

  xmodmap -e "keysym KP_Tab = Tab"
get_bindings(only_event_bindings=nil) src

Returns a Hash containing the event bindings for the object.

get_binding(ievent) src

Returns the event binding assigned to ievent or nil if there is no binding. For example: get_binding(:on_key_press).

activate_menubar() src

Searches through parents until an menubar is found and activates it.

activate_popup(x=nil, y=nil) src

Searches through parents until a popup menu is found and activates the first one it finds.

trigger_on_mouse_move(frame, lx, ly, is_mouse_button_pressed) src

This is called by trigger_gui_event during an on_mouse_move event. All on_mouse_move events from the GUI are directed here. This looks at the position of the mouse, adds the :border element to the event, and generates the on_mouse_over, on_mouse_out, on_mouse_over_border, on_mouse_out_border and on_mouse_move events as needed. Here is the order as the mouse move into an object and then out of an object:

All of these events are forwarded to trigger() for processing. This returns the border the mouse is currently over.

trigger(ievent, levent=nil) src

This invokes or triggers ievent. 1) redirects all events to self[:_trap_events] if self[:_trap_events] is defined, the GUI binding uses this 2) eats events for disabled or locked objects 3) calls the method created for this event which should call process_event in turn All GUI Binding events eventually pass through here.

fire(ievent, levent=nil)

Alias for trigger

process_event(ievent, levent=nil) src

All event methods should call this just before the each event is processed. This calls Levent.trap_events, if defined, and allows you to easily trap/monitor any/all events and raise an error if needed. You can raise the CancelEvent error (defined in Locana.rb) to cancel any event before it is processed. The event monitor process in the GUI builder uses Levent.trap_events to report all events. If a Proc object or String has been assigned to an object, see bind(), it is called here. All GUI Binding events call trigger_event which forwards the event here.

event() src

This returns the event current being process by the event handler. This allows event bindings that are strings to reference the event when they are triggered.

on_after_update(levent=nil, &block) src

Triggered by the on_exit event of an object when it is dirty (the content of the object has changed). Removes the :dirty attribute for self, sets the :dirty attribute for the parent window, and clears the undo variable.

on_alt_key(levent=nil, &block) src

Triggered by on_key_press of the alt key. The default action is to activate the menubar (calls activate_menubar). This event is triggered from the trigger() method rather than the on_key_press method to make sure it gets priority over the on_key_press methods.

on_backspace_key(levent=nil, &block) src

Triggered by on_key_press of the backspace key.

on_before_update(levent=nil, &block) src

Triggered just before the content of an object is changed and the object is not yet dirty (has not changed yet). Saves the current :value in the :_undo attribute in case the on_undo event is triggered.

on_change(levent=nil, &block) src

Triggered when the user interactively changes the content of an object such as a textbox, checkbox, listbox, etc.. Triggers the on_before_update event when the object is not dirty and sets the :dirty attribute in self. The self[:value] attribute should report the value of the object before the on_change event and levent[:value] should contain the newly changed value.

on_click(levent=nil, &block) src

Triggered by pressing the enter key on a button or menu, the space bar key on a checkbox or radiobox, or on_mlb_down for many of the objects. Not supported by all objects.

on_copy(levent=nil, &block) src

Triggered by pressing ctrl-c (on_key_press event) and pressing ctrl-insert (on_insert_key event with the control key pressed). Copies the selected text from :value attribute into the clipboard. Only supported by a few objects such as Ltextbox and Leditbox.

on_cut(levent=nil, &block) src

Triggered by pressing ctrl-x (on_key_press event) and pressing ctrl-delete or shift-delete (on_delete_key event with the control key pressed). Cuts the selected text from :value attribute of the object and places it in the clipboard. Only supported by a few objects such as Ltextbox and Leditbox.

on_delete_key(levent=nil, &block) src

Triggered by the on_key_press event of the delete key. This triggers the on_cut event during ctrl-delete key or shift-delete key.

on_down_key(levent=nil, &block) src

Triggered by the on_key_press event of the down arrow key.

on_end_key(levent=nil, &block) src

Triggered by the on_key_press event of the end key.

on_enter(levent=nil, &block) src

Triggered when the keyboard focus enters this object. This calls Locana_gui::set_focus to let the GUI Binding we have the focus. If :auto_select is enabled, the text in the object will be automatically highlighted or selected, only for Ltextbox and Leditbox objects. Also lets the parent window know we have the focus and calls paint_focus to render the focus in the object.

on_enter_key(levent=nil, &block) src

Triggered by the on_key_press event of the enter or return key.

on_error(levent=nil, &block) src

This is triggered whenever an error occurs in Locana. The default action is to call Lobject.on_error_print_error() which prints the error to stderr and opens a msgbox containing the error.

on_escape_key(levent=nil, &block) src

Triggered by the on_key_press event of the escape key. This allows you to assign a common task to the escape key. Here is the default action:

on_exit(levent=nil, &block) src

Triggered when the keyboard focus is leaving the object. Triggers the on_after_update event if the object is dirty (its content or :value attribute has been changed). Calls paint_focus_remove to remove or undo the focus for this object.

on_help(levent=nil, &block) src

Triggered by the on_key_release event of the F1 key. The default is to open a message box containing the :help attribute when releasing the F1 key.

on_home_key(levent=nil, &block) src

Triggered by the on_key_press event of the home key.

on_insert_key(levent=nil, &block) src

Triggered by the on_key_press event of the insert key. This triggers the on_copy event during ctrl-insert key and on_paste during shift-insert key.

on_key_press(levent=nil, &block) src

This triggers the following events:

We also need to check for and call accelerators and cancel the balloon help timer and close the balloon help if it is open.

on_key_release(levent=nil, &block) src

This triggers the following events:

All functions key events are forwarded to the parent_window.

on_f1_key(levent=nil, &block) src

Triggered by the on_key_release event of the F1 key. Triggers the on_help event.

on_f2_key(levent=nil, &block) src

Triggered by the on_key_release event of the F2 key.

on_f3_key(levent=nil, &block) src

Triggered by the on_key_release event of the F3 key.

on_f4_key(levent=nil, &block) src

Triggered by the on_key_release event of the F4 key.

on_f5_key(levent=nil, &block) src

Triggered by the on_key_release event of the F5 key.

on_f6_key(levent=nil, &block) src

Triggered by the on_key_release event of the F6 key.

on_f7_key(levent=nil, &block) src

Triggered by the on_key_release event of the F7 key.

on_f8_key(levent=nil, &block) src

Triggered by the on_key_release event of the F8 key.

on_f9_key(levent=nil, &block) src

Triggered by the on_key_release event of the F9 key.

on_f10_key(levent=nil, &block) src

Triggered by the on_key_release event of the F10 key.

on_f11_key(levent=nil, &block) src

Triggered by the on_key_release event of the F11 key.

on_f12_key(levent=nil, &block) src

Triggered by the on_key_release event of the F12 key.

on_left_key(levent=nil, &block) src

Triggered by the on_key_press event of the left arrow key.

on_mouse_ldbl(levent=nil, &block) src

Triggered by double clicking on the left mouse button.

on_mouse_ldn(levent=nil, &block) src

Triggered by clicking on the left mouse button. Check for and supports :allow_dragging and allow_dragging_parent and prepare for dragging when needed. check for and supports the :allow_sizing attribute when the mouse is over the border. Give this object the focus, calls set_focus().

on_mouse_lup(levent=nil, &block) src

Triggered by releasing the left mouse button. Cancels the balloon help timer and closes the balloon help it is open.

on_mouse_mdbl(levent=nil, &block) src

Triggered by double clicking on the middle mouse button.

on_mouse_mdn(levent=nil, &block) src

Triggered by clicking on the middle mouse button. Cancel the balloon help timer and close the balloon help it is open.

on_mouse_mup(levent=nil, &block) src

Triggered by releasing the middle mouse button. Cancel the balloon help timer and close the balloon help it is open.

on_mouse_rdbl(levent=nil, &block) src

Triggered by double clicking on the right mouse button.

on_mouse_rdn(levent=nil, &block) src

Triggered by clicking on the right mouse button. Calls activate_popup if there is a popup style menu assigned to this object of one of this objects parents. Also remembers the object under the mouse so the popup menu can use it.

on_mouse_rup(levent=nil, &block) src

Triggered by releasing the middle mouse button. Cancel the balloon help timer and close the balloon help it is open.

on_mouse_move(levent=nil, &block) src

Triggered by moving the mouse. Closes the balloon help, if open. Supports dragging objects if the user has clicked on an object that can be dragged (see the :allow_dragging attribute). Supports resizing objects if the user has clicked in the border area of an object than can be sized (see the :allow_sizing attribute). Automatically sets the mouse cursor to one of the mouse sizing cursors when :allow_sizing is turned on and the mouse is over one of the objects borders. Needed when the mouse is over one of the borders and is moved to another border without leaving the border area.

on_mouse_move_object(levent=nil, &block) src

Triggered by on_mouse_move when :allow_dragging is turned on and the left mouse button is down. Moves the object based on the new mouse coordinates. Triggers the :on_move event for the object being dragged.

on_mouse_over(levent=nil, &block) src

Triggered when the mouse is moved over the border or client area of the object. Starts the balloon help timer. Automatically changes the mouse cursor to match the :mouse_cursor attribute. Here is the order of events:

on_mouse_over_border(levent=nil, &block) src

Triggered when the mouse is moved over the border area of the object. Automatically changes the mouse cursor to appropriate cursor when :allow_sizing is on to indicate that sizing is allowed. Order of events:

on_mouse_out(levent=nil, &block) src

Triggered when the mouse is moved outside the object border and client area. Cancels the balloon help timer and close the balloon help if it is open. Clears the mouse cursor. Here is the order of events:

on_mouse_out_border(levent=nil, &block) src

Triggered when the mouse cursor is no longer over the border area of the object. Automatically reverts the cursor back to the :mouse_cursor attribute. Here is the order of events:

on_mouse_resize_object(levent=nil, &block) src

Triggered during the on_mouse_move event when the :allow_dragging attribute is turned on and the left mouse button is pressed. Resized the object based on the new mouse coordinates. When resizing the east or north borders, triggers the :on_move event for the object being resized. Otherwise, triggers the on_resize event for the object being resized.

on_move(levent=nil, &block) src

Triggered when an object is dragged or a window is moved. It records the new position of the object if needed. This does not actually move the object, it expects that the object is already in the new position.

on_next_object(levent=nil, &block) src

Triggered by the on_tab_key event. Calls next_focus() to give the next object the focus.

on_pagedown_key(levent=nil, &block) src

Triggered by the on_key_press event of the page down key.

on_pageup_key(levent=nil, &block) src

Triggered by the on_key_press event of the page up key.

on_paste(levent=nil, &block) src

Triggered by pressing ctrl-v (on_key_press event) and pressing shift-insert (on_insert_key event). Pastes the content of the clipboard into the objects :value attribute. Only supported by a few objects such as Ltextbox and Leditbox.

on_prev_object(levent=nil, &block) src

Triggered by the on_tab_key event when the shift key is pressed. Calls prev_focus to give the focus to the previous object.

on_resize(levent=nil, &block) src

Triggered when an object is resized (not during a reprepare) or a window is resized. Records the new position of the object if needed. This does not actually resize the object, it expects that the object is already in the new position.

on_right_key(levent=nil, &block) src

Triggered by the on_key_press event of the right arrow key.

on_scroll(levent=nil, &block) src

Triggered by the Lscrollbar object when the scroller button in the scrollbar has changed position. Allows you to customize the action to take when the scroller moves.

on_tab_key(levent=nil, &block) src

Triggered by the on_key_press event of the tab key. Triggers on_next_object or on_prev_object when the shift key is pressed.

on_timer(levent=nil, &block) src

Triggered when a timer has matured and the Ltimer.start method was not supplied a block.

on_undo(levent=nil, &block) src

Triggered during the on_escape_key event. Resets the :value attribute back to it’s original value using the :_undo attribute (the undo variable).

on_up_key(levent=nil, &block) src

Triggered by the on_key_press event of the up arrow key.

on_load(levent=nil, &block) src

Triggered when the object is first opening up before it is prepared, displayed or opened. This event is only supported for Lwindow objects.

on_open(levent=nil, &block) src

Triggered when the object is first opening up after it has been prepared and before it is displayed or opened. This event is only supported for Lwindow objects.

on_show(levent=nil, &block) src

Triggered just after the object is opened and displayed. The show() method also triggers this. This event is only supported for Lwindow objects.

on_hide(levent=nil, &block) src

Triggered just before the object removed from the display. Called by the close() and hide(). This event is only supported for Lwindow objects.

on_close(levent=nil, &block) src

Triggers as the object closes just before the window is removed from the display. It is safe to cancel this event and the closing of the window by calling raise CancelEvent. This event is only supported for Lwindow objects.

on_unload(levent=nil, &block) src

Triggered after the object and all of its children are closed and removed from the display. This event is only supported for Lwindow objects.

is_prepared?() src

Returns true if this object has been prepared.

reprepare_all(parent=nil, move_obj=nil) src

This will reprepare all objects.

reprepare(move_obj=nil) src

This will reprepare all objects only when needed. This is called during the :on_resize event. This cleared the prepared flag and calls prepare()

prepare(parent=nil, move_obj=nil) src

This determines the x,y,w,h position of the object based on the objects attributes. For example, you can leave the ‘w’ and ‘h’ attributes empty for a window, this method will calculate them based on the sizes and positions of it’s children. Open() automatically calls this method.

Here is the order of processing:

prepare_lobject(parent=nil, move_obj=nil)

Alias for prepare

prepare_internal_lobject(move_obj=nil)

Alias for prepare_internal

prepare_object(move_obj=nil) src

Fills in any empty values (x,y,w,h) for the object. Calls the following in order:


Seva Software


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.

http://www.arunadb.org http://www.locana.org http://www.ruby-lang.org http://www.coolwell.org http://www.sevasoftware.com