[PATCH] Add documentation
Thomas Fischer <[email protected]>
| Newsgroups | gmane.comp.freedesktop.xcb |
|---|---|
| Message-ID | <[email protected]> |
From: Synray <[email protected]> --- src/xproto.xml | 150 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 126 insertions(+), 24 deletions(-) diff --git a/src/xproto.xml b/src/xproto.xml index dea48df..9624700 100644 --- a/src/xproto.xml +++ b/src/xproto.xml @@ -1147,6 +1147,27 @@ <enum name="WindowClass"> <item name="CopyFromParent"><value>0</value></item> <item name="InputOutput"> <value>1</value></item> <item name="InputOnly"> <value>2</value></item> + <doc> + <field name="CopyFromParent"><![CDATA[ +The class is taken from the `parent`. A `depth` of zero for class `InputOutput` +or `CopyFromParent` means the `depth` is taken from the `parent`. + ]]></field> + <field name="InputOutput"><![CDATA[ +An `InputOutput` window is the normal kind of opaque window, used for both +input and output. `InputOutput` windows can have both `InputOutput` and +`InputOnly` windows as inferiors. + ]]></field> + <field name="InputOnly"><![CDATA[ +An `InputOnly` window is a window that cannot be used for graphics requests. +`InputOnly` windows are invisible and can be used to control such things as +cursors, input event generation, and grabbing. `InputOnly` windows cannot have +`InputOutput` windows as inferiors. + +The server essentially acts as if `InputOnly` windows do not exist for the +purposes of graphics requests, exposure processing, and `VisibilityNotify` +events. + ]]></field> + </doc> </enum> <!-- Window attributes for CreateWindow and ChangeWindowAttributes. --> @@ -1250,20 +1271,23 @@ <enum name="CW"> ancestor windows when no client has the event type selected in this window. ]]></field> <field name="Colormap"><![CDATA[ -The colormap specifies the colormap that best reflects the true colors of the window. Servers -capable of supporting multiple hardware colormaps may use this information, and window man- -agers may use it for InstallColormap requests. The colormap must have the same visual type -and root as the window (or a Match error results). If CopyFromParent is specified, the parent's -colormap is copied (subsequent changes to the parent's colormap attribute do not affect the child). -However, the window must have the same visual type as the parent (or a Match error results), -and the parent must not have a colormap of None (or a Match error results). For an explanation -of None, see FreeColormap request. The colormap is copied by sharing the colormap object -between the child and the parent, not by making a complete copy of the colormap contents. +The colormap specifies the colormap that best reflects the true colors of the +window. Servers capable of supporting multiple hardware colormaps may use this +information, and window man- agers may use it for `InstallColormap` requests. +The colormap must have the same visual type and `root` as the window (or a +`Match` error results). If `CopyFromParent` is specified, the parent's colormap +is copied (subsequent changes to the parent's colormap attribute do not affect +the child). However, the window must have the same visual type as the parent +(or a Match error results), and the parent must not have a colormap of `None` +(or a `Match` error results). For an explanation of `None`, see `FreeColormap` +request. The colormap is copied by sharing the colormap object between the +child and the parent, not by making a complete copy of the colormap contents. ]]></field> <field name="Cursor"><![CDATA[ -If a cursor is specified, it will be used whenever the pointer is in the window. If None is speci- -fied, the parent's cursor will be used when the pointer is in the window, and any change in the -parent's cursor will cause an immediate change in the displayed cursor. +If a cursor is specified, it will be used whenever the pointer is in the +window. If `None` is specified, the parent's cursor will be used when the +pointer is in the window, and any change in the parent's cursor will cause an +immediate change in the displayed cursor. ]]></field> </doc> </enum> @@ -1365,7 +1389,7 @@ <request name="CreateWindow" opcode="1"> </switch> <doc> - <brief>Creates a window</brief> + <brief>Creates a window and assigns the identifier wid to it</brief> <description><![CDATA[ Creates an unmapped window as child of the specified `parent` window. A CreateNotify event will be generated. The new window is placed on top in the @@ -1387,7 +1411,7 @@ <request name="CreateWindow" opcode="1"> `xcb_generate_id`. ]]></field> <field name="depth"><![CDATA[ -Specifies the new window's depth (TODO: what unit?). +Specifies the new window's color depth in pits per pixel. The special value `XCB_COPY_FROM_PARENT` means the depth is taken from the `parent` window. @@ -1403,35 +1427,63 @@ <request name="CreateWindow" opcode="1"> The parent window of the new window. ]]></field> <field name="border_width"><![CDATA[ - TODO: +An `InputOutput` window can have a border of equal thickness on all four sides of +the window. A `pixmap` defines the contents of the border, and the server +automatically maintains the contents of the border. Exposure events are never +generated for border regions. Must be zero if the `class` is `InputOnly` or a `xcb_match_error_t` occurs. ]]></field> <field name="x"><![CDATA[The X coordinate of the new window.]]></field> <field name="y"><![CDATA[The Y coordinate of the new window.]]></field> <field name="width"><![CDATA[The width of the new window.]]></field> - <field name="height"><![CDATA[The height of the new window.]]></field> + <field name="height"><![CDATA[The height of the new window. + +The `width` and `height` specify the inside size, not including the `border_width`, +and must be nonzero (or a `Value` error results). + ]]></field> + <field name="value_mask" /> + <field name="value_list"><![CDATA[ +Values for each of the attributes specified in the bitmask `value_mask`. The +order has to correspond to the order of possible `value_mask` bits. See the +example. + ]]></field> <error type="Colormap"><![CDATA[ -TODO: reasons? +The value given for the `colormap` argument does not refer to a defined +`xcb_colormap_t`. ]]></error> <error type="Match"><![CDATA[ -TODO: reasons? +For an `InputOnly` window the `border_width` and the `depth` must be zero or +`CopyFromParent`. + +For an `InputOutput` window, the visual type and the `depth` must be a +combination supported for the screen. The parent of an `InputOutput` window +must not be a window of class `InputOnly`. ]]></error> <error type="Cursor"><![CDATA[ -TODO: reasons? +A value for a `xcb_cursor_t` argument does not refer to a defined `xcb_cursor_t`. ]]></error> <error type="Pixmap"><![CDATA[ -TODO: reasons? +A value for a `xcb_pixmap_t` argument does not refer to a defined `xcb_pixmap_t`. ]]></error> <error type="Value"><![CDATA[ -TODO: reasons? +Some numeric value falls outside the range of values accepted by the request. + +The `width` and `height` must be nonzero. ]]></error> <error type="Window"><![CDATA[ -TODO: reasons? +The specified `window` does not exist. ]]></error> <error type="Alloc"><![CDATA[ -The X server could not allocate the requested resources (no memory?). +The X server could not allocate the requested resource. Note that when a server +runs out of allocation space the semantics are left unspecified, but a server +may generate an `xcb_alloc_error_t` error on any request. ]]></error> + <example> + <![CDATA[ +See xcb_map_window(3). + ]]> + </example> <see type="function" name="xcb_generate_id" /> <see type="request" name="MapWindow" /> <see type="event" name="CreateNotify" /> @@ -1758,6 +1810,56 @@ <request name="MapWindow" opcode="8"> <error type="Match"><![CDATA[ The specified window does not exist. ]]></error> + <example> + <![CDATA[ +#include <unistd.h> /* pause() */ + +#include <xcb/xcb.h> + +int +main () +{ + /* Open the connection to the X server */ + xcb_connection_t *connection = xcb_connect (NULL, NULL); + + + /* Get the first screen */ + const xcb_setup_t *setup = xcb_get_setup (connection); + xcb_screen_iterator_t iter = xcb_setup_roots_iterator (setup); + xcb_screen_t *screen = iter.data; + + + /* Create the window */ + xcb_window_t window = xcb_generate_id (connection); + xcb_create_window (connection, /* Connection */ + XCB_COPY_FROM_PARENT, /* depth (same as root)*/ + window, /* window Id */ + screen->root, /* parent window */ + 0, 0, /* x, y */ + 150, 150, /* width, height */ + 10, /* border_width */ + XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */ + screen->root_visual, /* visual */ + 0, NULL ); /* masks, not used yet */ + + + /* Map the window on the screen */ + xcb_map_window (connection, window); + + + /* Make sure commands are sent before we pause so that the window gets shown */ + xcb_flush (connection); + + + pause(); /* hold client until Ctrl-C */ + + xcb_disconnect (connection); + + return 0; +} + + ]]> + </example> <see type="event" name="MapNotify" /> <see type="event" name="Expose" /> <see type="request" name="UnmapWindow" /> @@ -2118,7 +2220,7 @@ <request name="InternAtom" opcode="16"> Return a valid atom id only if the atom already exists. ]]></field> <error type="Alloc"><![CDATA[ -TODO: reasons? +The X server could not store the property (no memory?). ]]></error> <error type="Value"><![CDATA[ A value other than 0 or 1 was specified for `only_if_exists`. -- 2.18.0 _______________________________________________ Xcb mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/xcb