1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   -- 
  5. --                Copyright (C) 2000-2003 ACT-Europe                 -- 
  6. --                                                                   -- 
  7. -- This library is free software; you can redistribute it and/or     -- 
  8. -- modify it under the terms of the GNU General Public               -- 
  9. -- License as published by the Free Software Foundation; either      -- 
  10. -- version 2 of the License, or (at your option) any later version.  -- 
  11. --                                                                   -- 
  12. -- This library is distributed in the hope that it will be useful,   -- 
  13. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  14. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  15. -- General Public License for more details.                          -- 
  16. --                                                                   -- 
  17. -- You should have received a copy of the GNU General Public         -- 
  18. -- License along with this library; if not, write to the             -- 
  19. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  20. -- Boston, MA 02111-1307, USA.                                       -- 
  21. --                                                                   -- 
  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. with Gdk.Visual; 
  52.  
  53. package Gdk.Color is 
  54.  
  55.    type Gdk_Color is private; 
  56.    --  A color to be displayed on the screen. 
  57.    --  Currently, GtkAda only supports the RGB standard, ie each color is 
  58.    --  set by its red, green and blue components. 
  59.    --  An extra field (Pixel) is the internal representation of the color, 
  60.    --  which is set once the color has been allocated. 
  61.  
  62.    type Gdk_Color_Array is array (Natural range <>) of Gdk_Color; 
  63.    --  An array of colors. 
  64.  
  65.    Null_Color : constant Gdk_Color; 
  66.    --  No color. For most functions, this will select the default color in the 
  67.    --  context, although this exact specification depends on the function you 
  68.    --  want to use. 
  69.  
  70.    subtype Gdk_Colormap is Gdk.Gdk_Colormap; 
  71.    --  The set of colors the can be displayed on the screen. 
  72.    --  When the screen is not a true-color screen (ie there is only a limited 
  73.    --  number of possible colors, like 256), the colors are in fact indexes 
  74.    --  into a colormap, which gives the components of the color. 
  75.    --  This is the same concept as a palette. 
  76.  
  77.    Null_Colormap : constant Gdk_Colormap; 
  78.  
  79.    Wrong_Color : exception; 
  80.    --  Exception raised when some functions below could not find or allocate 
  81.    --  a color on the user's system. 
  82.  
  83.    function Gdk_Color_Type return Glib.GType; 
  84.    --  Return the internal gtk+ types associated with a color 
  85.  
  86.    function Gdk_Colormap_Type return Glib.GType; 
  87.    --  Return the internal gtk+ types associated with a colormap 
  88.  
  89.    --------------------------------------------- 
  90.    -- Setting/Getting the fields of Gdk_Color -- 
  91.    --------------------------------------------- 
  92.  
  93.    procedure Set_Rgb (Color : out Gdk_Color; Red, Green, Blue : Guint16); 
  94.    --  Modify the fields of the color. 
  95.    --  You then have to allocate the color with one of the Alloc* functions 
  96.    --  above. 
  97.  
  98.    procedure Set_Pixel (Color : in out Gdk_Color; Pixel : Guint32); 
  99.    --  This function should almost never be used. Instead, use Alloc_Color. 
  100.  
  101.    function Red (Color : Gdk_Color) return Guint16; 
  102.    --  Return the Red field of Color. 
  103.  
  104.    function Green (Color : Gdk_Color) return Guint16; 
  105.    --  Return the Green field of Color. 
  106.  
  107.    function Blue (Color : Gdk_Color) return Guint16; 
  108.    --  Return the Blue field of Color. 
  109.  
  110.    function Pixel (Color : Gdk_Color) return Guint32; 
  111.    --  Return the Pixel field of Color. 
  112.  
  113.    ------------------------------------ 
  114.    -- Creating and Destroying colors -- 
  115.    ------------------------------------ 
  116.  
  117.    procedure Gdk_New 
  118.      (Colormap     : out Gdk_Colormap; 
  119.       Visual       : Gdk.Visual.Gdk_Visual; 
  120.       Private_Cmap : Boolean); 
  121.    --  Create a new colormap for the visual. 
  122.    --  If Private_Cmap is true, then the 
  123.    --  colormap won't be modifiable outside this scope. This might result in 
  124.    --  some strange colors on the display... 
  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 Change 
  135.      (Colormap : Gdk_Colormap; Ncolors : Gint); 
  136.    --  Change the first Ncolors defined in Colormap. 
  137.  
  138.    procedure Alloc_Colors 
  139.      (Colormap   : Gdk_Colormap; 
  140.       Colors     : in out Gdk_Color_Array; 
  141.       Writeable  : Boolean := False; 
  142.       Best_Match : Boolean := True; 
  143.       Success    : out Boolean_Array; 
  144.       Result     : out Gint); 
  145.    --  Allocate a set of colors. 
  146.    --  The parameters are the same as for Alloc_Color 
  147.    --  Result is the number of colors not successfully allocated. 
  148.    -- 
  149.    --  The size of the Boolean_Array is equal to the length of the 
  150.    --  Colors_Array. Usage of an array of a different size will 
  151.    --  probably lead to a Constraint_Error. 
  152.  
  153.    procedure Alloc_Color 
  154.      (Colormap   : Gdk_Colormap; 
  155.       Color      : in out Gdk_Color; 
  156.       Writeable  : Boolean := False; 
  157.       Best_Match : Boolean := True; 
  158.       Success    : out Boolean); 
  159.    --  Allocate a new color. 
  160.    --  The fields RGB should have been set before calling this function. 
  161.    --  If Writeable is True, the color will be allocated read/write, that can 
  162.    --  be changed at any time. Not all visuals support this. On modern systems 
  163.    --  this usage has become less useful than before, since redrawing the 
  164.    --  screen with a new color is about as fast. 
  165.    --  If Best_Match is True, and the exact color can not be allocated, GtkAda 
  166.    --  will find the closest possible match, and modify the fields Red, Green 
  167.    --  and Blue of Color. 
  168.    --  Note that the allocation has more chances to succeed if Writeable is 
  169.    --  False and Best_Match is True. 
  170.    --  When you no longer use a color, you should call Free. 
  171.  
  172.    procedure Free_Colors (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array); 
  173.    --  Free Colors, assuming they are allocated in Colormap. 
  174.  
  175.    procedure Get_Visual 
  176.      (Colormap : Gdk_Colormap; 
  177.       Visual   : out Gdk.Visual.Gdk_Visual); 
  178.    --  Get the visual associated with a colormap. 
  179.    --  The main information you can get from there is the depth of the display. 
  180.  
  181.    procedure Copy (Source : Gdk_Color; Destination : out Gdk_Color); 
  182.    --  Copy the Source color to Destination. 
  183.  
  184.    function Parse (Spec : String) return Gdk_Color; 
  185.    --  Parse the string Spec, and get its Red/Green/Blue components. 
  186.    --  The color is not allocated, and you need to call Alloc_Color. 
  187.    --  If the string could not be parsed to an existing color, Wrong_Color is 
  188.    --  raised. 
  189.    --  The string can be one of : 
  190.    -- 
  191.    --  - "RGB:FF/FF/FF" where the "FF" substrings are respectively the value 
  192.    --    of the red, green and blue components. Some other prefixes than RGB 
  193.    --    are defined in the X11 definition, please see some X11 documentation 
  194.    --    (or the man page XParseColor on unix systems). 
  195.    -- 
  196.    --  - "color_name" which can be any color name defined in the file rgb.txt 
  197.    --    of the user's system. You should always check that Wrong_Color was not 
  198.    --    raised, in case the color was not known on the user's system. This 
  199.    --    string is case insensitive. Color names are not supported on Windows 
  200.    --    systems. 
  201.  
  202.    function Equal (Colora, Colorb : Gdk_Color) return Boolean; 
  203.    --  True if the Red, Green and Blue components of both colors are equal. 
  204.  
  205.    --  <doc_ignore> 
  206.    -------------------------- 
  207.    -- Deprecated functions -- 
  208.    -------------------------- 
  209.  
  210.    procedure Store (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array); 
  211.    --  Store the Colors in the Colormap. 
  212.  
  213.    procedure Alloc 
  214.      (Colormap   : Gdk_Colormap; 
  215.       Contiguous : Boolean; 
  216.       Planes     : Gulong_Array; 
  217.       Pixels     : Gulong_Array; 
  218.       Succeeded  : out Boolean); 
  219.    --  Allocate some Read/Write color cells. 
  220.    --  Color cells' values can be changed 
  221.    --  dynamically. The pixels allocated are returned in Pixels. 
  222.    --  See XAllocColorCells(3) on Unix systems. 
  223.    --  The Planes parameter can be used to nondestructively overlay one 
  224.    --  set of graphics over another. See the X11 manual for more info. 
  225.    --  Note that this is a low-level function which you should rarely 
  226.    --  have to use. 
  227.  
  228.    procedure Free 
  229.      (Colormap : Gdk_Colormap; 
  230.       Pixels   : Gulong_Array; 
  231.       Planes   : Gulong); 
  232.    --  Free some colors in the colormap. 
  233.    --  See XFreeColors(3) on Unix systems. 
  234.  
  235.    function White (Colormap : Gdk_Colormap) return Gdk_Color; 
  236.    --  Return the default white color for the colormap. 
  237.    --  If this color was not found or could not be allocated, Wrong_Color is 
  238.    --  raised. 
  239.  
  240.    function Black (Colormap : Gdk_Colormap) return Gdk_Color; 
  241.    --  Return the default black colors for the colormap. 
  242.    --  If this color is not found or could not be allocated, Wrong_Color is 
  243.    --  raised. 
  244.  
  245.    procedure Alloc 
  246.      (Colormap  : Gdk_Colormap; 
  247.       Color     : in out Gdk_Color); 
  248.    --  Same function as Alloc_Colors above, but for a single color. 
  249.    --  The color is allocated non-writeable, and the best-match is taken. 
  250.    --  Raises Wrong_Color if the color could not be allocated 
  251.  
  252.    procedure Change 
  253.      (Colormap  : Gdk_Colormap; 
  254.       Color     : in out Gdk_Color; 
  255.       Succeeded : out Boolean); 
  256.    --  Change the Read/Write colormap cell corresponding to Color. 
  257.    --  The new value is the one contained in the Red, Green and Blue 
  258.    --  fields of Color. 
  259.  
  260.    function To_String (Color : Gdk_Color) return String; 
  261.    --  Return the RGB values of Color under the form "#RRGGBB". 
  262.    --  Directly usable by Parse, see above. 
  263.  
  264.    ---------------- 
  265.    -- Properties -- 
  266.    ---------------- 
  267.    --  See the package Glib.Properties for more information on how to 
  268.    --  use properties 
  269.  
  270.    type Property_Gdk_Color is new Glib.Property; 
  271.  
  272.    procedure Set_Property 
  273.      (Object : access Glib.Object.GObject_Record'Class; 
  274.       Name   : Property_Gdk_Color; 
  275.       Value  : Gdk_Color); 
  276.  
  277.    function Get_Property 
  278.      (Object : access Glib.Object.GObject_Record'Class; 
  279.       Name   : Property_Gdk_Color) return Gdk_Color; 
  280.  
  281.    procedure Set_Value (Value : out Glib.Values.GValue; Val : Gdk_Color); 
  282.    function  Get_Value (Value : Glib.Values.GValue) return Gdk_Color; 
  283.    --  Store or retrieve a color from a value 
  284.  
  285.    --  </doc_ignore> 
  286.  
  287. private 
  288.    Null_Colormap : constant Gdk_Colormap := null; 
  289.  
  290.    type Gdk_Color is record 
  291.       Pixel : Guint32; 
  292.       Red   : Guint16; 
  293.       Green : Guint16; 
  294.       Blue  : Guint16; 
  295.    end record; 
  296.    pragma Convention (C, Gdk_Color); 
  297.    --  The fields are to be chosen between 0 and 65535, not 0 and 255!!! 
  298.  
  299.    Null_Color : constant Gdk_Color := (Guint32'Last, 1, 0, 0); 
  300.    --  Note: in the implementation of GtkAda, everytime a color is used, it 
  301.    --  is important to test whether this is Null_Color or not. If it is, then 
  302.    --  System.Null_Address should be passed to C instead of Null_Color'Address 
  303.    --  so that gtk+ can provide a default value for colors. 
  304.  
  305.    pragma Import (C, Gdk_Color_Type, "gdk_color_get_type"); 
  306.  
  307.    pragma Inline (Set_Rgb); 
  308.    pragma Inline (Set_Pixel); 
  309.    pragma Inline (Red); 
  310.    pragma Inline (Green); 
  311.    pragma Inline (Blue); 
  312.    pragma Inline (Pixel); 
  313.    pragma Inline (Set_Property); 
  314.    pragma Inline (Get_Property); 
  315.    pragma Import (C, Ref, "gdk_colormap_ref"); 
  316.    pragma Import (C, Unref, "gdk_colormap_unref"); 
  317.    pragma Import (C, Gdk_Colormap_Type, "gdk_colormap_get_type"); 
  318. end Gdk.Color; 
  319.  
  320. --  <example> 
  321. --  --  Here is an example how you can allocate a new color, when you know 
  322. --  --  its red/green/blue components: Note that we allocate white in fact 
  323. --  --  since the maximal value for color components is 65535. 
  324. --     Color   : Gdk_Color; 
  325. --     Success : Boolean; 
  326. --     Set_Rbg (Color, 65535, 65535, 65535); 
  327. --     Alloc_Color (Colormap   => Gtk.Widget.Get_Default_Colormap, 
  328. --                  Color      => Color, 
  329. --                  Writeable  => False, 
  330. --                  Best_Match => True, 
  331. --                  Success    => Success); 
  332. --     if not Success then 
  333. --         ...;  --  allocation failed 
  334. --     end if; 
  335. --  </example> 
  336. -- 
  337. --  missing: 
  338. --  gdk_color_get_type 
  339. --  gdk_colormap_get_type 
  340. --  gdk_color_free,  not needed in Ada