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. -- As a special exception, if other files instantiate generics from  -- 
  23. -- this unit, or you link this unit with other files to produce an   -- 
  24. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  25. -- executable to be covered by the GNU General Public License. This  -- 
  26. -- exception does not however invalidate any other reasons why the   -- 
  27. -- executable file  might be covered by the  GNU Public License.     -- 
  28. ----------------------------------------------------------------------- 
  29.  
  30. --  <description> 
  31. -- 
  32. --  This package provides an interface to the color handling facilities in 
  33. --  gtk+. It is able to handle any kind of visual (monochrome, greyscale, 
  34. --  color with different depths, ...), but provides a common and easy 
  35. --  interface for all of them. 
  36. --  Some of these functions expect a Colormap. There are two ways you can 
  37. --  get such a colormap, either a system default colormap or a per-widget 
  38. --  colormap. It is recommended, unless you are writing your own new widget, 
  39. --  to always use the system default Colormap. All the functions to get 
  40. --  these colormaps are found in Gtk.Widget. 
  41. -- 
  42. --  Getting the Red/Green/Blue components can be done through Parse, and is 
  43. --  actually recommended, since the exact color generally depends on the 
  44. --  visual your application is running on. 
  45. -- 
  46. --  Note for users transitioning from gtk+ 1.2: the Get_System call is now 
  47. --  obsolete, and you should use Gtk.Widget.Get_Default_Colormap instead. 
  48. -- 
  49. --  </description> 
  50. --  <c_version>1.3.6</c_version> 
  51. --  <group>Gdk, the low-level API</group> 
  52.  
  53. with Glib; use Glib; 
  54. with Glib.Object; 
  55. with Glib.Values; 
  56. with Gdk.Visual; 
  57.  
  58. package Gdk.Color is 
  59.  
  60.    type Gdk_Color is private; 
  61.    --  A color to be displayed on the screen. 
  62.    --  Currently, GtkAda only supports the RGB standard, ie each color is 
  63.    --  set by its red, green and blue components. 
  64.    --  An extra field (Pixel) is the internal representation of the color, 
  65.    --  which is set once the color has been allocated. 
  66.  
  67.    type Gdk_Color_Array is array (Natural range <>) of Gdk_Color; 
  68.    --  An array of colors. 
  69.  
  70.    Null_Color : constant Gdk_Color; 
  71.    --  No color. For most functions, this will select the default color in the 
  72.    --  context, although this exact specification depends on the function you 
  73.    --  want to use. 
  74.  
  75.    subtype Gdk_Colormap is Gdk.Gdk_Colormap; 
  76.    --  The set of colors the can be displayed on the screen. 
  77.    --  When the screen is not a true-color screen (ie there is only a limited 
  78.    --  number of possible colors, like 256), the colors are in fact indexes 
  79.    --  into a colormap, which gives the components of the color. 
  80.    --  This is the same concept as a palette. 
  81.  
  82.    Null_Colormap : constant Gdk_Colormap; 
  83.  
  84.    Wrong_Color : exception; 
  85.    --  Exception raised when some functions below could not find or allocate 
  86.    --  a color on the user's system. 
  87.  
  88.    function Gdk_Color_Type return Glib.GType; 
  89.    --  Return the internal gtk+ types associated with a color 
  90.  
  91.    function Gdk_Colormap_Type return Glib.GType; 
  92.    --  Return the internal gtk+ types associated with a colormap 
  93.  
  94.    --------------------------------------------- 
  95.    -- Setting/Getting the fields of Gdk_Color -- 
  96.    --------------------------------------------- 
  97.  
  98.    procedure Set_Rgb (Color : out Gdk_Color; Red, Green, Blue : Guint16); 
  99.    --  Modify the fields of the color. 
  100.    --  You then have to allocate the color with one of the Alloc* functions 
  101.    --  above. 
  102.  
  103.    procedure Set_Pixel (Color : in out Gdk_Color; Pixel : Guint32); 
  104.    --  This function should almost never be used. Instead, use Alloc_Color. 
  105.  
  106.    function Red (Color : Gdk_Color) return Guint16; 
  107.    --  Return the Red field of Color. 
  108.  
  109.    function Green (Color : Gdk_Color) return Guint16; 
  110.    --  Return the Green field of Color. 
  111.  
  112.    function Blue (Color : Gdk_Color) return Guint16; 
  113.    --  Return the Blue field of Color. 
  114.  
  115.    function Pixel (Color : Gdk_Color) return Guint32; 
  116.    --  Return the Pixel field of Color. 
  117.  
  118.    ------------------------------------ 
  119.    -- Creating and Destroying colors -- 
  120.    ------------------------------------ 
  121.  
  122.    procedure Gdk_New 
  123.      (Colormap     : out Gdk_Colormap; 
  124.       Visual       : Gdk.Visual.Gdk_Visual; 
  125.       Private_Cmap : Boolean); 
  126.    --  Create a new colormap for the visual. 
  127.    --  If Private_Cmap is true, then the 
  128.    --  colormap won't be modifiable outside this scope. This might result in 
  129.    --  some strange colors on the display... 
  130.  
  131.    procedure Ref (Colormap : Gdk_Colormap); 
  132.    --  Increment the ref-count for the color. 
  133.  
  134.    procedure Unref (Colormap : Gdk_Colormap); 
  135.    --  Unref is the only way to destroy a colormap once you no longer need it. 
  136.    --  Note that because gtk+ uses reference counts, the colormap will not 
  137.    --  be actually destroyed while at least one object is using it. 
  138.  
  139.    procedure Change 
  140.      (Colormap : Gdk_Colormap; Ncolors : Gint); 
  141.    --  Change the first Ncolors defined in Colormap. 
  142.  
  143.    procedure Alloc_Colors 
  144.      (Colormap   : Gdk_Colormap; 
  145.       Colors     : in out Gdk_Color_Array; 
  146.       Writeable  : Boolean := False; 
  147.       Best_Match : Boolean := True; 
  148.       Success    : out Boolean_Array; 
  149.       Result     : out Gint); 
  150.    --  Allocate a set of colors. 
  151.    --  The parameters are the same as for Alloc_Color 
  152.    --  Result is the number of colors not successfully allocated. 
  153.    -- 
  154.    --  The size of the Boolean_Array is equal to the length of the 
  155.    --  Colors_Array. Usage of an array of a different size will 
  156.    --  probably lead to a Constraint_Error. 
  157.  
  158.    procedure Alloc_Color 
  159.      (Colormap   : Gdk_Colormap; 
  160.       Color      : in out Gdk_Color; 
  161.       Writeable  : Boolean := False; 
  162.       Best_Match : Boolean := True; 
  163.       Success    : out Boolean); 
  164.    --  Allocate a new color. 
  165.    --  The fields RGB should have been set before calling this function. 
  166.    --  If Writeable is True, the color will be allocated read/write, that can 
  167.    --  be changed at any time. Not all visuals support this. On modern systems 
  168.    --  this usage has become less useful than before, since redrawing the 
  169.    --  screen with a new color is about as fast. 
  170.    --  If Best_Match is True, and the exact color can not be allocated, GtkAda 
  171.    --  will find the closest possible match, and modify the fields Red, Green 
  172.    --  and Blue of Color. 
  173.    --  Note that the allocation has more chances to succeed if Writeable is 
  174.    --  False and Best_Match is True. 
  175.    --  When you no longer use a color, you should call Free. 
  176.  
  177.    procedure Free_Colors (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array); 
  178.    --  Free Colors, assuming they are allocated in Colormap. 
  179.  
  180.    procedure Get_Visual 
  181.      (Colormap : Gdk_Colormap; 
  182.       Visual   : out Gdk.Visual.Gdk_Visual); 
  183.    --  Get the visual associated with a colormap. 
  184.    --  The main information you can get from there is the depth of the display. 
  185.  
  186.    procedure Copy (Source : Gdk_Color; Destination : out Gdk_Color); 
  187.    --  Copy the Source color to Destination. 
  188.  
  189.    function Parse (Spec : String) return Gdk_Color; 
  190.    --  Parse the string Spec, and get its Red/Green/Blue components. 
  191.    --  The color is not allocated, and you need to call Alloc_Color. 
  192.    --  If the string could not be parsed to an existing color, Wrong_Color is 
  193.    --  raised. 
  194.    --  The string can be one of : 
  195.    -- 
  196.    --  - "RGB:FF/FF/FF" where the "FF" substrings are respectively the value 
  197.    --    of the red, green and blue components. Some other prefixes than RGB 
  198.    --    are defined in the X11 definition, please see some X11 documentation 
  199.    --    (or the man page XParseColor on unix systems). 
  200.    -- 
  201.    --  - "color_name" which can be any color name defined in the file rgb.txt 
  202.    --    of the user's system. You should always check that Wrong_Color was not 
  203.    --    raised, in case the color was not known on the user's system. This 
  204.    --    string is case insensitive. Color names are not supported on Windows 
  205.    --    systems. 
  206.  
  207.    function Equal (Colora, Colorb : Gdk_Color) return Boolean; 
  208.    --  True if the Red, Green and Blue components of both colors are equal. 
  209.  
  210.    --  <doc_ignore> 
  211.    -------------------------- 
  212.    -- Deprecated functions -- 
  213.    -------------------------- 
  214.  
  215.    procedure Store (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array); 
  216.    --  Store the Colors in the Colormap. 
  217.  
  218.    procedure Alloc 
  219.      (Colormap   : Gdk_Colormap; 
  220.       Contiguous : Boolean; 
  221.       Planes     : Gulong_Array; 
  222.       Pixels     : Gulong_Array; 
  223.       Succeeded  : out Boolean); 
  224.    --  Allocate some Read/Write color cells. 
  225.    --  Color cells' values can be changed 
  226.    --  dynamically. The pixels allocated are returned in Pixels. 
  227.    --  See XAllocColorCells(3) on Unix systems. 
  228.    --  The Planes parameter can be used to nondestructively overlay one 
  229.    --  set of graphics over another. See the X11 manual for more info. 
  230.    --  Note that this is a low-level function which you should rarely 
  231.    --  have to use. 
  232.  
  233.    procedure Free 
  234.      (Colormap : Gdk_Colormap; 
  235.       Pixels   : Gulong_Array; 
  236.       Planes   : Gulong); 
  237.    --  Free some colors in the colormap. 
  238.    --  See XFreeColors(3) on Unix systems. 
  239.  
  240.    function White (Colormap : Gdk_Colormap) return Gdk_Color; 
  241.    --  Return the default white color for the colormap. 
  242.    --  If this color was not found or could not be allocated, Wrong_Color is 
  243.    --  raised. 
  244.  
  245.    function Black (Colormap : Gdk_Colormap) return Gdk_Color; 
  246.    --  Return the default black colors for the colormap. 
  247.    --  If this color is not found or could not be allocated, Wrong_Color is 
  248.    --  raised. 
  249.  
  250.    procedure Alloc 
  251.      (Colormap  : Gdk_Colormap; 
  252.       Color     : in out Gdk_Color); 
  253.    --  Same function as Alloc_Colors above, but for a single color. 
  254.    --  The color is allocated non-writeable, and the best-match is taken. 
  255.    --  Raises Wrong_Color if the color could not be allocated 
  256.  
  257.    procedure Change 
  258.      (Colormap  : Gdk_Colormap; 
  259.       Color     : in out Gdk_Color; 
  260.       Succeeded : out Boolean); 
  261.    --  Change the Read/Write colormap cell corresponding to Color. 
  262.    --  The new value is the one contained in the Red, Green and Blue 
  263.    --  fields of Color. 
  264.  
  265.    function To_String (Color : Gdk_Color) return String; 
  266.    --  Return the RGB values of Color under the form "#RRGGBB". 
  267.    --  Directly usable by Parse, see above. 
  268.  
  269.    ---------------- 
  270.    -- Properties -- 
  271.    ---------------- 
  272.    --  See the package Glib.Properties for more information on how to 
  273.    --  use properties 
  274.  
  275.    type Property_Gdk_Color is new Glib.Property; 
  276.  
  277.    procedure Set_Property 
  278.      (Object : access Glib.Object.GObject_Record'Class; 
  279.       Name   : Property_Gdk_Color; 
  280.       Value  : Gdk_Color); 
  281.  
  282.    function Get_Property 
  283.      (Object : access Glib.Object.GObject_Record'Class; 
  284.       Name   : Property_Gdk_Color) return Gdk_Color; 
  285.  
  286.    procedure Set_Value (Value : out Glib.Values.GValue; Val : Gdk_Color); 
  287.    function  Get_Value (Value : Glib.Values.GValue) return Gdk_Color; 
  288.    --  Store or retrieve a color from a value 
  289.  
  290.    --  </doc_ignore> 
  291.  
  292. private 
  293.    Null_Colormap : constant Gdk_Colormap := null; 
  294.  
  295.    type Gdk_Color is record 
  296.       Pixel : Guint32; 
  297.       Red   : Guint16; 
  298.       Green : Guint16; 
  299.       Blue  : Guint16; 
  300.    end record; 
  301.    pragma Convention (C, Gdk_Color); 
  302.    --  The fields are to be chosen between 0 and 65535, not 0 and 255!!! 
  303.  
  304.    Null_Color : constant Gdk_Color := (Guint32'Last, 1, 0, 0); 
  305.    --  Note: in the implementation of GtkAda, everytime a color is used, it 
  306.    --  is important to test whether this is Null_Color or not. If it is, then 
  307.    --  System.Null_Address should be passed to C instead of Null_Color'Address 
  308.    --  so that gtk+ can provide a default value for colors. 
  309.  
  310.    pragma Import (C, Gdk_Color_Type, "gdk_color_get_type"); 
  311.  
  312.    pragma Inline (Set_Rgb); 
  313.    pragma Inline (Set_Pixel); 
  314.    pragma Inline (Red); 
  315.    pragma Inline (Green); 
  316.    pragma Inline (Blue); 
  317.    pragma Inline (Pixel); 
  318.    pragma Inline (Set_Property); 
  319.    pragma Inline (Get_Property); 
  320.    pragma Import (C, Ref, "gdk_colormap_ref"); 
  321.    pragma Import (C, Unref, "gdk_colormap_unref"); 
  322.    pragma Import (C, Gdk_Colormap_Type, "gdk_colormap_get_type"); 
  323. end Gdk.Color; 
  324.  
  325. --  <example> 
  326. --  --  Here is an example how you can allocate a new color, when you know 
  327. --  --  its red/green/blue components: Note that we allocate white in fact 
  328. --  --  since the maximal value for color components is 65535. 
  329. --     Color   : Gdk_Color; 
  330. --     Success : Boolean; 
  331. --     Set_Rbg (Color, 65535, 65535, 65535); 
  332. --     Alloc_Color (Colormap   => Gtk.Widget.Get_Default_Colormap, 
  333. --                  Color      => Color, 
  334. --                  Writeable  => False, 
  335. --                  Best_Match => True, 
  336. --                  Success    => Success); 
  337. --     if not Success then 
  338. --         ...;  --  allocation failed 
  339. --     end if; 
  340. --  </example> 
  341. -- 
  342. --  missing: 
  343. --  gdk_color_get_type 
  344. --  gdk_colormap_get_type 
  345. --  gdk_color_free,  not needed in Ada