-------------------------------------------------------------------------
                        Linux X Builder (L-X-B) 
This is the file README for the program lxb version 0.1.
-------------------------------------------------------------------------

SUMMARY:
  lxb is an X/Motif interactive graphical user interface builder. With 
  it you can build a GUI made up of Motif widgets instantiated by 
  clicking on icons, move and resize them with the mouse, edit their 
  resources, and move about in the widget heirarchy via the arrow keys. 
  Once the GUI is built, pressing a button will produce all required C 
  source files to build the GUI, and an X resource file and Makefile.


PLEASE NOTE:
  This version of lxb is not completed. Not all Motif widgets are 
  included, nor can all resources be edited. However, all instantiated 
  widgets are declared as global, so that you can more easily write any 
  additional code required. 

  I am releasing this software now, even though it is incomplete, since 
  it will take a great deal of time and work to produce a GUI builder
  comparable to one of the commercial ones. Hopefully, with what 
  capabilities this software does currently have it will be useful for 
  someone.

  Also, at this time I am only releasing the executable. The software 
  would have to be more complete and stable before I would consider
  releasing the source.

-------------------------------------------------------------------------
Some requirments and further information...
-------------------------------------------------------------------------

FILE LIST:
  lxb/lxb         :   The program executable
  lxb/Lxb-ad      :   The program X defaults
  lxb/README      :   This file


SUPPORTED PLATFORMS:
  As the name suggests, only Linux systems. 

  My system has the Slackware 2.2 distribution installed as a base,
  with the kernel upgraded to 1.2.8; XFree86 3.1.1 (X11R6), libc4.5.26, 
  gcc 2.5.8. Your system's milage may vary. 


INSTALLING lxb:
  The lxb executable "lxb" must of course be in your "path".

  The X application defaults for lxb are in the file Lxb-ad. These
  can be placed any of many places, depending on how you do your X 
  resources.


REQUIRED SHARED LIBS:
  The exact output of ldd:

  libXpm.so.4 (DLL Jump 4.4) => /usr/X11R6/lib/libXpm.so.4.5
  libXt.so.6 (DLL Jump 6.0) => /usr/X11R6/lib/libXt.so.6.0
  libX11.so.6 (DLL Jump 6.0) => /usr/X11R6/lib/libX11.so.6.0
  libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.5.26

MOTIF VERSION:
  The version of Motif is 2.0, and it's library is of course statically 
  linked.

  Note that this means that lxb will work even if you do not have motif
  on your system, up to and including generating the C code to build the
  Motif GUI. But of course you must have Motif on your system in order to
  compile and execute the GUI application built with lxb.

-------------------------------------------------------------------------
Some operating instructions...
-------------------------------------------------------------------------

The best way to see how the builder works is to just play around with it. 
And a lot more cost efficient than for me to attempt to write a detailed 
set of instructions that may not make much sense anyhow. But I'll try and 
give you some basics.

COMMAND LINE PARAMETERS:

  lxb -V      :   will print the current version of lxb
  lxb -v [n]  :   sets the verbose level to n; the result being lots of
                  output which will mean very little to you and only a 
                  little more to me.


LAYOUT OF THE LXB SOFTWARE:
  There are 3 lxb windows:
  1) The main lxb GUI
  2) The application GUI being built
  3) The resource editor

MAIN WINDOW:
  The first and main window that will appear when the user enters "lxb" and
  presses <CR> will have on it a menubar, below that an information area,
  and below that an area with some icons. The information area lists the
  name of the GUI application, the "active" widget, and the "selected" widget.
  The area with icons have the names of the Motif widgets lxb can instantiate
  and are available for use in building a GUI.

  The icons with a Black background are only for menubars. (See below) They
  should not let you use them except in the correct places anyhow.


  MENUBAR:

    Files Pulldown:

      New Button:  Begin a new GUI
      Open Button: Opens an existing lxb save file. (See below) 
      Save Button: Saves the current GUI in an lxb save file. 
      Quit Button: Exits lxb.

    Edit Pulldown:

      Delete Widget Button: Deletes the selected widget.

    Options Pulldown:

      Code Button:  Produce the C source code, header files, X defaults file,
                    and Makefile to produce the GUI application.

    Diagnostics Pulldown: (This is temporary for development purposes)

      Application Widget Tree Button:   Lists the widgets in the application.
      Selected Widget Resources Button: Lists resources of the selected widget.


  INFORMATION AREA:

    The information area will list an "Active Widget" and a "Selected Widget".

    The "Active Widget" can be thought of as the parent widget; the widget that
    all subsequent widgets instantiated via lxb will have as a parent. (The 
    exception to this is in the case of Menubars; I still have not come up with
    a good solution to this - see the selection below on Menubars). In other words,
    except for menus, what ever widget gets put in your application when you push 
    the icon/button representing it will have as it's parent the "Active Widget" 
    shown in the information area. The Active Widget is the current application's 
    "World View".

    A cross-hatched pixmap is used to indicate all widgets from the parent and above 
    of the active widget, in effect "graying" them out. The widget that has a solid 
    background is the active widget. (There are bugs in this).

    The "Selected Widget" is the widget that is the one you are currently working
    on. It is the one that can be resized, moved, and have it's resources edited. 
    Usually, the selected widget will have a red border around it. (There are bugs in
    this, too). Especially, this often does often not work for container widgets.

    See below on how to navigate and select and all the rest about the widget 
    heirarchy.


APPLICATION GUI WINDOW:
  This will appear below the main lxb GUI area, but can be moved and resized and
  placed where ever you wish. This is the GUI application the user is building,
  and the canvas from where the user will work.

  An attempt has been made (in lxb) to disable all traversal mechanisms built into
  Motif widgets by default, and make them all insensitive. This was a requirement
  in writing lxb, and beyond the scope of this. So, the appplication window's widgets
  will most likely not respond to any attempts to push buttons or write text in text 
  widgets, ect.


RESOURCE EDITOR WINDOW:
  The top area lists some data on the selected widget. 

  The next area down is a List of all resources associated with the selected 
  widget. Clicking once on one of the entries in  this list will retrieve the 
  resource value and place it in the text widget that is direcly beneath it. 
  (Providing that the work has been done in lxb to handle that resource). 

  If the resource value has several options, such as a color, or the enumerated 
  types, all possible values will appear in the small List box directly beneath 
  the text input field.

  Clicking on any selection in the option box places it in the text input box.

  A value may also be entered with the keyboard into the text input field, and
  of course this method must be used for normal resources, like width and height.

  Two buttons are located at the bottom of the resource editor. One is "Dismiss",
  this will remove the Resource Editor from you screen. The other is "Set Resource",
  pressing this will result in lxb attempting to set whatever is in the text input 
  field as the value for resource selected in the top most List box.

  See below how to make the Resource Editor appear.


NAVIGATION AMONGST THE GUI'S WIDGETS:

  ARROW KEYS:

  The arrow keys are used to move about the applications's widget heirarchy. 

  Up Arrow Key: The up arrow key will make the current selected widget the new 
                active widget. There may be occasional bugs here. If you run into
                them, go up to the top level, and sequence down.

  Down Arrow Key: If there is a selected widget, it will become the new active
                  widget.

                  If there is no selected widget, the down arrow key will chose a 
                  child at random of the current active widget and make it the 
                  active widget.


  Left/Right Arrow Keys: They can be used to select the children of the active
                         widget. Either key can be used, since the selection is
                         circular and repeats itself. 

  Note that the Left/Right arrow keys must (currently) be used to select widgets 
  that are children of a pulldown from the menubar.

  MOUSE BUTTONS:

  The mouse buttons, from left to right, are MB1, MB2, MB3.

  MB1:    Selects widgets. When the pointer is in the aplication window and over 
          the the widget and this button is pressed and released, the widget 
          becomes the selected widget. Insure that the widget is a child of the 
          active widget, or it won't happen. Lots of times a red border is drawn
          around the widget to indicate it is selected.

          Moves widgets. If MB1 is pressed and held, and the mouse moved, the 
          widget will be dragged about in the application area. But see the note 
          below on container widgets.

  MB2:    Resizes a widget. If it is the selected widget. Press and hold MB2
          with the pointer in the selected widget, and it will drag-resize by
          it's bottom right corner.

  MB3:    Brings up the resource editor. The resources being edited wil be 
          those of the selected widget, where ever it may be.

  Note that MB1 cannot be used to select widgets in menu pulldowns.


HOW TO MAKE MENUBARS:
  This requires the one (so far) inconsistant process by the user of lxb in
  order to create a menubar. This is related to the awful way in general 
  menus are done in Motif. Sorry.

  As already mentioned, Icons in the icon area pertaining to menubars all 
  have a black background, and are:

  "MenuBar"; may have an active widget (parent) of anything. 

  "MenuCB"; (Cascade Buttton) an active widget (parent) of a MenuBar.

  "MenuPB"; (Push Button) and "MenuSep" (separator) can only have an active
  widget of the Cascade Button in the Menubar. (Notice I did not say "parent").

  These pushbuttons and separators cannot be "selected" with MB1, as can other 
  widgets - the left/right arrow keys must be used, as has been mentioned.
  See above on how this is done. Once the pulldown's widget is selected, 
  it's resources can be edited.


A SIMPLE EXAMPLE OF USING LXB:

  Press "New". In the text field, enter the word "tst". Press "OK", or <CR>.

  A rectangular window will be produced below the icon area. This is the
  GUI you are building. 

  Press on icons to build your GUI, use arrow keys and MB1 to move around in 
  the widget heirarchy, use the mouse buttons to select, resize, move, and
  bring up the resource editor for the selected widget.

  Edit the resources as desired (the ones that lxb can, anyhow).

  Press "Save". The file "tst.lxb" will be produced.

  Press "Code". The source file will be produced.

  Type "make". The program executable "tst" will be produced.

  Type xrdb -m tst-ad to merge in the example's X resources. 

  Type tst to run the program and produce your GUI.


-------------------------------------------------------------------------
Some helpful hints...
-------------------------------------------------------------------------

SELECTING CONTAINER WIDGETS:
  Such as forms, rowcolumns; currently may be difficult to select,
  or impossible, depending on the border thickness and similar
  resources. Try clicking mb1 with the pointer on the very edge
  of the container widget; or use the left and right arrow keys as
  explained above.


MENUS:
  Only Menubars with the main cascade button, but as many pushbuttons and 
  separators, are implemented. In other words, one series of widgets 
  may be pulled down from the cascade button in the menubar, but no 
  "pullright" menus - meaning cascade buttons in the pulldowns aren't
  implemented.

  Of course, you can add your own if you want to hack the code.


FORMS:
  The XmForm widget is included in the widgets that may be instantiated
  and resources edited with lxb. However, you may observe quite strange
  behaviour in regard to this widget off and on. It is most likely due
  to the resources you have set for it.

  Under certain circumstances, you may want to set XmNresizePolicy to 
  Xm_RESIZE_NONE for the form; else it will continually shrink/resize to 
  fit the child(ren), which again you occasionally may not want. It's 
  your GUI.

  The constraint resources for children of XmForm widgets should work.

  Beware circular contraints. They don't work.

-------------------------------------------------------------------------
Etc.
-------------------------------------------------------------------------

DEFICENCIES:

  - A callback editor is not provided as of yet.
  - No test mode.
  - No display of widget heirarchies is provided yet. Use editres.
  - Not all widgets are available yet.
  - Not all resources can be edited yet.
  - Widget names are not user assignable yet.
  - No choices are given as to the scope of the variables yet.
  - And many more, when compared to a commercial $3000+ GUI builder.


WORKAROUNDS:
  All widgets in the created GUI application are declared global.
  This was done so that the user may more easily change resources
  that I have not yet been able to provid the capability of editing, 
  adding callback functions to, etc.

  Also, the program editres may be useful if you desire to see
  widget heirarchies.


TO KEEP IN MIND:
  Most likely new versions of lxb released in the future, for 
  several releases, at least, will *probabably* not read save 
  files (*.lxb) created with older versions of lxb.

  AND, REMEMBER, this is an ALPHA version of incomplete software. If 
  it is of use to you, good. If not, I don't want to hear about it. :-)


TO BE DONE:
  Almost everything.


BUGS:
  Of course.


NO WARRANTY OF ANY KIND:
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


-------------------------------------------------------------------------
Bruce Parkin              --/--             email: bruce.parkin-1@umn.edu
-------------------------------------------------------------------------

