


XGetWindowProperty(3X11)			     XGetWindowProperty(3X11)
X11R5									X11R5



NAME
  XGetWindowProperty, XListProperties, XChangeProperty,	XRotateWindowProper-
  ties,	XDeleteProperty	- obtain and change window properties

SYNTAX
  int XGetWindowProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y, _l_o_n_g__o_f_f_s_e_t, _l_o_n_g__l_e_n_g_t_h,
  _d_e_l_e_t_e, _r_e_q__t_y_p_e,
			  _a_c_t_u_a_l__t_y_p_e__r_e_t_u_r_n, _a_c_t_u_a_l__f_o_r_m_a_t__r_e_t_u_r_n,
  _n_i_t_e_m_s__r_e_t_u_r_n, _b_y_t_e_s__a_f_t_e_r__r_e_t_u_r_n,
			  _p_r_o_p__r_e_t_u_r_n)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	Atom _p_r_o_p_e_r_t_y;
	long _l_o_n_g__o_f_f_s_e_t, _l_o_n_g__l_e_n_g_t_h;
	Bool _d_e_l_e_t_e;
	Atom _r_e_q__t_y_p_e;
	Atom *_a_c_t_u_a_l__t_y_p_e__r_e_t_u_r_n;
	int *_a_c_t_u_a_l__f_o_r_m_a_t__r_e_t_u_r_n;
	unsigned long *_n_i_t_e_m_s__r_e_t_u_r_n;
	unsigned long *_b_y_t_e_s__a_f_t_e_r__r_e_t_u_r_n;
	unsigned char **_p_r_o_p__r_e_t_u_r_n;

  Atom *XListProperties(_d_i_s_p_l_a_y, _w, _n_u_m__p_r_o_p__r_e_t_u_r_n)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	int *_n_u_m__p_r_o_p__r_e_t_u_r_n;

  XChangeProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y,	_t_y_p_e, _f_o_r_m_a_t, _m_o_d_e, _d_a_t_a, _n_e_l_e_m_e_n_t_s)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	Atom _p_r_o_p_e_r_t_y, _t_y_p_e;
	int _f_o_r_m_a_t;
	int _m_o_d_e;
	unsigned char *_d_a_t_a;
	int _n_e_l_e_m_e_n_t_s;

  XRotateWindowProperties(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_i_e_s, _n_u_m__p_r_o_p, _n_p_o_s_i_t_i_o_n_s)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	Atom _p_r_o_p_e_r_t_i_e_s[];
	int _n_u_m__p_r_o_p;
	int _n_p_o_s_i_t_i_o_n_s;

  XDeleteProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	Atom _p_r_o_p_e_r_t_y;

ARGUMENTS

  _a_c_t_u_a_l__f_o_r_m_a_t__r_e_t_u_r_n
	    Returns the	actual format of the property.

  _a_c_t_u_a_l__t_y_p_e__r_e_t_u_r_n
	    Returns the	atom identifier	 that defines the actual type of the
	    property.

  _b_y_t_e_s__a_f_t_e_r__r_e_t_u_r_n
	    Returns the	number of bytes	remaining to be	read in	the property
	    if a partial read was performed.

  _d_a_t_a	    Specifies the property data.

  _d_e_l_e_t_e    Specifies a	Boolean	value that determines whether the property is
	    deleted.

  _d_i_s_p_l_a_y   Specifies the connection to	the X server.

  _f_o_r_m_a_t    Specifies whether the data should be viewed	as a list of 8-bit,
	    16-bit, or 32-bit quantities.  Possible values are 8, 16, and 32.
	    This information allows the	X server to correctly perform byte-
	    swap operations as necessary.  If the format is 16-bit or 32-bit,
	    you	must explicitly	cast your data pointer to an (unsigned char
	    *) in the call to _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y.

  _l_o_n_g__l_e_n_g_t_h
	    Specifies the length in 32-bit multiples of	the data to be
	    retrieved.

  _l_o_n_g__o_f_f_s_e_t
	    Specifies the offset in the	specified property (in 32-bit quanti-
	    ties) where	the data is to be retrieved.

  _m_o_d_e	    Specifies the mode of the operation.  You can pass _P_r_o_p_M_o_d_e_R_e_-
	    _p_l_a_c_e, _P_r_o_p_M_o_d_e_P_r_e_p_e_n_d, or _P_r_o_p_M_o_d_e_A_p_p_e_n_d.

  _n_e_l_e_m_e_n_t_s Specifies the number of elements of	the specified data format.

  _n_i_t_e_m_s__r_e_t_u_r_n
	    Returns the	actual number of 8-bit,	16-bit,	or 32-bit items
	    stored in the prop_return data.

  _n_u_m__p_r_o_p  Specifies the length of the	properties array.

  _n_u_m__p_r_o_p__r_e_t_u_r_n
	    Returns the	length of the properties array.

  _n_p_o_s_i_t_i_o_n_s
	    Specifies the rotation amount.

  _p_r_o_p__r_e_t_u_r_n
	    Returns the	data in	the specified format.

  _p_r_o_p_e_r_t_y  Specifies the property name.

  _p_r_o_p_e_r_t_i_e_s
	    Specifies the array	of properties that are to be rotated.

  _r_e_q__t_y_p_e  Specifies the atom identifier associated with the property type
	    or _A_n_y_P_r_o_p_e_r_t_y_T_y_p_e.

  _t_y_p_e	    Specifies the type of the property.	 The X server does not inter-
	    pret the type but simply passes it back to an application that
	    later calls	_X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y.

  _w	    Specifies the window whose property	you want to obtain, change,
	    rotate or delete.

DESCRIPTION
  The _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y 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 pro-
  perty; and a pointer to the data actually returned.  _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y
  sets the return arguments as follows:

  oo++    If the specified	property does not exist	for the	specified window,
       _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y returns _N_o_n_e to actual_type_return and the value
       zero to actual_format_return and	bytes_after_return.  The
       nitems_return argument is empty.	 In this case, the delete argument is
       ignored.

  oo++    If the specified	property exists	but its	type does not match the
       specified type, _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y returns the actual property type to
       actual_type_return, the actual property format (never zero) to
       actual_format_return, and the property length in	bytes (even if the
       actual_format_return is 16 or 32) to bytes_after_return.	 It also
       ignores the delete argument.  The nitems_return argument	is empty.

  oo++    If the specified	property exists	and either you assign _A_n_y_P_r_o_p_e_r_t_y_T_y_p_e
       to the req_type argument	or the specified type matches the actual pro-
       perty type, _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y returns the actual property type to
       actual_type_return and the actual property format (never	zero) to
       actual_format_return. It	also returns a value to	bytes_after_return
       and nitems_return, by defining the following values:


	       N = actual length of the	stored property	in bytes
		    (even if the format	is 16 or 32)
	       I = 4 * long_offset
	       T = N - I
	       L = MINIMUM(T, 4	* long_length)
	       A = N - (I + L)

       The returned value starts at byte index I in the	property (indexing
       from zero), and its length in bytes is L.  If the value for
       long_offset causes L to be negative, a _B_a_d_V_a_l_u_e error results. The
       value of	bytes_after_return is A, giving	the number of trailing unread
       bytes in	the stored property.

  _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y always allocates one extra	byte in	prop_return (even if
  the property is zero length) and sets	it to ASCII null so that simple	pro-
  perties consisting of	characters do not have to be copied into yet another
  string before	use.  If delete	is _T_r_u_e	and bytes_after_return is zero,
  _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y deletes the property from the window and generates	a
  _P_r_o_p_e_r_t_y_N_o_t_i_f_y event on the window.

  The function returns _S_u_c_c_e_s_s if it executes successfully.  To	free the
  resulting data, use _X_F_r_e_e.

  _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y can generate _B_a_d_A_t_o_m, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w errors.

  The _X_L_i_s_t_P_r_o_p_e_r_t_i_e_s function returns a pointer to an array of	atom proper-
  ties that are	defined	for the	specified window or returns NULL if no pro-
  perties were found.  To free the memory allocated by this function, use
  _X_F_r_e_e.

  _X_L_i_s_t_P_r_o_p_e_r_t_i_e_s can generate a _B_a_d_W_i_n_d_o_w error.

  The _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y function alters the property for the specified window
  and causes the X server to generate a	_P_r_o_p_e_r_t_y_N_o_t_i_f_y event on	that window.
  _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y performs the following:

  oo++    If mode is _P_r_o_p_M_o_d_e_R_e_p_l_a_c_e, _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y discards the	previous pro-
       perty value and stores the new data.

  oo++    If mode is _P_r_o_p_M_o_d_e_P_r_e_p_e_n_d or _P_r_o_p_M_o_d_e_A_p_p_e_n_d, _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y inserts
       the specified data before the beginning of the existing data or onto
       the end of the existing data, respectively.  The	type and format	must
       match the existing property value, or a _B_a_d_M_a_t_c_h	error results.	If
       the property is undefined, it is	treated	as defined with	the correct
       type and	format with zero-length	data.

  The lifetime of a property is	not tied to the	storing	client.	 Properties
  remain until explicitly deleted, until the window is destroyed, or until
  the server resets.  For a discussion of what happens when the	connection to
  the X	server is closed, see section 2.6. The maximum size of a property is
  server dependent and can vary	dynamically depending on the amount of memory
  the server has available.  (If there is insufficient space, a	_B_a_d_A_l_l_o_c
  error	results.)

  _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e, and
  _B_a_d_W_i_n_d_o_w errors.

  The _X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_t_i_e_s function allows you to rotate properties on a
  window and causes the	X server to generate _P_r_o_p_e_r_t_y_N_o_t_i_f_y events.  If	the
  property names in the	properties array are viewed as being numbered start-
  ing from zero	and if there are num_prop property names in the	list, then
  the value associated with property name I becomes the	value associated with
  property name	(I + npositions) mod N for all I from zero to N	- 1.  The
  effect is to rotate the states by npositions places around the virtual ring
  of property names (right for positive	npositions, left for negative nposi-
  tions).  If npositions mod N is nonzero, the X server	generates a _P_r_o_p_e_r_-
  _t_y_N_o_t_i_f_y event for each property in the order	that they are listed in	the
  array.  If an	atom occurs more than once in the list or no property with
  that name is defined for the window, a _B_a_d_M_a_t_c_h error	results.  If a _B_a_d_A_-
  _t_o_m or _B_a_d_M_a_t_c_h error	results, no properties are changed.

  _X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_t_i_e_s can generate _B_a_d_A_t_o_m,	_B_a_d_M_a_t_c_h, and _B_a_d_W_i_n_d_o_w
  errors.

  The _X_D_e_l_e_t_e_P_r_o_p_e_r_t_y function deletes the specified property only if the
  property was defined on the specified	window and causes the X	server to
  generate a _P_r_o_p_e_r_t_y_N_o_t_i_f_y event on the window	unless the property does not
  exist.

  _X_D_e_l_e_t_e_P_r_o_p_e_r_t_y can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.

DIAGNOSTICS

  _B_a_d_A_l_l_o_c  The	server failed to allocate the requested	resource or server
	    memory.

  _B_a_d_A_t_o_m   A value for	an Atom	argument does not name a defined Atom.

  _B_a_d_V_a_l_u_e  Some numeric value falls outside the range of values accepted by
	    the	request.  Unless a specific range is specified for an argu-
	    ment, the full range defined by the	argument's type	is accepted.
	    Any	argument defined as a set of alternatives can generate this
	    error.

  _B_a_d_W_i_n_d_o_w A value for	a Window argument does not name	a defined Window.

SEE ALSO
  XFree(3X11), XInternAtom(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e











