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