X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=info%2Fexternal-widget.info;h=e003b3aa794a342a6598954c86a6164c0c15fc44;hp=e7ebc608f9dacc6647a096e0fe5a6545fedddda8;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=de1ec4b272dfa3f9ef2c9ae28a9ba67170d24da5 diff --git a/info/external-widget.info b/info/external-widget.info index e7ebc60..e003b3a 100644 --- a/info/external-widget.info +++ b/info/external-widget.info @@ -1,4 +1,4 @@ -This is ../info/external-widget.info, produced by makeinfo version 4.0 +This is ../info/external-widget.info, produced by makeinfo version 4.6 from external-widget.texi. INFO-DIR-SECTION XEmacs Editor @@ -18,6 +18,7 @@ powerful replacement for standard text widgets. * Using an External Client Widget:: * External Client Widget Resource Settings:: * Motif-Specific Info About the External Client Widget:: +* External Client Widget Internals::  File: external-widget.info, Node: Using an External Client Widget, Next: External Client Widget Resource Settings, Prev: Top, Up: Top @@ -25,10 +26,10 @@ File: external-widget.info, Node: Using an External Client Widget, Next: Exter 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 `-lextcli_Xm'. Another is designed for non-Motif -applications that still use the X toolkit; it is linked with the option +There are three different implementations of the external client widget. +One is designed for use in Motif applications and is linked with the +option `-lextcli_Xm'. Another is designed for non-Motif applications +that still use the X toolkit; it is linked with the option `-lextcli_Xt'. The third is designed for applications that do not use the X toolkit; it is linked with the option `-lextcli_Xlib'. In order to use an external client widget in a client program that uses the X @@ -59,9 +60,9 @@ File: external-widget.info, Node: External Client Widget Resource Settings, Ne 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: +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: `deadShell (class DeadShell)' A boolean resource indicating whether the last request to the @@ -110,12 +111,12 @@ are primarily for handling query-geometry and geometry-manager requests made by parent or child widgets.  -File: external-widget.info, Node: Motif-Specific Info About the External Client Widget, Prev: External Client Widget Resource Settings, Up: Top +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 Motif-Specific Info About the External Client Widget **************************************************** - By default, the external client widget has navigation type +By default, the external client widget has navigation type `XmTAB_GROUP'. The widget traversal keystrokes are modified slightly from the @@ -126,12 +127,121 @@ the Motif text widget. The traversal keystrokes `Ctrl-' and `Shift-' are silently filtered by the external client widget and are not seen by Emacs. + +File: external-widget.info, Node: External Client Widget Internals, Prev: Motif-Specific Info About the External Client Widget, Up: Top + +External Client Widget Internals +******************************** + +The following text is lifted verbatim from Ben Wing's comments in +`ExternalShell.c'. + + This is a special Shell that is designed to use an externally- +provided window created by someone else (possibly another process). +That other window should have an associated widget of class +ExternalClient. The two widgets communicate with each other using +ClientMessage events and properties on the external window. + + Ideally this feature should be independent of Emacs. Unfortunately +there are lots and lots of specifics that need to be dealt with for +this to work properly, and some of them can't conveniently be handled +within the widget's methods. Some day the code may be rewritten so +that the embedded-widget feature can be used by any application, with +appropriate entry points that are called at specific points within the +application. + + This feature is similar to the OLE (Object Linking & Embedding) +feature provided by MS Windows. + + Communication between this shell and the client widget: + + Communication is through ClientMessage events with message_type +EXTW_NOTIFY and format 32. Both the shell and the client widget +communicate with each other by sending the message to the same window +(the "external window" below), and the data.l[0] value is used to +determine who sent the message. + + The data is formatted as follows: + + data.l[0] = who sent this message: external_shell_send (0) or + external_client_send (1) data.l[1] = message type (see enum +en_extw_notify below) data.l[2-4] = data associated with this message + + EventHandler() handles messages from the other side. + + extw_send_notify_3() sends a message to the other side. + + extw_send_geometry_value() is used when an XtWidgetGeometry structure + needs to be sent. This is too much data to fit into a +ClientMessage, so the data is stored in a property and then +extw_send_notify_3() is called. + + extw_get_geometry_value() receives an XtWidgetGeometry structure +from a property. + + extw_wait_for_response() is used when a response to a sent message +is expected. It looks for a matching event within a particular +timeout. + + The particular message types are as follows: + + 1) extw_notify_init (event_window, event_mask) + + This is sent from the shell to the client after the shell realizes +its EmacsFrame widget on the client's "external window". This tells +the client that it should start passing along events of the types +specified in event_mask. event_window specifies the window of the +EmacsFrame widget, which is a child of the client's external window. + + extw_notify_init (client_type) + + When the client receives an extw_notify_init message from the shell, +it sends back a message of the same sort specifying the type of the +toolkit used by the client (Motif, generic Xt, or Xlib). + + 2) extw_notify_end () + + This is sent from the shell to the client when the shell's +EmacsFrame widget is destroyed, and tells the client to stop passing +events along. + + 3) extw_notify_qg (result) + + This is sent from the client to the shell when a QueryGeometry +request is received on the client. The XtWidgetGeometry structure +specified in the QueryGeometry request is passed on in the +EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the +external window. result is unused. + + In response, the shell passes the QueryGeometry request down the +widget tree, and when a response is received, sends a message of type +extw_notify_qg back to the client, with result specifying the +GeometryResult value. If this value is XtGeometryAlmost, the returned +XtWidgetGeometry structure is stored into the same property as above. +[BPW is there a possible race condition here?] + + 4) extw_notify_gm (result) + + A very similar procedure to that for extw_notify_qg is followed when +the shell's RootGeometryManager method is called, indicating that a +child widget wishes to change the shell's geometry. The +XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER +property. + + 5) extw_notify_focus_in (), extw_notify_focus_out () + + These are sent from the client to the shell when the client gains or +loses the keyboard focus. It is done this way because Xt maintains its +own concept of keyboard focus and only the client knows this +information. +  Tag Table: Node: Top232 -Node: Using an External Client Widget662 -Node: External Client Widget Resource Settings2377 -Node: Motif-Specific Info About the External Client Widget5120 +Node: Using an External Client Widget699 +Node: External Client Widget Resource Settings2410 +Node: Motif-Specific Info About the External Client Widget5150 +Node: External Client Widget Internals5961  End Tag Table