Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XIChangeHierarchy.txt
1 XICHANGEHIERARCHY(libmansuffix)
2 ===============================
3
4 NAME
5 ----
6
7    XIChangeHierarchy - change the device hierarchy.
8
9 SYNOPSIS
10 --------
11
12    #include <X11/extensions/XInput2.h>
13
14    Status XIChangeHierarchy( Display *display,
15                              XIAnyHierarchyChangeInfo *changes,
16                              int num_changes);
17
18    display
19           Specifies the connection to the X server.
20
21    num_changes
22           Specifies the number of elements in changes.
23
24    changes
25           Specifies the changes to be made.
26
27 DESCRIPTION
28 -----------
29
30    XIChangeHierarchy modifies the device hierarchy by creating or
31    removing master devices or changing the attachment of slave
32    devices. If num_changes is non-zero, changes is an array of
33    XIAnyHierarchyChangeInfo structures. If num_changes is equal or less than
34    zero, XIChangeHierarchy does nothing.
35
36    XIChangeHierarchy processes changes in order, effective
37    immediately. If an error occurs, processing is aborted and the
38    error is reported to the client. Changes already made remain
39    effective.
40
41    The list of changes is any combination of
42    XIAnyHierarchyChangeInfo. The type of a hierarchy change can be
43    XIAddMaster, XIRemoveMaster, XIAttachSlave or XIDetachSlave.
44
45                 typedef union {
46                     int type;
47                     XIAddMasterInfo add;
48                     XIRemoveMasterInfo remove;
49                     XIAttachSlave attach;
50                     XIDetachSlave detach;
51                 } XIAnyHierarchyChangeInfo;
52
53                 typedef struct {
54                     int type; /* XIAddMaster */
55                     char* name;
56                     Bool send_core;
57                     Bool enable;
58                 } XIAddMasterInfo;
59
60                 typedef struct {
61                     int type; /* XIRemoveMaster */
62                     int deviceid;
63                     int return_mode;
64                     int return_pointer;
65                     int return_keyboard;
66                 } XIRemoveMasterInfo;
67
68                 typedef struct {
69                     int type; /* XIAttachSlave */
70                     int deviceid;
71                     int new_master;
72                 } XIAttachSlaveInfo;
73
74                 typedef struct {
75                     int type; /* XIDetachSlave */
76                     int deviceid;
77                 } XIDetachSlaveInfo;
78
79    XIAddMasterInfo creates a new master pointer and a new
80    master keyboard labelled "name pointer" and "name keyboard"
81    respectively. If sendCore is True, the devices will send core
82    events. If enable is True, the device is enabled immediately.
83
84    XIAddMasterInfo can generate a BadValue error.
85
86    XIRemoveMasterInfo removes device and its paired master device.
87    If returnMode is XIAttachToMaster, all pointers attached to
88    device or its paired master device are attached to
89    returnPointer. Likewise, all keyboards are attached to
90    returnKeyboard. If returnMode is XIFloating, all attached
91    devices are set to floating.
92
93    XIRemoveMasterInfo can generate a BadValue and a BadDevice
94    error.
95
96    XIAttachSlaveInfo attaches device to newMaster. If the device
97    is currently attached to a master device, it is detached from
98    the master device and attached to the new master device.
99
100    XIAttachSlaveInfo can generate a BadDevice error.
101
102    XIDettachSlaveInfo deattaches device from the current master
103    device and sets it floating. If the device is already floating,
104    no changes are made.
105
106    XIDetachSlaveInfo can generate a BadDevice error.
107
108    XIChangeHierarchy generates an XIHierarchyEvent if any
109    modifications were successful.
110
111 DIAGNOSTICS
112 -----------
113
114    BadDevice
115           An invalid device was specified. The device does not
116           exist or is not a appropriate for the type of change.
117
118    BadValue
119           Some numeric value falls out of the allowed range.
120