]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/lablgtk/lablgtk_20001129-0.1.0/README
.cvsignore files missing
[helm.git] / 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$