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
XReparentWindow() to reparent the client
window into the embedder window.
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.
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:
Table 1. _XEMBED_INFO
| Field | Type | Comments |
|---|---|---|
| version | CARD32 | The protocol version |
| flags | CARD32 | A bitfield of flags |
The version 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 (version, max version supported by embedder).
The version number corresponding to the current version of the
protocol is 0.
[Should the version be defined as (Major << 16 | Minor) ?]
The currently defined bit in the
flags field is:
/* Flags for _XEMBED_INFO */ #define XEMBED_MAPPED (1 << 0)
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.)
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.
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.
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:
| Not focused |
| Not active |
| Modality off |
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
width_inc,
height_inc,
min_aspect, and
max_aspect fields are examples of
fields from WMNormalHints that are unlikely to be supported
by embedders.
The protocol ends in one of three ways:
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
parent field of the
XReparentEvent 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.
The client can reparent its window out of the embedder
window. If the embedder receives a ReparentNotify signal
with the window field being the
current client and the parent
field being a different window, this indicates the end
of the protocol.
[ 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. ]
The client can destroy its window.