--- /dev/null
+
+ LablGTK : an interface to the GIMP Tool Kit
+
+
+Needed:
+ ocaml-3.00
+ gtk-1.2.x
+ gmake (there is no standard for conditionals)
+
+How to compile:
+
+ You should normally not need to modify Makefiles.
+ First type "make configure <options>".
+ Options are
+ USE_CC=1 to use $(CC) rather than gcc
+ USE_GL=1 to compile with OpenGL support (see lower)
+ USE_GNOME=1 to compile GtkXmHTML support (requires gnome)
+
+ Then just type "make" to build the library and toplevels.
+
+ On FreeBSD, you need to link with libxpg4.so for Japanese
+ output.
+
+Contents:
+
+ gdk.ml low-level interface to the General Drawing Kit
+ gtk.ml low-level interface to the GIMP Tool Kit
+ gtkThread.ml main loop for threaded version
+ g[A-Z]*.ml object-oriented interface to GTK
+ gdkObj.ml object-oriented interface to GDK
+
+ lablgtk toplevel
+
+ examples/*.ml various examples
+ applications/* applications using the library
+ radtest a very experimental RAD for lablgtk
+ (by Hubert Fauque)
+ browser the begin of a port of OCamlBrowser
+ (by Jacques Garrigue)
+ unison a frontend for the Unison file synchronizer
+ see the README for details.
+
+Upgrading from lablgtk-1.00:
+ There are a few incompatibilities between this version and the
+ previous release. We do not describe them all, since usually a type
+ error message will inform you.
+ * all signals are no longer under #connect. #connect#event changed
+ to #event#connect, and some signals are under #misc#connect or
+ #grab#connect. See lower for a description of the new widget
+ structure.
+ * some defaults changed. In particular GPack.box#pack have now all
+ its parameter defaulting to false rather than true. See lower for
+ the new default policy. Beware that this does not cause type
+ errors, just changes in the aspect.
+
+How to run the examples:
+ In the examples directory just type:
+ lablgtk -labels examples/???.ml
+
+ Before installing lablgtk you have to be more explicit:
+ ../lablgtktop -labels -w s -I .. ???.ml
+
+How to link them:
+ lablgtktop contains an extra module GtkInit, whose only contents is:
+ let locale = GtkMain.Main.init ()
+ You must either add this line, or add this module to your link,
+ before calling any Gtk function.
+ ocamlc -I CAMLLIB/lablgtk -labels -w s lablgtk.cma gtkInit.cmo ???.ml -o ???
+
+How to use the threaded toplevel:
+
+ % lablgtk -thread (or lablgtktop_t before installing)
+ Objective Caml version 3.00
+
+ # let w = GWindow.window ~show:true ();;
+
+ You should at once see a window appear.
+ The GTK main loop is running in a separate thread. Any command
+ is immediately reflected by the system.
+ Beware that you cannot switch threads within a callback, that is the
+ only thread related command you may use in a callback is
+ Thread.create. On the other hand, all newly created threads will be
+ run directly by the caml main loop, so they can use all thread
+ operations.
+
+Structure of the (raw) Gtk* modules:
+
+ These modules are composed of one submodule for each class.
+ Signals specific to a widget are in a Signals inner module.
+ A setter function is defined to give access to set_param functions.
+
+Structure of the G[A-Z]* modules:
+
+ These modules provide classes to wrap the raw function calls.
+ Here are the widget classes contained in each module:
+
+ GDraw Gdk pixmaps, etc...
+ GObj gtkobj, widget, style
+ GData data, adjustment, tooltips
+ GContainer container, item_container
+ GWindow window, dialog, color_selection_dialog, file_selection, plug
+ GPack box, button_box, table, fixed, layout, packer, paned, notebook
+ GBin scrolled_window, event_box, handle_box, frame,
+ aspect_frame, viewport, socket
+ GButton button, toggle_button, check_button, radio_button, toolbar
+ GMenu menu_item, tearoff_item, check_menu_item, radio_menu_item,
+ menu_shell, menu, option_menu, menu_bar, factory
+ GMisc separator, statusbar, calendar, drawing_area,
+ misc, arrow, image, pixmap, label, tips_query,
+ color_selection, font_selection
+ GTree tree_item, tree
+ GList list_item, liste, clist
+ GEdit editable, entry, spin_button, combo, text
+ GRange progress, progress_bar, range, scale, scrollbar
+
+ While subtyping follows the Gtk widget hierarchy, you cannot always
+ use width subtyping (i.e. #super is not unifiable with all the
+ subclasses of super). Still, it works for some classes, like
+ #widget and #container, and allows subtyping without coercion towards
+ these classes (cf. #container in pousse.ml for instance).
+
+ Practically, each widget class is composed of:
+ * a coerce method, returning the object coerced to the type widget.
+ * an as_widget method, returning the raw Gtk widget used for packing, etc...
+ * a connect sub-object, allowing one to widget specific
+ signals (this is what prevents width subtyping in subclasses.)
+ * a misc sub-object, giving access to miscellanous functionality of
+ the basic gtkwidget class, and a misc#connect sub-object.
+ * an event sub-object, for Xevent related functions (only if the widget
+ has an Xwindow), and an event#connect sub-object.
+ * a grab sub-object, containing drag and drop functions,
+ and a grab#connect sub-object.
+ * widget specific methods.
+
+ Here is a diagram of the structure (- for methods, + for sub-objects)
+ - coerce : widget
+ - as_widget : Gtk.widget obj
+ - destroy : unit -> unit
+ - ...
+ + connect : mywidget_signals
+ | - after
+ | - signal_name : callback:(... -> ...) -> GtkSignal.id
+ + misc : misc_ops
+ | - show, hide, disconnect, ...
+ | + connect : misc_signals
+ + event : event_ops
+ | - add, ...
+ | + connect : event_signals
+ + grab : grab_ops
+ | - ...
+ | + connect : grab_signals
+
+ You create a widget by [<Module>.<widget name> options ... ()].
+ Many optional arguments are admitted. The last two of them, packing:
+ and show:, allow you respectively to call a function on your newly
+ created widget, and to decide wether to show it immediately or not.
+ By default all widgets except toplevel windows (GWindow module) are
+ shown immediately.
+
+Default arguments:
+ For many constructor or method arguments, default values are provided.
+ Generally, this default value is defined by GTK, and you must refer
+ to GTK's documentation.
+ For ML defined defaults, usually default values are either false, 0, None
+ or `NONE, according to the expected type.
+ Important exceptions are ~show, which default to true in all widgets
+ except those in GWindow, and ~fill, which defaults to true or `BOTH.
+
+Note about unit as method argument:
+
+ O'Caml introduces no distinction between methods having side-effects
+ and methods simply returning a value. In practice, this is
+ confusing, and awkward when used as callbacks. For this reason all
+ methods having noticeable side-effects should take arguments, and
+ unit if they have no argument.
+
+Memory management:
+
+ Important efforts have been dedicated to cooperate with Gtk's
+ reference counting mechanism. As a result you should generally be
+ able to use Gdk/Gtk data structures without caring about memory
+ management. They will be freed when nobody points to them any more.
+ This also means that you do not need to pay too much attention to
+ whether a data structure is still alive or not. If it is not, you
+ should get an error rather than a core dump.
+ The case of Gtk objects deserves special care. Since they are
+ interactive, we cannot just destroy them when they are no longer
+ referenced. They have to be explicitely destroyed. If a widget was
+ added to a container widget, it will automatically be destroyed when
+ its last container is destroyed. For this reason you need only
+ destroy toplevel widgets.
+
+GL extension
+
+ You can use lablgtk in combination with LablGL
+
+ * get and install lablGL 0.94 from
+ http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgl.html
+ * get and install gtkglarea-1.2.x.tar.gz from
+ http://www.student.oulu.fi/~jlof/gtkglarea/index.html
+ * reconfigure: "make configure USE_GL=1"
+
+ You can then use the widget GlGtk.gl_area as an OpenGL window.
+ Some examples are in examples/GL, but basically any LablGL example
+ can be easily ported.
+
+Windows port
+
+ A Win32 port is provided. In order to compile it, you will need to
+ get and unpack glib-dev-????.zip and gtk+-dev-????.zip from
+ http://www.gimp.org/~tml/gimp/win32/
+ Do not forget to get also extralibs-dev-????.zip, since you will
+ need some of the DLLs.
+
+ Edit config.make.nt, then, using Visual C++,
+ nmake -f Makefile.nt
+ nmake -f Makefile.nt opt (if you have an MS Assembler)
+ Then install with
+ nmake -f Makefile.nt install
+
+ Since the link is dynamic you will also need to have in your path:
+ gnu-intl.dll (extralibs), glib-1.3.dll, module-1.3.dll and
+ gthread-1.3.dll (glib), gdk-1.3.dll and gtk-1.3.dll (gtk+).
+
+ I checked with the 2000-02-02 version of these libraries.
+ Currently threads do not seem to work, but otherwise everything
+ seems OK. In particular, you can run all examples, and build
+ applications\unison as usual.
+
+Authors:
+ Jacques Garrigue <garrigue@kurims.kyoto-u.ac.jp>
+ Hubert Fauque <hubert.fauque@wanadoo.fr>
+ Jun Furuse <Jun.Furuse@inria.fr>
+ Koji Kagawa <kagawa@eng.kagawa-u.ac.jp>
+
+Bug reports:
+ Jacques Garrigue <garrigue@kurims.kyoto-u.ac.jp>
+
+$Id$