fpc/docs/gtk5.tex

\documentclass[10pt]{article}
\usepackage{a4}
\usepackage{epsfig}
\usepackage{listings}
\usepackage{tabularx}
\lstset{language=Delphi}%
\lstset{basicstyle=\sffamily\small}%
\lstset{commentstyle=\itshape}%
\lstset{keywordstyle=\bfseries}%
%\lstset{blankstring=true}%
\newcommand{\file}[1]{\textsf{#1}}
\newcommand{\var}[1]{\texttt{#1}}
\usepackage[pdftex]{hyperref}
\newif\ifpdf
\ifx\pdfoutput\undefined
  \pdffalse
\else
  \pdfoutput=1
  \pdftrue
\fi
\begin{document}
\title{Programming GTK in Free Pascal: Using GDK}
\author{Florian Kl\"ampfl\\and\\Micha\"el Van Canneyt}
\date{July 2001}
\maketitle
\section{Introduction}
In this article, some of the graphics primitives from the gdk toolkit will
be demonstrated in a small game - breakout.

The GTK toolkit widgets are built upon the GDK: Graphics Drawing Kit. 
The GDK does not know anything about buttons, menus checkboxes and so on.
Instead, it knows how to create windows, draw on them, handle mouse clicks
and keypresses. This functionality is used by the GTK widget set to create
usable widgets.

Sometimes, the widgets offered by GTK are not enough, and one has to fall
back on the graphics functionality of the GDK to be able to do what is 
needed for a program.

Fortunately, it is not necessary to create a GTK window and handle all
GDK events to be able to use the GDK functions. The GTK widget set has a
special widget, which can be used to draw upon. This widget is the 
\var{TGtkDrawingArea} widget. The use of the \var{TGtkDrawingArea} is what
will be explained below.

The GDK graphics functions will be explained using a simple arcade game,
to demonstrate that the speed of the GDK is sufficient for the creation of
simple games. The breakout game is chosen because it is conceptually simple, 
requires moving graphics and can be extended in many ways.

\section{The drawing area widget}
The drawing area widget (\var{TGTKDrawingArea}) is a simple widget which
just provides a drawing window. It responds to all widget events, and adds
additionally the 'configure\_event', which is called when the widget is
realized (i.e. when the window handle is created.)

The widget has only 1 method: \var{gtk\_drawing\_area\_size}, which sets
the size of the drawing area. It is defined as follows:
\begin{verbatim}
procedure gtk_drawing_area_size(Area:PGtkDrawingArea; width:gint;height:gint) 
\end{verbatim}
The arguments to this function are self-explaining.

To use the drawing area widget, one should respond to the 'expose\_event'.
This event is triggered whenever a part of the window that was invisible,
becomes visible. The event handler gets an \var{PGDKEventExpose} parameter,
which describes which area was exposed. This can be used for optimization
purposes.

To draw in the drawing area widget, the \var{Window} field of the
\var{TGTKWidget} parent can be used. This is of type \var{TGDKWindow}.
All drawing functions require a parameter of type \var{TGdkDrawable}
which can be one of the \var{TGdkWindow} or \var{TGdkPixMap} types.

\section{Graphics contexts}
Most drawing functions do not only require a drawable to draw on, they also
require a {\em Graphics Context}. A graphics context is a series of
parameters that determine how lines are drawn, what colors and font are
used etc.

The Graphics Context is an opaque record, and its members cannot be
accessed. The relevant parameters are set in a \var{TGdkGCValues} record,
which is defined as follows:
\begin{verbatim}
foreground : TGdkColor;
background : TGdkColor;
font : PGdkFont;
thefunction : TGdkfunction;
fill : TGdkFill;
tile : PGdkPixmap;
stipple : PGdkPixmap;
clip_mask : PGdkPixmap;
subwindow_mode : TGdkSubwindowMode;
ts_x_origin : gint;
ts_y_origin : gint;
clip_x_origin : gint;
clip_y_origin : gint;
graphics_exposures : gint;
line_width : gint;
line_style : TGdkLineStyle;
cap_style : TGdkCapStyle;
join_style : TGdkJoinStyle;
\end{verbatim}
The \var{ForeGround} and \var{Background} parameters determine the foreground
and background colors. \var{Font} is the default font. The \var{Fill} field
describes how areas are filled. It can be one of the following:
\begin{description}
\item[GDK\_SOLID] fill with the foreground color.
\item[GDK\_TILED] Use the pixmap specified in \var{Tile} to fill the area.
\item[GDK\_STIPPLED] Use the pixmap specified in \var{Stipple} to draw
pixels that are in the bitmap in the foreground color. Other bits are not
drawn.
\item[GDK\_OPAQUE\_STIPPLED] Same as \var{GDK\_STIPPLED} except that bits 
not in the pixmap will be drawn in the background color.
\end{description}
The \var{clip\_bitmap} is used to define a clip area. The
\var{ts\_x\_origin} and \var{ts\_y\_origin} define the stipple or tile
origin.  The \var{clip\_x\_origin} and \var{clip\_y\_origin} fields define 
the origin of the clipping region.
\var{LineWidth} is the linewidth used when drawing lines. \var{Line\_Style}
determines how dashed lines are drawn. It can have one of the following
values:
\begin{description}
\item[GDK\_LINE\_SOLID] Lines are drawn solid.
\item[GDK\_LINE\_ON\_OFF\_DASH] Even segments are drawn, odd segments are
not.
\item[GDK\_LINE\_DOUBLE\_DASH] Even segments are drawn, Odd segments are
drawn in the background color if the fill style is \var{GDK\_SOLID}.
\end{description}
\var{cap\_style} determines how line ends are drawn. The following values are
defined:
\begin{description}
\item[GDK\_CAP\_BUTT] The lines are drawn with square ends.  
\item[GDK\_CAP\_NOT\_LAST] Idem as \var{GDK\_CAP\_BUTT}, only for zero-width
lines, the last dot is not drawn.
\item[GDK\_CAP\_ROUND] The end of the line is a semicircle. The circle has
diameter equal to the linewidth, and the center is the endpoint of the line.
\item[GDK\_CAP\_PROJECTING] Idem as [GDK\_CAP\_BUTT], only the line extends
half the linewidth outside the endpoint.
\end{description}

The effect of these elements will be shown in the next section.

To set a color, a \var{TGDkColor} record must be allocated. Colors are
specified using a RGB value. Unfortunately, not all graphics cards can
show all colors. In order to find out which screen color corresponds 
to the RGB-specified color, the GDK uses a colormap, and allocates a
color that matches the closest to the specified color values. 
When allocating a new color, the colormap should be specified.

A colormap can be obtained from a \var{TGTKWidget} object using the
\var{gtk\_widget\_get\_colormap} function; A color can then be allocated
using the \var{gdk\_colormap\_alloc\_color} function:
\begin{verbatim}
function gdk_colormap_alloc_color(colormap:PGdkColormap; 
                                  color:PGdkColor;
                                  writeable:gboolean; 
                                  best_match:gboolean):gboolean;
\end{verbatim}
The \var{writeable} parameter specifies whether changes in the
\var{color} using \var{gdk\_color\_change} are allowed.
\var{best\_match} specifies whether a best match should be attempted 
on existing colors or an exact value is required.
The function returns \var{True} if the allocation succeeded, 
\var{False} otherwise.

\section{Drawing primitives}
Using the properties introduced in the previous section, drawing can be
attempted using the drawing primitives offered by GDK. GDK offers drawing
functions for points, lines, segments, rectangles, polygons, circles, text
and bitmaps.

All functions accept as the first two parameters a \var{PGDKdrawable}, which
can be a pointer to a \var{TGDKWindow} or a \var{TGDkPixmap}, and a 
\var{PGdkGC}, a pointer to a graphics context. 

These parameters are omitted from the following declarations:
\begin{verbatim}
procedure gdk_draw_point(x,y:gint);
procedure gdk_draw_line(x1,y1,x2,y2:gint);
procedure gdk_draw_rectangle(filled,x,y,width,height:gint);
\end{verbatim}
The above functions draw respectively a dot, a line and a rectangle.
The meaning of the parameters for these functions is obvious.
For the rectangle, care must be taken. If the parameter \var{Filled} is 
False (-1) then the drawn rectangle has actually a width and height of
\var{Width+1}, \var{Height+1}. If it is filled, then the width and 
height are as specified in the call to \var{gdk\_draw\_rectangle}.

The following functions can be used to draw a series of lines:
\begin{verbatim}
procedure gdk_draw_polygon(filled:gint;points:PGdkPoint; npoints:gint);
procedure gdk_draw_lines(points:PGdkPoint; npoints:gint);
procedure gdk_draw_segments(segs:PGdkSegment; nsegs:gint);
\end{verbatim}
The \var{gdk\_draw\_polygon} polygon takes a series of dots and connects 
them using lines, optionally filling them. The points are specified by a
pointer to an array of \var{TGDKPoint} records (there should be \var{npoint}
such records in the array). 
A \var{TGDKPoint} record contains 2 fields: \var{X,Y} which specify the 
location of a point. 
If needed, the first and last points are also connected using a line.

The \var{gdk\_draw\_lines} does the same, only it cannot be filled, and it 
will not connect the first and last points.
The \var{gdk\_draw\_segments} requires a series of \var{TGDKSegment}
records. These consist of 4 fields: \var{x1,y1,x2,y2}, each describing
the start and end point of a line segment. The segments will not be
connected.

The \var{gdk\_draw\_arc} can be used to draw a circle or a segment of
the circle, or an ellipse.
\begin{verbatim}
procedure gdk_draw_arc(filled,x,y,width,height,angle1,angle2 : gint);
\end{verbatim}
The \var{x,y, width} and \var{height} parameters describe a bounding
rectangle for the circle. The angles describe the start and extending 
angle of the segment to be drawn: The circle segment starts at angle
\var{angle1} and ends at \var{angle1+angle2}. These angles are specified 
in 1/64ths of a degree and are measured counterclockwise, starting at 
the 3 o'clock direction. A circle segment drawn from 90 to 270 degrees 
should therefore have as angles 90*64=5760 and 270*64=17280.

If filled is \var{True} (-1), then the segment will be connected to
the circle centre, and filled, in effect drawing a pie-slice.

Finally, for the \var{gdk\_draw\_string} function, the graphics context comes
before the graphics context:
\begin{verbatim}
procedure gdk_draw_string(drawable:PGdkDrawable; font:PGdkFont; gc:PGdkGC;
                          x:gint; y:gint; thestring:Pgchar);
\end{verbatim}
The meaning of the parameters for this functions should be obvious.

The font for the \var{gdk\_draw\_string} can be obtained using the
\var{gdk\_font\_load} function:
\begin{verbatim}
  function gdk_font_load(font_name:Pgchar):PGdkFont;
\end{verbatim}
The font name should be specified as an X font path.

All this is demonstrated in the following program:
\begin{lstlisting}{}
program graphics;

{$mode objfpc}
{$h+}

uses glib,gdk,gtk,sysutils;

var 
  window, 
  area : PGtkWidget;

Function CloseApp(widget : PGtkWidget ;
                  event : PGdkEvent;
                  data : gpointer) : boolean; cdecl;
Begin
  gtk_main_quit();
  close_application := false;
End;

Function AllocateColor(R,G,B : Integer; 
                       Widget : PGtkWidget) : PGdkColor;

begin
  Result:=New(PgdkColor);
  With Result^ do
    begin
    Pixel:=0;
    Red:=R;
    Blue:=B;
    Green:=G;  
    end;
  gdk_colormap_alloc_color(gtk_widget_get_colormap(Widget),
                           Result,true,False);
end;

function Exposed(Widget: PGtkWidget;
                 event : PGdkEventExpose; 
                 Data : gpointer) : Integer; cdecl;

Const 
  Triangle : Array[1..4] of TgdkPoint = 
            ((X:10;Y:195),
             (X:110;Y:195),
             (X:55;Y:145),
             (X:10;Y:195));
  LineStyles : Array[1..5] of TgdkLineStyle = 
          (GDK_LINE_SOLID, GDK_LINE_ON_OFF_DASH, 
           GDK_LINE_DOUBLE_DASH, GDK_LINE_ON_OFF_DASH, 
           GDK_LINE_SOLID);
  capstyles : Array[1..5] of TgdkCapStyle = 
          (GDK_CAP_ROUND,GDK_CAP_NOT_LAST, GDK_CAP_BUTT,  
           GDK_CAP_PROJECTING, GDK_CAP_NOT_LAST);
          
Var
  SegTriangle : Array[1..3] of TgdkSegment;
  Win : pgdkWindow;
  gc : PgdkGC;
  i,seg : Integer; 
  font : PgdkFont;
  Angle1,Angle2 : Longint;
    
begin
  gc:=gdk_gc_new(widget^.Window);
  Win:=widget^.window;
  With Event^.area do
    gdk_window_clear_area (win,x,y,width,height);
  gdk_gc_set_foreground(gc,allocatecolor(0,0,0,Widget));
  gdk_draw_rectangle(win,gc,0,5,5,590,390);
  gdk_gc_set_foreground(gc,allocatecolor(0,0,$ffff,Widget));
  for I:=10 to 50 do
    gdk_draw_point(win,gc,I*10,100);
  gdk_gc_set_foreground(gc,allocatecolor($ffff,0,0,Widget));
  for I:=10 to 50 do
    begin
    gdk_gc_set_line_attributes(gc,6,LineStyles[i div 10],CapStyles[i div 10],GDK_JOIN_MITER);
    gdk_draw_line(win,gc,I*10,20,I*10,90)
    end;
  gdk_gc_set_line_attributes(gc,1,GDK_LINE_SOLID,GDK_CAP_BUTT,GDK_JOIN_MITER);
  gdk_gc_set_foreground(gc,allocatecolor($ffff,0,$ffff,Widget));
  seg:=(360 div 20) * 64;
  For I:=1 to 20 do
    gdk_draw_arc(win,gc,0,220-I*4,200-i*4,8*i,8*i,i*seg,seg*19);
  For I:=1 to 20 do
    gdk_draw_arc(win,gc,-1,380-I*4,200-i*4,8*i,8*i,(i-1)*seg,seg);
  gdk_gc_set_foreground(gc,allocatecolor(0,$ffff,$ffff,Widget));
  gdk_draw_polygon(win,gc,0,@triangle[1],4);  
  For I:=1 to 4 do
    Triangle[i].Y:=400-Triangle[i].y;
  gdk_draw_polygon(win,gc,-1,@triangle[1],4);  
  gdk_gc_set_foreground(gc,allocatecolor(0,$ffff,0,Widget));
  For I:=1 to 4 do
    Triangle[i].X:=600-Triangle[i].x;
  gdk_draw_lines(win,gc,@triangle[1],4);
  For I:=1 to 3 do
    begin
    SegTriangle[i].X1:=Triangle[i].X;
    SegTriangle[i].Y1:=400-Triangle[i].Y;
    SegTriangle[i].X2:=Triangle[i+1].X;
    SegTriangle[i].Y2:=400-Triangle[i+1].Y;
    end;
  gdk_draw_segments(win,gc,@segtriangle[1],3);
  font:=gdk_font_load('-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1');
  gdk_gc_set_foreground(gc,allocatecolor($ffff,$ffff,0,Widget));
  For I:=1 to 4 do
    gdk_draw_string(win,font,gc,I*100,300,Pchar(format('String %d',[i])));
  result:=0;
end;

Begin
  // Initialize GTK and create the main window
  gtk_init( @argc, @argv );
  window := gtk_window_new( GTK_WINDOW_TOPLEVEL );
  gtk_window_set_policy(PgtkWindow(Window),0,0,1);
  gtk_signal_connect (GTK_OBJECT (window), 'delete_event',
          GTK_SIGNAL_FUNC( @CloseApp ), NIL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 10);
  area := gtk_drawing_area_new();
  gtk_container_add( GTK_CONTAINER(window), Area);
  gtk_signal_connect (GTK_OBJECT (area),'expose_event',
                      GTK_SIGNAL_FUNC(@Exposed),Nil);
  gtk_drawing_area_size (PGTKDRAWINGAREA(area),600,400);
  gtk_widget_show_all( window ); 
  gtk_main();
end.
\end{lstlisting}
The main program starts by creating a main window,
and adding a \var{TGTKDrawingArea} to it. It then connects 2 event handlers,
one to stop the application if the window is closed (\var{CloseApp}),  
the other to draw the \var{TGTKDrawingArea} when it is exposed 
(\var{Exposed}). This latter contains the actual drawing routines, and is
pretty self-explaining. It simply demonstrates the use of the drawing
primitives explained above.

Note that the allocated colors are not freed again, so this program does
contain a memory leak.

\section{Animation}
The GDK drawing functions can be used to draw directly on a window visible
on the screen. This is OK for normal applications, but applications that
have a lot of (changing) graphics will soon see a flickering screen. 

Luckily, GDK provides a means to cope with this: Instead of drawing directly
on the screen, one can draw on a bitmap which exists in memory, and copy
parts of the bitmap to the screen on an as-need basis.

This is the reason why the GDK drawing functions generally accept a
\var{PGDKdrawable} parameter: This can be of the type \var{PgdkWindow} or
\var{PGDKPixmap}: The \var{TGDKPixmap} can be used to do the drawing in the
background, and then copy the pixmap to the actual window. 

This technique, known as double buffering, will be demonstrated in a small
arcade game: BreakOut. The game is quite simple: at the top of the screen,
there are a series of bricks. At the bottom of the screen is a small pad,
which can be move left or right using the cursor keys. A ball bounces on the
screen. When the ball hits a brick, the brick dissappears. When the ball
hits the bottom of the window, the ball is lost. The pad can be used to
prevent the ball from hitting the bottom window.

When the pad hits the ball, the ball is accellerated in the direction the
pad was moving at the moment of impact. Also, an idea of 'slope' is
introduced: If the ball hits the pad at some distance from the pad's center,
the ball's trajectory is slightly disturbed, as if the pad has a slope.

After 5 balls were lost, the game is over. If all bricks have been
destroyed, a next level is started.

As stated above, the game will be implemented using double buffering.
The ball and pad themselves will be implemented as pixmaps; the bricks
will be drawn as simple rectangles.

These three objects will be implemented using a series of classes:
\var{TGraphicalObject}, which introduces a position and size. This class
will have 2 descendents: \var{TBlock}, which will draw a block on the
screen and \var{TSprite}, which contains all functionality to draw a moving
pixmap on the screen. From \var{TSprite}, \var{TBall} and \var{TPad} will be
derived. These two objects introduce the behaviour specific to the ball and
pad in the game.

The blocks will be managed by a \var{TBlockList} class, which is a
descendent of the standard \var{TList} class. 

All these objects are managed by a \var{TBreakOut} class, which contains the
game logic. The class structure could be improved a bit, but the idea is
more to separate the logic of the different objects.

The \var{TGraphicalObject} class is a simple object which introduces some 
easy access properties to get the position and size of the object:
\begin{verbatim}
TGraphicalObject  = Class(TObject)
  FRect : TGdkRectangle;
Public 
  Function Contains(X,Y : Integer) : Boolean;
  Property Left : SmallInt Read FRect.x Write Frect.x;
  Property Top : SmallInt  Read FRect.y Write Frect.y;
  Property Width : Word  Read Frect.Width Write Frect.Width;
  Property Height : Word  Read Frect.Height Write Frect.Height;
end;
\end{verbatim}

The \var{TBlock} object is a simple descendent of the var{TGraphicalObject}
class:
\begin{verbatim}
TBlock = Class(TGraphicalObject)
Private
  FMaxHits : Integer;
  FBlockList : TBlockList;
  FGC : PGDKGC;
  FColor : PGDKColor;
  FNeedRedraw : Boolean;
  Procedure CreateGC;
  Function DrawingArea : PGtkWidget;
  Function PixMap : PgdkPixMap; 
Public
  Procedure Draw;
  Function Hit : Boolean;
  Constructor Create (ABlockList : TBlockList);
  Property Color : PGDKColor Read FColor Write FColor;
end;
\end{verbatim}
The \var{FMaxHits} field determines how many times the ball must hit the
brick before it dissappears. With each hit, the field is decremented by 1.

The \var{FBlockList} refers to the blocklist object that will manage the 
block. The needed drawing widget and the pixmap on which the block must be
drawn are obtained from the blockmanager using the \var{DrawingArea} and 
\var{Pixmap} functions.
The \var{Draw} procedure will draw the block at it's position on the pixmap.
The \var{Color} property determines the color in which the block will be
drawn.

The implementation of the \var{TBlock} methods are quite simple. The first
methods don't need any explanation.
\begin{verbatim}
Constructor TBlock.Create (ABlockList : TBlockList);

begin
  Inherited Create;
  FBlockList:=ABlockList;
  FMaxHits:=1;
end;

Function TBlock.DrawingArea : PGtkWidget;

begin
  Result:=FBlockList.FBreakout.FDrawingArea;
end;

Function TBlock.PixMap : PgdkPixMap; 

begin
  Result:=FBlockList.PixMap;
end;
\end{verbatim}
The first interesting method is the \var{CreateGC} method:
\begin{verbatim}
Procedure TBlock.CreateGC;

begin
  FGC:=gdk_gc_new(DrawingArea^.Window);
  gdk_gc_set_foreground(FGC,FColor);
  gdk_gc_set_fill(FGC,GDK_SOLID);
  FNeedRedraw:=True;
end;
\end{verbatim}
The method is called the first time the block must be drawn. It allocates a
new graphics context using the \var{gdk\_gc\_new} function. This function
accepts a pointer to a \var{TGTKWidget} as a parameter and returns a new
graphics context. After the graphics context is created, the foreground
color and fill style are set. (it is assumed that \var{FColor} points
to a valid color)

The \var{Draw} procedure actually draws the block on the pixmap, using 
the graphics context created in the previous method:
\begin{verbatim}
Procedure TBlock.Draw;

begin
  if FGC=Nil then
    CreateGC;
  if FNeedRedraw Then
    begin
    gdk_draw_rectangle(PGDKDrawable(Pixmap),FGC,-1,Left,Top,Width,Height);
    FNeedRedraw:=False;
   end;
end;
\end{verbatim}
The \var{FNeedRedraw} procedure is used for optimization.

Finally, the \var{Hit} method is called when the block is hit by the ball.
It will decrease the \var{FMaxHits} field, and if it reaches zero, the 
place occupied by the block is redrawn in the background color. After that,
it removes itself from the blocklist and frees itself.
\begin{verbatim}
Function TBlock.Hit : Boolean;

begin
  Dec(FMaxHits);
  Result:=FMaxHits=0;
  If Result then
    begin
    FBlockList.FBreakOut.DrawBackground(FRect);
    FBlockList.Remove(Self);
    Free;
    end;
end;
\end{verbatim}

The \var{TSprite} object is a little more involved. The declaration is 
as follows:
\begin{verbatim}
TSprite = Class(TGraphicalObject)
  FPreviousTop,
  FPreviousLeft : Integer;
  FDrawingArea : PGtkWidget;
  FDrawPixMap : PgdkPixmap;
  FPixMap : PgdkPixMap;
  FBitMap : PGdkBitMap;
Protected
  Procedure CreateSpriteFromData(SpriteData : PPGchar);
  Procedure CreatePixMap; Virtual; Abstract; 
  Procedure SavePosition;
Public
  Constructor Create(DrawingArea: PGtkWidget);
  Procedure Draw;    
  Function GetChangeRect (Var Rect : TGDkRectAngle) : Boolean;
  Property PixMap : PgdkPixMap Read FPixMap;
  Property BitMap : PGdkBitMap Read FBitMap; 
end;
\end{verbatim}
The important property is the \var{PixMap} property; this contains the
pixmap with the sprite's image. The \var{BitMap} property contains the
bitmap associated with the pixmap. The second important method is the
\var{GetChangeRect} method; it returns the rectangle occupied by the
sprite at its previous position. This will be used to 'move' the sprite:
When moving the sprite, the current position is saved (using
\var{SavePosition}), and the new position is set. After that, the old 
position is cleared, and the sprite is drawn at the new position. 

All this drawing is done on the background pixmap, to avoid flickering 
when drawing: The result of the two drawing steps is shown at once.

The implementation of the \var{Draw} method is quite straightforward:
\begin{verbatim}
Procedure TSprite.Draw;    

Var
  gc : PGDKGc;
  
begin
  if FPixMap=Nil then
    CreatePixMap;    
  gc:=gtk_widget_get_style(FDrawingArea)^.fg_gc[GTK_STATE_NORMAL];
  gdk_gc_set_clip_origin(gc,Left,Top);
  gdk_gc_set_clip_mask(gc,FBitmap);
  gdk_draw_pixmap(FDrawPixMap,gc,FPixMap,0,0,Left,Top,Width,Height)
  gdk_gc_set_clip_mask(gc,Nil);  
end;
\end{verbatim}
After the pixmap has been created (a method which must be implemented by
descendent objects), the graphics context of the drawing area is retrieved 
to do the drawing.

The bitmap is drawn using the clipping functionality of the GDK toolkit:
To this end, the clip origin is set to the position of the sprite, and
the clip bitmask is set from the \var{FBitmap}, which is created when the
sprite's pixmap is created. When drawing the pixmap, only the bits in the
bitmap will be drawn, other bits are left untouched.

The pixmap is drawn using the \var{gdk\_draw\_pixmap} function. This
function copies a region from one \var{TGDKDrawable} to another.
It is defined as follows:
\begin{verbatim}
procedure gdk_draw_pixmap(drawable:PGdkDrawable; gc:PGdkGC; 
                          src:PGdkDrawable; 
                          xsrc,ysrc,xdest,ydest,width,height:gint);
\end{verbatim}
The function, as all GDK drawing functions, takes a \var{PGDKDrawable} 
pointer and a graphics contexts as its first two arguments. The third
argument is the \var{TGDKDrawable} which should be copied. The
\var{xsrc,ysrc} parameters indicate the position of the region that should
be copied in the source \var{TGDKDrawable}; the \var{xdest,ydest} indicate 
the position in the target \var{TGDKDrawable} where the bitmap should be
drawn.

In the case of \var{TSprite}, the function is used to copy the sprite's 
bitmap onto the memory pixmap with the game image. After the bitmap was
copied, the clip mask is removed again.

The creation of the pixmap happens when the sprite is drawn for the first
time; The \var{CreateSpriteFromData} method accepts a pointer to an XPM
pixmap, and uses the \var{gdk\_pixmap\_create\_from\_xpm\_d} function
(explained in the previous article) to create the actual pixmap and the 
corresponding bitmap.
\begin{verbatim}
Procedure TSprite.CreateSpriteFromData(SpriteData : PPGChar);

begin
  FPixMap:=gdk_pixmap_create_from_xpm_d(FDrawingArea^.Window, 
                                        @FBitmap,
                                        Nil,
                                        SpriteData);
end;
\end{verbatim}
This method can be used by the descendent object's \var{CreatePixmap} 
procedure.

The \var{SavePosition} and \var{GetChangeRect} methods are very
straightforward:
\begin{verbatim}
Function TSprite.GetChangeRect (Var Rect : TGDkRectAngle) : Boolean;

begin
  Result:=(FPreviousLeft<>Left) or (FPreviousTop<>Top);
  If Result then
    With Rect do
      begin
      x:=FPreviousLeft;
      y:=FPreviousTop;
      Width:=Abs(Left-FPreviousLeft)+self.Width;
      height:=Abs(Top-FPreviousTop)+self.Height;
      end;
end;

Procedure TSprite.SavePosition;

begin
  FPreviousLeft:=Left;
  FPreviousTop:=Top;
end;
\end{verbatim}
Note that the \var{GetChangeRect} procedure returns false if the position
of the sprite didn't change. This is used for optimization purposes.

The pad is the simplest of the two \var{TSprite} descendents. It only adds a
horizontal movement to the sprite:
\begin{verbatim}
TPad = Class (TSprite)
Private
  FSlope,
  FSpeed,FCurrentSpeed : Integer;
Protected
  Procedure CreatePixMap; override;
  Procedure InitialPosition; 
Public  
  Constructor Create(DrawingArea: PGtkWidget);
  Procedure Step;
  Procedure GoLeft;
  Procedure GoRight;
  Procedure Stop;
  Property CurrentSpeed : Integer Read FCurrentSpeed;
  Property Speed : Integer Read FSpeed Write FSpeed;
  Property Slope : Integer Read FSlope Write FSlope;
end;
\end{verbatim}
The procedures \var{GoLeft}, \var{GoRight} and \var{Stop} can be used to
control the movement of the pad. The method \var{Step} will be called at
regular intervals to actually move the pad. The \var{InitialPosition} 
sets the pad at its initial position on the screen. The \var{Speed} and 
\var{Slope} properties can be used to set the speed and slope of the pad.

The implementation is quite straightforward:
\begin{verbatim}
\end{verbatim}

\end{document}