\input texinfo  @c -*-texinfo-*-
@setfilename ../info/external-widget.info
@settitle The External Client Widget

@ifinfo
@dircategory XEmacs Editor
@direntry
* External Widget: (external-widget).   External Client Widget.
@end direntry
@end ifinfo

@node Top, Using an External Client Widget,, (dir)

An @dfn{external client widget} is a widget that is part of another program
but functions as an Emacs frame.  This is intended to be a more
powerful replacement for standard text widgets.

@menu
* Using an External Client Widget::
* External Client Widget Resource Settings::
* Motif-Specific Info About the External Client Widget::
* Example Program Using the External Client Widget::
@end menu


@node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
@chapter Using an External Client Widget

There are three different implementations of the external client widget.
One is designed for use in Motif applications and is linked with the
option @code{-lextcli_Xm}.  Another is designed for non-Motif
applications that still use the X toolkit; it is linked with the option
@code{-lextcli_Xt}.  The third is designed for applications that do not
use the X toolkit; it is linked with the option @code{-lextcli_Xlib}.
In order to use an external client widget in a client program that uses
the X toolkit (i.e. either of the first two options described above),
simply create an instance of widget type ExternalClient and link your
program with the appropriate library.  The corresponding header file is
called @file{ExternalClient.h}.

Documentation still needs to be provided for using the raw Xlib
version of the external client widget.

The external client widget will not do anything until an instance of
Emacs is told about this particular widget.  To do that, call the
function @code{make-frame}, specifying a value for the frame parameter
@code{window-id}.  This value should be a string containing the decimal
representation of the widget's X window ID number (this can be obtained
by the Xt function @code{XtWindow()}).  In order for the client program
to communicate this information to Emacs, a method such as sending a
ToolTalk message needs to be used.

Once @code{make-frame} has been called, Emacs will create a frame
that occupies the client widget's window.  This frame can be used just
like any other frame in Emacs.


@node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top
@chapter External Client Widget Resource Settings

The external client widget is a subclass of the Motif widget XmPrimitive
and thus inherits all its resources.  In addition, the following new
resources are defined:

@table @samp
@item deadShell (class DeadShell)
A boolean resource indicating whether the last request to the
ExternalShell widget that contains the frame corresponding to this
widget timed out.  If true, no further requests will be made (all
requests will automatically fail) until a response to the last
request is received.  This resource should normally not be set by the
user.

@item shellTimeout (class ShellTimeout)
A value specifying how long (in milliseconds) the client should wait
for a response when making a request to the corresponding ExternalShell
widget.  If this timeout is exceeded, the client will assume that the
shell is dead and will fail the request and all subsequent requests
until a response to the request is received.  Default value is 5000,
or 5 seconds.
@end table

The shell that contains the frame corresponding to an external client
widget is of type ExternalShell, as opposed to standard frames, whose
shell is of type TopLevelShell.  The ExternalShell widget is a direct
subclass of Shell and thus inherits its resources.  In addition, the
following new resources are defined:

@table @samp
@item window (class Window)
The X window ID of the widget to use for this Emacs frame.  This is
normally set by the call to @code{x-create-frame} and should not be
modified by the user.

@item deadClient (class DeadClient)
A boolean resource indicating whether the last request to the
corresponding ExternalClient widget timed out.  If true, no further
requests will be made (all requests will automatically fail) until a
response to the last request is received.  This resource should
normally not be set by the user.

@item ClientTimeout (class ClientTimeout)
A value specifying how long (in milliseconds) the shell should wait
for a response when making a request to the corresponding ExternalClient
widget.  If this timeout is exceeded, the shell will assume that the
client is dead and will fail the request and all subsequent requests
until a response to the request is received.  Default value is 5000,
or 5 seconds.
@end table

Note that the requests that are made between the client and the shell
are primarily for handling query-geometry and geometry-manager requests
made by parent or child widgets.


@node Motif-Specific Info About the External Client Widget, Example Program Using the External Client Widget, External Client Widget Resource Settings, Top
@chapter Motif-Specific Info About the External Client Widget

By default, the external client widget has navigation type
@samp{XmTAB_GROUP}.

The widget traversal keystrokes are modified slightly from the standard
XmPrimitive keystrokes.  In particular, @kbd{@key{TAB}} alone does not
traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
but functions like a normal @key{TAB} in Emacs.  This follows the
semantics of the Motif text widget.  The traversal keystrokes
@kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
the external client widget and are not seen by Emacs.


@node Example Program Using the External Client Widget, , Motif-Specific Info About the External Client Widget, Top
@chapter Example Program Using the External Client Widget

This is a very simple program.  It has some issues with exiting.
Be careful to destroy the Emacs frame in the client window before
exiting the client program.

@example
/*
   XEmacsInside.c

   Copyright (C) 2002 Free Software Foundation

   This program is part of XEmacs.  XEmacs is free software.  See the
   file COPYING that came with XEmacs for conditions on redistribution.

   This is an example of the XEmacs external widget facility.

   It uses libextcli-Xt.a to interface to the X Toolkit Intrinsics.

   Compile with

   gcc -I/path/to/XEmacs/source/src -L/path/to/XEmacs/build/src -static \
       -lextcli_Xt -lXt -lX11 -lSM -lICE \
       -o XEmacsInside XEmacsInside.c

   Run it with the resource "*input: True" and a reasonable geometry spec.
   It pops up a window, and prints a Lisp form on stdout.  Eval the form
   in an XEmacs configured with --external-widget.

   Written by Stephen J. Turnbull <stephen@@xemacs.org>

   Based on simple_text.c from _The Motif Programming Manual_ by Heller
   and Ferguson, O'Reilly.
*/

#include <stdio.h>

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <X11/Shell.h>

#include "ExternalClient.h"

main (int argc, char *argv[])
@{
  Widget toplevel, emacs;
  XtAppContext app;

  XtSetLanguageProc (NULL, NULL, NULL);

  toplevel = XtVaOpenApplication (&app, "Demo",
				  NULL, 0, &argc, argv,
				  NULL, sessionShellWidgetClass,
				  NULL);

  emacs = XtVaCreateManagedWidget ("externalWidget", externalClientWidgetClass,
				   toplevel,
				   NULL);

  XtRealizeWidget (toplevel);

  printf ("(make-frame '(window-id \"%d\"))\n", XtWindow(emacs));

  XtAppMainLoop (app);
@}

/* This function doesn't belong here but somehow it's not getting resolved
   from the library. */
void
fatal (char *msg)
@{
  fprintf (stderr, "%s", msg);
  exit (1);
@}
@end example


@summarycontents
@contents
@bye