wxRuby Documentation Home

Wx::EvtHandler

A class that can handle events from the windowing system.
Window (and therefore all window classes) are derived from
this class, and Wx::App is also an EvtHandler.

The methods listed here are relatively rarely needed in user code,
unless you wish to write your own event-generating classes, or to
dynamically remove event handlers in a running program.

This is because, in addition to the methods listed here, all event
handler classes support a number of convenience methods for seting up
event handlers. These methods have names of the form evt_xxx, for
example, evt_button or evt_close. The names of these methods can be
found in the documentation on the control class which generates the
events (for example Button), or in the documentation for
the event class (for example “CloseEvent”.closeevent.html).

Derived from

Object

See also

Event handling overvieweventhandlingoverview

Methods

Class Methods

EvtHandler.new_event_type

Integer new_event_type()

EvtHandler.register_class

Integer register_class(%(arg-type)Class% klass, Integer konstant = nil, String meth = nil, Event arity = nil)

Registers the mapping of user-defined events identified by the constant
konstant to the user-defined ruby event class klass. If konstant
is not specified, a new, unique identifier will be created by the API
(using Event.new_event_type) and
returned by the method.

Optionally, if meth and arity are specified, this method will also
create a shortcut method for setting up event handlers, comparable to
the in-built methods such as evt_menu, evt_button or evt_close.

If you wish to have such a method created, meth should contain the
name of the new method (for example “evt_foo”), and arity should be
the number of arguments the method should accept. Normally, for events
similar to the CommandEvents fired by in-built
control types like Button and TextCtrl,
this argument should be 1, which will be the id of the control whose
CommandEvents are being listened for.

Example

class MyCustomControl < Wx::Window … end class MyCustomEvent < Wx::CommandEvent end EVT_MY_CUSTOM = Wx::EvtHandler.new_event_type Wx::EvtHandler.register_class(MyCustomEvent, EVT_MY_CUSTOM, “evt_my_custom”, 1)

Instance Methods

EvtHandler#add_pending_event

add_pending_event(%(arg-type)Event% event)

This function posts an event to be processed later.

Parameters

Remarks

The difference between sending an event (using the
process_event method) and posting it is
that in the first case the event is processed before the function returns,
while in the second case, the function returns immediately and the event will
be processed sometime later (usually during the next event loop iteration).

A copy of event is made by the function, so the original can be deleted
as soon as function returns (it is common that the original is created on the
stack). This requires that the Event#clone method
be implemented by event so that it can be duplicated and stored until
it gets processed.

This is also the method to call for inter-thread communication—-it will
post events safely between different threads which means that this method is
thread-safe by using critical sections where needed. In a multi-threaded
program, you often need to inform the main GUI thread about the status of
other working threads and such notification should be done using this method.

This method automatically wakes up idle handling if the underlying window
system is currently idle and thus would not send any idle events. (Waking
up idle handling is done calling ::WakeUpIdle.)

EvtHandler#connect

connect(%(arg-type)Integer% id, Integer lastId, EventType eventType) { … }

Listens for events of the specified type and runs the associated block
when they occur. The id parameters are required for some events to
specify a particular object whose events are to be listened for -
typically, a control. A small number of event types accept a range, but
the second parameter is normally Wx::ID_ANY.

Note that it is usually simpler and more convenient to use the evt_xxx
methods than using connect directly.

Parameters

EvtHandler#disconnect

Boolean disconnect(%(arg-type)Integer% first_id, Integer last_id = ID_ANY, EventType evt_type = nil)

Disconnects event handlers which match the criteria passed in as
arguments. Returns true if any matching event handlers were found and
disconnected, or false if no changes were made.

The first_id is the wx identifier of the window whose events are no
longer to be responded to. The second_id is the optional upper part of
an id range, for those types of event handlers that accept ranges.

The evt_type is the type of events that should no longer be
handled. evt_type may be passed as either a Integer constant (for
example Wx::EVT_COMMAND_BUTTON_CLICKED), or may be the symbol name of
the method used to set up the event handler (for example :evt_button).
If evt_type is nil – the default – then all event types will be
disconnected.

EvtHandler#get_client_data

Object get_client_data()

Gets user-supplied client data.

Remarks

Normally, any extra data the programmer wishes to associate with the object
should be made available by deriving a new class with new data members.

See also

EvtHandler#set_client_data

EvtHandler#get_client_object

ClientData get_client_object()

Get a pointer to the user-supplied client data object.

See also

EvtHandler#set_client_object,
ClientData

EvtHandler#get_evt_handler_enabled

Boolean get_evt_handler_enabled()

Returns true if the event handler is enabled, false otherwise.

See also

EvtHandler#set_evt_handler_enabled

EvtHandler#get_next_handler

EvtHandler get_next_handler()

Gets the pointer to the next handler in the chain.

See also

EvtHandler#set_next_handler, EvtHandler#get_previous_handler, EvtHandler#set_previous_handler, Window#push_event_handler, Window#pop_event_handler

EvtHandler#get_previous_handler

EvtHandler get_previous_handler()

Gets the pointer to the previous handler in the chain.

See also

EvtHandler#set_previous_handler, EvtHandler#get_next_handler, EvtHandler#set_next_handler, Window#push_event_handler, Window#pop_event_handler

EvtHandler#process_event

Boolean process_event(%(arg-type)Event% event)

Processes an event, searching event tables and calling zero or more suitable event handler function(s).

Parameters

Return value

true if a suitable event handler function was found and executed, and the function did not
call Event#skip.

Remarks

Normally, your application would not call this function: it is called in the Widgets
implementation to dispatch incoming user interface events to the framework (and application).

However, you might need to call it if implementing new functionality (such as a new control) where
you define new event types, as opposed to allowing the user to override virtual functions.

An instance where you might actually override the ProcessEvent function is where you want
to direct event processing to event handlers not normally noticed by Widgets. For example,
in the document/view architecture, documents and views are potential event handlers.
When an event reaches a frame, ProcessEvent will need to be called on the associated
document and view in case event handler functions are associated with these objects.
The property classes library (Property) also overrides ProcessEvent for similar reasons.

The normal order of event table searching is as follows:

  1. If the object is disabled (via a call to EvtHandler#set_evt_handler_enabled)
    the function skips to step (6).
  2. If the object is a Window, ProcessEvent is recursively called on the window’s Validator. If this returns true, the function exits.
  3. SearchEventTable is called for this event handler. If this fails, the base
    class table is tried, and so on until no more tables exist or an appropriate function was found,
    in which case the function exits.
  4. The search is applied down the entire chain of event handlers (usually the chain has a length
    of one). If this succeeds, the function exits.
  5. If the object is a Window and the event is a CommandEvent, ProcessEvent is
    recursively applied to the parent window’s event handler. If this returns true, the function exits.
  6. Finally, ProcessEvent is called on the App object.

See also

EvtHandler#search_event_table

EvtHandler#search_event_table

Boolean search_event_table(%(arg-type)EventTable% table, Event event)

Searches the event table, executing an event handler function if an appropriate one
is found.

Parameters

Return value

true if a suitable event handler function was found and executed, and the function did not
call Event#skip.

Remarks

This function looks through the object’s event table and tries to find an entry
that will match the event.

An entry will match if:

  1. The event type matches, and
  2. the identifier or identifier range matches, or the event table entry’s identifier is zero.

If a suitable function is called but calls Event#skip, this function will
fail, and searching will continue.

See also

EvtHandler#process_event

EvtHandler#set_client_data

set_client_data(%(arg-type)% data)

Sets user-supplied client data.

Parameters

Remarks

Normally, any extra data the programmer wishes to associate with
the object should be made available by deriving a new class
with new data members. You must not call this method and
set_client_object on the
same class – only one of them.

See also

EvtHandler#get_client_data

EvtHandler#set_client_object

set_client_object(%(arg-type)ClientData% data)

Set the client data object. Any previous object will be deleted.

See also

EvtHandler#get_client_object,
ClientData

EvtHandler#set_evt_handler_enabled

set_evt_handler_enabled(%(arg-type)Boolean% enabled)

Enables or disables the event handler.

Parameters

Remarks

You can use this function to avoid having to remove the event handler from the chain, for example
when implementing a dialog editor and changing from edit to test mode.

See also

EvtHandler#get_evt_handler_enabled

EvtHandler#set_next_handler

set_next_handler(%(arg-type)EvtHandler% handler)

Sets the pointer to the next handler.

Parameters

See also

EvtHandler#get_next_handler, EvtHandler#set_previous_handler, EvtHandler#get_previous_handler, Window#push_event_handler, Window#pop_event_handler

EvtHandler#set_previous_handler

set_previous_handler(%(arg-type)EvtHandler% handler)

Sets the pointer to the previous handler.

Parameters

See also

EvtHandler#get_previous_handler, EvtHandler#set_next_handler, EvtHandler#get_next_handler, Window#push_event_handler, Window#pop_event_handler

[This page automatically generated from the Textile source at 2023-06-09 00:45:27 +0000]