minxlib::event Struct Reference

A generic X event, i.e., XAnyEvent. More...

#include <event.hh>

Public Member Functions
virtual	~event ()
	Event object clean-up. More...

Static Public Member Functions
static boost::shared_ptr< event >	create (const XEvent &e, Display *d)
	Factory method for creating events. More...
static void	pythonize ()
	Export event class to minxlib Python module. More...

Public Attributes
const int	type
	Event type as specified in X11/X.h. More...
const unsigned long	serial
	Last request number processed by X server. More...
const bool	send_event
	True if triggered by SendEvent request. More...
const window	target
	Event's target window. More...

Protected Types
typedef event *(*	cr_func )(const XEvent &, Display *)
	Signature of factory functions for creating events. More...
typedef void(*	py_func )()
	Signature of Pythonize functions. More...
typedef factory_map< int, cr_func, py_func >	registry
	Registry of subclass object factories and Pythonize functions. More...

Protected Member Functions
	event (const XEvent &e, Display *d, Window w)
	Create a wrapper object for an X event. More...

Detailed Description

A generic X event, i.e., XAnyEvent.

This is a base class for the event hierarchy exposed by minxlib to the Python parts (i.e., the rest) of Minx. The "main" window manager object, viz., minx.core.wm, will receive instances of subclasses of this class in its event loop when it calls minxlib.display.get_event().

If the Minx core receives an instance of this class itself, that means the event in question is an unregistered type. For registered event types, when an event is retrieved from the X event queue, we examine the event structure's type field and then create an object corresponding to that type and return the resulting object via a pointer to this class.

For example, if we get a key press event from the X server, the XEvent will be used to create a minxlib::key_press object (which is derived from minxlib::event) and, then, we will return the key_press as a minxlib::event*.

This module, viz., event.hh, uses an object factory to achieve the subclass object creation procedure described above. Unregistered event types are simply those XEvent::type values for which minxlib has no corresponding wrapper class derived from minxlib::event.

It should be alright for the Minx core to ignore such unregistered events because, in all likelihood, the window manager won't care for them. However, if it becomes necessary to respond to an event that is not properly wrapped by minxlib, then the correct way to effect that would be to implement the wrapper class in this module so that the Python parts of Minx see an event object derived from minxlib.event rather than an instance of minxlib.event itself.

On the Python side of Minx, the event type can, of course, be determined using the isinstance() function or the object's __class__ attribute. However, it may be more convenient to simply use the str() function to get a string representation of the event object and use that instead.

All minxlib.event objects have names of the form "x_something". For example, a key press event is called "x_key_press"; map requests are "x_map_request"; so on and so forth. The "x" in these object names indicate that the events are X events.

Member Typedef Documentation

typedef event*(* minxlib::event::cr_func)(const XEvent &, Display *)

protected

Signature of factory functions for creating events.

Each event subclass is instantiated by a factory function that takes an XEvent structure and a display pointer and returns a subclass instance upcast to minxlib::event. This type provides a convenient name for factory functions matching the above-mentioned signature.

All minxlib::event subclasses are required to implement a factory function matching this signature and to register it with the base class's registry of subclass object factories. Usually, the factory function will simply be the appropriate create_object function from minxlib's factory infrastructure.

typedef void(* minxlib::event::py_func)()

protected

Signature of Pythonize functions.

In addition to a factory function, each subclass of minxlib::event has to define a Pythonize function that will have the appropriate Boost.Python incantations in order to export its interface to minxlib's Python module.

All subclass Pythonize functions will be called by event::pythonize(), which is invoked by the main Python initialization module python.cc. Pythonize functions take no parameters and return nothing.

Like the factory functions, subclasses must register their Pythonize functions with the base class's registry of object factories, which stores pointers to the Pythonize functions in addition to the factory functions.

Note

Subclass Pythonize functions are usually static member functions in their respective classes.

typedef factory_map<int, cr_func, py_func> minxlib::event::registry

protected

Registry of subclass object factories and Pythonize functions.

This type defines the event object factory's registry, which maps the Xlib event type codes to the corresponding event subclass's factory function. Additionally, we store the Pythonize functions in the registry as well, which obviates the need for another map to hold them.

For the factory pattern to work, event subclasses must define a static boolean data member and, in its initializer, call event::registry::add(), passing it the appropriate Xlib event code, the subclass's factory function, and its Pythonize function.

Constructor & Destructor Documentation

minxlib::event::event ( const XEvent &  e, Display *  d, Window  w  )

protected

Create a wrapper object for an X event.

Parameters

e	The X event structure.
d	The display object associated with the event.
w	The Xlib ID of the target window for the event.

Returns

A properly constructed event object.

A protected constructor because event objects are meant to be instantiated using the create() factory method with only subclasses constructing the base data members.

Note

The fifth member of all Xlib event structures is a Window ID. However, in some of them, this field refers to the event's target window, while, in others, it refers to the target window's parent.

In this base class, we don't know exactly which Xlib event structure to use from the XEvent union; only the subclasses that wrap around specific event types have that information. Therefore, we require all subclasses to specify the correct ID to use for the target window and ignore whatever is in XEvent::xany.

virtual minxlib::event::~event ( )

virtual

Event object clean-up.

Returns

Nothing.

Because minxlib::event is a base class for other event types, it is a good idea for it to have a virtual destructor. This is especially necessary for the event class hierarchy because all events are created using a polymorphic factory that upcasts all subclass instances to minxlib::event*. Consequently, we have to provide a virtual destructor to ensure subclass objects are properly cleaned up when the base class pointers are deleted.

Furthermore, to get the magic conversions in Boost.Python to work properly, we need at least one virtual method in the minxlib::event base class. Otherwise, on the Python side, instances of subclasses of this class will not have the correct type; the Python interpreter will see those objects as instances of minxlib.event rather than their actual derived types.

Member Function Documentation

static boost::shared_ptr<event> minxlib::event::create ( const XEvent &  e, Display *  d  )

static

Factory method for creating events.

Parameters

e	The X event structure for which we want a wrapper object.
d	The display object associated with the event.

Returns

Event object created on heap and wrapped in a smart pointer.

We would like to expose the Xlib event types in such a way that the Python parts of Minx see a high-level, object-oriented interface to event processing instead of having to deal with low-level integers describing event types, etc. To achieve that, we use the factory design pattern to create objects based on the XEvent::type field.

This method provides the public interface to the above-mentioned event object factory. It is meant to be used by minxlib::display::get_event() in order to convert low-level X event structures into appropriate object types belonging to minxlib's event hierarchy.

Note

minxlib does not provide wrapper classes for all Xlib event types. Unwrapped event types will be reported via an instance of this, i.e., the event base class.

Boost.Python has all sorts of magic in it to convert C++ objects to their Python equivalents and vice versa. Since instances of minxlib::event are created using an object factory, i.e., on the heap and accessed via pointers, we need to wrap event objects in a boost::shared_ptr to make the Boost.Python conversion magic work with minimal effort.

static void minxlib::event::pythonize ( )

static

Export event class to minxlib Python module.

Returns

Nothing.

This function exposes the event class's interface so that it can be used by the Python parts of Minx. It is meant to be called by the Boost.Python initialization code in python.cc.

Note

This function will call the Pythonize functions of all the minxlib::event subclasses, thus, exporting the entire minxlib event hierarchy to Python. For this to work, all subclasses must register their Pythonize routines with the base class object factory registry as described earlier.

Member Data Documentation

const bool minxlib::event::send_event

True if triggered by SendEvent request.

This flag will be true if the event is an "artificial" one, i.e., generated by an application calling the SendEvent function rather than by an actual key press, mouse move, etc.

const unsigned long minxlib::event::serial

Last request number processed by X server.

The X server "tags" each event it generates with a serial number. This field records that number. It is not really used in minxlib or in Minx's Python core.

const window minxlib::event::target

Event's target window.

This field specifies the window on which the event occurred. Note that it is a minxlib::window object, which wraps around the Xlib notion of an X window.

const int minxlib::event::type

Event type as specified in X11/X.h.

This field specifies the type of event using one of the codes in the X11/X.h header. The minxlib eventhierarchy" uses the value of this field in conjunction with an object factory to create instances of subclasses of the minxlib::event class.