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. -- 
  26. --  This package provides all the required subprograms to create and 
  27. --  manipulate new properties associated with new widget types. 
  28. -- 
  29. --  You do not have to be familiar with this package in order to use 
  30. --  properties. See Glib.Object instead, that provides the minimal 
  31. --  subprograms to get and set properties. 
  32. -- 
  33. --  This package is only intended for writers of new widgets. You will need 
  34. --  this function to create new properties. 
  35. -- 
  36. --  Each object in gtk+ has a set of so-called properties. These are 
  37. --  attributes that can be accessed, and possibly modified, by names. 
  38. --  They provide introspection, that is an object can specify which 
  39. --  properties it knows about, which can be modified,..., and thus provide a 
  40. --  huge support for special applications like GUI-Builders that need to act 
  41. --  on any kind of widgets, even those it doesn't know about yet. 
  42. -- 
  43. --  However, for efficiency reasons, the properties are only names, and are 
  44. --  not the only way to modify attributes of objects. It is often more 
  45. --  efficient to use the alternate method, as documented in the GtkAda 
  46. --  documentation for each property. 
  47. -- 
  48. --  Another interesting feature of properties is that every time a property 
  49. --  is modified, a signal "property_changed" or "notify" is emitted, and 
  50. --  it is thus easy to keep track of attributes in objects. 
  51. -- 
  52. --  </description> 
  53. --  <group>Glib, the general-purpose library</group> 
  54.  
  55. with Glib.Object; 
  56. with Glib.Values; 
  57. with Interfaces.C.Strings; 
  58.  
  59. package Glib.Properties.Creation is 
  60.  
  61.    --  subtype Param_Spec is Glib.Param_Spec; 
  62.  
  63.    --  This type is the internal representation for properties. It contains all 
  64.    --  the required information about it, including some help string or the 
  65.    --  range of values it recognizes. 
  66.    -- 
  67.    --  All the values contained in a param_spec are typed. However, since these 
  68.    --  are not implemented as tagged types, it is your responsability to 
  69.    --  convert the param_specs to the appropriate type, based on the value 
  70.    --  returned by Value_Type. Most of the time, you won't need to use these 
  71.    --  functions at all, unless you are programming some self-inspection 
  72.    --  application, like a GUI-Builder for instance, or creating new properties 
  73.    --  for a new widget. 
  74.  
  75.    procedure Unref (Param : Param_Spec); 
  76.    --  Decrement the reference counter. If it reaches 0, the memory is freed. 
  77.  
  78.    ------------------ 
  79.    -- Enum classes -- 
  80.    ------------------ 
  81.    --  gtk+, a C library, has a whole system to describe its enumeration types, 
  82.    --  similar to what is available from the start in Ada ('Image and 'Value 
  83.    --  for instance). All enumerations are represented internally as 
  84.    --  Enum_Classes. However, there is no easy conversion between such an 
  85.    --  enum class and a GtkAda enumeration type. 
  86.    --  Most of the time, this has no impact on your work, since you know 
  87.    --  what type you need to use when calling an Ada function. However, you 
  88.    --  will need to manipulate these enumeration classes when interfacing 
  89.    --  with ParamSpecs and dealing with properties. 
  90.  
  91.    type Enum_Class is new Glib.C_Proxy; 
  92.    type Enum_Value is new Glib.C_Proxy; 
  93.  
  94.    function Get_Value (Klass : Enum_Class; Value : Glib.Gint) 
  95.       return Enum_Value; 
  96.    --  Return the value in Klass that is Value (equivalent of 'Val in Ada) 
  97.  
  98.    function Nth_Value (Klass : Enum_Class; Nth : Glib.Guint) return Enum_Value; 
  99.    --  Return the Nth-th value in Klass, or null if there is no such value. 
  100.  
  101.    function Value (Val : Enum_Value) return Glib.Gint; 
  102.    --  Return the numeric value for a specific enumeration. Use the matching 
  103.    --  Ada type and 'Val to convert it to a valid Ada enumeration 
  104.  
  105.    function Name (Val : Enum_Value) return String; 
  106.    --  Return the name of Val. This is the equivalent of 'Image in Ada. 
  107.  
  108.    function Nick (Val : Enum_Value) return String; 
  109.    --  Return a displayable string for Val. 
  110.  
  111.    function Register_Static_Enum 
  112.      (Name   : String; 
  113.       Values : Interfaces.C.Strings.chars_ptr_array) return Glib.GType; 
  114.    --  Create a new enumeration class from a list of valid values. 
  115.    --  Values must be freed by the caller. 
  116.  
  117.    function Enum_Class_From_Type (Typ : Glib.GType) return Enum_Class; 
  118.    --  Return the enumeration class corresponding to a type 
  119.  
  120.    ------------------- 
  121.    -- Flags classes -- 
  122.    ------------------- 
  123.    --  These are very similar to Enum Classes. However, the actual value 
  124.    --  of an instance of this type is a combination of a set of flags, rather 
  125.    --  than one single enumeration value. 
  126.    --  For instance, a Gdk_Event_Mask is a Flags_Class 
  127.  
  128.    type Flags_Class is new Glib.C_Proxy; 
  129.    type Flags_Value is new Glib.C_Proxy; 
  130.    type Flags_Int_Value is mod Glib.Gint'Last; 
  131.  
  132.    function Nth_Value (Klass : Flags_Class; Nth : Glib.Guint) 
  133.       return Flags_Value; 
  134.    --  Return the Nth-th value in Klass, or null if there is no such value. 
  135.  
  136.    function Value (Val : Flags_Value) return Flags_Int_Value; 
  137.    --  Return the numeric value for a specific enumeration. Use the matching 
  138.    --  Ada type and 'Val to convert it to a valid Ada enumeration 
  139.  
  140.    function Name (Val : Flags_Value) return String; 
  141.    --  Return the name of Val. This is the equivalent of 'Image in Ada. 
  142.  
  143.    function Nick (Val : Flags_Value) return String; 
  144.    --  Return a displayable string for Val. 
  145.  
  146.    --------------- 
  147.    -- ParamSpec -- 
  148.    --------------- 
  149.  
  150.    function Pspec_Name (Param : Param_Spec) return String; 
  151.    --  Return the name of the property. 
  152.    --  This is the internal string representing the property. It 
  153.    --  Should probably not be displayed on 
  154.  
  155.    function Nick_Name (Param : Param_Spec) return String; 
  156.    --  Return the nickname of the property. This is a string 
  157.    --  that can be displayed to represent the property, and is 
  158.    --  more user-friendly than the result of Name. 
  159.  
  160.    function Flags (Param : Param_Spec) return Param_Flags; 
  161.    --  Return the flags for the property 
  162.  
  163.    function Owner_Type (Param : Param_Spec) return Glib.GType; 
  164.    --  The type that defined Param. If you look for instance at all properties 
  165.    --  provides by a type, they will also include properties provided by the 
  166.    --  parents of the type. This function can be used to find those declared 
  167.    --  with that type only 
  168.  
  169.    function Description (Param : Param_Spec) return String; 
  170.    --  Return the description (ie the help string) for Param 
  171.  
  172.    function Value_Type (Param : Param_Spec) return Glib.GType; 
  173.    --  Return the type of param 
  174.  
  175.    procedure Set_Value_Type (Param : Param_Spec; Typ : Glib.GType); 
  176.    --  Override the type of param. You should only use this function when 
  177.    --  creating new Param_Spec types based on existing types. You should not 
  178.    --  change the type if you haven't created param yourself. 
  179.  
  180.    function Get_Qdata (Param : Param_Spec; Quark : GQuark) return Glib.C_Proxy; 
  181.    --  Return the user data set for Param 
  182.  
  183.    procedure Set_Qdata 
  184.      (Param   : Param_Spec; 
  185.       Quark   : GQuark; 
  186.       Data    : Glib.C_Proxy; 
  187.       Destroy : G_Destroy_Notify := null); 
  188.    --  Associate some named data with Param. Destroy is called when Param is 
  189.    --  destroyed. 
  190.  
  191.    --  Value_Type returns GType_Char 
  192.    type Param_Spec_Char is new Param_Spec; 
  193.    function Minimum (Param : Param_Spec_Char) return Glib.Gint8; 
  194.    function Maximum (Param : Param_Spec_Char) return Glib.Gint8; 
  195.    function Default (Param : Param_Spec_Char) return Glib.Gint8; 
  196.    function Gnew_Char 
  197.      (Name, Nick, Blurb         : String; 
  198.       Minimum, Maximum, Default : Glib.Gint8; 
  199.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  200.       return Param_Spec; 
  201.  
  202.    --  Value_Type returns GType_UChar 
  203.    type Param_Spec_Uchar is new Param_Spec; 
  204.    function Minimum (Param : Param_Spec_Uchar) return Glib.Guint8; 
  205.    function Maximum (Param : Param_Spec_Uchar) return Glib.Guint8; 
  206.    function Default (Param : Param_Spec_Uchar) return Glib.Guint8; 
  207.    function Gnew_Uchar 
  208.      (Name, Nick, Blurb         : String; 
  209.       Minimum, Maximum, Default : Glib.Guint8; 
  210.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  211.       return Param_Spec; 
  212.  
  213.    --  Value_Type returns GType_Bool 
  214.    type Param_Spec_Boolean is new Param_Spec; 
  215.    function Default (Param : Param_Spec_Boolean) return Boolean; 
  216.    function Gnew_Boolean 
  217.      (Name, Nick, Blurb : String; 
  218.       Default           : Boolean; 
  219.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  220.       return Param_Spec; 
  221.  
  222.    --  Value_Type returns GType_Int 
  223.    type Param_Spec_Int is new Param_Spec; 
  224.    function Minimum (Param : Param_Spec_Int) return Glib.Gint; 
  225.    function Maximum (Param : Param_Spec_Int) return Glib.Gint; 
  226.    function Default (Param : Param_Spec_Int) return Glib.Gint; 
  227.    function Gnew_Int 
  228.      (Name, Nick, Blurb         : String; 
  229.       Minimum, Maximum, Default : Glib.Gint; 
  230.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  231.       return Param_Spec; 
  232.  
  233.    --  Value_Type returns GType_Uint 
  234.    type Param_Spec_Uint is new Param_Spec; 
  235.    function Minimum (Param : Param_Spec_Uint) return Glib.Guint; 
  236.    function Maximum (Param : Param_Spec_Uint) return Glib.Guint; 
  237.    function Default (Param : Param_Spec_Uint) return Glib.Guint; 
  238.    function Gnew_Uint 
  239.      (Name, Nick, Blurb         : String; 
  240.       Minimum, Maximum, Default : Glib.Guint; 
  241.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  242.       return Param_Spec; 
  243.  
  244.    --  Value_Type returns GType_Long 
  245.    type Param_Spec_Long is new Param_Spec; 
  246.    function Minimum (Param : Param_Spec_Long) return Glib.Glong; 
  247.    function Maximum (Param : Param_Spec_Long) return Glib.Glong; 
  248.    function Default (Param : Param_Spec_Long) return Glib.Glong; 
  249.    function Gnew_Long 
  250.      (Name, Nick, Blurb         : String; 
  251.       Minimum, Maximum, Default : Glib.Glong; 
  252.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  253.       return Param_Spec; 
  254.  
  255.    --  Value_Type returns GType_ULong 
  256.    type Param_Spec_Ulong is new Param_Spec; 
  257.    function Minimum (Param : Param_Spec_Ulong) return Glib.Gulong; 
  258.    function Maximum (Param : Param_Spec_Ulong) return Glib.Gulong; 
  259.    function Default (Param : Param_Spec_Ulong) return Glib.Gulong; 
  260.    function Gnew_Ulong 
  261.      (Name, Nick, Blurb         : String; 
  262.       Minimum, Maximum, Default : Glib.Gulong; 
  263.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  264.       return Param_Spec; 
  265.  
  266.    --  Value_Type returns ??? 
  267.    type Param_Spec_Unichar is new Param_Spec; 
  268.    function Default (Param : Param_Spec_Unichar) return Gunichar; 
  269.    function Gnew_Unichar 
  270.      (Name, Nick, Blurb : String; 
  271.       Default           : Gunichar; 
  272.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  273.       return Param_Spec; 
  274.  
  275.    --  Value_Type returns GType_Enum 
  276.    --  See also the package Generic_Enumeration_Property on how to create 
  277.    --  properties based on an Ada enumeration type. 
  278.    type Param_Spec_Enum is new Param_Spec; 
  279.    function Enumeration (Param : Param_Spec_Enum) return Enum_Class; 
  280.    function Default (Param : Param_Spec_Enum) return Glib.Gint; 
  281.    function Gnew_Enum 
  282.      (Name, Nick, Blurb : String; 
  283.       Enum_Type         : GType; 
  284.       Default           : Gint := 0; 
  285.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  286.       return Param_Spec; 
  287.    --  See Glib.Properties.Creation.Register_Static_Enum on how to create 
  288.    --  Enum_Type 
  289.  
  290.    --  Value_Type returns GType_Flags 
  291.    type Param_Spec_Flags is new Param_Spec; 
  292.    function Flags_Enumeration (Param : Param_Spec_Flags) return Flags_Class; 
  293.    function Default (Param : Param_Spec_Flags) return Glong; 
  294.    function Gnew_Flags 
  295.      (Name, Nick, Blurb : String; 
  296.       Flags_Type        : Glib.GType; 
  297.       Default           : Guint; 
  298.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  299.       return Param_Spec; 
  300.  
  301.    --  Value_Type returns GType_Float 
  302.    type Param_Spec_Float is new Param_Spec; 
  303.    function Minimum (Param : Param_Spec_Float) return Gfloat; 
  304.    function Maximum (Param : Param_Spec_Float) return Gfloat; 
  305.    function Default (Param : Param_Spec_Float) return Gfloat; 
  306.    function Epsilon (Param : Param_Spec_Float) return Gfloat; 
  307.    function Gnew_Float 
  308.      (Name, Nick, Blurb         : String; 
  309.       Minimum, Maximum, Default : Glib.Gfloat; 
  310.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  311.       return Param_Spec; 
  312.  
  313.    --  Value_Type returns GType_Double 
  314.    type Param_Spec_Double is new Param_Spec; 
  315.    function Minimum (Param : Param_Spec_Double) return Gdouble; 
  316.    function Maximum (Param : Param_Spec_Double) return Gdouble; 
  317.    function Default (Param : Param_Spec_Double) return Gdouble; 
  318.    function Epsilon (Param : Param_Spec_Double) return Gdouble; 
  319.    function Gnew_Double 
  320.      (Name, Nick, Blurb         : String; 
  321.       Minimum, Maximum, Default : Glib.Gdouble; 
  322.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  323.       return Param_Spec; 
  324.  
  325.    --  Value_Type returns GType_String 
  326.    type Param_Spec_String is new Param_Spec; 
  327.    function Default (Param : Param_Spec_String) return String; 
  328.    function Cset_First (Param : Param_Spec_String) return String; 
  329.    function Cset_Nth (Param : Param_Spec_String) return String; 
  330.    function Substitutor (Param : Param_Spec_String) return Character; 
  331.    function Ensure_Non_Null (Param : Param_Spec_String) return Boolean; 
  332.    function Gnew_String 
  333.      (Name, Nick, Blurb : String; 
  334.       Default           : String; 
  335.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  336.       return Param_Spec; 
  337.  
  338.    --  Value_Type returns GType_Param 
  339.    type Param_Spec_Param is new Param_Spec; 
  340.    function Gnew_Param 
  341.      (Name, Nick, Blurb : String; 
  342.       Param_Type        : Glib.GType; 
  343.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  344.       return Param_Spec; 
  345.  
  346.    --  Value_Type returns GType_Boxed 
  347.    type Param_Spec_Boxed is new Param_Spec; 
  348.    function Gnew_Boxed 
  349.      (Name, Nick, Blurb : String; 
  350.       Boxed_Type        : Glib.GType; 
  351.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  352.       return Param_Spec; 
  353.  
  354.    --  Value_Type returns GType_Pointer 
  355.    type Param_Spec_Pointer is new Param_Spec; 
  356.    function Gnew_Pointer 
  357.      (Name, Nick, Blurb : String; 
  358.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  359.       return Param_Spec; 
  360.  
  361.    --  Value_Type returns GType_Param_Value_Array 
  362.    --  type Param_Spec_Value_Array is new Param_Spec; 
  363.  
  364.    --  Value_Type returns GType_Object 
  365.    type Param_Spec_Object is new Param_Spec; 
  366.    function Gnew_Object 
  367.      (Name, Nick, Blurb : String; 
  368.       Object_Type       : Glib.GType; 
  369.       Flags : Param_Flags := Param_Readable or Param_Writable) 
  370.       return Param_Spec; 
  371.  
  372.    ----------------------------- 
  373.    -- Creating new properties -- 
  374.    ----------------------------- 
  375.    --  There are several things that need to be done when creating a property. 
  376.    --  For one thing, you need to create the string that represents the 
  377.    --  property. This is the only item that needs to go in the specifications 
  378.    --  of your page. 
  379.    --  You then need to describe the type of the property, and the values it 
  380.    --  allows. This is very simple for simple types, and a generic packages is 
  381.    --  provided to handle the more complex enumeration-based properties. 
  382.    -- 
  383.    --  Your widget needs to define two handlers, Set_Property_Handler and 
  384.    --  Get_Property_Handler, that are called every time the user accesses the 
  385.    --  value of a property through a call to Glib.Object.Set_Property or 
  386.    --  Glib.Object.Get_Property. 
  387.    -- 
  388.    --  For efficiency reasons, a property is also associated with an integer 
  389.    --  value, that you must provide when creating the property. This value is 
  390.    --  completely free, and is passed to the two handlers described above. 
  391.    -- 
  392.    --  The two handlers manipulate Glib.Values.GValue values, so that they 
  393.    --  can get and return various types. 
  394.  
  395.    type Property_Id is new Guint; 
  396.  
  397.    type Set_Property_Handler is access procedure 
  398.      (Object        : access Glib.Object.GObject_Record'Class; 
  399.       Prop_Id       : Property_Id; 
  400.       Value         : Glib.Values.GValue; 
  401.       Property_Spec : Param_Spec); 
  402.    --  This handler is called every time the user has asked for a new 
  403.    --  property to be changed. 
  404.    --  Prop_Id is the id you used when creating the property. 
  405.    --  Value is the new value that should be set. It is your responsability 
  406.    --  to extract the actual value from it. However, consistency has already 
  407.    --  been checked by gtk+, so we know the type is correct. 
  408.    --  Property_Spec is the definition of the property. 
  409.    -- 
  410.    --  Note: It is your responsability to emit the "notify" signal after a 
  411.    --  property has been modified. The recommended way is to emit this signal 
  412.    --  from the internal function that actually modified the property, not 
  413.    --  directly from the Set_Propert_Handler itself. This will ensure that 
  414.    --  even if the user doesn't modify the attribute through a property but 
  415.    --  directly by calling the lower-level subprogram, the signal will still 
  416.    --  be emitted. 
  417.  
  418.    type Get_Property_Handler is access procedure 
  419.      (Object        : access Glib.Object.GObject_Record'Class; 
  420.       Prop_Id       : Property_Id; 
  421.       Value         : out Glib.Values.GValue; 
  422.       Property_Spec : Param_Spec); 
  423.    --  This handler is called when the application needs to retrive the value 
  424.    --  of a property. You should set the value in Value 
  425.  
  426.    procedure Set_Properties_Handlers 
  427.      (Class_Record : Glib.Object.Ada_GObject_Class; 
  428.       Set_Property : Set_Property_Handler; 
  429.       Get_Property : Get_Property_Handler); 
  430.    --  Set the two functions used to set and retrieve properties. You 
  431.    --  should never call this function on the class record of the standard 
  432.    --  gtk+ widgets, since this will break their behavior. You should first 
  433.    --  create a new class record through Initialize_Class_Record, and then 
  434.    --  use the returned Class_Record as a parameter to this subprogram. 
  435.    -- 
  436.    --  You cannot pass null to either of the two parameters, or you won't 
  437.    --  be able to install new properties afterwards 
  438.  
  439.    procedure Install_Property 
  440.      (Class_Record  : Glib.Object.Ada_GObject_Class; 
  441.       Prop_Id       : Property_Id; 
  442.       Property_Spec : Param_Spec); 
  443.    --  Adds a new property to Class_Record. You should use this function only 
  444.    --  on class records you have created yourself, not on one of the standard 
  445.    --  widgets. 
  446.    --  Prop_Id is the internal representation for properties, that will be 
  447.    --  passed to the Set_Property and Get_Property_Handlers (see above) to set 
  448.    --  and retrieve the value of a property. 
  449.    --  Property_Spec should be the result of one of the GNew_* subprograms for 
  450.    --  Param_Spec, and this defines the type of the property. 
  451.  
  452. private 
  453.    pragma Import (C, Flags, "ada_gparam_get_flags"); 
  454.    pragma Import (C, Owner_Type, "ada_gparam_get_owner_type"); 
  455.    pragma Import (C, Value_Type, "ada_gparam_get_value_type"); 
  456.    pragma Import (C, Set_Value_Type, "ada_gparam_set_value_type"); 
  457.    pragma Import (C, Get_Value, "g_enum_get_value"); 
  458.    pragma Import (C, Flags_Enumeration, "ada_gparam_get_flags_flags"); 
  459.    pragma Import (C, Enumeration, "ada_gparam_get_enum_class_enum"); 
  460.    pragma Import (C, Install_Property, "g_object_class_install_property"); 
  461.    pragma Import (C, Unref, "g_param_spec_unref"); 
  462.    pragma Import (C, Get_Qdata, "g_param_spec_get_qdata"); 
  463.    pragma Import (C, Set_Qdata, "g_param_spec_set_qdata_full"); 
  464.    pragma Import (C, Enum_Class_From_Type, "g_type_class_ref"); 
  465.    pragma Inline (Description); 
  466.    pragma Inline (Name); 
  467.  
  468.    pragma Inline (Minimum); 
  469.    pragma Inline (Maximum); 
  470.    pragma Inline (Default); 
  471.    pragma Inline (Epsilon); 
  472.    pragma Inline (Substitutor); 
  473.    pragma Inline (Cset_Nth); 
  474.    pragma Inline (Cset_First); 
  475.    pragma Inline (Ensure_Non_Null); 
  476. end Glib.Properties.Creation;