]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/lablgtk/lablgtk_20000829-0.1.0/README
* click signal changed: now the element argument is optional
[helm.git] / 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$