Subject: the new internal command execution interface

From: Dominik Vogt <[email-masked]>
Date: Wed, 11 Sep 2002 12:24:34 +0200

First a word of warning:  although the sources compile again, the
work is by no means complete.  There are definitely a lot of nasty
bugs yet.

Now to the details.  I initially started this work to make fvwm
fully functional in the menu loop with the mid term goal of making
tear off menus behave like any other windows.  This required to
remove all the global variables that were used to pass vital
information about the execution context around (Event, Fw,
lastTimestamp and others).

The new code consits of three central parts:

 * An event handling wrapper library FEvent.[ch] which hides the
   X envent handling functions and stores some extra information.

 * A new module execcontext.[ch] that provides a structure that
   holds all information a builtin command or an event handler
   needs to know to do its job.

 * The new builtin command and event handler interface (formerly
   F_CMD_ARGS and (void)).

Basically, executing anything now works like this:

 * An action is triggered (by an X event, a module, the scheduler,
   or other sources like startup or garbage_collection).

 * Depending on the action's source, either execute_function() or
   dispatch_event() is called.

 * Both functions assemble an exec_context_t structure with the
   relevant execution information.  Note that this structure type
   is *read only* everywhere.  If any members have to be changed,
   the function exc_clone_context() must be called to create a
   (read only) copy with some values changed.

 * The structure (exc) is passed down into any function that needs
   to know something about the context of execution.  For event
   handlers, the structure is wrapped in another structure to
   allow extending the event handler interface without much effort
   in the future.

 * As a side effect, it's no longer possible to pass values up to
   the caller.  Any new code should try very hard to avoid this.

 * Thus, it is no longer possible to change members of the event
   structure.  To do this, build up a new event structure in local
   memory and call fev_fake_event, e.g.

     XEvent e = *exc->e.etrigger;
     e.xbutton.x = 0;
     e.xbutton.y = 0;
     few_fake_event(&e);

   which is equivalent to the old way:

     Event.xbutton.x = 0;
     Event.xbutton.y = 0;

This is the structure's definition (refined for readability).

	typedef struct
	{
		exec_context_type_t type;
		struct
		{
			XEvent *etrigger;
			XEvent *elast;
		} x;
		struct
		{
			FvwmWindow *fw;
			Window w;
			unsigned long wcontext;
		} w;
		struct
		{
			int modnum;
		} m;
	} exec_context_t;

 * type:  an enum that indicates the original source of the action,
   e.g. EXCT_EVENT or EXCT_MODULE.  I'm not sure this information
   is useful, so I may remove it.
 * x.etrigger:  a copy of the event that originally triggered the
   action.
 * x.elast:  always points to the latest event received from the
   X server.  At the beginning of execution, the contents of
   *e.last are always identical to the contents of *x.etrigger
   (although the pointers are different).
 * w.fw, w.w, w.wcontext:  the context FvwmWindow, Window, and
   context mask.
 * m.modnum:  the module number that caused the action or -1.

References:

  * FEvent.h for an overview of the event handling layer.
  * execcontext.h for the available exec_context_t handling
    function.
  * functions.c (execute_function... functions) for the new
    function execution interface including some convenience
    functions.
  * conditionals.c for some examples.

Notes:

  * FEvent.h has an additional iterface that is only exported if
    FEVENT_PRIVILEGED_ACCESS is defined when including it.  This
    must be accessed *only* from execcontext.c.
  * DeferExecution is now called centrally in functions.c and
    *must not* be called externally.

Hopefully I'll get most functionality running this evening.  Until
then, many, many things are broken.  If you feel like trying it
out (not recommended unless you're a developer) write down a list
of things that don't work, but please don't bother me with them
yet.  I'll announce when I think that public testing makes sense.

Bye

Dominik ^_^  ^_^

 --
Dominik Vogt, mail: [email-masked], phone: 0721/91374-382
Schlund + Partner AG, Erbprinzenstr. 4-12, D-76133 Karlsruhe
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]