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: Glib.Object Subprograms,  Prev: Glib.Object Types,  Up: Package_Glib.Object

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

function Is_Created
       (Object             : in     GObject_Record'Class)
        return Boolean;

Return True if the associated C object has been created, False if
no C object is associated with Object.   This is not the same as
testing whether an access type (for instance  any of the widgets) is
"null", since this relates to the underlying  C object.
function Get_Type
       (Object             : access GObject_Record)
        return GType;

Return the type of Object.
This function is mostly used internally, since in Ada you can simply
test whether an object belong to a class with a statement like:

   if Object in Gtk_Button_Record'Class then ...

   which is easier.
Life cycle
----------

procedure G_New
       (Object             : out    GObject);

Create a new GObject.
This is only required when you want to create an Ada tagged type to
which you can attach new signals. Most of the time, you only need to
directly create the appropriate Gtk Widget by calling the correct
Gtk_New procedure.
procedure Ref
       (Object             : access GObject_Record);

Increment the reference counter for Object. See Unref below.
Since an object is not deleted while its reference count is not null,
this is a way to keep an object in memory, in particular when you  want
to temporarily remove a widget from its parent.
procedure Unref
       (Object             : access GObject_Record);

Decrement the reference counter for Object. When this reaches 0, the
object is effectively destroy, all the callbacks associated with it are
disconnected.
procedure Weak_Ref
       (Object             : access GObject_Record'Class;
        Notify             :        Weak_Notify;
        Data               :        System.Address
                            := System.Null_Address);

This kind of reference doesn't increment the object's reference
counting. However, it can and should be used to monitor the object's
life cycle, in particular to detect is destruction.   When Object is
destroyed, calls Notify
procedure Weak_Unref
       (Object             : access GObject_Record'Class;
        Notify             :        Weak_Notify;
        Data               :        System.Address
                            := System.Null_Address);

Cancels the settings of Weak_Ref.
Interfacing with C
------------------

The following functions are made public so that one can easily create
new objects outside the Glib or Gtk package hierarchy.   Only
experienced users should make use of these functions.

function Get_Object
       (Object             : access GObject_Record'Class)
        return System.Address;

Access the underlying C pointer.
procedure Set_Object
       (Object             : access GObject_Record'Class;
        Value              :        System.Address);

Modify the underlying C pointer.
function Get_User_Data
       (Obj                :        System.Address;
        Stub               :        GObject_Record'Class)
        return GObject;

Return the Ada object matching the C object Obj. If Obj was created
explicitely from GtkAda, this will be the exact same widget. If Obj was
created implicitely by gtk+ (buttons in complex windows,...), a new Ada
object of type Stub will be created.
function Get_User_Data_Fast
       (Obj                :        System.Address;
        Stub               :        GObject_Record'Class)
        return GObject;

Same as Get_User_Data, but does not try to guess the type of Obj,
always default to Stub if Obj is unknown to GtkAda.
function Unchecked_Cast
       (Obj                : access GObject_Record'Class;
        Stub               :        GObject_Record'Class)
        return GObject;

Cast Obj in an object of tag Stub'Class.
Return the resulting object and free the memory pointed by Obj.
Signals
-------

Any child of GObject can be associated with any number of signals. The
mechanism for signals is fully generic, and any number of arguments can
be associated with signals.   See the function Initialize_Class_Record
for more information on how  to create new signals for your own new
widgets.   The subprograms below are provided for introspection: they
make it  possible to query the list of signals defined for a specific
widget,  as well as their parameters and return types.

function Lookup
       (Object             :        Glib.GType;
        Signal             :        String)
        return Glib.Signal_Id;

Returns the signal Id associated with a specific Object/Signal pair.
Null_Signal_Id is returned if no such signal exists for Object.   You
can then use the Query procedure to get more information on the  signal.
function List_Ids
       (Typ                :        Glib.GType)
        return Signal_Id_Array;

Return the list of signals defined for Typ. You can get more information
on each of this signals by using the Query function below.   See also
the function Get_Type above to convert from an object instance  to its
type. Using a GType as the parameter makes it easier to find the
signals for a widget and its ancestors (using Glib.Parent).
procedure Query
       (Id                 :        Glib.Signal_Id;
        Result             : out    Signal_Query);

Return the description associated with the signal Id. You can get the
various fields from Query with one of the functions below.   Result is
undefined if Id is Invalid_Signal_Id or Null_Signal_Id
function Id
       (Q                  :        Signal_Query)
        return Glib.Signal_Id;

Return the signal Id. Each Id is specific to a widget/signal name pair.
These Ids can then be used to temporarily block a signal for instance,
through the subprograms in Gtk.Handlers.
function Signal_Name
       (Q                  :        Signal_Query)
        return String;

Return the name of the signal, as should be used in a call to Connect.
function Return_Type
       (Q                  :        Signal_Query)
        return Glib.GType;

Return the type of object returned by the handlers for this signal.
function Params
       (Q                  :        Signal_Query)
        return GType_Array;

Return the list of parameters for the handlers for this signal
Creating new widgets
--------------------

These types and functions are used only when creating new widget types
directly in Ada. These functions initialize the classes so that they are
correctly recognized by gtk+ itself  See the GtkAda user's guide for
more information on how to create your  own widget types in Ada.

procedure Initialize_Class_Record
       (Object             : access GObject_Record'Class;
        Signals            :        Gtkada.Types.Chars_Ptr_Array;
        Class_Record       : in out GObject_Class;
        Type_Name          :        String;
        Parameters         :        Signal_Parameter_Types
                            := Null_Parameter_Types);

Create the class record for a new object type.
It is associated with Signals'Length new signals. A pointer to the
newly created structure is also returned in Class_Record.   If
Class_Record /= System.Null_Address, no memory allocation is
performed, we just reuse it. As a result, each instantiation of an
object will share the same GObject_Class, exactly as is done for gtk+.

   Note: The underlying C object must already have been initialized  by
a call to its parent's Initialize function.   Parameters'Length should
be the same as Signals'Length, or the result  is undefined.   As a
special case, if Parameters has its default value, all signals are
created with no argument. This is done for backward compatibility
mainly, and you should instead give it an explicit value.   Type_Name
should be a unique name identifying the name of the new type.

   Only the signals with no parameter can be connected from C code.
However, any signal can be connected from Ada. This is due to the way
we define default marshallers for the signals.
function Type_From_Class
       (Class_Record       :        GObject_Class)
        return GType;

Return the internal gtk+ type that describes the newly created
Class_Record
function Class_From_Type
       (Typ                :        GType)
        return GObject_Class;

Return the class record for a specific type
Signals
-------

??? This section is incomplete.

procedure Notify
       (Object             : access GObject_Record;
        Property_Name      :        String);

Emits the "notify" signal, to signal every listener that the property
has been changed.
Lists
-----

function Convert
       (W                  :        GObject)
        return System.Address;

function C_Signal_Query_Size   return Natural;



File: gtkada_rm.info,  Node: Package_Glib.Properties,  Next: Package_Glib.Properties.Creation,  Prev: Package_Glib.Object,  Up: Top

Package Glib.Properties
***********************

Properties are a fully general way to modify the appareance or behavior
of widgets. Most of the time, there exists a faster way to modify the
widget in the same fashion (for instance a direct call to a primitive
subprogram). However, the properties provide a general scheme to modify
these attributes.   For instance, they can be used to provide
introspection on the widget  (to automatically retrieve the attributes
that can be modified), or if  you need to implement a tool like a
GUI-Builder that is able to  manipulate any widget, even those that
didn't exist when the tool was  written.

   Two functions are provided for each type of property: Set_Property
and  Get_Property, which allow easy modification of specific widget
properties. For instance, you could do the following:      declare
   Button : Gtk_Button;      begin          Gtk_New (Button, "old
label");          Set_Property (Button, Label_Property, "new label");
  end;  to modify the label of a button.

   Likewise, you can retrieve the current label with:      Current :
String := Get_Property (Button, Label_Property);

   Dispatching is used ensure type-safety while using properties. The
appropriate Set_Property/Get_Property functions are called depending
on the type of the property you are trying to use. This is checked
statically by the compiler, which provides additional type-safety
compared to the C library.

   Note that some properties are read-only, and thus do not have the
Set_Property subprogram defined.

   When a property is modified, the signal "notify::<property>" is
emitted,  for instance, "notify::label" for a gtk_button. This is a
standard gtk+  signal to which you can connect with the subprograms in
gtk-handlers.ads

* Menu:

* Glib.Properties Types::
* Glib.Properties Subprograms::


File: gtkada_rm.info,  Node: Glib.Properties Types,  Next: Glib.Properties Subprograms,  Up: Package_Glib.Properties

Types
=====

type Property_Address is new Glib.Property;


type Property_Boolean is new Glib.Property;


type Property_C_Proxy is new Glib.Property;


type Property_Char is new Char_Properties.Property;


type Property_Char_RO is new Char_Properties.Property_RO;


type Property_Double is new Glib.Property;


type Property_Float is new Glib.Property;


type Property_Int is new Int_Properties.Property;


type Property_Long is new Long_Properties.Property;


type Property_Long_RO is new Long_Properties.Property_RO;


type Property_Object is new Glib.Property;


type Property_Object_WO is new Glib.Property;


type Property_String is new Glib.Property;


type Property_String_RO is new Glib.Property;


type Property_String_WO is new Glib.Property;


type Property_Uchar is new Uchar_Properties.Property;


type Property_Uchar_RO is new Uchar_Properties.Property_RO;


type Property_Uint is new Uint_Properties.Property;


type Property_Uint_RO is new Uint_Properties.Property_RO;


type Property_Ulong is new Ulong_Properties.Property;


type Property_Ulong_RO is new Ulong_Properties.Property_RO;


type Property_Unichar is new Unichar_Properties.Property;



File: gtkada_rm.info,  Node: Glib.Properties Subprograms,  Prev: Glib.Properties Types,  Up: Package_Glib.Properties

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

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_String;
        Value              :        String);

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_String_WO;
        Value              :        String);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_String)
        return String;

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_String_RO)
        return String;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Boolean;
        Value              :        Boolean);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Boolean)
        return Boolean;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Object;
        Value              : access Glib.Object.GObject_Record'Class);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Object)
        return Glib.Object.GObject;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Object_WO;
        Value              : access Glib.Object.GObject_Record'Class);

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Address;
        Value              :        System.Address);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Address)
        return System.Address;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Float;
        Value              :        Gfloat);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Float)
        return Gfloat;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Double;
        Value              :        Gdouble);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_Double)
        return Gdouble;

procedure Set_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_C_Proxy;
        Value              :        C_Proxy);

function Get_Property
       (Object             : access Glib.Object.GObject_Record'Class;
        Name               :        Property_C_Proxy)
        return C_Proxy;


File: gtkada_rm.info,  Node: Package_Glib.Properties.Creation,  Next: Package_Glib.Type_Conversion_Hooks,  Prev: Package_Glib.Properties,  Up: Top

Package Glib.Properties.Creation
********************************

This package provides all the required subprograms to create and
manipulate new properties associated with new widget types.

   You do not have to be familiar with this package in order to use
properties. See Glib.Object instead, that provides the minimal
subprograms to get and set properties.

   This package is only intended for writers of new widgets. You will
need  this function to create new properties.

   Each object in gtk+ has a set of so-called properties. These are
attributes that can be accessed, and possibly modified, by names.
They provide introspection, that is an object can specify which
properties it knows about, which can be modified,..., and thus provide a
huge support for special applications like GUI-Builders that need to
act  on any kind of widgets, even those it doesn't know about yet.

   However, for efficiency reasons, the properties are only names, and
are  not the only way to modify attributes of objects. It is often more
efficient to use the alternate method, as documented in the GtkAda
documentation for each property.

   Another interesting feature of properties is that every time a
property  is modified, a signal "property_changed" or "notify" is
emitted, and  it is thus easy to keep track of attributes in objects.

* Menu:

* Glib.Properties.Creation Types::
* Glib.Properties.Creation Subprograms::


File: gtkada_rm.info,  Node: Glib.Properties.Creation Types,  Next: Glib.Properties.Creation Subprograms,  Up: Package_Glib.Properties.Creation

Types
=====

type Enum_Class is new Glib.C_Proxy;


type Enum_Value is new Glib.C_Proxy;


type Flags_Class is new Glib.C_Proxy;


type Flags_Int_Value is mod Glib.Gint'Last;


type Flags_Value is new Glib.C_Proxy;


type Get_Property_Handler is access procedure


type Param_Spec_Boolean is new Param_Spec;


type Param_Spec_Boxed is new Param_Spec;


type Param_Spec_Char is new Param_Spec;


type Param_Spec_Double is new Param_Spec;


type Param_Spec_Enum is new Param_Spec;


type Param_Spec_Flags is new Param_Spec;


type Param_Spec_Float is new Param_Spec;


type Param_Spec_Int is new Param_Spec;


type Param_Spec_Long is new Param_Spec;


type Param_Spec_Object is new Param_Spec;


type Param_Spec_Param is new Param_Spec;


type Param_Spec_Pointer is new Param_Spec;


type Param_Spec_String is new Param_Spec;


type Param_Spec_Uchar is new Param_Spec;


type Param_Spec_Uint is new Param_Spec;


type Param_Spec_Ulong is new Param_Spec;


type Param_Spec_Unichar is new Param_Spec;


type Property_Id is new Guint;


type Set_Property_Handler is access procedure



File: gtkada_rm.info,  Node: Glib.Properties.Creation Subprograms,  Prev: Glib.Properties.Creation Types,  Up: Package_Glib.Properties.Creation

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

procedure Unref
       (Param              :        Param_Spec);

Decrement the reference counter. If it reaches 0, the memory is freed.
Enum classes
------------

gtk+, a C library, has a whole system to describe its enumeration types,
similar to what is available from the start in Ada ('Image and 'Value
for instance). All enumerations are represented internally as
Enum_Classes. However, there is no easy conversion between such an
enum class and a GtkAda enumeration type.   Most of the time, this has
no impact on your work, since you know  what type you need to use when
calling an Ada function. However, you  will need to manipulate these
enumeration classes when interfacing  with ParamSpecs and dealing with
properties.

function Get_Value
       (Klass              :        Enum_Class;
        Value              :        Glib.Gint)
        return Enum_Value;

Return the value in Klass that is Value (equivalent of 'Val in Ada)
function Nth_Value
       (Klass              :        Enum_Class;
        Nth                :        Glib.Guint)
        return Enum_Value;

Return the Nth-th value in Klass, or null if there is no such value.
function Value
       (Val                :        Enum_Value)
        return Glib.Gint;

Return the numeric value for a specific enumeration. Use the matching
Ada type and 'Val to convert it to a valid Ada enumeration
function Name
       (Val                :        Enum_Value)
        return String;

Return the name of Val. This is the equivalent of 'Image in Ada.
function Nick
       (Val                :        Enum_Value)
        return String;

Return a displayable string for Val.
function Register_Static_Enum
       (Name               :        String;
        Values             :        Interfaces.C.Strings.chars_ptr_array)
        return Glib.GType;

Create a new enumeration class from a list of valid values.
Values must be freed by the caller.
function Enum_Class_From_Type
       (Typ                :        Glib.GType)
        return Enum_Class;

Return the enumeration class corresponding to a type
Flags classes
-------------

These are very similar to Enum Classes. However, the actual value
of an instance of this type is a combination of a set of flags, rather
than one single enumeration value.   For instance, a Gdk_Event_Mask is
a Flags_Class

function Nth_Value
       (Klass              :        Flags_Class;
        Nth                :        Glib.Guint)
        return Flags_Value;

Return the Nth-th value in Klass, or null if there is no such value.
function Value
       (Val                :        Flags_Value)
        return Flags_Int_Value;

Return the numeric value for a specific enumeration. Use the matching
Ada type and 'Val to convert it to a valid Ada enumeration
function Name
       (Val                :        Flags_Value)
        return String;

Return the name of Val. This is the equivalent of 'Image in Ada.
function Nick
       (Val                :        Flags_Value)
        return String;

Return a displayable string for Val.
ParamSpec
---------

function Pspec_Name
       (Param              :        Param_Spec)
        return String;

Return the name of the property.
This is the internal string representing the property. It  Should
probably not be displayed on
function Nick_Name
       (Param              :        Param_Spec)
        return String;

Return the nickname of the property. This is a string
that can be displayed to represent the property, and is  more
user-friendly than the result of Name.
function Flags
       (Param              :        Param_Spec)
        return Param_Flags;

Return the flags for the property
function Description
       (Param              :        Param_Spec)
        return String;

Return the description (ie the help string) for Param
function Value_Type
       (Param              :        Param_Spec)
        return Glib.GType;

Return the type of param
procedure Set_Value_Type
       (Param              :        Param_Spec;
        Typ                :        Glib.GType);

Override the type of param. You should only use this function when
creating new Param_Spec types based on existing types. You should not
change the type if you haven't created param yourself.
function Get_Qdata
       (Param              :        Param_Spec;
        Quark              :        GQuark)
        return Glib.C_Proxy;

Return the user data set for Param
procedure Set_Qdata
       (Param              :        Param_Spec;
        Quark              :        GQuark;
        Data               :        Glib.C_Proxy;
        Destroy            :        G_Destroy_Notify := null);

Associate some named data with Param. Destroy is called when Param is
destroyed.
function Minimum
       (Param              :        Param_Spec_Char)
        return Glib.Gint8;

function Default
       (Param              :        Param_Spec_Char)
        return Glib.Gint8;

function Minimum
       (Param              :        Param_Spec_Uchar)
        return Glib.Guint8;

function Default
       (Param              :        Param_Spec_Uchar)
        return Glib.Guint8;

function Default
       (Param              :        Param_Spec_Boolean)
        return Boolean;

function Minimum
       (Param              :        Param_Spec_Int)
        return Glib.Gint;

function Default
       (Param              :        Param_Spec_Int)
        return Glib.Gint;

function Minimum
       (Param              :        Param_Spec_Uint)
        return Glib.Guint;

function Default
       (Param              :        Param_Spec_Uint)
        return Glib.Guint;

function Minimum
       (Param              :        Param_Spec_Long)
        return Glib.Glong;

function Default
       (Param              :        Param_Spec_Long)
        return Glib.Glong;

function Minimum
       (Param              :        Param_Spec_Ulong)
        return Glib.Gulong;

function Default
       (Param              :        Param_Spec_Ulong)
        return Glib.Gulong;

function Default
       (Param              :        Param_Spec_Unichar)
        return Gunichar;

function Enumeration
       (Param              :        Param_Spec_Enum)
        return Enum_Class;

function Gnew_Enum
       (Name, Nick, Blurb  :        String;
        Enum_Type          :        GType;
        Default            :        Gint := 0;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

See Glib.Properties.Creation.Register_Static_Enum on how to create
Enum_Type
function Flags_Enumeration
       (Param              :        Param_Spec_Flags)
        return Flags_Class;

function Gnew_Flags
       (Name, Nick, Blurb  :        String;
        Flags_Type         :        Glib.GType;
        Default            :        Guint;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Minimum
       (Param              :        Param_Spec_Float)
        return Gfloat;

function Default
       (Param              :        Param_Spec_Float)
        return Gfloat;

function Gnew_Float
       (Name, Nick, Blurb  :        String;
        Minimum, Maximum, Default  :        Glib.Gfloat;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Minimum
       (Param              :        Param_Spec_Double)
        return Gdouble;

function Default
       (Param              :        Param_Spec_Double)
        return Gdouble;

function Gnew_Double
       (Name, Nick, Blurb  :        String;
        Minimum, Maximum, Default  :        Glib.Gdouble;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Default
       (Param              :        Param_Spec_String)
        return String;

function Cset_Nth
       (Param              :        Param_Spec_String)
        return String;

function Ensure_Non_Null
       (Param              :        Param_Spec_String)
        return Boolean;

function Gnew_Param
       (Name, Nick, Blurb  :        String;
        Param_Type         :        Glib.GType;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Gnew_Boxed
       (Name, Nick, Blurb  :        String;
        Boxed_Type         :        Glib.GType;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Gnew_Pointer
       (Name, Nick, Blurb  :        String;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

function Gnew_Object
       (Name, Nick, Blurb  :        String;
        Object_Type        :        Glib.GType;
        Flags              :        Param_Flags
                            := Param_Readable or Param_Writable)
        return Param_Spec;

Creating new properties
-----------------------

There are several things that need to be done when creating a property.
For one thing, you need to create the string that represents the
property. This is the only item that needs to go in the specifications
of your page.   You then need to describe the type of the property, and
the values it  allows. This is very simple for simple types, and a
generic packages is  provided to handle the more complex
enumeration-based properties.

   Your widget needs to define two handlers, Set_Property_Handler and
Get_Property_Handler, that are called every time the user accesses the
value of a property through a call to Glib.Object.Set_Property or
Glib.Object.Get_Property.

   For efficiency reasons, a property is also associated with an integer
value, that you must provide when creating the property. This value is
completely free, and is passed to the two handlers described above.

   The two handlers manipulate Glib.Values.GValue values, so that they
can get and return various types.

procedure Set_Properties_Handlers
       (Class_Record       :        Glib.Object.GObject_Class;
        Set_Property       :        Set_Property_Handler;
        Get_Property       :        Get_Property_Handler);

Set the two functions used to set and retrieve properties. You
should never call this function on the class record of the standard
gtk+ widgets, since this will break their behavior. You should first
create a new class record through Initialize_Class_Record, and then
use the returned Class_Record as a parameter to this subprogram.

   You cannot pass null to either of the two parameters, or you won't
be able to install new properties afterwards
procedure Install_Property
       (Class_Record       :        Glib.Object.GObject_Class;
        Prop_Id            :        Property_Id;
        Property_Spec      :        Param_Spec);

Adds a new property to Class_Record. You should use this function only
on class records you have created yourself, not on one of the standard
widgets.   Prop_Id is the internal representation for properties, that
will be  passed to the Set_Property and Get_Property_Handlers (see
above) to set  and retrieve the value of a property.   Property_Spec
should be the result of one of the GNew_* subprograms for  Param_Spec,
and this defines the type of the property.

File: gtkada_rm.info,  Node: Package_Glib.Type_Conversion_Hooks,  Next: Package_Glib.Unicode,  Prev: Package_Glib.Properties.Creation,  Up: Top

Package Glib.Type`_'Conversion`_'Hooks
**************************************

This package provides an implementation for hooks used in
Gtk.Type_Conversion. These hooks should be used when you import a new
C GObject, so that GtkAda can recreate the Ada structure from the
underlying C structure.   Note that when you create a GObject directly
in Ada, you do not need to  provide any hook.

   Implementation note: This is a separate package from
Gtk.Type_Conversion  so that adding a hook does not necessarily mean
the user has to 'with'  Gtk.Type_Conversion, and thus all the packages
from GtkAda.

   Note that this package is not thread safe. You should call the
function Add_Hook from the elaboration part of your packages.

* Menu:

* Glib.Type_Conversion_Hooks Types::
* Glib.Type_Conversion_Hooks Subprograms::


File: gtkada_rm.info,  Node: Glib.Type_Conversion_Hooks Types,  Next: Glib.Type_Conversion_Hooks Subprograms,  Up: Package_Glib.Type_Conversion_Hooks

Types
=====

type File_Conversion_Hook_Type is access function
         (Type_Name : String) return Glib.Object.GObject;

This variable can be point to one of your functions.   It gets the name
of a C widget (ex/ "GtkButton") and should return  a newly allocated
Ada widget.
type Hook_List is record
         Func : File_Conversion_Hook_Type;
         Next : Hook_List_Access := null;
         end record;

Internal structure used for the list.
type Hook_List_Access is access Hook_List;



File: gtkada_rm.info,  Node: Glib.Type_Conversion_Hooks Subprograms,  Prev: Glib.Type_Conversion_Hooks Types,  Up: Package_Glib.Type_Conversion_Hooks

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

procedure Add_Hook
       (Func               :        File_Conversion_Hook_Type);

Add a new function to the list of hooks for file conversions.
All the hooks are called when GtkAda finds a type which is not one of
the standard types.
function Conversion_Hooks      return Hook_List_Access;


Return the head of the hook list.

File: gtkada_rm.info,  Node: Package_Glib.Unicode,  Next: Package_Glib.Values,  Prev: Package_Glib.Type_Conversion_Hooks,  Up: Top

Package Glib.Unicode
********************

This package provides functions for handling of unicode characters and
utf8 strings. See also Glib.Convert.

* Menu:

* Glib.Unicode Types::
* Glib.Unicode Subprograms::


File: gtkada_rm.info,  Node: Glib.Unicode Types,  Next: Glib.Unicode Subprograms,  Up: Package_Glib.Unicode

Types
=====

type G_Unicode_Type is
         (Unicode_Control,
          Unicode_Format,
          Unicode_Unassigned,
          Unicode_Private_Use,
          Unicode_Surrogate,
          Unicode_Lowercase_Letter,
          Unicode_Modifier_Letter,
          Unicode_Other_Letter,
          Unicode_Titlecase_Letter,
          Unicode_Uppercase_Letter,
          Unicode_Combining_Mark,
          Unicode_Enclosing_Mark,
          Unicode_Non_Spacing_Mark,
          Unicode_Decimal_Number,
          Unicode_Letter_Number,
          Unicode_Other_Number,
          Unicode_Connect_Punctuation,
          Unicode_Dash_Punctuation,
          Unicode_Close_Punctuation,
          Unicode_Final_Punctuation,
          Unicode_Initial_Punctuation,
          Unicode_Other_Punctuation,
          Unicode_Open_Punctuation,
          Unicode_Currency_Symbol,
          Unicode_Modifier_Symbol,
          Unicode_Math_Symbol,
          Unicode_Other_Symbol,
          Unicode_Line_Separator,
          Unicode_Paragraph_Separator,
          Unicode_Space_Separator);

The possible character classifications.   See
http://www.unicode.org/Public/UNIDATA/UnicodeData.html

File: gtkada_rm.info,  Node: Glib.Unicode Subprograms,  Prev: Glib.Unicode Types,  Up: Package_Glib.Unicode

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

procedure UTF8_Validate
       (Str                :        UTF8_String;
        Valid              : out    Boolean;
        Invalid_Pos        : out    Natural);

Validate a UTF8 string.
Set Valid to True if valid, set Invalid_Pos to first invalid byte.
Character classes
-----------------

function Is_Space
       (Char               :        Gunichar)
        return Boolean;

True if Char is a space character
function Is_Alnum
       (Char               :        Gunichar)
        return Boolean;

True if Char is an alphabetical or numerical character
function Is_Alpha
       (Char               :        Gunichar)
        return Boolean;

True if Char is an alphabetical character
function Is_Digit
       (Char               :        Gunichar)
        return Boolean;

True if Char is a digit
function Is_Lower
       (Char               :        Gunichar)
        return Boolean;

True if Char is a lower-case character
function Is_Upper
       (Char               :        Gunichar)
        return Boolean;

True if Char is an upper-case character
function Is_Punct
       (Char               :        Gunichar)
        return Boolean;

True if Char is a punctuation character
function Unichar_Type
       (Char               :        Gunichar)
        return G_Unicode_Type;

Return the unicode character type of a given character
Case handling
-------------

function To_Lower
       (Char               :        Gunichar)
        return Gunichar;

Convert Char to lower cases
function To_Upper
       (Char               :        Gunichar)
        return Gunichar;

Convert Char to upper cases
function UTF8_Strdown
       (Str                :        ICS.chars_ptr;
        Len                :        Integer)
        return ICS.chars_ptr;

function UTF8_Strdown
       (Str                :        UTF8_String)
        return UTF8_String;

Convert Str to lower cases
function UTF8_Strup
       (Str                :        ICS.chars_ptr;
        Len                :        Integer)
        return ICS.chars_ptr;

function UTF8_Strup
       (Str                :        UTF8_String)
        return UTF8_String;

Convert Str to upper cases
Manipulating strings
--------------------

function UTF8_Strlen
       (Str                :        ICS.chars_ptr;
        Max                :        Integer := -1)
        return Glong;

function UTF8_Strlen
       (Str                :        UTF8_String)
        return Glong;

Return the number of characters in Str
function UTF8_Find_Next_Char
       (Str                :        ICS.chars_ptr;
        Str_End            :        ICS.chars_ptr := ICS.Null_Ptr)
        return ICS.chars_ptr;

function UTF8_Find_Next_Char
       (Str                :        UTF8_String;
        Index              :        Natural)
        return Natural;

function UTF8_Next_Char
       (Str                :        UTF8_String;
        Index              :        Natural)
        return Natural;

function UTF8_Find_Prev_Char
       (Str_Start          :        ICS.chars_ptr;
        Str                :        ICS.chars_ptr)
        return ICS.chars_ptr;

function UTF8_Find_Prev_Char
       (Str                :        UTF8_String;
        Index              :        Natural)
        return Natural;

Find the start of the previous UTF8 character after the Index-th byte.
Index doesn't need to be on the start of a character.   Index is set to
a value smaller than Str'First if there is no  previous character.
Conversions
-----------

function Unichar_To_UTF8
       (C                  :        Gunichar;
        Buffer             :        ICS.chars_ptr := ICS.Null_Ptr)
        return Natural;

procedure Unichar_To_UTF8
       (C                  :        Gunichar;
        Buffer             : out    UTF8_String;
        Last               : out    Natural);

Encode C into Buffer. Buffer must have at least 6 bytes free.
Return the index of the last byte written in Buffer.
function UTF8_Get_Char
       (Str                :        UTF8_String)
        return Gunichar;

Converts a sequence of bytes encoded as UTF8 to a unicode character.
If Str doesn't point to a valid UTF8 encoded character, the result is
undefined.
function UTF8_Get_Char_Validated
       (Str                :        UTF8_String)
        return Gunichar;

Same as above. However, if the sequence if an incomplete start of a
possibly valid character, it returns -2. If the sequence is invalid,
returns -1.

File: gtkada_rm.info,  Node: Package_Glib.Values,  Next: Package_Glib.XML,  Prev: Package_Glib.Unicode,  Up: Top

Package Glib.Values
*******************

This package provides an interface to generic values as used in the
Glib object model.

   The main type in this package is GValues, which is the  equivalent
of the C's (GValue*) array, i.e an array of unions.  This  package
provides functions to extract the values from this type.

* Menu:


File: gtkada_rm.info,  Node: Package_Glib.XML,  Next: Package_Gtk,  Prev: Package_Glib.Values,  Up: Top

Package Glib.XML
****************

This package provides a simple minded XML parser to be used with  Gate.

* Menu:

* Glib.XML Types::
* Glib.XML Subprograms::


File: gtkada_rm.info,  Node: Glib.XML Types,  Next: Glib.XML Subprograms,  Up: Package_Glib.XML

Types
=====

type Free_Specific_Data is access procedure
         (Data : in out XML_Specific_Data);

type Node is record
         Tag   : String_Ptr;
           -- The name of this node. This is utf8-encoded
     
         Attributes   : String_Ptr;
           -- The attributes of this node. This is utf8-encoded
     
         Value : String_Ptr;
           -- The value, or null is not relevant. This is utf8-encoded
     
         Parent : Node_Ptr;
           -- The parent of this Node.
     
         Child : Node_Ptr;
           -- The first Child of this Node. The next child is Child.Next
     
         Next  : Node_Ptr;
           -- Next sibling node.
     
         Specific_Data : XML_Specific_Data;
           -- Use to store data specific to each implementation (e.g a boolean
           -- indicating whether this node has been accessed)
         end record;

A node of the XML tree.   Each time a tag is found in the XML file, a
new node is created, that  points to its parent, its children and its
siblings (nodes at the same  level in the tree and with the same
parent).
type Node_Ptr is access all Node;


Pointer to a node of the XML tree.
type XML_Specific_Data is private;


The type of the extra data that can be attached to each node of the
XML tree. See for instance the package Glib.Glade.

File: gtkada_rm.info,  Node: Glib.XML Subprograms,  Prev: Glib.XML Types,  Up: Package_Glib.XML

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

function Parse
       (File               :        String)
        return Node_Ptr;

Parse File and return the first node representing the XML file.
function Parse_Buffer
       (Buffer             :        UTF8_String)
        return Node_Ptr;

Parse a given Buffer in memory and return the first node representing
the XML contents.
procedure Print
       (N                  :        Node_Ptr;
        File_Name          :        String := "");

Write the tree starting with N into a file File_Name. The generated
file is valid XML, and can be parsed with the Parse function.   If
File_Name is the empty string, then the tree is printed on the
standard output
function Protect
       (S                  :        String)
        return String;

Return a copy of S modified so that it is a valid XML value
function Find_Tag
       (N                  :        Node_Ptr;
        Tag                :        UTF8_String)
        return Node_Ptr;

Find a tag Tag in N and its brothers.
function Get_Field
       (N                  :        Node_Ptr;
        Field              :        UTF8_String)
        return String_Ptr;

Return the value of the field 'Field' if present in the children of N.
Return null otherwise.   Do not free the returned value.
procedure Add_Child
       (N                  :        Node_Ptr;
        Child              :        Node_Ptr;
        Append             :        Boolean := False);

Add a new child to a node.
If Append is true, the child is added at the end of the current list of
children.
function Deep_Copy
       (N                  :        Node_Ptr)
        return Node_Ptr;

Return a deep copy of the tree starting with N. N can then be freed
without affecting the copy.
procedure Free
       (N                  : in out Node_Ptr;
        Free_Data          :        Free_Specific_Data := null);

Free the memory allocated for a node and its children.
It also disconnects N from its parent.   If Free_Data is not null, it
is used to free the memory occupied by  the Specific_Data for each node.
function Get_Attribute
       (N                  : in     Node_Ptr;
        Attribute_Name     : in     UTF8_String;
        Default            : in     UTF8_String := "")
        return UTF8_String;

Return the value of the attribute 'Attribute_Name' if present.
Return Default otherwise.
procedure Set_Attribute
       (N                  :        Node_Ptr;
        Attribute_Name, Attribute_Value  :        UTF8_String);

Create a new attribute, or replace an existing one
function Find_Tag_With_Attribute
       (N                  :        Node_Ptr;
        Tag                :        UTF8_String;
        Key                :        UTF8_String;
        Value              :        UTF8_String := "")
        return Node_Ptr;

Find a tag Tag in N that has a given key (and value if given).

File: gtkada_rm.info,  Node: Package_Gtkada,  Next: Package_Gtkada.Canvas,  Prev: Package_Gtk.Window,  Up: Top

Package Gtkada
**************

This is the parent package for the GtkAda specific units.

* Menu:


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

Package Gtkada.Canvas
*********************

This package provides an interactive canvas, on which the user can put
items, move them with the mouse, etc. The items can be connected
together,  and the connections remain active while the items are moved.

   It also supports scrolling if put in a Gtk_Scrolled_Window.   The
canvas will be scrolled (and the selected items moved) if an item is
selected and the mouse is dragged on a small area on the side of the
canvas  or even directly outside of the canvas. Scrolling will continue
until the  mouse is either released or moved back inside the canvas.

   The scrolling speed will slightly increase over time if the mouse is
kept  outside of the canvas. This makes the canvas much more
comfortable to use  for the user.

   All items put in this canvas must inherit from the type
Canvas_Item_Record.   However, it is your responsability, as a
programmer, to provide drawing  routines. In fact, all these items
should draw in a pixmap, which is then  copied automatically to the
screen whenever the canvas needs to redraw  itself.

   The items can also react to mouse events: mouse clicks are
transmitted to  the item if the mouse did not move more than a given
amount of pixels.   To decide what their reaction should be, you should
override the  On_Button_Click subprogram.

   This canvas is not intended for cases where you want to put hundreds
of  items on the screen. For instance, it does not provide any smart
double-buffering other than the one provided by gtk+ itself, and thus
you  would get some flicker if there are too many items.

   There are three coordinate systems used by widget. All the
subprograms  expect a specific coordinate system as input or output.
Here are the three  systems:
   * World coordinates      The position of an item is reported in
     pixels, as if the canvas      currently had a zoom level of 100%.
     This is fully independent, at any      time, from the current zoom
     level of the canvas.       Since the canvas is considered to
     expand ad infinitum, the top-left      corner doesn't have any
     specific fixed coordinates. It can be known by      checking the
     current lower value of the adjustments (aka scrollbars).

   * Canvas coordinates      This is similar to world coordinates,
     except these depend on the      current zoom level of the canvas.
     This also affect the width and height      of the objects in the
     canvas.       The subprograms To_Canvas_Coordinates and
     To_World_Coordinates can be      used to convert lengths from
     world to canvas coordinates.       The same behavior as world
     coordinates applies for the top-left corner.       All drawing to
     the screen, in particular for Draw_Background, must be      done
     using this coordinate systems

   * Item coordinates      The position of a point is relative to the
     top-left corner of the      current item. This corner therefore
     has coordinates (0, 0).       This coordinate systems assumes a
     zoom-level of 100%

    Items are selected automatically when they are clicked. If Control
is  pressed at the same time, multiple items can be selected.   If the
background is clicked (and control is not pressed), then all items  are
unselected.   Pressing and dragging the mouse in the backgroudn draws a
virtual box on  the screen. All the items fully included in this box
when it is released  will be selected (this will replace the current
selection if Control was  not pressed).

* Menu:

* Gtkada.Canvas Signals::
* Gtkada.Canvas Types::
* Gtkada.Canvas Subprograms::
* Gtkada.Canvas Example::


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

Signals
=======

   * "background_click"

     procedure Handler (Canvas : access Interactive_Canvas_Record'Class;
     Event  : Gdk.Event.Gdk_Event);
     Called every time the user clicks in the background (ie not on an
     item, or On_Button_Click would be called).  This is called both on
     Button_Release and Button_Press events.  The coordinates (X, Y) in
     the Event are relative to the top-left corner of Canvas.

   * "item_moved"

     procedure Handler (Canvas : access Interactive_Canvas_Record'Class;
     Item   : Canvas_Item);
     Emitted when Item has been moved. New coordinates have been
     assigned to Item. However, the canvas hasn't been refreshed yet.
     This signal might be called multiple time when the user finishes a
     drag action, in case there were several selected items.

   * "item_selected"

     procedure Handler (Canvas : access Interactive_Canvas_Record'Class;
     Item   : Canvas_Item);
     Emitted when the user has clicked on an item to select it, ie
     before any drag even has occured. This is a good time to add other
     items to the selection if you need. At thee same time, the
     primitive operation Selected is called for the item.

   * "item_unselected"

     procedure Handler (Canvas : access Interactive_Canvas_Record'Class;
     Item   : Canvas_Item);
     Emitted when the Item was unselected. At the same time, the
     primitive operation Selected is called for the item.

   * "zoomed"

     procedure Handler (Canvas : access
     Interactive_Canvas_Record'Class);
     Emitted when the canvas has been zoomed in or out. You do not need
     to redraw the items yourself, since this will be handled by calls
     to Draw



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

Types
=====

type Arrow_Type is
         (No_Arrow,
             -- the link does not have an arrow
     
          Start_Arrow,
             -- the link has an arrow at its beginning
     
          End_Arrow,
             -- the link has an arrow at the end
     
          Both_Arrow
             -- the link has an arrow on both sides
          );

Indicate whether the links have an arrow or not.
type Item_Iterator is private;


type Item_Processor is access function
         (Canvas : access Interactive_Canvas_Record'Class;

type Item_Side is
         (East, West, North, South);

Each side of an item, along its rectangle bounding box
type Layout_Algorithm is access procedure


type Link_Processor is access function
         (Canvas : access Interactive_Canvas_Record'Class;

type Selection_Iterator is private;


