Classes | Public Types | Public Member Functions | Private Attributes | Friends

gui2::event::tdispatcher Class Reference

Base class for event handling. More...

#include <dispatcher.hpp>

Inheritance diagram for gui2::event::tdispatcher:
Inheritance graph
[legend]
Collaboration diagram for gui2::event::tdispatcher:
Collaboration graph
[legend]

List of all members.

Classes

struct  tsignal
 Helper struct to generate the various signal types. More...
struct  tsignal_queue
 Helper struct to generate the various event queues. More...

Public Types

enum  tevent_type { pre = 1, child = 2, post = 4 }
enum  tposition {
  front_pre_child, back_pre_child, front_child, back_child,
  front_post_child, back_post_child
}
 

The position where to add a new callback in the signal handler.

More...
enum  tmouse_behaviour { all, hit, none }
 

The behaviour of the mouse events.

More...

Public Member Functions

 tdispatcher ()
virtual ~tdispatcher ()
void connect ()
 Connects the dispatcher to the event handler.
virtual bool is_at (const tpoint &coordinate) const =0
 Determines whether the location is inside an active widget.
bool has_event (const tevent event, const tevent_type event_type)
bool fire (const tevent event, twidget &target)
 Fires an event which has no extra parameters.
bool fire (const tevent event, twidget &target, const tpoint &coordinate)
 Fires an event which takes a coordinate parameter.
bool fire (const tevent event, twidget &target, const SDLKey key, const SDLMod modifier, const Uint16 unicode)
 Fires an event which takes keyboard parameters.
bool fire (const tevent event, twidget &target, void *)
 Fires an event which takes notification parameters.
bool fire (const tevent event, twidget &target, tmessage &message)
 Fires an event which takes message parameters.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event, boost::mpl::int_
< E > > >::type 
connect_signal (const tsignal_function &signal, const tposition position=back_child)
 Connect a signal for callback in tset_event.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event, boost::mpl::int_
< E > > >::type 
disconnect_signal (const tsignal_function &signal, const tposition position=back_child)
 Disconnect a signal for callback in tset_event.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_mouse,
boost::mpl::int_< E >
> >::type 
connect_signal (const tsignal_mouse_function &signal, const tposition position=back_child)
 Connect a signal for callback in tset_event_mouse.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_mouse,
boost::mpl::int_< E >
> >::type 
disconnect_signal (const tsignal_mouse_function &signal, const tposition position=back_child)
 Disconnect a signal for callback in tset_event_mouse.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_keyboard,
boost::mpl::int_< E >
> >::type 
connect_signal (const tsignal_keyboard_function &signal, const tposition position=back_child)
 Connect a signal for callback in tset_event_keyboard.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_keyboard,
boost::mpl::int_< E >
> >::type 
disconnect_signal (const tsignal_keyboard_function &signal, const tposition position=back_child)
 Disconnect a signal for callback in tset_event_keyboard.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_notification,
boost::mpl::int_< E >
> >::type 
connect_signal (const tsignal_notification_function &signal, const tposition position=back_child)
 Connect a signal for callback in tset_event_notification.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_notification,
boost::mpl::int_< E >
> >::type 
disconnect_signal (const tsignal_notification_function &signal, const tposition position=back_child)
 Disconnect a signal for callback in tset_event_notification.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_message,
boost::mpl::int_< E >
> >::type 
connect_signal (const tsignal_message_function &signal, const tposition position=back_child)
 Connect a signal for callback in tset_event_message.
template<tevent E>
boost::enable_if
< boost::mpl::has_key
< tset_event_message,
boost::mpl::int_< E >
> >::type 
disconnect_signal (const tsignal_message_function &signal, const tposition position=back_child)
 Disconnect a signal for callback in tset_event_message.
void capture_mouse ()
 Captures the mouse.
void release_mouse ()
 Releases the mouse capture.
void set_mouse_behaviour (const tmouse_behaviour mouse_behaviour)
tmouse_behaviour get_mouse_behaviour () const
void set_want_keyboard_input (const bool want_keyboard_input)
bool get_want_keyboard_input () const
void register_hotkey (const hotkey::HOTKEY_COMMAND id, const thotkey_function &function)
 Registers a hotkey.
bool execute_hotkey (const hotkey::HOTKEY_COMMAND id)
 Executes a hotkey.

Private Attributes

tmouse_behaviour mouse_behaviour_
 The mouse behaviour for the dispatcher.
bool want_keyboard_input_
 Does the dispatcher want to receive keyboard input.
tsignal_queue< tsignal_functionsignal_queue_
 Signal queue for callbacks in tset_event.
tsignal_queue
< tsignal_mouse_function
signal_mouse_queue_
 Signal queue for callbacks in tset_event_mouse.
tsignal_queue
< tsignal_keyboard_function
signal_keyboard_queue_
 Signal queue for callbacks in tset_event_keyboard.
tsignal_queue
< tsignal_notification_function
signal_notification_queue_
 Signal queue for callbacks in tset_event_notification.
tsignal_queue
< tsignal_message_function
signal_message_queue_
 Signal queue for callbacks in tset_event_message.
bool connected_
 Are we connected to the event handler.
std::map
< hotkey::HOTKEY_COMMAND,
thotkey_function
hotkeys_
 The registered hotkeys for this dispatcher.

Friends

struct tdispatcher_implementation

Detailed Description

Base class for event handling.

A dispatcher has slots for events, when an event arrives it looks for the functions that registered themselves for that event and calls their callbacks.

This class is a base class for all widgets[1], what a widget does on a callback can differ greatly, an image might ignore all events a window can track the mouse location and fire MOUSE_ENTER and MOUSE_LEAVE events to the widgets involved.

[1] Not really sure whether it will be a base clase for a twidget or tcontrol yet.

Definition at line 135 of file dispatcher.hpp.


Member Enumeration Documentation

Enumerator:
pre 
child 
post 

Definition at line 167 of file dispatcher.hpp.

The behaviour of the mouse events.

Normally for mouse events there's first cheched whether a dispatcher has captured the mouse if so it gets the event. If not the dispatcher is searched from the back to the front in the layers and it's behavious is checked. * none The event is never send to the layer and goes on the the next layer. This is used for tooltips who might cover a button but a click on the tooltips should still click the button. * all The event is always send to this layer and stops the search for a next layer. * hit If the mouse is inside the dispatcher area the event is send and no longer searched further. If not inside tests the last layer.

If after these tests no dispatcher is found the event is ignored.

Enumerator:
all 
hit 
none 

Definition at line 490 of file dispatcher.hpp.

The position where to add a new callback in the signal handler.

The signal handler has three callback queues: * pre_child These callbacks are called before a container widget sends it to the child items. Widgets without children should also use this queue. * child The callbacks for the proper child widget(s) are called. * post_child The callbacks for the parent container to be called after the child.

For every queue it's possible to add a new event in the front or in the back.

Whether all three queues are executed depend on the whether the callbacks modify the handled and halt flag. * When the halt flag is set execution of the current queue stops, when doing so the handled flag must be set as well. * When the handled flag is set the events in that queue are executed and no more queues afterwards.

Here are some use case examples. A button that plays a sound and executes an optional user callback: * The buttons internal click handler is invoked and sets the handled flag * The callback installed by the user is in the same queue and gets exectuted afterwards.

A toggle button may or may not be toggled: * The user inserts a callback, that validates whether the action is allowed, if not allowed it sets the halt flag (and handled), else leaves the flags untouched. * The normal buttons toggle function then might get invoked and if so sets the handled flag. * Optionally there is another user callback invoked at this point.

Enumerator:
front_pre_child 
back_pre_child 
front_child 
back_child 
front_post_child 
back_post_child 

Definition at line 262 of file dispatcher.hpp.


Constructor & Destructor Documentation

gui2::event::tdispatcher::tdispatcher (  ) 

Definition at line 23 of file dispatcher.cpp.

gui2::event::tdispatcher::~tdispatcher (  )  [virtual]

Definition at line 36 of file dispatcher.cpp.


Member Function Documentation

void gui2::event::tdispatcher::capture_mouse (  )  [inline]

Captures the mouse.

Definition at line 498 of file dispatcher.hpp.

void gui2::event::tdispatcher::connect (  ) 

Connects the dispatcher to the event handler.

When a dispatcher is connected to the event handler it will get the events directly from the event handler. This is wanted for top level items like windows but not for most other widgets.

So a window can call connect to register itself, it will automatically disconnect upon destruction.

Definition at line 43 of file dispatcher.cpp.

References connected_, and gui2::event::disconnect_dispatcher().

Referenced by gui2::twindow::twindow().

Here is the call graph for this function:

Here is the caller graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::connect_signal ( const tsignal_function signal,
const tposition  position = back_child 
) [inline]

Connect a signal for callback in tset_event.

The function uses some boost magic to avoid registering the wrong function, but the common way to use this function is: widget->connect_signal<EVENT_ID>( boost::bind(&tmy_dialog::my_member, this)); This allows simply adding a member of a dialog to be used as a callback for widget without a lot of magic. Note most widgets probaly will get a callback like connect_signal_mouse_left_click(const tsignal_function& callback) which hides this function for the avarage use.

Template Parameters:
E The event the callback needs to react to.
Parameters:
signal The callback function.
position The position to place the callback.

Definition at line 292 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::connect_signal(), and signal_queue_.

Referenced by connect_queue(), gui2::event::connect_signal_mouse_left_click(), gui2::event::connect_signal_notify_modified(), gui2::event::connect_signal_pre_key_press(), gui2::tlobby_main::post_build(), gui2::event::tdistributor::tdistributor(), and gui2::ttree_view_node::ttree_view_node().

Here is the call graph for this function:

Here is the caller graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_message, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::connect_signal ( const tsignal_message_function signal,
const tposition  position = back_child 
) [inline]

Connect a signal for callback in tset_event_message.

Template Parameters:
E The event the callback needs to react to.
Parameters:
signal The callback function.
position The position to place the callback. Since the message is send to a widget directly the pre and post positions make no sense and shouldn't be used.

Definition at line 443 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::connect_signal(), and signal_message_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_mouse, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::connect_signal ( const tsignal_mouse_function signal,
const tposition  position = back_child 
) [inline]

Connect a signal for callback in tset_event_mouse.

Template Parameters:
E The event the callback needs to react to.
Parameters:
signal The callback function.
position The position to place the callback.

Definition at line 327 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::connect_signal(), and signal_mouse_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_keyboard, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::connect_signal ( const tsignal_keyboard_function signal,
const tposition  position = back_child 
) [inline]

Connect a signal for callback in tset_event_keyboard.

Template Parameters:
E The event the callback needs to react to.
Parameters:
signal The callback function.
position The position to place the callback.

Definition at line 362 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::connect_signal(), and signal_keyboard_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_notification, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::connect_signal ( const tsignal_notification_function signal,
const tposition  position = back_child 
) [inline]

Connect a signal for callback in tset_event_notification.

Template Parameters:
E The event the callback needs to react to.
Parameters:
signal The callback function.
position The position to place the callback. Since the message is send to a widget directly the pre and post positions make no sense and shouldn't be used.

Definition at line 400 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::connect_signal(), and signal_notification_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_notification, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::disconnect_signal ( const tsignal_notification_function signal,
const tposition  position = back_child 
) [inline]

Disconnect a signal for callback in tset_event_notification.

Template Parameters:
E The event the callback was used for.
Parameters:
signal The callback function.
position The place where the function was added. Needed remove the event from the right place. (The function doesn't care whether was added in front or back, but it needs to know the proper queue so it's save to add with front_child and remove with back_child. But it's not save to add with front_child and remove with front_pre_child)

Definition at line 424 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::disconnect_signal(), and signal_notification_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_message, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::disconnect_signal ( const tsignal_message_function signal,
const tposition  position = back_child 
) [inline]

Disconnect a signal for callback in tset_event_message.

Template Parameters:
E The event the callback was used for.
Parameters:
signal The callback function.
position The place where the function was added. Needed remove the event from the right place. (The function doesn't care whether was added in front or back, but it needs to know the proper queue so it's save to add with front_child and remove with back_child. But it's not save to add with front_child and remove with front_pre_child)

Definition at line 467 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::disconnect_signal(), and signal_message_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::disconnect_signal ( const tsignal_function signal,
const tposition  position = back_child 
) [inline]

Disconnect a signal for callback in tset_event.

Template Parameters:
E The event the callback was used for.
Parameters:
signal The callback function.
position The place where the function was added. Needed remove the event from the right place. (The function doesn't care whether was added in front or back.)

Definition at line 311 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::disconnect_signal(), and signal_queue_.

Referenced by gui2::event::disconnect_signal_mouse_left_click().

Here is the call graph for this function:

Here is the caller graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_mouse, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::disconnect_signal ( const tsignal_mouse_function signal,
const tposition  position = back_child 
) [inline]

Disconnect a signal for callback in tset_event_mouse.

Template Parameters:
E The event the callback was used for.
Parameters:
signal The callback function.
position The place where the function was added. Needed remove the event from the right place. (The function doesn't care whether was added in front or back.)

Definition at line 346 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::disconnect_signal(), and signal_mouse_queue_.

Here is the call graph for this function:

template<tevent E>
boost::enable_if<boost::mpl::has_key< tset_event_keyboard, boost::mpl::int_<E> > >::type gui2::event::tdispatcher::disconnect_signal ( const tsignal_keyboard_function signal,
const tposition  position = back_child 
) [inline]

Disconnect a signal for callback in tset_event_keyboard.

Template Parameters:
E The event the callback was used for.
Parameters:
signal The callback function.
position The place where the function was added. Needed remove the event from the right place. (The function doesn't care whether was added in front or back.)

Definition at line 381 of file dispatcher.hpp.

References gui2::event::tdispatcher::tsignal_queue< T >::disconnect_signal(), and signal_keyboard_queue_.

Here is the call graph for this function:

bool gui2::event::tdispatcher::execute_hotkey ( const hotkey::HOTKEY_COMMAND  id  ) 

Executes a hotkey.

Parameters:
id The hotkey to execute.
Returns:
true if the hotkey is handled, false otherwise.

Definition at line 318 of file dispatcher.cpp.

References hotkeys_.

Referenced by gui2::event::thandler::hotkey_pressed().

Here is the caller graph for this function:

bool gui2::event::tdispatcher::fire ( const tevent  event,
twidget target 
)
bool gui2::event::tdispatcher::fire ( const tevent  event,
twidget target,
tmessage message 
)

Fires an event which takes message parameters.

Parameters:
event The event to fire.
target The widget that should receive the event. Normally this is the window holding the widget.
message The extra information needed for a window (or another widget in the chain) to handle the message.

Definition at line 303 of file dispatcher.cpp.

bool gui2::event::tdispatcher::fire ( const tevent  event,
twidget target,
const SDLKey  key,
const SDLMod  modifier,
const Uint16  unicode 
)

Fires an event which takes keyboard parameters.

Parameters:
event The event to fire.
target The widget that should receive the event.
key The SDL key code of the key pressed.
modifier The SDL key modifiers used.
unicode The unicode value for the key pressed.

Definition at line 242 of file dispatcher.cpp.

bool gui2::event::tdispatcher::fire ( const tevent  event,
twidget target,
const tpoint coordinate 
)

Fires an event which takes a coordinate parameter.

Parameters:
event The event to fire.
target The widget that should receive the event.
coordinate The mouse position for the event.

Definition at line 203 of file dispatcher.cpp.

bool gui2::event::tdispatcher::fire ( const tevent  event,
twidget target,
void *   
)

Fires an event which takes notification parameters.

Note:
the void* parameter is a dummy needed for SFINAE.
Parameters:
event The event to fire.
target The widget that should receive the event.

Definition at line 270 of file dispatcher.cpp.

tmouse_behaviour gui2::event::tdispatcher::get_mouse_behaviour (  )  const [inline]

Definition at line 516 of file dispatcher.hpp.

References mouse_behaviour_.

bool gui2::event::tdispatcher::get_want_keyboard_input (  )  const [inline]

Definition at line 526 of file dispatcher.hpp.

References want_keyboard_input_.

bool gui2::event::tdispatcher::has_event ( const tevent  event,
const tevent_type  event_type 
)

Definition at line 50 of file dispatcher.cpp.

References gui2::event::connect_dispatcher(), and connected_.

Referenced by gui2::event::implementation::build_event_chain().

Here is the call graph for this function:

Here is the caller graph for this function:

virtual bool gui2::event::tdispatcher::is_at ( const tpoint coordinate  )  const [pure virtual]

Determines whether the location is inside an active widget.

This is used to see whether a mouse event is inside the widget.

Parameters:
coordinate The coordinate to test whether inside the widget.
Returns:
True if inside an active widget, false otherwise.

Implemented in gui2::twidget.

void gui2::event::tdispatcher::register_hotkey ( const hotkey::HOTKEY_COMMAND  id,
const thotkey_function function 
)

Registers a hotkey.

Todo:
add a static function register_global_hotkey.

Once that's done execute_hotkey will first try to execute a global hotkey and if that fails tries the hotkeys in this dispatcher.

Parameters:
id The hotkey to register.
function The callback function to call.

Definition at line 312 of file dispatcher.cpp.

Referenced by gui2::ttitle_screen::post_build(), gui2::tlobby_main::post_build(), and gui2::twindow::twindow().

Here is the caller graph for this function:

void gui2::event::tdispatcher::release_mouse (  )  [inline]

Releases the mouse capture.

Definition at line 504 of file dispatcher.hpp.

void gui2::event::tdispatcher::set_mouse_behaviour ( const tmouse_behaviour  mouse_behaviour  )  [inline]

Definition at line 511 of file dispatcher.hpp.

References mouse_behaviour_.

Referenced by gui2::twindow::show_non_modal(), and gui2::twindow::show_tooltip().

Here is the caller graph for this function:

void gui2::event::tdispatcher::set_want_keyboard_input ( const bool  want_keyboard_input  )  [inline]

Definition at line 521 of file dispatcher.hpp.

References want_keyboard_input_.

Referenced by gui2::twindow::show_tooltip().

Here is the caller graph for this function:


Friends And Related Function Documentation

friend struct tdispatcher_implementation [friend]

Definition at line 137 of file dispatcher.hpp.


Member Data Documentation

Are we connected to the event handler.

Definition at line 707 of file dispatcher.hpp.

Referenced by connect(), and has_event().

The registered hotkeys for this dispatcher.

Definition at line 710 of file dispatcher.hpp.

Referenced by execute_hotkey().

The mouse behaviour for the dispatcher.

Definition at line 677 of file dispatcher.hpp.

Referenced by get_mouse_behaviour(), and set_mouse_behaviour().

Signal queue for callbacks in tset_event_keyboard.

Definition at line 698 of file dispatcher.hpp.

Referenced by connect_signal(), and disconnect_signal().

Signal queue for callbacks in tset_event_message.

Definition at line 704 of file dispatcher.hpp.

Referenced by connect_signal(), and disconnect_signal().

Signal queue for callbacks in tset_event_mouse.

Definition at line 695 of file dispatcher.hpp.

Referenced by connect_signal(), and disconnect_signal().

Signal queue for callbacks in tset_event_notification.

Definition at line 701 of file dispatcher.hpp.

Referenced by connect_signal(), and disconnect_signal().

Signal queue for callbacks in tset_event.

Definition at line 692 of file dispatcher.hpp.

Referenced by connect_signal(), and disconnect_signal().

Does the dispatcher want to receive keyboard input.

Todo:
The entire mouse and keyboard handling can use a code review to seen whether it might be combined in one flag field. At the moment the keyboard doesn't look whether a dialog has the mouse focus before sending the event, so maybe we should add an active dispatcher to keep track of it. But since at the moment there are only non-modal windows and tooltips it's not a problem.

Definition at line 689 of file dispatcher.hpp.

Referenced by get_want_keyboard_input(), and set_want_keyboard_input().


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated by doxygen 1.7.1 on Thu May 24 2012 01:23:58 for The Battle for Wesnoth
Gna! | Forum | Wiki | CIA | devdocs