Blame README.mlTk

Packit bd2e5d
INTRODUCTION
Packit bd2e5d
============
Packit bd2e5d
mlTk is a library for interfacing OCaml with the scripting
Packit bd2e5d
language Tcl/Tk (all versions since 8.0.3, but no betas).
Packit bd2e5d
Packit bd2e5d
In addition to the basic interface with Tcl/Tk, this package contains
Packit bd2e5d
 * the OCamlBrowser code editor / library browser written by Jacques
Packit bd2e5d
 Garrigue.
Packit bd2e5d
 * the "jpf" library, written by Jun P. Furuse; it contains a "file
Packit bd2e5d
 selector" and "balloon help" support
Packit bd2e5d
 * the "frx" library, written by Francois Rouaix
Packit bd2e5d
 * the "tkanim" library, which supports animated gif loading/display
Packit bd2e5d
Packit bd2e5d
mlTk = CamlTk + LablTk
Packit bd2e5d
======================
Packit bd2e5d
There existed two parallel Tcl/Tk interfaces for OCaml, CamlTk and LablTk.
Packit bd2e5d
Packit bd2e5d
CamlTk uses classical features only, therefore it is easy to understand for
Packit bd2e5d
the beginners of ML. It makes many conservative OCaml gurus also happy.
Packit bd2e5d
LablTk, on the other hand, uses rather newer features of OCaml, the labeled
Packit bd2e5d
optional arguments and polymorphic variants. Its syntax has much more Tcl/Tk
Packit bd2e5d
script flavor, but provides more powerful typing than CamlTk at the same time
Packit bd2e5d
(i.e. less run time type checking of widgets).
Packit bd2e5d
Until now, these two interfaces have been distributed and maintained
Packit bd2e5d
independently.
Packit bd2e5d
Packit bd2e5d
mlTk unifies these libraries into one. Since mlTk provides the both API's,
Packit bd2e5d
both CamlTk and LablTk users can compile their applications with mlTk,
Packit bd2e5d
just with little fixes.
Packit bd2e5d
Packit bd2e5d
REQUIREMENTS
Packit bd2e5d
============
Packit bd2e5d
You must have already installed
Packit bd2e5d
 * OCaml source, version 3.04+8 or later
Packit bd2e5d
Packit bd2e5d
 * Tcl/Tk 8.0.3 or later
Packit bd2e5d
    http://www.scriptics.com/ or various mirrors
Packit bd2e5d
Packit bd2e5d
PLATFORMS:
Packit bd2e5d
Essentially any Unix/X Window System platform. We have tested
Packit bd2e5d
releases on Linux (ELF x86), FreeBSD (x86), SunOS4.1.x (sparc), DEC
Packit bd2e5d
OSF/1 V4.0 (alpha), DGUX SVR4 (m88k) and Windows (VC++ and Cygwin).
Packit bd2e5d
Packit bd2e5d
INSTALLATION
Packit bd2e5d
============
Packit bd2e5d
Packit bd2e5d
0. Check-out the OCaml CVS source code tree.
Packit bd2e5d
Packit bd2e5d
1. Compile OCaml (= make world). If you want, also make opt.
Packit bd2e5d
Packit bd2e5d
2. Untar this mlTk distribution in the otherlibs directory, just like
Packit bd2e5d
   the labltk source tree.
Packit bd2e5d
Packit bd2e5d
3. change directory to otherlibs/mltk, and make (and make opt)
Packit bd2e5d
Packit bd2e5d
4. To install the library, make install (and make installopt)
Packit bd2e5d
Packit bd2e5d
To compile mlTk, you need the OCaml source tree, since mltk/camlbrowser
Packit bd2e5d
requires some modules of OCaml. If you are not interested in camlbrowser,
Packit bd2e5d
you can compile mlTk without the OCaml source tree, but you have to modify
Packit bd2e5d
support/Makefile.common.
Packit bd2e5d
Packit bd2e5d
Packit bd2e5d
Compile your CamlTk/LablTk applications with mlTk
Packit bd2e5d
=================================================
Packit bd2e5d
Packit bd2e5d
* General
Packit bd2e5d
Packit bd2e5d
The names of the additional libraries libjpf and libfrx are changed
Packit bd2e5d
to jpflib and frxlib respectively, to avoid the library name space confusion.
Packit bd2e5d
Packit bd2e5d
* LablTk users
Packit bd2e5d
Packit bd2e5d
Just change the occurrences of labltk in your Makefiles to mltk
Packit bd2e5d
(i.e. -I +labltk => -I +mltk, labltk.cma => mltk.cma, and so on)
Packit bd2e5d
Since the API functions are 100% compatible, you need not to change
Packit bd2e5d
your .ml files.
Packit bd2e5d
Packit bd2e5d
* CamlTk users
Packit bd2e5d
Packit bd2e5d
  - Makefiles : apply the same modification explained above for LablTk users.
Packit bd2e5d
Packit bd2e5d
  - open Camltk : The API modules and functions are stored in the modules
Packit bd2e5d
    Camltk. Therefore you need to replace the module name Tk to Camltk.
Packit bd2e5d
    For example, open Tk => open Camltk.
Packit bd2e5d
Packit bd2e5d
      open Camltk (* instead of open Tk *)
Packit bd2e5d
Packit bd2e5d
      let t = openTk ();;
Packit bd2e5d
      let b = Button.create t [];;
Packit bd2e5d
Packit bd2e5d
   - You may also need to open the Camltk module explicitly, when your
Packit bd2e5d
    original module source contain no open Tk phrase. Widget and the other
Packit bd2e5d
    Tcl/Tk related types are now under Camltk. (e.g. Widget.widget is now
Packit bd2e5d
    Camltk.Widget.widget) Add open Camltk at the beginning of .mli files,
Packit bd2e5d
    if these types are used:
Packit bd2e5d
Packit bd2e5d
      open Camltk (* added for compiling under mlTk *)
Packit bd2e5d
Packit bd2e5d
      val create_progress_bar : Widget.widget -> Widget.widget
Packit bd2e5d
Packit bd2e5d
  - Eta expansion to flush optional arguments at registering callbacks.
Packit bd2e5d
    Functions with the _displayof suffix are unified with their non-displayof
Packit bd2e5d
    versions, using optional labeled arguments. For example, Bell.ring
Packit bd2e5d
    had/have the following types:
Packit bd2e5d
Packit bd2e5d
        before: Bell.ring : unit -> unit
Packit bd2e5d
        now:    Bell.ring : ?displayof:Camltk.widget -> unit -> unit
Packit bd2e5d
Packit bd2e5d
    If you use these functions as callbacks directly like Command Bell.ring,
Packit bd2e5d
    you need eta-expansions to flush these new optional arguments:
Packit bd2e5d
Packit bd2e5d
        Button.create w [Command Bell.ring]
Packit bd2e5d
Packit bd2e5d
             => Button.create w [Command (fun () -> Bell.ring ())]
Packit bd2e5d
Packit bd2e5d
Use the both API's at the same time
Packit bd2e5d
===================================
Packit bd2e5d
It is possible to use the both API's in one program. If you want to use
Packit bd2e5d
a widget library written in the different API from you use, you need to
Packit bd2e5d
do it. (It will be confusing, but easier than porting the library itself
Packit bd2e5d
from one to the other API.)
Packit bd2e5d
Packit bd2e5d
For the users who mainly use LablTk API, CamlTk API is available
Packit bd2e5d
in the modules start with 'C'. For example, the source file of
Packit bd2e5d
the CamlTk button widget functions is CButton (and exported also as
Packit bd2e5d
Camltk.Button).
Packit bd2e5d
Packit bd2e5d
For the users who mainly use CamlTk API, LablTk API modules are exported
Packit bd2e5d
inside Labltk module. For example, LablTk's Button module can be also
Packit bd2e5d
accessible as Labltk.Button.
Packit bd2e5d
Packit bd2e5d
In CamlTk, we have only one widget type, [widget]. This type is equivalent
Packit bd2e5d
to the LablTk's type [any widget]. Therefore, if you want to apply CamlTk
Packit bd2e5d
functions to LablTk widget, you can use [coe] function to coerce it to
Packit bd2e5d
[any widget].
Packit bd2e5d
Packit bd2e5d
To do the converse, the "widget-typers" are available inside the module Labltk.
Packit bd2e5d
For example, to recover the type of a button widget, use Labltk.button.
Packit bd2e5d
These widget-typers checks the types of widgets at run-time. If the widget
Packit bd2e5d
type is different from the context type, a run-time exception is raised.
Packit bd2e5d
Packit bd2e5d
  open Tk (* open LablTk API *)
Packit bd2e5d
Packit bd2e5d
  let t = openTk ();; (* t is LablTk widget, toplevel widget *)
Packit bd2e5d
  (* CButton.create takes [any widget]; [t] must be coerced to the type. *)
Packit bd2e5d
  let caml_b = CButton.create (coe t) [];;
Packit bd2e5d
  (* caml_b is [any widget], must be explicitly typed as [button widget],
Packit bd2e5d
     when it is used with LablTk API functions *)
Packit bd2e5d
  let b = Labltk.button caml_b in (* recover the type [button widget] *)
Packit bd2e5d
  ...