Added a title page

[AXE.git] / doc / tutorial.xml

<?xml version="1.0"?>
<!DOCTYPE doc SYSTEM "/usr/local/xslt/doc.dtd">

<doc>

<!--
      AXE - Andromeda X-Windows Encapsulation
      Original author :  Arjen Baart - arjen@andromeda.nl
      Version         : $Revision: 1.2 $

      This document is prepared for XMLDoc. Transform to HTML,
      LaTeX, Postscript or plain text with XMLDoc utilities and
      XSLT sheets from http://www.andromeda.nl/projects/xmldoc/
-->

<book>

<titlepage>
   <title>AXE Tutorial</title>
   <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
   <date>July 24, 2002</date>
   <docinfo>
      <infoitem label="Version">0.2</infoitem>
      <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
   </docinfo>
   <abstract>
   </abstract>
</titlepage>

<toc/>

<chapter>
<heading>Introduction</heading>
<para>
The <strong>Andromeda X-Windows Encapsulation (AXE)</strong> is a C++ class
library which encapsulates the X Windows library (<emph>Xlib</emph>).
Classical programming with Xlib is rather cumbersome to say the least.
The Xlib calls are rather complicated and often require many parameters
that can more easily be stored in objects.
Also, the classical event loop present in most X applications is something
you don't want to reinvent every time.
That sort of thing is better left to a framework which provides you
with more easy way to deal with events from the X server.
</para>

<para>
The intention of <strong>AXE</strong> is to make programming for X a lot
easier.
It was first developed to teach programming in C++ to students and let
them do some graphics without being confronted by the X library.
Over the past years it has grown into a framwork that not only encapsulates
the resources in the X server, like windows, colors and graphic context,
but provides some mechanisms that handle low-level communication with
the X server, user interface classes, multithreading and utility classes.
Although functionality of <strong>AXE</strong> overlaps with some other
user interface libraries such as <emph>gtk+</emph> or <emph>Qt</emph>,
the first goal of <strong>AXE</strong> is not to be a user interface
library.
Some of the design goals in <strong>AXE</strong> are not met yet, but
they include features such as dynamically loading of the user interface,
a strong set of graphical object functions, image processing, high-level
graphics objects and lots more.
</para>

<para>
To get you started with <strong>AXE</strong>, this tutorial takes you through
a sample application in which some the features of <strong>AXE</strong>
are touched upon.
The sample application is a doodle program, where the user can freely
draw pictures with the mouse.
The pictures are stored as simple polylines with a few attributes.
Writing the doodle program will show you how to build an <strong>AXE</strong>
application and create the most basic functions for an application.
In this tutorial, I assume you have sucessfully downloaded and installed
<strong>AXE</strong>.
</para>

</chapter>

<chapter>
<heading>A minimal AXE application</heading>

<para>
In this chapter we'll start writing the very minimum to get an AXE
application going.
All we do is make a top-level window, draw something in that window
and add a button to quit the application.
</para>

<section>
<heading>The start: class xapplication</heading>

<para>
Assuming you installed <strong>AXE</strong>, you can start creating the
doodle program.
The first thing you need in each and every <strong>AXE</strong> application
is to create an application class, derived from the class
<code>xapplication</code> and declare a static object of that class.
In the example below, our application class is called <code>doodle</code>
and the static object is <code>DoodleApp</code>:

<verbatim>

#include &lt;AXE/xappl.h&gt;

class doodle: public xapplication
{
};

doodle DoodleApp;

</verbatim>

Note that you need to include the header file <code>AXE/xappl.h</code>
which contains the definition of the <code>xapplication</code> class.
Also note that, other than in classical C or C++ programs, you do not
have a <code>main()</code> function.
This is taken care of by the <strong>AXE</strong> library.

Next, compile and link the application:

<verbatim>
g++ -c doodle1.cpp
g++ -o doodle1 doodle1.o -lAXE -L/usr/X11R6/lib -lX11 -lXpm
</verbatim>

Start the doodle program and you'll see that nothing happes.
All this program does is connect to the X server and wait for
events that will never come.
To do someting visible, we have to create a window and map in on
the screen.
The <code>main()</code> function in <strong>AXE</strong> calls virtual
functions in the static application object, which you can override
in your own application class to get some useful work done.
One of the first functions it calls after makeing the connection with
the X display is <code>SetupResources</code>.
We will now override this function and create a top-level window for
doodle (see <emph>demos/doodle1.cpp</emph>):

<verbatim>
#include &lt;AXE/xappl.h&gt;

class doodle: public xapplication
{
   managed_window *main_frame;

   virtual void SetupResources(void);
};

doodle DoodleApp;

void doodle::SetupResources()
{
   main_frame = new managed_window("Doodling with AXE");
   main_frame-&gt;Map();
}
</verbatim>

We added two items to our <code>doodle</code> class:
<enumerate>
<item>The <code>managed_window</code> pointer to our top-level window:
      <code>main_frame</code>
</item>
<item>The overridden fuunction from the base class:
      <code>SetupResources()</code>
</item>
</enumerate>

In the <code>SetupResources()</code> function, we create the actual
window as a <code>managed_window</code> object.
A <code>managed_window</code> is a window like any other window, except
that is a direct child of the server's root window and as such is
managed by the window manager.
The window manager will put all kinds of decorations on our top-level
window like a title bar, a close button, a menu button, a border for
resizing and that sort of stuff.
Your mileage may vary, depending on the window manager you use.
We pass the title of our application to the constructor of the
<code>managed_window</code>, so we'll know what window we're looking at:

<verbatim>
   main_frame = new managed_window("Doodling with AXE");
</verbatim>

The window is created but is not visible yet.
To show the window on the screen, we have to <strong>Map</strong> the
window with the member function <code>Map()</code>.
When you start the program, it will show the empty window with our
'Doodling with AXE' title in the titlebar:

<para>
<picture src='tutor2.1.png' eps='tutor2.1.eps'/>
</para>

You can do most of the usual things a window manager lets you do with
the doodle window.
You can minimize and restore or resize and move the window, provided
your window manager implements those functions.
The one thing you can not do is close the window.
The only way to stop doodle1 is to press ctrl-C in the terminal you
started the program.
This is because we do not handle the proper events to let the
window manager close our application.
As a matter of fact we do not handle any events at all, but we'll
get to that in the next section.
</para>

</section>

<section>
<heading>Drawing in the window</heading>

<para>
For drawing graphics in X Windows, we need two things.
First of all the window to draw in, of course. Second, we need a
<emph>Graphics Context</emph>.
A graphics context is a resource in X Windows that defines how graphical
primitives are drawn. It holds all the properties such as backround and
foreground color, line size and dashing, the font for text strings and
much more.
The window part of drawing is easy.
We just created a window for doodle and all graphical drawing functions
are simply member functions of the <code>window</code> class.
The graphics context is encapsulated with the <code>gc</code> class.
For our first example we will create a <code>gc</code> object with a foreground
color of black.
This means that everything we draw in the window is black on a white background
(assuming the default background of the window is white).
To start drawing graphics, we add two lines to our <code>SetupResources()</code>
member funtion:

<verbatim>
   gc    graphic("black");
   main_frame-&gt;DrawRectangle(graphic, 50, 70, 200, 100);

</verbatim>

The parameters to <code>DrawRectangle()</code> are: the graphics context, the X and
Y coordinates of the top left corner and the size (width and height) of the rectangle.
So, this example draws a rectangle that has a top left corner 50 pixels to the right
of the left side of our window and 70 pixels down from the top side of our window.
The rectangle is 200 pixels wide and 100 pixels high.
</para>

<para>
Getting a picture in a window is not so hard in itself.
However, drawing once and immediately after creating the window is not enough
in any practical application.
Try some window operations on your fresh drawing after doodle puts the window
on the screen.
You can resize the window or move windows from other applications over the doodle
window and you'll see the rectangle disappear just as easily as you created it.
That is because the X server does not remember what you drew in the window.
At the moment you call the <code>DrawRectangle()</code> function, the X server
renders the pixels to make the area on the screen look like a rectangle and then
immediately forgets the request to draw the rectangle.
When the doodle window becomes visible again after having been obscured for a while
or when the contents of the window are supposed to change for any other reason,
all the X server can do is clear the area of the window.
It is left to the application to redraw the contents of the window.
</para>

<para>
Fortunately, the X server lets you know when somthing interesting happens to
your windows and when you are supposed to react.
It does this by sending <emph>events</emph> to the application that owns
the window where the event takes place.
The X server sends lots of events for all sorts of reasons.
Events are sent to your application for example when the user clicks a mouse button,
moves the mouse, hits a key on the keyboard or makes parts of your
window visible.
For each type of event, there is a virtual function in the <code>window</code> class.
If you want to handle any of those events from the X server, you have to
override an event handling function in a class you derive from the <code>window</code>
base class.
In our doodle application, we will make a new class and a new window.
The new window is created as a child window of our top level window and we will
draw pictures only in this child window.
Generally, it is not a good idea to do all kinds of drawing in the top level
window.
Any real application uses many windows for various kinds of user interaction
and the top level window is used only to organize all these sub windows and
interact with the window manager.
So, here we go with our own class derived from <code>window</code>, which we will
call a <code>doodle_view</code>:

<verbatim>

class doodle_view : public window
{
public:

   doodle_view(window *parent) : window (*parent, 10, 30, 300, 220)
   {
      SelectInput(ExposureMask, 1);
      Background(color("lightyellow"));
   }

   virtual int EV_Expose(XExposeEvent);
};

</verbatim>

We define two member functions for our <code>doodle_view</code> class: The contructor
function <code>doodle_view()</code> and the overridden event handler for
<emph>Expose</emph> events, <code>EV_Expose()</code>.
In the constructor, we pass the parent window to the contructor of the base class,
<code>window</code> and add the default geometry of our subwindow.
The geometry for a subwindow is very similar to drawing a rectangle.
The four numbers are the X and Y coordinate of the top left corner, the width
and the height of the subwindow, relative to the parent window.
Inside the contructor, we tell <strong>AXE</strong> that we want to handle
<emph>Expose</emph> events by calling <code>SelectInput()</code>.
The first parameter of <code>SelectInput()</code> is a bitmask of the events
we want to select.
The binary values and their names for the mask are the same as the ones defined
for the X library.
The second parameter is a boolean value which is '1' if you want to turn selection
of the events on and '0' of you want these events to be turned off.
We also add a little color to the subwindow, so it stands out more clearly
in the parent window.
The parent window specifies in which window we want to put our subwindow.
In doodle, we create the subwindow as a child of the top level window we created earlier.
A pointer to the subwindow is created inside the <code>doodle class</code>:

<verbatim>

class doodle: public xapplication
{
   managed_window *main_frame;
   doodle_view    *draw_frame;


</verbatim>

The actual creation of the subwindow is put in the <code>SetupResources()</code>
member funtion of the <code>doodle</code> class, right after the creation
of the top level window:

<verbatim>
void doodle::SetupResources()
{
   main_frame = new managed_window("Doodling with AXE");
   main_frame-&gt;Map();

   draw_frame = new doodle_view(main_frame);
   draw_frame-&gt;Map();
}
</verbatim>

Note that we have to <emph>Map</emph> the subwindow, just like the top level
window to make it visible.
</para>

<para>
Finally, we have to implement the event handler function of the <emph>Expose</emph>
event handler, <code>EV_Expose()</code>.
As you may have noticed, the <code>DrawRectangle()</code> is removed from the
<code>SetupResources()</code> function.
We now wait for an expose event from the X server to do the actual drawing.
Every time our window becomes 'exposed' the X server sends an <emph>Expose</emph>
event, to which we react by redrawing our rectangle in the window.
Here is the implementation of the <emph>Expose</emph> event handler:

<verbatim>

int doodle_view::EV_Expose(XExposeEvent ev)
{
   gc    graphic("black");

   DrawRectangle(graphic, 50, 70, 200, 100);

   return 1;
}
</verbatim>

Here you see the <code>gc</code> object and the <code>DrawRectangle()</code>
again, nearly the same as we previously had in the <code>SetupResources()</code>
function of the <code>doodle</code> class.
There is one difference: The pointer to the window (<code>main_frame-&gt;</code>
in our previous example) is removed from the function call.
This is because we are now inside a member funtion of the <code>doodle_view</code>
class and our window is passed implicitly as the <strong>this</strong> pointer
of the object itself.
</para>

<para>
The complete source code of the second doodle example is in the file
<strong>demos/doodle2.cpp</strong> of the <strong>AXE</strong> distribution.
If you compile and run doodle2, it should look like this:

<para>
<picture src='tutor2.2.png' eps='tutor2.2.eps'/>
</para>

You can now move the window all over the screen, resize it, move other windows
over the doodle window and the rectangle we draw in the little yellow window
should stay intact.
</para>

</section>

<section>
<heading>Quitting the application</heading>

<para>
Up until now, we do not have a decent way to quit the doodle application.
You have to kill doodle by sending it a signal, like hitting ctrl-C on your
keyboard.
It's about time to remedy that situation.
There are many ways to close an application, like hitting a specific key
('q' for quit might be a good one), clicking on the close button provided
by the window manager or providing a 'Quit' button or menu item in the
application itself.
We will explore all of these possibilities in later chapters.
For now, to keep things simple, we will use the keyboard to quit doodle.
</para>

<para>
When the user hits a key while the focus is on the doodle window, the X server
sends a <emph>KeyPress</emph> event to our application.
This <emph>KeyPress</emph> event is dispatched by <strong>AXE</strong> to the
window on which the key was pressed, just as <emph>Expose</emph> events are
dispatched to the appropriate window.
In <strong>AXE</strong>, you can use any event to quit your application program.
All you need to do is return the value 0 (zero) from the event handler function.
You may have noticed in the previous section that the <code>EV_Expose()</code>
handler function returned the value 1 (one).
This return value tells the <strong>AXE</strong> library not the quit the program
after the event is handled.
If you return 0 (zero) from an event handler function, <strong>AXE</strong> will
destroy all your windows, close the display connection with the X server
and quit the application.
</para>

<para>
So, to quit doodle on a key stroke, we select <emph>KeyPress</emph> events
next to <emph>Expose</emph> events in our subwindow and override the
<code>EV_KeyPress()</code> event handler function.
To select <emph>KeyPress</emph> events, we add another <code>SelectInput()</code>
in our <code>doodle_view</code> contructor:

<verbatim>
   doodle_view(window *parent) : window (*parent, 10, 30, 300, 220)
   {
      SelectInput(ExposureMask, 1);
      SelectInput(KeyPressMask, 1);
      Background(color("lightyellow"));
   }
</verbatim>

Next, also in the <code>doodle_view</code> class declaration, we add the
declaration of the member function to handle the KeyPress events:

<verbatim>
   virtual int EV_KeyPress(XKeyEvent ev);
</verbatim>

The implementation of the event handler is very trivial.
Just return the value 0 (zero) and doodle will close down when any key
is pressed in the light yellow window:

<verbatim>
int doodle_view::EV_KeyPress(XKeyEvent ev)
{
   return 0;
}
</verbatim>

Having any key at all, even the Ctrl or the CapsLock key, quit doodle is a bit
cruel, don;t you think.
So, let's restrain the quitting to just the lower case 'q' key.
When we get an event from the X server in one of our event handling functions,
all kinds of information about that event is passed in the <emph>ev</emph>
parameter.
Until now, we silently ignored the <emph>ev</emph> parameter but is this
case we need it to find out which key was actually pressed.
There is no special provision in <strong>AXE</strong> to do this.
There are Xlib functions that do the job just fine.
The one Xlib function we use here is <code>XLookupKeysym()</code>, which extracts
information from the <code>XKeyEvent</code> structure and returns
a standardized code (a <emph>KeySym</emph>) of the key that was actually pressed.
For most 'ordinary' keys, the <emph>KeySym</emph> value is the same as the ASCII
value.
We can use the 'q' key simply by checking the <emph>KeySym</emph> for the
value 'q':

<verbatim>
int doodle_view::EV_KeyPress(XKeyEvent ev)
{
   KeySym   key;

   key = XLookupKeysym(&amp;ev, ev.state &amp; 1);

   if (key == 'q')
   {
      return 0;
   }
   else
   {
      return 1;
   }
}
</verbatim>

With this extra check, you can hit any key you want on doodle, but
only the 'q' key makes doodle leave the desktop.
You can find the complete source of this example in <strong>demos/doodle3.cpp</strong>.
</para>

</section>

</chapter>

<!--
 
  Drawing
    tracking mouse events
    storing the strokes.

  Menus, file IO
    the file selector.
    about box

   Window manager
     changing the title
     resizing
     close button
     icon
-->
</book>

</doc>