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

   1 This is ../info/external-widget.info, produced by makeinfo version 4.8
   2 from external-widget.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * External Widget: (external-widget) External Client Widget.
   7 END-INFO-DIR-ENTRY
   8
   9 \1f
  10 File: external-widget.info,  Node: Top,  Next: Using an External Client Widget,  Up: (dir)
  11
  12    An "external client widget" is a widget that is part of another
  13 program but functions as an Emacs frame.  This is intended to be a more
  14 powerful replacement for standard text widgets.
  15
  16 * Menu:
  17
  18 * Using an External Client Widget::
  19 * External Client Widget Resource Settings::
  20 * Motif-Specific Info About the External Client Widget::
  21 * External Client Widget Internals::
  22
  23 \1f
  24 File: external-widget.info,  Node: Using an External Client Widget,  Next: External Client Widget Resource Settings,  Prev: Top,  Up: Top
  25
  26 1 Using an External Client Widget
  27 *********************************
  28
  29 There are three different implementations of the external client widget.
  30 One is designed for use in Motif applications and is linked with the
  31 option `-lextcli_Xm'.  Another is designed for non-Motif applications
  32 that still use the X toolkit; it is linked with the option
  33 `-lextcli_Xt'.  The third is designed for applications that do not use
  34 the X toolkit; it is linked with the option `-lextcli_Xlib'.  In order
  35 to use an external client widget in a client program that uses the X
  36 toolkit (i.e. either of the first two options described above), simply
  37 create an instance of widget type ExternalClient and link your program
  38 with the appropriate library.  The corresponding header file is called
  39 `ExternalClient.h'.
  40
  41    Documentation still needs to be provided for using the raw Xlib
  42 version of the external client widget.
  43
  44    The external client widget will not do anything until an instance of
  45 Emacs is told about this particular widget.  To do that, call the
  46 function `make-frame', specifying a value for the frame parameter
  47 `window-id'.  This value should be a string containing the decimal
  48 representation of the widget's X window ID number (this can be obtained
  49 by the Xt function `XtWindow()').  In order for the client program to
  50 communicate this information to Emacs, a method such as sending a
  51 ToolTalk message needs to be used.
  52
  53    Once `make-frame' has been called, Emacs will create a frame that
  54 occupies the client widget's window.  This frame can be used just like
  55 any other frame in Emacs.
  56
  57 \1f
  58 File: external-widget.info,  Node: External Client Widget Resource Settings,  Next: Motif-Specific Info About the External Client Widget,  Prev: Using an External Client Widget,  Up: Top
  59
  60 2 External Client Widget Resource Settings
  61 ******************************************
  62
  63 The external client widget is a subclass of the Motif widget XmPrimitive
  64 and thus inherits all its resources.  In addition, the following new
  65 resources are defined:
  66
  67 `deadShell (class DeadShell)'
  68      A boolean resource indicating whether the last request to the
  69      ExternalShell widget that contains the frame corresponding to this
  70      widget timed out.  If true, no further requests will be made (all
  71      requests will automatically fail) until a response to the last
  72      request is received.  This resource should normally not be set by
  73      the user.
  74
  75 `shellTimeout (class ShellTimeout)'
  76      A value specifying how long (in milliseconds) the client should
  77      wait for a response when making a request to the corresponding
  78      ExternalShell widget.  If this timeout is exceeded, the client
  79      will assume that the shell is dead and will fail the request and
  80      all subsequent requests until a response to the request is
  81      received.  Default value is 5000, or 5 seconds.
  82
  83    The shell that contains the frame corresponding to an external client
  84 widget is of type ExternalShell, as opposed to standard frames, whose
  85 shell is of type TopLevelShell.  The ExternalShell widget is a direct
  86 subclass of Shell and thus inherits its resources.  In addition, the
  87 following new resources are defined:
  88
  89 `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 `x-create-frame' and should not be
  92      modified by the user.
  93
  94 `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
  98      a response to the last request is received.  This resource should
  99      normally not be set by the user.
 100
 101 `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
 104      ExternalClient widget.  If this timeout is exceeded, the shell
 105      will assume that the client is dead and will fail the request and
 106      all subsequent requests until a response to the request is
 107      received.  Default value is 5000, or 5 seconds.
 108
 109    Note that the requests that are made between the client and the shell
 110 are primarily for handling query-geometry and geometry-manager requests
 111 made by parent or child widgets.
 112
 113 \1f
 114 File: external-widget.info,  Node: Motif-Specific Info About the External Client Widget,  Next: External Client Widget Internals,  Prev: External Client Widget Resource Settings,  Up: Top
 115
 116 3 Motif-Specific Info About the External Client Widget
 117 ******************************************************
 118
 119 By default, the external client widget has navigation type
 120 `XmTAB_GROUP'.
 121
 122    The widget traversal keystrokes are modified slightly from the
 123 standard XmPrimitive keystrokes.  In particular, `<TAB>' alone does not
 124 traverse to the next widget (`Ctrl-<TAB>' must be used instead), but
 125 functions like a normal <TAB> in Emacs.  This follows the semantics of
 126 the Motif text widget.  The traversal keystrokes `Ctrl-<TAB>' and
 127 `Shift-<TAB>' are silently filtered by the external client widget and
 128 are not seen by Emacs.
 129
 130 \1f
 131 File: external-widget.info,  Node: External Client Widget Internals,  Prev: Motif-Specific Info About the External Client Widget,  Up: Top
 132
 133 4 External Client Widget Internals
 134 **********************************
 135
 136 The following text is lifted verbatim from Ben Wing's comments in
 137 `ExternalShell.c'.
 138
 139    This is a special Shell that is designed to use an externally-
 140 provided window created by someone else (possibly another process).
 141 That other window should have an associated widget of class
 142 ExternalClient.  The two widgets communicate with each other using
 143 ClientMessage events and properties on the external window.
 144
 145    Ideally this feature should be independent of Emacs.  Unfortunately
 146 there are lots and lots of specifics that need to be dealt with for
 147 this to work properly, and some of them can't conveniently be handled
 148 within the widget's methods.  Some day the code may be rewritten so
 149 that the embedded-widget feature can be used by any application, with
 150 appropriate entry points that are called at specific points within the
 151 application.
 152
 153    This feature is similar to the OLE (Object Linking & Embedding)
 154 feature provided by MS Windows.
 155
 156    Communication between this shell and the client widget:
 157
 158    Communication is through ClientMessage events with message_type
 159 EXTW_NOTIFY and format 32.  Both the shell and the client widget
 160 communicate with each other by sending the message to the same window
 161 (the "external window" below), and the data.l[0] value is used to
 162 determine who sent the message.
 163
 164    The data is formatted as follows:
 165
 166    data.l[0] = who sent this message: external_shell_send (0) or
 167     external_client_send (1) data.l[1] = message type (see enum
 168 en_extw_notify below) data.l[2-4] = data associated with this message
 169
 170    EventHandler() handles messages from the other side.
 171
 172    extw_send_notify_3() sends a message to the other side.
 173
 174    extw_send_geometry_value() is used when an XtWidgetGeometry structure
 175   needs to be sent.  This is too much data to fit into a
 176 ClientMessage, so the data is stored in a property and then
 177 extw_send_notify_3() is called.
 178
 179    extw_get_geometry_value() receives an XtWidgetGeometry structure
 180 from a    property.
 181
 182    extw_wait_for_response() is used when a response to a sent message
 183 is expected.  It looks for a matching event within a    particular
 184 timeout.
 185
 186    The particular message types are as follows:
 187
 188    1) extw_notify_init (event_window, event_mask)
 189
 190    This is sent from the shell to the client after the shell realizes
 191 its EmacsFrame widget on the client's "external window".  This tells
 192 the client that it should start passing along events of the types
 193 specified in event_mask.  event_window specifies the window of the
 194 EmacsFrame widget, which is a child of the client's external window.
 195
 196    extw_notify_init (client_type)
 197
 198    When the client receives an extw_notify_init message from the shell,
 199 it sends back a message of the same sort specifying the type of the
 200 toolkit used by the client (Motif, generic Xt, or Xlib).
 201
 202    2) extw_notify_end ()
 203
 204    This is sent from the shell to the client when the shell's
 205 EmacsFrame widget is destroyed, and tells the client to stop passing
 206 events along.
 207
 208    3) extw_notify_qg (result)
 209
 210    This is sent from the client to the shell when a QueryGeometry
 211 request is received on the client.  The XtWidgetGeometry structure
 212 specified in the QueryGeometry request is passed on in the
 213 EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the
 214 external window.  result is unused.
 215
 216    In response, the shell passes the QueryGeometry request down the
 217 widget tree, and when a response is received, sends a message of type
 218 extw_notify_qg back to the client, with result specifying the
 219 GeometryResult value.  If this value is XtGeometryAlmost, the returned
 220 XtWidgetGeometry structure is stored into the same property as above.
 221 [BPW is there a possible race condition here?]
 222
 223    4) extw_notify_gm (result)
 224
 225    A very similar procedure to that for extw_notify_qg is followed when
 226 the shell's RootGeometryManager method is called, indicating that a
 227 child widget wishes to change the shell's geometry.  The
 228 XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER
 229 property.
 230
 231    5) extw_notify_focus_in (), extw_notify_focus_out ()
 232
 233    These are sent from the client to the shell when the client gains or
 234 loses the keyboard focus.  It is done this way because Xt maintains its
 235 own concept of keyboard focus and only the client knows this
 236 information.
 237
 238
 239 \1f
 240 Tag Table:
 241 Node: Top\7f232
 242 Node: Using an External Client Widget\7f699
 243 Node: External Client Widget Resource Settings\7f2414
 244 Node: Motif-Specific Info About the External Client Widget\7f5158
 245 Node: External Client Widget Internals\7f5973
 246 \1f
 247 End Tag Table