-
Notifications
You must be signed in to change notification settings - Fork 7
User Guide : wxRuby Event Handling
Event handling is the core of runtime code execution in event based frameworks like wxWidgets which means it needs to
be fully supported by wxRuby. Fortunately it is.
As Ruby is a fully dynamic language though the statically declared event tables typical for wxWidgets application are not.
Instead wxRuby offers a dynamic solution that is just as easy to use and even offers more flexibility in a typical Ruby-way.
Instead of the EVT_XXX
event handler declaration macros used in wxWidgets wxRuby provides similarly named event handler
definition methods for each of the known event declarations which are inherited by all classes derived from Wx::EvtHandler
(which includes all window classes, the Wx::App class and Wx::Timer as well as various other classes).
Naming is (mostly) identical but rubified. So EVT_MENU
becomes evt_menu
, EVT_IDLE
becomes evt_idle
, EVT_UPDATE_UI
becomes evt_update_ui
etc.
Like the event handler macros some of these methods require a single (window) id (like evt_menu
) or a range of of ids
(specified through a first and last id like for evt_update_ui_range
) and some require only a handler definition (like
evt_idle
).
Event handler setup is typically something done during the initialization of an event handler object (like a window) but this is not required. As all event handlers are assigned dynamically in wxRuby you can setup (some) event handlers at a later moment. You could also disconnect earlier activated handlers at any time (see Wx::EvtHandler#disconnect).
In case of some frame class MyForm
including a menu a wxWidgets static event handling table like:
wxBEGIN_EVENT_TABLE(MyForm, wxFrame)
EVT_IDLE(MyForm::OnIdle)
EVT_MOVE(MyForm::OnMove)
EVT_SIZE(MyForm::OnResize)
EVT_MENU( wxID_ABOUT, MyForm::OnAbout )
EVT_MENU( wxID_EXIT, MyForm::OnCloseClick )
wxEND_EVENT_TABLE()
could translate to event handler initializations in wxRuby like this:
class MyForm < Wx::Frame
def initialize(title)
super(nil, title: title)
# initialize frame elements
# ...
# setup event handlers
evt_idle do |evt|
# do something
evt.skip
end
evt_move :on_move
evt_size method(:on_size)
evt_menu(Wx::ID_ABOUT, Proc.new { on_about })
evt_menu(Wx::ID_EXIT) { close(false) }
end
def on_idle(evt)
#...
end
def on_move(evt)
#...
end
def on_resize(evt)
#...
end
def on_about
#...
end
end
As you can see there are multiple options for specifying the actual handler. Any event handler definition method will
accept either a Symbol
(or String
) specifying a method of the receiver (the event handler instance), a Proc
object
(or lambda) or a Method
object.
Event handler methods are not required to declare the single event object argument. The event handler definition method will take care of checking and handling method arity.
Custom event definitions are fully supported in wxRuby including the definition of new event types.
New event classes can be registered with Wx::EvtHandler.register_class which returns the new event type for the event class like this:
# A custom type of event associated with a target control. Note that for
# user-defined controls, the associated event should inherit from
# Wx::CommandEvent rather than Wx::Event.
class ProgressUpdateEvent < Wx::CommandEvent
# Create a new unique constant identifier, associate this class
# with events of that identifier and create an event handler definition method 'evt_update_progress'
# for setting up this handler.
EVT_UPDATE_PROGRESS = Wx::EvtHandler.register_class(self, nil, 'evt_update_progress', 0)
def initialize(value, gauge)
# The constant id is the arg to super
super(EVT_UPDATE_PROGRESS)
# simply use instance variables to store custom event associated data
@value = value
@gauge = gauge
end
attr_reader :value, :gauge
end
Check the reference documentation here for more information.
In wxRuby overruling the normal chain of event handling has been limited to being able to override the default
Wx::EvtHandler#try_before and Wx::EvtHandler#try_after methods. These are the advised interception points for events
when you really need to do this.
Overriding Wx::EvtHandler#process_event is not considered to be efficient (or desired)
for wxRuby applications and has therefor been blocked.
Use of Wx::EvtHandler#process_event or Wx::EvtHandler#queue_event and Wx::EvtHandler#add_pending_event in wxRuby to trigger event processing of user generated (possibly custom) events is fully supported.
As with wxWidgets Wx::EvtHandler#process_event will trigger immediate processing of the given event, not returning before
this has finished.
Wx::EvtHandler#queue_event and Wx::EvtHandler#add_pending_event on the other hand will post (append) the given event
to the event queue and return immediately after that is done. The event will than be processed after any other events in
the queue. Unlike in wxWidgets in wxRuby there is no practical difference between queue_event
and add_pending_event
.
In addition to Wx::EvtHandler#queue_event and Wx::EvtHandler#add_pending_event to trigger asynchronous processing wxRuby also supports Wx::EvtHandler#call_after.
This method provides the means to trigger asynchronous execution of arbitrary code and because it has been rubified is
easy and powerful to use. Like with event handler definition this method accepts a Symbol
or String
(identifying a
method of the receiver), a Proc
object (or lambda), a Method
object or a block. Unlike an event handler method no
event object will be passed but rather any arguments passed to the call_after
method in addition to the 'handler'.
Given an event handler object call_after
could be used like:
# sync call to method of event handler (no args)
evt_handler.call_after :async_method
# async call of lambda (single arg)
evt_handler.call_after(->(txt) { Wx.log_info(txt) }, "Hello")
# async call of block
evt_handler.call_after('Call nr. %d', 1) { |fmt, num| Wx.log_info(fmt, num) }
Like in C++ the wxRuby Event objects passed to the event handlers are (in general) references to temporary objects which are only safe to access within the execution scope of the event handler that received the reference. If you need (really?) to store a reference to such an object do so to a cloned version (see Wx::Event#clone) and not to the original object otherwise you will run into 'Object already deleted' exceptions.
Only user defined events instantiated in Ruby code (or cloned Event objects) will be subject to Ruby's normal life cycle rules (GC). This means that when you instantiate a user defined event and pass it to Wx::EvtHandler#process_event it would be possible to directly store the reference to such an Event object passed to it's event handler. You have to know for sure though (see below). So, in case of doubt (or to be safe) use Wx::Event#clone.
Another 'feature' to be aware of is the fact that when passing an (user instantiated) Event object to
Wx::EvtHandler#queue_event
or Wx::EvtHandler#add_pending_event the Ruby event instance is unlinked from it's C++ counterpart (or in the case of user
defined events a cloned instance is associated with it's C++ counterpart) before being queued and the C++ side now takes ownership
(and will delete the Event object when handled).
As a result this means that even in the case of a user defined Event object any event handler triggered by a asynchronously
processed event will be handling a temporary Event object.
Additionally this also means that any Event object passed to Wx::EvtHandler#queue_event or
Wx::EvtHandler#add_pending_event
is essentially invalidated after these methods return and should not be referenced anymore.
-
- Introduction
- Quick start
- wxRuby Modules
- wxRuby Life Cycles
- wxRuby Dialogs
- wxRuby Enum values
- wxRuby Event Handling
- Geometry
- Colour and Font
- wxRuby Extensions
- Exception Handling
- Locating and loading art
- Drawing and Device Contexts
- Client data with wxRuby
- Validators and data binding
- Configuration support
- Persistence support