(Warning: I am probably a poor english writer. Faults tolerance is required.)

(c) Rodolphe Ortalo, 1997. Permission to use and distribute for non-commercial
purposes is granted under the terms of the GNU GPL.
   (I hate legal thingy, but, well, sometimes...)

INSTALLATION
============
Nothing special. Once the AMULET_* env. variables are set (to
Amulet _V3_), a simple GNU make will produce the object file
ro_widgets.o and a test program 'testrowidgets'.


USE
===
The ro_widgets.h file contains the declarations of the exported widgets
and slots. It should be included in user programs. These should
be linked with the ro_widgets.o object file, and they should call
the procedure Ro_Widgets_Init(void) after Amulet initialization
to initialize the widgets. (See the test program.)


IMPLEMENTED WIDGETS
===================
Remark: Sometimes, I have reused slot names from Amulet to avoid
namespace pollution (laziness also?). Such reuse may or may not
have been very adequate. I usually find it satisfaying.

	INDEX CARDS:
	===========

 * Ro_Border_Card : Is a prototype of a card, containing a user
defined widget, with a text index at the top of the card.
The Am_LABEL slot OF THE PROTOTYPE OBJECT will contain the name
of the card (displayed in the index).
(NB: I don't think a graphical object in place of a string
would work. It could easily however.)
The Am_ITEM slot should contain the prototype of a graphical object (or
widget) you want to be displayed in the card. The reason to use a
prototype (even though we will probably have only one instance of
it) is that... it was easier. I therefore avoid the burden of handling
the parts a user could add directly to the card (demon?). This would
be the right way. Instead, I use a formula which changes a part of the
card based on the Am_ITEM slot with a side-effect, the ugly way.

 * Ro_Card_Set : This is a canonical widget based on Am_Map and the
previous Ro_Border_Card. So, you just need to set the Am_ITEMS slot
of the card set with the various prototypes of cards content, and you
will have a card set. There is a specialized layout procedure
in the map that will display the cards and indexes correctly.

 * Ro_Card_Widget : This is the same as the previous one, except that
the whole thing is displayed in a new window (the needed slots are
propagated to the content that is the previous one).

	FILE SELECTION
	==============

This is a preliminary work. The function 
   Am_String Ro_Show_File_Select_Dialog(void)
will display the widget and return a string containing the file
name selected.
I am really not satisfied with the way it works. See the source code
to understand why. But, admitedly, it works.

	SLOT EDITION
        ============

 * Ro_Text_Slot_Edit_Widget : This text line widget allows to edit
the value of a slot of an object (in the same way as the inspector
somehow). Currently, only strings are really accepted, but other
types of value could be. (In fact, it would be convenient to export
some of the things used in the inspector I think.)
The slot Ro_SLOT_EDITED contains the key of the slot edited, the slot
Ro_EDITED_OBJECT the object in which it resides.

	PROGRESS REPORT
	===============
 * Ro_Progress_Bar : This is a simple progress bar.
The Ro_CURRENT_VALUE and Ro_MAX_VALUE slot must contain integer
or float values corresponding to the progress being displayed.
The slot Ro_BAR_NUM_FORMAT contains one of :
 enum Bar_Num_Format { Ro_None, Ro_Percent, Ro_Fraction, Ro_Direct }
Depending on it, a value is added in the center of the bar, like
'38%', '14/20' or '147' (or nothing).	
To edit finely the attributes of the various parts, the parts are
named and names exported.

 * Ro_2Text_Info : Very simple widget! Two strings coming from
Am_LABEL and Am_TEXT, one in bold, with horizontal layout. It is
also exported, but mainly useful for the next one.

 * Ro_Progress_Report : This widget displays a bar like the previous
one, but also two text objects (corresponding to strings stored in
the Am_LABEL and Am_TEXT slot of the Ro_Progress_Report object).
It is useful to add information to a simple bar. And you set the *_VALUE
and bar num format directly in it.

	MONITOR
	=======

 * Ro_File_Monitor : This object is not a graphical one, but allows
to monitor the content of a text file. The Am_VALUE slot of the object
will contain a list of Am_String (corresponding to each line of the
file), regularly updated (if Ro_AUTO is true).
The Ro_FILE slot should contain the name of the file to monitor. The
Ro_AUTO slot contain a boolean saying if you want automatic update on
modifications to the file.
3 methods exists: Ro_GET_METHOD, Ro_UPDATE_METHOD, Ro_CLOSE_METHOD.
The first and last one corresponds to activation and closing of the object.
They MUST be called for someting to happen. The update method can be
activated manually, or by the timer associated to the object if started
by the get method (Ro_AUTO true). It will not re-open the file, but only
look at the end of the opened stream.
The behavior could be improved. Currently: once the file is opened, if the
filename changes, subsequent updates will keep on looking at the ORIGINAL
filehandle. If the Ro_AUTO slot changes during operation, the automatic
timer update will NOT be stopped. I will look at this one day, but I feel
that such features are not critical (but they are counter-intuitive).

 * Ro_Process_Monitor : NOT YET IMPLEMENTED.
This would proceed from the same idea as the previous one : look at a
PID, gather information and make it accessible. GET, UPDATE, CLOSE, but
also SUSPEND, RESUME and KILL method should be proposed. (The latter could
be gathered elsewhere by the way... In a kind of non-blocking Am_Command..?)

	TEXT DISPLAY
	============
 * Ro_Raw_Text_Show : This widget is also a simple one. It is an
Am_Scrolling group containing an Am_Map of Am_Text. You set its
Am_VALUE slot with a list of strings, it will display them as a
simple text viewer. In the test program, this widget is used in
conjunction with Ro_File_Monitor to display the content of a bogus
file named 'out.txt' in the current directory. If you append something
to this file, (echo 'Bonjour de France' >> out.txt) it will be
reflected on the screen.


Finally: All these widgets are, generally, fast hacked ones.
  Therefore, I am very humble concerning them... Even if I
  hope they can help someone, and if I would be very pleased if it
  occured, I cannot guarantee they will fit anyone needs. (Except me:)

Rodolphe Ortalo, February 1997
e-mail: ortalo@laas.fr (until the end of 1997)
