+\1f
+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.
+