1------------------------------------------------------------------------------ 2-- GtkAda - Ada95 binding for Gtk+/Gnome -- 3-- -- 4-- Copyright (C) 2001-2015, AdaCore -- 5-- -- 6-- This library is free software; you can redistribute it and/or modify it -- 7-- under terms of the GNU General Public License as published by the Free -- 8-- Software Foundation; either version 3, or (at your option) any later -- 9-- version. This library is distributed in the hope that it will be useful, -- 10-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- -- 11-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. -- 12-- -- 13-- As a special exception under Section 7 of GPL version 3, you are granted -- 14-- additional permissions described in the GCC Runtime Library Exception, -- 15-- version 3.1, as published by the Free Software Foundation. -- 16-- -- 17-- You should have received a copy of the GNU General Public License and -- 18-- a copy of the GCC Runtime Library Exception along with this program; -- 19-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- 20-- <http://www.gnu.org/licenses/>. -- 21-- -- 22------------------------------------------------------------------------------ 23 24-- <description> 25-- This package provides an interface to generic values as used in the 26-- Glib object model. 27-- 28-- The main type in this package is GValues, which is the 29-- equivalent of the C's (GValue*) array, i.e an array of unions. This 30-- package provides functions to extract the values from this type. 31-- </description> 32-- <c_version>1.3.15</c_version> 33-- <group>Glib, the general-purpose library</group> 34 35with System; 36with Interfaces.C.Strings; 37 38with Glib.Object; 39 40package Glib.Values is 41 42 -- <doc_ignore>Do not create automatic documentation for this package 43 44 type GValue is private; 45 -- A generic value that can hold any of the types as provided in the 46 -- Set and Get functions below. 47 48 type GValues is private; 49 -- This type represents a table of values. Each argument of the 50 -- table can be of any type. 51 -- The index of the first element is always 1. 52 53 type C_GValues is new System.Address; 54 -- An array of GValues 55 56 type GValue_Array is array (Gint range <>) of GValue; 57 58 function Make_Values (Nb : Guint) return GValues; 59 -- Create a new GValues structure from scratch. This procedure 60 -- causes the allocation of an underlying C array, and this memory 61 -- should be deallocated after use using procedure Free (see below). 62 63 function Make_Values (Nb : Guint; Val : C_GValues) return GValues; 64 -- Build a GValues structure from the given C array. Nb should be the 65 -- number of elements in the Values array. 66 67 procedure Free (Val : in out GValues); 68 -- Deallocate the memory associated with the given Values array. 69 70 function Nth (Val : GValues; Num : Guint) return GValue; 71 -- Return the Num-th element from Values. 72 -- In general, the returned value does not need to be unset, since it is 73 -- still handled by C (in particular when processing the parameters for a 74 -- callback). 75 76 -- <doc_ignore> 77 78 procedure Unsafe_Nth (Values : C_GValues; Num : Guint; V : in out GValue); 79 pragma Import (C, Unsafe_Nth, "ada_gvalue_nth"); 80 -- This returns the Num-th element, starting at 0. This procedure does 81 -- not check that Values contains at least Num elements, so is potentially 82 -- dangerous. 83 -- In general, the returned value does not need to be unset, since it is 84 -- still handled by C (in particular when processing the parameters for a 85 -- callback). 86 87 generic 88 type T is private; 89 function Unsafe_Proxy_Nth (Values : C_GValues; Num : Guint) return T; 90 pragma Inline (Unsafe_Proxy_Nth); 91 -- Extract a point from Values (at index Num, 0-based), and convert it to 92 -- T. This is unsafe because no check is made that Num is a valid index, 93 -- and no check is made that casting to T makes sense. 94 95 generic 96 type T is (<>); 97 function Unsafe_Enum_Nth 98 (Values : C_GValues; Num : Guint) return T; 99 pragma Inline (Unsafe_Enum_Nth); 100 -- Used for enumeration types 101 102 -- </doc_ignore> 103 104 ------------------------------------------------- 105 -- Conversion functions, interfacing to GValue -- 106 ------------------------------------------------- 107 108 procedure Init (Value : in out GValue; G_Type : Glib.GType); 109 -- Set the type of Value to G_Type. This limits the operations you can then 110 -- apply to Value. For instance, Value must have been initialized with 111 -- a GType_Int before you can use Set_Int (see below). 112 -- Note that for enumeration types, you shouldn't use GType_Enum, but 113 -- rather the exact GType corresponding to the enumeration. 114 -- If you need to store a reference-counted type in a GValue, it is 115 -- recommanded that you use a type derived from Boxed (see Set_Boxed below) 116 117 procedure Unset (Value : in out GValue); 118 -- Frees the memory allocate for Value (like strings contents) in the call 119 -- to Init. You only need to call this function in cases where you have 120 -- called Init yourself. 121 122 function Type_Of (Value : GValue) return Glib.GType; 123 pragma Inline (Type_Of); 124 -- Return the type of data that Value contains. 125 -- It returns GType_Invalid if Value was not initialized 126 127 procedure Set_Char (Value : in out GValue; V_Char : Gchar); 128 function Get_Char (Value : GValue) return Gchar; 129 130 procedure Set_Uchar (Value : in out GValue; V_Uchar : Guchar); 131 function Get_Uchar (Value : GValue) return Guchar; 132 133 procedure Init_Set_Boolean (Value : in out GValue; V : Boolean); 134 procedure Set_Boolean (Value : in out GValue; V_Boolean : Boolean); 135 function Get_Boolean (Value : GValue) return Boolean; 136 -- Set_Boolean must only be called when Init has already been used. 137 -- Otherwise use Init_Set_Boolean. 138 139 procedure Init_Set_Int (Value : in out GValue; V : Gint); 140 procedure Set_Int (Value : in out GValue; V_Int : Gint); 141 function Get_Int (Value : GValue) return Gint; 142 -- Set_Int must only be called when Init has already been used. 143 -- Otherwise use Init_Set_Int. 144 145 procedure Init_Set_Uint (Value : in out GValue; V : Guint); 146 procedure Set_Uint (Value : in out GValue; V_Uint : Guint); 147 function Get_Uint (Value : GValue) return Guint; 148 149 procedure Set_Long (Value : in out GValue; V_Long : Glong); 150 function Get_Long (Value : GValue) return Glong; 151 152 procedure Set_Ulong (Value : in out GValue; V_Ulong : Gulong); 153 function Get_Ulong (Value : GValue) return Gulong; 154 155 procedure Set_Float (Value : in out GValue; V_Float : Gfloat); 156 function Get_Float (Value : GValue) return Gfloat; 157 158 procedure Set_Double (Value : in out GValue; V_Double : Gdouble); 159 function Get_Double (Value : GValue) return Gdouble; 160 161 procedure Init_Set_String (Value : in out GValue; V : String); 162 procedure Set_String (Value : in out GValue; V_String : String); 163 function Get_String (Value : GValue) return String; 164 function Get_String (Value : GValue; Length : Gint) return String; 165 166 function Get_Chars (Value : GValue) return Interfaces.C.Strings.chars_ptr; 167 168 procedure Set_Proxy (Value : in out GValue; V_Proxy : C_Proxy); 169 function Get_Proxy (Value : GValue) return C_Proxy; 170 171 procedure Set_Address (Value : in out GValue; V_Address : System.Address); 172 function Get_Address (Value : GValue) return System.Address; 173 174 procedure Set_Boxed (Value : in out GValue; V_Address : System.Address); 175 function Get_Boxed (Value : GValue) return System.Address; 176 -- This is similar to Set_Address and Get_Address, except that the boxed 177 -- type might have been associated with some specific initialization and 178 -- finalization functions through Glib.Boxed_Type_Register_Static 179 -- For instance: 180 -- declare 181 -- Typ : Glib.GType; 182 -- Value : GValue; 183 -- function To_Ref_Counted_Value is new Ada.Unchecked_Conversion 184 -- (System.Address, My_Ref_Counted_Type); 185 -- begin 186 -- Typ := Boxed_Typed_Register_Static 187 -- ("FOO", Copy'Access, Free'Access); 188 -- Init (Value, Typ); 189 -- Set_Boxed (Value, my_ref_counted_value.all'address); 190 -- 191 -- Val := To_Ref_Counted_Value (Get_Boxed (Value)); 192 -- Unset (Value); 193 -- end; 194 -- 195 -- See also Glib.Generic_Properties.Generic_Internal_Boxed_Property. 196 197 procedure Set_Enum (Value : in out GValue; V_Enum : Gint); 198 function Get_Enum (Value : GValue) return Glib.Gint; 199 -- These are used to manipulate the standard GtkAda enumeration types. 200 -- For types that you have redefined yourself, you have access to more 201 -- suitable functions directly in the package Generic_Enumeration_Property. 202 203 procedure Set_Flags (Value : in out GValue; V_Enum : Guint); 204 function Get_Flags (Value : GValue) return Glib.Guint; 205 -- ??? Should really manipulate Glib.Properties.Creation.Flags_Int_Value 206 207 procedure Set_Object 208 (Value : in out GValue; To : access Glib.Object.GObject_Record'Class); 209 function Get_Object (Value : GValue) return Glib.Object.GObject; 210 -- These are used to manipulate GObject instances. 211 212 -- Convenience function to Get and Set a Gtk_Text_Iter are 213 -- also provided inside Gtk.Text_Iter. 214 215private 216 type GValue_Data is array (1 .. 2) of Guint64; 217 type GValue is record 218 g_type : GType := GType_Invalid; 219 data : GValue_Data; 220 end record; 221 pragma Convention (C, GValue); 222 223 type GValues is record 224 Nb : Guint; 225 Arr : C_GValues; 226 end record; 227 228 pragma Import (C, Set_Char, "g_value_set_char"); 229 pragma Import (C, Get_Char, "g_value_get_char"); 230 pragma Import (C, Set_Uchar, "g_value_set_uchar"); 231 pragma Import (C, Get_Uchar, "g_value_get_uchar"); 232 pragma Import (C, Set_Int, "g_value_set_int"); 233 pragma Import (C, Get_Int, "g_value_get_int"); 234 pragma Import (C, Set_Uint, "g_value_set_uint"); 235 pragma Import (C, Get_Uint, "g_value_get_uint"); 236 pragma Import (C, Set_Long, "g_value_set_long"); 237 pragma Import (C, Get_Long, "g_value_get_long"); 238 pragma Import (C, Set_Ulong, "g_value_set_ulong"); 239 pragma Import (C, Get_Ulong, "g_value_get_ulong"); 240 pragma Import (C, Set_Float, "g_value_set_float"); 241 pragma Import (C, Get_Float, "g_value_get_float"); 242 pragma Import (C, Set_Double, "g_value_set_double"); 243 pragma Import (C, Get_Double, "g_value_get_double"); 244 pragma Import (C, Set_Proxy, "g_value_set_pointer"); 245 pragma Import (C, Set_Address, "g_value_set_pointer"); 246 pragma Import (C, Set_Enum, "g_value_set_enum"); 247 pragma Import (C, Get_Enum, "g_value_get_enum"); 248 pragma Import (C, Get_Chars, "g_value_get_string"); 249 pragma Import (C, Set_Flags, "g_value_set_flags"); 250 pragma Import (C, Get_Flags, "g_value_get_flags"); 251 pragma Import (C, Set_Boxed, "g_value_set_boxed"); 252 pragma Import (C, Get_Boxed, "g_value_get_boxed"); 253 pragma Import (C, Unset, "g_value_unset"); 254 255 -- ??? We use our own version here, that doesn't check the type of 256 -- GValue. This is used for signals (Gtk.Handlers), but should be 257 -- cleaned up. 258 pragma Import (C, Get_Address, "ada_gvalue_get_pointer"); 259 pragma Import (C, Get_Proxy, "ada_gvalue_get_pointer"); 260 261 pragma Inline (Make_Values); 262 pragma Inline (Set_Boolean); 263 pragma Inline (Get_Boolean); 264 pragma Inline (Set_String); 265 pragma Inline (Get_String); 266 267 -- </doc_ignore> 268end Glib.Values; 269