\documentclass[12pt]{report}
\usepackage{epsfig}
% <fsm>
%\usepackage{../tools/verbawf2e}
%\usepackage{../tools/cxx}
%\newcommand{\FSMinput}[1]{\input{#1}}
\usepackage{/users/kym/target/target/vxl/vgui/doc/tools/verbawf2e}
\usepackage{/users/kym/target/target/vxl/vgui/doc/tools/cxx}
\newcommand{\FSMinput}[1]{}
% </fsm>
\usepackage{alltt}
\topmargin=-0.5in
\oddsidemargin=-0.2in
\evensidemargin=0.1in
\textwidth=6.6in
\textheight=8.9in
\parskip =.16in
\parindent=0in


\begin{document}
\title {\ VGUI \\ Tutorial for application programmers}

\author{Karen McGaul \\ Robotics Research Group \\ Department of
  Engineering Science\\ University of Oxford}

\maketitle
\pagenumbering{roman}

{\sf\large Copyright} \\
All rights reserved. No part of this work may be reproduced, stored in
a retrieval system, or transmitted, in a form or by any means,
electronic, mechanical, photocopying, recording or otherwise,without
the prior written permission of the author.

\bigskip

{\sf\large Warranties} \\
Robotics Research Group makes no warranties,either express or implied,
regarding the enclosed computer software package, its merchantability,
or its fitness for any particular purpose. This publication may be
revised from time to time, without notice.
While all care has been taken to ensure this document's accuracy,
Robotics Research Group assumes no responsibility for any errors which
may appear.

\pagenumbering{arabic}
\newpage
\tableofcontents
\newpage

\chapter{Introduction}

The purpose of this document is to provide an overview of the
GUI (graphical user interface) used with Target.  It should provide all the
information necessary to write applications but does not go into
details about the design and internal workings of the new GUI system.  It is
assumed that the reader has a reasonable knowledge of C++.

\section{Getting started}

This document consists of example programs which introduce different aspects of GUI.
This is what you will need to do to compile and run the examples:

Make a copy of the examples directory.  Source code and CMakeLists.txt are provided.
%***urgh: out of date
\scriptsize
\begin{verbawf}
  unix% mkdir ~/examples
  unix% cd ~/examples/
  unix% cp $VXLROOT/core/vgui/examples/*.cxx $VXLROOT/core/vgui/examples/CMakeLists.txt ./
\end{verbawf}
\normalsize

If you want to compile the examples use
\scriptsize
\begin{verbawf}
  unix% cmake .
\end{verbawf}
\normalsize

In order to run the examples use
\scriptsize
\begin{verbawf}
  unix% ./example<something> <--factory=gui-toolkit> <image>
\end{verbawf}
\normalsize

The user interface consists of two parts:
\begin{itemize}
\item an OpenGL area/window used to display images and 3D models
(this is called a tableau)
\item a GUI toolkit used to create menus, buttons, etc.
\end{itemize}

If one of these examples is run with no preference given on the command line
for a GUI toolkit then application will look to find a suitable GUI toolkit that is
registered.  If more than one GUI toolkit is registered then one will be selected at
random.  If you wish to specify a GUI toolkit (for example Foo) then you will need to add
{\tt --factory=Foo} to the end of the command line or set the variable
{\tt vgui} to Foo.

\chapter{Displaying images and 2D objects}

\section{Displaying an image}
This first example simply displays an image in a window.
The image is loaded into a tableau which displays images ({\tt vgui\_image\_tableau})
and this is put inside a 2D viewer tableau ({\tt vgui\_viewer2d}).  The 2D viewer
adds the functionality that would commonly be required for viewing 2D images
and objects such as zooming and moving which part of the image is displayed.

Pressing the control key and the right mouse button on the image zooms the
image out, the control key and the left mouse button zoom in.  The control key
and middle button allow the image to be dragged around the display area.
\FSMinput{display-image}

\section{Displaying 2D objects}
In order to display 2D objects we need to use a different tableau called {\tt vgui\_easy2D}.
This tableau has functions which allow us to draw points, lines and other geometric
objects.  As in the previous example we include this into a 2D viewer tableau.
\FSMinput{draw-line}

\section{Displaying images and 2D objects together}
To display images and 2D objects together we simply ``stack'' tableaux with the
required functionality.  So all we need to do is add an image tableau to an easy2D tableau.
\FSMinput{2d-example}

\chapter{Menus and dialog boxes}

\section{Adding a menubar}

To make a menubar we simply create a {\tt vgui\_menu} (a menu description) and pass that in when we call
{\tt vgui::produce\_window}.

\FSMinput{menubar-example}

\section{Adding a pop-up menu}

A pop-up menu is also specified by a {\tt vgui\_menu}.  In this next example we take the
same {\tt vgui\_menu} we used to specify the menubar, but this time we add it to a
pop-up menu.

\FSMinput{popup-example}

Click the right mouse button anywhere on the image to get the pop-up menu to appear.
The implementation of pop-up menus in VGUI is very simple: you can only attach a menu
to a tableau and the default method to get it to ``pop up'' is a right mouse click.

Other items in the pop-up menu that we didn't specifiy are the default items for an
image tableau.  You would see these items in a pop-up menu if you right clicked on any
of the previous examples.  If you wish to replace the default pop-up menu (instead of
adding to it) then instead of {\tt include\_in\_popup}, use the function {\tt add\_popup}.

\section{Adding a dialog box}

To make a dialog box, create a {\tt vgui\_dialog}.  In this example the dialog box is
shown when we select the menu item called ``Dialog'',

\FSMinput{dialog-example}

\chapter{Handling events}

\section{Getting mouse position}

When a mouse button is pressed it produces an event which is passed to the
{\tt handle\_impl} function of the tableau.  In order to use a mouse event we need to write
our own tableau which is derived from a {\tt vgui\_tableau}.

In this next example we get the mouse position when the left mouse button is pressed on
the image.  The mouse position is given in viewport coordinates with the lower-left corner
as the origin. (In general the viewport will be the area displaying OpenGL).

\FSMinput{mouse-position}

We can use this to draw a line onto the image.  In this next example a line is drawn between
two points selected by pressing the left mouse button.
\FSMinput{mouse-draw-line}

\section{Rubberbanding}

A nicer way to add a line to an image is to use rubberbanding.  VGUI contains a
rubberbanding tableau (vgui\_rubberbander) which takes a vgui\_easy2D as its child.  This
next example allows the user to select either a line, circle or polygon to rubberband.
\FSMinput{rubberband}

\chapter{Displaying 3D objects}
3D objects can be added using the easy3D tableau and putting it inside a viewer3D tableau
gives functionality to zoom and move the object.

Pressing the shift key and left mouse button then dragging the mouse moves the object in
3 dimensions.
\FSMinput{3d-example}

\chapter{More complicated GUIs}

There are several reasons why you may wish to write your application without using
the VGUI pattern.  One reason is that only menus and dialog boxes are available using
the pattern provided by VGUI. If you want to use more complicated widgets in your
GUI (e.g. sliders, buttons) then you will have to write the application for one
particular GUI toolkit only.

Alternatively you may be very familiar with a particular toolkit and not want to learn
the VGUI pattern for menus etc (but remember this will make your code less portable).

As a first example here is the display image example again, but this time written in GTK.
We still use the tableau code from VGUI to create the OpenGL area where the image is
displayed and the {\tt vgui\_gtk\_adaptor} class to plug the OpenGL area into our GTK code.

\FSMinput{gtk-display-image}

In this next example we are writing a movie player and we want to use
buttons to stop and start the movie.  In order to do this the application
has been written in GTK.

\FSMinput{gtk-movie-player}

\end{document}
