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