1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --                     Copyright (C) 2001-2014, 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. --  Note: this package need only be used and understood by people who 
  26. --  want to create their own new widgets and their associated properties. 
  27. --  Normal usage of properties doesn't require any deep understanding of 
  28. --  this package. 
  29. -- 
  30. --  This package provides two generic subpackages that make it easy to 
  31. --  declare properties. 
  32. --  Each of these packages define two types: 
  33. -- 
  34. --  - Property_RO : this type should be used for a read-only property 
  35. --                  of the given type. 
  36. --  - Property    : This is for read-write properties 
  37. -- 
  38. --  Each of these two types is associated with one or two primitive 
  39. --  operations Get_Property and Set_Property, that allows the modification 
  40. --  of properties of this type. 
  41. -- 
  42. --  As a user and creator of new widgets, you should always use the 
  43. --  Generic_Enumeration_Property package, since it also registers the 
  44. --  enumeration type with gtk+ for a full compatibility with C. 
  45. --  </description> 
  46. --  <group>Glib, the general-purpose library</group> 
  47.  
  48. with Glib.Object; 
  49. with Glib.Values; 
  50.  
  51. package Glib.Generic_Properties is 
  52.  
  53.    -------------------------------------------------- 
  54.    -- Generic package for discrete type properties -- 
  55.    -------------------------------------------------- 
  56.    --  This package should be used to implement the 
  57.    --  Get_Property and Set_Property subprograms for all 
  58.    --  properties related to enumeration types and simple 
  59.    --  types. 
  60.    --  This should be used only for types defined in GtkAda 
  61.    --  or gtk+ themselves, not for types that you define 
  62.    --  yourself. Use Generic_Discrete_Type instead. 
  63.  
  64.    generic 
  65.       type Discrete_Type is (<>); 
  66.    package Generic_Internal_Discrete_Property is 
  67.       type Property_RO is new Glib.Property; 
  68.       type Property is new Glib.Property; 
  69.  
  70.       procedure Set_Property 
  71.         (Object : access Glib.Object.GObject_Record'Class; 
  72.          Name   : Property; 
  73.          Value  : Discrete_Type); 
  74.       --  Set a property of Object based on Enumeration_Type. 
  75.  
  76.       function Get_Property 
  77.         (Object : access Glib.Object.GObject_Record'Class; 
  78.          Name   : Property) return Discrete_Type; 
  79.       pragma Inline (Get_Property); 
  80.  
  81.       function Get_Property 
  82.         (Object : access Glib.Object.GObject_Record'Class; 
  83.          Name   : Property_RO) return Discrete_Type; 
  84.       --  Get a property from Object 
  85.  
  86.    end Generic_Internal_Discrete_Property; 
  87.  
  88.    ------------------------------------------------- 
  89.    -- Generic package for enumerations properties -- 
  90.    ------------------------------------------------- 
  91.    --  This package should be used to implement the 
  92.    --  Get_Property and Set_Property subprograms for all 
  93.    --  properties related to enumeration types and simple 
  94.    --  types in users' applications. 
  95.    --  Name is the name registered in gtk+ for the type. This is also 
  96.    --  the name that appears in all the tools that use introspection 
  97.    --  to get information about the widgets and their properties, like 
  98.    --  GUI builders for instance 
  99.    -- 
  100.    --  !!IMPORTANT!!: For proper usage of properties based on enumeration 
  101.    --  types, you must specify the Convention C on the type: 
  102.    --      pragma Convention (C, Enumeration_Type); 
  103.  
  104.    generic 
  105.       Name : String; 
  106.       type Enumeration is (<>); 
  107.    package Generic_Enumeration_Property is 
  108.  
  109.       ----------------- 
  110.       --  Properties -- 
  111.       ----------------- 
  112.  
  113.       package Properties is new Generic_Internal_Discrete_Property 
  114.         (Enumeration); 
  115.       type Property_RO is new Properties.Property_RO; 
  116.       type Property    is new Properties.Property; 
  117.  
  118.       ----------- 
  119.       -- Types -- 
  120.       ----------- 
  121.  
  122.       function Get_Type return Glib.GType; 
  123.       --  Return the internal gtk+ type associated with the Ada enumeration 
  124.       --  Enumeration. You don't need to use such a function for the types 
  125.       --  defined in standard in GtkAda. Use Glib.Type_From_Name 
  126.       --  instead. 
  127.  
  128.       function Gnew_Enum 
  129.         (Name, Nick, Blurb   : String; 
  130.          Default             : Enumeration := Enumeration'First; 
  131.          Flags : Param_Flags := Param_Readable or Param_Writable) 
  132.          return Param_Spec; 
  133.       --  Create a new param_spec (to describe properties), based on the 
  134.       --  Ada enumeration type Enumeration. This function is used when 
  135.       --  creating the property with Install_Property on an object. 
  136.       --  Name, Nick and Blurb should describe the property, not its type. 
  137.  
  138.       ------------ 
  139.       -- Values -- 
  140.       ------------ 
  141.  
  142.       function Get_Enum (Value : Glib.Values.GValue) return Enumeration; 
  143.       --  Return the enumeration contained in Value, assuming it is of type 
  144.       --  Enumeration 
  145.  
  146.       procedure Set_Enum 
  147.         (Value : in out Glib.Values.GValue; Enum : Enumeration); 
  148.       --  Set the enumeration value for Value. This properly initializes the 
  149.       --  type of Value, so you don't need to call Init yourself. 
  150.  
  151.    private 
  152.       The_Type : Glib.GType := Glib.GType_Invalid; 
  153.       pragma Import (C, Get_Enum, "g_value_get_enum"); 
  154.    end Generic_Enumeration_Property; 
  155.  
  156.    ------------------------------------------------- 
  157.    -- Generic package for record types properties -- 
  158.    ------------------------------------------------- 
  159.    --  This package should be used to implement the 
  160.    --  Get_Property and Set_Property subprograms for all 
  161.    --  properties related to record type, like Gdk_Color and 
  162.    --  Gdk_Rectangle. 
  163.    --  This should be used only for types defined in GtkAda 
  164.    --  or gtk+ themselves, not for types that you define 
  165.    --  yourself. 
  166.  
  167.    generic 
  168.       type Boxed_Type is private; 
  169.       with function Get_Type return Glib.GType; 
  170.  
  171.       with function To_Address 
  172.         (B : Boxed_Type; Default : System.Address) return System.Address; 
  173.       --  Convert B into an address that can be passed to gtk+. 
  174.       --  Default is the address of the parameters passed by the user (since 
  175.       --  this function cannot return B'Address, where B might be passed by 
  176.       --  copy). 
  177.  
  178.    package Generic_Internal_Boxed_Property is 
  179.       type Property_RO is new Glib.Property; 
  180.       type Property    is new Glib.Property; 
  181.  
  182.       procedure Set_Property 
  183.         (Object : access Glib.Object.GObject_Record'Class; 
  184.          Name   : Property; 
  185.          Value  : Boxed_Type); 
  186.       --  Set a property of Object based on Enumeration_Type. 
  187.  
  188.       function Get_Property 
  189.         (Object : access Glib.Object.GObject_Record'Class; 
  190.          Name   : Property) return Boxed_Type; 
  191.       pragma Inline (Get_Property); 
  192.  
  193.       function Get_Property 
  194.         (Object : access Glib.Object.GObject_Record'Class; 
  195.          Name   : Property_RO) return Boxed_Type; 
  196.       --  Get a property from Object. 
  197.       --  Unset_Value is raised if the property is not set 
  198.  
  199.       procedure Set_Value 
  200.         (Value  : out Glib.Values.GValue; 
  201.          Val    : Boxed_Type); 
  202.       --  Store Val in Value. The latter is properly initialized, and reference 
  203.       --  counting is handled automatically. You must Unset Value when you are 
  204.       --  done using it. 
  205.  
  206.       function Get_Value (Value : Glib.Values.GValue) return Boxed_Type; 
  207.       --  Get the value stored in Value. Reference counting is automatically 
  208.       --  handled, and the returned value has been properly referenced. 
  209.       --  Unset_Value is raised if Value contains no data 
  210.  
  211.    end Generic_Internal_Boxed_Property; 
  212.  
  213.    Unset_Value : exception; 
  214.  
  215. end Glib.Generic_Properties;