Permalink
Browse files

Updated README to match the ewmh.py docstring change from 96adc52, co…

…rrected spelling in both, and clarified both.
  • Loading branch information...
1 parent 3e1b10b commit 8ac687452f3a62196d6dc960a9c25cf669a56ba0 @whitelynx whitelynx committed Jan 15, 2013
Showing with 58 additions and 58 deletions.
  1. +56 −57 README
  2. +2 −1 xpybutil/ewmh.py
View
113 README
@@ -1,14 +1,14 @@
Introduction
============
-xpybutil is an abstraction over the X Python Binding (xpyb - the Python version
-of XCB). It exists because xpyb is a very low level library that communicates
+xpybutil is an abstraction over the X Python Binding (xpyb - the Python version
+of XCB). It exists because xpyb is a very low level library that communicates
with X.
-The most mature portions of xpybutil are the ICCCM and EWMH modules. Each
-implement their respective specifications of the same name. The EWMH module
-also implements the '_NET_WM_WINDOW_OPACITY' and '_NET_VISIBLE_DESKTOPS'
-non-standard features. The former is widely used by compositing managers and
-other utilities (i.e., xcompmgr and transset-df) while the latter is used by my
+The most mature portions of xpybutil are the ICCCM and EWMH modules. Each
+implement their respective specifications of the same name. The EWMH module
+also implements the '_NET_WM_WINDOW_OPACITY' and '_NET_VISIBLE_DESKTOPS'
+non-standard features. The former is widely used by compositing managers and
+other utilities (i.e., xcompmgr and transset-df) while the latter is used by my
fork of Openbox called Openbox Multihead.
@@ -19,15 +19,15 @@ The API docs can be found here: http://burntsushi.net/X11/xpybutil/docs/
Examples
========
-There are a few examples included in the 'examples' directory of the source of
-xpybutil. You could also look at my 'window-marker' or 'pytyle3' utilities. The
-former is a small script but the latter is on the order of ~1000 lines and
-encompasses a wide variety of use cases of xpybutil. (And still yet, other use
+There are a few examples included in the 'examples' directory of the source of
+xpybutil. You could also look at my 'window-marker' or 'pytyle3' utilities. The
+former is a small script but the latter is on the order of ~1000 lines and
+encompasses a wide variety of use cases of xpybutil. (And still yet, other use
cases are probably more appropriate only for window manager development.)
-Another program that uses xpybutil is 'pager-multihead'. I would advise not
-looking to it for inspiration, as it mixes xpybutil and GTK. (Namely, it uses
-GTK's event dispatcher, but interacts with the window manager mostly using
+Another program that uses xpybutil is 'pager-multihead'. I would advise not
+looking to it for inspiration, as it mixes xpybutil and GTK. (Namely, it uses
+GTK's event dispatcher, but interacts with the window manager mostly using
xpybutil.)
@@ -46,7 +46,7 @@ event.py - A module that can send client events to windows. It also allows
icccm.py - A module that implements most of the ICCCM spec.
-image.py - An incomplete and haphazard collection of functions that can
+image.py - An incomplete and haphazard collection of functions that can
bridge a gap between PIL and drawing images with X.
keybind.py - A set of functions devoted to binding key presses and registering
@@ -58,35 +58,35 @@ keysymdef.py - The sole purpose of this module is to provide a mapping from
by the user). This should probably never be used directly. It is
used by the keysym module.
-motif.py - Implements a subset of the Motif spec. This module exists
+motif.py - Implements a subset of the Motif spec. This module exists
because some window managers still use this as the only way of
toggling window decorations via events.
mousebind.py - Similar to keybind.py, but for mice.
-rect.py - A few utility functions that do math associated with X style
+rect.py - A few utility functions that do math associated with X style
rectangles. (i.e., a 4-tuple of (top_left_x, top_left_y, width,
height).) It can also calculate monitor rectangles after
accounting for struts.
-render.py - A nearly exact port of the module by the same name from
+render.py - A nearly exact port of the module by the same name from
xcb-util. I used it once to help with a compositing manager that
I wrote with xpyb.
-util.py - A vast assortment of utility functions. The ones of interest to
+util.py - A vast assortment of utility functions. The ones of interest to
you are probably 'get_atom' and 'get_atom_name'. The rest are
heavily used throughout the rest of xpybutil.
-window.py - A few utility functions related to client windows. In
+window.py - A few utility functions related to client windows. In
particular, getting an accurate geometry of a client window
including the decorations (this can vary with the window
manager). Also, a functon to move and/or resize a window
accurately by the top-left corner. (Also can change based on
- the currently running window manager.)
+ the currently running window manager.)
- This module also contains a function 'listen' that must be used
- in order to receive certain events from a window. For example,
- if you wanted to run 'func' whenever a property on the root
+ This module also contains a function 'listen' that must be used
+ in order to receive certain events from a window. For example,
+ if you wanted to run 'func' whenever a property on the root
window changed, you could do something like:
import xpybutil
@@ -101,10 +101,10 @@ window.py - A few utility functions related to client windows. In
active_window_id = ewmh.get_active_window().reply()
window.listen(xpybutil.root, 'PropertyChange')
- event.connect('PropertyNotify', xpybutil.root, func)
+ event.connect('PropertyNotify', xpybutil.root, func)
The idea here is to tell X that you want events that fall under
- the 'PropertyChange' category. Then you bind 'func' to the
+ the 'PropertyChange' category. Then you bind 'func' to the
particular event 'PropertyNotify'.
xinerama.py - A couple of functions that support retrieving information about
@@ -120,14 +120,14 @@ xinerama.py - A couple of functions that support retrieving information about
Unusable modules
================
font.py is pretty inadequate. Mostly because if you find
-yourself wanting to use font.py, you're probably doing something wrong.
+yourself wanting to use font.py, you're probably doing something wrong.
(i.e., use pycairo or PIL.)
EWMH and ICCCM
==============
-xpybutil's primary purpose was to make accessing ICCCM and EWMH related
-information extremely easy. This can be done by using the ewmh or icccm
+xpybutil's primary purpose was to make accessing ICCCM and EWMH related
+information extremely easy. This can be done by using the ewmh or icccm
modules. Here's a quick example (assuming xpybutil is installed):
import xpybutil.ewmh as ewmh
@@ -137,56 +137,55 @@ modules. Here's a quick example (assuming xpybutil is installed):
print names.get(current_desktop, current_desktop)
-This imports the ewmh module (and by extension, connects to the X server) and
-fetches a list of the current desktop names and the current desktop index
-(starting from 0). Since not every desktop must be named, the desktop index is
+This imports the ewmh module (and by extension, connects to the X server) and
+fetches a list of the current desktop names and the current desktop index
+(starting from 0). Since not every desktop must be named, the desktop index is
printed if it has no name.
-Note that the functions in the ewmh and icccm module return *cookies*. In order
-to pull a response from the X server, call the 'reply()' method on a cookie
-object. To force a response sent to the X server, call the 'check()' method on
+Note that the functions in the ewmh and icccm module return *cookies*. In order
+to pull a response from the X server, call the 'reply()' method on a cookie
+object. To force a response sent to the X server, call the 'check()' method on
the corresponding cookie.
-Much of the EWMH and ICCCM modules encapsulate packing data from convenient
-Python data types into C structs (using the 'struct' Python module). For
-example, if one wants to fetch the partial struts set by some window with
+Much of the EWMH and ICCCM modules encapsulate packing data from convenient
+Python data types into C structs (using the 'struct' Python module). For
+example, if one wants to fetch the partial struts set by some window with
identifier ID, you could do:
import xpybutil.ewmh as ewmh
print ewmh.get_wm_strut_partial(ID).reply()
-Which outputs a dictionary with 12 entries, where each corresponds to a value
+Which outputs a dictionary with 12 entries, where each corresponds to a value
in the partial strut. (i.e., 'left', 'top_end_x', 'right_start_y', etc...).
-In general, particularly with the EWMH module, the ewmh module is very nearly
-representative of the spec itself. Functions that get property values start
-with 'get_', functions that set property values start with 'set_', and
-functions that send an event to a client (which typically requests the window
+In general, particularly with the EWMH module, the ewmh module is very nearly
+representative of the spec itself. Functions that get property values start
+with 'get_', functions that set property values start with 'set_', and
+functions that send an event to a client (which typically requests the window
manager to DO something) start with 'request_'.
-If a request has no reply (typically the 'set_' functions), then the
-default is to call it 'unchecked'. If you want to check the result (and force
+If a request has no reply (typically the 'set_' functions), then the
+default is to call it 'unchecked'. If you want to check the result (and force
retrieval), then use the '_checked' variant.
-The reverse goes for the 'get_' functions. By default, they are checked, but
+The reverse goes for the 'get_' functions. By default, they are checked, but
you can use the '_unchecked' variant too.
-Basically, you should probably almost always use the 'checked' variant of
-everything. The cases where you don't are when you want to send a whole bunch
-of requests to the X server at once. You could use the unchecked invariant, and
-after you've initialized all the cookies, calling 'flush' will force
+Basically, you should probably almost always use the 'checked' variant of
+everything. The cases where you don't are when you want to send a whole bunch
+of requests to the X server at once. You could use the unchecked invariant, and
+after you've initialized all the cookies, calling 'flush' will force
communication with the X server.
-Finally, unless you're writing a window manager or creating a client window
-from scratch, you'll almost always want to use the 'get_' and 'request_'
-functions. For exampe, if you want to change the current desktop...
+Finally, unless you're writing a window manager or creating a client window
+from scratch, you'll almost always want to use the 'get_' and 'request_'
+functions, not 'set_'. For example, if you want to change the current
+desktop...
- DON'T DO: ewmh.get_current_desktop_checked(2).check()
+ DON'T DO: ewmh.set_current_desktop_checked(2).check()
DO: ewmh.request_current_desktop_checked(2).check()
-The former will probably not work, but the latter will. Just follow the EWMH
+The former will probably not work, but the latter will. Just follow the EWMH
spec :-)
-
-
View
@@ -60,7 +60,8 @@
Finally, unless you're writing a window manager or creating a client window
from scratch, you'll almost always want to use the ``get_`` and ``request_``
-functions. For exampe, if you want to change the current desktop...
+functions, not ``set_``. For example, if you want to change the current
+desktop...
DON'T DO: ``ewmh.set_current_desktop_checked(2).check()``

0 comments on commit 8ac6874

Please sign in to comment.