\documentclass{article}
\usepackage{hevea}
\newcommand{\url}[1]{\ahref{#1}{#1}}
\title{A simple starting guide for mlglade}
\author{Benjamin Monate}
\begin{document}
\maketitle

\section{Introduction}
\label{sec:introduction}
\ahref{http://glade.gnome.org/}{Glade} is a freely available graphical
interface builder. It is very
powerful and enables one to quickly visually design an interface.
It can export source code for various languages like C, C++, Perl,
Eiffel. Mlglade adds support for the OCaml language. It helps you to
build ocaml applications with a gtk user interface without using
libglade.

For a more in-depth view of Glade see the \ahref{http://glade.gnome.org/}{homepage of glade}.

Before you continue, you have to install these tools :
\begin{itemize}
\item Ocaml 3.04 or above \url{http://caml.inria.fr}.
\item Latest LabGTK compatible with Ocaml 3.04 compiled with no special options : you do
  not need to enable libglade, gnome or gl support.
  \url{http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html}
\item Gtk 1.2 or any later than 1.x version \url{http://www.gtk.org}
\item Glade 0.6.2 or any later than 0.6 stable version
  \url{http://glade.gnome.org}.
\item Mlglade : download from
  \url{http://www.lri.fr/\home{monate}/mlglade}, compile and copy the
  ''mlglade'' binary in your path. 
\end{itemize}

On a debian system, this is achieved by having the following packages
installed:  
\begin{itemize}
\item \texttt{ocaml}, version 3.04 or higher,
\item \texttt{liblablgtk-ocaml-dev},
\item One of \texttt{glade}, \texttt{glade-gnome}, or
  \texttt{glade-gnome-db}, of version 0.6 or higher. 
\end{itemize} 


\section{Hello World}
\label{sec:hello-world}
Let's build your first application with mlglade. At the end of this
tutorial, you will have an application looking like this one : 
\imgsrc[center]{hello.png}


If you have already used glade just skip the first part and design a
glade hello.glade project containing a window named ''my\_window''
with a two rows vertical box. Put a label with ''Hello World'' inside
and a button labeled ''Quit''.

\begin{enumerate}
\item Basic design.
  \begin{itemize}
  \item Launch glade. It opens three windows : the main window, the
    palette window and the properties window.
  \item In the palette window click on the top leftmost icon whose
    tooltip is ''Window''. This creates a new window called ''window1''
    : this is your application's main window. 
  \item In the properties window, change the ''Name''  from ''window1''
    to ''my\_window''. This is the ocaml identifier for your window. 
  \item Change the ''Title'' into ''Hello World''. Note that your
    application's window is updated automatically.  
  \item In the Palette window click on the ''Vertical Box'' icon. 
  \item Click in your application's window and choose 2 rows.
  \item In the Palette window click on the ''Label'' icon.
  \item Click in the upper part of your application's window.
  \item In the properties window change the ''Label'' field into ''Hello
    world''
  \item In the Palette window click on the ''Button'' icon and the in
    the lower part of your application's window.
  \item Change the ''Label'' from ''button1'' to ''Quit''.
  \item Save you project with the ''Project Name'' hello in a new
    directory.
  \item You don't need to close glade as you will use it again later.
  \end{itemize}
\item Generating the first ocaml program.
  \begin{itemize}
  \item Go in the project's directory and run ''mlglade
    hello.glade''. No output should be produced.
  \item Type ''make''. 
  \item Run ''./hello''
  \item Kill your application. Closing the window is not enough !
  \end{itemize}
\item Reacting to events. Now we want to close the application when the
  ''Quit'' button is clicked.
  \begin{itemize}
  \item In Glade, select your ''Quit'' button and open the ''Signal''
    panel of the properties window.
  \item Click on the ''...'' icon in front of ''Signal''.
  \item Select ''clicked'' then click ''ok''. 
  \item Change the ''Handler'' in to ''quit''. This is the name of the
    function called by your application when the button is clicked.
  \item Click on ''Add''.
  \item Save your project and regenerate with ''mlglade hello.glade''.
    You should read two warnings that you can ignore. 
  \item Now recompile with ''make'' and run your application
    ''./hello''.
  \item Notice what happens when you click on the ''Quit''
    button. This is the default handler for the event.
  \item Edit with your favorite editor the file
    ''hello\_glade\_main.ml''. This file is created only once by
    mlglade and will never be overwritten. 
It looks like :
\begin{verbatim}
(* THIS FILE WILL NEVER BE OVERWRITTEN.
Use it as a template for your own main module.*)
open GMain
class customized_callbacks = object(self)
inherit Hello_glade_callbacks.default_callbacks
end
let main () = 
let callbacks = new customized_callbacks in
let my_window = new Hello_glade_interface.top_my_window callbacks in
let _ = GtkBase.Widget.add_events my_window#my_window#as_widget [`ALL_EVENTS] in
let _ = my_window#my_window#show() in
Main.main ()

let _ = Printexc.print main ()
\end{verbatim}
\item To define your own callback for ''Quit'' button you have to
  override the default one in the class customized\_callbacks. Modify
  the class like this : 
\begin{verbatim}
class customized_callbacks = object(self)
inherit Hello_glade_callbacks.default_callbacks
method quit () = exit 0
end
\end{verbatim}
\item Recompile and click on your ''Quit'' button to test.
  \end{itemize}
\end{enumerate}
Now you can add other callbacks to your application using glade and
then implement them in your application.

\section{Interacting with widgets}
\label{sec:inter-with-widg}

You can access all the widgets from the callbacks methods. You just need
to know the name you gave to them in glade.
For example, in the ''hello'' example, if you want to change the text of the
label when the button is clicked, you need to modify the method
\texttt{quit} like this :
\begin{verbatim}
method quit () = 
       let the_label= self#top_my_window#label1 in
       the_label#set_text "Another Label"
\end{verbatim}

All widgets are available as methods of \texttt{self\#top\_my\_window}.
There is no tree structure of the widgets. Therefore you should never
give the same name for two widgets in glade.


\section{Building real world applications}
\label{sec:building-real-world}

The first thing you will change is the ''makefile''. The generated one
is very basic and stupid but explains how to compile an application
with gtk support. It can be (and should be) modified at will to fit
your needs. 

The second file you want to edit is the \texttt{hello\_glade\_main.ml}. You
can use it as a guide for your application, but you can ignore it
completely if you want and know how to initialize the lablgtk
library. You just need to define in one of your modules class
inheriting from \texttt{Hello\_glade\_callbacks.default\_callbacks}
which defines the skeleton of your interface.

In any case contact me for help, suggestions, comments and/or
congratulations.

\section{Supported widgets}
\label{sec:implemented-widgets}
This is the list of widgets you can use in glade without problems.
They are mainly on the GTK+ Basic page of the palette window.

\begin{itemize}
\item GtkButton (no stock buttons)
\item GtkCheckb
\item GtkColorSelectionDialog 
        (you cannot change the labels of the buttons inside glade)
\item GtkCombo (no method connect available in GEdit.combo : lablgtk pb ???)
\item GtkDrawingArea
\item GtkEntry
\item GtkEventBox
\item GtkFileSelection (you cannot change the labels of the buttons inside glade)
\item GtkFontSelectionDialog 
        (you cannot change the labels of the buttons inside glade)
\item GtkHBox
\item GtkHButtonBox
\item GtkHPaned
\item GtkHSeparator
\item GtkHandleBox
\item GtkLabel
\item GtkList
\item GtkMenu
\item GtkMenuBar
\item GtkMenuItem
\item GtkNoteBook
\item GtkOptionMenu
\item GtkPixmap
\item GtkProgressBar
\item GtkScrolledWindow
\item GtkSpinButton
\item GtkStatusBar
\item GtkTable
\item GtkText 
\item GtkToolbar
\item GtkToggleButton
\item GtkTree
\item GtkVBox
\item GtkVButtonBox
\item GtkVPaned
\item GtkVSeparator
\item GtkViewPort
\item GtkWindow
\end{itemize}


\section{Contact information}
\label{sec:contact-information}

The latest version of this file is available from
\url{http://www.lri.fr/\home{monate}/mlglade}.

You can contact the author : 
\noindent Benjamin Monate\\
\mailto{Benjamin.Monate@lri.fr}

\end{document}