Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XIChangeHierarchy.man
1 '\" t
2 .\"     Title: xichangehierarchy
3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\"      Date: 09/23/2011
6 .\"    Manual: [FIXME: manual]
7 .\"    Source: [FIXME: source]
8 .\"  Language: English
9 .\"
10 .TH "XICHANGEHIERARCHY" "libmansuffix" "09/23/2011" "[FIXME: source]" "[FIXME: manual]"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 XIChangeHierarchy \- change the device hierarchy\&.
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 #include <X11/extensions/XInput2\&.h>
36 .fi
37 .sp
38 .nf
39 Status XIChangeHierarchy( Display *display,
40                           XIAnyHierarchyChangeInfo *changes,
41                           int num_changes);
42 .fi
43 .sp
44 .nf
45 display
46        Specifies the connection to the X server\&.
47 .fi
48 .sp
49 .nf
50 num_changes
51        Specifies the number of elements in changes\&.
52 .fi
53 .sp
54 .nf
55 changes
56        Specifies the changes to be made\&.
57 .fi
58 .SH "DESCRIPTION"
59 .sp
60 .if n \{\
61 .RS 4
62 .\}
63 .nf
64 XIChangeHierarchy modifies the device hierarchy by creating or
65 removing master devices or changing the attachment of slave
66 devices\&. If num_changes is non\-zero, changes is an array of
67 XIAnyHierarchyChangeInfo structures\&. If num_changes is equal or less than
68 zero, XIChangeHierarchy does nothing\&.
69 .fi
70 .if n \{\
71 .RE
72 .\}
73 .sp
74 .if n \{\
75 .RS 4
76 .\}
77 .nf
78 XIChangeHierarchy processes changes in order, effective
79 immediately\&. If an error occurs, processing is aborted and the
80 error is reported to the client\&. Changes already made remain
81 effective\&.
82 .fi
83 .if n \{\
84 .RE
85 .\}
86 .sp
87 .if n \{\
88 .RS 4
89 .\}
90 .nf
91 The list of changes is any combination of
92 XIAnyHierarchyChangeInfo\&. The type of a hierarchy change can be
93 XIAddMaster, XIRemoveMaster, XIAttachSlave or XIDetachSlave\&.
94 .fi
95 .if n \{\
96 .RE
97 .\}
98 .sp
99 .if n \{\
100 .RS 4
101 .\}
102 .nf
103 typedef union {
104     int type;
105     XIAddMasterInfo add;
106     XIRemoveMasterInfo remove;
107     XIAttachSlave attach;
108     XIDetachSlave detach;
109 } XIAnyHierarchyChangeInfo;
110 .fi
111 .if n \{\
112 .RE
113 .\}
114 .sp
115 .if n \{\
116 .RS 4
117 .\}
118 .nf
119 typedef struct {
120     int type; /* XIAddMaster */
121     char* name;
122     Bool send_core;
123     Bool enable;
124 } XIAddMasterInfo;
125 .fi
126 .if n \{\
127 .RE
128 .\}
129 .sp
130 .if n \{\
131 .RS 4
132 .\}
133 .nf
134 typedef struct {
135     int type; /* XIRemoveMaster */
136     int deviceid;
137     int return_mode;
138     int return_pointer;
139     int return_keyboard;
140 } XIRemoveMasterInfo;
141 .fi
142 .if n \{\
143 .RE
144 .\}
145 .sp
146 .if n \{\
147 .RS 4
148 .\}
149 .nf
150 typedef struct {
151     int type; /* XIAttachSlave */
152     int deviceid;
153     int new_master;
154 } XIAttachSlaveInfo;
155 .fi
156 .if n \{\
157 .RE
158 .\}
159 .sp
160 .if n \{\
161 .RS 4
162 .\}
163 .nf
164 typedef struct {
165     int type; /* XIDetachSlave */
166     int deviceid;
167 } XIDetachSlaveInfo;
168 .fi
169 .if n \{\
170 .RE
171 .\}
172 .sp
173 .if n \{\
174 .RS 4
175 .\}
176 .nf
177 XIAddMasterInfo creates a new master pointer and a new
178 master keyboard labelled "name pointer" and "name keyboard"
179 respectively\&. If sendCore is True, the devices will send core
180 events\&. If enable is True, the device is enabled immediately\&.
181 .fi
182 .if n \{\
183 .RE
184 .\}
185 .sp
186 .if n \{\
187 .RS 4
188 .\}
189 .nf
190 XIAddMasterInfo can generate a BadValue error\&.
191 .fi
192 .if n \{\
193 .RE
194 .\}
195 .sp
196 .if n \{\
197 .RS 4
198 .\}
199 .nf
200 XIRemoveMasterInfo removes device and its paired master device\&.
201 If returnMode is XIAttachToMaster, all pointers attached to
202 device or its paired master device are attached to
203 returnPointer\&. Likewise, all keyboards are attached to
204 returnKeyboard\&. If returnMode is XIFloating, all attached
205 devices are set to floating\&.
206 .fi
207 .if n \{\
208 .RE
209 .\}
210 .sp
211 .if n \{\
212 .RS 4
213 .\}
214 .nf
215 XIRemoveMasterInfo can generate a BadValue and a BadDevice
216 error\&.
217 .fi
218 .if n \{\
219 .RE
220 .\}
221 .sp
222 .if n \{\
223 .RS 4
224 .\}
225 .nf
226 XIAttachSlaveInfo attaches device to newMaster\&. If the device
227 is currently attached to a master device, it is detached from
228 the master device and attached to the new master device\&.
229 .fi
230 .if n \{\
231 .RE
232 .\}
233 .sp
234 .if n \{\
235 .RS 4
236 .\}
237 .nf
238 XIAttachSlaveInfo can generate a BadDevice error\&.
239 .fi
240 .if n \{\
241 .RE
242 .\}
243 .sp
244 .if n \{\
245 .RS 4
246 .\}
247 .nf
248 XIDettachSlaveInfo deattaches device from the current master
249 device and sets it floating\&. If the device is already floating,
250 no changes are made\&.
251 .fi
252 .if n \{\
253 .RE
254 .\}
255 .sp
256 .if n \{\
257 .RS 4
258 .\}
259 .nf
260 XIDetachSlaveInfo can generate a BadDevice error\&.
261 .fi
262 .if n \{\
263 .RE
264 .\}
265 .sp
266 .if n \{\
267 .RS 4
268 .\}
269 .nf
270 XIChangeHierarchy generates an XIHierarchyEvent if any
271 modifications were successful\&.
272 .fi
273 .if n \{\
274 .RE
275 .\}
276 .SH "DIAGNOSTICS"
277 .sp
278 .if n \{\
279 .RS 4
280 .\}
281 .nf
282 BadDevice
283        An invalid device was specified\&. The device does not
284        exist or is not a appropriate for the type of change\&.
285 .fi
286 .if n \{\
287 .RE
288 .\}
289 .sp
290 .if n \{\
291 .RS 4
292 .\}
293 .nf
294 BadValue
295        Some numeric value falls out of the allowed range\&.
296 .fi
297 .if n \{\
298 .RE
299 .\}