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