DarkRadiant EventManager

From The DarkMod Wiki
Jump to: navigation, search

The EventManager plugin provides methods to define events and connect them to (member) functions that are called upon connect. In addition to that it implements a subclass to interpret the various mouseclick/modifier combinations for the different Windows (Orthoview, Camera).

Connecting Widgets to Events

The events can be connected to certain GtkWidgets (like GtkMenuItems, GtkCheckMenuItems and GtkToolButtons/GtkToggleToolButtons). The events recognise the supported widet types and connect the GTK callbacks automatically. For example, a Toggle event can of course be connected to a GtkCheckMenuItem or a GtkToggleToolButton, whereas a Command event cannot (connect it to a GtkMenuItem instead).

Event Types

The interface of an event (IEvent) is defined in ieventmanager.h. Events have to be created via the EventManager interface methods (e.g. addCommand(), addToggle(), addRegistryToggle() and so on). Each command can be enabled and disabled (enableEvent(), disableEvent()).

  • (Event) - this is the basic, empty implementation of an event. It is used internally by the EventManager only.
  • Command - this is a single-fire event that calls a function upon "KeyDown". Compatible widgets: GtkMenuItem, GtkToolButton, GtkButton
  • Toggle - this is an event that has an internal bool state, that gets inverted on "KeyDown". Compatible widgets: GtkCheckMenuItem, GtkToggleToolButton, GtkToggleButton.
  • RegistryToggle - use this if you want the Event to invert a boolean value (i.e. "0"/"1") in the XMLRegistry. This event doesn't require a callback upon creation (only the event name and the registry key), as the change of the connected RegistryKey can be catched by implementing a RegistryKeyObserver class (or letting a class derive from RegistryKeyObserver). There are some examples in the GlobalXYWnd or the CameraSettings class to see how a RegistryKeyObserver can be implemented. As a RegistryToggle derives from the Toggle event, it can of course be connected to the same GtkWidgets.
  • WidgetToggle - this is also deriving from Toggle and provides some special behaviour when connected to a widget. It can basically be used to show/hide certain widgets (as implemented for the Camera Window) upon connection. Being of type Toggle it can of course be connected to the GtkCheckMenuItem and GtkToggleToolButton, but in addition to that it can be connected to any other widget as well. If the passed widget is NOT a ToggleToolButton/CheckMenuItem, the widget is added to an internal list. Upon activation of the toggle the whole widget list is shown/hidden according to the internal event state bool. So a WidgetToggle can be used to implement an easy-to-use Togglebutton to show hide a window or a checkbox or something else.
  • KeyEvent - this is an event that catches both "KeyDown" and "KeyUp" of the according Accelerator and calls the connected callback functions. Use this if your class needs to implement a custom key handler (an example is the Camera Window in free-look mode).

Accelerators

Each event can be connected to an accelerator, the definitions for this are stored in the input.xml file in the <shortcut> tags. The accelerators are connected by the EventManager itself on DarkRadiant startup, so to add a shortcut to a specific event, one currently has to edit the input.xml.

The accelerator class passes both GDK events (KeyUp and KeyDown) to the connected event, it is the concern of the event to react on the call or not. For example, the basic Command event does only react on KeyDown, and does nothing on KeyRelease. It's perfectly possible to implement such an event, however.