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

- EvtHandler.register_class
- EvtHandler#add_pending_event
- EvtHandler#connect
- EvtHandler#disconnect
- EvtHandler#get_client_data
- EvtHandler#get_client_object
- EvtHandler#get_evt_handler_enabled
- EvtHandler#get_next_handler
- EvtHandler#get_previous_handler
- EvtHandler#process_event
- EvtHandler#search_event_table
- EvtHandler#set_client_data
- EvtHandler#set_client_object
- EvtHandler#set_evt_handler_enabled
- EvtHandler#set_next_handler
- EvtHandler#set_previous_handler

## 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

- event Event to add to process queue.

#### 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

- id The identifier (or first of the identifier range) to be
  associated with the event handler function. For the version not taking this
  argument, it defaults to `ID_ANY`.
- lastId The second part of the identifier range to be associated with the event handler function.
- eventType The event type to be associated with this event handler.

### 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

- event Event to process.

#### 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

- table Event table to be searched.
- event Event to be matched against an event table entry.

#### 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

- data Data to be associated with the event handler.

#### 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

- enabled true if the event handler is to be enabled, false if it is to be disabled.

#### 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

- handler Event handler to be set as the next handler.

#### 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

- handler Event handler to be set as the previous handler.

#### 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]