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 an interface to the color handling facilities in 
  28. --  gtk+. It is able to handle any kind of visual (monochrome, greyscale, 
  29. --  color with different depths, ...), but provides a common and easy 
  30. --  interface for all of them. 
  31. --  Some of these functions expect a Colormap. There are two ways you can 
  32. --  get such a colormap, either a system default colormap or a per-widget 
  33. --  colormap. It is recommended, unless you are writing your own new widget, 
  34. --  to always use the system default Colormap. All the functions to get 
  35. --  these colormaps are found in Gtk.Widget. 
  36. -- 
  37. --  Getting the Red/Green/Blue components can be done through Parse, and is 
  38. --  actually recommended, since the exact color generally depends on the 
  39. --  visual your application is running on. 
  40. -- 
  41. --  Note for users transitioning from gtk+ 1.2: the Get_System call is now 
  42. --  obsolete, and you should use Gtk.Widget.Get_Default_Colormap instead. 
  43. -- 
  44. --  </description> 
  45. --  <c_version>1.3.6</c_version> 
  46. --  <group>Gdk, the low-level API</group> 
  47.  
  48. with Glib; use Glib; 
  49. with Glib.Object; 
  50. with Glib.Values; 
  51.  
  52. package Gdk.Color is 
  53.  
  54.    type Gdk_Color is private; 
  55.    --  A color to be displayed on the screen. 
  56.    --  Currently, GtkAda only supports the RGB standard, ie each color is 
  57.    --  set by its red, green and blue components. 
  58.    --  An extra field (Pixel) is the internal representation of the color, 
  59.    --  which is set once the color has been allocated. 
  60.  
  61.    type Gdk_Color_Array is array (Natural range <>) of Gdk_Color; 
  62.    --  An array of colors. 
  63.  
  64.    type Gdk_Color_Unconstrained_Array is array (Natural) of Gdk_Color; 
  65.    pragma Convention (C, Gdk_Color_Unconstrained_Array); 
  66.    --  An array of colors as returned by C. This is only useful in a few 
  67.    --  low-level subprograms that also pass the size as argument 
  68.  
  69.    function To_Array 
  70.       (Colors   : Gdk_Color_Unconstrained_Array; 
  71.        N_Colors : Gint) return Gdk_Color_Array; 
  72.    --  Return a version of Colors easier to use in Ada. 
  73.  
  74.    Null_Color : constant Gdk_Color; 
  75.    --  No color. For most functions, this will select the default color in the 
  76.    --  context, although this exact specification depends on the function you 
  77.    --  want to use. 
  78.  
  79.    subtype Gdk_Colormap is Gdk.Gdk_Colormap; 
  80.    --  The set of colors the can be displayed on the screen. 
  81.    --  When the screen is not a true-color screen (ie there is only a limited 
  82.    --  number of possible colors, like 256), the colors are in fact indexes 
  83.    --  into a colormap, which gives the components of the color. 
  84.    --  This is the same concept as a palette. 
  85.  
  86.    Null_Colormap : constant Gdk_Colormap; 
  87.  
  88.    Wrong_Color : exception; 
  89.    --  Exception raised when some functions below could not find or allocate 
  90.    --  a color on the user's system. 
  91.  
  92.    function Gdk_Color_Type return Glib.GType; 
  93.    --  Return the internal gtk+ types associated with a color 
  94.  
  95.    function Gdk_Colormap_Type return Glib.GType; 
  96.    --  Return the internal gtk+ types associated with a colormap 
  97.  
  98.    --------------------------------------------- 
  99.    -- Setting/Getting the fields of Gdk_Color -- 
  100.    --------------------------------------------- 
  101.  
  102.    procedure Set_Rgb (Color : out Gdk_Color; Red, Green, Blue : Guint16); 
  103.    --  Modify the fields of the color. 
  104.    --  You then have to allocate the color with one of the Alloc* functions 
  105.    --  above. 
  106.  
  107.    procedure Set_Pixel (Color : in out Gdk_Color; Pixel : Guint32); 
  108.    --  This function should almost never be used. Instead, use Alloc_Color. 
  109.  
  110.    function Red (Color : Gdk_Color) return Guint16; 
  111.    --  Return the Red field of Color. 
  112.  
  113.    function Green (Color : Gdk_Color) return Guint16; 
  114.    --  Return the Green field of Color. 
  115.  
  116.    function Blue (Color : Gdk_Color) return Guint16; 
  117.    --  Return the Blue field of Color. 
  118.  
  119.    function Pixel (Color : Gdk_Color) return Guint32; 
  120.    --  Return the Pixel field of Color. 
  121.  
  122.    ------------------------------------ 
  123.    -- Creating and Destroying colors -- 
  124.    ------------------------------------ 
  125.  
  126.    procedure Ref (Colormap : Gdk_Colormap); 
  127.    --  Increment the ref-count for the color. 
  128.  
  129.    procedure Unref (Colormap : Gdk_Colormap); 
  130.    --  Unref is the only way to destroy a colormap once you no longer need it. 
  131.    --  Note that because gtk+ uses reference counts, the colormap will not 
  132.    --  be actually destroyed while at least one object is using it. 
  133.  
  134.    procedure Copy (Source : Gdk_Color; Destination : out Gdk_Color); 
  135.    --  Copy the Source color to Destination. 
  136.  
  137.    function Parse (Spec : String) return Gdk_Color; 
  138.    --  Parse the string Spec, and get its Red/Green/Blue components. 
  139.    --  The color is not allocated, and you need to call Alloc_Color. 
  140.    --  If the string could not be parsed to an existing color, Wrong_Color is 
  141.    --  raised. 
  142.    --  The string can be one of : 
  143.    -- 
  144.    --  - "RGB:FF/FF/FF" where the "FF" substrings are respectively the value 
  145.    --    of the red, green and blue components. Some other prefixes than RGB 
  146.    --    are defined in the X11 definition, please see some X11 documentation 
  147.    --    (or the man page XParseColor on unix systems). 
  148.    -- 
  149.    --  - "color_name" which can be any color name defined in the file rgb.txt 
  150.    --    of the user's system. You should always check that Wrong_Color was not 
  151.    --    raised, in case the color was not known on the user's system. This 
  152.    --    string is case insensitive. Color names are not supported on Windows 
  153.    --    systems. 
  154.  
  155.    function Equal (Colora, Colorb : Gdk_Color) return Boolean; 
  156.    function "=" (Colora, Colorb : Gdk_Color) return Boolean renames Equal; 
  157.    --  True if the Red, Green and Blue components of both colors are equal. 
  158.  
  159.    --  <doc_ignore> 
  160.  
  161.    function To_String (Color : Gdk_Color) return String; 
  162.    --  Return the RGB values of Color under the form "#RRGGBB". 
  163.    --  Directly usable by Parse, see above. 
  164.  
  165.    ---------------- 
  166.    -- Properties -- 
  167.    ---------------- 
  168.    --  See the package Glib.Properties for more information on how to 
  169.    --  use properties 
  170.  
  171.    type Property_Gdk_Color is new Glib.Property; 
  172.  
  173.    procedure Set_Property 
  174.      (Object : access Glib.Object.GObject_Record'Class; 
  175.       Name   : Property_Gdk_Color; 
  176.       Value  : Gdk_Color); 
  177.  
  178.    function Get_Property 
  179.      (Object : access Glib.Object.GObject_Record'Class; 
  180.       Name   : Property_Gdk_Color) return Gdk_Color; 
  181.  
  182.    procedure Set_Value (Value : out Glib.Values.GValue; Val : Gdk_Color); 
  183.    function  Get_Value (Value : Glib.Values.GValue) return Gdk_Color; 
  184.    --  Store or retrieve a color from a value 
  185.  
  186.    --  </doc_ignore> 
  187.  
  188.    --  <doc_ignore> 
  189.    function Gdk_Color_Or_Null (Val : System.Address) return System.Address; 
  190.    --  Used for the GtkAda binding itself. 
  191.    --  Return either a Null_Address or a pointer to Val, depending on 
  192.    --  whether Val is the null value for the type. 
  193.    --  In all cases, Val is supposed to be an access to the type mentioned in 
  194.    --  the name of the subprogram. 
  195.    --  In Ada2012, these could be replaced with expression functions instead. 
  196.    --  </doc_ignore> 
  197.  
  198. private 
  199.    Null_Colormap : constant Gdk_Colormap := null; 
  200.  
  201.    type Gdk_Color is record 
  202.       Pixel : Guint32; 
  203.       Red   : Guint16; 
  204.       Green : Guint16; 
  205.       Blue  : Guint16; 
  206.    end record; 
  207.    pragma Convention (C, Gdk_Color); 
  208.    --  The fields are to be chosen between 0 and 65535, not 0 and 255!!! 
  209.  
  210.    Null_Color : constant Gdk_Color := (Guint32'Last, 1, 0, 0); 
  211.    --  Note: in the implementation of GtkAda, everytime a color is used, it 
  212.    --  is important to test whether this is Null_Color or not. If it is, then 
  213.    --  System.Null_Address should be passed to C instead of Null_Color'Address 
  214.    --  so that gtk+ can provide a default value for colors. 
  215.  
  216.    pragma Import (C, Gdk_Color_Type, "gdk_color_get_type"); 
  217.  
  218.    pragma Inline (Set_Rgb); 
  219.    pragma Inline (Set_Pixel); 
  220.    pragma Inline (Red); 
  221.    pragma Inline (Green); 
  222.    pragma Inline (Blue); 
  223.    pragma Inline (Pixel); 
  224.    pragma Inline (Set_Property); 
  225.    pragma Inline (Get_Property); 
  226.    pragma Import (C, Ref, "gdk_colormap_ref"); 
  227.    pragma Import (C, Unref, "gdk_colormap_unref"); 
  228.    pragma Import (C, Gdk_Colormap_Type, "gdk_colormap_get_type"); 
  229. end Gdk.Color; 
  230.  
  231. --  <example> 
  232. --  --  Here is an example how you can allocate a new color, when you know 
  233. --  --  its red/green/blue components: Note that we allocate white in fact 
  234. --  --  since the maximal value for color components is 65535. 
  235. --     Color   : Gdk_Color; 
  236. --     Success : Boolean; 
  237. --     Set_Rbg (Color, 65535, 65535, 65535); 
  238. --     Alloc_Color (Colormap   => Gtk.Widget.Get_Default_Colormap, 
  239. --                  Color      => Color, 
  240. --                  Writeable  => False, 
  241. --                  Best_Match => True, 
  242. --                  Success    => Success); 
  243. --     if not Success then 
  244. --         ...;  --  allocation failed 
  245. --     end if; 
  246. --  </example> 
  247. -- 
  248. --  missing: 
  249. --  gdk_color_get_type 
  250. --  gdk_colormap_get_type 
  251. --  gdk_color_free,  not needed in Ada