1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  5. --                     Copyright (C) 1998-2014, AdaCore                     -- 
  6. --                                                                          -- 
  7. -- This library is free software;  you can redistribute it and/or modify it -- 
  8. -- under terms of the  GNU General Public License  as published by the Free -- 
  9. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  10. -- version. This library is distributed in the hope that it will be useful, -- 
  11. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  12. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  13. --                                                                          -- 
  14. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  15. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  16. -- version 3.1, as published by the Free Software Foundation.               -- 
  17. --                                                                          -- 
  18. -- You should have received a copy of the GNU General Public License and    -- 
  19. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  20. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  21. -- <http://www.gnu.org/licenses/>.                                          -- 
  22. --                                                                          -- 
  23. ------------------------------------------------------------------------------ 
  24.  
  25. --  <description> 
  26. -- 
  27. --  This package provides definitions for the basic types used in Glib, Cairo, 
  28. --  Gdk and Gtk. 
  29. -- 
  30. --  </description> 
  31. --  <group>Glib, the general-purpose library</group> 
  32.  
  33. with Ada.Unchecked_Deallocation; 
  34. with Ada.Unchecked_Conversion; 
  35. with System; 
  36. with Interfaces.C; 
  37.  
  38. package Glib is 
  39.    pragma Preelaborate; 
  40.  
  41.    package C renames Interfaces.C; 
  42.    use type C.int; 
  43.    use type C.unsigned; 
  44.  
  45.    ------------------------------------- 
  46.    -- The basic types defined by glib -- 
  47.    ------------------------------------- 
  48.  
  49.    type Gshort is new C.short; 
  50.    type Glong  is new C.long; 
  51.    type Gint   is new C.int; 
  52.    type Gchar  is new C.char; 
  53.    type Gboolean is new Gint; 
  54.  
  55.    type Gushort is new C.unsigned_short; 
  56.    type Gulong  is new C.unsigned_long; 
  57.    type Guint   is new C.unsigned; 
  58.    type Guchar  is new C.unsigned_char; 
  59.  
  60.    type Gfloat  is new C.C_float; 
  61.    type Gdouble is new C.double; 
  62.  
  63.    type Gint8  is range -(2 ** 7) .. (2 ** 7 - 1); 
  64.    type Gint16 is range -(2 ** 15) .. (2 ** 15 - 1); 
  65.    type Gint32 is range -(2 ** 31) .. (2 ** 31 - 1); 
  66.    type Gint64 is range -(2 ** 63) .. (2 ** 63 - 1); 
  67.  
  68.    type Guint8  is mod 2 ** 8; 
  69.    type Guint16 is mod 2 ** 16; 
  70.    type Guint32 is mod 2 ** 32; 
  71.    type Guint64 is mod 2 ** 64; 
  72.  
  73.    type Gsize is new C.size_t; 
  74.    type Gssize is 
  75.      range -(2 ** (C.size_t'Size - 1)) .. (2 ** (C.size_t'Size - 1) - 1); 
  76.  
  77.    type array_of_gsize is array (Natural range <>) of Gsize; 
  78.  
  79.    type Gunichar is new Guint32; 
  80.  
  81.    subtype UTF8_String is String; 
  82.    --  A string that accepts only valid UTF8 sequences. 
  83.    --  Most Gtk+ function expect valid UTF8 strings instead of regular strings. 
  84.  
  85.    type GTime_Val is record 
  86.       TV_Sec  : Glong; 
  87.       TV_Usec : Glong; 
  88.    end record; 
  89.    pragma Convention (C, GTime_Val); 
  90.  
  91.    type GTime_Val_Access is access all GTime_Val; 
  92.    pragma Convention (C, GTime_Val_Access); 
  93.  
  94.    subtype Grange_Float is Gdouble; 
  95.    --  Needed for better compatibility between GtkAda 1.2 and 2.0 
  96.  
  97.    subtype Gcolor_Int is Guint16; 
  98.    --  Provided for better compatibility between GtkAda 1.2 and 2.0 
  99.  
  100.    subtype Allocation_Int is Gint; 
  101.    --  Provided for better compatibility between GtkAda 1.2 and 2.0 
  102.  
  103.    ---------------------- 
  104.    -- Some Array types -- 
  105.    ---------------------- 
  106.  
  107.    type Gboolean_Array is array (Natural range <>) of Gboolean; 
  108.    type Gshort_Array   is array (Natural range <>) of Gshort; 
  109.    type Glong_Array    is array (Natural range <>) of Glong; 
  110.    type Gint_Array     is array (Natural range <>) of Gint; 
  111.    type Guint_Array    is array (Natural range <>) of Guint; 
  112.    type Guint32_Array  is array (Natural range <>) of Guint32; 
  113.    type Gushort_Array  is array (Natural range <>) of Gushort; 
  114.    type Gulong_Array   is array (Natural range <>) of Gulong; 
  115.    type Gfloat_Array   is array (Natural range <>) of Gfloat; 
  116.    type Guchar_Array   is array (Natural range <>) of Guchar; 
  117.    type Gdouble_Array  is array (Natural range <>) of Gdouble; 
  118.  
  119.    type Boolean_Array  is array (Natural range <>) of Boolean; 
  120.  
  121.    type Short_Array    is array (Natural range <>) of C.short; 
  122.    type Long_Array     is array (Natural range <>) of C.long; 
  123.  
  124.    ------------------------- 
  125.    -- Conversion services -- 
  126.    ------------------------- 
  127.  
  128.    function To_Boolean_Array (A : Gboolean_Array) return Boolean_Array; 
  129.    --  Convert a C-style boolean array into an Ada-style array. 
  130.  
  131.    function To_Gint (Bool : Boolean) return Gint; 
  132.    --  Convert an Ada boolean into a C int. 
  133.  
  134.    ----------------------- 
  135.    -- Some Access types -- 
  136.    ----------------------- 
  137.  
  138.    type Guchar_Array_Access is access Guchar_Array; 
  139.  
  140.    type String_Ptr is access all String; 
  141.  
  142.    --  <doc_ignore> 
  143.    procedure Free is new Ada.Unchecked_Deallocation 
  144.      (Object => Guchar_Array, Name => Guchar_Array_Access); 
  145.  
  146.    procedure Free is new Ada.Unchecked_Deallocation 
  147.      (Object => String, Name => String_Ptr); 
  148.    --  </doc_ignore> 
  149.  
  150.    --  <doc_ignore> 
  151.    type C_Dummy is limited private; 
  152.    --  </doc_ignore> 
  153.  
  154.    type C_Proxy is access all C_Dummy; 
  155.    pragma Convention (C, C_Proxy); 
  156.    --  General proxy for C structures. 
  157.    --  This type is used instead of System.Address so that the variables are 
  158.    --  automatically initialized to 'null'. 
  159.    --  The value pointed to is irrelevant, and in fact should not be accessed. 
  160.    --  It has thus been made limited private with no subprogram to access it. 
  161.    --  C_Proxy is a public type so that one can compare directly the value 
  162.    --  of the variables with 'null'. 
  163.  
  164.    type C_Boxed is tagged private; 
  165.    --  An opaque type that wraps a pointer to a C object. It is used instead of 
  166.    --  a C_Proxy in cases where we want to have a tagged type so that users can 
  167.    --  use the object-dotted notation when calling methods. 
  168.  
  169.    --  <doc_ignore> 
  170.    function To_Proxy is new Ada.Unchecked_Conversion (System.Address, C_Proxy); 
  171.    function To_Address is new 
  172.      Ada.Unchecked_Conversion (C_Proxy, System.Address); 
  173.    --  Converts from a System.Address returned by a C function to an 
  174.    --  internal C_Proxy. 
  175.  
  176.    function Get_Object (Self : C_Boxed'Class) return System.Address; 
  177.    procedure Set_Object (Self : in out C_Boxed'Class; Ptr : System.Address); 
  178.    pragma Inline (Get_Object, Set_Object); 
  179.    --  The internal C object. It should not be used directly by applications. 
  180.  
  181.    procedure g_free (A : System.Address); 
  182.    pragma Import (C, g_free, "g_free"); 
  183.    --  </doc_ignore> 
  184.  
  185.    function Is_Null (Self : C_Boxed'Class) return Boolean; 
  186.    pragma Inline (Is_Null); 
  187.    --  Whether the object has been initialized already. 
  188.  
  189.    type GApp_Info is new C_Proxy; 
  190.  
  191.    type G_Destroy_Notify_Address is 
  192.      access procedure (Data : System.Address); 
  193.    pragma Convention (C, G_Destroy_Notify_Address); 
  194.  
  195.    type G_Destroy_Notify is access procedure (Data : Glib.C_Proxy); 
  196.    pragma Convention (C, G_Destroy_Notify); 
  197.    --  Callback used when some named data associated with an object is 
  198.    --  destroyed. 
  199.  
  200.    ------------ 
  201.    -- Quarks -- 
  202.    ------------ 
  203.  
  204.    type GQuark is new Guint32; 
  205.    --  Represents a string internally in GtkAda. Once you know the 
  206.    --  equivalent for a string, you can always use it instead of the string, 
  207.    --  which provides a faster access for all the functions that use htables 
  208.    --  in GtkAda. 
  209.    --  There is a global htable that contains all the quarks defined in 
  210.    --  your application and GtkAda itself. 
  211.  
  212.    Unknown_Quark : constant GQuark := 0; 
  213.  
  214.    function Quark_From_String (Id : String) return GQuark; 
  215.    --  Return, or create the quark associated with the string. 
  216.    --  Note that if the quark does not already exist, an entry is created for 
  217.    --  it in the global htable for quarks. 
  218.  
  219.    function Quark_Try_String (Id : String) return GQuark; 
  220.    --  Return the quark associated with the string, if it exists. 
  221.    --  If it does not exist, return Unknown_Quark. 
  222.  
  223.    ------------- 
  224.    -- Signals -- 
  225.    ------------- 
  226.  
  227.    type Signal_Id is private; 
  228.    --  This uniquely identifies a connection widget<->signal. 
  229.  
  230.    type Signal_Name is new String; 
  231.    --  A signal name as used in connect, shared type between the Gtk 
  232.    --  and Glib layer. 
  233.  
  234.    Invalid_Signal_Id : constant Signal_Id; 
  235.    Null_Signal_Id : constant Signal_Id; 
  236.  
  237.    type G_Connect_Flags is mod 2 ** C.int'Size; 
  238.    G_Connect_After   : constant G_Connect_Flags := 2 ** 0; 
  239.    G_Connect_Swapped : constant G_Connect_Flags := 2 ** 1; 
  240.    --  Used to specify the behavior of a signal's connection. 
  241.  
  242.    ---------------- 
  243.    -- Properties -- 
  244.    ---------------- 
  245.    --  This is only the definition of the property types. See Glib.Properties 
  246.    --  on how to get and set the value of properties for specific objects, or 
  247.    --  the package Glib.Properties.Creation for information on how to create 
  248.    --  new properties in your own widgets. 
  249.    --  Introspection is available, ie from an existing object you can find out 
  250.    --  the list of properties it supports. See the functions 
  251.    --  Glib.Object.Interface_List_Properties and 
  252.    --  Glib.Object.Class_List_Properties 
  253.  
  254.    type Property (<>) is private; 
  255.  
  256.    function Build (Name : String) return Property; 
  257.    --  You should use this function only if you are creating new widgets, and 
  258.    --  their properties. Normal usage of properties doesn't require the use 
  259.    --  of this function. 
  260.    --  An ASCII.NUL character is automatically appended if necessary 
  261.  
  262.    function Property_Name (Prop : Property) return String; 
  263.    --  Return the name of the property. 
  264.    --  This name includes the trailing ASCII.Nul, and thus can be passed as is 
  265.    --  to C. 
  266.  
  267.    type Param_Spec is new Glib.C_Proxy; 
  268.    type Param_Spec_Array is array (Natural range <>) of Param_Spec; 
  269.    --  See Glib.Properties.Creation for more information on this type 
  270.  
  271.    type Param_Flags is mod 2 ** 6; 
  272.    Param_Readable       : constant Param_Flags := 2 ** 0; 
  273.    Param_Writable       : constant Param_Flags := 2 ** 1; 
  274.    Param_Construct      : constant Param_Flags := 2 ** 2; 
  275.    Param_Construct_Only : constant Param_Flags := 2 ** 3; 
  276.    Param_Lax_Validation : constant Param_Flags := 2 ** 4; 
  277.    Param_Private        : constant Param_Flags := 2 ** 5; 
  278.    --  These are the various flags that help define if, and when, a property 
  279.    --  can be read and modified. 
  280.  
  281.    ----------- 
  282.    -- GType -- 
  283.    ----------- 
  284.  
  285.    type GType is new Gsize; 
  286.    --  This type describes an internal type in Glib. 
  287.    --  You shouldn't have to use it in your own applications, however it might 
  288.    --  be useful sometimes. 
  289.    --  Every object type is associated with a specific value, created 
  290.    --  dynamically at run time the first time you instantiate an object of that 
  291.    --  type (thus if you have never used e.g a Gtk_File_Selection, it won't 
  292.    --  have any GType associated with it). 
  293.    --  You can get the exact type value for each type by using the functions 
  294.    --  Get_Type provided in all the packages in GtkAda. 
  295.    --  You can get the specific value for an existing widget by using the 
  296.    --  function Glib.Object.Get_Type. 
  297.  
  298.    type GType_Class is private; 
  299.    --  An opaque structure used as the base for all classes in glib and gtk+. 
  300.    --  See also Glib.Object.GObject_Class for a more useful child of this 
  301.    --  type. 
  302.  
  303.    type GType_Array is array (Guint range <>) of Glib.GType; 
  304.  
  305.    function Parent (Typ : GType) return GType; 
  306.    --  Return the parent type of Typ (eg if Typ is associated with a Gtk 
  307.    --  widget, it returns the typ of its parent). 
  308.  
  309.    function Fundamental (Typ : GType) return GType; 
  310.    --  Return the fundamental type for Type.  In gtk+, the types are organized 
  311.    --  into several hierarchies, similar to what is done for widgets. 
  312.    --  All of these hierarchies are based on one of the fundamental types 
  313.    --  defined below. 
  314.    --  This function returns that fundamental type. 
  315.    -- 
  316.    --  For instance, each enumeration type in gtk+ has its own GType. 
  317.    --  However, Fundamental will return GType_Enum in all of these cases. 
  318.  
  319.    function Type_Name (Type_Num : GType) return String; 
  320.    --  Return the name of the type (enumeration,...) associated with Typ. 
  321.    --  If Fundamental (Typ) return GType_Enum, this returns the name of 
  322.    --  the enumeration type that Typ represents. 
  323.    --  This might be useful in debug messages. 
  324.  
  325.    function Type_From_Name (Name : String) return GType; 
  326.    --  Convert a string to the matching type. 
  327.    --  Name should be the C GObject name rather than the Ada name: thus, 
  328.    --  use names such as GtkScrollbar or GtkButton for widgets. 
  329.  
  330.    function Get_Qdata (Typ : GType; Quark : GQuark) return Glib.C_Proxy; 
  331.    --  Return the user data set for Typ 
  332.  
  333.    procedure Set_Qdata 
  334.      (Typ     : GType; 
  335.       Quark   : GQuark; 
  336.       Data    : Glib.C_Proxy); 
  337.    --  Associate some named data with Typ. 
  338.  
  339.    --  The list of fundamental types defined in Glib. As opposed to most other 
  340.    --  types (for instance the ones used for widgets), the types have static 
  341.    --  values, always the same. 
  342.  
  343.    GType_Fundamental_Shift : constant Integer := 2; 
  344.  
  345.    GType_Invalid   : constant GType := 0 * (2 ** GType_Fundamental_Shift); 
  346.    GType_None      : constant GType := 1 * (2 ** GType_Fundamental_Shift); 
  347.    GType_Interface : constant GType := 2 * (2 ** GType_Fundamental_Shift); 
  348.  
  349.    GType_Char      : constant GType := 3 * (2 ** GType_Fundamental_Shift); 
  350.    GType_Uchar     : constant GType := 4 * (2 ** GType_Fundamental_Shift); 
  351.    GType_Boolean   : constant GType := 5 * (2 ** GType_Fundamental_Shift); 
  352.    GType_Int       : constant GType := 6 * (2 ** GType_Fundamental_Shift); 
  353.    GType_Uint      : constant GType := 7 * (2 ** GType_Fundamental_Shift); 
  354.    GType_Long      : constant GType := 8 * (2 ** GType_Fundamental_Shift); 
  355.    GType_Ulong     : constant GType := 9 * (2 ** GType_Fundamental_Shift); 
  356.    GType_Int64     : constant GType := 10 * (2 ** GType_Fundamental_Shift); 
  357.    GType_UInt64    : constant GType := 11 * (2 ** GType_Fundamental_Shift); 
  358.    GType_Enum      : constant GType := 12 * (2 ** GType_Fundamental_Shift); 
  359.    GType_Flags     : constant GType := 13 * (2 ** GType_Fundamental_Shift); 
  360.    GType_Float     : constant GType := 14 * (2 ** GType_Fundamental_Shift); 
  361.    GType_Double    : constant GType := 15 * (2 ** GType_Fundamental_Shift); 
  362.    GType_String    : constant GType := 16 * (2 ** GType_Fundamental_Shift); 
  363.    --  Null terminated string. 
  364.  
  365.    GType_Pointer   : constant GType := 17 * (2 ** GType_Fundamental_Shift); 
  366.    --  A general pointer type. 
  367.  
  368.    GType_Param     : constant GType := 19 * (2 ** GType_Fundamental_Shift); 
  369.    GType_Object    : constant GType := 20 * (2 ** GType_Fundamental_Shift); 
  370.    --  One of the widgets/objects 
  371.  
  372.    ----------------- 
  373.    -- Boxed types -- 
  374.    ----------------- 
  375.    --  Boxed types are a convenient way to encapsulate Ada types through a C 
  376.    --  layer. An initialization and a finalization function can be provided. 
  377.    --  The most frequent usage of such types is in argument to signals and 
  378.    --  handlers (See the functions in Glib.Values), or to store such types 
  379.    --  in a Gtk_Tree_Model. This allows you for instance to store reference 
  380.    --  counted types where you want to be able to control what should happen 
  381.    --  when the cell is removed from the tree. 
  382.    -- 
  383.    --  See an example with the subprogram Glib.Values.Set_Boxed 
  384.  
  385.    GType_Boxed     : constant GType := 18 * (2 ** GType_Fundamental_Shift); 
  386.    --  The base type for all boxed types. In tree models, you should use the 
  387.    --  actual type returned by Boxed_Type_Register_Static. 
  388.  
  389.    type Boxed_Copy is access 
  390.       function (Boxed : System.Address) return System.Address; 
  391.    pragma Convention (C, Boxed_Copy); 
  392.    type Boxed_Free is access procedure (Boxed : System.Address); 
  393.    pragma Convention (C, Boxed_Free); 
  394.  
  395.    function Boxed_Type_Register_Static 
  396.      (Name : String; 
  397.       Copy : Boxed_Copy; 
  398.       Free : Boxed_Free) return GType; 
  399.    --  Create a new boxed type 
  400.  
  401. private 
  402.    type C_Dummy is record 
  403.       Dummy1 : System.Address; 
  404.    end record; 
  405.    pragma Convention (C, C_Dummy); 
  406.    --  This array can contain anything, since it is never used on the Ada side 
  407.    --  anyway. Pretend it contains an address so that the compiler a 
  408.    --  reasonable default alignment, compatible with most types. 
  409.  
  410.    type GType_Class is new System.Address; 
  411.  
  412.    type C_Boxed is tagged record 
  413.       Ptr : System.Address := System.Null_Address; 
  414.    end record; 
  415.  
  416.    type Property is new String; 
  417.  
  418.    type Signal_Id is new Guint; 
  419.    Invalid_Signal_Id : constant Signal_Id := -1; 
  420.    Null_Signal_Id : constant Signal_Id := 0; 
  421.  
  422.    pragma Import (C, Fundamental, "ada_gtype_fundamental"); 
  423.    pragma Import (C, Parent, "g_type_parent"); 
  424.    pragma Import (C, Get_Qdata, "g_type_get_qdata"); 
  425.    pragma Import (C, Set_Qdata, "g_type_set_qdata"); 
  426.    pragma Inline (Build); 
  427.  
  428. end Glib;