XEmbed Protocol Specification

Mathias Ettrich


Owen Taylor


Version 0.5

Table of Contents

Rationale and discussion
Window activation state
Keyboard focus
Tab focus chain
Keyboard short cuts / accelerators
Drag and drop (XDND)
Embedding life cycle
Message Specifications
Handling errors
Forwarding X Events
Sending XEmbed messages
Implementation of modality
Clarify function of timestamps
Complexity of accelerator handling
Infinite loops in focusing
Directional focusing
Modal dialogs
Propagation of key presses
Handling of toplevel modes
A. Change history


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:

  1. Support for out-of process controls, written in any toolkit or even plain Xlib.

  2. Support for in-process-controls when mixing different toolkits in one process.

  3. Smooth integration of the embedding application and embedded client in areas such as input device handling and visual feedback.

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

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.

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.