Encapsulate the details of an X window. More...

#include <window.hh>

Public Types
enum	event_mask
	An enumeration for the different event masks. More...

enum	configure_mask
	An enumeration for the different configure values. More...

Public Member Functions
	window (Display *d, Window w)
	Create a wrapper object for an existing Xlib window. More...

bool	operator== (const window &w) const
	Window equality operator. More...

bool	operator!= (const window &w) const
	Window inequality operator. More...

bool	operator== (Window w) const
	Window equality operator. More...

bool	operator!= (Window w) const
	Window inequality operator. More...

	operator Window () const
	Convert to an Xlib Window. More...

std::map< std::string, std::string >	properties ()
	Retrieve window properties from X server. More...

virtual void	set_properties (const std::map< std::string, std::string > &prop)
	Set window properties. More...

virtual void	reparent (const window &p)
	Reparent this window to another. More...

virtual window	parent ()
	Get this window's parent window. More...

std::vector< window >	children ()
	Get this window's children. More...

virtual int	screen ()
	Get screen number of this window. More...

void	select_events (long mask)
	Set the X event mask for this window. More...

void	grab_key (const std::string &s)
	Setup a passive keyboard grab. More...

virtual void	show ()
	Show the window, i.e., map it. More...

virtual void	hide ()
	Hide this window, i.e., unmap it. More...

virtual bool	is_mapped ()
	Check if window is currently mapped or not. More...

virtual void	move_resize (int x, int y, int w, int h)
	Move and resize the window. More...

virtual void	configure (int x, int y, int w, int h, int b, const window *s, int t, unsigned int v)
	Configure the window. More...

virtual void	set_border_attr (unsigned long c, unsigned int s)
	Set window's border color and size. More...

virtual std::vector< int >	geometry ()
	Retrieve window's size, position, and border width. More...

virtual void	focus ()
	Set input focus on this window and raise it. More...

virtual void	kill ()
	Kill this window. More...

virtual void	nuke ()
	Kill this window using brute force. More...

virtual	~window ()
	Destructor. More...

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

Detailed Description

Encapsulate the details of an X window.

This class provides an API for the Python parts of Minx to be able to deal with X windows. It wraps around the relevant parts of Xlib and exposes its functionality to Python via Boost.Python.

Member Enumeration Documentation

enum minxlib::window::configure_mask

An enumeration for the different configure values.

This enumeration simply provides C++ names for the Xlib value mask for configure requests. These names are exported to Python via Boost.Python's enum exporting facility.

The minxlib and corresponding Xlib names for these enums are shown below:

minxlib	Xlib
configure_x	CWX
configure_y	CWY
configure_width	CWWidth
configure_height	CWHeight
configure_border_width	CWBorderWidth
configure_sibling	CWSibling
configure_stack_mode	CWStackMode

enum minxlib::window::event_mask

An enumeration for the different event masks.

This enumeration simply provides C++ names for the Xlib event masks that are exported to Python via Boost.Python's enum exporting facility.

minxlib's names for the event masks and their corresponding Xlib names are shown below:

minxlib	Xlib
no_event_mask	NoEventMask
key_press_mask	KeyPressMask
key_release_mask	KeyReleaseMask
button_press_mask	ButtonPressMask
button_release_mask	ButtonReleaseMask
enter_window_mask	EnterWindowMask
leave_window_mask	LeaveWindowMask
pointer_motion_mask	PointerMotionMask
pointer_motion_hint_mask	PointerMotionHintMask
button1_motion_mask	Button1MotionMask
button2_motion_mask	Button2MotionMask
button3_motion_mask	Button3MotionMask
button4_motion_mask	Button4MotionMask
button5_motion_mask	Button5MotionMask
button_motion_mask	ButtonMotionMask
keymap_state_mask	KeymapStateMask
exposure_mask	ExposureMask
visibility_change_mask	VisibilityChangeMask
structure_notify_mask	StructureNotifyMask
resize_redirect_mask	ResizeRedirectMask
substructure_notify_mask	SubstructureNotifyMask
substructure_redirect_mask	SubstructureRedirectMask
focus_change_mask	FocusChangeMask
property_change_mask	PropertyChangeMask
colormap_change_mask	ColormapChangeMask
owner_grab_button_mask	OwnerGrabButtonMask

Constructor & Destructor Documentation

minxlib::window::window	(	Display *	d,
		Window	w
	)

Create a wrapper object for an existing Xlib window.

Parameters

d	The display object to which the window is "linked."
w	The Xlib Window ID.

Returns: A valid window wrapper for the given Xlib window.

virtual minxlib::window::~window ( )

virtual

Destructor.

Returns: Nothing.

Clean-up for when a window object is deleted. Really, there's nothing to do because this class is only a thin wrapper around X windows and we only maintain a pointer to the Xlib display structure and an integral ID. We don't actually create or acquire anything when this class is instantiated; consequently, there's nothing to destroy or release.

Member Function Documentation

std::vector<window> minxlib::window::children ( )

Get this window's children.

Returns: Window's children.

This function uses XQueryTree() to determine the list of child windows of the X window encapsulated by this object. If the call to XQueryTree() fails, this function will return an empty list and, eventually, X will generate a protocol error.

virtual void minxlib::window::configure	(	int	x,
		int	y,
		int	w,
		int	h,
		int	b,
		const window *	s,
		int	t,
		unsigned int	v
	)

virtual

Configure the window.

Parameters

x	Window's x coordinate relative to parent's origin.
y	Window's y coordinate relative to parent's origin.
w	Window's width (not counting its border).
h	Window's height (not counting its border).
b	Window's border width.
s	Window's sibling for stacking operations.
t	Window's stacking mode.
v	Value mask to determine what to configure.

Returns: Nothing.

This function calls XConfigureWindow() using v as the value_mask parameter to the Xlib function and using the other parameters to fill out the XWindowChanges structure. The value_mask is a bitwise OR of the configure_mask enums.

Please consult Xlib documentation for further details. For example, the following page may be instructive:

http://tronche.com/gui/x/xlib/window/configure.html

Reimplemented in minxlib::root_window.

virtual void minxlib::window::focus ( )

virtual

Set input focus on this window and raise it.

Returns: Nothing.

Reimplemented in minxlib::root_window.

virtual std::vector<int> minxlib::window::geometry ( )

virtual

Retrieve window's size, position, and border width.

Returns: STL vector of ints containing window geometry.

This function uses XGetGeometry() to determine the window's size, position, and border width. It returns an STL vector of integers containing the following five values:

Element 0: x-coordinate of window's top-left corner
Element 1: y-coordinate of window's top-left corner
Element 2: window width
Element 3: window height
Element 4: window's border width

If the call to XGetGeometry() fails, this function will return an empty vector.

Note: On the Python side, the STL vector returned by this function will be converted into a Python list. Also, since we would expect a minxlib::protocol_error to be raised soon after a failed XGetGeometry(), we return and empty list instead of throwing an exception in case the call to XGetGeometry() bombs.

Reimplemented in minxlib::root_window.

void minxlib::window::grab_key ( const std::string & s)

Setup a passive keyboard grab.

Parameters

s	String describing key sequence for activating grab.

Returns: Nothing.

The string s is expected to name a key binding and should be of the form:

    (([CAS]|M[1-5]?)-)*key

The parenthesized part plus the asterisk in the above expression are a regular expression while "key" stands for the string form of a valid X keysym. Here are some examples of key binding specifications:

C-A-T	CTRL + ALT + T
S-F1	SHIFT + F1
A-Tab	ALT + Tab
M-R	META + R
M5-S	Mod5 + S
C-C	CTRL + C

Minx's key bindings specification is designed to be similar to the way key bindings are specified in Emacs.

This function interprets its parameter s in the manner described above and infers the appropriate keycode and corresponding modifier mask for the specified key binding. It then sets up a passive grab for that keycode and modifier mask and also records the name of the key binding (viz., s) in a key map that is indexed using the keycode and modifier mask.

Later, when the X server sends Minx keyboard events, we will use the event's keycode and modifier mask to look-up the key binding in the above-mentioned key map and return that name as part of the event to Minx's Python core.

virtual void minxlib::window::hide ( )

virtual

Hide this window, i.e., unmap it.

Returns: Nothing.

Reimplemented in minxlib::root_window.

virtual bool minxlib::window::is_mapped ( )

virtual

Check if window is currently mapped or not.

Returns: True if window is mapped, false otherwise.

This function uses XGetWindowAttributes() and checks the value of the XWindowAttributes's map_state field to see if the window is mapped or not. It'll return true if map_state equals IsViewable or IsUnviewable and false if either map_state is IsUnmapped or if the call to XGetWindowAttributes() fails.

Note: If XGetWindowAttributes() fails, we would expect a minxlib::protocol_error to be raised soon after. That's why this function returns false instead of throwing an exception.

Reimplemented in minxlib::root_window.

virtual void minxlib::window::kill ( )

virtual

Kill this window.

Returns: Nothing.

This method destroys the X window encapsulated by this object by killing the X client application that created the window. If the window supports the WM_DELETE_WINDOW protocol, this method will use that to kill the window and its client application. Otherwise, it will simply use the XKillClient() function to destroy the window and its client by brute force.

Reimplemented in minxlib::root_window.

virtual void minxlib::window::move_resize	(	int	x,
		int	y,
		int	w,
		int	h
	)

virtual

Move and resize the window.

Parameters

x	Window's x coordinate relative to parent's origin.
y	Window's y coordinate relative to parent's origin.
w	Window's width (not counting its border).
h	Window's height (not counting its border).

Returns: Nothing.

This function sets the window geometry by calling XMoveResizeWindow(). Please consult Xlib documentation for further details.

Reimplemented in minxlib::root_window.

virtual void minxlib::window::nuke ( )

virtual

Kill this window using brute force.

Returns: Nothing.

This method destroys the X window encapsulated by this object without trying a graceful shutdown via WM_DELETE_WINDOW. It is meant to be used on those clients whose windows advertise support for WM_DELETE_WINDOW but don't implement the delete protocol properly and stay alive without good cause despite a user-initiated kill request.

Reimplemented in minxlib::root_window.

minxlib::window::operator Window ( ) const

inline

Convert to an Xlib Window.

Returns: This object cast to an Xlib Window.

This cast operator allows us to pass minxlib::window objects seamlessly to Xlib functions.

bool minxlib::window::operator!= ( const window & w) const

inline

Window inequality operator.

Parameters

w	The minxlib::window against which this should be checked.

Returns: True if this window does not equal w; false if it does.

Two window objects are considered equal if they have the same ID and belong to the same display.

bool minxlib::window::operator!= ( Window w) const

inline

Window inequality operator.

Parameters

w	The Xlib window ID against which this should be checked.

Returns: True if this window's ID does not equal w; false otherwise.

This version of the inequality operator only checks this object's window ID against w.

bool minxlib::window::operator== ( const window & w) const

inline

Window equality operator.

Parameters

w	The minxlib::window against which this should be checked.

Returns: True if this window equals w; false otherwise.

Two window objects are considered equal if they have the same ID and belong to the same display.

bool minxlib::window::operator== ( Window w) const

inline

Window equality operator.

Parameters

w	The Xlib window ID against which this should be checked.

Returns: True if this window's ID equals w; false otherwise.

This version of the equality operator only checks this object's window ID against w.

virtual window minxlib::window::parent ( )

virtual

Get this window's parent window.

Returns: Parent window.

This function uses XQueryTree() to determine the parent window of the X window encapsulated by this object. If the call to XQueryTree() fails, this function will return a window object with the id member set to zero. Eventually, on XQueryTree() failure, X will generate a protocol error; that's why we don't bother throwing an exception.

Reimplemented in minxlib::root_window.

std::map<std::string, std::string> minxlib::window::properties ( )

Retrieve window properties from X server.

Returns: An STL map of strings to strings.

This function gets the WM_NAME, WM_ICON_NAME, and WM_CLASS properties for this window and returns them in an STL map of strings to strings as shown below:

Key	Value
name	WM_NAME
icon_name	WM_ICON_NAME
class	WM_CLASS.res_class
res_name	WM_CLASS.res_name

If we are unable to retrieve a particular property, that key's value will be an empty string. For example, if some window doesn't have a WM_CLASS property, the "class" and "res_name" keys for that window will be empty.

On the Python side of Minx, the above STL map will be returned as a Python dict.

Note: Although rare, the WM_NAME and WM_ICON_NAME X properties may contain more than one string as values. If that is the case, these multiple values in the returned map/dict will be represented as semicolon separated strings. For example, if some window's WM_NAME property has values "foo" and "bar", the value of the "name" key in the returned map will be "foo;bar".

static void minxlib::window::pythonize ( )

static

Export the window class to minxlib Python module.

Returns: Nothing.

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

virtual void minxlib::window::reparent ( const window & p)

virtual

Reparent this window to another.

Parameters

p	New parent window.

Returns: Nothing.

Reimplemented in minxlib::root_window.

virtual int minxlib::window::screen ( )

virtual

Get screen number of this window.

Returns: Window's screen number.

This function returns the zero-based index of the physical screen this window is on. If Xinerama is active and this window overlaps two or more screens, this function will return the screen that has most of the window.

Note: This function calls XGetWindowAttributes(). If the call to XGetWindowAttributes() fails, this function will return -1 and, eventually, the X server will raise a protocol error.

Reimplemented in minxlib::root_window.

void minxlib::window::select_events ( long mask)

Set the X event mask for this window.

Parameters

mask	The X event mask.

Returns: Nothing.

This method allows clients to specify the events they are interested in receiving for this window. The mask parameter should be a bitwise OR of the event_mask enum and is passed as-is to XSelectInput(). See the relevant Xlib documentation for the details about the event mask.

virtual void minxlib::window::set_border_attr	(	unsigned long	c,
		unsigned int	s
	)

virtual

Set window's border color and size.

Parameters

c	Three-byte RGB spec.
s	Border size (in pixels).

Returns: Nothing.

This function calls XSetWindowBorderWidth() and XSetWindowBorder() to specify the window's border color and size to the desired values.

Reimplemented in minxlib::root_window.

virtual void minxlib::window::set_properties ( const std::map< std::string, std::string > & prop)

virtual

Set window properties.

Parameters

prop	An STL map of strings to strings.

Returns: Nothing.

This function sets the window properties specified in its prop parameter. The following properties are supported:

minxlib Name	Xlib Property
name	WM_NAME
icon_name	WM_ICON_NAME
class	WM_CLASS.res_class
res_name	WM_CLASS.res_name

For example, let's say you have a minxlib::window object w and set its properties as shown by the snippet of code below:

std::map<std::string, std::string> prop ;
prop["class"] = "foo" ;
prop["name" ] = "bar" ;
w.set_properties(prop);

That will set the WM_CLASS.res_class and WM_NAME properties of the window w.

Reimplemented in minxlib::root_window.

virtual void minxlib::window::show ( )

virtual

Show the window, i.e., map it.

Returns: Nothing.

Reimplemented in minxlib::root_window.

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation