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

FieldTypeComments
versionCARD32The protocol version
flagsCARD32A 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)
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.)

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:

  1. 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.

  2. 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. ]

  3. The client can destroy its window.