Dogcows Code - chaz/openbox/blob - doc/python/pointer.txt

   1 input.Pointer
   2
   3 ----
   4
   5 This document describes the 'Pointer' class, exposed by Openbox's 'input'
   6 module to its python scripts.
   7
   8 All pointer events which will be generated because of the Pointer class can
   9 be caught from the hooks.pointer hook.
  10
  11 ----
  12
  13 Terminology
  14
  15 ----
  16
  17 Context -- A context is a string describing a part of a window or screen in
  18            which an event can occur. Contexts are used for grabbing and
  19            tracking pointer events. A list of possible contexts are exposed by
  20            the engine through the contexts() method. The standard list of
  21            contexts are:
  22            * "none" - no context associated.
  23            * "root" - the root window.
  24            * "frame" - the client's entire frame. Note: when a button is
  25                        grabbed in the "frame" context, it will not get passed
  26                        through to the client.
  27            * "client" - client's window.
  28            * "titlebar" - a client's titlebar.
  29            * "handle" - a client's handle.
  30            * "tlcorner" - the top-left corner of a client's decorations.
  31            * "trcorner" - the top-right corner of a client's decorations.
  32            * "blcorner" - the bottom-left corner of a client's decorations.
  33            * "brcorner" - the bottom-right corner of a client's decorations.
  34            * "maximize" - the maximize button in the titlebar.
  35            * "close" - the close button in the titlebar.
  36            * "iconify" - the iconify button in the titlebar.
  37            * "alldesktops" - the all-desktops button in the titlebar.
  38            * "icon" - the window icon in the titlebar.
  39
  40            An engine may add to this list as it sees fit (most engines will
  41            include "close", "maximize", etc. contexts for titlebar buttons).
  42
  43 ----
  44
  45 Methods
  46
  47 ----
  48
  49 bind(button, context, action, func)
  50
  51 Binds a pointer button for a context and action to a function. See the
  52 Terminology section for a decription and list of common contexts. The button is
  53 a string which defines a modifier and button combination with the format
  54 [Modifier-]...[Button]. Modifiers can be 'mod1', 'mod2', 'mod3', 'mod4',
  55 'mod5', 'control', and 'shift'. The keys on your keyboard that are bound to
  56 each of these modifiers can be found by running 'xmodmap'. The button is the
  57 number of the button. Button numbers can be found by running 'xev', pressing
  58 the button with the pointer over its window, and watching its output. Here
  59 are some examples of valid buttons: 'control-1', '2', 'mod1-shift-5'. The
  60 action is one of the Action_* constants. The func must have a definition
  61 similar to 'def func(ptrdata, client)'. The arguments passed to the function
  62 are a PointerData object and a Client object (or None). A button and context
  63 may be bound to more than one function.
  64
  65         button: A string defining the modifiers and button to for which events
  66                 should be generated.
  67
  68         context: The context in which the button events should be generated.
  69
  70         action: One of the Action_* constants specifying the action to bind
  71                 the function to.
  72
  73         func: A function to bind to the button/context.
  74
  75 ----
  76
  77 clearBinds()
  78
  79 Removes all bindings that were previously made by bind().
  80
  81 ----
  82
  83 grab(func)
  84
  85 Grabs the pointer device, causing all possible pointer events to be sent to
  86 the given function. CAUTION: Be sure when you grab() that you also have an
  87 ungrab() that will execute, or you will not be able to use the pointer device
  88 until you restart Openbox. The func must have a definition similar to
  89 'def func(data)'. The argument passed to the function is a PointerData object.
  90 The pointer cannot be grabbed if it is already grabbed. When a grab is active,
  91 no pointer bindings will fire, everything is sent only to the specified func.
  92
  93         func: A function to receive all the grabbed pointer events.
  94
  95 ----
  96
  97 ungrab()
  98
  99 Ungrabs the pointer. The pointer cannot be ungrabbed if it is not grabbed.
 100
 101 ----
 102
 103 Constants
 104
 105 ----
 106
 107 Action_Press            a pointer button press
 108 Action_Release          a pointer button release
 109 Action_Click            a pointer button click (press-release)
 110 Action_DoubleClick      a pointer button double-click
 111 Action_Motion           a pointer drag
 112
 113 ----
 114
 115 Configuration options (through the config module)
 116
 117 ----
 118
 119 double_click_rate
 120
 121 An integer containing the number of milliseconds in which 2 clicks must be
 122 received to cause a double-click event.
 123
 124 ----
 125
 126 drag_threshold
 127
 128 An integer containing the number of pixels a drag must go before motion events
 129 start getting generated. Once a drag has begun, the button release will not
 130 count as a click event.