Metadata-Version: 1.2
Name: xpybutil
Version: 0.0.2
Summary: An incomplete xcb-util port plus some extras
Home-page: http://github.com/fennerm/xpybutil
Maintainer: Fenner Macrae
Maintainer-email: fmacrae.dev@gmail.com
License: WTFPL
Description: 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
        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
        fork of Openbox called Openbox Multihead.
        
        
        Documentation
        =============
        The API docs can be found here: http://pdoc.burntsushi.net/xpybutil
        
        
        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
        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
        xpybutil.)
        
        
        Usable modules
        ==============
        cursor.py    - Provides a listing of all built-in X cursors, and provides a
                       function 'create_font_cursor' to create one. This object can
                       then be directly used in a call to CreateWindow or
                       ChangeWindowAttributes.
        
        ewmh.py      - A module that implements the entire EWMH spec.
        
        event.py     - A module that can send client events to windows. It also allows
                       registering callback functions to particular events. It can also
                       run the main event loop.
        
        icccm.py     - A module that implements most of the ICCCM spec.
        
        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
                       callbacks. This will automatically hook into the event callbacks
                       in event.py.
        
        keysymdef.py - The sole purpose of this module is to provide a mapping from
                       X keysyms to english string representations (for easier binding
                       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
                       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
                       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
                       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
                       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
                       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.)
        
                       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
                       import xpybutil.event as event
                       import xpybutil.ewmh as ewmh
                       import xpybutil.util as util
                       import xpybutil.window as window
        
                       def func(e):
                         if util.get_atom_name(e.atom) == '_NET_ACTIVE_WINDOW':
                           # Do something whenever the active window changes
                           active_window_id = ewmh.get_active_window().reply()
        
                       window.listen(xpybutil.root, 'PropertyChange')
                       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
                       particular event 'PropertyNotify'.
        
        xinerama.py  - A couple of functions that support retrieving information about
                       all active physical heads. This is done through the Xinerama
                       extension, which implicitly supports RandR and TwinView.
        
                       The 'get_physical_mapping' function will produce a list of
                       monitor indices in a physical ordering (left to right, top to
                       bottom). These indices can then be used in the list returned by
                       'get_monitors'.
        
        
        Unusable modules
        ================
        font.py is pretty inadequate. Mostly because if you find
        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
        modules. Here's a quick example (assuming xpybutil is installed):
        
          import xpybutil.ewmh as ewmh
        
          desktop_names = ewmh.get_desktop_names().reply()
          current_desktop = ewmh.get_current_desktop().reply()
        
          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
        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
        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
        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
        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
        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
        retrieval), then use the '_checked' variant.
        
        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
        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, not 'set_'. For example, if you want to change the current
        desktop...
        
          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
        spec :-)
        
Keywords: xorg X xcb xpyb xcffib
Platform: UNKNOWN
