man/XIChangeProperty.txt

   1 XICHANGEPROPERTY(libmansuffix)
   2 ==============================
   3
   4 NAME
   5 ----
   6
   7    XIChangeProperty, XIGetProperty, XIDeleteProperty - change, retrieve
   8    or delete a device's property.
   9
  10 SYNOPSIS
  11 --------
  12
  13     #include <X11/extensions/XInput2.h>
  14
  15     void XIChangeProperty( Display* dpy,
  16                            int deviceid,
  17                            Atom property,
  18                            Atom type,
  19                            int format,
  20                            int mode,
  21                            unsigned char *data,
  22                            int num_items)
  23
  24    void XIDeleteProperty( Display *dpy,
  25                           int deviceid,
  26                           Atom property)
  27
  28    Status XIGetProperty( Display *dpy,
  29                          int deviceid,
  30                          Atom property,
  31                          long offset,
  32                          long length,
  33                          Bool delete_property,
  34                          Atom type,
  35                          Atom *type_return,
  36                          int *format_return,
  37                          unsigned long *num_items_return,
  38                          unsigned long *bytes_after_return,
  39                          unsigned char **data)
  40
  41    bytes_after_return
  42           Returns the number of bytes remaining to be read in the prop-
  43           erty if a partial read was performed.
  44
  45    data
  46           Specifies the property data.
  47
  48    display
  49           Specifies the connection to the X server.
  50
  51    delete_property
  52           Specifies a Boolean value that determines whether the property
  53           is to be deleted.
  54
  55    deviceid
  56           The device to list the properties for.
  57
  58    format
  59           Specifies whether the data should be viewed as a list of
  60           8-bit, 16-bit, or 32-bit quantities.  Possible values are 8,
  61           16, and 32.  This information allows the X server to correctly
  62           perform byte-swap operations as necessary. If the
  63           format is 16-bit or 32-bit, you must explicitly cast your
  64           data pointer to an (unsigned char *) in the call to
  65           XIChangeProperty.
  66
  67    format_return
  68           Returns the actual format of the property.
  69
  70    length
  71           Specifies the length in 32-bit multiples of the data to be
  72           retrieved.
  73
  74    offset
  75           Specifies the offset in the specified property (in 32-bit
  76           quantities) where the data is to be retrieved.
  77
  78    mode
  79           One of PropModeAppend, PropModePrepend or PropModeReplace.
  80
  81    num_items
  82           Number of items in data in the format specified.
  83
  84    nitems_return
  85           Returns the actual number of 8-bit, 16-bit, or 32-bit items
  86           stored in data.
  87
  88    property
  89           Specifies the property name.
  90
  91    type
  92           Specifies the type of the property.  The X server does not
  93           interpret the type but simply passes it back to an application
  94           that later calls XIGetProperty.
  95
  96    type_return
  97           Returns the atom identifier that defines the actual type of
  98           the property.
  99
 100 DESCRIPTION
 101 -----------
 102
 103 The XIGetProperty function returns the actual type of the property;
 104 the actual format of the property; the number of 8-bit, 16-bit,
 105 or 32-bit items transferred; the number of bytes remaining to be read
 106 in the property; and a pointer to the data actually returned.
 107 XIGetProperty sets the return arguments as follows:
 108
 109    - If the specified property does not exist for the specified device,
 110    XIGetProperty returns None to actual_type_return and the
 111    value zero to actual_format_return and bytes_after_return.  The
 112    nitems_return argument is empty.  In this case, the delete argument
 113    is ignored.
 114
 115    - If the specified property exists but its type does not match the
 116    specified type, XIGetProperty returns the actual property
 117    type to actual_type_return, the actual property format (never
 118    zero) to actual_format_return, and the property length in bytes
 119    (even if the actual_format_return is 16 or 32) to
 120    bytes_after_return.  It also ignores the delete argument.  The
 121    nitems_return argument is empty.
 122
 123    - If the specified property exists and either you assign
 124    AnyPropertyType to the req_type argument or the specified type
 125    matches the actual property type, XIGetProperty returns the
 126    actual property type to actual_type_return and the actual property
 127    format (never zero) to actual_format_return.  It also returns a value
 128    to bytes_after_return and nitems_return, by defining the following
 129    values:
 130
 131    N = length of the stored property in bytes
 132    I = 4 * offset
 133    T = N - I
 134    L = MINIMUM(T, 4 * length)
 135    A = N - (I + L)
 136
 137 The returned value starts at byte index I in the property
 138 (indexing from zero), and its length in bytes is L.  If the value
 139 for long_offset causes L to be negative, a BadValue error results.
 140 The value of bytes_after_return is A, giving the number of trailing
 141 unread bytes in the stored property.
 142
 143 If the returned format is 8, the returned data is represented as a char
 144 array.  If the returned format is 16, the returned data is represented
 145 as a uint16_t array and should be cast to that type to obtain the ele-
 146 ments.  If the returned format is 32, the returned data is represented
 147 as a uint32_t array and should be cast to that type to obtain the elements.
 148
 149 XIGetProperty always allocates one extra byte in prop_return (even
 150 if the property is zero length) and sets it to zero so that simple
 151 properties consisting of characters do not have to be copied into yet
 152 another string before use.
 153
 154 If delete is True and bytes_after_return is zero, XIGetProperty
 155 deletes the property from the window and generates an XIPropertyNotify
 156 event on the window.
 157
 158 The function returns Success if it executes successfully.  To free the
 159 resulting data, use XFree.
 160
 161 XIGetProperty can generate BadAtom, BadValue, and BadWindow
 162 errors.
 163
 164 The XIChangeProperty function alters the property for the specified device
 165 and causes the X server to generate a XIPropertyNotify event for that
 166 device.  XIChangeProperty performs the following:
 167
 168 - If mode is PropModeReplace, XIChangeProperty discards the previous
 169   property value and stores the new data.
 170
 171 - If mode is PropModePrepend or PropModeAppend, XChangeProperty
 172   inserts the specified data before the beginning of the existing
 173   data or onto the end of the existing data, respectively.  The type
 174   and format must match the existing property value, or a BadMatch
 175   error results.  If the property is undefined, it is treated as
 176   defined with the correct type and format with zero-length data.
 177
 178 If the specified format is 8, the property data must be a char array.
 179 If the specified format is 16, the property data must be a uint16_t array.
 180 If the specified format is 32, the property data must be a uint32_t array.
 181
 182 The lifetime of a property is not tied to the storing client.
 183 Properties remain until explicitly deleted, until the device is removed,
 184 or until the server resets.  The maximum size of a property is server
 185 dependent and can vary dynamically depending on the amount of memory
 186 the server has available.  (If there is insufficient space, a BadAlloc
 187 error results.)
 188
 189 XIChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and
 190 BadDevice errors.
 191
 192 The XIDeleteProperty function deletes the specified property only if the
 193 property was defined on the specified device and causes the X server to
 194 generate a XIPropertyNotify event for the device unless the property does
 195 not exist.
 196
 197 XIDeleteProperty can generate BadAtom and BadDevice errors.
 198
 199
 200 DIAGNOSTICS
 201 -----------
 202 BadAlloc
 203         The server failed to allocate the requested resource or
 204         server memory.
 205
 206 BadAtom
 207         A value for an Atom argument does not name a defined Atom.
 208
 209 BadValue
 210         Some numeric value falls outside the range of values accepted
 211         by the request.  Unless a specific range is specified for an
 212         argument, the full range defined by the argument’s type is
 213         accepted.  Any argument defined as a set of alternatives can
 214         generate this error.
 215
 216 BadDevice
 217        An invalid device was specified. The device does not
 218        exist.
 219
 220 BadAtom
 221        An invalid property was specified. The property does not
 222        exist.
 223
 224 SEE ALSO
 225 --------
 226
 227 XIListProperties(libmansuffix)