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


File: gtkada_rm.info,  Node: Package_Gdk.Font,  Next: Package_Gdk.GC,  Prev: Package_Gdk.Event,  Up: Top

Package Gdk.Font
****************

This is the base package for handling fonts.   GtkAda knows about
bitmap and vectorial fonts, and can draw both.   The list of fonts
available to you depends on what is installed on  your system.

   The name of the font is indicated in the standard X11 fashion,
namely:  (example extracted from the Xlib manual):

   -adobe-courier-bold-o-normal-10-100-75-75-m-60-iso8859-1  where:
   * adobe     : foundry

   * courier   : font family

   * bold      : weight (e.g. bold, medium)

   * o         : slant (e.g. roman, italic, oblique)

   * normal    : set width (e.g. normal, condensed, narrow, double)

   * 10        : pixels

   * 100       : points (in tenths of a point)

   * 75        : horizontal resolution in dpi

   * 75        : vertical resolution in dpi

   * m         : spacing (e.g. monospace or proportional)

   * 60        : average width (in tenths of a pixel)

   * iso8859-1 : character set

    Any of the fields can have a '*' instead, so that the system will
automatically find a font that matches the rest of the string, and won't
care about that specific field.

   But the easiest way to select a font is by using some external
programs,  for instance xfontsel, xlsfont, gfontsel, or even the font
selection  dialog example in the testgtk/ directory of the GtkAda
distribution.

   *note Package_Gtk.Extra.PsFont:: for a package that processes
postscript  fonts, with their more usual names, and can easily convert
them to standard  Gdk_Font structures.

   Some of the functions below should be used only for wide-character
strings.   This is needed for languages with more than 256 characters.

   Wide character values between 0 and 127 are always identical in
meaning to  the ASCII character codes.   An alternative to wide
characters is multi-byte characters, which extend  normal char strings
to cope with larger character sets. As the name  suggests, multi-byte
characters use a different number of bytes to store  different
character codes. For example codes 0-127 (i.e. the ASCII codes)  often
use just one byte of memory, while other codes may use 2, 3 or even  4
bytes. Multi-byte characters have the advantage that they can often be
used in an application with little change, since strings are still
represented as arrays of char values. However multi-byte strings are
much  easier to manipulate since the character are all of the same size.

   On Unix systems, the external utility 'xfd' can be used to display
all  the characters in a font.

* Menu:

* Gdk.Font Types::
* Gdk.Font Subprograms::


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

Types
=====

type Gdk_Font is new Gdk.C_Proxy;

A font used to draw text.   This can represent a bitmap font, a
scalable (vectorial) font, or  a fontset. A fontset is a list of
comma-separated fonts, that permits  GtkAda to obtain the fonts needed
for a variety of locales from a  single locale-independent base font
name. The single base font name  should name a family of fonts whose
members are encoded in the various  charsets needed by the locales of
interest.   The algorithm used to select the font is described in the
manual page  for XCreateFontSet(3X).

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

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

procedure Load
     (Font               : out    Gdk_Font;
        Font_Name          : in     String);

Load a new font, given its name.
This is the first step before using a font.   The font is first looked
up in the cache, and if it was already  loaded, it is not reloaded
again. Thus, it does not harm to call  this function multiple times
with the same Font_Name.   Null_Font is returned if the font could not
be loaded.
procedure Fontset_Load
     (Font               : out    Gdk_Font;
        Fontset_Name       : in     String);

Load a new font set.
Fontset_Name is a comma-separated list of fonts that will be loaded  as
part of the fontset.
procedure Ref
     (Font               : in     Gdk_Font);

Increment the reference counter for the font.
You should not make any assumption of the initial value of the fonts
returned by Load or Fontset_Load, since these can be extracted from a
cache.
procedure Unref
     (Font               : in     Gdk_Font);

Decrement the reference counter for the font.
When this counter reaches 0, the font is deleted from memory.
function Id
     (Font               : in     Gdk_Font)
        return Gint;

Return the X font id for the font.
This Id will only be needed if you want to call directly X11 functions,
you won't need it with GtkAda.
function Equal
     (Fonta, Fontb       : in     Gdk_Font)
        return Boolean;

Compare two fonts or two fontsets for equality.
Two fonts are equal if they have the same font Id.   Two fontsets are
equal if the name given to Fontset_Load was the same.
function Get_Ascent
     (Font               : in     Gdk_Font)
        return Gint;

Return the maximal ascent for the font.
This is the logical extent above the baseline for spacing between two
lines.
function Get_Descent
     (Font               : in     Gdk_Font)
        return Gint;

Return the maximal descent for the font.
This is the logical extent below the baseline for spacing between two
lines.
function String_Width
     (Font               : in     Gdk_Font;
        Str                : in     String)
        return Gint;

Return the width in pixels that Str will occupy if drawn with Font.
The value returned is the distance between the origin of the text and
the position at which the next string should be drawn.
function Text_Width
     (Font               : in     Gdk_Font;
        Text               : in     String)
        return Gint;

This is the same function as String_Width.
In C, this function is intended to measure only the width of a part  of
the string, but you can simply pass it a substring in Ada.
function Text_Width
     (Font               : in     Gdk_Font;
        Text               : in     Gdk.Types.Gdk_WString)
        return Gint;

Return the width in pixels that Text will occupy on the screen.
This function should be used with strings that contain Unicode
characters
function Char_Width
     (Font               : in     Gdk_Font;
        Char               : in     Character)
        return Gint;

Return the width in pixels occupied by a single character on the screen.
The value returned is the distance between Char's origin on the screen
and the origin of the next character in the string.
function Char_Width
     (Font               : in     Gdk_Font;
        Char               : in     Gdk.Types.Gdk_WChar)
        return Gint;

Return the width in pixels occupied by a single wide-character.
function String_Measure
     (Font               : in     Gdk_Font;
        Str                : in     String)
        return Gint;

Determine the distance from the origin to the rightmost portion of Str.
This is not the correct value for determining the origin of the next
portion when drawing text in multiple pieces.   See String_Width
instead.
function Text_Measure
     (Font               : in     Gdk_Font;
        Text               : in     String)
        return Gint;

Same function a String_Measure.
In C, this function is intended to measure only the width of a part of
the string, but you can simply pass it a substring in Ada.   This is
also called the right bearing of the string.
function Char_Measure
     (Font               : in     Gdk_Font;
        Char               : in     Character)
        return Gint;

Return the width in pixels of Char.
As opposed to Char_Width, the value returned is not the distance at
which the next character should be drawn.   This is also called the
right bearing of the character.
procedure String_Extents
     (Font               : in     Gdk.Font.Gdk_Font;
        Str                : in     String;
        Lbearing           : out    Gint;
        Rbearing           : out    Gint;
        Width              : out    Gint;
        Ascent             : out    Gint;
        Descent            : out    Gint);

Return the metrics for a given text.
See the picture for more explanations on all the fields.   Lbearing :
Origin to left edge of character.   Rbearing : Origin to right edge of
character.   Width    : Advance to next character's origin.   Ascent
: Baseline to top edge of character.   Descent  : Baseline to bottom
edge of character.
procedure Text_Extents
     (Font               : in     Gdk_Font;
        Text               : in     String;
        Lbearing           : out    Gint;
        Rbearing           : out    Gint;
        Width              : out    Gint;
        Ascent             : out    Gint;
        Descent            : out    Gint);

Return all the metrics for a given text.
See the picture for more explanations on all the fields.   in C, this
function would be used for part of a string, which you can  simulate in
Ada with a substring.
procedure Text_Extents
     (Font               : in     Gdk_Font;
        Text               : in     Gdk.Types.Gdk_WString;
        Lbearing           : out    Gint;
        Rbearing           : out    Gint;
        Width              : out    Gint;
        Ascent             : out    Gint;
        Descent            : out    Gint);

Return all the metrics for a given wide-character string.
See the picture for more explanations on the returned values.
function String_Height
     (Font               : in     Gdk_Font;
        Str                : in     String)
        return Gint;

Return the height in pixels of the string.
This is the total height, and you can not easily tell how this height
is split around the baseline.
function Text_Height
     (Font               : in     Gdk_Font;
        Str                : in     String)
        return Gint;

Same as String_Height.
In C, this function is intended to measure only the width of a part of
the string, but you can simply pass it a substring in Ada.   This is
also called the right bearing of the string.
function Char_Height
     (Font               : in     Gdk_Font;
        Char               : in     Character)
        return Gint;

Return the total height in pixels of a single character.

File: gtkada_rm.info,  Node: Package_Gdk.GC,  Next: Package_Gdk.Main,  Prev: Package_Gdk.Font,  Up: Top

Package Gdk.GC
**************

A graphic context is a structure that describes all the attributes
used by the drawing functions in Gdk.   The colors, line styles, Fill
styles and so on are defined through  this structure.

   On X11 systems, this structure is stored directly on the XServer,
which speeds up the transfer of the drawing attributes a lot. Instead
of transferring all of them every time you call one of the drawing
functions, you simply specify which GC you want to use.

   Thus, it is recommended to create as many GCs as you need, instead
of creating a single one that is modified every time you need to
modify one of the attributes.

   On Unix machines, you should have a look at the external utility
'xgc'  which demonstrates all the basic settings of the graphic
contexts.

* Menu:

* Gdk.GC Types::
* Gdk.GC Subprograms::


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

Types
=====

subtype Gdk_GC is Gdk.Gdk_GC;

A graphic context that contain all the information to draw graphics  on
the screen.   Creating these GC is more efficient than passing a lot of
parameters  to each of the drawing functions, since these GC are stored
on the  server side and do not need to be pass through the network.
type Gdk_GC_Values is new Gdk.C_Proxy;

A structure used on the client side to store the same information  as
the GC. Creating a GC from this structure is more efficient than
calling a lot of functions to modify the GC directly, since there is  a
single call to the server.

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

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

Gdk_GC
------

procedure Gdk_New
     (GC                 : out    Gdk_GC;
        Window             : in     Gdk.Window.Gdk_Window);

Create a new graphic context.
The window must have been realized first (so that it is associated
with some resources on the Xserver).   The GC can then be used for any
window that has the same root window,  and same color depth as Window.
See the manual page for XCreateGC on Unix systems for more information.
procedure Gdk_New
     (GC                 : out    Gdk_GC;
        Window             : in     Gdk.Window.Gdk_Window;
        Values             : in     Gdk_GC_Values;
        Values_Mask        : in     Types.Gdk_GC_Values_Mask);

Create a new graphic context.
It is directly created with the values set in Values, and whose
associated field has been set in Values_Mask.   This is faster than
calling the simple Gdk_New function and each of  other functions in
this package, since each of them requires a call  to the server.
procedure Destroy
     (GC                 : in     Gdk_GC);

Free the memory allocated on the server for the graphic context.
Graphic contexts are never freed automatically by GtkAda, this is  the
user responsibility to do so.
procedure Ref
     (GC                 : in     Gdk_GC);

Increment the reference counting for the graphic context.
You should usually not have to use it.
procedure Unref
     (GC                 : in     Gdk_GC);

Decrement the reference counting for the graphic context.
When this reaches 0, the graphic context is destroyed.
procedure Get_Values
     (GC                 : in     Gdk_GC;
        Values             : in     Gdk_GC_Values);

Get the values set in the GC.
This copies the values from the server to client, allowing faster
modifications. Values can then be copied back to the server by
creating a new graphic context with the function Gdk_New above.
Values should have been allocated first with a call to Gdk_New.
procedure Set_Foreground
     (GC                 : in     Gdk_GC;
        Color              : in     Gdk.Color.Gdk_Color);

Set the foreground color for the graphic context.
This color is the one that is used by most drawing functions.
procedure Set_Background
     (GC                 : in     Gdk_GC;
        Color              : in     Gdk.Color.Gdk_Color);

Set the background color for the graphic context.
procedure Set_Font
     (GC                 : in     Gdk_GC;
        Font               : in     Gdk.Font.Gdk_Font);

Set the font used by the graphic context.
This font is used by the function Gdk.Drawable.Draw_Text.
procedure Set_Function
     (GC                 : in     Gdk_GC;
        Func               : in     Types.Gdk_Function);

Set the function in the graphic context.
This function specifies how the points are put on the screen, ie  if
GtkAda how GtkAda should mix the point already on the screen  and the
new point being put.   Note that setting the function to Gdk_Xor is not
the right way  to do animation. You should instead save the background
pixmap,  put the image, and then restore the background.

   In general, there are three basic steps to drawing: reading the
source  pixels, reading the destination pixels, and writing the
destination  pixels.  Some functions only perform the third step (Set
and Clear),  some do not need the middle step (Copy), whereas most
require the three  steps, and thus can be much slower.
procedure Set_Fill
     (GC                 : in     Gdk_GC;
        Fill               : in     Types.Gdk_Fill);

Set the pattern used for filling the polygons.
procedure Set_Tile
     (GC                 : in     Gdk_GC;
        Tile               : in     Gdk.Gdk_Pixmap);

procedure Set_Stipple
     (GC                 : in     Gdk_GC;
        Stipple            : in     Gdk.Gdk_Pixmap);

procedure Set_Clip_Mask
     (GC                 : in     Gdk.GC.Gdk_GC;
        Mask               : in     Gdk.Gdk_Bitmap);

If Mask is set to Null_Bitmap, then no clip_mask is used for drawing.
Points will be drawn through this GC only where the bits are set to 1
in the mask. See also the function Set_Clip_Origin for  how to move the
mask inside the GC.
procedure Set_Ts_Origin
     (GC                 : in     Gdk_GC;
        X, Y               : in     Gint);

Set the Tile and Stipple origin in the graphic context.
procedure Set_Clip_Origin
     (GC                 : in     Gdk_GC;
        X, Y               : in     Gint);

Set the origin of the clip mask.
See the functions Set_Clip_Rectangle, Set_Clip_Region and
Gdk.Bitmap.Set_Clip_Mask for more explanation.
procedure Set_Clip_Rectangle
     (GC                 : in     Gdk_GC;
        Rectangle          : in     Gdk.Rectangle.Gdk_Rectangle);

Set the clip rectangle.
Only the points that are drawn inside this rectangle will be displayed
on the screen. Note that you might have to modify the Clip origin first
with Set_Clip_Origin.   See Set_Clip_Mask to delete the current clip
mask.
procedure Set_Clip_Region
     (GC                 : in     Gdk_GC;
        Region             : in     Gdk.Region.Gdk_Region);

Define a clip region on the screen.
This is just like Set_Clip_Rectangle, except that a region is a more
complex region, that can be the intersection or union of multiple
rectangles. Note that the Clip_Origin can have an influence on this
function.
procedure Set_Subwindow
     (GC                 : in     Gdk_GC;
        Mode               : in     Types.Gdk_Subwindow_Mode);

Set the subwindow mode for the graphic context.
This specifies whether the drawing routines should be clipped to  the
specific window they are drawn into, or if they should extend  to
subwindows as well.
procedure Set_Exposures
     (GC                 : in     Gdk_GC;
        Exposures          : in     Boolean);

Exposures indicates whether you want "expose" and "noexpose" events to
be reported when calling Copy_Area and Copy_Plane with this GC.   You
should disable this if you don't need the event and want to optimize
your application.   If Exposures is True, then any call to Copy_Area or
Draw_Pixmap will  generate an expose event. Otherwise, these will
generate a no_expose  event.
procedure Set_Line_Attributes
     (GC                 : in     Gdk_GC;
        Line_Width         : in     Gint;
        Line_Style         : in     Types.Gdk_Line_Style;
        Cap_Style          : in     Types.Gdk_Cap_Style;
        Join_Style         : in     Types.Gdk_Join_Style);

Set the line attributes for this GC.
Line_Width is the width of the line. If its value is 0, the line is as
thin as possible, possibly even more so than if the width is 1. It is
also faster to draw a line with width 0 than any other line width.

   Line_Style specifies whether the line should be solid or dashed.
With Line_On_Off_Dash, the colors are alternatively the foreground
color, and blank. With Line_Double_Dash, the colors are  alternatively
the foreground and background colors.

   Cap_Style specifies how the line should end, either flat or rounded.

   Join_Style specifies how two consecutive lines drawn by Draw_Lines
are  connected.
procedure Set_Dashes
     (Gc                 : in     Gdk_GC;
        Dash_Offset        : in     Gint;
        Dash_List          : in     Guchar_Array);

Specify the dash pattern when the line's style is anything but solid.
The values in the array alternatively give the length (in pixels) of
the plain dash, the empty dash, the second plain dash, ... None of
these values can be 0. If there is an odd number of items in Dash_List,
this is equivalent to giving the array concatenated with itself.
Dash_Offset specifies the phase of the pattern to start with.
procedure Copy
     (Dst_GC             : in     Gdk_GC;
        Src_GC             : in     Gdk_GC);

Copy a Src_GC to Dst_GC.
Gdk_Color_Values
----------------

function Gdk_New               return Gdk_GC_Values;

Allocate a new Values structure on the client.
Note that this function allocates a C structure, and thus needs to  be
freed with a call to Free below.
procedure Free
     (Values             : in     Gdk_GC_Values);

Free the C structure associated with Values.
procedure Set_Foreground
     (Values             : in     Gdk_GC_Values;
        Color              : in     Gdk.Color.Gdk_Color);

Same as Set_Foreground, but on the client side
procedure Set_Background
     (Values             : in     Gdk_GC_Values;
        Color              : in     Gdk.Color.Gdk_Color);

Same as Set_Background, but on the client side
procedure Set_Font
     (Values             : in     Gdk_GC_Values;
        Font               : in     Gdk.Font.Gdk_Font);

Same as Set_Font, but on the client side
procedure Set_Function
     (Values             : in     Gdk_GC_Values;
        Func               : in     Types.Gdk_Function);

Same as Set_Function, but on the client side
procedure Set_Fill
     (Values             : in     Gdk_GC_Values;
        Fill               : in     Types.Gdk_Fill);

Same as Set_Fill, but on the client side
procedure Set_Ts_Origin
     (Values             : in     Gdk_GC_Values;
        X, Y               : in     Gint);

Same as Set_Ts_Origin, but on the client side
procedure Set_Clip_Origin
     (Values             : in     Gdk_GC_Values;
        X, Y               : in     Gint);

Same as Set_Clip_Origin, but on the client side
procedure Set_Subwindow
     (Values             : in     Gdk_GC_Values;
        Mode               : in     Types.Gdk_Subwindow_Mode);

Same as Set_Subwindow, but on the client side
procedure Set_Exposures
     (Values             : in     Gdk_GC_Values;
        Exposures          : in     Boolean);

Same as Set_Exposures, but on the client side
procedure Set_Line_Attributes
     (Values             : in     Gdk_GC_Values;
        Line_Width         : in     Gint;
        Line_Style         : in     Types.Gdk_Line_Style;
        Cap_Style          : in     Types.Gdk_Cap_Style;
        Join_Style         : in     Types.Gdk_Join_Style);

Same as Set_Line_Attributes, but on the client side

File: gtkada_rm.info,  Node: Package_Gdk.Main,  Next: Package_Gdk.Pixbuf,  Prev: Package_Gdk.GC,  Up: Top

Package Gdk.Main
****************

This package provides routines to handle initialization and set up of
the  Gdk library.

* Menu:

* Gdk.Main Subprograms::


File: gtkada_rm.info,  Node: Gdk.Main Subprograms,  Up: Package_Gdk.Main

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

procedure Init;

Initialize the library for use.
The command line arguments are modified to reflect any arguments  which
were not handled. (Such arguments should either  be handled by the
application or dismissed).
procedure Gdk_Exit
     (Error_Code         : in     Gint);

Restore the library to an un-itialized state and exits
the program using the "exit" system call.   Error_Code is the error
value to pass to "exit".   Allocated structures are freed and the
program exits cleanly.
function Set_Locale            return String;

Initialize handling of internationalization of strings.
*note Package_Gtkada.Intl:: for more details.
procedure Set_Locale;

Drops the string returned by the Set_Locale function;
procedure Set_Use_Xshm
     (Use_Xshm           : in     Boolean := True);

Set whether shared memory (when supported by the graphic server) should
be used.
function Get_Use_Xshm          return Boolean;

Return whether shared memory on the graphic server is used.
function Get_Display           return String;

Return the name of the display.
function Time_Get              return Guint32;

Get the number of milliseconds since the library was initialized.
This time value is accurate to milliseconds even though  a more
accurate time down to the microsecond could be  returned.   Note that
this function is currently not supported under Win32 systems.
function Timer_Get             return Guint32;

Return the current timer interval.
This interval is in units of milliseconds.
procedure Timer_Set
     (Milliseconds       : in     Guint32);

Set the timer interval.
Milliseconds is the new value for the timer.   As a side effect, calls
to Gdk.Event.Get will last for a maximum  of time of Milliseconds.
However, a value of 0 milliseconds will cause  Gdk.Event.Get to block
indefinitely until an event is received.
procedure Timer_Enable;

Enable the Gdk timer.
procedure Timer_Disable;

Disable the Gdk timer.
function Screen_Width          return Gint;

Return the width of the screen.
function Screen_Height         return Gint;

Return the height of the screen.
function Screen_Width_MM       return Gint;

Return the width of the screen in millimeters.
function Screen_Height_MM      return Gint;

Return the height of the screen in millimeters.
procedure Flush;

Flush the queue of graphic events and then wait
until all requests have been received and processed.
procedure Beep;

Emit a beep.
procedure Key_Repeat_Disable;

Disable the key repeat behavior.
procedure Key_Repeat_Restore;

Restore the key repet behavior.
function Pointer_Grab
     (Window             : in     Gdk.Window.Gdk_Window;
        Owner_Events       : in     Boolean := True;
        Event_Mask         : in     Gdk.Types.Gdk_Event_Mask;
        Confine_To         : in     Gdk.Window.Gdk_Window
                            := Gdk.Window.Null_Window;
        Cursor             : in     Gdk.Cursor.Gdk_Cursor
                            := Gdk.Cursor.Null_Cursor;
        Time               : in     Guint32)
        return Boolean;

Grab the pointer to a specific window.
   * Window is the window which will receive the grab

   * Owner_Events specifies whether events will be reported as is,
     or relative to Window

   * Event_Mask masks only interesting events

   * Confine_To limits the cursor movement to the specified window

   * Cursor changes the cursor for the duration of the grab

   * Time specifies the time  Requires a corresponding call to
     Pointer_Ungrab

procedure Pointer_Ungrab
     (Time               : in     Guint32);

Release any pointer grab.
function Pointer_Is_Grabbed    return Boolean;

Tell wether there is an active pointer grab in effect.
function Keyboard_Grab
     (Window             : in     Gdk.Window.Gdk_Window;
        Owner_Events       : in     Boolean := True;
        Time               : in     Guint32)
        return Boolean;

Grab the keyboard to a specific window.
   * Window is the window which will receive the grab

   * Owner_Events specifies whether events will be reported as is,
     or relative to Window

   * Time specifies the time  Requires a corresponding call to
     Keyboard_Ungrab

procedure Keyboard_Ungrab
     (Time               : in     Guint32);

Release any keyboard grab.

File: gtkada_rm.info,  Node: Package_Gdk.Pixbuf,  Next: Package_Gdk.Pixmap,  Prev: Package_Gdk.Main,  Up: Top

Package Gdk.Pixbuf
******************

This object provides image manipulation routines.

   The following image formats are known, but some depend on external
libraries for the proper loading of files (indicated with * in the
list):     PNG*, JPEG*, TIFF*, GIF, XPM, PNM, Sun raster file (ras),
ico,     bmp.

   With this package, you can load images from file, display them on the
screen, re-scale them and composite them with other images.   All the
functions fully support alpha channels (opacity).

   Different filters are provided, depending on the quality of output
you  expect and the speed you need.

* Menu:

* Gdk.Pixbuf Types::
* Gdk.Pixbuf Subprograms::


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

Types
=====

type Alpha_Mode is
     (Alpha_Bilevel, Alpha_Full);

Alpha compositing mode.   This indicates how the alpha channel (for
opacity) is handled when  rendering.
type Gdk_Pixbuf is private;

A very efficient client-side pixmap.   This type can be adapted to all
the possible screen depths (number of  bits per pixel), and the
algorithms are extremely efficient.   You can also load a pixbuf
directly from an external file in one of  the standard image formats.

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

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

Accessing the fields
--------------------

function Get_Format
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gdk.Art.Pixbuf.Art_Pix_Format;

Return the format of the image.
This can currently be only RGB, but extensions will be implemented  for
gray, cmyk, lab,...
function Get_N_Channels
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gint;

Number of channels in the image.
function Get_Has_Alpha
     (Pixbuf             : in     Gdk_Pixbuf)
        return Boolean;

Return True if the image has an alpha channel (opacity information).
function Get_Bits_Per_Sample
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gint;

Number of bits per color sample.
function Get_Pixels
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gdk.Rgb.Rgb_Buffer_Access;

Return a pointer to the pixel data of the image.
function Get_Width
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gint;

Return the width of the image in pixels.
function Get_Height
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gint;

Return the height of the image in pixels.
function Get_Rowstride
     (Pixbuf             : in     Gdk_Pixbuf)
        return Gint;

Return the number of bytes between rows in the image data.
Reference counting
------------------

procedure Ref
     (Pixbuf             : in     Gdk_Pixbuf);

Increment the reference counting on the image.
The image is destroyed when its reference counting reaches 0.   Note
also that most of the time you won't have to call this  function
yourself.
procedure Unref
     (Pixbuf             : in     Gdk_Pixbuf);

Decrement the reference counting on the image.
Libart interface
----------------

function New_From_Art_Pixbuf
     (Pixbuf             : in     Gdk.Art.Pixbuf.Art_Pixbuf)
        return Gdk_Pixbuf;

Wrap an art_pixbuf.
The reference counting is initialized to 1.
function Gdk_New
     (Width              : in     Gint;
        Height             : in     Gint;
        Format             : in     Gdk.Art.Pixbuf.Art_Pix_Format
                            := Gdk.Art.Pixbuf.Art_Pix_RGB;
        Has_Alpha          : in     Boolean := False;
        Bits_Per_Sample    : in     Gint := 8)
        return Gdk_Pixbuf;

Create a blank pixbuf with an optimal row stride and a new buffer.
The buffer is allocated, but not cleared.   The reference counting is
initialized to 1.
Creating
--------

function New_From_File
     (Filename           : in     String)
        return Gdk_Pixbuf;

Load an image from file.
function New_From_Xpm_Data
     (Data               : in     Interfaces.C.Strings.chars_ptr_array)
        return Gdk_Pixbuf;

Create an image from a XPM data.
function Add_Alpha
     (Pixbuf             : in     Gdk_Pixbuf;
        Substitute_Color   : in     Boolean;
        Red                : in     Guchar := 0;
        Green              : in     Guchar := 0;
        Blue               : in     Guchar := 0)
        return Gdk_Pixbuf;

Return a newly allocated image copied from Pixbuf, but with an
extra alpha channel.   If Pixbuf already had an alpha channel, the two
images have exactly  the same contents.   If Substitute_Color is True,
the color (Red, Green, Blue) is  substituted for zero opacity.   If
Substitute_Color is False, Red, Green and Blue are ignored, and a  new
color is created with zero opacity.
Rendering
---------

procedure Render_Threshold_Alpha
     (Pixbuf             : in     Gdk_Pixbuf;
        Bitmap             : in     Gdk.Bitmap.Gdk_Bitmap;
        Src_X              : in     Gint;
        Src_Y              : in     Gint;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Width              : in     Gint;
        Height             : in     Gint;
        Alpha_Threshold    : in     Gint);

Take the opacity values in a rectangular portion of a pixbuf and
thresholds them to produce a bi-level alpha mask that can be used as  a
clipping mask for a drawable.   Bitmap is the bitmap where the bilevel
mask will be painted to.   Alpha_Threshold are the opacity values below
which a pixel will be  painted as zero. All other values will be
painted as one.
procedure Render_To_Drawable
     (Pixbuf             : in     Gdk_Pixbuf;
        Drawable           : in     Gdk.Drawable.Gdk_Drawable;
        Gc                 : in     Gdk.GC.Gdk_GC;
        Src_X              : in     Gint;
        Src_Y              : in     Gint;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Width              : in     Gint;
        Height             : in     Gint;
        Dither             : in     Gdk.Rgb.Gdk_Rgb_Dither
                            := Gdk.Rgb.Dither_Normal;
        X_Dither           : in     Gint := 0;
        Y_Dither           : in     Gint := 0);

Render a rectangular portion of a pixbuf to a drawable while using the
specified GC. This is done using Gdk.RGB, so the specified drawable
must have the Gdk.RGB visual and colormap.  Note that this function
will ignore the opacity information for images with an alpha channel;
the GC must already have the clipping mask set if you want transparent
regions to show through.

   For an explanation of dither offsets, see the Gdk.RGB documentation.
In  brief, the dither offset is important when re-rendering partial
regions  of an image to a rendered version of the full image, or for
when the  offsets to a base position change, as in scrolling.  The
dither matrix  has to be shifted for consistent visual results.  If you
do not have  any of these cases, the dither offsets can be both zero.
procedure Render_To_Drawable_Alpha
     (Pixbuf             : in     Gdk_Pixbuf;
        Drawable           : in     Gdk.Drawable.Gdk_Drawable;
        Src_X              : in     Gint;
        Src_Y              : in     Gint;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Width              : in     Gint;
        Height             : in     Gint;
        Alpha              : in     Alpha_Mode;
        Alpha_Threshold    : in     Gint;
        Dither             : in     Gdk.Rgb.Gdk_Rgb_Dither
                            := Gdk.Rgb.Dither_Normal;
        X_Dither           : in     Gint := 0;
        Y_Dither           : in     Gint := 0);

Render a rectangular portion of a pixbuf to a drawable.
This is done using Gdk.RGB, so the specified drawable must have the
GdkRGB visual and colormap. When used with Alpha_Bilevel, this function
has to create a bitmap out of the thresholded alpha channel of the
image and, it has to set this bitmap as the clipping mask for the GC
used for drawing.  This can be a significant performance penalty
depending on the size and the complexity of the alpha channel of the
image.  If performance is crucial, consider handling the alpha channel
yourself (possibly by caching it in your application) and using
Render_To_Drawable or Gdk.RGB directly instead.

   If the image does have opacity information and Alpha_Mode  is
Alpha_Bilevel, specifies the threshold value for opacity values
function Get_From_Drawable
     (Dest               : in     Gdk_Pixbuf;
        Src                : in     Gdk.Drawable.Gdk_Drawable;
        Cmap               : in     Gdk.Color.Gdk_Colormap;
        Src_X              : in     Gint;
        Src_Y              : in     Gint;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Width              : in     Gint;
        Height             : in     Gint)
        return Gdk_Pixbuf;

Transfer image data from a Gdk drawable and converts it to an RGB(A)
representation inside a Gdk_Pixbuf.

   If the drawable src is a pixmap, then a suitable colormap must be
specified, since pixmaps are just blocks of pixel data without an
associated colormap.   If the drawable is a window, the Cmap argument
will be ignored and the  window's own colormap will be used instead.

   If the specified destination pixbuf Dest is Null_Pixbuf, then this
function will create an RGB pixbuf with 8 bits per channel and no
alpha, with the same size specified by the Width and Height  arguments.
In this case, the Dest_x and Dest_y arguments must be  specified as 0,
otherwise the function will return Null_Pixbuf.  If the  specified
destination pixbuf is not Null_Pixbuf and it contains alpha
information, then the filled pixels will be set to full opacity.

   If the specified drawable is a pixmap, then the requested source
rectangle must be completely contained within the pixmap, otherwise the
function will Null_Pixbuf

   If the specified drawable is a window, then it must be viewable, i.e.
all of its ancestors up to the root window must be mapped.  Also, the
specified source rectangle must be completely contained within the
window and within the screen.  If regions of the window are obscured by
non-inferior windows, the contents of those regions are undefined.
The contents of regions obscured by inferior windows of a different
depth than that of the source window will also be undefined.

   Return value: The same pixbuf as Dest if it was non-NULL, or a
newly-created pixbuf with a reference count of 1 if no destination
pixbuf was specified.
procedure Copy_Area
     (Src_Pixbuf         : in     Gdk_Pixbuf;
        Src_X              : in     Gint;
        Src_Y              : in     Gint;
        Width              : in     Gint;
        Height             : in     Gint;
        Dest_Pixbuf        : in     Gdk_Pixbuf;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint);

Copy a rectangular area from Src_pixbuf to Dest_pixbuf.
Conversion of pixbuf formats is done automatically.
Scaling
-------

procedure Scale
     (Src                : in     Gdk_Pixbuf;
        Dest               : in     Gdk_Pixbuf;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Dest_Width         : in     Gint;
        Dest_Height        : in     Gint;
        Offset_X           : in     Gdouble := 0.0;
        Offset_Y           : in     Gdouble := 0.0;
        Scale_X            : in     Gdouble := 1.0;
        Scale_Y            : in     Gdouble := 1.0;
        Filter_Level       : in     Gdk.Art.Pixbuf.Art_Filter_Level
                            := Gdk.Art.Pixbuf.Filter_Bilinear);

Transform the source image by scaling by Scale_x and Scale_y then
translating by Offset_x and Offset_y.   The image is then rendered in
the rectangle (Dest_x, Dest_y,  Dest_width, Dest_height) of the
resulting image onto the destination  drawable replacing the previous
contents.
procedure Composite
     (Src                : in     Gdk_Pixbuf;
        Dest               : in     Gdk_Pixbuf;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Dest_Width         : in     Gint;
        Dest_Height        : in     Gint;
        Offset_X           : in     Gdouble := 0.0;
        Offset_Y           : in     Gdouble := 0.0;
        Scale_X            : in     Gdouble := 1.0;
        Scale_Y            : in     Gdouble := 1.0;
        Filter_Level       : in     Gdk.Art.Pixbuf.Art_Filter_Level
                            := Gdk.Art.Pixbuf.Filter_Bilinear;
        Overall_Alpha      : in     Gint := 128);

Transform the source image by scaling by Scale_x and Scale_y then
translating by Offset_x and Offset_y, then composite the rectangle
(Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image onto
the destination drawable.  Alpha should be in 0 .. 255
procedure Composite_Color
     (Src                : in     Gdk_Pixbuf;
        Dest               : in     Gdk_Pixbuf;
        Dest_X             : in     Gint;
        Dest_Y             : in     Gint;
        Dest_Width         : in     Gint;
        Dest_Height        : in     Gint;
        Offset_X           : in     Gdouble := 0.0;
        Offset_Y           : in     Gdouble := 0.0;
        Scale_X            : in     Gdouble := 1.0;
        Scale_Y            : in     Gdouble := 1.0;
        Filter_Level       : in     Gdk.Art.Pixbuf.Art_Filter_Level
                            := Gdk.Art.Pixbuf.Filter_Bilinear;
        Overall_Alpha      : in     Gint := 128;
        Check_X            : in     Gint := 0;
        Check_Y            : in     Gint := 0;
        Check_Size         : in     Gint := 0;
        Color1             : in     Gdk.Art.Pixbuf.Art_U32 := 0;
        Color2             : in     Gdk.Art.Pixbuf.Art_U32 := 0);

Transform the source image by scaling by Scale_x and Scale_y then
translating by Offset_x and Offset_y, then composites the rectangle
(Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image with
a checkboard of the colors Color1 and Color2 and renders it onto the
destination drawable.   The origin of checkboard is at (Check_x,
Check_y)  Color1 is the color at the upper left of the check.
function Scale_Simple
     (Src                : in     Gdk_Pixbuf;
        Dest_Width         : in     Gint;
        Dest_Height        : in     Gint;
        Filter_Level       : in     Gdk.Art.Pixbuf.Art_Filter_Level
                            := Gdk.Art.Pixbuf.Filter_Bilinear)
        return Gdk_Pixbuf;

Scale the Src image to Dest_width x Dest_height and render the result
into a new pixbuf.
function Composite_Color_Simple
     (Src                : in     Gdk_Pixbuf;
        Dest_Width         : in     Gint;
        Dest_Height        : in     Gint;
        Filter_Level       : in     Gdk.Art.Pixbuf.Art_Filter_Level
                            := Gdk.Art.Pixbuf.Filter_Bilinear;
        Overall_Alpha      : in     Gint := 128;
        Color1             : in     Gdk.Art.Pixbuf.Art_U32 := 0;
        Color2             : in     Gdk.Art.Pixbuf.Art_U32 := 0)
        return Gdk_Pixbuf;

Scale Src to Dest_width x Dest_height and composite the result with
a checkboard of colors Color1 and Color2 and render the result into  a
new pixbuf.

File: gtkada_rm.info,  Node: Package_Gdk.Pixmap,  Next: Package_Gdk.Rgb,  Prev: Package_Gdk.Pixbuf,  Up: Top

Package Gdk.Pixmap
******************

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.Pixmap.Draw. 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.Bitmap:: for more details on bitmap
handling.

* Menu:

* Gdk.Pixmap Types::
* Gdk.Pixmap Subprograms::


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

Types
=====

subtype Gdk_Pixmap is Gdk.Gdk_Pixmap;

A server-side image.   You can create an empty pixmap, or load if from
external files in  bitmap and pixmap format. See Gdk.Pixbuf if you need
to load  images in other formats.

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

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

procedure Gdk_New
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Width              : in     Gint;
        Height             : in     Gint;
        Depth              : in     Gint := -1);

Create a new pixmap with a given size.
Window is used to determine default values for the new pixmap.   Can be
eventually null.   Width is the width of the new pixmap in pixels.
Height is the height of the new pixmap in pixels.   Depth is the depth
(number of bits per pixel) of the new pixmap.   If -1, and window is
not null, the depth of the new pixmap will be  equal to that of window.
Automatically reference the pixmap once.
procedure Ref
     (Pixmap             : in     Gdk_Pixmap);

Add a reference to a pixmap.
procedure Unref
     (Pixmap             : in     Gdk_Pixmap);

This is the usual way to destroy a pixmap. The memory is freed when
there is no more reference
procedure Create_From_Data
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Data               : in     String;
        Width              : in     Gint;
        Height             : in     Gint;
        Depth              : in     Gint;
        Fg                 : in     Color.Gdk_Color;
        Bg                 : in     Color.Gdk_Color);

Create a pixmap 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.   Depth is the depth (number of bits per
pixel) of the new pixmap.   Fg is the foreground color.   Bg is the
background color.
procedure Create_From_Xpm
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Mask               : in out Gdk.Bitmap.Gdk_Bitmap;
        Transparent        : in     Gdk.Color.Gdk_Color;
        Filename           : in     String);

Create a pixmap from a XPM file.
Window is used to determine default values for the new pixmap.   Mask
is a pointer to a place to store a bitmap representing the
transparency mask of the XPM file. Can be null, in which case
transparency will be ignored.   Transparent is the color to be used for
the pixels that are transparent  in the input file. Can be null, in
which case a default color will be  used.   Filename is the filename of
a file containing XPM data.
procedure Create_From_Xpm
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Colormap           : in     Gdk.Color.Gdk_Colormap;
        Mask               : in out Gdk.Bitmap.Gdk_Bitmap;
        Transparent        : in     Gdk.Color.Gdk_Color;
        Filename           : in     String);

Create a pixmap from a XPM file using a particular colormap.
Window is used to determine default values for the new pixmap. Can be
null if colormap is given.   Colormap is the Gdk_Colormap that the new
pixmap will use. If omitted,  the colormap for window will be used.
Mask is a pointer to a place to store a bitmap representing the
transparency mask of the XPM file. Can be null, in which case
transparency will be ignored.   Transparent is the color to be used for
the pixels that are transparent  in the input file. Can be null, in
which case a default color will be  used.   Filename is the filename of
a file containing XPM data.
procedure Create_From_Xpm_D
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Mask               : in out Gdk.Bitmap.Gdk_Bitmap;
        Transparent        : in     Gdk.Color.Gdk_Color;
        Data               : in     Gtkada.Types.Chars_Ptr_Array);

Create a pixmap from data in XPM format.
Window is used to determine default values for the new pixmap.   Mask
is a pointer to a place to store a bitmap representing the
transparency mask of the XPM file. Can be null, in which case
transparency will be ignored.   Transparent will be used for the pixels
that are transparent in the  input file. Can be null in which case a
default color will be used.   Data is a pointer to a string containing
the XPM data.
procedure Create_From_Xpm_D
     (Pixmap             : out    Gdk_Pixmap;
        Window             : in     Gdk.Window.Gdk_Window;
        Colormap           : in     Gdk.Color.Gdk_Colormap;
        Mask               : in out Gdk.Bitmap.Gdk_Bitmap;
        Transparent        : in     Gdk.Color.Gdk_Color;
        Data               : in     Gtkada.Types.Chars_Ptr_Array);

Create a pixmap from data in XPM format using a particular colormap.
Window is used to determine default values for the new pixmap.
Colormap is the Gdk_Colormap that the new pixmap will be use. If
omitted, the colormap for window will be used.   Mask is a pointer to a
place to store a bitmap representing the  transparency mask of the XPM
file. Can be null, in which case  transparency will be ignored.
Transparent will be used for the pixels that are transparent in the
input file. Can be null in which case a default color will be used.
Data is a pointer to a string containing the XPM data.

File: gtkada_rm.info,  Node: Package_Gdk.Rgb,  Next: Package_Gdk.Threads,  Prev: Package_Gdk.Pixmap,  Up: Top

Package Gdk.Rgb
***************

This package implements a client-side pixmap. As opposed to the pixmaps
found in Gdk.Pixmap, this one simply implements a local buffer, which
can be manipulated at the pixel level easily. This buffer then needs to
be sent to the server.   The major efficiency difference is that the
same amount of data needs  to be sent to the server no matter how much
things were modified.   Gdk.Pixmaps requires one communication with the
server per drawing  function.   Some X servers are also optimized so
that the buffers in this package  can be implemented in shared memory
with the server, which of course  makes it much faster to transfer the
data.   This package is basically an implementation of XImage (on
X-Window),  which means that it handles transparently different depths,
byte  ordering,... It also provides some color dithering functions.

   Note that you need to initialize this package before using it by
calling the Init procedure below.

   See the commands Get_Visual and Get_Cmap below on how to use the
colormaps and visual with this package

   Dithering simulates a higher number of colors than what is available
on  the current visual (only for 8-bit and 16-bit displays).

* Menu:

* Gdk.Rgb Types::
* Gdk.Rgb Subprograms::

