diff options
Diffstat (limited to 'libxcb/xcb-proto/src/xproto.xml')
| -rw-r--r-- | libxcb/xcb-proto/src/xproto.xml | 2796 |
1 files changed, 2789 insertions, 7 deletions
diff --git a/libxcb/xcb-proto/src/xproto.xml b/libxcb/xcb-proto/src/xproto.xml index 42a6852a1..bf4dcbf0f 100644 --- a/libxcb/xcb-proto/src/xproto.xml +++ b/libxcb/xcb-proto/src/xproto.xml @@ -307,6 +307,44 @@ authorization from the authors. <field type="CARD16" name="state" mask="KeyButMask" /> <field type="BOOL" name="same_screen" /> <pad bytes="1" /> + <doc> + <brief>a key was pressed/released</brief> + <field name="detail"><![CDATA[ +The keycode (a number representing a physical key on the keyboard) of the key +which was pressed. + ]]></field> + <field name="time"><![CDATA[ +Time when the event was generated (in milliseconds). + ]]></field> + <field name="root"><![CDATA[ +The root window of `child`. + ]]></field> + <field name="same_screen"><![CDATA[ +Whether the `event` window is on the same screen as the `root` window. + ]]></field> + <field name="event_x"><![CDATA[ +If `same_screen` is true, this is the X coordinate relative to the `event` +window's origin. Otherwise, `event_x` will be set to zero. + ]]></field> + <field name="event_y"><![CDATA[ +If `same_screen` is true, this is the Y coordinate relative to the `event` +window's origin. Otherwise, `event_y` will be set to zero. + ]]></field> + <field name="root_x"><![CDATA[ +The X coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="root_y"><![CDATA[ +The Y coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="state"><![CDATA[ +The logical state of the pointer buttons and modifier keys just prior to the +event. + ]]></field> + <see type="request" name="GrabKey" /> + <see type="request" name="GrabKeyboard" /> + </doc> </event> <eventcopy name="KeyRelease" number="3" ref="KeyPress" /> @@ -333,6 +371,44 @@ authorization from the authors. <field type="CARD16" name="state" mask="KeyButMask" /> <field type="BOOL" name="same_screen" /> <pad bytes="1" /> + <doc> + <brief>a mouse button was pressed/released</brief> + <field name="detail"><![CDATA[ +The keycode (a number representing a physical key on the keyboard) of the key +which was pressed. + ]]></field> + <field name="time"><![CDATA[ +Time when the event was generated (in milliseconds). + ]]></field> + <field name="root"><![CDATA[ +The root window of `child`. + ]]></field> + <field name="same_screen"><![CDATA[ +Whether the `event` window is on the same screen as the `root` window. + ]]></field> + <field name="event_x"><![CDATA[ +If `same_screen` is true, this is the X coordinate relative to the `event` +window's origin. Otherwise, `event_x` will be set to zero. + ]]></field> + <field name="event_y"><![CDATA[ +If `same_screen` is true, this is the Y coordinate relative to the `event` +window's origin. Otherwise, `event_y` will be set to zero. + ]]></field> + <field name="root_x"><![CDATA[ +The X coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="root_y"><![CDATA[ +The Y coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="state"><![CDATA[ +The logical state of the pointer buttons and modifier keys just prior to the +event. + ]]></field> + <see type="request" name="GrabButton" /> + <see type="request" name="GrabPointer" /> + </doc> </event> <eventcopy name="ButtonRelease" number="5" ref="ButtonPress" /> @@ -356,6 +432,44 @@ authorization from the authors. <field type="CARD16" name="state" mask="KeyButMask" /> <field type="BOOL" name="same_screen" /> <pad bytes="1" /> + <doc> + <brief>a key was pressed</brief> + <field name="detail"><![CDATA[ +The keycode (a number representing a physical key on the keyboard) of the key +which was pressed. + ]]></field> + <field name="time"><![CDATA[ +Time when the event was generated (in milliseconds). + ]]></field> + <field name="root"><![CDATA[ +The root window of `child`. + ]]></field> + <field name="same_screen"><![CDATA[ +Whether the `event` window is on the same screen as the `root` window. + ]]></field> + <field name="event_x"><![CDATA[ +If `same_screen` is true, this is the X coordinate relative to the `event` +window's origin. Otherwise, `event_x` will be set to zero. + ]]></field> + <field name="event_y"><![CDATA[ +If `same_screen` is true, this is the Y coordinate relative to the `event` +window's origin. Otherwise, `event_y` will be set to zero. + ]]></field> + <field name="root_x"><![CDATA[ +The X coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="root_y"><![CDATA[ +The Y coordinate of the pointer relative to the `root` window at the time of +the event. + ]]></field> + <field name="state"><![CDATA[ +The logical state of the pointer buttons and modifier keys just prior to the +event. + ]]></field> + <see type="request" name="GrabKey" /> + <see type="request" name="GrabKeyboard" /> + </doc> </event> <enum name="NotifyDetail"> @@ -389,6 +503,34 @@ authorization from the authors. <field type="CARD16" name="state" mask="KeyButMask" /> <field type="BYTE" name="mode" enum="NotifyMode" /> <field type="BYTE" name="same_screen_focus" /> + <doc> + <brief>the pointer is in a different window</brief> + <field name="event"><![CDATA[ +The reconfigured window or its parent, depending on whether `StructureNotify` +or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The window that was unmapped. + ]]></field> + <field name="root"><![CDATA[ +The root window for the final cursor position. + ]]></field> + <field name="root_x"><![CDATA[ +The pointer X coordinate relative to `root`'s origin at the time of the event. + ]]></field> + <field name="root_y"><![CDATA[ +The pointer Y coordinate relative to `root`'s origin at the time of the event. + ]]></field> + <field name="event_x"><![CDATA[ +If `event` is on the same screen as `root`, this is the pointer X coordinate +relative to the event window's origin. + ]]></field> + <field name="event_y"><![CDATA[ +If `event` is on the same screen as `root`, this is the pointer Y coordinate +relative to the event window's origin. + ]]></field> + <field name="mode" /> + </doc> </event> <eventcopy name="LeaveNotify" number="8" ref="EnterNotify" /> @@ -398,6 +540,16 @@ authorization from the authors. <field type="WINDOW" name="event" /> <field type="BYTE" name="mode" enum="NotifyMode" /> <pad bytes="3" /> + <doc> + <brief>NOT YET DOCUMENTED</brief> + <field name="event"><![CDATA[ +The window on which the focus event was generated. This is the window used by +the X server to report the event. + ]]></field> + <!-- enum documentation is sufficient --> + <field name="detail" /> + <field name="mode" /> + </doc> </event> <eventcopy name="FocusOut" number="10" ref="FocusIn" /> @@ -415,6 +567,32 @@ authorization from the authors. <field type="CARD16" name="height" /> <field type="CARD16" name="count" /> <pad bytes="2" /> + <doc> + <brief>NOT YET DOCUMENTED</brief> + <field name="window"><![CDATA[ +The exposed (damaged) window. + ]]></field> + <field name="x"><![CDATA[ +The X coordinate of the left-upper corner of the exposed rectangle, relative to +the `window`'s origin. + ]]></field> + <field name="y"><![CDATA[ +The Y coordinate of the left-upper corner of the exposed rectangle, relative to +the `window`'s origin. + ]]></field> + <field name="width"><![CDATA[ +The width of the exposed rectangle. + ]]></field> + <field name="height"><![CDATA[ +The height of the exposed rectangle. + ]]></field> + <field name="count"><![CDATA[ +The amount of `Expose` events following this one. Simple applications that do +not want to optimize redisplay by distinguishing between subareas of its window +can just ignore all Expose events with nonzero counts and perform full +redisplays on events with zero counts. + ]]></field> + </doc> </event> <event name="GraphicsExposure" number="13"> @@ -468,6 +646,17 @@ authorization from the authors. <pad bytes="1" /> <field type="WINDOW" name="event" /> <field type="WINDOW" name="window" /> + <doc> + <brief>a window is destroyed</brief> + <field name="event"><![CDATA[ +The reconfigured window or its parent, depending on whether `StructureNotify` +or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The window that is destroyed. + ]]></field> + <see type="request" name="DestroyWindow" /> + </doc> </event> <event name="UnmapNotify" number="18"> @@ -476,6 +665,21 @@ authorization from the authors. <field type="WINDOW" name="window" /> <field type="BOOL" name="from_configure" /> <pad bytes="3" /> + <doc> + <brief>a window is unmapped</brief> + <field name="event"><![CDATA[ +The reconfigured window or its parent, depending on whether `StructureNotify` +or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The window that was unmapped. + ]]></field> + <field name="from_configure"><![CDATA[ +Set to 1 if the event was generated as a result of a resizing of the window's +parent when `window` had a win_gravity of `UnmapGravity`. + ]]></field> + <see type="request" name="UnmapWindow" /> + </doc> </event> <event name="MapNotify" number="19"> @@ -484,12 +688,36 @@ authorization from the authors. <field type="WINDOW" name="window" /> <field type="BOOL" name="override_redirect" /> <pad bytes="3" /> + <doc> + <brief>a window was mapped</brief> + <field name="event"><![CDATA[ +The window which was mapped or its parent, depending on whether +`StructureNotify` or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The window that was mapped. + ]]></field> + <field name="override_redirect"><![CDATA[ +Window managers should ignore this window if `override_redirect` is 1. + ]]></field> + <see type="request" name="MapWindow" /> + </doc> </event> <event name="MapRequest" number="20"> <pad bytes="1" /> <field type="WINDOW" name="parent" /> <field type="WINDOW" name="window" /> + <doc> + <brief>window wants to be mapped</brief> + <field name="parent"><![CDATA[ +The parent of `window`. + ]]></field> + <field name="window"><![CDATA[ +The window to be mapped. + ]]></field> + <see type="request" name="MapWindow" /> + </doc> </event> <event name="ReparentNotify" number="21"> @@ -515,6 +743,42 @@ authorization from the authors. <field type="CARD16" name="border_width" /> <field type="BOOL" name="override_redirect" /> <pad bytes="1" /> + <doc> + <brief>NOT YET DOCUMENTED</brief> + <field name="event"><![CDATA[ +The reconfigured window or its parent, depending on whether `StructureNotify` +or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The window whose size, position, border, and/or stacking order was changed. + ]]></field> + <field name="above_sibling"><![CDATA[ +If `XCB_NONE`, the `window` is on the bottom of the stack with respect to +sibling windows. However, if set to a sibling window, the `window` is placed on +top of this sibling window. + ]]></field> + <field name="x"><![CDATA[ +The X coordinate of the upper-left outside corner of `window`, relative to the +parent window's origin. + ]]></field> + <field name="y"><![CDATA[ +The Y coordinate of the upper-left outside corner of `window`, relative to the +parent window's origin. + ]]></field> + <field name="width"><![CDATA[ +The inside width of `window`, not including the border. + ]]></field> + <field name="height"><![CDATA[ +The inside height of `window`, not including the border. + ]]></field> + <field name="border_width"><![CDATA[ +The border width of `window`. + ]]></field> + <field name="override_redirect"><![CDATA[ +Window managers should ignore this window if `override_redirect` is 1. + ]]></field> + <see type="request" name="FreeColormap" /> + </doc> </event> <event name="ConfigureRequest" number="23"> @@ -548,6 +812,14 @@ authorization from the authors. <enum name="Place"> <item name="OnTop"> <value>0</value></item> <item name="OnBottom"><value>1</value></item> + <doc> + <field name="OnTop"><![CDATA[ +The window is now on top of all siblings. + ]]></field> + <field name="OnBottom"><![CDATA[ +The window is now below all siblings. + ]]></field> + </doc> </enum> <event name="CirculateNotify" number="26"> @@ -557,6 +829,19 @@ authorization from the authors. <pad bytes="4" /> <field type="BYTE" name="place" enum="Place" /> <pad bytes="3" /> + <doc> + <brief>NOT YET DOCUMENTED</brief> + <field name="event"><![CDATA[ +Either the restacked window or its parent, depending on whether +`StructureNotify` or `SubstructureNotify` was selected. + ]]></field> + <field name="window"><![CDATA[ +The restacked window. + ]]></field> + <!-- the enum doc is sufficient --> + <field name="place" /> + <see type="request" name="CirculateWindow" /> + </doc> </event> <eventcopy name="CirculateRequest" number="27" ref="CirculateNotify" /> @@ -573,6 +858,21 @@ authorization from the authors. <field type="TIMESTAMP" name="time" /> <field type="BYTE" name="state" enum="Property" /> <pad bytes="3" /> + <doc> + <brief>a window property changed</brief> + <field name="window"><![CDATA[ +The window whose associated property was changed. + ]]></field> + <field name="atom"><![CDATA[ +The property's atom, to indicate which property was changed. + ]]></field> + <field name="time"><![CDATA[ +A timestamp of the server time when the property was changed. + ]]></field> + <!-- enum documentation is sufficient --> + <field name="state" /> + <see type="request" name="ChangeProperty" /> + </doc> </event> <event name="SelectionClear" number="29"> @@ -681,6 +981,14 @@ authorization from the authors. <enum name="ColormapState"> <item name="Uninstalled"><value>0</value></item> <item name="Installed"> <value>1</value></item> + <doc> + <field name="Uninstalled"><![CDATA[ +The colormap was uninstalled. + ]]></field> + <field name="Installed"><![CDATA[ +The colormap was installed. + ]]></field> + </doc> </enum> <enum name="Colormap"> @@ -694,6 +1002,22 @@ authorization from the authors. <field type="BOOL" name="new" /> <field type="BYTE" name="state" enum="ColormapState" /> <pad bytes="2" /> + <doc> + <brief>the colormap for some window changed</brief> + <field name="window"><![CDATA[ +The window whose associated colormap is changed, installed or uninstalled. + ]]></field> + <field name="colormap"><![CDATA[ +The colormap which is changed, installed or uninstalled. This is `XCB_NONE` +when the colormap is changed by a call to `FreeColormap`. + ]]></field> + <field name="_new"><![CDATA[ +Indicates whether the colormap was changed (1) or installed/uninstalled (0). + ]]></field> + <!-- enum doc is sufficient --> + <field name="state" /> + <see type="request" name="FreeColormap" /> + </doc> </event> <union name="ClientMessageData"> @@ -709,6 +1033,26 @@ authorization from the authors. <field type="WINDOW" name="window" /> <field type="ATOM" name="type" /> <field type="ClientMessageData" name="data" /> + <doc> + <brief>NOT YET DOCUMENTED</brief> + <description><![CDATA[ +This event represents a ClientMessage, sent by another X11 client. An example +is a client sending the `_NET_WM_STATE` ClientMessage to the root window +to indicate the fullscreen window state, effectively requesting that the window +manager puts it into fullscreen mode. + ]]></description> + <field name="format"><![CDATA[ +Specifies how to interpret `data`. Can be either 8, 16 or 32. + ]]></field> + <field name="type"><![CDATA[ +An atom which indicates how the data should be interpreted by the receiving +client. + ]]></field> + <field name="data"><![CDATA[ +The data itself (20 bytes max). + ]]></field> + <see type="request" name="SendEvent" /> + </doc> </event> <enum name="Mapping"> @@ -723,6 +1067,17 @@ authorization from the authors. <field type="KEYCODE" name="first_keycode" /> <field type="CARD8" name="count" /> <pad bytes="1" /> + <doc> + <brief>keyboard mapping changed</brief> + <!-- enum documentation is sufficient --> + <field name="request" /> + <field name="first_keycode"><![CDATA[ +The first number in the range of the altered mapping. + ]]></field> + <field name="count"><![CDATA[ +The number of keycodes altered. + ]]></field> + </doc> </event> @@ -791,6 +1146,106 @@ authorization from the authors. <item name="DontPropagate"> <bit>12</bit></item> <item name="Colormap"> <bit>13</bit></item> <item name="Cursor"> <bit>14</bit></item> + <doc> + <field name="BackPixmap"><![CDATA[ +Overrides the default background-pixmap. The background pixmap and window must +have the same root and same depth. Any size pixmap can be used, although some +sizes may be faster than others. + +If `XCB_BACK_PIXMAP_NONE` is specified, the window has no defined background. +The server may fill the contents with the previous screen contents or with +contents of its own choosing. + +If `XCB_BACK_PIXMAP_PARENT_RELATIVE` is specified, the parent's background is +used, but the window must have the same depth as the parent (or a Match error +results). The parent's background is tracked, and the current version is +used each time the window background is required. + ]]></field> + <field name="BackPixel"><![CDATA[ +Overrides `BackPixmap`. A pixmap of undefined size filled with the specified +background pixel is used for the background. Range-checking is not performed, +the background pixel is truncated to the appropriate number of bits. + ]]></field> + <field name="BorderPixmap"><![CDATA[ +Overrides the default border-pixmap. The border pixmap and window must have the +same root and the same depth. Any size pixmap can be used, although some sizes +may be faster than others. + +The special value `XCB_COPY_FROM_PARENT` means the parent's border pixmap is +copied (subsequent changes to the parent's border attribute do not affect the +child), but the window must have the same depth as the parent. + ]]></field> + <field name="BorderPixel"><![CDATA[ +Overrides `BorderPixmap`. A pixmap of undefined size filled with the specified +border pixel is used for the border. Range checking is not performed on the +border-pixel value, it is truncated to the appropriate number of bits. + ]]></field> + <field name="BitGravity"><![CDATA[ +Defines which region of the window should be retained if the window is resized. + ]]></field> + <field name="WinGravity"><![CDATA[ +Defines how the window should be repositioned if the parent is resized (see +`ConfigureWindow`). + ]]></field> + <field name="BackingStore"><![CDATA[ +A backing-store of `WhenMapped` advises the server that maintaining contents of +obscured regions when the window is mapped would be beneficial. A backing-store +of `Always` advises the server that maintaining contents even when the window +is unmapped would be beneficial. In this case, the server may generate an +exposure event when the window is created. A value of `NotUseful` advises the +server that maintaining contents is unnecessary, although a server may still +choose to maintain contents while the window is mapped. Note that if the server +maintains contents, then the server should maintain complete contents not just +the region within the parent boundaries, even if the window is larger than its +parent. While the server maintains contents, exposure events will not normally +be generated, but the server may stop maintaining contents at any time. + ]]></field> + <field name="BackingPlanes"><![CDATA[ +The backing-planes indicates (with bits set to 1) which bit planes of the +window hold dynamic data that must be preserved in backing-stores and during +save-unders. + ]]></field> + <field name="BackingPixel"><![CDATA[ +The backing-pixel specifies what value to use in planes not covered by +backing-planes. The server is free to save only the specified bit planes in the +backing-store or save-under and regenerate the remaining planes with the +specified pixel value. Any bits beyond the specified depth of the window in +these values are simply ignored. + ]]></field> + <field name="OverrideRedirect"><![CDATA[ +The override-redirect specifies whether map and configure requests on this +window should override a SubstructureRedirect on the parent, typically to +inform a window manager not to tamper with the window. + ]]></field> + <field name="SaveUnder"><![CDATA[ +If 1, the server is advised that when this window is mapped, saving the +contents of windows it obscures would be beneficial. + ]]></field> + <field name="EventMask"><![CDATA[ +The event-mask defines which events the client is interested in for this window +(or for some event types, inferiors of the window). + ]]></field> + <field name="DontPropagate"><![CDATA[ +The do-not-propagate-mask defines which events should not be propagated to +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. + ]]></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. + ]]></field> + </doc> </enum> <enum name="BackPixmap"> @@ -827,6 +1282,79 @@ authorization from the authors. <valueparam value-mask-type="CARD32" value-mask-name="value_mask" value-list-name="value_list" /> + <doc> + <brief>Creates a window</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 +stacking order with respect to siblings. + +The coordinate system has the X axis horizontal and the Y axis vertical with +the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms +of pixels, and coincide with pixel centers. Each window and pixmap has its own +coordinate system. For a window, the origin is inside the border at the inside, +upper-left corner. + +The created window is not yet displayed (mapped), call `xcb_map_window` to +display it. + +The created window will initially use the same cursor as its parent. + ]]></description> + <field name="wid"><![CDATA[ +The ID with which you will refer to the new window, created by +`xcb_generate_id`. + ]]></field> + <field name="depth"><![CDATA[ +Specifies the new window's depth (TODO: what unit?). + +The special value `XCB_COPY_FROM_PARENT` means the depth is taken from the +`parent` window. + ]]></field> + <field name="visual"><![CDATA[ +Specifies the id for the new window's visual. + +The special value `XCB_COPY_FROM_PARENT` means the visual is taken from the +`parent` window. + ]]></field> + <field name="class"></field> + <field name="parent"><![CDATA[ +The parent window of the new window. + ]]></field> + <field name="border_width"><![CDATA[ + TODO: + +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> + <error type="Colormap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Cursor"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Pixmap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Alloc"><![CDATA[ +The X server could not allocate the requested resources (no memory?). + ]]></error> + <see type="function" name="xcb_generate_id" /> + <see type="request" name="MapWindow" /> + <see type="event" name="CreateNotify" /> + </doc> + </request> <request name="ChangeWindowAttributes" opcode="2"> @@ -835,6 +1363,43 @@ authorization from the authors. <valueparam value-mask-type="CARD32" value-mask-name="value_mask" value-list-name="value_list" /> + <doc> + <brief>change window attributes</brief> + <description><![CDATA[ +Changes the attributes specified by `value_mask` for the specified `window`. + ]]></description> + <field name="window"><![CDATA[ +The window to change. + ]]></field> + <!-- the enum documentation is good enough. --> + <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="Access"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Colormap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Cursor"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Pixmap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + </doc> </request> <enum name="MapState"> @@ -863,12 +1428,79 @@ authorization from the authors. <field type="CARD32" name="your_event_mask" mask="EventMask" /> <field type="CARD16" name="do_not_propagate_mask" mask="EventMask" /> <pad bytes="2" /> + <doc> + <field name="override_redirect"><![CDATA[ +Window managers should ignore this window if `override_redirect` is 1. + ]]></field> + <field name="visual"><![CDATA[ +The associated visual structure of `window`. + ]]></field> + <field name="backing_planes"><![CDATA[ +Planes to be preserved if possible. + ]]></field> + <field name="backing_pixel"><![CDATA[ +Value to be used when restoring planes. + ]]></field> + <field name="save_under"><![CDATA[ +Boolean, should bits under be saved? + ]]></field> + <field name="colormap"><![CDATA[ +Color map to be associated with window. + ]]></field> + <field name="all_event_masks"><![CDATA[ +Set of events all people have interest in. + ]]></field> + <field name="your_event_mask"><![CDATA[ +My event mask. + ]]></field> + <field name="do_not_propagate_mask"><![CDATA[ +Set of events that should not propagate. + ]]></field> + <!-- enum documentation is sufficient for these fields --> + <field name="backing_store" /> + <field name="class" /> + <field name="bit_gravity" /> + <field name="win_gravity" /> + <field name="map_state" /> + </doc> </reply> + <doc> + <brief>Gets window attributes</brief> + <description><![CDATA[ +Gets the current attributes for the specified `window`. + ]]></description> + <field name="window"><![CDATA[The window to get the attributes from.]]></field> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <error type="Drawable"><![CDATA[ +TODO: reasons? + ]]></error> + </doc> + </request> <request name="DestroyWindow" opcode="4"> <pad bytes="1" /> <field type="WINDOW" name="window" /> + <doc> + <brief>Destroys a window</brief> + <description><![CDATA[ +Destroys the specified window and all of its subwindows. A DestroyNotify event +is generated for each destroyed window (a DestroyNotify event is first generated +for any given window's inferiors). If the window was mapped, it will be +automatically unmapped before destroying. + +Calling DestroyWindow on the root window will do nothing. + ]]></description> + <field name="window"><![CDATA[The window to destroy.]]></field> + <error type="Window"><![CDATA[ +The specified window does not exist. + ]]></error> + <see type="event" name="DestroyNotify" /> + <see type="request" name="MapWindow" /> + <see type="request" name="UnmapWindow" /> + </doc> </request> <request name="DestroySubwindows" opcode="5"> @@ -884,6 +1516,28 @@ authorization from the authors. <request name="ChangeSaveSet" opcode="6"> <field type="BYTE" name="mode" enum="SetMode" /> <field type="WINDOW" name="window" /> + <doc> + <brief>Changes a client's save set</brief> + <description><![CDATA[ +TODO: explain what the save set is for. + +This function either adds or removes the specified window to the client's (your +application's) save set. + ]]></description> + <field name="mode"><![CDATA[Insert to add the specified window to the save set or Delete to delete it from the save set.]]></field> + <field name="window"><![CDATA[The window to add or delete to/from your save set.]]></field> + <error type="Match"><![CDATA[ +You created the specified window. This does not make sense, you can only add +windows created by other clients to your save set. + ]]></error> + <error type="Value"><![CDATA[ +You specified an invalid mode. + ]]></error> + <error type="Window"><![CDATA[ +The specified window does not exist. + ]]></error> + <see type="request" name="ReparentWindow" /> + </doc> </request> <request name="ReparentWindow" opcode="7"> @@ -892,11 +1546,78 @@ authorization from the authors. <field type="WINDOW" name="parent" /> <field type="INT16" name="x" /> <field type="INT16" name="y" /> + <doc> + <brief>Reparents a window</brief> + <description><![CDATA[ +Makes the specified window a child of the specified parent window. If the +window is mapped, it will automatically be unmapped before reparenting and +re-mapped after reparenting. The window is placed in the stacking order on top +with respect to sibling windows. + +After reparenting, a ReparentNotify event is generated. + ]]></description> + <field name="window"><![CDATA[The window to reparent.]]></field> + <field name="parent"><![CDATA[The new parent of the window.]]></field> + <field name="x"><![CDATA[ +The X position of the window within its new parent. + ]]></field> + <field name="y"><![CDATA[ +The Y position of the window within its new parent. + ]]></field> + <error type="Match"><![CDATA[ +The new parent window is not on the same screen as the old parent window. + +The new parent window is the specified window or an inferior of the specified window. + +The new parent is InputOnly and the window is not. + +The specified window has a ParentRelative background and the new parent window is not the same depth as the specified window. + ]]></error> + <error type="Window"><![CDATA[ +The specified window does not exist. + ]]></error> + <see type="event" name="ReparentNotify" /> + <see type="request" name="MapWindow" /> + <see type="request" name="UnmapWindow" /> + </doc> </request> <request name="MapWindow" opcode="8"> <pad bytes="1" /> <field type="WINDOW" name="window" /> + <doc> + <brief>Makes a window visible</brief> + <description><![CDATA[ +Maps the specified window. This means making the window visible (as long as its +parent is visible). + +This MapWindow request will be translated to a MapRequest request if a window +manager is running. The window manager then decides to either map the window or +not. Set the override-redirect window attribute to true if you want to bypass +this mechanism. + +If the window manager decides to map the window (or if no window manager is +running), a MapNotify event is generated. + +If the window becomes viewable and no earlier contents for it are remembered, +the X server tiles the window with its background. If the window's background +is undefined, the existing screen contents are not altered, and the X server +generates zero or more Expose events. + +If the window type is InputOutput, an Expose event will be generated when the +window becomes visible. The normal response to an Expose event should be to +repaint the window. + ]]></description> + <field name="window"><![CDATA[ +The window to make visible. +]]></field> + <error type="Match"><![CDATA[ +The specified window does not exist. + ]]></error> + <see type="event" name="MapNotify" /> + <see type="event" name="Expose" /> + <see type="request" name="UnmapWindow" /> + </doc> </request> <request name="MapSubwindows" opcode="9"> @@ -907,6 +1628,25 @@ authorization from the authors. <request name="UnmapWindow" opcode="10"> <pad bytes="1" /> <field type="WINDOW" name="window" /> + <doc> + <brief>Makes a window invisible</brief> + <description><![CDATA[ +Unmaps the specified window. This means making the window invisible (and all +its child windows). + +Unmapping a window leads to the `UnmapNotify` event being generated. Also, +`Expose` events are generated for formerly obscured windows. + ]]></description> + <field name="window"><![CDATA[ +The window to make invisible. +]]></field> + <error type="Window"><![CDATA[ +The specified window does not exist. + ]]></error> + <see type="event" name="UnmapNotify" /> + <see type="event" name="Expose" /> + <see type="request" name="MapWindow" /> + </doc> </request> <request name="UnmapSubwindows" opcode="11"> @@ -940,6 +1680,55 @@ authorization from the authors. <valueparam value-mask-type="CARD16" value-mask-name="value_mask" value-list-name="value_list" /> + <doc> + <brief>Configures window attributes</brief> + <description><![CDATA[ +Configures a window's size, position, border width and stacking order. + ]]></description> + <example><![CDATA[ +/* + * Configures the given window to the left upper corner + * with a size of 1024x768 pixels. + * + */ +void my_example(xcb_connection *c, xcb_window_t window) { + uint16_t mask = 0; + + mask |= XCB_CONFIG_WINDOW_X; + mask |= XCB_CONFIG_WINDOW_Y; + mask |= XCB_CONFIG_WINDOW_WIDTH; + mask |= XCB_CONFIG_WINDOW_HEIGHT; + + const uint32_t values[] = { + 0, /* x */ + 0, /* y */ + 1024, /* width */ + 768 /* height */ + }; + + xcb_configure_window(c, window, mask, values); + xcb_flush(c); +} + ]]></example> + <field name="window"><![CDATA[The window to configure.]]></field> + <field name="value_mask"><![CDATA[Bitmask of attributes to change.]]></field> + <field name="value_list"><![CDATA[ +New values, corresponding to the attributes in value_mask. The order has to +correspond to the order of possible `value_mask` bits. See the example. + ]]></field> + <error type="Match"><![CDATA[ +You specified a Sibling without also specifying StackMode or the window is not +actually a Sibling. + ]]></error> + <error type="Window"><![CDATA[ +The specified window does not exist. TODO: any other reason? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="event" name="MapNotify" /> + <see type="event" name="Expose" /> + </doc> </request> <enum name="Circulate"> @@ -950,6 +1739,27 @@ authorization from the authors. <request name="CirculateWindow" opcode="13"> <field type="CARD8" name="direction" enum="Circulate" /> <field type="WINDOW" name="window" /> + <doc> + <brief>Change window stacking order</brief> + <description><![CDATA[ +If `direction` is `XCB_CIRCULATE_RAISE_LOWEST`, the lowest mapped child (if +any) will be raised to the top of the stack. + +If `direction` is `XCB_CIRCULATE_LOWER_HIGHEST`, the highest mapped child will +be lowered to the bottom of the stack. + ]]></description> + <!-- The enums are documented, we have nothing to add. --> + <field name="direction" /> + <field name="window"><![CDATA[ +The window to raise/lower (depending on `direction`). + ]]></field> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <error type="Value"><![CDATA[ +The specified `direction` is invalid. + ]]></error> + </doc> </request> <request name="GetGeometry" opcode="14"> @@ -964,7 +1774,67 @@ authorization from the authors. <field type="CARD16" name="height" /> <field type="CARD16" name="border_width" /> <pad bytes="2" /> + <doc> + <field name="root"><![CDATA[ +Root window of the screen containing `drawable`. + ]]></field> + <field name="x"><![CDATA[ +The X coordinate of `drawable`. If `drawable` is a window, the coordinate +specifies the upper-left outer corner relative to its parent's origin. If +`drawable` is a pixmap, the X coordinate is always 0. + ]]></field> + <field name="y"><![CDATA[ +The Y coordinate of `drawable`. If `drawable` is a window, the coordinate +specifies the upper-left outer corner relative to its parent's origin. If +`drawable` is a pixmap, the Y coordinate is always 0. + ]]></field> + <field name="width"><![CDATA[ +The width of `drawable`. + ]]></field> + <field name="height"><![CDATA[ +The height of `drawable`. + ]]></field> + <field name="border_width"><![CDATA[ +The border width (in pixels). + ]]></field> + <field name="depth"><![CDATA[ +The depth of the drawable (bits per pixel for the object). + ]]></field> + </doc> </reply> + <doc> + <brief>Get current window geometry</brief> + <description><![CDATA[ +Gets the current geometry of the specified drawable (either `Window` or `Pixmap`). + ]]></description> + <example><![CDATA[ +/* + * Displays the x and y position of the given window. + * + */ +void my_example(xcb_connection *c, xcb_window_t window) { + xcb_get_geometry_cookie_t cookie; + xcb_get_geometry_reply_t *reply; + + cookie = xcb_get_geometry(c, window); + /* ... do other work here if possible ... */ + if ((reply = xcb_get_geometry_reply(c, cookie, NULL))) { + printf("This window is at %d, %d\\n", reply->x, reply->y); + } + free(reply); +} + ]]></example> + <field name="drawable"><![CDATA[ +The drawable (`Window` or `Pixmap`) of which the geometry will be received. + ]]></field> + <error type="Drawable"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="program" name="xwininfo" /> + </doc> </request> <request name="QueryTree" opcode="15"> @@ -979,7 +1849,51 @@ authorization from the authors. <list type="WINDOW" name="children"> <fieldref>children_len</fieldref> </list> + <doc> + <field name="root"><![CDATA[ +The root window of `window`. + ]]></field> + <field name="parent"><![CDATA[ +The parent window of `window`. + ]]></field> + <field name="children_len"><![CDATA[ +The number of child windows. + ]]></field> + </doc> </reply> + <doc> + <brief>query the window tree</brief> + <description><![CDATA[ +Gets the root window ID, parent window ID and list of children windows for the +specified `window`. The children are listed in bottom-to-top stacking order. + ]]></description> + <example><![CDATA[ +/* + * Displays the root, parent and children of the specified window. + * + */ +void my_example(xcb_connection *conn, xcb_window_t window) { + xcb_query_tree_cookie_t cookie; + xcb_query_tree_reply_t *reply; + + cookie = xcb_query_tree(conn, window); + if ((reply = xcb_query_tree_reply(conn, cookie, NULL))) { + printf("root = 0x%08x\\n", reply->root); + printf("parent = 0x%08x\\n", reply->parent); + + xcb_window_t *children = xcb_query_tree_children(reply); + for (int i = 0; i < xcb_query_tree_children_length(reply); i++) + printf("child window = 0x%08x\\n", children[i]); + + free(reply); + } +} + ]]></example> + <field name="window"><![CDATA[ +The `window` to query. + ]]></field> + <see type="program" name="xwininfo" /> + </doc> </request> <request name="InternAtom" opcode="16"> @@ -993,6 +1907,53 @@ authorization from the authors. <pad bytes="1" /> <field type="ATOM" name="atom" altenum="Atom" /> </reply> + <doc> + <brief>Get atom identifier by name</brief> + <description><![CDATA[ +Retrieves the identifier (xcb_atom_t TODO) for the atom with the specified +name. Atoms are used in protocols like EWMH, for example to store window titles +(`_NET_WM_NAME` atom) as property of a window. + +If `only_if_exists` is 0, the atom will be created if it does not already exist. +If `only_if_exists` is 1, `XCB_ATOM_NONE` will be returned if the atom does +not yet exist. + ]]></description> + <example><![CDATA[ +/* + * Resolves the _NET_WM_NAME atom. + * + */ +void my_example(xcb_connection *c) { + xcb_intern_atom_cookie_t cookie; + xcb_intern_atom_reply_t *reply; + + cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME"); + /* ... do other work here if possible ... */ + if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) { + printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); + free(reply); + } +} + ]]></example> + <field name="name_len"><![CDATA[ +The length of the following `name`. + ]]></field> + <field name="name"><![CDATA[ +The name of the atom. + ]]></field> + <field name="only_if_exists"><![CDATA[ +Return a valid atom id only if the atom already exists. + ]]></field> + <error type="Alloc"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +A value other than 0 or 1 was specified for `only_if_exists`. + ]]></error> + <see type="program" name="xlsatoms" /> + <see type="request" name="GetAtomName" /> + </doc> + </request> <request name="GetAtomName" opcode="17"> @@ -1012,6 +1973,21 @@ authorization from the authors. <item name="Replace"><value>0</value></item> <item name="Prepend"><value>1</value></item> <item name="Append"> <value>2</value></item> + <doc> + <field name="Replace"><![CDATA[ +Discard the previous property value and store the new data. + ]]></field> + <field name="Prepend"><![CDATA[ +Insert the new data before the beginning of existing data. The `format` must +match existing property value. If the property is undefined, it is treated as +defined with the correct type and format with zero-length data. + ]]></field> + <field name="Append"><![CDATA[ +Insert the new data after the beginning of existing data. The `format` must +match existing property value. If the property is undefined, it is treated as +defined with the correct type and format with zero-length data. + ]]></field> + </doc> </enum> <request name="ChangeProperty" opcode="18"> @@ -1031,6 +2007,71 @@ authorization from the authors. <value>8</value> </op> </list> + <doc> + <brief>Changes a window property</brief> + <description><![CDATA[ +Sets or updates a property on the specified `window`. Properties are for +example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`). +Protocols such as EWMH also use properties - for example EWMH defines the +window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property. + ]]></description> + <example><![CDATA[ +/* + * Sets the WM_NAME property of the window to "XCB Example". + * + */ +void my_example(xcb_connection *conn, xcb_window_t window) { + xcb_change_property(conn, + XCB_PROP_MODE_REPLACE, + window, + XCB_ATOM_WM_NAME, + XCB_ATOM_STRING, + 8, + strlen("XCB Example"), + "XCB Example"); + xcb_flush(conn); +} + ]]></example> + <field name="window"><![CDATA[ +The window whose property you want to change. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="mode" /> + <field name="property"><![CDATA[ +The property you want to change (an atom). + ]]></field> + <field name="type"><![CDATA[ +The type of the property you want to change (an atom). + ]]></field> + <field name="format"><![CDATA[ +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. + ]]></field> + <field name="data_len"><![CDATA[ +Specifies the number of elements (see `format`). + ]]></field> + <field name="data"><![CDATA[ +The property data. + ]]></field> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <error type="Atom"><![CDATA[ +`property` or `type` do not refer to a valid atom. + ]]></error> + <error type="Alloc"><![CDATA[ +The X server could not store the property (no memory?). + ]]></error> + <see type="request" name="InternAtom" /> + <see type="program" name="xprop" /> + </doc> </request> <request name="DeleteProperty" opcode="19"> @@ -1057,15 +2098,110 @@ authorization from the authors. <field type="CARD32" name="value_len" /> <pad bytes="12" /> <list type="void" name="value"> - <op op="*"> - <fieldref>value_len</fieldref> - <op op="/"> - <fieldref>format</fieldref> - <value>8</value> - </op> - </op> + <op op="*"> + <fieldref>value_len</fieldref> + <op op="/"> + <fieldref>format</fieldref> + <value>8</value> + </op> + </op> </list> + <doc> + <field name="format"><![CDATA[ +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. + ]]></field> + <field name="type"><![CDATA[ +The actual type of the property (an atom). + ]]></field> + <field name="bytes_after"><![CDATA[ +The number of bytes remaining to be read in the property if a partial read was +performed. + ]]></field> + <field name="value_len"><![CDATA[ +The length of value. You should use the corresponding accessor instead of this +field. + ]]></field> + </doc> </reply> + <doc> + <brief>Gets a window property</brief> + <description><![CDATA[ +Gets the specified `property` from the specified `window`. Properties are for +example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`). +Protocols such as EWMH also use properties - for example EWMH defines the +window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property. + +TODO: talk about `type` + +TODO: talk about `delete` + +TODO: talk about the offset/length thing. what's a valid use case? + ]]></description> + <example><![CDATA[ +/* + * 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); +} + ]]></example> + <field name="window"><![CDATA[ +The window whose property you want to get. + ]]></field> + <field name="delete"><![CDATA[ +Whether the property should actually be deleted. For deleting a property, the +specified `type` has to match the actual property type. + ]]></field> + <field name="property"><![CDATA[ +The property you want to get (an atom). + ]]></field> + <field name="type"><![CDATA[ +The type of the property you want to get (an atom). + ]]></field> + <field name="long_offset"><![CDATA[ +Specifies the offset (in 32-bit multiples) in the specified property where the +data is to be retrieved. + ]]></field> + <field name="long_length"><![CDATA[ +Specifies how many 32-bit multiples of data should be retrieved (e.g. if you +set `long_length` to 4, you will receive 16 bytes of data). + ]]></field> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <error type="Atom"><![CDATA[ +`property` or `type` do not refer to a valid atom. + ]]></error> + <error type="Value"><![CDATA[ +The specified `long_offset` is beyond the actual property length (e.g. the +property has a length of 3 bytes and you are setting `long_offset` to 1, +resulting in a byte offset of 4). + ]]></error> + <see type="request" name="InternAtom" /> + <see type="program" name="xprop" /> + </doc> </request> <request name="ListProperties" opcode="21"> @@ -1086,6 +2222,38 @@ authorization from the authors. <field type="WINDOW" name="owner" altenum="Window" /> <field type="ATOM" name="selection" /> <field type="TIMESTAMP" name="time" altenum="Time" /> + <doc> + <brief>Sets the owner of a selection</brief> + <description><![CDATA[ +Makes `window` the owner of the selection `selection` and updates the +last-change time of the specified selection. + +TODO: briefly explain what a selection is. + ]]></description> + <field name="selection"><![CDATA[ +The selection. + ]]></field> + <field name="owner"><![CDATA[ +The new owner of the selection. + +The special value `XCB_NONE` means that the selection will have no owner. + ]]></field> + <field name="time"><![CDATA[ +Timestamp to avoid race conditions when running X over the network. + +The selection will not be changed if `time` is earlier than the current +last-change time of the `selection` or is later than the current X server time. +Otherwise, the last-change time is set to the specified time. + +The special value `XCB_CURRENT_TIME` will be replaced with the current server +time. + ]]></field> + <error type="Atom"><![CDATA[ +`selection` does not refer to a valid atom. + ]]></error> + <see type="request" name="SetSelectionOwner" /> + </doc> + </request> <request name="GetSelectionOwner" opcode="23"> @@ -1094,7 +2262,27 @@ authorization from the authors. <reply> <pad bytes="1" /> <field type="WINDOW" name="owner" altenum="Window" /> + <doc> + <field name="owner"><![CDATA[ +The current selection owner window. + ]]></field> + </doc> </reply> + <doc> + <brief>Gets the owner of a selection</brief> + <description><![CDATA[ +Gets the owner of the specified selection. + +TODO: briefly explain what a selection is. + ]]></description> + <field name="selection"><![CDATA[ +The selection. + ]]></field> + <error type="Atom"><![CDATA[ +`selection` does not refer to a valid atom. + ]]></error> + <see type="request" name="SetSelectionOwner" /> + </doc> </request> <request name="ConvertSelection" opcode="24"> @@ -1116,11 +2304,97 @@ authorization from the authors. <field type="WINDOW" name="destination" altenum="SendEventDest" /> <field type="CARD32" name="event_mask" mask="EventMask" /> <list type="char" name="event"><value>32</value></list> + <doc> + <brief>send an event</brief> + <description><![CDATA[ +Identifies the `destination` window, determines which clients should receive +the specified event and ignores any active grabs. + +The `event` must be one of the core events or an event defined by an extension, +so that the X server can correctly byte-swap the contents as necessary. The +contents of `event` are otherwise unaltered and unchecked except for the +`send_event` field which is forced to 'true'. + ]]></description> + <example><![CDATA[ +/* + * Tell the given window that it was configured to a size of 800x600 pixels. + * + */ +void my_example(xcb_connection_t *conn, xcb_window_t window) { + /* Every X11 event is 32 bytes long. Therefore, XCB will copy 32 bytes. + * In order to properly initialize these bytes, we allocate 32 bytes even + * though we only need less for an xcb_configure_notify_event_t */ + xcb_configure_notify_event_t *event = calloc(32, 1); + + event->event = window; + event->window = window; + event->response_type = XCB_CONFIGURE_NOTIFY; + + event->x = 0; + event->y = 0; + event->width = 800; + event->height = 600; + + event->border_width = 0; + event->above_sibling = XCB_NONE; + event->override_redirect = false; + + xcb_send_event(conn, false, window, XCB_EVENT_MASK_STRUCTURE_NOTIFY, + (char*)event); + xcb_flush(conn); + free(event); +} + ]]></example> + <field name="destination"><![CDATA[ +The window to send this event to. Every client which selects any event within +`event_mask` on `destination` will get the event. + +The special value `XCB_SEND_EVENT_DEST_POINTER_WINDOW` refers to the window +that contains the mouse pointer. + +The special value `XCB_SEND_EVENT_DEST_ITEM_FOCUS` refers to the window which +has the keyboard focus. + ]]></field> + <field name="event_mask"><![CDATA[ +Event_mask for determining which clients should receive the specified event. +See `destination` and `propagate`. + ]]></field> + <field name="propagate"><![CDATA[ +If `propagate` is true and no clients have selected any event on `destination`, +the destination is replaced with the closest ancestor of `destination` for +which some client has selected a type in `event_mask` and for which no +intervening window has that type in its do-not-propagate-mask. If no such +window exists or if the window is an ancestor of the focus window and +`InputFocus` was originally specified as the destination, the event is not sent +to any clients. Otherwise, the event is reported to every client selecting on +the final destination any of the types specified in `event_mask`. + ]]></field> + <field name="event"><![CDATA[ +The event to send to the specified `destination`. + ]]></field> + <error type="Window"><![CDATA[ +The specified `destination` window does not exist. + ]]></error> + <error type="Value"><![CDATA[ +The given `event` is neither a core event nor an event defined by an extension. + ]]></error> + <see type="event" name="ConfigureNotify" /> + </doc> </request> <enum name="GrabMode"> <item name="Sync"> <value>0</value></item> <item name="Async"><value>1</value></item> + <doc> + <field name="Sync"><![CDATA[ +The state of the keyboard appears to freeze: No further keyboard events are +generated by the server until the grabbing client issues a releasing +`AllowEvents` request or until the keyboard grab is released. + ]]></field> + <field name="Async"><![CDATA[ +Keyboard event processing continues normally. + ]]></field> + </doc> </enum> <enum name="GrabStatus"> @@ -1147,11 +2421,118 @@ authorization from the authors. <reply> <field type="BYTE" name="status" enum="GrabStatus" /> </reply> + <doc> + <brief>Grab the pointer</brief> + <description><![CDATA[ +Actively grabs control of the pointer. Further pointer events are reported only to the grabbing client. Overrides any active pointer grab by this client. + + ]]></description> + <example><![CDATA[ +/* + * Grabs the pointer actively + * + */ +void my_example(xcb_connection *conn, xcb_screen_t *screen, xcb_cursor_t cursor) { + xcb_grab_pointer_cookie_t cookie; + xcb_grab_pointer_reply_t *reply; + + cookie = xcb_grab_pointer( + conn, + false, /* get all pointer events specified by the following mask */ + screen->root, /* grab the root window */ + XCB_NONE, /* which events to let through */ + XCB_GRAB_MODE_ASYNC, /* pointer events should continue as normal */ + XCB_GRAB_MODE_ASYNC, /* keyboard mode */ + XCB_NONE, /* confine_to = in which window should the cursor stay */ + cursor, /* we change the cursor to whatever the user wanted */ + XCB_CURRENT_TIME + ); + + if ((reply = xcb_grab_pointer_reply(conn, cookie, NULL))) { + if (reply->status == XCB_GRAB_STATUS_SUCCESS) + printf("successfully grabbed the pointer\\n"); + free(preply); + } +} + ]]></example> + <field name="event_mask"><![CDATA[ +Specifies which pointer events are reported to the client. + +TODO: which values? + ]]></field> + <field name="confine_to"><![CDATA[ +Specifies the window to confine the pointer in (the user will not be able to +move the pointer out of that window). + +The special value `XCB_NONE` means don't confine the pointer. + ]]></field> + <field name="cursor"><![CDATA[ +Specifies the cursor that should be displayed or `XCB_NONE` to not change the +cursor. + ]]></field> + <field name="owner_events"><![CDATA[ +If 1, the `grab_window` will still get the pointer events. If 0, events are not +reported to the `grab_window`. + ]]></field> + <field name="grab_window"><![CDATA[ +Specifies the window on which the pointer should be grabbed. + ]]></field> + <field name="time"><![CDATA[ +The time argument allows you to avoid certain circumstances that come up if +applications take a long time to respond or if there are long network delays. +Consider a situation where you have two applications, both of which normally +grab the pointer when clicked on. If both applications specify the timestamp +from the event, the second application may wake up faster and successfully grab +the pointer before the first application. The first application then will get +an indication that the other application grabbed the pointer before its request +was processed. + +The special value `XCB_CURRENT_TIME` will be replaced with the current server +time. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="pointer_mode" /> + <field name="keyboard_mode" /> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + + <see type="request" name="GrabKeyboard" /> + </doc> </request> <request name="UngrabPointer" opcode="27"> <pad bytes="1" /> <field type="TIMESTAMP" name="time" altenum="Time" /> + <doc> + <brief>release the pointer</brief> + <description><![CDATA[ +Releases the pointer and any queued events if you actively grabbed the pointer +before using `xcb_grab_pointer`, `xcb_grab_button` or within a normal button +press. + +EnterNotify and LeaveNotify events are generated. + ]]></description> + <field name="time"><![CDATA[ +Timestamp to avoid race conditions when running X over the network. + +The pointer will not be released if `time` is earlier than the +last-pointer-grab time or later than the current X server time. + ]]></field> + <field name="name_len"><![CDATA[ +Length (in bytes) of `name`. + ]]></field> + <field name="name"><![CDATA[ +A pattern describing an X core font. + ]]></field> + <see type="request" name="GrabPointer" /> + <see type="request" name="GrabButton" /> + <see type="event" name="EnterNotify" /> + <see type="event" name="LeaveNotify" /> + </doc> </request> <enum name="ButtonIndex"> @@ -1161,6 +2542,26 @@ authorization from the authors. <item name="3"> <value>3</value></item> <item name="4"> <value>4</value></item> <item name="5"> <value>5</value></item> + <doc> + <field name="Any"><![CDATA[ +Any of the following (or none): + ]]></field> + <field name="1"><![CDATA[ +The left mouse button. + ]]></field> + <field name="2"><![CDATA[ +The right mouse button. + ]]></field> + <field name="3"><![CDATA[ +The middle mouse button. + ]]></field> + <field name="4"><![CDATA[ +Scroll wheel. TODO: direction? + ]]></field> + <field name="5"><![CDATA[ +Scroll wheel. TODO: direction? + ]]></field> + </doc> </enum> <request name="GrabButton" opcode="28"> @@ -1174,6 +2575,92 @@ authorization from the authors. <field type="CARD8" name="button" enum="ButtonIndex" /> <pad bytes="1" /> <field type="CARD16" name="modifiers" mask="ModMask" /> + <doc> + <brief>Grab pointer button(s)</brief> + <description><![CDATA[ +This request establishes a passive grab. The pointer is actively grabbed as +described in GrabPointer, the last-pointer-grab time is set to the time at +which the button was pressed (as transmitted in the ButtonPress event), and the +ButtonPress event is reported if all of the following conditions are true: + +The pointer is not grabbed and the specified button is logically pressed when +the specified modifier keys are logically down, and no other buttons or +modifier keys are logically down. + +The grab-window contains the pointer. + +The confine-to window (if any) is viewable. + +A passive grab on the same button/key combination does not exist on any +ancestor of grab-window. + +The interpretation of the remaining arguments is the same as for GrabPointer. +The active grab is terminated automatically when the logical state of the +pointer has all buttons released, independent of the logical state of modifier +keys. Note that the logical state of a device (as seen by means of the +protocol) may lag the physical state if device event processing is frozen. This +request overrides all previous passive grabs by the same client on the same +button/key combinations on the same window. A modifier of AnyModifier is +equivalent to issuing the request for all possible modifier combinations +(including the combination of no modifiers). It is not required that all +specified modifiers have currently assigned keycodes. A button of AnyButton is +equivalent to issuing the request for all possible buttons. Otherwise, it is +not required that the button specified currently be assigned to a physical +button. + +An Access error is generated if some other client has already issued a +GrabButton request with the same button/key combination on the same window. +When using AnyModifier or AnyButton, the request fails completely (no grabs are +established), and an Access error is generated if there is a conflicting grab +for any combination. The request has no effect on an active grab. + + ]]></description> + <field name="owner_events"><![CDATA[ +If 1, the `grab_window` will still get the pointer events. If 0, events are not +reported to the `grab_window`. + ]]></field> + <field name="grab_window"><![CDATA[ +Specifies the window on which the pointer should be grabbed. + ]]></field> + <field name="event_mask"><![CDATA[ +Specifies which pointer events are reported to the client. + +TODO: which values? + ]]></field> + <field name="confine_to"><![CDATA[ +Specifies the window to confine the pointer in (the user will not be able to +move the pointer out of that window). + +The special value `XCB_NONE` means don't confine the pointer. + ]]></field> + <field name="cursor"><![CDATA[ +Specifies the cursor that should be displayed or `XCB_NONE` to not change the +cursor. + ]]></field> + <field name="modifiers"><![CDATA[ +The modifiers to grab. + +Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all +possible modifier combinations. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="pointer_mode" /> + <field name="keyboard_mode" /> + <field name="button" /> + <error type="Access"><![CDATA[ +Another client has already issued a GrabButton with the same button/key +combination on the same window. + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Cursor"><![CDATA[ +The specified `cursor` does not exist. + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + </doc> </request> <request name="UngrabButton" opcode="29"> @@ -1201,6 +2688,70 @@ authorization from the authors. <reply> <field type="BYTE" name="status" enum="GrabStatus" /> </reply> + <doc> + <brief>Grab the keyboard</brief> + <description><![CDATA[ +Actively grabs control of the keyboard and generates FocusIn and FocusOut +events. Further key events are reported only to the grabbing client. + +Any active keyboard grab by this client is overridden. If the keyboard is +actively grabbed by some other client, `AlreadyGrabbed` is returned. If +`grab_window` is not viewable, `GrabNotViewable` is returned. If the keyboard +is frozen by an active grab of another client, `GrabFrozen` is returned. If the +specified `time` is earlier than the last-keyboard-grab time or later than the +current X server time, `GrabInvalidTime` is returned. Otherwise, the +last-keyboard-grab time is set to the specified time. + ]]></description> + <example><![CDATA[ +/* + * Grabs the keyboard actively + * + */ +void my_example(xcb_connection *conn, xcb_screen_t *screen) { + xcb_grab_keyboard_cookie_t cookie; + xcb_grab_keyboard_reply_t *reply; + + cookie = xcb_grab_keyboard( + conn, + true, /* report events */ + screen->root, /* grab the root window */ + XCB_CURRENT_TIME, + XCB_GRAB_MODE_ASYNC, /* process events as normal, do not require sync */ + XCB_GRAB_MODE_ASYNC + ); + + if ((reply = xcb_grab_keyboard_reply(conn, cookie, NULL))) { + if (reply->status == XCB_GRAB_STATUS_SUCCESS) + printf("successfully grabbed the keyboard\\n"); + + free(reply); + } +} + ]]></example> + <field name="owner_events"><![CDATA[ +If 1, the `grab_window` will still get the pointer events. If 0, events are not +reported to the `grab_window`. + ]]></field> + <field name="grab_window"><![CDATA[ +Specifies the window on which the pointer should be grabbed. + ]]></field> + <field name="time"><![CDATA[ +Timestamp to avoid race conditions when running X over the network. + +The special value `XCB_CURRENT_TIME` will be replaced with the current server +time. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="pointer_mode" /> + <field name="keyboard_mode" /> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <see type="request" name="GrabPointer" /> + </doc> </request> <request name="UngrabKeyboard" opcode="32"> @@ -1221,6 +2772,78 @@ authorization from the authors. <field type="CARD8" name="pointer_mode" enum="GrabMode" /> <field type="CARD8" name="keyboard_mode" enum="GrabMode" /> <pad bytes="3" /> + <doc> + <brief>Grab keyboard key(s)</brief> + <description><![CDATA[ +Establishes a passive grab on the keyboard. In the future, the keyboard is +actively grabbed (as for `GrabKeyboard`), the last-keyboard-grab time is set to +the time at which the key was pressed (as transmitted in the KeyPress event), +and the KeyPress event is reported if all of the following conditions are true: + +The keyboard is not grabbed and the specified key (which can itself be a +modifier key) is logically pressed when the specified modifier keys are +logically down, and no other modifier keys are logically down. + +Either the grab_window is an ancestor of (or is) the focus window, or the +grab_window is a descendant of the focus window and contains the pointer. + +A passive grab on the same key combination does not exist on any ancestor of +grab_window. + +The interpretation of the remaining arguments is as for XGrabKeyboard. The active grab is terminated +automatically when the logical state of the keyboard has the specified key released (independent of the +logical state of the modifier keys), at which point a KeyRelease event is reported to the grabbing window. + +Note that the logical state of a device (as seen by client applications) may lag the physical state if +device event processing is frozen. + +A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified +have currently assigned KeyCodes. A keycode argument of AnyKey is equivalent to issuing the request for +all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_keycode +and max_keycode in the connection setup, or a BadValue error results. + +If some other client has issued a XGrabKey with the same key combination on the same window, a BadAccess +error results. When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error +results (no grabs are established) if there is a conflicting grab for any combination. + + ]]></description> + <field name="owner_events"><![CDATA[ +If 1, the `grab_window` will still get the pointer events. If 0, events are not +reported to the `grab_window`. + ]]></field> + <field name="grab_window"><![CDATA[ +Specifies the window on which the pointer should be grabbed. + ]]></field> + <field name="key"><![CDATA[ +The keycode of the key to grab. + +The special value `XCB_GRAB_ANY` means grab any key. + ]]></field> + <field name="cursor"><![CDATA[ +Specifies the cursor that should be displayed or `XCB_NONE` to not change the +cursor. + ]]></field> + <field name="modifiers"><![CDATA[ +The modifiers to grab. + +Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all +possible modifier combinations. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="pointer_mode" /> + <field name="keyboard_mode" /> + <error type="Access"><![CDATA[ +Another client has already issued a GrabKey with the same button/key +combination on the same window. + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + <see type="request" name="GrabKeyboard" /> + </doc> </request> <request name="UngrabKey" opcode="34"> @@ -1228,6 +2851,35 @@ authorization from the authors. <field type="WINDOW" name="grab_window" /> <field type="CARD16" name="modifiers" mask="ModMask" /> <pad bytes="2" /> + <doc> + <brief>release a key combination</brief> + <description><![CDATA[ +Releases the key combination on `grab_window` if you grabbed it using +`xcb_grab_key` before. + ]]></description> + <field name="key"><![CDATA[ +The keycode of the specified key combination. + +Using the special value `XCB_GRAB_ANY` means releasing all possible key codes. + ]]></field> + <field name="grab_window"><![CDATA[ +The window on which the grabbed key combination will be released. + ]]></field> + <field name="modifiers"><![CDATA[ +The modifiers of the specified key combination. + +Using the special value `XCB_MOD_MASK_ANY` means releasing the key combination +with every possible modifier combination. + ]]></field> + <error type="Window"><![CDATA[ +The specified `grab_window` does not exist. + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="request" name="GrabKey" /> + <see type="program" name="xev" /> + </doc> </request> <enum name="Allow"> @@ -1239,11 +2891,106 @@ authorization from the authors. <item name="ReplayKeyboard"><value>5</value></item> <item name="AsyncBoth"> <value>6</value></item> <item name="SyncBoth"> <value>7</value></item> + <doc> + <field name="AsyncPointer"><![CDATA[ +For AsyncPointer, if the pointer is frozen by the client, pointer event +processing continues normally. If the pointer is frozen twice by the client on +behalf of two separate grabs, AsyncPointer thaws for both. AsyncPointer has no +effect if the pointer is not frozen by the client, but the pointer need not be +grabbed by the client. + +TODO: rewrite this in more understandable terms. + ]]></field> + <field name="SyncPointer"><![CDATA[ +For SyncPointer, if the pointer is frozen and actively grabbed by the client, +pointer event processing continues normally until the next ButtonPress or +ButtonRelease event is reported to the client, at which time the pointer again +appears to freeze. However, if the reported event causes the pointer grab to be +released, then the pointer does not freeze. SyncPointer has no effect if the +pointer is not frozen by the client or if the pointer is not grabbed by the +client. + ]]></field> + <field name="ReplayPointer"><![CDATA[ +For ReplayPointer, if the pointer is actively grabbed by the client and is +frozen as the result of an event having been sent to the client (either from +the activation of a GrabButton or from a previous AllowEvents with mode +SyncPointer but not from a GrabPointer), then the pointer grab is released and +that event is completely reprocessed, this time ignoring any passive grabs at +or above (towards the root) the grab-window of the grab just released. The +request has no effect if the pointer is not grabbed by the client or if the +pointer is not frozen as the result of an event. + ]]></field> + <field name="AsyncKeyboard"><![CDATA[ +For AsyncKeyboard, if the keyboard is frozen by the client, keyboard event +processing continues normally. If the keyboard is frozen twice by the client on +behalf of two separate grabs, AsyncKeyboard thaws for both. AsyncKeyboard has +no effect if the keyboard is not frozen by the client, but the keyboard need +not be grabbed by the client. + ]]></field> + <field name="SyncKeyboard"><![CDATA[ +For SyncKeyboard, if the keyboard is frozen and actively grabbed by the client, +keyboard event processing continues normally until the next KeyPress or +KeyRelease event is reported to the client, at which time the keyboard again +appears to freeze. However, if the reported event causes the keyboard grab to +be released, then the keyboard does not freeze. SyncKeyboard has no effect if +the keyboard is not frozen by the client or if the keyboard is not grabbed by +the client. + ]]></field> + <field name="ReplayKeyboard"><![CDATA[ +For ReplayKeyboard, if the keyboard is actively grabbed by the client and is +frozen as the result of an event having been sent to the client (either from +the activation of a GrabKey or from a previous AllowEvents with mode +SyncKeyboard but not from a GrabKeyboard), then the keyboard grab is released +and that event is completely reprocessed, this time ignoring any passive grabs +at or above (towards the root) the grab-window of the grab just released. The +request has no effect if the keyboard is not grabbed by the client or if the +keyboard is not frozen as the result of an event. + ]]></field> + <field name="SyncBoth"><![CDATA[ +For SyncBoth, if both pointer and keyboard are frozen by the client, event +processing (for both devices) continues normally until the next ButtonPress, +ButtonRelease, KeyPress, or KeyRelease event is reported to the client for a +grabbed device (button event for the pointer, key event for the keyboard), at +which time the devices again appear to freeze. However, if the reported event +causes the grab to be released, then the devices do not freeze (but if the +other device is still grabbed, then a subsequent event for it will still cause +both devices to freeze). SyncBoth has no effect unless both pointer and +keyboard are frozen by the client. If the pointer or keyboard is frozen twice +by the client on behalf of two separate grabs, SyncBoth thaws for both (but a +subsequent freeze for SyncBoth will only freeze each device once). + ]]></field> + <field name="AsyncBoth"><![CDATA[ +For AsyncBoth, if the pointer and the keyboard are frozen by the client, event +processing for both devices continues normally. If a device is frozen twice by +the client on behalf of two separate grabs, AsyncBoth thaws for both. AsyncBoth +has no effect unless both pointer and keyboard are frozen by the client. + ]]></field> + </doc> </enum> <request name="AllowEvents" opcode="35"> <field type="CARD8" name="mode" enum="Allow" /> <field type="TIMESTAMP" name="time" altenum="Time" /> + <doc> + <brief>release queued events</brief> + <description><![CDATA[ +Releases queued events if the client has caused a device (pointer/keyboard) to +freeze due to grabbing it actively. This request has no effect if `time` is +earlier than the last-grab time of the most recent active grab for this client +or if `time` is later than the current X server time. + ]]></description> + <!-- the enum doc is sufficient. --> + <field name="mode" /> + <field name="time"><![CDATA[ +Timestamp to avoid race conditions when running X over the network. + +The special value `XCB_CURRENT_TIME` will be replaced with the current server +time. + ]]></field> + <error type="Value"><![CDATA[ +You specified an invalid `mode`. + ]]></error> + </doc> </request> <request name="GrabServer" opcode="36" /> @@ -1263,7 +3010,56 @@ authorization from the authors. <field type="INT16" name="win_y" /> <field type="CARD16" name="mask" mask="KeyButMask" /> <pad bytes="2" /> + <doc> + <field name="same_screen"><![CDATA[ +If `same_screen` is False, then the pointer is not on the same screen as the +argument window, `child` is None, and `win_x` and `win_y` are zero. If +`same_screen` is True, then `win_x` and `win_y` are the pointer coordinates +relative to the argument window's origin, and child is the child containing the +pointer, if any. + ]]></field> + <field name="root"><![CDATA[ +The root window the pointer is logically on. + ]]></field> + <field name="child"><![CDATA[ +The child window containing the pointer, if any, if `same_screen` is true. If +`same_screen` is false, `XCB_NONE` is returned. + ]]></field> + <field name="root_x"><![CDATA[ +The pointer X position, relative to `root`. + ]]></field> + <field name="root_y"><![CDATA[ +The pointer Y position, relative to `root`. + ]]></field> + <field name="win_x"><![CDATA[ +The pointer X coordinate, relative to `child`, if `same_screen` is true. Zero +otherwise. + ]]></field> + <field name="win_y"><![CDATA[ +The pointer Y coordinate, relative to `child`, if `same_screen` is true. Zero +otherwise. + ]]></field> + <field name="mask"><![CDATA[ +The current logical state of the modifier keys and the buttons. Note that the +logical state of a device (as seen by means of the protocol) may lag the +physical state if device event processing is frozen. + ]]></field> + </doc> </reply> + <doc> + <brief>get pointer coordinates</brief> + <description><![CDATA[ +Gets the root window the pointer is logically on and the pointer coordinates +relative to the root window's origin. + ]]></description> + <field name="window"><![CDATA[ +A window to check if the pointer is on the same screen as `window` (see the +`same_screen` field in the reply). + ]]></field> + <error type="Window"><![CDATA[ +The specified `window` does not exist. + ]]></error> + </doc> </request> <struct name="TIMECOORD"> @@ -1311,6 +3107,38 @@ authorization from the authors. <field type="CARD16" name="src_height" /> <field type="INT16" name="dst_x" /> <field type="INT16" name="dst_y" /> + <doc> + <brief>move mouse pointer</brief> + <description><![CDATA[ +Moves the mouse pointer to the specified position. + +If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the +pointer is inside `src_window` and within the rectangle specified by (`src_x`, +`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to +`src_window`. + +If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the +offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is +`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`) +relative to the current position of the pointer. + ]]></description> + <field name="src_window"><![CDATA[ +If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the +pointer is inside `src_window` and within the rectangle specified by (`src_x`, +`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to +`src_window`. + ]]></field> + <field name="dst_window"><![CDATA[ +If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the +offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is +`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`) +relative to the current position of the pointer. + ]]></field> + <error type="Window"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="request" name="SetInputFocus" /> + </doc> </request> <!-- used for revert_to and focus --> @@ -1319,12 +3147,71 @@ authorization from the authors. <item name="PointerRoot"><value>1</value></item> <item name="Parent"> <value>2</value></item> <!-- revert_to only --> <item name="FollowKeyboard"><value>3</value></item> <!-- xinput extension only --> + <doc> + <field name="None"><![CDATA[ +The focus reverts to `XCB_NONE`, so no window will have the input focus. + ]]></field> + <field name="PointerRoot"><![CDATA[ +The focus reverts to `XCB_POINTER_ROOT` respectively. When the focus reverts, +FocusIn and FocusOut events are generated, but the last-focus-change time is +not changed. + ]]></field> + <field name="Parent"><![CDATA[ +The focus reverts to the parent (or closest viewable ancestor) and the new +revert_to value is `XCB_INPUT_FOCUS_NONE`. + ]]></field> + <field name="FollowKeyboard"><![CDATA[ +NOT YET DOCUMENTED. Only relevant for the xinput extension. + ]]></field> + </doc> </enum> <request name="SetInputFocus" opcode="42"> <field type="CARD8" name="revert_to" enum="InputFocus" /> <field type="WINDOW" name="focus" altenum="InputFocus" /> <field type="TIMESTAMP" name="time" altenum="Time" /> + <doc> + <brief>Sets input focus</brief> + <description><![CDATA[ +Changes the input focus and the last-focus-change time. If the specified `time` +is earlier than the current last-focus-change time, the request is ignored (to +avoid race conditions when running X over the network). + +A FocusIn and FocusOut event is generated when focus is changed. + ]]></description> + <field name="focus"><![CDATA[ +The window to focus. All keyboard events will be reported to this window. The +window must be viewable (TODO), or a `xcb_match_error_t` occurs (TODO). + +If `focus` is `XCB_NONE` (TODO), all keyboard events are +discarded until a new focus window is set. + +If `focus` is `XCB_POINTER_ROOT` (TODO), focus is on the root window of the +screen on which the pointer is on currently. + ]]></field> + <field name="time"><![CDATA[ +Timestamp to avoid race conditions when running X over the network. + +The special value `XCB_CURRENT_TIME` will be replaced with the current server +time. + ]]></field> + <field name="revert_to"><![CDATA[ +Specifies what happens when the `focus` window becomes unviewable (if `focus` +is neither `XCB_NONE` nor `XCB_POINTER_ROOT`). + ]]></field> + <error type="Window"><![CDATA[ +The specified `focus` window does not exist. + ]]></error> + <error type="Match"><![CDATA[ +The specified `focus` window is not viewable. + ]]></error> + <error type="Value"><![CDATA[ +TODO: Reasons? + ]]></error> + <see type="event" name="FocusIn" /> + <see type="event" name="FocusOut" /> + </doc> + </request> <request name="GetInputFocus" opcode="43"> @@ -1349,6 +3236,28 @@ authorization from the authors. <list type="char" name="name"> <fieldref>name_len</fieldref> </list> + <doc> + <brief>opens a font</brief> + <description><![CDATA[ +Opens any X core font matching the given `name` (for example "-misc-fixed-*"). + +Note that X core fonts are deprecated (but still supported) in favor of +client-side rendering using Xft. + ]]></description> + <field name="fid"><![CDATA[ +The ID with which you will refer to the font, created by `xcb_generate_id`. + ]]></field> + <field name="name_len"><![CDATA[ +Length (in bytes) of `name`. + ]]></field> + <field name="name"><![CDATA[ +A pattern describing an X core font. + ]]></field> + <error type="Name"><![CDATA[ +No font matches the given `name`. + ]]></error> + <see type="function" name="xcb_generate_id" /> + </doc> </request> <request name="CloseFont" opcode="46"> @@ -1401,7 +3310,48 @@ authorization from the authors. <list type="CHARINFO" name="char_infos"> <fieldref>char_infos_len</fieldref> </list> + <doc> + <field name="min_bounds"><![CDATA[ +minimum bounds over all existing char + ]]></field> + <field name="max_bounds"><![CDATA[ +maximum bounds over all existing char + ]]></field> + <field name="min_char_or_byte2"><![CDATA[ +first character + ]]></field> + <field name="max_char_or_byte2"><![CDATA[ +last character + ]]></field> + <field name="default_char"><![CDATA[ +char to print for undefined character + ]]></field> + <field name="properties_len"><![CDATA[ +how many properties there are + ]]></field> + <field name="all_chars_exist"><![CDATA[ +flag if all characters have nonzero size + ]]></field> + <field name="font_ascent"><![CDATA[ +baseline to top edge of raster + ]]></field> + <field name="font_descent"><![CDATA[ +baseline to bottom edge of raster + ]]></field> + <!-- enum doc is sufficient --> + <field name="draw_direction" /> + </doc> </reply> + <doc> + <brief>query font metrics</brief> + <description><![CDATA[ +Queries information associated with the font. + ]]></description> + <field name="font"><![CDATA[ +The fontable (Font or Graphics Context) to query. + ]]></field> + <!-- TODO: example --> + </doc> </request> <request name="QueryTextExtents" opcode="48"> @@ -1420,6 +3370,47 @@ authorization from the authors. <field type="INT32" name="overall_left" /> <field type="INT32" name="overall_right" /> </reply> + <doc> + <brief>get text extents</brief> + <description><![CDATA[ +Query text extents from the X11 server. This request returns the bounding box +of the specified 16-bit character string in the specified `font` or the font +contained in the specified graphics context. + +`font_ascent` is set to the maximum of the ascent metrics of all characters in +the string. `font_descent` is set to the maximum of the descent metrics. +`overall_width` is set to the sum of the character-width metrics of all +characters in the string. For each character in the string, let W be the sum of +the character-width metrics of all characters preceding it in the string. Let L +be the left-side-bearing metric of the character plus W. Let R be the +right-side-bearing metric of the character plus W. The lbearing member is set +to the minimum L of all characters in the string. The rbearing member is set to +the maximum R. + +For fonts defined with linear indexing rather than 2-byte matrix indexing, each +`xcb_char2b_t` structure is interpreted as a 16-bit number with byte1 as the +most significant byte. If the font has no defined default character, undefined +characters in the string are taken to have all zero metrics. + +Characters with all zero metrics are ignored. If the font has no defined +default_char, the undefined characters in the string are also ignored. + ]]></description> + <field name="font"><![CDATA[ +The `font` to calculate text extents in. You can also pass a graphics context. + ]]></field> + <field name="string_len"><![CDATA[ +The number of characters in `string`. + ]]></field> + <field name="string"><![CDATA[ +The text to get text extents for. + ]]></field> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + <error type="Font"><![CDATA[ +The specified `font` does not exist. + ]]></error> + </doc> </request> <struct name="STR"> @@ -1443,7 +3434,31 @@ authorization from the authors. <list type="STR" name="names"> <fieldref>names_len</fieldref> </list> + <doc> + <field name="names_len"><![CDATA[ +The number of font names. + ]]></field> + </doc> </reply> + <doc> + <brief>get matching font names</brief> + <description><![CDATA[ +Gets a list of available font names which match the given `pattern`. + ]]></description> + <field name="pattern_len"><![CDATA[ +The length (in bytes) of `pattern`. + ]]></field> + <field name="pattern"><![CDATA[ +A font pattern, for example "-misc-fixed-*". + +The asterisk (*) is a wildcard for any number of characters. The question mark +(?) is a wildcard for a single character. Use of uppercase or lowercase does +not matter. + ]]></field> + <field name="max_names"><![CDATA[ +The maximum number of fonts to be returned. + ]]></field> + </doc> </request> <request name="ListFontsWithInfo" opcode="50"> @@ -1476,7 +3491,66 @@ authorization from the authors. <list type="char" name="name"> <fieldref>name_len</fieldref> </list> + <doc> + <field name="name_len"><![CDATA[ +The number of matched font names. + ]]></field> + <field name="min_bounds"><![CDATA[ +minimum bounds over all existing char + ]]></field> + <field name="max_bounds"><![CDATA[ +maximum bounds over all existing char + ]]></field> + <field name="min_char_or_byte2"><![CDATA[ +first character + ]]></field> + <field name="max_char_or_byte2"><![CDATA[ +last character + ]]></field> + <field name="default_char"><![CDATA[ +char to print for undefined character + ]]></field> + <field name="properties_len"><![CDATA[ +how many properties there are + ]]></field> + <field name="all_chars_exist"><![CDATA[ +flag if all characters have nonzero size + ]]></field> + <field name="font_ascent"><![CDATA[ +baseline to top edge of raster + ]]></field> + <field name="font_descent"><![CDATA[ +baseline to bottom edge of raster + ]]></field> + <field name="replies_hint"><![CDATA[ +An indication of how many more fonts will be returned. This is only a hint and +may be larger or smaller than the number of fonts actually returned. A zero +value does not guarantee that no more fonts will be returned. + ]]></field> + <!-- enum doc is sufficient --> + <field name="draw_direction" /> + </doc> </reply> + <doc> + <brief>get matching font names and information</brief> + <description><![CDATA[ +Gets a list of available font names which match the given `pattern`. + ]]></description> + <field name="pattern_len"><![CDATA[ +The length (in bytes) of `pattern`. + ]]></field> + <field name="pattern"><![CDATA[ +A font pattern, for example "-misc-fixed-*". + +The asterisk (*) is a wildcard for any number of characters. The question mark +(?) is a wildcard for a single character. Use of uppercase or lowercase does +not matter. + ]]></field> + <field name="max_names"><![CDATA[ +The maximum number of fonts to be returned. + ]]></field> + </doc> + </request> <request name="SetFontPath" opcode="51"> @@ -1505,11 +3579,55 @@ authorization from the authors. <field type="DRAWABLE" name="drawable" /> <field type="CARD16" name="width" /> <field type="CARD16" name="height" /> + <doc> + <brief>Creates a pixmap</brief> + <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`. + ]]></description> + <field name="depth"><![CDATA[ +TODO + ]]></field> + <field name="pid"><![CDATA[ +The ID with which you will refer to the new pixmap, created by +`xcb_generate_id`. + ]]></field> + <field name="drawable"><![CDATA[ +Drawable to get the screen from. + ]]></field> + <field name="width"><![CDATA[ +The width of the new pixmap. + ]]></field> + <field name="height"><![CDATA[ +The height of the new pixmap. + ]]></field> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="Alloc"><![CDATA[ +The X server could not allocate the requested resources (no memory?). + ]]></error> + <see type="function" name="xcb_generate_id" /> + </doc> </request> <request name="FreePixmap" opcode="54"> <pad bytes="1" /> <field type="PIXMAP" name="pixmap" /> + <doc> + <brief>Destroys a pixmap</brief> + <description><![CDATA[ +Deletes the association between the pixmap ID and the pixmap. The pixmap +storage will be freed when there are no more references to it. + ]]></description> + <field name="pixmap"><![CDATA[The pixmap to destroy.]]></field> + <error type="Pixmap"><![CDATA[ +The specified pixmap does not exist. + ]]></error> + </doc> </request> <enum name="GC"> @@ -1536,6 +3654,154 @@ authorization from the authors. <item name="DashOffset"> <bit>20</bit></item> <item name="DashList"> <bit>21</bit></item> <item name="ArcMode"> <bit>22</bit></item> + <doc> + <field name="Function"><![CDATA[ +TODO: Refer to GX + ]]></field> + <field name="PlaneMask"><![CDATA[ +In graphics operations, given a source and destination pixel, the result is +computed bitwise on corresponding bits of the pixels; that is, a Boolean +operation is performed in each bit plane. The plane-mask restricts the +operation to a subset of planes, so the result is: + + ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) + ]]></field> + <field name="Foreground"><![CDATA[ +Foreground colorpixel. + ]]></field> + <field name="Background"><![CDATA[ +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. + ]]></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[ +The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill +requests (for example, PolyText8, PolyText16, PolyFillRectangle, FillPoly, and PolyFillArc) +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. + ]]></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. + ]]></field> + <field name="TileStippleOriginX"><![CDATA[ +TODO + ]]></field> + <field name="TileStippleOriginY"><![CDATA[ +TODO + ]]></field> + <field name="Font"><![CDATA[ +Which font to use for the `ImageText8` and `ImageText16` requests. + ]]></field> + <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. + ]]></field> + <field name="GraphicsExposures"><![CDATA[ +Whether ExposureEvents should be generated (1) or not (0). + +The default is 1. + ]]></field> + <field name="ClipOriginX"><![CDATA[ +TODO + ]]></field> + <field name="ClipOriginY"><![CDATA[ +TODO + ]]></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 +SetClipRectangles request. + ]]></field> + <field name="DashOffset"><![CDATA[ +TODO + ]]></field> + <field name="DashList"><![CDATA[ +TODO + ]]></field> + <field name="ArcMode"><![CDATA[ +TODO + ]]></field> + </doc> + </enum> <!-- GC Function values --> @@ -1606,6 +3872,39 @@ authorization from the authors. <valueparam value-mask-type="CARD32" value-mask-name="value_mask" value-list-name="value_list" /> + <doc> + <brief>Creates a graphics context</brief> + <description><![CDATA[ +Creates a graphics context. The graphics context can be used with any drawable +that has the same root and depth as the specified drawable. + ]]></description> + <field name="cid"><![CDATA[ +The ID with which you will refer to the graphics context, created by +`xcb_generate_id`. + ]]></field> + <field name="drawable"><![CDATA[ +Drawable to get the root/depth from. + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Font"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Pixmap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Alloc"><![CDATA[ +The X server could not allocate the requested resources (no memory?). + ]]></error> + <see type="function" name="xcb_generate_id" /> + </doc> </request> <request name="ChangeGC" opcode="56"> @@ -1614,6 +3913,62 @@ authorization from the authors. <valueparam value-mask-type="CARD32" value-mask-name="value_mask" value-list-name="value_list" /> + <doc> + <brief>change graphics context components</brief> + <description><![CDATA[ +Changes the components specified by `value_mask` for the specified graphics context. + ]]></description> + <example><![CDATA[ +/* + * Changes the foreground color component of the specified graphics context. + * + */ +void my_example(xcb_connection *conn, xcb_gcontext_t gc, uint32_t fg, uint32_t bg) { + /* C99 allows us to use a compact way of changing a single component: */ + xcb_change_gc(conn, gc, XCB_GC_FOREGROUND, (uint32_t[]){ fg }); + + /* The more explicit way. Beware that the order of values is important! */ + uint32_t mask = 0; + mask |= XCB_GC_FOREGROUND; + mask |= XCB_GC_BACKGROUND; + + uint32_t values[] = { + fg, + bg + }; + xcb_change_gc(conn, gc, mask, values); + xcb_flush(conn); +} + ]]></example> + <field name="gc"><![CDATA[ +The graphics context to change. + ]]></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. + ]]></field> + <error type="Font"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="GC"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Pixmap"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Alloc"><![CDATA[ +The X server could not allocate the requested resources (no memory?). + ]]></error> + </doc> </request> <request name="CopyGC" opcode="57"> @@ -1651,6 +4006,16 @@ authorization from the authors. <request name="FreeGC" opcode="60"> <pad bytes="1" /> <field type="GCONTEXT" name="gc" /> + <doc> + <brief>Destroys a graphics context</brief> + <description><![CDATA[ +Destroys the specified `gc` and all associated storage. + ]]></description> + <field name="gc"><![CDATA[The graphics context to destroy.]]></field> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + </doc> </request> <request name="ClearArea" opcode="61"> @@ -1673,6 +4038,48 @@ authorization from the authors. <field type="INT16" name="dst_y" /> <field type="CARD16" name="width" /> <field type="CARD16" name="height" /> + <doc> + <brief>copy areas</brief> + <description><![CDATA[ +Copies the specified rectangle from `src_drawable` to `dst_drawable`. + ]]></description> + <field name="dst_drawable"><![CDATA[ +The destination drawable (Window or Pixmap). + ]]></field> + <field name="src_drawable"><![CDATA[ +The source drawable (Window or Pixmap). + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + ]]></field> + <field name="src_x"><![CDATA[ +The source X coordinate. + ]]></field> + <field name="src_y"><![CDATA[ +The source Y coordinate. + ]]></field> + <field name="dst_x"><![CDATA[ +The destination X coordinate. + ]]></field> + <field name="dst_y"><![CDATA[ +The destination Y coordinate. + ]]></field> + <field name="width"><![CDATA[ +The width of the area to copy (in pixels). + ]]></field> + <field name="height"><![CDATA[ +The height of the area to copy (in pixels). + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + <error type="Match"><![CDATA[ +`src_drawable` has a different root or depth than `dst_drawable`. + ]]></error> + </doc> </request> <request name="CopyPlane" opcode="63"> @@ -1692,6 +4099,14 @@ authorization from the authors. <enum name="CoordMode"> <item name="Origin"> <value>0</value></item> <item name="Previous"><value>1</value></item> + <doc> + <field name="Origin"><![CDATA[ +Treats all coordinates as relative to the origin. + ]]></field> + <field name="Previous"><![CDATA[ +Treats all coordinates after the first as relative to the previous coordinate. + ]]></field> + </doc> </enum> <!-- combine-adjacent doesn't work for mode==Relative --> @@ -1707,6 +4122,56 @@ authorization from the authors. <field type="DRAWABLE" name="drawable" /> <field type="GCONTEXT" name="gc" /> <list type="POINT" name="points" /> + <doc> + <brief>draw lines</brief> + <description><![CDATA[ +Draws `points_len`-1 lines between each pair of points (point[i], point[i+1]) +in the `points` array. The lines are drawn in the order listed in the array. +They join correctly at all intermediate points, and if the first and last +points coincide, the first and last lines also join correctly. For any given +line, a pixel is not drawn more than once. If thin (zero line-width) lines +intersect, the intersecting pixels are drawn multiple times. If wide lines +intersect, the intersecting pixels are drawn only once, as though the entire +request were a single, filled shape. + ]]></description> + <example><![CDATA[ +/* + * Draw a straight line. + * + */ +void my_example(xcb_connection *conn, xcb_drawable_t drawable, xcb_gcontext_t gc) { + xcb_poly_line(conn, XCB_COORD_MODE_ORIGIN, drawable, gc, 2, + (xcb_point_t[]) { {10, 10}, {100, 10} }); + xcb_flush(conn); +} + ]]></example> + <field name="drawable"><![CDATA[ +The drawable to draw the line(s) on. + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + ]]></field> + <field name="points_len"><![CDATA[ +The number of `xcb_point_t` structures in `points`. + ]]></field> + <field name="points"><![CDATA[ +An array of points. + ]]></field> + <!-- the enum doc is sufficient. --> + <field name="coordinate_mode" /> + <error type="Drawable"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="GC"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <error type="Value"><![CDATA[ +TODO: reasons? + ]]></error> + </doc> </request> <struct name="SEGMENT"> @@ -1721,6 +4186,43 @@ authorization from the authors. <field type="DRAWABLE" name="drawable" /> <field type="GCONTEXT" name="gc" /> <list type="SEGMENT" name="segments" /> + <doc> + <brief>draw lines</brief> + <description><![CDATA[ +Draws multiple, unconnected lines. For each segment, a line is drawn between +(x1, y1) and (x2, y2). The lines are drawn in the order listed in the array of +`xcb_segment_t` structures and does not perform joining at coincident +endpoints. For any given line, a pixel is not drawn more than once. If lines +intersect, the intersecting pixels are drawn multiple times. + +TODO: include the xcb_segment_t data structure + +TODO: an example + ]]></description> + <field name="drawable"><![CDATA[ +A drawable (Window or Pixmap) to draw on. + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + +TODO: document which attributes of a gc are used + ]]></field> + <field name="segments_len"><![CDATA[ +The number of `xcb_segment_t` structures in `segments`. + ]]></field> + <field name="segments"><![CDATA[ +An array of `xcb_segment_t` structures. + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` does not exist. + ]]></error> + <error type="GC"><![CDATA[ +The specified `gc` does not exist. + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + </doc> </request> <request name="PolyRectangle" opcode="67" combine-adjacent="true"> @@ -1763,6 +4265,42 @@ authorization from the authors. <field type="DRAWABLE" name="drawable" /> <field type="GCONTEXT" name="gc" /> <list type="RECTANGLE" name="rectangles" /> + <doc> + <brief>Fills rectangles</brief> + <description><![CDATA[ +Fills the specified rectangle(s) in the order listed in the array. For any +given rectangle, each pixel is not drawn more than once. If rectangles +intersect, the intersecting pixels are drawn multiple times. + ]]></description> + <field name="drawable"><![CDATA[ +The drawable (Window or Pixmap) to draw on. + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + +The following graphics context components are used: function, plane-mask, +fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + +The following graphics context mode-dependent components are used: +foreground, background, tile, stipple, tile-stipple-x-origin, and +tile-stipple-y-origin. + ]]></field> + <field name="rectangles_len"><![CDATA[ +The number of `xcb_rectangle_t` structures in `rectangles`. + ]]></field> + <field name="rectangles"><![CDATA[ +The rectangles to fill. + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + </doc> </request> <request name="PolyFillArc" opcode="71" combine-adjacent="true"> @@ -1841,6 +4379,52 @@ authorization from the authors. <list type="char" name="string"> <fieldref>string_len</fieldref> </list> + <doc> + <brief>Draws text</brief> + <description><![CDATA[ +Fills the destination rectangle with the background pixel from `gc`, then +paints the text with the foreground pixel from `gc`. The upper-left corner of +the filled rectangle is at [x, y - font-ascent]. The width is overall-width, +the height is font-ascent + font-descent. The overall-width, font-ascent and +font-descent are as returned by `xcb_query_text_extents` (TODO). + +Note that using X core fonts is deprecated (but still supported) in favor of +client-side rendering using Xft. + ]]></description> + <field name="drawable"><![CDATA[ +The drawable (Window or Pixmap) to draw text on. + ]]></field> + <field name="string_len"><![CDATA[ +The length of the `string`. Note that this parameter limited by 255 due to +using 8 bits! + ]]></field> + <field name="string"><![CDATA[ +The string to draw. Only the first 255 characters are relevant due to the data +type of `string_len`. + ]]></field> + <field name="x"><![CDATA[ +The x coordinate of the first character, relative to the origin of `drawable`. + ]]></field> + <field name="y"><![CDATA[ +The y coordinate of the first character, relative to the origin of `drawable`. + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + +The following graphics context components are used: plane-mask, foreground, +background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="request" name="ImageText16" /> + </doc> </request> <request name="ImageText16" opcode="77"> @@ -1852,6 +4436,53 @@ authorization from the authors. <list type="CHAR2B" name="string"> <fieldref>string_len</fieldref> </list> + <doc> + <brief>Draws text</brief> + <description><![CDATA[ +Fills the destination rectangle with the background pixel from `gc`, then +paints the text with the foreground pixel from `gc`. The upper-left corner of +the filled rectangle is at [x, y - font-ascent]. The width is overall-width, +the height is font-ascent + font-descent. The overall-width, font-ascent and +font-descent are as returned by `xcb_query_text_extents` (TODO). + +Note that using X core fonts is deprecated (but still supported) in favor of +client-side rendering using Xft. + ]]></description> + <field name="drawable"><![CDATA[ +The drawable (Window or Pixmap) to draw text on. + ]]></field> + <field name="string_len"><![CDATA[ +The length of the `string` in characters. Note that this parameter limited by +255 due to using 8 bits! + ]]></field> + <field name="string"><![CDATA[ +The string to draw. Only the first 255 characters are relevant due to the data +type of `string_len`. Every character uses 2 bytes (hence the 16 in this +request's name). + ]]></field> + <field name="x"><![CDATA[ +The x coordinate of the first character, relative to the origin of `drawable`. + ]]></field> + <field name="y"><![CDATA[ +The y coordinate of the first character, relative to the origin of `drawable`. + ]]></field> + <field name="gc"><![CDATA[ +The graphics context to use. + +The following graphics context components are used: plane-mask, foreground, +background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. + ]]></field> + <error type="Drawable"><![CDATA[ +The specified `drawable` (Window or Pixmap) does not exist. + ]]></error> + <error type="GC"><![CDATA[ +The specified graphics context does not exist. + ]]></error> + <error type="Match"><![CDATA[ +TODO: reasons? + ]]></error> + <see type="request" name="ImageText8" /> + </doc> </request> <enum name= "ColormapAlloc"> @@ -1915,6 +4546,31 @@ authorization from the authors. <pad bytes="2" /> <field type="CARD32" name="pixel" /> </reply> + <doc> + <brief>Allocate a color</brief> + <description><![CDATA[ +Allocates a read-only colormap entry corresponding to the closest RGB value +supported by the hardware. If you are using TrueColor, you can take a shortcut +and directly calculate the color pixel value to avoid the round trip. But, for +example, on 16-bit color setups (VNC), you can easily get the closest supported +RGB value to the RGB value you are specifying. + ]]></description> + <field name="cmap"><![CDATA[ +TODO + ]]></field> + <field name="red"><![CDATA[ +The red value of your color. + ]]></field> + <field name="green"><![CDATA[ +The green value of your color. + ]]></field> + <field name="blue"><![CDATA[ +The blue value of your color. + ]]></field> + <error type="Colormap"><![CDATA[ +The specified colormap `cmap` does not exist. + ]]></error> + </doc> </request> <request name="AllocNamedColor" opcode="85"> @@ -2092,11 +4748,82 @@ authorization from the authors. <field type="CARD16" name="back_red" /> <field type="CARD16" name="back_green" /> <field type="CARD16" name="back_blue" /> + <doc> + <brief>create cursor</brief> + <description><![CDATA[ +Creates a cursor from a font glyph. X provides a set of standard cursor shapes +in a special font named cursor. Applications are encouraged to use this +interface for their cursors because the font can be customized for the +individual display type. + +All pixels which are set to 1 in the source will use the foreground color (as +specified by `fore_red`, `fore_green` and `fore_blue`). All pixels set to 0 +will use the background color (as specified by `back_red`, `back_green` and +`back_blue`). + ]]></description> + <field name="cid"><![CDATA[ +The ID with which you will refer to the cursor, created by `xcb_generate_id`. + ]]></field> + <field name="source_font"><![CDATA[ +In which font to look for the cursor glyph. + ]]></field> + <field name="mask_font"><![CDATA[ +In which font to look for the mask glyph. + ]]></field> + <field name="source_char"><![CDATA[ +The glyph of `source_font` to use. + ]]></field> + <field name="mask_char"><![CDATA[ +The glyph of `mask_font` to use as a mask: Pixels which are set to 1 define +which source pixels are displayed. All pixels which are set to 0 are not +displayed. + ]]></field> + <field name="fore_red"><![CDATA[ +The red value of the foreground color. + ]]></field> + <field name="fore_green"><![CDATA[ +The green value of the foreground color. + ]]></field> + <field name="fore_blue"><![CDATA[ +The blue value of the foreground color. + ]]></field> + <field name="back_red"><![CDATA[ +The red value of the background color. + ]]></field> + <field name="back_green"><![CDATA[ +The green value of the background color. + ]]></field> + <field name="back_blue"><![CDATA[ +The blue value of the background color. + ]]></field> + <error type="Alloc"><![CDATA[ +The X server could not allocate the requested resources (no memory?). + ]]></error> + <error type="Font"><![CDATA[ +The specified `source_font` or `mask_font` does not exist. + ]]></error> + <error type="Value"><![CDATA[ +Either `source_char` or `mask_char` are not defined in `source_font` or `mask_font`, respectively. + ]]></error> + <!-- TODO: example --> + </doc> </request> <request name="FreeCursor" opcode="95"> <pad bytes="1" /> <field type="CURSOR" name="cursor" /> + <doc> + <brief>Deletes a cursor</brief> + <description><![CDATA[ +Deletes the association between the cursor resource ID and the specified +cursor. The cursor is freed when no other resource references it. + ]]></description> + <field name="cursor"><![CDATA[The cursor to destroy.]]></field> + <error type="Cursor"><![CDATA[ +The specified cursor does not exist. + ]]></error> + </doc> + </request> <request name="RecolorCursor" opcode="96"> @@ -2141,7 +4868,44 @@ authorization from the authors. <field type="CARD8" name="major_opcode" /> <field type="CARD8" name="first_event" /> <field type="CARD8" name="first_error" /> + <doc> + <field name="present"><![CDATA[ +Whether the extension is present on this X11 server. + ]]></field> + <field name="major_opcode"><![CDATA[ +The major opcode for requests. + ]]></field> + <field name="first_event"><![CDATA[ +The first event code, if any. + ]]></field> + <field name="first_error"><![CDATA[ +The first error code, if any. + ]]></field> + </doc> </reply> + <doc> + <brief>check if extension is present</brief> + <description><![CDATA[ +Determines if the specified extension is present on this X11 server. + +Every extension has a unique `major_opcode` to identify requests, the minor +opcodes and request formats are extension-specific. If the extension provides +events and errors, the `first_event` and `first_error` fields in the reply are +set accordingly. + +There should rarely be a need to use this request directly, XCB provides the +`xcb_get_extension_data` function instead. + ]]></description> + <field name="name_len"><![CDATA[ +The length of `name` in bytes. + ]]></field> + <field name="name"><![CDATA[ +The name of the extension to query, for example "RANDR". This is case +sensitive! + ]]></field> + <see type="program" name="xdpyinfo" /> + <see type="function" name="xcb_get_extension_data" /> + </doc> </request> <request name="ListExtensions" opcode="99"> @@ -2349,6 +5113,24 @@ authorization from the authors. <request name="KillClient" opcode="113"> <pad bytes="1" /> <field type="CARD32" name="resource" altenum="Kill" /> + <doc> + <brief>kills a client</brief> + <description><![CDATA[ +Forces a close down of the client that created the specified `resource`. + ]]></description> + <field name="resource"><![CDATA[ +Any resource belonging to the client (for example a Window), used to identify +the client connection. + +The special value of `XCB_KILL_ALL_TEMPORARY`, the resources of all clients +that have terminated in `RetainTemporary` (TODO) are destroyed. + ]]></field> + <error type="Value"><![CDATA[ +The specified `resource` does not exist. + ]]></error> + <see type="program" name="xkill" /> + </doc> + </request> <request name="RotateProperties" opcode="114"> |