1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2006-2009, 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. -- -- -- -- -- -- -- -- -- -- -- -- 
  21. ----------------------------------------------------------------------- 
  22.  
  23. --  <description> 
  24. --  The Gtk_About_Dialog offers a simple way to display information about a 
  25. --  program like its logo, name, copyright, website and license. It is also 
  26. --  possible to give credits to the authors, documenters, translators and 
  27. --  artists who have worked on the program. An about dialog is typically opened 
  28. --  when the user selects the About option from the Help menu. All parts of the 
  29. --  dialog are optional. 
  30. -- 
  31. --  About dialog often contain links and email addresses. Gtk_About_Dialog 
  32. --  supports this by offering global hooks, which are called when the user 
  33. --  clicks on a link or email address, see Set_Email_Hook and Set_Url_Hook. 
  34. --  Email addresses in the authors, documenters and artists properties are 
  35. --  recognized by looking for <user@host>, URLs are recognized by looking for 
  36. --  http://url, with url extending to the next space, tab or line break. 
  37. -- 
  38. --  To make constructing a Gtk_About_Dialog as convenient as possible, you can 
  39. --  use the function gtk_show_about_dialog which constructs and shows a dialog 
  40. --  and keeps it around so that it can be shown again. 
  41. --  </description> 
  42. --  <c_version>2.16</c_version> 
  43. --  <group>Windows</group> 
  44. --  <testgtk>create_about.adb</testgtk> 
  45.  
  46. with Glib.Properties; 
  47. with Gdk.Color; 
  48. with Gdk.Pixbuf; 
  49. with Gtk.Dialog; 
  50. with GNAT.Strings; 
  51. with Interfaces.C.Strings; 
  52. with System; 
  53.  
  54. package Gtk.About_Dialog is 
  55.  
  56.    type Gtk_About_Dialog_Record is new Gtk.Dialog.Gtk_Dialog_Record with 
  57.      null record; 
  58.    type Gtk_About_Dialog is access all Gtk_About_Dialog_Record'Class; 
  59.  
  60.    procedure Gtk_New (About : out Gtk_About_Dialog); 
  61.    procedure Initialize (About : access Gtk_About_Dialog_Record'Class); 
  62.    --  Creates a new Gtk_About_Dialog. 
  63.  
  64.    function Get_Type return Gtk.Gtk_Type; 
  65.    --  Return the internal value associated with a Gtk_Button. 
  66.  
  67.    procedure Set_Artists 
  68.      (About   : access Gtk_About_Dialog_Record; 
  69.       Artists : GNAT.Strings.String_List); 
  70.    function Get_Artists 
  71.      (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; 
  72.    --  Returns the strings which are displayed in the artists tab 
  73.    --  of the secondary credits dialog. 
  74.    --  The returned value must be freed by the caller, as well as the Artists 
  75.    --  parameter. 
  76.  
  77.    procedure Set_Authors 
  78.      (About   : access Gtk_About_Dialog_Record; 
  79.       Authors : GNAT.Strings.String_List); 
  80.    function Get_Authors 
  81.      (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; 
  82.    --  Returns the string which are displayed in the authors tab 
  83.    --  of the secondary credits dialog. 
  84.    --  The returned value must be freed by the caller, as well as the Authors 
  85.    --  paramaeter. 
  86.  
  87.    procedure Set_Comments 
  88.      (About  : access Gtk_About_Dialog_Record; Comments : String); 
  89.    function Get_Comments 
  90.      (About : access Gtk_About_Dialog_Record) return String; 
  91.    --  Returns the comments string. 
  92.  
  93.    procedure Set_Copyright 
  94.      (About : access Gtk_About_Dialog_Record; Copyright : String); 
  95.    function Get_Copyright 
  96.      (About : access Gtk_About_Dialog_Record) return String; 
  97.    --  Returns the copyright string. 
  98.  
  99.    procedure Set_Documenters 
  100.      (About       : access Gtk_About_Dialog_Record; 
  101.       Documenters : GNAT.Strings.String_List); 
  102.    function Get_Documenters 
  103.      (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; 
  104.    --  Returns the string which are displayed in the documenters 
  105.    --  tab of the secondary credits dialog. 
  106.    --  The returned value must be freed by the caller, as well as the 
  107.    --  Documenters parameter. 
  108.  
  109.    procedure Set_License 
  110.      (About : access Gtk_About_Dialog_Record; License : String); 
  111.    function Get_License 
  112.      (About : access Gtk_About_Dialog_Record) return String; 
  113.    --  Returns the license information. 
  114.  
  115.    procedure Set_Logo 
  116.      (About : access Gtk_About_Dialog_Record; 
  117.       Logo  : Gdk.Pixbuf.Gdk_Pixbuf); 
  118.    function Get_Logo 
  119.      (About : access Gtk_About_Dialog_Record) return Gdk.Pixbuf.Gdk_Pixbuf; 
  120.    --  Returns the pixbuf displayed as logo in the about dialog. 
  121.    --  The returned value is owned by the dialog. If you want to keep a 
  122.    --  reference to it, you must call Ref on it. 
  123.    --  Set_Logo sets the pixbuf to be displayed as logo in the about dialog. If 
  124.    --  it is null, the default window icon set with Gtk.Window.Set_Default_Icon 
  125.    --  will be used. 
  126.  
  127.    procedure Set_Logo_Icon_Name 
  128.      (About     : access Gtk_About_Dialog_Record; 
  129.       Icon_Name : String := ""); 
  130.    function Get_Logo_Icon_Name 
  131.      (About : access Gtk_About_Dialog_Record) return String; 
  132.    --  Returns the icon name displayed as logo in the about dialog. 
  133.    --  If the Icon_Name is set to the empty string, the default window icon 
  134.    --  set with Gtk.Window.Set_Default_Icon will be used. 
  135.  
  136.    function Get_Program_Name (About : access Gtk_About_Dialog_Record) 
  137.       return String; 
  138.    procedure Set_Program_Name 
  139.      (About : access Gtk_About_Dialog_Record; 
  140.       Name  : String); 
  141.    --  Returns or sets the program name displayed in the about dialog. 
  142.    --  (since 2.12) 
  143.  
  144.    procedure Set_Translator_Credits 
  145.      (About              : access Gtk_About_Dialog_Record; 
  146.       Translator_Credits : String); 
  147.    function Get_Translator_Credits 
  148.      (About : access Gtk_About_Dialog_Record) return String; 
  149.    --  Sets the translator credits string which is displayed in 
  150.    --  the translators tab of the secondary credits dialog. 
  151.    -- 
  152.    --  The intended use for this string is to display the translator 
  153.    --  of the language which is currently used in the user interface. 
  154.    --  Using Gtkada.Intl.Gettext, a simple way to achieve that is to mark the 
  155.    --  string for translation: 
  156.    --       Set_Translator_Credits (About, -"translator-credits"); 
  157.    --  It is a good idea to use the customary msgid "translator-credits" for 
  158.    --  this purpose, since translators will already know the purpose of that 
  159.    --  msgid, and since Gtk_About_Dialog will detect if "translator-credits" is 
  160.    --  untranslated and hide the tab. 
  161.  
  162.    procedure Set_Version 
  163.      (About   : access Gtk_About_Dialog_Record; Version : String); 
  164.    function Get_Version 
  165.      (About : access Gtk_About_Dialog_Record) return String; 
  166.    --  Returns the version string. 
  167.  
  168.    procedure Set_Website 
  169.      (About   : access Gtk_About_Dialog_Record; Website : String); 
  170.    function Get_Website 
  171.      (About : access Gtk_About_Dialog_Record) return String; 
  172.    --  Returns the website URL. This URL must start with http:// to be 
  173.    --  properly recognized as an hyper link. You must also have called 
  174.    --  Set_Url_Hook before calling this function. 
  175.  
  176.    procedure Set_Website_Label 
  177.      (About         : access Gtk_About_Dialog_Record; 
  178.       Website_Label : String); 
  179.    function Get_Website_Label 
  180.      (About : access Gtk_About_Dialog_Record) return String; 
  181.    --  Returns the label used for the website link. It defaults to the URL. 
  182.  
  183.    procedure Set_Wrap_License 
  184.      (About        : access Gtk_About_Dialog_Record; 
  185.       Wrap_License : Boolean); 
  186.    function Get_Wrap_License 
  187.      (About : access Gtk_About_Dialog_Record) return Boolean; 
  188.    --  Returns whether the license text in About is 
  189.    --  automatically wrapped. 
  190.  
  191.    type Activate_Link_Func is access procedure 
  192.      (About : System.Address; 
  193.       Link  : Interfaces.C.Strings.chars_ptr; 
  194.       Data  : System.Address); 
  195.    pragma Convention (C, Activate_Link_Func); 
  196.    --  A callback called when the user presses an hyper link in the about 
  197.    --  dialog. This is a low-level function, and you'll need to convert the 
  198.    --  parameters to more useful types with: 
  199.    --     Stub : Gtk_About_Dialog_Record; 
  200.    --     A    : constant Gtk_About_Dialog := 
  201.    --       Gtk_About_Dialog (Get_User_Data (About, Stub)); 
  202.    --     L    : constant String := Interfaces.C.Strings.Value (Link); 
  203.  
  204.    function Set_Email_Hook 
  205.      (Func    : Activate_Link_Func; 
  206.       Data    : System.Address; 
  207.       Destroy : Glib.G_Destroy_Notify_Address) 
  208.       return Activate_Link_Func; 
  209.    --  Installs a global function to be called whenever the user activates an 
  210.    --  email link in an about dialog. 
  211.    --  Return value: the previous email hook. 
  212.  
  213.    function Set_Url_Hook 
  214.      (Func    : Activate_Link_Func; 
  215.       Data    : System.Address; 
  216.       Destroy : Glib.G_Destroy_Notify_Address) 
  217.       return Activate_Link_Func; 
  218.    --  Installs a global function to be called whenever the user activates a 
  219.    --  URL link in an about dialog. 
  220.    --  Return value: the previous URL hook. 
  221.  
  222.    procedure Set_Name 
  223.      (About : access Gtk_About_Dialog_Record; Name  : String) 
  224.      renames Set_Program_Name; 
  225.    pragma Obsolescent; --  Set_Name 
  226.    function Get_Name 
  227.      (About : access Gtk_About_Dialog_Record) return String 
  228.      renames Get_Program_Name; 
  229.    pragma Obsolescent; --  Get_Name 
  230.    --  Returns the program name displayed in the about dialog. 
  231.  
  232.    ---------------- 
  233.    -- Properties -- 
  234.    ---------------- 
  235.    --  The following properties are defined for this widget. See 
  236.    --  Glib.Properties for more information on properties. 
  237.  
  238.    --  <properties> 
  239.    --  Name:  Artists_Property 
  240.    --  Type:  Boxed 
  241.    --  Descr: List of people who have contributed artwork to the program 
  242.    -- 
  243.    --  Name:  Authors_Property 
  244.    --  Type:  Boxed 
  245.    --  Descr: List of authors of the program 
  246.    -- 
  247.    --  Name:  Comments_Property 
  248.    --  Type:  String 
  249.    --  Descr: Comments about the program 
  250.    -- 
  251.    --  Name:  Copyright_Property 
  252.    --  Type:  String 
  253.    --  Descr: Copyright information for the program 
  254.    -- 
  255.    --  Name:  Documenters_Property 
  256.    --  Type:  Boxed 
  257.    --  Descr: List of people documenting the program 
  258.    -- 
  259.    --  Name:  Logo_Property 
  260.    --  Type:  Object 
  261.    --  Descr: A logo for the about box. If this is not set, it defaults to 
  262.    --         Gtk.Window.Get_Default_Icon_List 
  263.    -- 
  264.    --  Name:  Logo_Icon_Name_Property 
  265.    --  Type:  String 
  266.    --  Descr: A named icon to use as the logo for the about box. 
  267.    -- 
  268.    --  Name:  Name_Property 
  269.    --  Type:  String 
  270.    --  Obsolescent, see Program_Name_Property 
  271.    --  Descr: The name of the program. If this is not set, it defaults to 
  272.    --         the application name from the command line 
  273.    -- 
  274.    --  Name:  Program_Name_Property 
  275.    --  Type:  String 
  276.    --  Descr: The name of the program. 
  277.    -- 
  278.    --  Name:  Translator_Credits_Property 
  279.    --  Type:  String 
  280.    --  Descr: Credits to the translators. This string should be marked as 
  281.    --         translatable 
  282.    -- 
  283.    --  Name:  Version_Property 
  284.    --  Type:  String 
  285.    --  Descr: The version of the program 
  286.    -- 
  287.    --  Name:  Website_Property 
  288.    --  Type:  String 
  289.    --  Descr: The URL for the link to the website of the program 
  290.    -- 
  291.    --  Name:  Website_Label_Property 
  292.    --  Type:  String 
  293.    --  Descr: The label for the link to the website of the program. If this is 
  294.    --         not set, it defaults to the URL 
  295.    -- 
  296.    --  Name:  Wrap_License_Property 
  297.    --  Type:  Boolean 
  298.    --  Descr: Whether to wrap the license text. 
  299.    --  </properties> 
  300.  
  301.    --   Artists_Property       : constant Glib.Properties.Property_Boxed; 
  302.    --   Authors_Property       : constant Glib.Properties.Property_Boxed; 
  303.    Comments_Property           : constant Glib.Properties.Property_String; 
  304.    Copyright_Property          : constant Glib.Properties.Property_String; 
  305.    --  Documenters_Property    : constant Glib.Properties.Property_Boxed; 
  306.    Logo_Property               : constant Glib.Properties.Property_Object; 
  307.    Logo_Icon_Name_Property     : constant Glib.Properties.Property_String; 
  308.    Name_Property               : constant Glib.Properties.Property_String; 
  309.    Program_Name_Property       : constant Glib.Properties.Property_String; 
  310.    Translator_Credits_Property : constant Glib.Properties.Property_String; 
  311.    Version_Property            : constant Glib.Properties.Property_String; 
  312.    Website_Property            : constant Glib.Properties.Property_String; 
  313.    Website_Label_Property      : constant Glib.Properties.Property_String; 
  314.    Wrap_License_Property       : constant Glib.Properties.Property_Boolean; 
  315.  
  316.    ----------------- 
  317.    -- Obsolescent -- 
  318.    ----------------- 
  319.    --  All subprograms below are now obsolescent in gtk+. They might be removed 
  320.    --  from future versions of gtk+ (and therefore GtkAda). 
  321.    --  To find out whether your code uses any of these, we recommend compiling 
  322.    --  with the -gnatwj switch 
  323.    --  <doc_ignore> 
  324.  
  325.    ---------------------- 
  326.    -- Style Properties -- 
  327.    ---------------------- 
  328.    --  The following properties can be changed through the gtk theme and 
  329.    --  configuration files, and retrieved through Gtk.Widget.Style_Get_Property 
  330.  
  331.    --  <style_properties> 
  332.    --  Name:  Link_Color_Property 
  333.    --  Type:  Boxed 
  334.    --  Descr: Color of hyperlinks 
  335.    --  </style_properties> 
  336.  
  337.    Link_Color_Property : constant Gdk.Color.Property_Gdk_Color; 
  338.  
  339. private 
  340. --     Artists_Property : constant Glib.Properties.Property_Boxed := 
  341. --       Glib.Properties.Build ("artists"); 
  342. --     Authors_Property : constant Glib.Properties.Property_Boxed := 
  343. --       Glib.Properties.Build ("authors"); 
  344.    Comments_Property : constant Glib.Properties.Property_String := 
  345.      Glib.Properties.Build ("comments"); 
  346.    Copyright_Property : constant Glib.Properties.Property_String := 
  347.      Glib.Properties.Build ("copyright"); 
  348. --     Documenters_Property : constant Glib.Properties.Property_Boxed := 
  349. --       Glib.Properties.Build ("documenters"); 
  350.    Logo_Property : constant Glib.Properties.Property_Object := 
  351.      Glib.Properties.Build ("logo"); 
  352.    Logo_Icon_Name_Property : constant Glib.Properties.Property_String := 
  353.      Glib.Properties.Build ("logo-icon-name"); 
  354.    Name_Property : constant Glib.Properties.Property_String := 
  355.      Glib.Properties.Build ("name"); 
  356.    Program_Name_Property : constant Glib.Properties.Property_String := 
  357.      Glib.Properties.Build ("program-name"); 
  358.    Translator_Credits_Property : constant Glib.Properties.Property_String := 
  359.      Glib.Properties.Build ("translator-credits"); 
  360.    Version_Property : constant Glib.Properties.Property_String := 
  361.      Glib.Properties.Build ("version"); 
  362.    Website_Property : constant Glib.Properties.Property_String := 
  363.      Glib.Properties.Build ("website"); 
  364.    Website_Label_Property : constant Glib.Properties.Property_String := 
  365.      Glib.Properties.Build ("website-label"); 
  366.    Wrap_License_Property : constant Glib.Properties.Property_Boolean := 
  367.      Glib.Properties.Build ("wrap-license"); 
  368.  
  369.    Link_Color_Property : constant Gdk.Color.Property_Gdk_Color := 
  370.      Gdk.Color.Property_Gdk_Color (Glib.Build ("link-color")); 
  371.  
  372.    pragma Import (C, Get_Type,       "gtk_about_dialog_get_type"); 
  373.    pragma Import (C, Set_Email_Hook, "gtk_about_dialog_set_email_hook"); 
  374.    pragma Import (C, Set_Url_Hook,   "gtk_about_dialog_set_url_hook"); 
  375. end Gtk.About_Dialog; 
  376.  
  377. --  No binding: gtk_show_about_dialog 
  378. -- 
  379. --  These are obsolescent, and implemented as renamings 
  380. --  No binding: gtk_about_dialog_get_name 
  381. --  No binding: gtk_about_dialog_set_name