xembed: Merge import from CVS

3 files changed, 1429 insertions, 0 deletions

diff --git a/xembed/spec/.cvsignore b/xembed/spec/.cvsignore
new file mode 100644
index 0000000..4879615
--- /dev/null
+++ b/xembed/spec/.cvsignore
@@ -0,0 +1,5 @@
+Makefile.in
+Makefile
+*.stamp
+*.ps
+html
diff --git a/xembed/spec/Makefile.am b/xembed/spec/Makefile.am
new file mode 100644
index 0000000..9611f10
--- /dev/null
+++ b/xembed/spec/Makefile.am
@@ -0,0 +1,17 @@
+EXTRA_DIST = xembed-spec.xml
+
+html-build.stamp: xembed-spec.xml
+	sdir=`cd $(srcdir) && pwd` &&           \
+	rm -rf html && mkdir html &&		\
+	cd html &&				\
+	docbook2html $$sdir/xembed-spec.xml &&	\
+	touch ../html-build.stamp
+
+xembed-spec.ps: xembed-spec.xml
+	docbook2ps $(srcdir)/xembed-spec.xml
+
+all-local: html-build.stamp xembed-spec.ps
+
+clean-local:
+	rm -rf html-build.stamp html xembed-spec.ps
+
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 &lt;&lt; 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 &lt;&lt; 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 &lt;&lt; 0)
+#define XEMBED_MODIFIER_CONTROL  (1 &lt;&lt; 1)
+#define XEMBED_MODIFIER_ALT      (1 &lt;&lt; 2)
+#define XEMBED_MODIFIER_SUPER    (1 &lt;&lt; 3)
+#define XEMBED_MODIFIER_HYPER    (1 &lt;&lt; 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 &lt;&lt; 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 &lt;X11/Xlib.h&gt;
+
+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 &lt;X11/Xlib.h&gt;
+
+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 &lt;X11/Xlib.h&gt;
+
+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(&amp;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, &amp;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>