+++ /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)
-
- 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$