Add documentation for xcb_create_window

Submitted by Thomas Fischer on June 25, 2019, 10:50 a.m.

Details

Message ID CAGbX=_U3sQubXzq_GhVq+v92b-XCLg48wWXi0Y3DQbkv2LA5Hg@mail.gmail.com
State New
Headers show
Series "Add documentation for xcb_create_window" ( rev: 1 ) in XCB

Not browsing as part of any series.

Commit Message

Thomas Fischer June 25, 2019, 10:50 a.m.
Hello,

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.
This patch is the previous two patches I sent, but I squashed them into
one, and corrected a typo I had made.

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.

I hope this helps anyone who wants to get into using XCB.

Thanks,
Thomas Fischer

---
 src/xproto.xml | 304 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 233 insertions(+), 71 deletions(-)

   </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 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>
+      <!-- the enum documentation is good enough. -->
+      <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.

Patch hide | download patch | download mbox

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>