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