always adjust the frames size and position together, so there is no more weird resizi...
[mikachu/openbox.git] / 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.