Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

136 lines (129 sloc) 5.086 kb
.TH xcb_get_property 3 2011-12-18 "XCB" "XCB Requests"
.ad l
.SH NAME
xcb_get_property \- Gets a window property
.SH SYNOPSIS
.hy 0
.B #include <xcb/xproto.h>
.SS Request function
.HP
xcb_get_property_cookie_t \fBxcb_get_property\fP(xcb_connection_t\ *\fIconn\fP, uint8_t\ \fI_delete\fP, xcb_window_t\ \fIwindow\fP, xcb_atom_t\ \fIproperty\fP, xcb_atom_t\ \fItype\fP, uint32_t\ \fIlong_offset\fP, uint32_t\ \fIlong_length\fP);
.PP
.SS Reply datastructure
.nf
.sp
typedef struct xcb_get_property_reply_t {
uint8_t \fIresponse_type\fP;
uint8_t \fIformat\fP;
uint16_t \fIsequence\fP;
uint32_t \fIlength\fP;
xcb_atom_t \fItype\fP;
uint32_t \fIbytes_after\fP;
uint32_t \fIvalue_len\fP;
uint8_t \fIpad0\fP[12];
} \fBxcb_get_property_reply_t\fP;
.fi
.SS Reply function
.HP
xcb_get_property_reply_t *\fBxcb_get_property_reply\fP(xcb_connection_t\ *\fIconn\fP, xcb_get_property_cookie_t\ \fIcookie\fP, xcb_generic_error_t\ **\fIe\fP);
.SS Reply accessors
.HP
void *\fBxcb_get_property_value\fP(const xcb_get_property_request_t *\fIreply\fP);
.HP
int \fBxcb_get_property_value_length\fP(const xcb_get_property_reply_t *\fIreply\fP);
.HP
xcb_generic_iterator_t \fBxcb_get_property_value_end\fP(const xcb_get_property_reply_t *\fIreply\fP);
.br
.hy 1
.SH REQUEST ARGUMENTS
.IP \fIconn\fP 1i
The XCB connection to X11.
.IP \fI_delete\fP 1i
Whether the property should actually be deleted. For deleting a property, the
specified \fItype\fP has to match the actual property type.
.IP \fIwindow\fP 1i
The window whose property you want to get.
.IP \fIproperty\fP 1i
The property you want to get (an atom).
.IP \fItype\fP 1i
The type of the property you want to get (an atom).
.IP \fIlong_offset\fP 1i
Specifies the offset (in 32-bit multiples) in the specified property where the
data is to be retrieved.
.IP \fIlong_length\fP 1i
Specifies how many 32-bit multiples of data should be retrieved (e.g. if you
set \fIlong_length\fP to 4, you will receive 16 bytes of data).
.SH REPLY FIELDS
.IP \fIresponse_type\fP 1i
The type of this reply, in this case \fIXCB_GET_PROPERTY\fP. This field is also present in the \fIxcb_generic_reply_t\fP and can be used to tell replies apart from each other.
.IP \fIsequence\fP 1i
The sequence number of the last request processed by the X11 server.
.IP \fIlength\fP 1i
The length of the reply, in words (a word is 4 bytes).
.IP \fIformat\fP 1i
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.
.IP \fItype\fP 1i
The actual type of the property (an atom).
.IP \fIbytes_after\fP 1i
The number of bytes remaining to be read in the property if a partial read was
performed.
.IP \fIvalue_len\fP 1i
The length of value. You should use the corresponding accessor instead of this
field.
.SH DESCRIPTION
Gets the specified \fIproperty\fP from the specified \fIwindow\fP. Properties are for
example the window title (\fIWM_NAME\fP) or its minimum size (\fIWM_NORMAL_HINTS\fP).
Protocols such as EWMH also use properties - for example EWMH defines the
window title, encoded as UTF-8 string, in the \fI_NET_WM_NAME\fP property.
TODO: talk about \fItype\fP
TODO: talk about \fIdelete\fP
TODO: talk about the offset/length thing. what's a valid use case?
.SH RETURN VALUE
Returns an \fIxcb_get_property_cookie_t\fP. Errors have to be handled when calling the reply function \fIxcb_get_property_reply\fP.
If you want to handle errors in the event loop instead, use \fIxcb_get_property_unchecked\fP. See \fBxcb-requests(3)\fP for details.
.SH ERRORS
.IP \fIxcb_window_error_t\fP 1i
The specified \fIwindow\fP does not exist.
.IP \fIxcb_value_error_t\fP 1i
The specified \fIlong_offset\fP is beyond the actual property length (e.g. the
property has a length of 3 bytes and you are setting \fIlong_offset\fP to 1,
resulting in a byte offset of 4).
.IP \fIxcb_atom_error_t\fP 1i
\fIproperty\fP or \fItype\fP do not refer to a valid atom.
.SH EXAMPLE
.nf
.sp
/*
* Prints the WM_NAME property of the window.
*
*/
void my_example(xcb_connection *c, xcb_window_t window) {
xcb_get_property_cookie_t cookie;
xcb_get_property_reply_t *reply;
/* These atoms are predefined in the X11 protocol. */
xcb_atom_t property = XCB_ATOM_WM_NAME;
xcb_atom_t type = XCB_ATOM_STRING;
// TODO: a reasonable long_length for WM_NAME?
cookie = xcb_get_property(c, 0, window, property, type, 0, 0);
if ((reply = xcb_get_property_reply(c, cookie, NULL))) {
int len = xcb_get_property_value_length(reply);
if (len == 0) {
printf("TODO\\n");
free(reply);
return;
}
printf("WM_NAME is %.*s\\n", len,
(char*)xcb_get_property_value(reply));
}
free(reply);
}
.fi
.SH SEE ALSO
.BR xcb-requests (3),
.BR xcb-examples (3),
.BR xcb_intern_atom (3),
.BR xprop (1)
.SH AUTHOR
Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.
Jump to Line
Something went wrong with that request. Please try again.