Encapsulate the details of the connection to the X server. More...

#include <display.hh>

Public Member Functions
	display (const std::string &name=std::string(), bool sync=false)
	Open a connection to the X server. More...

	~display ()
	Close the connection to the X server. More...

window	create_window (const window &p, int x, int y, int w, int h)
	Create a window. More...

std::vector< root_window >	get_root_windows ()
	Retrieve the list of root windows. More...

std::vector< window >	get_top_level_windows ()
	Retrieve top-level windows across all screens. More...

window	get_focused_window ()
	Get the window with the input focus. More...

std::vector< std::string >	get_keyboard_mapping ()
	Retrieve currently supported keysyms in string form. More...

boost::shared_ptr< event >	get_event ()
	Retrieve the next event from the X server. More...

Static Public Member Functions
static void	pythonize ()
	Export the display class to minxlib Python module. More...

Detailed Description

Encapsulate the details of the connection to the X server.

This class provides an API for the Python parts of Minx to be able to talk to the display server. It wraps around the relevant parts of Xlib and exposes its functionality to Python via Boost.Python.

This class is meant to be used by the minx.core.wm Python class. When end-user Minx configs start-up the window manager, they will instantiate minx.core.wm, which, in turn, will create an instance of minxlib::display to establish the connection to the X server.

Note: This class should only be instantiated once and really should not be subclassed. However, there is nothing in its implementation to prevent you from creating multiple minxlib::display objects or from subclassing it.

: Nonetheless, it is rare to ever want to have more than one instance of this class, to subclass it, or to want to access it from multiple thread contexts. If you need to do such things, you will have to take care of the details of tracking the multiple connections, accessing them from different threads, etc.

: In short, don't do these funky things; minxlib and the minx library are not designed for it and you really shouldn't need such functionality anyway (multithreaded window manager with multiple connections to the X server? really? why? don't you have enough problems in your life already?).

Constructor & Destructor Documentation

minxlib::display::display	(	const std::string &	name = `std::string()`,
		bool	sync = `false`
	)

Open a connection to the X server.

Parameters

name	Name of the X server.
sync	Flag for synchronizing Xlib requests.

Returns: A valid connection to the display server.

Instantiating a minxlib::display object automatically sets up a connection to the X server. If the connection fails, a connection_error will be thrown.

The name parameter will usually be an empty string, in which case, the contructor will connect to the X server specified by the DISPLAY environment variable. If specified, it should be something like "host:0.0". Look up X server and Xlib documentation to get the low-down on this.

The sync flag indicates whether we want Xlib requests to be synchronous or not. By default, it is false, i.e., Xlib requests are buffered. Turning synchronization on is useful for debugging. Note that the choice between synchronous and buffered mode of operation is decided at creation time. That is, it cannot be toggled after a display object has been instantiated.

In addition to establishing the connection to the display server, this constructor will also setup Xlib error handlers. When the X server flags errors by invoking the handlers, they will be reported to Python clients via appropriate Python exceptions.

In case a fatal error is reported, clients are expected to clean-up and then terminate the process. The display object will become unusable after a fatal_error exception is thrown. Any attempt to use it after a fatal error will result in continued fatal_error exceptions.

minxlib::display::~display ( )

Close the connection to the X server.

Returns: Nothing.

When a display object is destroyed, it will automatically sever its connection to the display server.

Member Function Documentation

window minxlib::display::create_window	(	const window &	p,
		int	x,
		int	y,
		int	w,
		int	h
	)

Create a window.

Parameters

p	The new window's parent window.
x	The x-coordinate of the new window's origin.
y	The y-coordinate of the new window's origin.
w	The new window's width.
h	The new window's height.

Returns: The newly created window.

This function creates a new window by calling XCreateSimpleWindow(), wraps the result in a minxlib::window object and returns that.

The parameter p must be an existing window; x and y are relative to the parent's origin.

Note: Although this function can churn out arbitrary windows parented by arbitrary other windows, end-user code should most definitely not abuse it in that manner. It is meant to be used only to create layouts.

boost::shared_ptr<event> minxlib::display::get_event ( )

Retrieve the next event from the X server.

Returns: A minxlib::event object describing the X event.

This function removes the next event from the X event queue and returns it to its caller via an instance of a subclass of minxlib::event. This function is meant to be used by minx.core.wm in its event loop.

window minxlib::display::get_focused_window ( )

Get the window with the input focus.

Returns: Currently focused window.

This function uses XGetInputFocus() to determine which X window currently has the input focus and returns that wrapped in a minxlib::window object.

If no window has the input focus, this function will return a window with the ID zero.

std::vector<std::string> minxlib::display::get_keyboard_mapping ( )

Retrieve currently supported keysyms in string form.

Returns: List of strings containing current keysyms.

The X server assigns unique integer codes to each physical key on the keyboard. However, since different keyboard models and brands can have different keycodes, applications usually deal with keysyms, which are the symbols on the key caps (this is an oversimplification, but good enough for explanatory purposes).

This function queries the X server for its mapping between keycodes and keysyms, converts the keysyms to strings, and returns the resulting list.

std::vector<root_window> minxlib::display::get_root_windows ( )

Retrieve the list of root windows.

Returns: List of root windows.

This function queries the X server for all its screens and their corresponding root windows. The returned list holds the root windows in the screen order, i.e., the first element of the list is the root window for the first screen, the second is the root window for the second screen, so on and so forth.

Note: On multi-head setups with Xinerama, there is only one screen, and, thus, only one root window as far as the X server is concerned. Nonetheless, this function will still return as many root windows as there are physical monitors; each of these root windows will have the same window ID, but their geometries will be different.

std::vector<window> minxlib::display::get_top_level_windows ( )

Retrieve top-level windows across all screens.

Returns: List of top-level windows.

This function queries the X server for all the top-level windows on all screens. Do not rely on the returned list being in any particular order.

This function is meant to be used by minx.core.wm just before it enters its event loop so that Minx can manage any extant top-level windows that were created before Minx was started.

static void minxlib::display::pythonize ( )

static

Export the display class to minxlib Python module.

Returns: Nothing.

This function exposes the display 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.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation