git.chise.org Git - chise/xemacs-chise.git.1/blob - man/external-widget.texi

   1 \input texinfo  @c -*-texinfo-*-
   2 @setfilename ../info/external-widget.info
   3
   4 @ifinfo
   5 @dircategory XEmacs Editor
   6 @direntry
   7 * External Widget: (external-widget) External Client Widget.
   8 package.
   9 @end direntry
  10 @end ifinfo
  11
  12 @node Top, Using an External Client Widget,, (dir)
  13
  14 An @dfn{external client widget} is a widget that is part of another program
  15 but functions as an Emacs frame.  This is intended to be a more
  16 powerful replacement for standard text widgets.
  17
  18 @menu
  19 * Using an External Client Widget::
  20 * External Client Widget Resource Settings::
  21 * Motif-Specific Info About the External Client Widget::
  22 @end menu
  23
  24
  25 @node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
  26 @chapter Using an External Client Widget
  27
  28 There are three different implementations of the external client widget.
  29 One is designed for use in Motif applications and is linked with the
  30 option @code{-lextcli_Xm}.  Another is designed for non-Motif
  31 applications that still use the X toolkit; it is linked with the option
  32 @code{-lextcli_Xt}.  The third is designed for applications that do not
  33 use the X toolkit; it is linked with the option @code{-lextcli_Xlib}.
  34 In order to use an external client widget in a client program that uses
  35 the X toolkit (i.e. either of the first two options described above),
  36 simply create an instance of widget type ExternalClient and link your
  37 program with the appropriate library.  The corresponding header file is
  38 called @file{ExternalClient.h}.
  39
  40 Documentation still needs to be provided for using the raw Xlib
  41 version of the external client widget.
  42
  43 The external client widget will not do anything until an instance of
  44 Emacs is told about this particular widget.  To do that, call the
  45 function @code{make-frame}, specifying a value for the frame parameter
  46 @code{window-id}.  This value should be a string containing the decimal
  47 representation of the widget's X window ID number (this can be obtained
  48 by the Xt function @code{XtWindow()}).  In order for the client program
  49 to communicate this information to Emacs, a method such as sending a
  50 ToolTalk message needs to be used.
  51
  52 Once @code{make-frame} has been called, Emacs will create a frame
  53 that occupies the client widget's window.  This frame can be used just
  54 like any other frame in Emacs.
  55
  56
  57 @node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top
  58 @chapter External Client Widget Resource Settings
  59
  60 The external client widget is a subclass of the Motif widget XmPrimitive
  61 and thus inherits all its resources.  In addition, the following new
  62 resources are defined:
  63
  64 @table @samp
  65 @item deadShell (class DeadShell)
  66 A boolean resource indicating whether the last request to the
  67 ExternalShell widget that contains the frame corresponding to this
  68 widget timed out.  If true, no further requests will be made (all
  69 requests will automatically fail) until a response to the last
  70 request is received.  This resource should normally not be set by the
  71 user.
  72
  73 @item shellTimeout (class ShellTimeout)
  74 A value specifying how long (in milliseconds) the client should wait
  75 for a response when making a request to the corresponding ExternalShell
  76 widget.  If this timeout is exceeded, the client will assume that the
  77 shell is dead and will fail the request and all subsequent requests
  78 until a response to the request is received.  Default value is 5000,
  79 or 5 seconds.
  80 @end table
  81
  82 The shell that contains the frame corresponding to an external client
  83 widget is of type ExternalShell, as opposed to standard frames, whose
  84 shell is of type TopLevelShell.  The ExternalShell widget is a direct
  85 subclass of Shell and thus inherits its resources.  In addition, the
  86 following new resources are defined:
  87
  88 @table @samp
  89 @item window (class Window)
  90 The X window ID of the widget to use for this Emacs frame.  This is
  91 normally set by the call to @code{x-create-frame} and should not be
  92 modified by the user.
  93
  94 @item deadClient (class DeadClient)
  95 A boolean resource indicating whether the last request to the
  96 corresponding ExternalClient widget timed out.  If true, no further
  97 requests will be made (all requests will automatically fail) until a
  98 response to the last request is received.  This resource should
  99 normally not be set by the user.
 100
 101 @item ClientTimeout (class ClientTimeout)
 102 A value specifying how long (in milliseconds) the shell should wait
 103 for a response when making a request to the corresponding ExternalClient
 104 widget.  If this timeout is exceeded, the shell will assume that the
 105 client is dead and will fail the request and all subsequent requests
 106 until a response to the request is received.  Default value is 5000,
 107 or 5 seconds.
 108 @end table
 109
 110 Note that the requests that are made between the client and the shell
 111 are primarily for handling query-geometry and geometry-manager requests
 112 made by parent or child widgets.
 113
 114
 115 @node Motif-Specific Info About the External Client Widget, , External Client Widget Resource Settings, Top
 116 @chapter Motif-Specific Info About the External Client Widget
 117
 118 By default, the external client widget has navigation type
 119 @samp{XmTAB_GROUP}.
 120
 121 The widget traversal keystrokes are modified slightly from the standard
 122 XmPrimitive keystrokes.  In particular, @kbd{@key{TAB}} alone does not
 123 traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
 124 but functions like a normal @key{TAB} in Emacs.  This follows the
 125 semantics of the Motif text widget.  The traversal keystrokes
 126 @kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
 127 the external client widget and are not seen by Emacs.
 128
 129 @summarycontents
 130 @contents
 131 @bye