<div dir="ltr"><div class="gmail_quote">Hello,</div><div class="gmail_quote"> </div><div class="gmail_quote">I had forgotten I made this, but here's a patch that adds documentation for xcb_create_window, xcb_create_pixmap, and xcb_create_gc. It also adds an example for xcb_map_window, which I believe I got from the wiki.</div><div class="gmail_quote">This patch is the previous two patches I sent, but I squashed them into one, and corrected a typo I had made.</div><div class="gmail_quote"> </div><div class="gmail_quote">I believe when I was writing this, I was working out of the "X Window System Protocol" and the Xlib man pages, so the information should be accurate, but please let me know if I can correct anything.</div><div class="gmail_quote"> </div><div class="gmail_quote">I hope this helps anyone who wants to get into using XCB.</div><div class="gmail_quote"> </div><div class="gmail_quote">Thanks,</div><div class="gmail_quote">Thomas Fischer</div><div class="gmail_quote"> </div><div class="gmail_quote"> --- src/xproto.xml | 304 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 233 insertions(+), 71 deletions(-) diff --git a/src/xproto.xml b/src/xproto.xml index dea48df..33ca5f1 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>  @@ -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 bits 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,61 @@ <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; + + uint32_t value_mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK; + uint32_t value_list[] = { screen->black_pixel, + XCB_EVENT_MASK_KEY_RELEASE | XCB_EVENT_MASK_EXPOSE + /* | XCB_EVENT_MASK_* ... */ }; + + /* 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 */ + value_mask, value_list ); /* masks, creates window + that receives KEY_RELEASE and EXPOSE events */ + + + /* 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 +2225,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`. @@ -3308,7 +3415,7 @@ <request name="WarpPointer" opcode="41"> relative to the current position of the pointer. ]]></field> <error type="Window"><![CDATA[ -TODO: reasons? +Either the `src_window` or the `dst_window` do not refer to a defined `window`. ]]></error> <see type="request" name="SetInputFocus" /> </doc> @@ -3757,9 +3864,11 @@ <request name="CreatePixmap" opcode="53"> <description><![CDATA[ Creates a pixmap. The pixmap can only be used on the same screen as `drawable` is on and only with drawables of the same `depth`. + +The initial contents of the pixmap are undefined. ]]></description> <field name="depth"><![CDATA[ -TODO +Specifies the new pixmap's color depth in pits per pixel. ]]></field> <field name="pid"><![CDATA[ The ID with which you will refer to the new pixmap, created by @@ -3767,6 +3876,9 @@ <request name="CreatePixmap" opcode="53"> ]]></field> <field name="drawable"><![CDATA[ Drawable to get the screen from. + +It is `legal` to pass an `XCB_WINDOW_CLASS_INPUT_ONLY` drawable to this +request. ]]></field> <field name="width"><![CDATA[ The width of the new pixmap. @@ -3775,7 +3887,8 @@ <request name="CreatePixmap" opcode="53"> The height of the new pixmap. ]]></field> <error type="Value"><![CDATA[ -TODO: reasons? +The `width` and `height` of the pixmap must be nonzero. The `depth` must be +supported by the root of the specified drawable. ]]></error> <error type="Drawable"><![CDATA[ The specified `drawable` (Window or Pixmap) does not exist. @@ -3846,36 +3959,46 @@ <enum name="GC"> Background colorpixel. ]]></field> <field name="LineWidth"><![CDATA[ -The line-width is measured in pixels and can be greater than or equal to one, a wide line, or the -special value zero, a thin line. +The line-width is measured in pixels and can be greater than or equal to one, a +wide line, or the special value zero, a thin line. ]]></field> <field name="LineStyle"><![CDATA[ The line-style defines which sections of a line are drawn: + Solid The full path of the line is drawn. + DoubleDash The full path of the line is drawn, but the even dashes are filled differently than the odd dashes (see fill-style), with Butt cap-style used where even and odd dashes meet. + OnOffDash Only the even dashes are drawn, and cap-style applies to all internal ends of the individual dashes (except NotLast is treated as Butt). ]]></field> <field name="CapStyle"><![CDATA[ The cap-style defines how the endpoints of a path are drawn: + NotLast The result is equivalent to Butt, except that for a line-width of zero the final endpoint is not drawn. + Butt The result is square at the endpoint (perpendicular to the slope of the line) with no projection beyond. + Round The result is a circular arc with its diameter equal to the line-width, centered on the endpoint; it is equivalent to Butt for line-width zero. + Projecting The result is square at the end, but the path continues beyond the endpoint for a distance equal to half the line-width; it is equivalent to Butt for line-width zero. ]]></field> <field name="JoinStyle"><![CDATA[ The join-style defines how corners are drawn for wide lines: + Miter The outer edges of the two lines extend to meet at an angle. However, if the angle is less than 11 degrees, a Bevel join-style is used instead. + Round The result is a circular arc with a diameter equal to the line-width, centered on the joinpoint. + Bevel The result is Butt endpoint styles, and then the triangular notch is filled. ]]></field> <field name="FillStyle"><![CDATA[ @@ -3884,53 +4007,70 @@ <enum name="GC"> as well as for line requests with line-style Solid, (for example, PolyLine, PolySegment, PolyRectangle, PolyArc) and for the even dashes for line requests with line-style OnOffDash or DoubleDash: + Solid Foreground + Tiled Tile + OpaqueStippled A tile with the same width and height as stipple but with background everywhere stipple has a zero and with foreground everywhere stipple has a one + Stippled Foreground masked by stipple + For the odd dashes for line requests with line-style DoubleDash: + Solid Background + Tiled Same as for even dashes + OpaqueStippled Same as for even dashes + Stippled Background masked by stipple ]]></field> <field name="FillRule"><![CDATA[ ]]></field> <field name="Tile"><![CDATA[ -The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all -dimensions. When that plane is superimposed on the drawable for use in a graphics operation, -the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable -specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the -origin of whatever destination drawable is specified in a graphics request. -The tile pixmap must have the same root and depth as the gcontext (or a Match error results). -The stipple pixmap must have depth one and must have the same root as the gcontext (or a -Match error results). For fill-style Stippled (but not fill-style -OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an -additional clip mask to be ANDed with the clip-mask. -Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than -others. +The tile/stipple represents an infinite two-dimensional plane with the +tile/stipple replicated in all dimensions. When that plane is superimposed on +the drawable for use in a graphics operation, the upper-left corner of some +instance of the tile/stipple is at the coordinates within the drawable +specified by the tile/stipple origin. The tile/stipple and clip origins are +interpreted relative to the origin of whatever destination drawable is +specified in a graphics request. + +The tile pixmap must have the same root and depth as the gcontext (or a Match +error results). The stipple pixmap must have depth one and must have the same +root as the gcontext (or a Match error results). For fill-style Stippled (but +not fill-style OpaqueStippled), the stipple pattern is tiled in a single plane +and acts as an additional clip mask to be ANDed with the clip-mask. + +Any size pixmap can be used for tiling or stippling, although some sizes may be +faster to use than others. ]]></field> <field name="Stipple"><![CDATA[ -The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all -dimensions. When that plane is superimposed on the drawable for use in a graphics operation, -the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable -specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the -origin of whatever destination drawable is specified in a graphics request. -The tile pixmap must have the same root and depth as the gcontext (or a Match error results). -The stipple pixmap must have depth one and must have the same root as the gcontext (or a -Match error results). For fill-style Stippled (but not fill-style -OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an -additional clip mask to be ANDed with the clip-mask. -Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than -others. +The tile/stipple represents an infinite two-dimensional plane with the +tile/stipple replicated in all dimensions. When that plane is superimposed on +the drawable for use in a graphics operation, the upper-left corner of some +instance of the tile/stipple is at the coordinates within the drawable +specified by the tile/stipple origin. The tile/stipple and clip origins are +interpreted relative to the origin of whatever destination drawable is +specified in a graphics request. + +The tile pixmap must have the same root and depth as the gcontext (or a Match +error results). The stipple pixmap must have depth one and must have the same +root as the gcontext (or a Match error results). For fill-style Stippled (but +not fill-style OpaqueStippled), the stipple pattern is tiled in a single plane +and acts as an additional clip mask to be ANDed with the clip-mask. + +Any size pixmap can be used for tiling or stippling, although some sizes may be +faster to use than others. ]]></field> <field name="TileStippleOriginX"><![CDATA[ -TODO +Specifies the X origin in the drawable for the `upper-left` corner of the tile/stipple pixmap. ]]></field> <field name="TileStippleOriginY"><![CDATA[ -TODO +Specifies the Y origin in the drawable for the `upper-left` corner of the tile/stipple pixmap. ]]></field> <field name="Font"><![CDATA[ Which font to use for the `ImageText8` and `ImageText16` requests. @@ -3938,11 +4078,11 @@ <enum name="GC"> <field name="SubwindowMode"><![CDATA[ For ClipByChildren, both source and destination windows are additionally clipped by all viewable InputOutput children. For IncludeInferiors, neither -source nor destination window is -clipped by inferiors. This will result in including subwindow contents in the source and drawing -through subwindow boundaries of the destination. The use of IncludeInferiors with a source or -destination window of one depth with mapped inferiors of differing depth is not illegal, but the -semantics is undefined by the core protocol. +source nor destination window is clipped by inferiors. This will result in +including subwindow contents in the source and drawing through subwindow +boundaries of the destination. The use of IncludeInferiors with a source or +destination window of one depth with mapped inferiors of differing depth is not +illegal, but the semantics is undefined by the core protocol. ]]></field> <field name="GraphicsExposures"><![CDATA[ Whether ExposureEvents should be generated (1) or not (0). @@ -3950,28 +4090,43 @@ <enum name="GC"> The default is 1. ]]></field> <field name="ClipOriginX"><![CDATA[ -TODO +Specifies the X origin in the drawable for the `upper-left` corner of the `ClipMask` pixmap. ]]></field> <field name="ClipOriginY"><![CDATA[ -TODO +Specifies the Y origin in the drawable for the `upper-left` corner of the `ClipMask` pixmap. ]]></field> <field name="ClipMask"><![CDATA[ -The clip-mask restricts writes to the destination drawable. Only pixels where the clip-mask has -bits set to 1 are drawn. Pixels are not drawn outside the area covered by the clip-mask or where -the clip-mask has bits set to 0. The clip-mask affects all graphics requests, but it does not clip -sources. The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. If a pixmap is specified as the clip-mask, it must have -depth 1 and have the same root as the gcontext (or a Match error results). If clip-mask is None, -then pixels are always drawn, regardless of the clip origin. The clip-mask can also be set with the +The clip-mask restricts writes to the destination drawable. Only pixels where +the clip-mask has bits set to 1 are drawn. Pixels are not drawn outside the +area covered by the clip-mask or where the clip-mask has bits set to 0. The +clip-mask affects all graphics requests, but it does not clip sources. The +clip-mask origin is interpreted relative to the origin of whatever destination +drawable is specified in a graphics request. If a pixmap is specified as the +clip-mask, it must have depth 1 and have the same root as the gcontext (or a +Match error results). If clip-mask is None, then pixels are always drawn, +regardless of the clip origin. The clip-mask can also be set with the SetClipRectangles request. ]]></field> <field name="DashOffset"><![CDATA[ -TODO +Defines the phase of the dash pattern, specifying how many pixels into `dashes` +the pattern should actually begin in any single graphics request. Dashing is +continuous through path elements combined with a join-style but is reset to the +`DashOffset` between each sequence of joined lines. ]]></field> <field name="DashList"><![CDATA[ -TODO +Specifies a list of `dash lengths` in pixels. All of the elements must be +nonzero or a `Value` error occurs. The length of `DashList` must be nonzero or +a `Value` error occurs. + ]]></field> <field name="ArcMode"><![CDATA[ -TODO +The `ArcMode` controls filling in the `PolyFillArc` request. + +For `Chord`, the single line segment joining the endpoints of the arc is used. + +For `PieSlice`, the two line segments joining the endpoints of the arc with the +center point are used. + ]]></field> </doc> @@ -4150,6 +4305,13 @@ <request name="CreateGC" opcode="55"> ]]></field> <field name="drawable"><![CDATA[ Drawable to get the root/depth from. + ]]></field> +  + <field name="value_mask" /> + <field name="value_list"><![CDATA[ +Values for each of the components specified in the bitmask `value_mask`. The +order has to correspond to the order of possible `value_mask` bits. See the +example in xcb_chane_gc(3). ]]></field> <error type="Drawable"><![CDATA[ The specified `drawable` (Window or Pixmap) does not exist. -- 2.22.0 </div></div>