X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=man%2Fexternal-widget.texi;h=817d492ee01c42282551fddf8221a4c44f72a95c;hp=9de5af0ab26111a2c0fd193d7215938a3b30f958;hb=c1fa38c050ef3bd87e784dea66eba3cdac585536;hpb=976b002b16336930724ae22476014583ad022e7d diff --git a/man/external-widget.texi b/man/external-widget.texi index 9de5af0..817d492 100644 --- a/man/external-widget.texi +++ b/man/external-widget.texi @@ -5,7 +5,6 @@ @dircategory XEmacs Editor @direntry * External Widget: (external-widget) External Client Widget. -package. @end direntry @end ifinfo @@ -19,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:: @end menu @@ -112,7 +112,7 @@ 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, , External Client Widget Resource Settings, Top +@node Motif-Specific Info About the External Client Widget, External Client Widget Internals, External Client Widget Resource Settings, Top @chapter Motif-Specific Info About the External Client Widget By default, the external client widget has navigation type @@ -126,6 +126,113 @@ 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 External Client Widget Internals, , Motif-Specific Info About the External Client Widget, Top +@chapter External Client Widget Internals + +The following text is lifted verbatim from Ben Wing's comments in +@file{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. + @summarycontents @contents @bye