diff options
Diffstat (limited to 'xembed/spec/xembed-spec.xml')
| -rw-r--r-- | xembed/spec/xembed-spec.xml | 1407 |
1 files changed, 1407 insertions, 0 deletions
diff --git a/xembed/spec/xembed-spec.xml b/xembed/spec/xembed-spec.xml new file mode 100644 index 0000000..78734a5 --- /dev/null +++ b/xembed/spec/xembed-spec.xml @@ -0,0 +1,1407 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<article id="index"> + <articleinfo> + <title>XEmbed Protocol Specification</title> + <releaseinfo>Version 0.5</releaseinfo> + <date>15 April 2002</date> + <authorgroup> + <author> + <firstname>Mathias</firstname> + <surname>Ettrich</surname> + <affiliation> + <address> + <email>ettrich@trolltech.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Owen</firstname> + <surname>Taylor</surname> + <affiliation> + <address> + <email>otaylor@redhat.com</email> + </address> + </affiliation> + </author> + </authorgroup> + </articleinfo> + + <sect1 id="overview"> + <title>Overview</title> + <para> + XEmbed is a protocol that uses basic X mechanisms such as client + messages and reparenting windows to provide embedding of a + control from one application into another application. Some + of the goals of the XEmbed design are: + </para> + <orderedlist> + <listitem> + <para> + Support for out-of process controls, written in any toolkit + or even plain Xlib. + </para> + </listitem> + <listitem> + <para> + Support for in-process-controls when mixing different + toolkits in one process. + </para> + </listitem> + <listitem> + <para> + Smooth integration of the embedding application and embedded client + in areas such as input device handling and visual feedback. + </para> + </listitem> + <listitem> + <para> + Easy implementation. A full implementation supporting all + details correctly may require minor toolkit modifications, + but it should be possible to get basic functionality going + in less than 1000 lines of code. + </para> + </listitem> + </orderedlist> + <para> + Goal 1 is the most urgent one. A embedding specification allows + developers to write applets for whatever desktop the user is + using in whatever toolkit they prefer. Goal 2 is more of + something to keep in mind than a immediate requirement. While + there are other ways to mix two or more toolkits, using XEmbed + might be the easiest and thus most comfortable way. Goal 3 + describes the targeted level of integration. The users should + not necessarily notice that they work with embedded controls; + devices like the keyboard and the mouse should work as expected, + inactive windows should look like they are inactive, and so + forth. The level of integration may, however, be limited by goal + 4. In order for the protocol to be successful, it's crucial to + get implementations for the most important toolkits. Thus, the + implementation should not require too much coding and no or only + few modifications to the toolkit's kernel. + </para> + <para> + At the time of writing, an implementation of XEmbed is included + in GTK+-2.0 that mostly conforms to this version of the + specification. The main area of divergence is in the area of + accelerators, where a simpler scheme is implemented than the + XEMBED_REGISTER_ACCELERATOR, XEMBED_UNREGISTER_ACCELERATOR + accelerator scheme described here. The KDE libraries (libkdeui) + include QXEmbed, a mostly-complete implementation for Qt of an + earlier version of the protocol. + </para> + </sect1> + <sect1 id="definitions"> + <title>Definitions</title> + <variablelist> + <varlistentry> + <term>Active</term> + <listitem> + <para> + A toplevel window is <firstterm>active</firstterm> if it + currently is receiving keyboard events. (The window or a + descendant has the X keyboard focus.) A widget within the + toplevel is active if the toplevel is active, regardless + of whether that widget has the input focus within the + toplevel. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Client</term> + <listitem> + <para> + In an embedding situation, the <firstterm>client</firstterm> is + the window that is embedded into an embedder. Sometimes also + called a plug. (Note that the usage here should not be + confused with the typical X usage of "client" to mean an application + connecting to the X server. That is always referred to as + an application in this document) + </para> + <remark> + [ Should we replace client by some other term in + this document to avoid the confusion? ] + </remark> + </listitem> + </varlistentry> + <varlistentry> + <term>Embedder</term> + <listitem> + <para> + In an embedding situation, the <firstterm>embedder</firstterm> + is the graphical location that embeds an external + client. Sometimes also called a socket or site. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Focused</term> + <listitem> + <para> + A widget is <firstterm>focused</firstterm> if it receives + keyboard events within its toplevel. This is without + regard to whether the toplevel is active, and has nothing + to do with the X keyboard focus. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + <sect1 id="rationale"> + <title>Rationale and discussion</title> + <para> + The basis for handling embedding is that the embedder acts like + a "window manager" for the client. (The window management + protocol is defined in the X Inter-Client Communications Manual + or ICCCM). The embedder selects with SubstructureRedirectMask + on its window so that it can intercept, and then the client + window is reparented (using + <function>XReparentWindow()</function>) + as a child of the embedder window. Because of the substructure redirect, the + embedder is able to intercept calls to move or resize the client + window, and handle them as appropriate to the location in the + embedding application. (Map requests are also redirected, but + XEmbed actually handles map requests separately... see the + description of the XEMBED_MAPPED flag.) + </para> + <para> + The window management protocol is sufficient to handle the + basics of visual embedding, but has deficiencies in other areas + that prevent it from providing natural integration between + toolkits. These areas include: + </para> + + <simplelist> + <member>window activation state</member> + <member>keyboard focus</member> + <member>tab focus chain</member> + <member>keyboard short cuts / accelerators</member> + <member>modality</member> + <member>drag and drop (XDND)</member> + </simplelist> + + <para> + The XEmbed protocol is mainly concerned with communicating + additional information between embedder and client to handle + these areas. Communication in XEmbed is done by forwarding + slightly modified XEvents using + <function>XSendEvent()</function>, + by sending special XEmbed messages, and by setting X properties. In addition, + standard ICCCM features like WMNormalHints are used where + appropriate. + </para> + <para> + The next sections explain why these problems occur with the + simple "window management" approach and how XEmbed solves them. + </para> + + <sect2> + <title>Window activation state</title> + <para> + A widget has to know the activation state of its toplevel + window. This enables input widgets like a line editor, to display + a blinking cursor only when the user can actually type into it. In + addition, certain GUI styles choose to display inactive windows + differently, typically with a lighter and less contrasting color + palette. + </para> + <para> + Unfortunately, there are no such messages like WindowActivate + or WindowDeactivate in the X protocol. Instead, a window knows + that it is active when it receives keyboard focus (FocusIn + event with certain modes) or looses it (FocusOut event with certain + modes). This applies to embedded child windows only, when the + mouse pointer points onto one of the child's subwindows in the very + moment the window manager puts the X focus on the toplevel + window. For that reason, XEmbed requires the embedders to pass + XEMBED_WINDOW_ACTIVATE and XEMBED_WINDOW_DEACTIVATE messages to + their respective clients whenever they get or loose X keyboard + </para> + </sect2> + + <sect2> + <title>Keyboard focus</title> + <para> + The delivery of keyboard events in X is designed in a way that + does not correspond to the typical operation of modern + toolkits; instead it seems designed to allow things to allow + things to work without either a window manager or a focus + handling in the toolkit. Typically, key events are sent to the + window which has the X input focus (set with + XSetInputFocus()). However, if the mouse pointer is inside + that focus window, the event is sent to the subwindow of the + focus window that is under the moues pointer. In modern toolkits, + the X input focus is typically left on the toplevel window and + a separate logical input focus is implemented within the + toolkit. The toolkit ignores the window that the key event is + actually sent to (which might be a scrollbar or other random + widget within the toplevel, depending on where the mouse + pointer is), and distributes key events to widget with the + logical input focus. + </para> + <para> + So, for standard operation, the behavior where key events are sent + to the window with the mouse pointer is simply ignored. But + with embedded windows, it causes problems, since, if the + mouse pointer is within the embedded window, the outer toolkit + doesn't see any key events, even if the logical keyboard focus + is elsewhere within the outer toolkits toplevel window. + </para> + <para> + Previous embedding techniques therefore required clients to + forward any key event they receive (KeyPress and KeyRelease) to + their respective embedder. In order to support multiple levels of + embedding, events that stem from a SendEvent request had to be + forwarded as well. While this is a possible solution, it adds both + race conditions and inefficiency. + </para> + <para> + The solution proposed by XEmbed is is to beat X11 with its own + weapons: The topmost toolkit is <emphasis>required</emphasis> + to keep the X input focus on one of its own windows without + any embedded children. Keeping the focus on such a window + ensures that key events are always delivered to the outer + toolkit and thus can be forwarded easily to any embedded + window. This also makes it possible to use this part of XEmbed + with clients that do not support the protocol at all, without + breaking keyboard input for the embedding application. + </para> + <para> + In detail, the topmost embedder creates a not-visible X Window to + hold the focus, the focus proxy. (It might be a 1x1 child + window of toplevel located at -1,-1.) Since the focus proxy isn't + an ancestor of the client window, the X focus can never move + into the client window because of the mouse pointer location. + In other words, whenever the outer window is activated + (receives the X input focus), it has to put the X focus on the + FocusProxy by calling <function>XSetInputFocus()</function>. + </para> + <para> + The trouble with this is, that you should not use <function>XSetInputFocus()</function> + without a proper time stamp from the Server, to avoid race + conditions. Unfortunately, the FocusIn event does not carry a + timestamp. The solution to this is, to ask the window manager for + the WM_TAKE_FOCUS window protocol. Thus, whenever the window is + activated, it will receive a WM_PROTOCOLS client message with + data.l[0] being WM_TAKE_FOCUS and data.l[1] being a proper + timestamp. This timestamp can be used safely for the call to + <function>XSetInputFocus()</function>. + </para> + <para> + If an embedder widget gets the logical input focus, it sends + an XEMBED_FOCUS_IN message to its client. The client that + receives this messages knows that its logical focus is now + also the logical focus of the application window and will + react accordingly. If its logical focus lies on the line + editor control mentioned above, and the window is active, the + editor will show a blinking cursor after processing this + message. + </para> + <para> + In a similar fashion, if the embedder looses focus, it sends + an XEMBED_FOCUS_OUT message. + </para> + </sect2> + <sect2> + <title>Tab focus chain</title> + <para> + X does not have a concept of a tab focus chain, it is up to the + toolkit or the application to implement it. Since the concept + is standard among almost all toolkits, XEmbed supports it. An + XEmbed client integrates perfectly in the embedder's tab focus + chain, i.e. the user can tab onto the client, through all its + widgets and back to the outer world without noticing that they + traversed an external window. + </para> + <para> + As explained in the previous section, an embedder sends an + XEMBED_FOCUS_IN message to its client when it gets focus. The + detail code of this message is per default 0, that is, + XEMBED_FOCUS_CURRENT. It indicates that the clients keeps its own + logical focus where it was. To support tabbing, XEmbed provides + two more detail codes, namely XEMBED_FOCUS_FIRST and + XEMBED_FOCUS_LAST, that indicate that the client should move + its focus to the beginning or end of the focus chain. + </para> + <para> + When the user tabs to the very end of a client's tab chain, the + client follows the request (i.e. it puts its logical focus back to + the beginning its tab chain) and sends an XEMBED_FOCUS_NEXT + message to the embedder. If the embedder has siblings that accept + tab focus, it will do a virtual tab forward. As a result, it will + loose focus itself and consequently send an XEMBED_FOCUS_OUT + message to the client. As expected, the client's line edit control + from the previous example will stop blinking. + </para> + <para> + Backward tabbing is done exactly in the same manner, using the + XEMBED_FOCUS_PREV message. + </para> + </sect2> + <sect2> + <title>Keyboard short cuts / accelerators</title> + <para> + XEmbed is designed in such a way, that keyboard events are + received by the toplevel window, and then sent down the focus + focus chain. Toolkits will usually check for shortcuts or + accelerators before sending the event to the focus widget. If + such a shortcut is defined, the respective action is taken + rather than passing the event through to the focus + widget. This means, accelerators in the outmost window always + work properly, whereas accelerators defined inside an embedded + client only work if that client actually has focus. XEmbed + solves this problem with two messages, + XEMBED_REGISTER_ACCELERATOR and XEMBED_UNREGISTER_ACCELERATOR. + With XEMBED_REGISTER_ACCELERATOR, a client can reserve a + certain key/modifier combination as shortcut or + accelerator. The message is passed through to the topmost + embedder, where the key combination is stored. An + XEMBED_UNREGISTER_ACCELERATOR message releases the key again. + </para> + </sect2> + <sect2> + <title>Modality</title> + <para> + If an application window is shadowed by a modal dialog, no user + input is supposed to get through. The XEmbed design ensures this + for keyboard input, because the toplevel window knows about its + modal state and will not pass key events through. Embedded clients + thus inherit the modality from the topmost embedder. Mouse input, + however, is sent directly to the embedded clients by the X-Server, + unaffected by the modality of the application window. To give + clients the possibility to behave correctly when being shadowed by + a modal dialog, an embedder can choose to send an + XEMBED_MODALITY_ON message to its client when it becomes shadowed, + and an XEMBED_MODALITY_OFF message when it leaves modality + again. If the client contains embedders itself, those have to pass + both messages through to their clients. + </para> + </sect2> + <sect2> + <title>Drag and drop (XDND)</title> + <para> + XDND drag-and-drop does not work with reparented external + windows, since messages are exchanged with the toplevel window + only. This is done for performance reasons. While it is cheap to + get the window under the mouse pointer, it is very expensive to + get a window under another window. Unfortunately, this is required + quite often when dragging objects around, since the pointer + may overlap the drag icon. + </para> + <para> + Solving the drag-and-drop problem, however, is quite easy, + since the XDND protocol was carefully designed in a way that + makes it possible to support embedded windows. Basically, the + embedder has to operate as drag-and-drop proxy for the client. Any + XDND messages like XdndEnter, Xdnd,Leave, etc. simply have to be + passed through. A toolkit's XDND implementation has to take this + situation in consideration. + </para> + </sect2> + </sect1> + <sect1 id="lifecycle"> + <title>Embedding life cycle</title> + <para> + The protocol is started by the embedder. The window ID of + the client window is passed (by unspecified means) to the + embedding application, and the embedder calls + <function>XReparentWindow()</function> to reparent the client + window into the embedder window. + </para> + <para> + Implementations may choose to support an alternate method of + beginning the protocol where the window ID of the embedder + is passed to client application and the client creates a window + within the embedder, or reparents an existing window into + the embedder's window. Which method of starting XEmbed is + used a matter up to higher level agreement and outside the + scope of this specification. + </para> + <para> + In either case the client window must have a property called + _XEMBED_INFO on it. This property has type _XEMBED_INFO + and format 32. The contents of the property are: + </para> + <table> + <title>_XEMBED_INFO</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Field</entry><entry>Type</entry><entry>Comments</entry> + </row> + </thead> + <tbody> + <row> + <entry>version</entry><entry>CARD32</entry><entry>The protocol version</entry> + </row> + <row> + <entry>flags</entry><entry>CARD32</entry><entry>A bitfield of flags</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The <structfield>version</structfield> field indicates the + maximum version of the protocol that the client supports. + The embedder should retrieve this field and set the data2 field + of the XEMBED_EMBEDDED_NOTIFY to + Min (<structfield>version</structfield>, <replaceable>max version supported by embedder</replaceable>). + The version number corresponding to the current version of the + protocol is 0. + <remark>[Should the version be defined as (Major << 16 | Minor) ?]</remark> + </para> + <para> + The currently defined bit in the + <structfield>flags</structfield> field is: + </para> + <programlisting><!-- +-->/* Flags for _XEMBED_INFO */ +#define XEMBED_MAPPED (1 << 0)<!-- + --></programlisting> + <variablelist> + <varlistentry> + <term>XEMBED_MAPPED</term> + <listitem> + <para> + If set the client should be mapped. The embedder must + track the flags field by selecting for PropertyNotify + events on the client and map and unmap the client + appropriately. (The embedder can leave the client unmapped + when this bit is set, but should immediately unmap the + client upon detecting that the bit has been unset.) + </para> + <remark> + Rationale: the reason for using this bit rather than + MapRequest events is so that the client can reliably + control it's map state before the inception of the + protocol without worry that the client window will + become visible as a child of the root window. + </remark> + </listitem> + </varlistentry> + </variablelist> + <para> + To support future expansion, all fields not currently defined + must be set to zero. To add proprietary extensions to the + XEMBED protocol, an application must use a separate property, rather + than using unused bits in the struct field or extending the + _XEMBED_INFO property. + </para> + <para> + At the start of the protocol, the embedder first sends an + XEMBED_EMBEDDED_NOTIFY message, then sends + XEMBED_FOCUS_IN, XEMBED_WINDOW_ACTIVATE, and XEMBED_MODALITY_ON + messages as necessary to synchronize the state of the + client with that of the embedder. Before any of these messages + received, the state of the client is: + <simplelist> + <member>Not focused</member> + <member>Not active</member> + <member>Modality off</member> + </simplelist> + </para> + <para> + If the embedder is geometry managed and can change its size, it + should obey the client's WMNormalHints settings. Note that + most toolkits will not have equivalents for all the hints in + the WMNormalHints settings, clients must not assume that the + requested hints will be obeyed exactly. The + <structfield>width_inc</structfield>, + <structfield>height_inc</structfield>, + <structfield>min_aspect</structfield>, and + <structfield>max_aspect</structfield> fields are examples of + fields from WMNormalHints that are unlikely to be supported + by embedders. + </para> + <para> + The protocol ends in one of three ways: + </para> + <orderedlist> + <listitem> + <para> + The embedder can unmap the client and reparent the client + window to the root window. If the client receives an + ReparentNotify event, it should check the + <structfield>parent</structfield> field of the + <structname>XReparentEvent</structname> structure. If this + is the root window of the window's screen, then the protocol + is finished and there is no further interaction. If it + is a window other than the root window, then the protocol + continues with the new parent acting as the embedder window. + </para> + </listitem> + <listitem> + <para> + The client can reparent its window out of the embedder + window. If the embedder receives a ReparentNotify signal + with the <structfield>window</structfield> field being the + current client and the <structfield>parent</structfield> + field being a different window, this indicates the end + of the protocol. + </para> + <remark> + [ GTK+ doesn't currently handle this; but it seems useful + to allow the protocol to be ended in a non-destructive + fashion from either end. ] + </remark> + </listitem> + <listitem> + <para> + The client can destroy its window. + </para> + </listitem> + </orderedlist> + </sect1> + <sect1 id="messages"> + <title>Message Specifications</title> + <para> + An XEmbed message is an X11 client message with message type + "_XEMBED". The format is 32, the first three data longs carry the + toolkit's X time (l[0]), the message's major opcode (l[1]) and the + message's detail code (l[2]). If no detail is required, the value + passed has to be 0. The remaining two data longs (l[3] and l[4]) + are reserved for data1 and data2. Unused bytes of the client + message are set to 0. The event is sent to the target window with + no event mask and propagation turned off. + </para> + <para> + The valid XEmbed messages are: + </para> + <programlisting><!-- +-->/* XEMBED messages */ +#define XEMBED_EMBEDDED_NOTIFY 0 +#define XEMBED_WINDOW_ACTIVATE 1 +#define XEMBED_WINDOW_DEACTIVATE 2 +#define XEMBED_REQUEST_FOCUS 3 +#define XEMBED_FOCUS_IN 4 +#define XEMBED_FOCUS_OUT 5 +#define XEMBED_FOCUS_NEXT 6 +#define XEMBED_FOCUS_PREV 7 +/* 8-9 were used for XEMBED_GRAB_KEY/XEMBED_UNGRAB_KEY */ +#define XEMBED_MODALITY_ON 10 +#define XEMBED_MODALITY_OFF 11 +#define XEMBED_REGISTER_ACCELERATOR 12 +#define XEMBED_UNREGISTER_ACCELERATOR 13 +#define XEMBED_ACTIVATE_ACCELERATOR 14<!-- + --></programlisting> + <para> + A detail code is required for XEMBED_FOCUS_IN. The following values + are valid: + </para> + <programlisting><!-- +-->/* Details for XEMBED_FOCUS_IN: */ +#define XEMBED_FOCUS_CURRENT 0 +#define XEMBED_FOCUS_FIRST 1 +#define XEMBED_FOCUS_LAST 2<!-- + --></programlisting> + <sect2> + <title>XEMBED_EMBEDDED_NOTIFY</title> + <para> + Sent from the embedder to the client on embedding, after + reparenting and mapping the client's X window. A client that + receives this messages knows that its window was embedded by an + XEmbed site and not simply reparented by a window manager. To support toolkits + that do not keep track of reparenting events, the message carries + the embedder's window handle as data1: + </para> + <table> + <title>XEMBED_EMBEDDED_NOTIFY</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>data1</entry><entry>The embedder's window handle.</entry> + </row> + <row> + <entry>data2</entry><entry>The protocol version in use + (see the description of _XEMBED_INFO).</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>XEMBED_WINDOW_ACTIVATE / XEMBED_WINDOW_DEACTIVATE</title> + <para> + Sent from the embedder to the client when the window becomes + active or inactive, i.e. when the window gets or looses the + keyboard input focus. If the client contains embedders itself, + those have to pass the message through to their clients. + </para> + <para> + Note that no XEMBED_FOCUS_IN or XEMBED_FOCUS_OUT messages + should be sent when the toplevel window gains or loses + focus. The XEMBED_FOCUS_IN and XEMBED_FOCUS_OUT messages + refer only to focus <firstterm>within</firstterm> the + toplevel window and are independent of toplevel activation + state. This independence is necessary so that input focus + within a toplevel can be moved programmatically when the + toplevel doesn't have input focus. + </para> + <remark> + [ GTK+ is currently in violation of the preceding note, + and sends FOCUS_IN and FOCUS_OUT only when the toplevel + is active. See + <ulink + url="http://bugzilla.gnome.org/show_bug.cgi?id=67943">GNOME bug #67943</ulink> ] + </remark> + <para> + Widgets within the client should typically be displayed with + the focus only when the client both has focus and is active. + </para> + </sect2> + <sect2> + <title>XEMBED_REQUEST_FOCUS</title> + <para> + Sent from the client to the embedder when the client wants + focus. The most common occasion is when the user clicks into one + of the client's child widgets, for example a line editor, in order + to type something in. + </para> + <para> + The message is passed along to the topmost embedder that + eventually responds with a XEMBED_FOCUS_IN message. The focus in + message is passed all the way back until it reaches the original + focus requester. In the end, not only the original client has + focus, but also all its ancestor embedders. + </para> + </sect2> + <sect2> + <title>XEMBED_FOCUS_IN</title> + <para> + Sent from the embedder to the client when it gets focus. The + detail code determines, where the client shall move its own + logical focus to. Three possibilities exist: + </para> + <variablelist> + <varlistentry> + <term>XEMBED_FOCUS_CURRENT</term> + <listitem> + <para> + Normal activation, does not move the clients logical + focus. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>XEMBED_FOCUS_FIRST</term> + <listitem> + <para> + Used when the user tabs onto a client. It indicates that + the client should put its logical focus onto the widget + that comes first in its own tab focus chain. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>XEMBED_FOCUS_LIST</term> + <listitem> + <para> + Used when the user tabs onto a client. It indicates that + the client should put its logical focus onto the widget + that comes first in its own tab focus chain. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2> + <title>XEMBED_FOCUS_OUT</title> + <para> + Sent from the embedder to the client when it looses focus. + </para> + </sect2> + <sect2> + <title>XEMBED_FOCUS_NEXT</title> + <para> + Sent from the client to the embedder when it reaches the end of + its logical tab chain after the user tabbed forward. If the + embedder has siblings that accept tab focus, it will do a virtual + tab forward. As a result, it will loose focus itself and + consequently send an XEMBED_FOCUS_OUT message to the client + </para> + </sect2> + <sect2> + <title>XEMBED_FOCUS_PREV</title> + <para> + Sent from the client to the embedder when it reaches the + beginning of its logical tab chain after the user tabbed + backward. If the embedder has siblings that accept tab focus, it + will do a virtual tab backward. As a result, it will loose focus + itself and consequently send an XEMBED_FOCUS_OUT message to the + client + </para> + </sect2> + <sect2> + <title>XEMBED_REGISTER_ACCELERATOR / XEMBED_UNREGISTER_ACCELERATOR</title> + <para> + A client that needs to reserve a certain key/modifier + combination as shortcut or accelerators, sends a XEMBED_REGISTER_ACCELERATOR + message to its embedder. As long as the embedder itself is a child + of a client, the accelerator will be propagated up to the toplevel. + </para> + <table> + <title>XEMBED_REGISTER_ACCELERATOR</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>detail</entry><entry>accelerator_id</entry> + </row> + <row> + <entry>data1</entry><entry>X key symbol</entry> + </row> + <row> + <entry>data2</entry><entry>bit field of modifier values</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The accelerator_id is used to identify the accelerator when + activating the accelerator. The reason for using an + accelerator ID instead of identifying accelerators simply by + key symbol and modifiers is to allow the correct handling of + overloaded accelerators with embedded widgets. (An accelerator + is overloaded if there multiple accelerators on the same key, + usually because of accidental collisions.) When an overloaded + accelerator is pressed repeatedly, the toplevel activates + accelerators on that key in round-robin fashion. If this + round-robin behavior is not supported by the embedding + toolkit, picking an arbitrary accelerator for the key and + activating it is acceptable. Well designed applications should + avoid collisions in any case. + </para> + <note> + <para> + Ordering the round-robin of conflicting accelerators + in a predictable (geometric or in focus chain) order + is desirable. This can be achieved if the toplevel sorts + the conflicting accelerators as if they applied to the + client instead of widgets within the client and then + each client does the same sort on the subset of conflicting + accelerators within it. To get this to work properly + if there are conflicting accelerators within a client, say widget + A and B both have the same mnemonic, then instead of + registering one accelerator for widget A and one for + widget B, the client should register two accelerators that + corresponds to both A and B, and then when + XEMBED_ACTIVATE_ACCELERATOR is received for either + accelerator, implement round robin between A and B + with the correct sorting. + </para> + </note> + <para> + The modified bit field is a bitwise OR of values indicating + various modifiers; these indicate logical accelerator + keys rather than corresponding directly to the bits in + the XKeyEvent state field. + </para> + <programlisting><!-- +-->/* Modifiers field for XEMBED_REGISTER_ACCELERATOR */ +#define XEMBED_MODIFIER_SHIFT (1 << 0) +#define XEMBED_MODIFIER_CONTROL (1 << 1) +#define XEMBED_MODIFIER_ALT (1 << 2) +#define XEMBED_MODIFIER_SUPER (1 << 3) +#define XEMBED_MODIFIER_HYPER (1 << 4)<!-- + --></programlisting> + <para> + (Meta is intentionally left out here because if you try to separate + Alt and Meta, a large fraction of users will experience problems + with their keyboard setups... there is no reliably standard + of which one is the primary modifier key and on the Alt key.) + </para> + <para> + On activation, the topmost embedder will send + XEMBED_ACTIVATE_ACCELERATOR to its client; if the + accelerator was registered by an embedder inside that + client, the embedder will send XEMBED_ACTIVATE_ACCELERATOR + to its client and so forth. + </para> + <para> + Note that the assignment of ID's is private for each pair + of client and embedder and when accelerators are being + propagated through multiple client/embedder pairs, a + different accelerator ID may be used for each pair. + </para> + <para> + The XEMBED_UNREGISTER_ACCELERATOR message releases the key + combination again. + </para> + <table> + <title>XEMBED_UNREGISTER_ACCELERATOR</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>detail</entry><entry>integer ID passed + to XEMBED_REGISTER_ACCELERATOR</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + Hint to implementors: It is the responsibility of the + embedder to keep track of all forwarded accelerators + and to remove them when the client window dies. + </para> + </sect2> + <sect2> + <title>XEMBED_ACTIVATE_ACCELERATOR</title> + <para> + The XEMBED_ACTIVATE_ACCELERATOR message is sent when a + accelerator previously registered with + XEMBED_REGISTER_ACCELERATOR is activated on the toplevel + containing the embedder. + </para> + <table> + <title>XEMBED_ACTIVATE_ACCELERATOR</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>detail</entry><entry>integer ID passed + when registering the accelerator</entry> + </row> + <row> + <entry>data1</entry><entry>flags.</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The following bit is defined for the flags field; all + other bits must be zero. + </para> + <programlisting><!-- +-->/* Flags for XEMBED_ACTIVATE_ACCELERATOR */ +#define XEMBED_ACCELERATOR_OVERLOADED (1 << 0)<!-- + --> + </programlisting> + <variablelist> + <varlistentry> + <term>XEMBED_ACCELERATOR_OVERLOADED</term> + <listitem> + <para> + This flag indicates that multiple accelerators exist for + the key combination within the toplevel. The toolkit + may modify the behavior of the accelerator based on + this value. For instance, if the accelerator is a + mnemonic for a button, it might activate the the button + immediately if the accelerator is not overloaded, but + when overloaded, it would only focus the button. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2> + <title>XEMBED_MODALITY_ON / XEMBED_MODALITY_OFF</title> + <para> + Sent from the embedder to the client when the window becomes + shadowed by a modal dialog, or when it is released again. If the + client contains embedders itself, those have to pass the message + through to their clients. An embedded control should ignore + mouse input while modality is active. Note that that keyboard + input is blocked anyway by XEmbed, since the topmost embedder will + not pass keyboard events through in modal state. + </para> + </sect2> + </sect1> + + <sect1 id="techniques"> + <title>Techniques</title> + + <sect2> + <title>Handling errors</title> + <para> + Implementors of the XEmbed protocol should handle the other + party disappearing at any point. For this reason X errors + must be trapped when performing any operation with a window + not created by the application. This is done by using + <function>XSetErrorHandler()</function>. + A sample implementation of trapping errors in C looks like: + </para> + <programlisting><!-- +-->#include <X11/Xlib.h> + +static int trapped_error_code = 0; +static int (*old_error_handler) (Display *, XErrorEvent *); + +static int +error_handler(Display *display, + XErrorEvent *error) +{ + trapped_error_code = error->error_code; + return 0; +} + +void +trap_errors(void) +{ + trapped_error_code = 0; + old_error_handler = XSetErrorHandler(error_handler); +} + +int +untrap_errors(void) +{ + XSetErrorHandler(old_error_handler); + return trapped_error_code; +}<!-- + --></programlisting> + </sect2> + <sect2> + <title>Forwarding X Events</title> + <para> + An XEmbed embedder has to forward key-press and key-release + events to its respective client. + </para> + <para> + Key events are forwarded by changing the event's window field + to the window handle of the client and sending the modified + message via <function>XSendEvent()</function> to the embedder, + with no event mask and propagation turned off. + </para> + <para> + Note: XEmbed requires toolkits to handle key-events that come + from a SendEvent request. That means, if somebody can access + your X-Server, it's possible to fake keyboard input. Given + that most toolkits accept sent key events today anyway and the + X Server is typically protected through magic cookie + authorization, this is not considered to be an + issue. Applications with higher security requirements may + choose not to use embedded components, though, and to filter + out any events coming from <function>XSendEvent()</function>. + </para> + <para> + Given that Window client is the client's window handle, + here is a piece of code of an imaginary event-loop in C that does + the forwarding. + </para> + <programlisting><!-- +-->#include <X11/Xlib.h> + +void handle_event( + Display* dpy, /* display */ + XEvent* ev /* event */ +){ + if ( ev->type == KeyPress || ev->type == KeyRelease ) { + ev->xkey.window = client; + trap_errors(); + XSendEvent( dpy, client, False, NoEventMask, ev ); + XSync( dpy, False ); + if (untrap_errors()) { + /* Handle failure */ + } + + return; + } + ... /* normal event handling */ +}<!-- + --></programlisting> + </sect2> + <sect2> + <title>Sending XEmbed messages</title> + <para> + Given that Time x_time contains the timestamp from the event + currently being processed. (CurrentTime is generally the best + choice if no event is being processed), here is a valid + implementation in C of sending an XEMBED message: + </para> + <programlisting><!-- +-->#include <X11/Xlib.h> + +void send_xembed_message( + Display* dpy, /* display */ + Window w, /* receiver */ + long message, /* message opcode */ + long detail /* message detail */ + long data1 /* message data 1 */ + long data2 /* message data 2 */ +){ + XEvent ev; + memset(&ev, 0, sizeof(ev)); + ev.xclient.type = ClientMessage; + ev.xclient.window = w; + ev.xclient.message_type = XInternAtom( dpy, "_XEMBED", False ); + ev.xclient.format = 32; + ev.xclient.data.l[0] = x_time; + ev.xclient.data.l[1] = message; + ev.xclient.data.l[2] = detail; + ev.xclient.data.l[3] = data1; + ev.xclient.data.l[4] = data2; + trap_errors(); + XSendEvent(dpy, w, False, NoEventMask, &ev); + XSync(dpy, False); + if (untrap_errors()) { + /* Handle failure */ + } +}<!-- + --></programlisting> + </sect2> + </sect1> + <sect1 id="issues"> + <title>Issues</title> + <sect2> + <title>Implementation of modality</title> + <para> + The protocol could be simplified by removing the + XEMBED_MODALITY_ON and XEMBED_MODALITY_OFF messages in favor + of requiring the embedder to map an input-only window over + it's child when it beings shadowed by a modal grab. + </para> + <para> + One possible reason for the current protocol is that a toolkit + might want to have elements such as scrollbars that remain + active even when grab shadowed. (I know of no toolkit that + actually implements this.) + </para> + </sect2> + <sect2> + <title>Clarify function of timestamps</title> + <para> + The function of the timestamp arguments needs to be clarified, + as well as the requirements for what should be passed + in the field. The original draft of the specification + contained the text about the determining the timestamp. + </para> + <blockquote> + <para> + The x time is to be updated whenever the toolkit receives an + event from the server that carries a timestamp. XEmbed client + messages qualify for that. + </para> + <para> + Hint to implementors: Check that the xembed time stamp + is actually later than your current x time. While this cannot + happen with ordinary XEvents, delayed client messages may have + this effect. Be prepared that evil implementations may even + pass CurrentTime sometimes. + </para> + </blockquote> + <para> + But I [OWT] wouldn't agree with this advice. The point + of a timestamp is to make sure that when events are processed + out of order, the event generated last by the user wins + for shared resources such as input focus, selections, and + grabs. An example of where this can matter is if you have + </para> + <programlisting><!-- +--> Toplevel Window + Embedder + Client + Text Entry 1 + Embedder + Client + Text Entry 2<!-- + --></programlisting> + <para> + If the entries are set to select the text on focus in, and the + user hits TAB in quick succession, then the timestamps on the + FOCUS_IN events are what makes sure that Entry 2 actually ends + up owning the PRIMARY selection, instead of it being a race + between the two clients. But in situations like this having + the correct timestamp only matters if a user action triggers + the behavior. + </para> + <para> + Hence the advice that the timestamp should be the time from + the event currently being processed. + </para> + <para> + If no explicit user action is involved, then the + best thing to do is to use CurrentTime; using the timestamp + from the last X event received can cause problems if the + ultimate trigger of the behavior is a timeout or network + and the last X event happened some time in the distant past. + </para> + </sect2> + <sect2> + <title>Complexity of accelerator handling</title> + <para> + The current specification for accelerator handling is a little + complex. Most of the complexity (the accelerator IDs) comes + from the need to handle conflicting accelerators. + GTK+ currently implements a simpler scheme where grabs are + identified only by key symbol and modifier and conflicting + mnemonic resolution doesn't work across embedder/client + interfaces. + </para> + </sect2> + <sect2> + <title>Infinite loops in focusing</title> + <para> + There is the potential for infinite loops of focusing - + Consider the case: + </para> + <programlisting><!-- +--> Toplevel Window + Embedder + Client<!-- + --></programlisting> + <para> + Where there are no focusable sites in the client or in the + toplevel window. Then if <keysym>Tab</keysym> is pressed, the embedder + will send: FOCUS_IN/FOCUS_FIRST to the client, the client will + send FOCUS_NEXT to the embedder, the toplevel window will + wrap the focus around and send FOCUS_IN/FOCUS_FIRST to the + client... + </para> + <para> + The minimum mechanism that seems necessary to prevent this + loop is a serial number in the FOCUS_IN/FOCUS_FIRST message + that is repeated in a resulting FOCUS_NEXT message. + </para> + <para> + A possibly better way of handling this could be to make FOCUS_IN have + an explicit response; that, is, add a XEMBED_FOCUS_IN_RESPONSE + that the client must send to the embedder after receipt + of a FOCUS_IN message. + </para> + + <table> + <title>XEMBED_FOCUS_IN_RESPONSE</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>detail</entry><entry>1 if the client accepted the focus, 0 otherwise</entry> + </row> + <row> + <entry>data1</entry><entry>serial number from XEMBED_FOCUS_IN</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The main problem with requiring a response here is that caller + needs to wait for the return event, and to handle cases like + parent (client 1) => child (client 2) => grandchild (client 1), + it probably needs to process all sorts of incoming events at + this point. If the user hits <keysym>Tab</keysym><keysym>Tab</keysym> + in quick succession things could get very complicated. + </para> + </sect2> + <sect2> + <title>Robustness</title> + <para> + The protocol, as currently constituted, is not robust against + the embedder crashing. This will result in the embedder + window being destroyed by the X server, and, as a consequence + client's window being unexpectedly destroyed, which will likely cause the + client to die with a BadWindow error. + </para> + <para> + To fix this requires an X protocol extension which extends + the functionality of <function>XChangeSaveSet()</function> in + two areas: + </para> + <itemizedlist> + <listitem> + <para> + Allow it to be specified that the saved window should be + reparented to the root window rather than to the nearest + parent. (The nearest parent typically being the window + manager's frame window, reparenting to the nearest + parent only saves the client until the window manager + cleans up and destroys the frame window.) + </para> + </listitem> + <listitem> + <para> + Allow it to be specified that the saved window should be + unmapped rather than then mapped. (Without this capability + the client will mapped as a child of the root window, + which will be confusing to the user.) + </para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Sensitivity</title> + <para> + Toolkits such as Qt and GTK+ have a concept of disabled + widgets. This notion is typically hierarchical, so if + the embedder or a ancestry of the embedder becomes + insensitive, widgets inside the client should be displayed as, + and act insensitive as well. + </para> + </sect2> + <sect2> + <title>Directional focusing</title> + <para> + Some toolkits, such as GTK+, support, along with the standard + concept of a focus chain, the idea of <firstterm>directional + focusing</firstterm>; it's possible in some cases to navigate + focus using the arrow keys. To do this perfectly, you need + to have information about the coordinates of the original + focus window, which is hard to do in an embedding context, + but a good approximation is to, when focusing into a + container, provide the side of the container where focus + is coming from and to focus the "middle widget" on this side. + </para> + <para> + This could be supported by adding an extra data field to + to the XEMBED_FOCUS_FIRST/XEMBED_FOCUS_LAST subtypes + of XEMBED_FOCUS_IN and to XEMBED_FOCUS_NEXT and + XEMBED_FOCUS_PREV, which would contain: + </para> + <programlisting><!-- +-->/* Directions for focusing */ +#define XEMBED_DIRECTION_DEFAULT 0 +#define XEMBED_DIRECTION_UP_DOWN 1 +#define XEMBED_DIRECTION_LEFT_RIGHT 2<!-- + --></programlisting> + <para> + Applications supporting only normal tab focusing would always + pass XEMBED_DIRECTION_DEFAULT and treat all received + directions as XEMBED_DIRECTION_DEFAULT. + </para> + <para> + The argument against supporting this is that it's a rather + confusing feature to start with (many widgets eat arrow keys + for other purposes), and becomes more confusing if you have + a application containing widgets from different toolkits, + some of which support it, some of which don't. + </para> + </sect2> + <sect2> + <title>Modal dialogs</title> + <para> + The specification doesn't have any provisions for handling the + case where an embedded client wants to put up a dialog. Such a + dialog should be transient-for the real toplevel window, and, + if modal, should block the entire toplevel window. To fully + implement this, you would need some concept of an application + that spanned multiple toplevel windows in multiple clients. + </para> + </sect2> + <sect2> + <title>Propagation of key presses</title> + <para> + It's frequently useful to have key bindings that trigger on + a widget if the focus is on a child of that widget. For + instance, <keysym>Control</keysym><keysym>PageUp</keysym> + and <keysym>Control</keysym><keysym>PageUp</keysym> switch + pages in a notebook widget when the focus is on a child + of the notebook. The XEmbed spec currently has no handling + of this situation. + </para> + <para> + The simplest solution would be to specify that if the client + widget doesn't handle a key press sent to it, it then sends + the event back to the embedder. Some care would be required + in the embedder handle infinite loops, but it shouldn't + be that bad. + </para> + </sect2> + <sect2> + <title>Handling of toplevel modes</title> + <para> + GTK+-2.0 contains a feature for key navigation of tooltips + where Control-F1 toggles a "tooltips keyboard mode" where + the tooltip for the currently focused window is displayed. + There is no way of propagating this across XEMBED. + This feature could clearly be implemented the same + way as XEMBED_WINDOW_ACTIVATE, but adding a pair of + messages for every feature of this type seems excessive. + </para> + <para> + A possible alternate idea would be to add a _XEMBED_STATE + property that the embedder sets on the client window which + is a list of atoms. This could actually be used to + replace XEMBED_WINDOW_ACTIVATE, and XEMBED_MODALITY_ON, + simplifying the protocol. + </para> + <para> + There are some race conditions in maintaining this property + if the client is allowed to reparent itself out of the + embedder that would have to be considered. + </para> + </sect2> + </sect1> + <appendix id="changes"> + <title>Change history</title> + <formalpara> + <title>"Version 1.0 DRAFT 1", 22 April 2000, Matthias Ettrich</title> + <para> + </para> + </formalpara> + <formalpara> + <title>"Version 1.0 DRAFT 2", 15 August 2000, Matthias Ettrich</title> + <para> + </para> + </formalpara> + <formalpara> + <title>Version 0.5, 19 April 2002, Owen Taylor</title> + <para> + <itemizedlist> + <listitem> + <para> + Add the life-cycle chapter, including _XEMBED_INFO + property, and the XEMBED_MAPPED flags. + </para> + </listitem> + <listitem> + <para> + Define the data2 for XEMBED_EMBEDDED_NOTIFY to be the + protocol version in use. + </para> + </listitem> + <listitem> + <para> + Replaced XEMBED_GRAB_KEY scheme for handling accelerators + with XEMBED_REGISTER_ACCELERATOR. + </para> + </listitem> + <listitem> + <para> + Removed text "This also means that the client has to + prepare for becoming visible anytime without filing a map + request itself" from the description of + XEMBED_EMBEDDED_NOTIFY". + </para> + </listitem> + <listitem> + <para> + Added text about the independence of FOCUS_IN/OUT and + ACTIVATE/DEACTIVATE to the description of + XEMBED_WINDOW_ACTIVATE / XEMBED_WINDOW_DEACTIVATE. + </para> + </listitem> + <listitem> + <para> + Added note about fields in WMNormalHints not necessarily + being obeyed by embedders. + </para> + </listitem> + <listitem> + <para> + Removed mention of XEMBED_PROCESS_NEXT_EVENT, which is + no longer part of the protocol. + </para> + </listitem> + <listitem> + <para> + Added definitions of "Active" and "Focused" to the + definitions section. + </para> + </listitem> + <listitem> + <para> + Added issues and change history sections. + </para> + </listitem> + <listitem> + <para> + Lots of textual editing for clarity, style consistency. + </para> + </listitem> + <listitem> + <para> + Converted to docbook format. + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + </appendix> +</article> |