Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XGetDeviceProperty.man
1 '\" t
2 .\"     Title: xgetdeviceproperty
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 "XGETDEVICEPROPERTY" "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 XGetDeviceProperty, XChangeDeviceProperty, XDeleteDeviceProperty \- Get, change or delete a device\*(Aqs property\&.
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 #include <X11/extensions/XInput\&.h>
36 .fi
37 .sp
38 .nf
39 int XGetDeviceProperty( Display *display,
40                         XDevice *device,
41                         Atom property,
42                         long offset,
43                         long length,
44                         Bool delete,
45                         Atom req_type,
46                         Atom *actual_type_return,
47                         int *actual_format_return,
48                         unsigned long *nitems_return,
49                         unsigned long *bytes_after_return,
50                         unsigned char **prop_return)
51 .fi
52 .sp
53 .nf
54 void XChangeDeviceProperty( Display *display,
55                             XDevice *device,
56                             Atom property,
57                             Atom type,
58                             int format,
59                             int mode,
60                             const char *data,
61                             int nelements)
62 .fi
63 .sp
64 .nf
65 void XDeleteDeviceProperty( Display *display,
66                             XDevice *device,
67                             Atom property)
68 .fi
69 .sp
70 .nf
71 actual_type_return
72        Returns an atom identifier that defines the actual type
73        of the property\&.
74 .fi
75 .sp
76 .nf
77 actual_format_return
78        Returns the actual format of the property\&.
79 .fi
80 .sp
81 .nf
82 bytes_after_return
83        Returns the number of bytes remaining to be read in the
84        property if a partial read was performed\&.
85 .fi
86 .sp
87 .nf
88 data
89        Specifies the property data\&.
90 .fi
91 .sp
92 .nf
93 delete
94        Specifies a Boolean value that determines whether the
95        property is deleted\&.
96 .fi
97 .sp
98 .nf
99 display
100        Specifies the connection to the X server\&.
101 .fi
102 .sp
103 .nf
104 device
105        The device to grab\&.
106 .fi
107 .sp
108 .nf
109 format
110        Specifies whether the data should be viewed as a list of
111        8\-bit, 16\-bit, or 32\-bit quantities\&. Possible values are
112        8, 16, and 32\&. This information allows the X server to
113        correctly perform byte\-swap operations as necessary\&. If
114        the format is 16\-bit or 32\-bit, you must explicitly cast
115        the data pointer to an (unsigned char*) in the call to
116        XChangeDeviceProperty\&.
117 .fi
118 .sp
119 .nf
120 length
121        Specifies the length in 32\-bit multiplies of the data to
122        be retrieved\&.
123 .fi
124 .sp
125 .nf
126 mode
127        Specifies the mode of operation\&. You can pass
128        PropModeReplace, PropModePrepend, or PropModeAppend\&.
129 .fi
130 .sp
131 .nf
132 nelements
133        Specifies the number of elements in data\&.
134 .fi
135 .sp
136 .nf
137 nitems_return
138        Returns the actual number of 8\-bit, 16\-bit, or 32\-bit
139        items stored in the prop_return array\&.
140 .fi
141 .sp
142 .nf
143 num_values
144        Specifies the number of elements in the values list\&.
145 .fi
146 .sp
147 .nf
148 offset
149        Specifies the offset in the specified property (in
150        32\-bit quantities) where the data is to be retrieved\&.
151 .fi
152 .sp
153 .nf
154 property
155        Specifies the property to modify or query\&.
156 .fi
157 .sp
158 .nf
159 prop_return
160        Returns the data in the specified format\&. If the
161        returned format is 8, the returned data is represented
162        as a char array\&. If the returned format is 16, the
163        returned data is represented as an array of short int
164        type and should be cast to that type to obtain the
165        elements\&. If the returned format is 32, the property
166        data will be stored as an array of longs (which in a
167        64\-bit application will be 64\-bit values that are padded
168        in the upper 4 bytes)\&.
169 .fi
170 .sp
171 .nf
172 req_type
173        Specifies the atom identifier associated with the
174        property type or AnyPropertyType\&.
175 .fi
176 .SH "DESCRIPTION"
177 .sp
178 The XGetDeviceProperty function returns the actual type of the property; the actual format of the property; the number of 8\-bit, 16\-bit, or 32\-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned\&. For a detailed description of this function, see the man page to XGetWindowProperty\&.
179 .sp
180 The XChangeDeviceProperty function alters the property for the specified device and causes the server to generate a XPropertyNotifyEvent event on that device\&. For a detailed description of this function, see the man page to XChangeProperty\&.
181 .sp
182 The XDeleteDeviceProperty function deletes the specified device property\&. Note that a client cannot delete a property created by a driver or the server\&. Attempting to do so will result in a BadAtom error\&.
183 .sp
184 XGetDeviceProperty can generate a BadAtom, BadDevice error\&.
185 .sp
186 XChangeDeviceProperty can generate a BadDevice, a BadMatch, a BadAtom, and a BadValue error\&.
187 .sp
188 XDeleteDeviceProperty can generate a BadDevice, and a BadAtom error\&.
189 .SH "DIAGNOSIS"
190 .sp
191 .if n \{\
192 .RS 4
193 .\}
194 .nf
195 BadAtom
196        A value does not describe a valid named identifier or
197        the client attempted to remove a driver\-allocated
198        property\&.
199 .fi
200 .if n \{\
201 .RE
202 .\}
203 .sp
204 .if n \{\
205 .RS 4
206 .\}
207 .nf
208 BadDevice
209        An invalid device was specified\&. The device does not
210        exist\&.
211 .fi
212 .if n \{\
213 .RE
214 .\}
215 .SH "SEE ALSO"
216 .sp
217 .if n \{\
218 .RS 4
219 .\}
220 .nf
221 XListDeviceProperties(libmansuffix)
222 .fi
223 .if n \{\
224 .RE
225 .\}