4 Embedding life cycle #
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.
The currently defined bit in the
flags field is:
/* Flags for _XEMBED_INFO */ #define XEMBED_MAPPED (1 << 0)
- XEMBED_MAPPED
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.)
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
parentfield 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
windowfield being the current client and theparentfield being a different window, this indicates the end of the protocol.The client can destroy its window.