Status XagQueryVersion(
  Display*      dpy,
  int*          major_version_return,
  int*          minor_version_return);

XagQueryVersion sets major_version_return and minor_version_return to the major and minor Application Group protocol version supported by the server. If the Xag library is compatible with the version returned by the server it returns non-zero. If dpy does not support the Application Group extension, or if the server and library protocol versions are incompatible, or if there was an error during communication with the server, it returns zero. No other Xag functions may be called before this function. If a program violates this rule, the effects of all subsequent Xag calls that it makes are undefined.

---

Note: An embedding manager in, e.g. a Personal Computer Web Browser, will need to open a connection to the Personal Computer X server by calling XOpenDisplay() before using the Application Group extension.

---

An embedding manager such as a web browser that intends to embed programs in an Application Group should create the Application Group with XagCreateEmbeddedApplicationGroup.

Status XagCreateEmbeddedApplicationGroup(
  Display*      dpy,
  VisualID      root_visual,
  Colormap      default_colormap,
  unsigned long black_pixel,
  unsigned long white_pixel,
  XAppGroup*    app_group_return);

XagCreateEmbeddedApplicationGroup creates an Application Group for an embedding manager with the attributes specified. It also sets the default_root attribute to DefaultRoot(dpy, DefaultsScreen(dpy)) and the single_screen and app_group_leader attributes to True. It returns the Application Group ID in app_group_return.

You can create an Application Group without intending to do embedding. One reason for doing this is to give a group of clients their own font-path.

---

Note: A special font-path can be created by creating an Application Group, getting an Authorization using XSecurityGenerateAuthorization, and then running `xset fp+ <new font path>' as a member of the Application Group. Font-path elements added in this way will be “private” to the Application Group.

---

Status XagCreateNonembeddedApplicationGroup(
  Display*      dpy,
  XAppGroup*    app_group_return);

An Application Group created with XagCreateNonembeddedApplicationGroup will have the default_root, root_visual, and default_colormap attributes all set to None; the single_screen and app_group_leader attributes are set to False, and the black_pixel and white_pixel attributes are not used since the default_colormap attribute is None.

To destroy an Application Group use XagDestroyApplicationGroup.

Status XagDestroyApplicationGroup(
  Display*      dpy,
  XAppGroup     app_group);

The Application Group specified by app_group is destroyed. If the Application Group was created using XagCreateEmbeddingApplicationGroup, i.e. and therefore the app_group_leader attribute is True, all programs that are members of the Application Group are killed as if a KillClient request had been issued.

To retrieve the attributes of an Application Group use XagGetApplicationGroupAttributes.

Status XagGetApplicationGroupAttributes(
  Display*      dpy,
  XAppGroup     app_group,
  ...);

XagGetApplicationGroupAttributes is a varargs function that retrieves the Application Group's attributes specified in the vararg parameter list.

The attributes that may be specified are: XagNappGroupLeader, XagNsingleScreen, XagNdefaultRoot, XagNrootVisual, XagNdefaultColormap, XagNblackPixel, and XagNwhitePixel; which correspond to app_group_leader, single_screen, default_root, root_visual, default_colormap, black_pixel, and white_pixel respectively. See “AppGroupCreate” in Chapter 3 for a description of each attribute.

The types for each of the parameters are pointers to the following:

Example:

...
Boolean app_group_leader, single_screen;
Window default_root;
VisualID root_visual;
Colormap default_colormap;
Pixel black_pixel, white_pixel;
...
status = XagGetApplicationGroupAttributes(dpy, app_group,
  XagNappGroupLeader, &app_group_leader,
  XagNsingleScreen, &single_screen,
  XagNdefault_root, &default_root,
  XagNrootVisual, &root_visual,
  XagNdefaultColormap, &default_colormap,
  XagNblackPixel, &black_pixel,
  XagNwhitePixel, &white_pixel,
  NULL);
...

To determine which Application Group a resource (such as a window) belongs to, use XagQueryApplicationGroup.

Status XagQueryApplicationGroup(
  Display*      dpy,
  XID           resource,
  XAppGroup*    app_group_return);

The Application Group is returned in app_group_return, if the resource is not in any Application Group then app_group_return will be set to None.

To associate an X Window ID with a system-specific window ID, such as a HWND or a WindowPtr, use XagCreateAssociation.

Status XagCreateAssociation(
  Display*      dpy,
  Window*       window_return,
  void*         system_window);

The window_ret may be used as the target for a ReparentWindow request.

---

Note: Because XReparentWindow is not constrained in the same way that Win32's SetParent and the Macintosh are, there is no reason to call XagCreateAssociation in an X-based embedding manager. As such if XagCreateAssociation is called in a native X program, the window_return will be the same as the system_window, and the implementation may even elect to not generate any protocol.

---

To create an association on the Macintosh:

struct {
  WindowPtr win;
  Rect rect;
} system_window;

system_window.win = win_ptr;
system_window.rect.top = system_window.rect.left = 20;
system_window.rect.bottom = 180;
system_window.rect.right = 380;

status = XagCreateAssociation (dpy, &window, (void*)&system_window);

To create an association using a Win16, Win32, or OS/2 PM:

HWND system_window;
status = XagCreateAssociation (dpy, &window, (void*)&system_window);

To destroy the association created with XagCreateAssociation use XagDestroyAssociation.

Status XagDestroyAssociation(
  Display*      dpy,
  Window        window);

After calling XagDestroyAssociation the window may no longer be used to reparent windows with XReparentWindow.

---

Note: Like XagCreateAssociation, if the native window system is X11 the implementation may elect to not generate any protocol as a result of this function call in order to avoid unintentionally destroying the the system_window that was specified in the prior XagCreateAssociation call.

---