This is gtkada_rm.info, produced by makeinfo version 4.5 from
gtkada_rm.texi.

INFO-DIR-SECTION User Interface Toolkit
START-INFO-DIR-ENTRY
* GtkAda_Rm: (gtkada_rm).           Ada95 graphical tookit based on GTK+ (Reference Manual)
END-INFO-DIR-ENTRY


File: gtkada_rm.info,  Node: Gtkada.Canvas Subprograms,  Next: Gtkada.Canvas Example,  Prev: Gtkada.Canvas Types,  Up: Package_Gtkada.Canvas

Subprograms
===========

Creating a canvas
-----------------

procedure Gtk_New
       (Canvas             : out    Interactive_Canvas;
        Auto_Layout        :        Boolean := True);

Create a new empty Canvas.
If Auto_Layout is True, then the items are automatically positioned as
they are put in the canvas, if no coordinates are specified.
procedure Configure
       (Canvas             : access Interactive_Canvas_Record;
        Grid_Size          :        Glib.Guint
                            := Default_Grid_Size;
        Annotation_Font    :        Pango.Font.Pango_Font_Description
                            := Pango.Font.From_String (Default_Annotation_Font);

function Get_Vadj
       (Canvas             : access Interactive_Canvas_Record'Class)
        return Gtk.Adjustment.Gtk_Adjustment;

Return the vertical adjustment associated with Canvas
function Get_Hadj
       (Canvas             : access Interactive_Canvas_Record'Class)
        return Gtk.Adjustment.Gtk_Adjustment;

Return the horizontal adjustment associated with Canvas
procedure Draw_Area
       (Canvas             : access Interactive_Canvas_Record'Class;
        Rect               :        Gdk.Rectangle.Gdk_Rectangle);

Draw in Canvas the specified area.
procedure Draw_Background
       (Canvas             : access Interactive_Canvas_Record;
        Screen_Rect        :        Gdk.Rectangle.Gdk_Rectangle);

Draw the background of the canvas. This procedure should be overriden if
you want to draw something else on the background. It must first clear
the area on the screen.

   Screen_Rect is the rectangle on the screen that needs to be
refreshed. These are canvas coordinates, therefore you must take into
account the current zoom level while drawing.

   The default implementation draws a grid.

   An example implementation that draws a background image is shown at
the  end of this file.
procedure Draw_Grid
       (Canvas             : access Interactive_Canvas_Record;
        GC                 :        Gdk.GC.Gdk_GC;
        Screen_Rect        :        Gdk.Rectangle.Gdk_Rectangle);

Helper function that can be called from Draw_Background. It cannot be
used directly as Draw_Background, since it doesn't clear the area first.
procedure Set_Orthogonal_Links
       (Canvas             : access Interactive_Canvas_Record;
        Orthogonal         :        Boolean);

If Orthogonal is True, then all the links will be drawn only with
vertical and horizontal lines. This is not applied for the second or
more link between two items.
function Get_Orthogonal_Links
       (Canvas             : access Interactive_Canvas_Record)
        return Boolean;

Return True if the links are only drawn horizontally and vertically.
procedure Align_On_Grid
       (Canvas             : access Interactive_Canvas_Record;
        Align              :        Boolean := True);

Choose whether the items should be aligned on the grid when moved.
Existing items are not moved even if you set this parameter to True,
this will only take effect the next time the items are moved.
function Get_Align_On_Grid
       (Canvas             : access Interactive_Canvas_Record)
        return Boolean;

Return True if items are currently aligned on grid.
procedure Move_To
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class;
        X, Y               :        Glib.Gint := Glib.Gint'First);

Move the item in the canvas, to world coordinates (X, Y).
Item is assumed to be already in the canvas.   If you leave both
coordinates X and Y to their default value, then the  item's location
will be automatically computed when you layout the  canvas (it is your
responsability to call Layout).
procedure Set_Items
       (Canvas             : access Interactive_Canvas_Record;
        Items              :        Glib.Graphs.Graph);

Set the items and links to display in the canvas from Items.
All items previously in the canvas are removed, and replaced by the
vertices in Items.   Note that the vertices in Items must be in
Canvas_Item_Record'Class, and  the links must be in
Canvas_Link_Record'Class.   If you do not have an automatic layout set
up in Canvas, you need to set  the coordinates of all the vertices by
calling Move_To separately.

   You mustn't destroy items yourself, this is done automatically when
the  canvas is destroyed.
procedure Put
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class;
        X, Y               :        Glib.Gint := Glib.Gint'First);

Add a new item to the canvas, at world coordinates (X, Y).
The item is added at a specific location.   If you leave both X and Y
to their default value, the item's location  will be computed
automatically when you call Layout on the canvas,  unless Auto_Layout
has been set, in which case the position will be  computed immediately.
function Item_At_Coordinates
       (Canvas             : access Interactive_Canvas_Record;
        X, Y               :        Glib.Gint)
        return Canvas_Item;

Return the item at world coordinates (X, Y) which is on top of all
others.   null is returned if there is no such item.
function Item_At_Coordinates
       (Canvas             : access Interactive_Canvas_Record;
        Event              :        Gdk.Event.Gdk_Event)
        return Canvas_Item;

Same as above, but using the canvas coordinates of the event, taking
into account the current zoom level and current scrolling
procedure Remove
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Remove an item and all the links to and from it from the canvas.
The item itself is not freed, but the links are.   Nothing is done if
the item is not part of the canvas.
procedure Item_Updated
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

This should be called when Item has changed the contents of its
pixmap, and thus the Canvas should be updated.
procedure Refresh_Canvas
       (Canvas             : access Interactive_Canvas_Record);

Redraw the whole canvas (both in the double buffer and on the screen).
procedure Raise_Item
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Raise the item so that it is displayed on top of all the others
The canvas is refreshed as needed to reflect the change.   Nothing
happens if Item is not part of the canvas.
procedure Lower_Item
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Lower the item so that it is displayed below all the others.
The canvas is refreshed as needed to reflect the change.   Nothing
happens if Item is not part of the canvas.
function Is_On_Top
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class)
        return Boolean;

Return True if Item is displayed on top of all the others in the canvas.
procedure Show_Item
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Scroll the canvas so that Item is visible.
Iterating over items
--------------------

procedure For_Each_Item
       (Canvas             : access Interactive_Canvas_Record;
        Execute            :        Item_Processor;
        Linked_From_Or_To  :        Canvas_Item := null);

Execute an action on each of the items contained in the canvas.
If Execute returns False, we stop traversing the list of children.   It
is safe to remove the items in Item_Processor.

   If Linked_From_Or_To is not null, then only the items linked to this
one  will be processed. It is possible that a given item will be
returned  twice, if it is both linked to and from the item.
function Start
       (Canvas             : access Interactive_Canvas_Record;
        Linked_From_Or_To  :        Canvas_Item := null)
        return Item_Iterator;

Return the first item in the canvas.
The same restriction as above applies if Linked_From_Or_To is not null.
procedure Next
       (Iter               : in out Item_Iterator);

Move the iterator to the next item.
All items will eventually be returned if you do not add new items during
the iteration and none are removed. However, it is safe to remove items
at any time, except the current item
function Get
       (Iter               :        Item_Iterator)
        return Canvas_Item;

Return the item pointed to by the iterator.
null is returned when there are no more item in the canvas.
function Is_Linked_From
       (Iter               :        Item_Iterator)
        return Boolean;

Return True if there is a link from:
Get (Iter) -> Linked_From_Or_To  Linked_From_Or_To is the item passed
to Start. False is returned if this  item was null.
Zooming
-------

procedure Zoom
       (Canvas             : access Interactive_Canvas_Record;
        Percent            :        Glib.Guint := 100;
        Steps              :        Glib.Guint := 1);

Zoom in or out in the canvas.
Steps is the number of successive zooms that will be done to provide
smooth scrolling.

   Note that one possible use for this function is to refresh the canvas
and emit the "zoomed" signal, which might redraw all the items. This
can  be accomplished by keeping the default 100 value for Percent.
function Get_Zoom
       (Canvas             : access Interactive_Canvas_Record)
        return Glib.Guint;

Return the current zoom level
function To_Canvas_Coordinates
       (Canvas             : access Interactive_Canvas_Record'Class;
        X                  :        Glib.Gint)
        return Glib.Gint;

Scale the scalar X depending by the zoom level (map from world
coordinates to canvas coordinates).   Substract the coordinates of the
top-left corner if you are converting  coordinates instead of lengths.
function Top_World_Coordinates
       (Canvas             : access Interactive_Canvas_Record'Class)
        return Glib.Gint;

Return the world coordinates for the y=0 canvas coordinates (ie for the
upper-left corner).
function Left_World_Coordinates
       (Canvas             : access Interactive_Canvas_Record'Class)
        return Glib.Gint;

Return the world coordinates for the x=0 canvas coordinates (ie for the
upper-left corner).
function To_World_Coordinates
       (Canvas             : access Interactive_Canvas_Record'Class;
        X                  :        Glib.Gint)
        return Glib.Gint;

Scale the scalar X depending by the zoom level (map from canvas
coordinates to world coordinates)
procedure Get_World_Coordinates
       (Canvas             : access Interactive_Canvas_Record'Class;
        X, Y               : out    Glib.Gint;
        Width              : out    Glib.Gint;
        Height             : out    Glib.Gint);

Return the world coordinates of Canvas.
Layout of items
---------------

procedure Set_Layout_Algorithm
       (Canvas             : access Interactive_Canvas_Record;
        Algorithm          :        Layout_Algorithm);

Set the layout algorithm to use to compute the position of the items.
Algorithm mustn't be null.
procedure Default_Layout_Algorithm
       (Canvas             : access Interactive_Canvas_Record'Class;
        Graph              :        Glib.Graphs.Graph;
        Force              :        Boolean;
        Vertical_Layout    :        Boolean);

The default algorithm used in the canvas.
Basically, items are put next to each other, unless there is a link
between two items. In that case, the second item is put below the first,
as space allows.
procedure Set_Auto_Layout
       (Canvas             : access Interactive_Canvas_Record;
        Auto_Layout        :        Boolean);

If Auto_Layout is true, then the items will be automatically layed out
when inserted in the canvas, if no coordinates are specified.
procedure Layout
       (Canvas             : access Interactive_Canvas_Record;
        Force              :        Boolean := False;
        Vertical_Layout    :        Boolean := False);

Recompute the layout of the canvas.
If Force is False, only the items that don't already have a location are
moved.
Links
-----

procedure Configure
       (Link               : access Canvas_Link_Record;
        Arrow              : in     Arrow_Type := End_Arrow;
        Descr              : in     Glib.UTF8_String := "");

Configure a link.
The link is an oriented bound between two items on the canvas.   If
Descr is not the empty string, it will be displayed in the middle  of
the link, and should indicate what the link means.   Arrow indicates
whether some arrows should be printed as well.
function Get_Descr
       (Link               : access Canvas_Link_Record)
        return Glib.UTF8_String;

Return the description for the link, or "" if there is none
function Get_Arrow_Type
       (Link               : access Canvas_Link_Record)
        return Arrow_Type;

Return the location of the arrows on Link
procedure Set_Src_Pos
       (Link               : access Canvas_Link_Record;
        X_Pos, Y_Pos       :        Glib.Gfloat := 0.5);

Set the position of the link's attachment in its source item.
X_Pos and Y_Pos should be given between 0.0 and 1.0 (from left to right
or top to bottom)..   By default, all links are considered to be
attached to the center of  items. However, in some cases it is more
convenient to attach it to a  specific part of the item. For instance,
you can force a link to always  start from the top of the item by
setting Y_Pos to 0.0.
procedure Set_Dest_Pos
       (Link               : access Canvas_Link_Record;
        X_Pos, Y_Pos       :        Glib.Gfloat := 0.5);

Same as Set_Src_Pos for the destination item
procedure Get_Src_Pos
       (Link               : access Canvas_Link_Record;
        X, Y               : out    Glib.Gfloat);

Return the attachment position of the link along its source item
procedure Get_Dest_Pos
       (Link               : access Canvas_Link_Record;
        X, Y               : out    Glib.Gfloat);

Return the attachment position of the link along its destination item
function Has_Link
       (Canvas             : access Interactive_Canvas_Record;
        From, To           : access Canvas_Item_Record'Class;
        Name               :        Glib.UTF8_String := "")
        return Boolean;

Test whether there is a link from From to To, with the same name.
If Name is the empty string "", then no check is done on the name,  and
True if returned if there is any link between the two items.
procedure Add_Link
       (Canvas             : access Interactive_Canvas_Record;
        Link               : access Canvas_Link_Record'Class;
        Src                : access Canvas_Item_Record'Class;
        Dest               : access Canvas_Item_Record'Class;
        Arrow              : in     Arrow_Type := End_Arrow;
        Descr              : in     Glib.UTF8_String := "");

Add Link in the canvas. This connects the two items Src and Dest.
Simpler procedure to add a standard link.   This takes care of memory
allocation, as well as adding the link to  the canvas.
procedure Remove_Link
       (Canvas             : access Interactive_Canvas_Record;
        Link               : access Canvas_Link_Record'Class);

Remove a link from the canvas.
It also destroys the link itself, and free the memory allocated to it.
Nothing is done if Link does not belong to canvas.
procedure For_Each_Link
       (Canvas             : access Interactive_Canvas_Record;
        Execute            :        Link_Processor;
        From, To           :        Canvas_Item := null);

Execute an action on each of the links contained in the canvas.
If Execute returns False, we stop traversing the list of links.   It is
safe to remove the link from the list in Link_Processor.

   (From, To) can be used to limit what links are looked for.

   ??? Would be nicer to give direct access to the Graph iterators
procedure Destroy
       (Link               : in out Canvas_Link_Record);

Method called every time a link is destroyed. You should override this
if you define your own link types.   Note that the link might already
have been removed from the canvas  when this subprogram is called.
This shouldn't free the link itself, only its fields.
Drawing links
-------------

Drawing of links can be controlled at several levels:
   * Redefining Update_Links gives control at the canvas level. This can
         be used to implement routing algorithms for the links where
     the      routes must be computed before any link is actually drawn
     (otherwise      it is better to redefine Draw_Link). It can also
     be used to control      in what order the links should be drawn.

   * Redefining Draw_Link gives the opportunity to draw links any way
     you      need (several bends, ...). It can be used to control the
     routing of      this specific link, for routing algorithms that
     only rely on the      items layout and not on other links.
     Otherwise see Update_Links.

   * Redefining Draw_Straight_Line if slightly lower-level. This is
     called by the default Draw_Link procedure, once the ends of the
       links have been computed.

procedure Update_Links
       (Canvas             : access Interactive_Canvas_Record;
        GC                 :        Gdk.GC.Gdk_GC;
        Invert_Mode        :        Boolean;
        From_Selection     :        Boolean);

Redraw all the links in the canvas, after the items have been laid out.
GC is a default graphic context that can be used for drawing. However,
any other graphic context will do. If Invert_Mode is true, this graphic
context must draw in xor mode.   If From_Selection is true, then only
the links to or from one of the  selected items need to be drawn.
procedure Draw_Link
       (Canvas             : access Interactive_Canvas_Record'Class;
        Link               : access Canvas_Link_Record;
        Invert_Mode        :        Boolean;
        GC                 :        Gdk.GC.Gdk_GC;
        Edge_Number        :        Glib.Gint);

Redraw the link on the canvas.
Note that this is a primitive procedure of Link, not of Canvas, and thus
can easily be overrided for specific links. The default version draws
either straight or arc links (the latter when there are multiple links
between two given items).   This function shouldn't be called if one of
the two ends of the link is  invisible.

   The link should be drawn directly in Get_Window (Canvas).

   GC is a possible graphic context that could be used to draw the
link. You shouldn't destroy it or modify its attributes. However, you
can use any other graphic context specific to your application, for
instance if you want to draw the link in various colors or shapes. The
graphic context you use must be in Invert mode (see Gdk.GC.Set_Function)
if and only if Invert_Mode is true, so that when items are moved on the
canvas, the links properly follow the items they are attached to.
This graphic context is only used to draw links, so you don't need to
restore it on exit if your Draw_Link function always sets it at the
beginning.

   Edge_Number indicates the index of link in the list of links that
join  the same source to the same destination. It should be used so
that two  links do not overlap (for instance, the default is to draw
the first  link straight, and the others as arcs).
procedure Clip_Line
       (Src                : access Canvas_Item_Record;
        To_X               :        Glib.Gint;
        To_Y               :        Glib.Gint;
        X_Pos              :        Glib.Gfloat;
        Y_Pos              :        Glib.Gfloat;
        Side               : out    Item_Side;
        X_Out              : out    Glib.Gint;
        Y_Out              : out    Glib.Gint);

Clip the line that goes from Src at pos (X_Pos, Y_Pos) to (To_X, To_Y)
in world coordinates.   The intersection between that line and the
border of Rect is returned  in (X_Out, Y_Out). The result should be in
world coordinates.   X_Pos and Y_Pos have the same meaning as Src_X_Pos
and Src_Y_Pos in the  link record.   This procedure is called when
computing the position for the links  within the default Draw_Link
procedure. The default implementation only  works with rectangular
items. The computed coordinates are then passed  on directly to
Draw_Straight_Line.
procedure Draw_Straight_Line
       (Link               : access Canvas_Link_Record;
        Window             :        Gdk.Window.Gdk_Window;
        GC                 :        Gdk.GC.Gdk_GC;
        Src_Side           :        Item_Side;
        X1, Y1             :        Glib.Gint;
        Dest_Side          :        Item_Side;
        X2, Y2             :        Glib.Gint);

Draw a straight link between two points. This could be overriden if you
need to draw an something along the link.   The links goes from (Src,
X1, Y1) to (Dest, X2, Y2), in canvas  coordinates. The coordinates have
already been clipped so that they do  not override the item.
Selection
---------

procedure Clear_Selection
       (Canvas             : access Interactive_Canvas_Record);

Clear the list of currently selected items.
procedure Add_To_Selection
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Add Item to the selection.  This is only meaningful during a drag
operation (ie during a button press and the matching button  release).
Item will be moved at the same time that the selection is  moved.
Item is not added again if it is already in the selection.   This
function can be called from the Button_Click subprogram to force
moving items.   This emits the "item_selected" signal.
procedure Remove_From_Selection
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class);

Remove Item from the selection.
This emits the "item_unselected" signal.
function Is_Selected
       (Canvas             : access Interactive_Canvas_Record;
        Item               : access Canvas_Item_Record'Class)
        return Boolean;

Return True if the item is currently selected
function Start
       (Canvas             : access Interactive_Canvas_Record)
        return Selection_Iterator;

Return the first selected item
function Next
       (Iterator           :        Selection_Iterator)
        return Selection_Iterator;

Move to the next selected item
function Get
       (Iterator           :        Selection_Iterator)
        return Canvas_Item;

Return the current item, or null if there is no more selected item.
Items manipulation
------------------

procedure Selected
       (Item               : access Canvas_Item_Record;
        Canvas             : access Interactive_Canvas_Record'Class;
        Is_Selected        :        Boolean);

Called when the item is selected or unselected.
The default is to do nothing
function Point_In_Item
       (Item               : access Canvas_Item_Record;
        X, Y               :        Glib.Gint)
        return Boolean;

This function should return True if (X, Y) is inside the item. X and Y
are in world coordinates.   This function is meant to be overriden for
non-rectangular items, since  the default behavior works for
rectangular items.   This function is never called for invisible items
procedure Set_Screen_Size
       (Item               : access Canvas_Item_Record;
        Width              :        Glib.Gint;
        Height             :        Glib.Gint);

Set the size of bounding box for the item in world coordinates.
The item itself needn't occupy the whole area of this bounding box,
see Point_In_Item.   You need to redraw the item, and call Item_Updated
to force the canvas  to refresh the screen.
procedure Draw
       (Item               : access Canvas_Item_Record;
        Canvas             : access Interactive_Canvas_Record'Class;
        GC                 :        Gdk.GC.Gdk_GC;
        Xdest, Ydest       :        Glib.Gint);

This subprogram, that must be overridden, should draw the item on
Get_Pixmap (Canvas), at the specific location (Xdest, Ydest). The item
must also be drawn at the appropriate zoom level.   If you need to
change the contents of the item, you should call  Item_Updated after
having done the drawing.
procedure Destroy
       (Item               : in out Canvas_Item_Record);

Free the memory occupied by the item (not the item itself). You should
override this function if you define your own widget type, but always
call the parent's Destroy subprogram.
procedure On_Button_Click
       (Item               : access Canvas_Item_Record;
        Event              :        Gdk.Event.Gdk_Event_Button);

Function called whenever the item was clicked on.
Note that this function is not called when the item is moved, and thus
is only called when the click was short.   The coordinates (X, Y) in
the Event are relative to the top-left corner  of Item.
function Get_Coord
       (Item               : access Canvas_Item_Record)
        return Gdk.Rectangle.Gdk_Rectangle;

Return the coordinates and size of the bounding box for item, in world
coordinates.   If the item has never been resized, it initially has a
width and height  of 1.
procedure Set_Visibility
       (Item               : access Canvas_Item_Record;
        Visible            :        Boolean);

Set the visibility status of the item. An invisible item will not be
visible on the screen, and will not take part in the computation of the
the scrollbars for the canvas.   The canvas is not refreshed (this is
your responsibility to do it after  you have finished doing all the
modifications).
function Is_Visible
       (Item               : access Canvas_Item_Record)
        return Boolean;

Return True if the item is currently visible.
function Is_From_Auto_Layout
       (Item               : access Canvas_Item_Record)
        return Boolean;

Return True if the current location of the item is the result from the
auto layout algorithm.   False is returned if the item was moved
manually by the user.
Buffered items
--------------

function Pixmap
       (Item               : access Buffered_Item_Record)
        return Gdk.Pixmap.Gdk_Pixmap;

Return the double-buffer.
All the drawing on this pixmap must be done at zoom level 100%
Signals
-------

procedure Set_Screen_Size
       (Item               : access Buffered_Item_Record;
        Width, Height      :        Glib.Gint);

See documentation from inherited subprogram
procedure Draw
       (Item               : access Buffered_Item_Record;
        Canvas             : access Interactive_Canvas_Record'Class;
        GC                 :        Gdk.GC.Gdk_GC;
        Xdest, Ydest       :        Glib.Gint);

Draw the item's double-buffer onto Dest.
procedure Destroy
       (Item               : in out Buffered_Item_Record);

Free the double-buffer allocated for the item

File: gtkada_rm.info,  Node: Gtkada.Canvas Example,  Prev: Gtkada.Canvas Subprograms,  Up: Package_Gtkada.Canvas

Example
=======

      --  The following example shows a possible Draw_Background procedure,
      --  that draws a background image on the canvas's background. It fully
      --  handles zooming and tiling of the image. Note that drawing a large
      --  image will dramatically slow down the performances.
     
      Background : Gdk.Pixbuf.Gdk_Pixbuf := ...;
     
      procedure Draw_Background
        (Canvas        : access Image_Canvas_Record;
         Screen_Rect   : Gdk.Rectangle.Gdk_Rectangle)
      is
         X_Left : constant Glib.Gint := Left_World_Coordinates (Canvas);
         Y_Top  : constant Glib.Gint := Top_World_Coordinates (Canvas);
         X, Y, W, H, Ys : Gint;
         Xs : Gint := Screen_Rect.X;
         Bw : constant Gint := Get_Width (Background)
           * Gint (Get_Zoom (Canvas)) / 100;
         Bh : constant Gint := Get_Height (Background)
           * Gint (Get_Zoom (Canvas)) / 100;
         Scaled : Gdk_Pixbuf := Background;
      begin
         if Get_Zoom (Canvas) /= 100 then
            Scaled := Scale_Simple (Background, Bw, Bh);
         end if;
     
         while Xs < Screen_Rect.X + Screen_Rect.Width loop
            Ys := Screen_Rect.Y;
            X := (X_Left + Xs) mod Bw;
            W := Gint'Min (Screen_Rect.Width + Screen_Rect.X- Xs, Bw - X);
     
            while Ys < Screen_Rect.Y + Screen_Rect.Height loop
               Y := (Y_Top  + Ys) mod Bh;
               H := Gint'Min
                 (Screen_Rect.Height + Screen_Rect.Y - Ys, Bh - Y);
               Render_To_Drawable
                 (Pixbuf       => Scaled,
                  Drawable     => Get_Window (Canvas),
                  Gc           => Get_Black_GC (Get_Style (Canvas)),
                  Src_X        => X,
                  Src_Y        => Y,
                  Dest_X       => Xs,
                  Dest_Y       => Ys,
                  Width        => W,
                  Height       => H);
               Ys := Ys + H;
            end loop;
            Xs := Xs + W;
         end loop;
     
         if Get_Zoom (Canvas) /= 100 then
            Unref (Scaled);
         end if;
      end Draw_Background;


File: gtkada_rm.info,  Node: Package_Gtkada.Dialogs,  Next: Package_Gtkada.File_Selection,  Prev: Package_Gtkada.Canvas,  Up: Top

Package Gtkada.Dialogs
**********************

This package provides a ready to use high level dialog capability.

* Menu:

* Gtkada.Dialogs Types::
* Gtkada.Dialogs Subprograms::


File: gtkada_rm.info,  Node: Gtkada.Dialogs Types,  Next: Gtkada.Dialogs Subprograms,  Up: Package_Gtkada.Dialogs

Types
=====

type Button_Range is range 0 .. 8;


The range of valid buttons.
type Message_Dialog_Buttons is mod 2 ** 32;


Define the set of values a button in a message dialog box can have.
type Message_Dialog_Type is
         (Warning,
             -- Message box with a yellow exclamation point.
     
          Error,
             -- Message box with a red stop sign.
     
          Information,
             -- Message box with a blue "i".
     
          Confirmation,
             -- Message box with a blue question mark.
     
          Custom
             -- Message box with no pixmap. The caption of the box should be set by
             -- the user.
          );

Define the values describing the type of message box.   Used by the
Message_Dialog function.

File: gtkada_rm.info,  Node: Gtkada.Dialogs Subprograms,  Prev: Gtkada.Dialogs Types,  Up: Package_Gtkada.Dialogs

Subprograms
===========

function Message_Dialog
       (Msg                :        Glib.UTF8_String;
        Dialog_Type        :        Message_Dialog_Type
                            := Information;
        Buttons            :        Message_Dialog_Buttons
                            := Button_OK or Button_Help;
        Default_Button     :        Message_Dialog_Buttons
                            := Button_OK;
        Help_Msg           :        Glib.UTF8_String := "";
        Title              :        Glib.UTF8_String := "";
        Justification      :        Gtk_Justification
                            := Justify_Center;
        Parent             :        Gtk.Window.Gtk_Window := null)
        return Message_Dialog_Buttons;

Display a message dialog box centered on the mouse.
This will create a dialog box containing the specified message.
Dialog_Type indicates the purpose of the dialog.   Buttons indicates
which buttons should appear in the dialog.   Help_Msg is the message
displayed in a separate dialog box when the help  button is pressed
while the dialog is displayed.   If Help_Msg is null, a dialog
containing the message  "No help available" will be displayed. In both
cases, the dialog  displayed will only have a OK button.   If Title is
null, a default title will be chosen depending on the value  of
Dialog_Type.   The dialog will be centered with regards to Parent

   This function will return only after the user pressed one of the
buttons  or deleted the dialog, by running an additional level of main
loop.   One of the following values will be returned:
   * Button_None

   * Button_Abort

   * Button_Yes

   * Button_Ok

   * Button_Retry

   * Button_No

   * Button_Cancel

   * Button_Ignore

   * Button_All

function Create_Gtk_Dialog
       (Msg                :        Glib.UTF8_String;
        Dialog_Type        :        Message_Dialog_Type
                            := Information;
        Title              :        Glib.UTF8_String := "";
        Justification      :        Gtk_Justification
                            := Justify_Center;
        Parent             :        Gtk.Window.Gtk_Window := null)
        return Gtk.Dialog.Gtk_Dialog;

Convenience function to create a new dialog.
This function was introduced in GtkAda 2.0 to provide a compatibility
with Message_Dialog, while using the standard Gtk.Dialog. You should add
the buttons yourself, through Gtk.Dialog.Gtk_Dialog, and then display
the dialog on the screen through Gtk.Dialog.Run.   As opposed to
Message_Dialog, you can provide your own custom buttons if  needed.

File: gtkada_rm.info,  Node: Package_Gtkada.File_Selection,  Next: Package_Gtkada.Handlers,  Prev: Package_Gtkada.Dialogs,  Up: Top

Package Gtkada.File`_'Selection
*******************************

This package provides a high level support for creating file selection
dialogs by handling the signals internally.

* Menu:

* Gtkada.File_Selection Subprograms::


File: gtkada_rm.info,  Node: Gtkada.File_Selection Subprograms,  Up: Package_Gtkada.File_Selection

Subprograms
===========

function File_Selection_Dialog
       (Title              :        Glib.UTF8_String
                            := "Select File";
        Default_Dir        :        String := "";
        Dir_Only           :        Boolean := False;
        Must_Exist         :        Boolean := False)
        return String;

Open a file selection dialog and make it modal.
Return when either the Cancel button is clicked or when a file is
selected.   Default_Dir is the directory to display in dialog
initially. Note that  it must end with a directory separator ('/' or
'\', depending on your  system). You can use
GNAT.Os_Lib.Directory_Separator to get the correct  value for your
system.   If Must_Exist is True, then the file (or directory if
Dir_Only is True)  must exist.   If Dir_Only is True, then the dialog
is modified so that the user can  only choose a directory name, but not
a file name.   The value returned is the name of the file selected, or
"" if none.

File: gtkada_rm.info,  Node: Package_Gtkada.Handlers,  Next: Package_Gtkada.Intl,  Prev: Package_Gtkada.File_Selection,  Up: Top

Package Gtkada.Handlers
***********************

This package provides the most commonly used instantiations of
Gtk.Handlers

   Gate takes advantage of these pre-instantiated packages.

* Menu:


File: gtkada_rm.info,  Node: Package_Gtkada.Intl,  Next: Package_Gtkada.Pixmaps,  Prev: Package_Gtkada.Handlers,  Up: Top

Package Gtkada.Intl
*******************

This package provides support for string internationalization using the
libintl library.

   To change the current locale setting, use on the environment
variables  "LANG" or "LC_MESSAGES". For example, to switch to the
french locale using  bash:

   $ export LANG=fr

   Depending on the specific implementation of gettext, the following
environment variables may be set to change the default settings of
locale  parameters:

   * LANG Specifies locale name.

   * LC_MESSAGES          Specifies messaging locale, and if present
     overrides          LANG for messages.

   * TEXTDOMAIN          Specifies the text domain name, which is
     identical to          the message object filename without .mo
     suffix.

   * TEXTDOMAINDIR          Specifies the pathname to the message
     database, and if          present replaces the default (e.g
     /usr/lib/locale on Solaris,          /usr/share/locale on Linux).

    See the gettext documentation of your specific OS for more details.

   The recommended way to use the gettext capability in your
application is  to use Dgettext with your own domain, and define the
following shortcut:

   function "-" (Msg : UTF8_String) return UTF8_String;  -  Convenient
shortcut to the Gettext function.

   function "-" (Msg : UTF8_String) return UTF8_String is  begin
return Dgettext ("my_domain", Msg);  end "-";

   Do not forget to call Bind_Text_Domain ("my_domain", "my locale
prefix")  at the beginning of your program. For example, if the prefix
of your  application is /usr, the standard location of the locale would
be /usr/share/locale, e.g:    Bind_Text_Domain ("GtkAda",
"/usr/share/locale");

   Under this locale directory, the functions provided by this package
will look for the directory $LANG/LC_MESSAGES,
/usr/share/locale/fr/LC_MESSAGES in our example; and in this directory,
the file <domain>.mo will be used, e.g
/usr/share/locale/fr/LC_MESSAGES/GtkAda.mo

   The .mo files can be generated using the GNU tool msgfmt that takes a
text file containing for each string the original and the translation.
See msgfmt documentation for more details.   Here is a sample
translation file that can be used as an input for msgfmt:

   # gtkada-fr.po  msgid  "Help"  msgstr "Aide"

   msgid  "Yes"  msgstr "Oui"

   $ msgfmt gtkada-fr.po -o gtkada-fr.gmo  $ cp gtkada-fr.gmo
/usr/share/locale/fr/LC_MESSAGES/GtkAda.mo

   Then, to enable the string translation in your application, use the
"-"  function defined above, e.g:

   Gtk_New (Label, -"Help");  Gtk_New (Label, -("Help ?") & ASCII.LF &
-("Yes"));

* Menu:

* Gtkada.Intl Subprograms::


File: gtkada_rm.info,  Node: Gtkada.Intl Subprograms,  Up: Package_Gtkada.Intl

Subprograms
===========

function Gettext
       (Msg                :        Glib.UTF8_String)
        return Glib.UTF8_String;

Look up Msg in the current default message catalog.
Use the current locale as specified by LC_MESSAGES. If not found, return
Msg itself (the default text).
function Dgettext
       (Domain             :        String;
        Msg                :        Glib.UTF8_String)
        return Glib.UTF8_String;

Look up Msg in the Domain message catalog for the current locale.
function "-"
       (Msg                :        Glib.UTF8_String)
        return Glib.UTF8_String;

Shortcut for Dgettext ("GtkAda", Msg)
function Dcgettext
       (Domain             :        String;
        Msg                :        Glib.UTF8_String;
        Category           :        Integer)
        return Glib.UTF8_String;

Look up Msg in the Domain message catalog for the Category locale.
function Default_Text_Domain   return String;


Return the current default message catalog.
procedure Text_Domain
       (Domain             :        String := "");

Set the current default message catalog to Domain.
If Domain is "", reset to the default of "messages".
procedure Bind_Text_Domain
       (Domain             :        String;
        Dirname            :        String);

Specify that the Domain message catalog will be found in Dirname.
This overrides the default system locale data base.

File: gtkada_rm.info,  Node: Package_Gtkada.Pixmaps,  Next: Package_Gtkada.Types,  Prev: Package_Gtkada.Intl,  Up: Top

Package Gtkada.Pixmaps
**********************

This package provides a collection of "standard" pixmaps

* Menu:

* Gtkada.Pixmaps Subprograms::


File: gtkada_rm.info,  Node: Gtkada.Pixmaps Subprograms,  Up: Package_Gtkada.Pixmaps

Subprograms
===========

function "+"
       (Str                : in     String)
        return Gtkada.Types.Chars_Ptr;


File: gtkada_rm.info,  Node: Package_Gtkada.Types,  Next: Package_Pango,  Prev: Package_Gtkada.Pixmaps,  Up: Top

Package Gtkada.Types
********************

This package provides GtkAda specific types and their associated
functions.

* Menu:

* Gtkada.Types Types::
* Gtkada.Types Subprograms::


File: gtkada_rm.info,  Node: Gtkada.Types Types,  Next: Gtkada.Types Subprograms,  Up: Package_Gtkada.Types

Types
=====

subtype Chars_Ptr is Interfaces.C.Strings.chars_ptr;


subtype Chars_Ptr_Array is Interfaces.C.Strings.chars_ptr_array;



File: gtkada_rm.info,  Node: Gtkada.Types Subprograms,  Prev: Gtkada.Types Types,  Up: Package_Gtkada.Types

Subprograms
===========

procedure g_free
       (Mem                :        Chars_Ptr);

Free a C string returned from Gtk.
function Null_Array            return Chars_Ptr_Array;


Return a null array.
Handling of arrays of Strings
-----------------------------

The following functions provide a very convenient way to create
C arrays of null terminated strings in Ada.

   You can either create such a String on the fly, or declare a
variable:

   Signals : Chars_Ptr_Array := "clicked" + "missed" + "new signal";

   which corresponds to the C declaration:

   char *signals[] = {"clicked", "missed", "new signal"};

   Note that you still need to manually call Free (Signals) if you want
to  release the memory dynamically allocated by the "+" functions.

function "+"
       (S1, S2             :        String)
        return Chars_Ptr_Array;

Create an array containing S1 and S2.
Note that this function allocates memory to store S1 and S2 as null
terminated Strings. The user is responsible for calling Free on the
resulting array.
function "+"
       (S1                 :        Chars_Ptr_Array;
        S2                 :        String)
        return Chars_Ptr_Array;

Append S2 to S1.
Note that this function allocates memory to store S2 as a null
terminated Strings. The user is responsible for calling Free on the
resulting array.
function "+"
       (S1                 :        Chars_Ptr_Array;
        S2                 :        Chars_Ptr)
        return Chars_Ptr_Array;

Append S2 to S1.
Note that this function allocates memory to store S2 as a null
terminated Strings. The user is responsible for calling Free on the
resulting array.
function "+"
       (S1                 :        Chars_Ptr;
        S2                 :        String)
        return Chars_Ptr_Array;

Create an array containing S1 and S2.
Note that this function allocates memory to store S2 as a null
terminated string. The user is responsible for calling Free on the
resulting array.
procedure Free
       (A                  : in out Chars_Ptr_Array);

Free all the strings in A.

File: gtkada_rm.info,  Node: Package_Canvas_Link,  Next: Package_GObject,  Prev: Top,  Up: Top

Package Canvas_Link
*******************


File: gtkada_rm.info,  Node: Package_GObject,  Next: Package_Gdk,  Prev: Package_Canvas_Link,  Up: Top

Package GObject
***************


File: gtkada_rm.info,  Node: Package_Gdk,  Next: Package_Gdk.Bitmap,  Prev: Package_GObject,  Up: Top

Package Gdk
***********

This is the top level package of the Gdk hierarchy.   It provides the
type definitions used to access underlying C structures.

* Menu:

* Gdk Types::


File: gtkada_rm.info,  Node: Gdk Types,  Up: Package_Gdk

Types
=====

subtype C_Proxy is Glib.C_Proxy;


subtype Gdk_Bitmap is Gdk_Drawable;


type Gdk_Colormap is new C_Proxy;


type Gdk_Drawable is new C_Proxy;


type Gdk_Font is new C_Proxy;


type Gdk_GC is new C_Proxy;


type Gdk_Image is new C_Proxy;


subtype Gdk_Pixmap is Gdk_Drawable;


type Gdk_Region is new C_Proxy;


type Gdk_Visual is new C_Proxy;


subtype Gdk_Window is Gdk_Drawable;


type Gdk_Window_Attr is new C_Proxy;



File: gtkada_rm.info,  Node: Package_Gdk.Bitmap,  Next: Package_Gdk.Color,  Prev: Package_Gdk,  Up: Top

Package Gdk.Bitmap
******************

Pixmaps are off-screen drawables. They can be drawn upon with the
standard  drawing primitives, then copied to another drawable (such as
a Gdk_Window)  with Gdk.Drawable.Draw_Drawable. The depth of a pixmap
is the number of  bits per pixels. Bitmaps are simply pixmaps with a
depth of 1. (That is,  they are monochrome bitmaps - each pixel can be
either on or off).   *note Package_Gdk.Pixmap:: for more details on
pixmap handling.

* Menu:

* Gdk.Bitmap Types::
* Gdk.Bitmap Subprograms::


File: gtkada_rm.info,  Node: Gdk.Bitmap Types,  Next: Gdk.Bitmap Subprograms,  Up: Package_Gdk.Bitmap

Types
=====

subtype Gdk_Bitmap is Gdk.Gdk_Bitmap;


A black and white image.   This type is mainly used as a mask when
drawing other colored images.   Each pixel can have two values, 0 or 1.

File: gtkada_rm.info,  Node: Gdk.Bitmap Subprograms,  Prev: Gdk.Bitmap Types,  Up: Package_Gdk.Bitmap

Subprograms
===========

procedure Gdk_New
       (Bitmap             : out    Gdk_Bitmap;
        Window             :        Gdk.Window.Gdk_Window;
        Width              :        Gint;
        Height             :        Gint);

Create a new bitmap with a given size.
Window is used to determine default values for the new bitmap.   Can be
eventually null in which case the root window is used.   Width is the
width of the new bitmap in pixels.   Height is the height of the new
bitmap in pixels.
procedure Ref
       (Bitmap             :        Gdk_Bitmap);

Add a reference to a bitmap.
procedure Unref
       (Bitmap             :        Gdk_Bitmap);

This is the usual way to destroy a bitmap. The memory is freed when
there is no more reference
procedure Create_From_Data
       (Bitmap             : out    Gdk_Bitmap;
        Window             :        Gdk.Window.Gdk_Window;
        Data               :        String;
        Width              :        Gint;
        Height             :        Gint);

Create a bitmap from data in XBM format.
Window is used to determine default values for the new bitmap, can be
null in which case the root window is used.   Data is the XBM data.
Width is the width of the new bitmap in pixels.   Height is the height
of the new bitmap in pixels.

File: gtkada_rm.info,  Node: Package_Gdk.Color,  Next: Package_Gdk.Cursor,  Prev: Package_Gdk.Bitmap,  Up: Top

Package Gdk.Color
*****************

This package provides an interface to the color handling facilities in
gtk+. It is able to handle any kind of visual (monochrome, greyscale,
color with different depths, ...), but provides a common and easy
interface for all of them.   Some of these functions expect a Colormap.
There are two ways you can  get such a colormap, either a system
default colormap or a per-widget  colormap. It is recommended, unless
you are writing your own new widget,  to always use the system default
Colormap. All the functions to get  these colormaps are found in
Gtk.Widget.

   Getting the Red/Green/Blue components can be done through Parse, and
is  actually recommended, since the exact color generally depends on the
visual your application is running on.

   Note for users transitioning from gtk+ 1.2: the Get_System call is
now  obsolete, and you should use Gtk.Widget.Get_Default_Colormap
instead.

* Menu:

* Gdk.Color Types::
* Gdk.Color Subprograms::
* Gdk.Color Example::


File: gtkada_rm.info,  Node: Gdk.Color Types,  Next: Gdk.Color Subprograms,  Up: Package_Gdk.Color

Types
=====

type Gdk_Color is private;


A color to be displayed on the screen.   Currently, GtkAda only
supports the RGB standard, ie each color is  set by its red, green and
blue components.   An extra field (Pixel) is the internal
representation of the color,  which is set once the color has been
allocated.
type Gdk_Color_Array is array (Natural range <>) of Gdk_Color;


An array of colors.
subtype Gdk_Colormap is Gdk.Gdk_Colormap;


The set of colors the can be displayed on the screen.   When the screen
is not a true-color screen (ie there is only a limited  number of
possible colors, like 256), the colors are in fact indexes  into a
colormap, which gives the components of the color.   This is the same
concept as a palette.
