[Texmacs-dev] Towards the TMGUI API

[Joris van der Hoeven]

Continuing my thoughts, I think that we indeed should
start with formulating a precise definition of the "TMGUI API".
The purpose of this API is to describe what TeXmacs needs from the GUI.
It might describe what TeXmacs gives back to the GUI.
It does *not* describe the TeXmacs API (embedding TeXmacs
in extern applications will be dealt with later).

At the end, it should be possible to compile any concrete TMGUI
independently from TeXmacs, be it as a static or shared library,
or as an independent program which can be invoked via a pipe.
In particular, the TMGUI API should not rely on TeXmacs data types,
although we will probably make an exception for the first version.

---------------------------------------------------------------------------

The TMGUI API should offer the following functionality:

  * The interface with the window manager.

  * An abstract set of widget construction routines.

  * An interface for the main TeXmacs widget, comprising
    - A way to send events to the main widget.
    - An implementation of the abstract ps_device class.
    - A way to receive events from the main widget for changing menus, etc.

  * Additional global services (selections, changing pointer shape, etc.)

---------------------------------------------------------------------------

The TMGUI exports four main classes:

  * tmgui_application : the global server with its services.

  * tmgui_display     : an X-like display with its services.

  * tmgui_widget      : a blackbox class; a safe pointer to a structure
                        which may depend on the actual GUI.

  * tmgui_texmacs     : an abstract class with all methods for
                        the interface with TeXmacs.
                        edit_interface will inherit from this class.

---------------------------------------------------------------------------

The tmgui_application class should contain the following functionality:

  * A way to start and end the application.

  * Support for opening and closing tmgui_displays.

---------------------------------------------------------------------------

The tmgui_display class should contain the following functionality:

  * Getting information about the display and initializing it.

  * Support for creating, destroying, mapping and unmapping windows
    with a particular tmgui_widget in it.

  * Clipboard for setting and getting selections.

  * A way to deal with colormaps? (I would prefer to get rid of this,
    so that everything is just plain rgb).

  * Font handling? (Not really needed at a first stage, but we might
    want this later on).

  * Miscellaneous services like help balloons, setting the pointer,
    or dialogues.

---------------------------------------------------------------------------

The tmgui_widget class is a black box class without particular
functionality. We provide widget construction routines and
allow widgets to be passed as parameters.

We have to decide whether the widget construction routines should
be global routines or member functions of tmgui_application or
tmgui_display.

---------------------------------------------------------------------------

The tmgui_texmacs class contains the following functionality

  * Input slots for
    - keyboard events;
    - keyboard focus events;
    - mouse events;
    - repaint events;
    - attachment events
      (to which canvas do we belong? where are the menus?).

  * Output slots for
    - drawing graphics to a ps_device;
    - changes in the menu bar, icon bars, popup menus and footer;
    - dialogue boxes, which might be part of the footer.

---------------------------------------------------------------------------

The following modifications might be made in the ps_device class:

  * Changing the way we deal with coordinates.

  * Support for pdf-like information (hyperlinks and so).

  * Support of additional ways to deal with fonts,
    which may be platform specific.

  * Support of external plugins for drawing graphics
    (like ghostscript, but one might also consider things like OpenGL).

However, non of these changes are urgent, so we may postpone them
to a second version of the TMGUI API.

---------------------------------------------------------------------------

I think that I have been more or less complete, although everything
still has to be specified in greater detail. Please let me know
if you think that something is missing, or if you think that
certain changes are needed.

<Joris>