/* $XConsortium: README /main/3 1996/07/15 14:00:27 drk $ */

This directory contains the source code for the Exm demonstration widgets.

The Exm demonstration widgets illustrate how to write a Motif widget in C.

If you are interested in writing a Motif widget in C++, you should see the

../ExmCxx directory.  Complete details on the Exm demonstration widgets can

be found in the "OSF/Motif Widget Writer's Guide and Reference" manual. 

We are providing the Exm widget set for educational purposes only.  

Programmers should not use any Exm widgets inside a commercial application.

This README file summarizes the purpose of each file in this directory. 

The end of this README file contains instructions for building the Exm widget

set. 

                           ***************************

                            WIDGETS IN THIS DIRECTORY

                           ***************************

The Exm demonstration widgets is an eight widget set having the following

hierarchy:

                            --------------------Core--------------------

                            |                                          |

                            V                                          V

                       XmPrimitive                                 XmManager

                            |                                          |

                            |                                          |

                            V                                          V

                        ExmSimple------------------------           ExmGrid

                            |                           |

                            V                           V

       -----------------ExmString--------------      ExmPanner

       |                    |                 |

       V                    V                 V

 ExmCommandButton   ExmStringTransfer    ExmMenuButton

       |

       V

 ExmTabButton

*********

ExmSimple

*********

The ExmSimple widget consists of three files: 

   * Simple.c 

   * Simple.h

   * SimpleP.h

The ExmSimple widget renders a rectangle or an oval.  This widget demonstrates 

how to create a 

   * relatively easy Motif widget.

   * primitive widget that can serve as a superclass for other widgets.

   * new representation type.

*********

ExmString

*********

The ExmString widget consists of three files: 

   * String.c

   * String.h

   * StringP.h

The ExmString widget demonstrates how to handle compound strings in Motif

widgets.  The ExmString widget is similar to the XmLabel widget.  

The biggest difference between the two is that an XmLabel can 

render either a compound string or a pixmap but an ExmString can 

render only a compound string.  More specifically, the ExmString 

widget demonstrates how to:

  * use the four recommended resources for handling compound strings.

  * use the XmQTaccessTextual trait.

  * calculate the baselines of each lines of text.

****************

ExmCommandButton

****************

The ExmCommandButton widget consists of three files: 

   * CommandB.c 

   * CommandB.h 

   * CommandBP.h

This widget displays a button that, when activated, initiates a callback.

This widget demonstrates how to

   * create Motif-style button visuals.

   * establish Motif-style actions for buttons. 

   * install the XmQTactivatable trait.

   * install the XmQTtakesDefault trait.

   * establish a simple Motif callback.

*************

ExmMenuButton

*************

The ExmMenuButton widget consists of three files: 

   * MenuB.c

   * MenuB.h

   * MenuBP.h

This widget renders a menu child button that, when activated, initiates

a callback.  This widget demonstrates how to 

   * create a menu child widget, in the style of XmPushButton. 

   * install the XmQTmenuSavvy trait. 

   * call the trait methods of XmQTmenuSystem.

*****************

ExmStringTransfer

*****************

The ExmStringTransfer widget consists of three files: 

   * StringTrans.c

   * StringTrans.h

   * StringTransP.h

This widget renders a compound string.  The ExmStringTransfer widget 

demonstrates how to

   * implement the Uniform Transfer Method (UTM) in a Motif widget.

   * write a widget that supports Drag and Drop.

   * install the XmQTtransfer trait.

*********

ExmPanner

*********

The ExmPanner widget consists of three files: 

   * Panner.c

   * Panner.h

   * PannerP.h

This widget allows users to pan (navigate) through different portions

of another widget.  The ExmPanner widget renders a small rectangle 

inside a widget.  The user may move this rectangle.  As the rectangle 

moves to different portions of its surrounding widget, different 

portions of the target widget will become visible.  The ExmPanner widget

demonstrates how to:

   * write a navigator widget.

   * use the XmQTnavigator trait.

************

ExmTabButton

************

The ExmTabButton widget consists of three files: 

   * TabB.c

   * TabB.h

   * TabBP.h

This widget attaches itself to one side of a parent widget in order

to give the appearance of a tab "growing out of" the parent.  The

ExmTabButton widget is activatable.  It demonstrates how to

   * use the XmQTjoinSide trait.

   * use several Xme drawing functions.

*******

ExmGrid

*******

The ExmGrid widget consists of three files: 

   * Grid.c 

   * Grid.h

   * GridP.h

The ExmGrid widget demonstrates how to

   * write a manager widget. 

   * use the XmQTdialogSavvy trait.

                                 ***********

                                 UIL SUPPORT

                                 ***********

The directory also contains several files pertaining to UIL support of the

Exm widgets.  They are:

   * Exm.uil: a header file that can be included in UIL applications.

              This file defines the API for UIL applications wishing

              to use the Exm widget set.

   * Exm.wml: (not available at Alpha.)  This file can be compiled with

              wml in order to form a new motif.wmd file or a new UIL compiler.

   * ExmMrm.c: contains MrmRegisterClass calls for the Exm widget set.

   * ExmMrm.h: a header file that provides an interface to the code in the

               ExmMrm.c file.

                         ***************************

                         BUILDING THE EXM WIDGET SET

                         ***************************

This directory contains an Imakefile.  In order to build the Exm widget set

from this Imakefile, you should follow these steps: 

   1. $ make Makefile    # This command should create a true Makefile.

   2. $ make includes

   3. $ make depend

   4. $ make

The "make" command should compile all of the source code files in the directory.

The resulting widget object files will be archived into a library file named 

libExm.a.  The ExmMrm.o object file will be archived into a library file named 

libMrm.a.  In order to exercise the code in the libraries, you must build an

application stored in one of the following subdirectories:

   * simple_app

   * exm_app_in_c

   * exm_app_in_uil