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

Class Methods

EvtHandler.new_event_type

Integer new_event_type()

EvtHandler.register_class

Integer register_class(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(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(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(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(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(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(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(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(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(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 Wed Sep 09 02:21:07 +0100 2009]