helm/DEVEL/lablgtk/lablgtk_20001129-0.1.0/README

   1
   2                 LablGTK : an interface to the GIMP Tool Kit
   3
   4
   5 Needed:
   6         ocaml-3.00
   7         gtk-1.2.x
   8         gmake (there is no standard for conditionals)
   9
  10 How to compile:
  11
  12         You should normally not need to modify Makefiles.
  13         First type "make configure <options>".
  14         Options are
  15                 USE_CC=1        to use $(CC) rather than gcc
  16                 USE_GL=1        to compile with OpenGL support (see lower)
  17                 USE_GNOME=1     to compile GtkXmHTML support (requires gnome)
  18
  19         Then just type "make" to build the library and toplevels.
  20
  21         On FreeBSD, you need to link with libxpg4.so for Japanese
  22         output.
  23
  24 Contents:
  25
  26         gdk.ml          low-level interface to the General Drawing Kit
  27         gtk.ml          low-level interface to the GIMP Tool Kit
  28         gtkThread.ml    main loop for threaded version
  29         g[A-Z]*.ml      object-oriented interface to GTK
  30         gdkObj.ml       object-oriented interface to GDK
  31
  32         lablgtk         toplevel
  33
  34         examples/*.ml   various examples
  35         applications/*  applications using the library
  36                 radtest         a very experimental RAD for lablgtk
  37                                 (by Hubert Fauque)
  38                 browser         the begin of a port of OCamlBrowser
  39                                 (by Jacques Garrigue)
  40                 unison          a frontend for the Unison file synchronizer
  41                                 see the README for details.
  42
  43 Upgrading from lablgtk-1.00:
  44   There are a few incompatibilities between this version and the
  45   previous release. We do not describe them all, since usually a type
  46   error message will inform you.
  47   * all signals are no longer under #connect. #connect#event changed
  48     to #event#connect, and some signals are under #misc#connect or
  49     #grab#connect. See lower for a description of the new widget
  50     structure.
  51   * some defaults changed. In particular GPack.box#pack have now all
  52     its parameter defaulting to false rather than true. See lower for
  53     the new default policy. Beware that this does not cause type
  54     errors, just changes in the aspect.
  55
  56 How to run the examples:
  57   In the examples directory just type:
  58         lablgtk -labels examples/???.ml
  59
  60   Before installing lablgtk you have to be more explicit:
  61         ../lablgtktop -labels -w s -I .. ???.ml
  62
  63 How to link them:
  64   lablgtktop contains an extra module GtkInit, whose only contents is:
  65         let locale = GtkMain.Main.init ()
  66   You must either add this line, or add this module to your link,
  67   before calling any Gtk function.
  68   ocamlc -I CAMLLIB/lablgtk -labels -w s lablgtk.cma gtkInit.cmo ???.ml -o ???
  69
  70 How to use the threaded toplevel:
  71
  72         % lablgtk -thread           (or lablgtktop_t before installing)
  73                 Objective Caml version 3.00
  74
  75         # let w = GWindow.window ~show:true ();;
  76
  77   You should at once see a window appear.
  78   The GTK main loop is running in a separate thread. Any command
  79   is immediately reflected by the system.
  80   Beware that you cannot switch threads within a callback, that is the
  81   only thread related command you may use in a callback is
  82   Thread.create. On the other hand, all newly created threads will be
  83   run directly by the caml main loop, so they can use all thread
  84   operations.
  85
  86 Structure of the (raw) Gtk* modules:
  87
  88   These modules are composed of one submodule for each class.
  89   Signals specific to a widget are in a Signals inner module.
  90   A setter function is defined to give access to set_param functions.
  91
  92 Structure of the G[A-Z]* modules:
  93
  94   These modules provide classes to wrap the raw function calls.
  95   Here are the widget classes contained in each module:
  96
  97   GDraw         Gdk pixmaps, etc...
  98   GObj          gtkobj, widget, style
  99   GData         data, adjustment, tooltips
 100   GContainer    container, item_container
 101   GWindow       window, dialog, color_selection_dialog, file_selection, plug
 102   GPack         box, button_box, table, fixed, layout, packer, paned, notebook
 103   GBin          scrolled_window, event_box, handle_box, frame,
 104                 aspect_frame, viewport, socket
 105   GButton       button, toggle_button, check_button, radio_button, toolbar
 106   GMenu         menu_item, tearoff_item, check_menu_item, radio_menu_item,
 107                 menu_shell, menu, option_menu, menu_bar, factory
 108   GMisc         separator, statusbar, calendar, drawing_area,
 109                 misc, arrow, image, pixmap, label, tips_query,
 110                 color_selection, font_selection
 111   GTree         tree_item, tree
 112   GList         list_item, liste, clist
 113   GEdit         editable, entry, spin_button, combo, text
 114   GRange        progress, progress_bar, range, scale, scrollbar
 115
 116   While subtyping follows the Gtk widget hierarchy, you cannot always
 117   use width subtyping (i.e. #super is not unifiable with all the
 118   subclasses of super). Still, it works for some classes, like
 119   #widget and #container, and allows subtyping without coercion towards
 120   these classes (cf. #container in pousse.ml for instance).
 121
 122   Practically, each widget class is composed of:
 123   * a coerce method, returning the object coerced to the type widget.
 124   * an as_widget method, returning the raw Gtk widget used for packing, etc...
 125   * a connect sub-object, allowing one to widget specific
 126     signals (this is what prevents width subtyping in subclasses.)
 127   * a misc sub-object, giving access to miscellanous functionality of
 128     the basic gtkwidget class, and a misc#connect sub-object.
 129   * an event sub-object, for Xevent related functions (only if the widget
 130     has an Xwindow), and an event#connect sub-object.
 131   * a grab sub-object, containing drag and drop functions,
 132     and a grab#connect sub-object.
 133   * widget specific methods.
 134
 135   Here is a diagram of the structure (- for methods, + for sub-objects)
 136         - coerce : widget
 137         - as_widget : Gtk.widget obj
 138         - destroy : unit -> unit
 139         - ...
 140         + connect : mywidget_signals
 141         |   - after
 142         |   - signal_name : callback:(... -> ...) -> GtkSignal.id
 143         + misc : misc_ops
 144         |   - show, hide, disconnect, ...
 145         |   + connect : misc_signals
 146         + event : event_ops
 147         |   - add, ...
 148         |   + connect : event_signals
 149         + grab : grab_ops
 150         |   - ...
 151         |   + connect : grab_signals
 152
 153   You create a widget by [<Module>.<widget name> options ... ()].
 154   Many optional arguments are admitted. The last two of them, packing:
 155   and show:, allow you respectively to call a function on your newly
 156   created widget, and to decide wether to show it immediately or not.
 157   By default all widgets except toplevel windows (GWindow module) are
 158   shown immediately.
 159
 160 Default arguments:
 161   For many constructor or method arguments, default values are provided.
 162   Generally, this default value is defined by GTK, and you must refer
 163   to GTK's documentation.
 164   For ML defined defaults, usually default values are either false, 0, None
 165   or `NONE, according to the expected type.
 166   Important exceptions are ~show, which default to true in all widgets
 167   except those in GWindow, and ~fill, which defaults to true or `BOTH.
 168
 169 Note about unit as method argument:
 170
 171   O'Caml introduces no distinction between methods having side-effects
 172   and methods simply returning a value. In practice, this is
 173   confusing, and awkward when used as callbacks. For this reason all
 174   methods having noticeable side-effects should take arguments, and
 175   unit if they have no argument.
 176
 177 Memory management:
 178
 179   Important efforts have been dedicated to cooperate with Gtk's
 180   reference counting mechanism. As a result you should generally be
 181   able to use Gdk/Gtk data structures without caring about memory
 182   management. They will be freed when nobody points to them any more.
 183   This also means that you do not need to pay too much attention to
 184   whether a data structure is still alive or not. If it is not, you
 185   should get an error rather than a core dump.
 186   The case of Gtk objects deserves special care. Since they are
 187   interactive, we cannot just destroy them when they are no longer
 188   referenced. They have to be explicitely destroyed. If a widget was
 189   added to a container widget, it will automatically be destroyed when
 190   its last container is destroyed. For this reason you need only
 191   destroy toplevel widgets.
 192
 193 GL extension
 194
 195   You can use lablgtk in combination with LablGL
 196
 197   * get and install lablGL 0.94 from
 198     http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgl.html
 199   * get and install gtkglarea-1.2.x.tar.gz from
 200     http://www.student.oulu.fi/~jlof/gtkglarea/index.html
 201   * reconfigure: "make configure USE_GL=1"
 202
 203   You can then use the widget GlGtk.gl_area as an OpenGL window.
 204   Some examples are in examples/GL, but basically any LablGL example
 205   can be easily ported.
 206
 207 Windows port
 208
 209   A Win32 port is provided. In order to compile it, you will need to
 210   get and unpack glib-dev-????.zip and gtk+-dev-????.zip from
 211         http://www.gimp.org/~tml/gimp/win32/
 212   Do not forget to get also extralibs-dev-????.zip, since you will
 213   need some of the DLLs.
 214
 215   Edit config.make.nt, then, using Visual C++,
 216         nmake -f Makefile.nt
 217         nmake -f Makefile.nt opt        (if you have an MS Assembler)
 218   Then install with
 219         nmake -f Makefile.nt install
 220
 221   Since the link is dynamic you will also need to have in your path:
 222   gnu-intl.dll (extralibs), glib-1.3.dll, module-1.3.dll and
 223   gthread-1.3.dll (glib), gdk-1.3.dll and gtk-1.3.dll (gtk+).
 224
 225   I checked with the 2000-02-02 version of these libraries.
 226   Currently threads do not seem to work, but otherwise everything
 227   seems OK. In particular, you can run all examples, and build
 228   applications\unison as usual.
 229
 230 Authors:
 231         Jacques Garrigue <garrigue@kurims.kyoto-u.ac.jp>
 232         Hubert Fauque  <hubert.fauque@wanadoo.fr>
 233         Jun Furuse     <Jun.Furuse@inria.fr>
 234         Koji Kagawa    <kagawa@eng.kagawa-u.ac.jp>
 235
 236 Bug reports:
 237         Jacques Garrigue <garrigue@kurims.kyoto-u.ac.jp>
 238
 239 $Id$