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-2013, AdaCore                   -- 
  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. --  The Gtk_About_Dialog offers a simple way to display information about a 
  32. --  program like its logo, name, copyright, website and license. It is also 
  33. --  possible to give credits to the authors, documenters, translators and 
  34. --  artists who have worked on the program. An about dialog is typically opened 
  35. --  when the user selects the About option from the Help menu. All parts of the 
  36. --  dialog are optional. 
  37. -- 
  38. --  About dialog often contain links and email addresses. Gtk_About_Dialog 
  39. --  supports this by offering global hooks, which are called when the user 
  40. --  clicks on a link or email address, see Set_Email_Hook and Set_Url_Hook. 
  41. --  Email addresses in the authors, documenters and artists properties are 
  42. --  recognized by looking for <user@host>, URLs are recognized by looking for 
  43. --  http://url, with url extending to the next space, tab or line break. 
  44. -- 
  45. --  To make constructing a Gtk_About_Dialog as convenient as possible, you can 
  46. --  use the function gtk_show_about_dialog which constructs and shows a dialog 
  47. --  and keeps it around so that it can be shown again. 
  48. -- 
  49. --  </description> 
  50. --  <group>Windows</group> 
  51. --  <testgtk>create_about.adb</testgtk> 
  52.  
  53. pragma Warnings (Off, "*is already use-visible*"); 
  54. with GNAT.Strings;         use GNAT.Strings; 
  55. with Gdk.Pixbuf;           use Gdk.Pixbuf; 
  56. with Glib;                 use Glib; 
  57. with Glib.Properties;      use Glib.Properties; 
  58. with Glib.Types;           use Glib.Types; 
  59. with Gtk.Buildable;        use Gtk.Buildable; 
  60. with Gtk.Dialog;           use Gtk.Dialog; 
  61. with Gtk.Widget;           use Gtk.Widget; 
  62. with Interfaces.C.Strings; use Interfaces.C.Strings; 
  63.  
  64. package Gtk.About_Dialog is 
  65.  
  66.    type Gtk_About_Dialog_Record is new Gtk_Dialog_Record with null record; 
  67.    type Gtk_About_Dialog is access all Gtk_About_Dialog_Record'Class; 
  68.  
  69.    type Activate_Link_Func is access procedure 
  70.      (About : System.Address; 
  71.       Link  : Interfaces.C.Strings.chars_ptr; 
  72.       Data  : System.Address); 
  73.    pragma Convention (C, Activate_Link_Func); 
  74.    --  A callback called when the user presses an hyper link in the about 
  75.    --  dialog. This is a low-level function, and you'll need to convert the 
  76.    --  parameters to more useful types with: 
  77.    --     Stub : Gtk_About_Dialog_Record; 
  78.    --     A    : constant Gtk_About_Dialog := 
  79.    --       Gtk_About_Dialog (Get_User_Data (About, Stub)); 
  80.    --     L    : constant String := Interfaces.C.Strings.Value (Link); 
  81.  
  82.    ------------------ 
  83.    -- Constructors -- 
  84.    ------------------ 
  85.  
  86.    procedure Gtk_New (About : out Gtk_About_Dialog); 
  87.    procedure Initialize (About : access Gtk_About_Dialog_Record'Class); 
  88.    --  Creates a new Gtk.About_Dialog.Gtk_About_Dialog. 
  89.    --  Since: gtk+ 2.6 
  90.  
  91.    function Get_Type return Glib.GType; 
  92.    pragma Import (C, Get_Type, "gtk_about_dialog_get_type"); 
  93.  
  94.    ------------- 
  95.    -- Methods -- 
  96.    ------------- 
  97.  
  98.    function Get_Artists 
  99.       (About : access Gtk_About_Dialog_Record) 
  100.        return GNAT.Strings.String_List; 
  101.    procedure Set_Artists 
  102.       (About   : access Gtk_About_Dialog_Record; 
  103.        Artists : GNAT.Strings.String_List); 
  104.    --  Sets the strings which are displayed in the artists tab of the 
  105.    --  secondary credits dialog. 
  106.    --  Since: gtk+ 2.6 
  107.    --  "artists": a null-terminated array of strings 
  108.  
  109.    function Get_Authors 
  110.       (About : access Gtk_About_Dialog_Record) 
  111.        return GNAT.Strings.String_List; 
  112.    procedure Set_Authors 
  113.       (About   : access Gtk_About_Dialog_Record; 
  114.        Authors : GNAT.Strings.String_List); 
  115.    --  Sets the strings which are displayed in the authors tab of the 
  116.    --  secondary credits dialog. 
  117.    --  Since: gtk+ 2.6 
  118.    --  "authors": a null-terminated array of strings 
  119.  
  120.    function Get_Comments 
  121.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  122.    procedure Set_Comments 
  123.       (About    : access Gtk_About_Dialog_Record; 
  124.        Comments : UTF8_String); 
  125.    --  Sets the comments string to display in the about dialog. This should be 
  126.    --  a short string of one or two lines. 
  127.    --  Since: gtk+ 2.6 
  128.    --  "comments": a comments string 
  129.  
  130.    function Get_Copyright 
  131.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  132.    procedure Set_Copyright 
  133.       (About     : access Gtk_About_Dialog_Record; 
  134.        Copyright : UTF8_String); 
  135.    --  Sets the copyright string to display in the about dialog. This should 
  136.    --  be a short string of one or two lines. 
  137.    --  Since: gtk+ 2.6 
  138.    --  "copyright": (allow-none) the copyright string 
  139.  
  140.    function Get_Documenters 
  141.       (About : access Gtk_About_Dialog_Record) 
  142.        return GNAT.Strings.String_List; 
  143.    procedure Set_Documenters 
  144.       (About       : access Gtk_About_Dialog_Record; 
  145.        Documenters : GNAT.Strings.String_List); 
  146.    --  Sets the strings which are displayed in the documenters tab of the 
  147.    --  secondary credits dialog. 
  148.    --  Since: gtk+ 2.6 
  149.    --  "documenters": a null-terminated array of strings 
  150.  
  151.    function Get_License 
  152.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  153.    procedure Set_License 
  154.       (About   : access Gtk_About_Dialog_Record; 
  155.        License : UTF8_String); 
  156.    --  Sets the license information to be displayed in the secondary license 
  157.    --  dialog. If License is null, the license button is hidden. 
  158.    --  Since: gtk+ 2.6 
  159.    --  "license": the license information or null 
  160.  
  161.    function Get_Logo 
  162.       (About : access Gtk_About_Dialog_Record) return Gdk.Pixbuf.Gdk_Pixbuf; 
  163.    procedure Set_Logo 
  164.       (About : access Gtk_About_Dialog_Record; 
  165.        Logo  : access Gdk.Pixbuf.Gdk_Pixbuf_Record'Class); 
  166.    --  Sets the pixbuf to be displayed as logo in the about dialog. If it is 
  167.    --  null, the default window icon set with Gtk.Window.Set_Default_Icon will 
  168.    --  be used. 
  169.    --  Since: gtk+ 2.6 
  170.    --  "logo": a Gdk.Pixbuf.Gdk_Pixbuf, or null 
  171.  
  172.    function Get_Logo_Icon_Name 
  173.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  174.    procedure Set_Logo_Icon_Name 
  175.       (About     : access Gtk_About_Dialog_Record; 
  176.        Icon_Name : UTF8_String); 
  177.    --  Sets the pixbuf to be displayed as logo in the about dialog. If it is 
  178.    --  null, the default window icon set with Gtk.Window.Set_Default_Icon will 
  179.    --  be used. 
  180.    --  Since: gtk+ 2.6 
  181.    --  "icon_name": an icon name, or null 
  182.  
  183.    function Get_Name 
  184.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  185.    pragma Obsolescent (Get_Name); 
  186.    procedure Set_Name 
  187.       (About : access Gtk_About_Dialog_Record; 
  188.        Name  : UTF8_String); 
  189.    pragma Obsolescent (Set_Name); 
  190.    --  Sets the name to display in the about dialog. If this is not set, it 
  191.    --  defaults to g_get_application_name. 
  192.    --  Since: gtk+ 2.6 
  193.    --  Deprecated since 2.12, Use Gtk.About_Dialog.Set_Program_Name instead. 
  194.    --  "name": the program name 
  195.  
  196.    function Get_Program_Name 
  197.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  198.    procedure Set_Program_Name 
  199.       (About : access Gtk_About_Dialog_Record; 
  200.        Name  : UTF8_String); 
  201.    --  Sets the name to display in the about dialog. If this is not set, it 
  202.    --  defaults to g_get_application_name. 
  203.    --  Since: gtk+ 2.12 
  204.    --  "name": the program name 
  205.  
  206.    function Get_Translator_Credits 
  207.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  208.    procedure Set_Translator_Credits 
  209.       (About              : access Gtk_About_Dialog_Record; 
  210.        Translator_Credits : UTF8_String); 
  211.    --  Sets the translator credits string which is displayed in the 
  212.    --  translators tab of the secondary credits dialog. The intended use for 
  213.    --  this string is to display the translator of the language which is 
  214.    --  currently used in the user interface. Using gettext, a simple way to 
  215.    --  achieve that is to mark the string for translation: |[ 
  216.    --  gtk_about_dialog_set_translator_credits (about, 
  217.    --  _("translator-credits")); ]| It is a good idea to use the customary 
  218.    --  msgid "translator-credits" for this purpose, since translators will 
  219.    --  already know the purpose of that msgid, and since 
  220.    --  Gtk.About_Dialog.Gtk_About_Dialog will detect if "translator-credits" is 
  221.    --  untranslated and hide the tab. 
  222.    --  Since: gtk+ 2.6 
  223.    --  "translator_credits": the translator credits 
  224.  
  225.    function Get_Version 
  226.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  227.    procedure Set_Version 
  228.       (About   : access Gtk_About_Dialog_Record; 
  229.        Version : UTF8_String); 
  230.    --  Sets the version string to display in the about dialog. 
  231.    --  Since: gtk+ 2.6 
  232.    --  "version": the version string 
  233.  
  234.    function Get_Website 
  235.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  236.    procedure Set_Website 
  237.       (About   : access Gtk_About_Dialog_Record; 
  238.        Website : UTF8_String); 
  239.    --  Sets the URL to use for the website link. Note that that the hook 
  240.    --  functions need to be set up before calling this function. 
  241.    --  Since: gtk+ 2.6 
  242.    --  "website": a URL string starting with "http://" 
  243.  
  244.    function Get_Website_Label 
  245.       (About : access Gtk_About_Dialog_Record) return UTF8_String; 
  246.    procedure Set_Website_Label 
  247.       (About         : access Gtk_About_Dialog_Record; 
  248.        Website_Label : UTF8_String); 
  249.    --  Sets the label to be used for the website link. It defaults to the 
  250.    --  website URL. 
  251.    --  Since: gtk+ 2.6 
  252.    --  "website_label": the label used for the website link 
  253.  
  254.    function Get_Wrap_License 
  255.       (About : access Gtk_About_Dialog_Record) return Boolean; 
  256.    procedure Set_Wrap_License 
  257.       (About        : access Gtk_About_Dialog_Record; 
  258.        Wrap_License : Boolean); 
  259.    --  Sets whether the license text in About is automatically wrapped. 
  260.    --  Since: gtk+ 2.8 
  261.    --  "wrap_license": whether to wrap the license 
  262.  
  263.    --------------- 
  264.    -- Functions -- 
  265.    --------------- 
  266.  
  267.    function Set_Email_Hook 
  268.       (Func    : Activate_Link_Func; 
  269.        Data    : System.Address; 
  270.        Destroy : Glib.G_Destroy_Notify_Address) return Activate_Link_Func; 
  271.    pragma Obsolescent (Set_Email_Hook); 
  272.    --  Installs a global function to be called whenever the user activates an 
  273.    --  email link in an about dialog. Since 2.18 there exists a default 
  274.    --  function which uses gtk_show_uri(). To deactivate it, you can pass null 
  275.    --  for Func. 
  276.    --  Since: gtk+ 2.6 
  277.    --  Deprecated since 2.24, Use the 
  278.    --  Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal 
  279.    --  "func": a function to call when an email link is activated. 
  280.    --  "data": data to pass to Func 
  281.    --  "destroy": Glib.G_Destroy_Notify_Address for Data 
  282.  
  283.    function Set_Url_Hook 
  284.       (Func    : Activate_Link_Func; 
  285.        Data    : System.Address; 
  286.        Destroy : Glib.G_Destroy_Notify_Address) return Activate_Link_Func; 
  287.    pragma Obsolescent (Set_Url_Hook); 
  288.    --  Installs a global function to be called whenever the user activates a 
  289.    --  URL link in an about dialog. Since 2.18 there exists a default function 
  290.    --  which uses gtk_show_uri(). To deactivate it, you can pass null for Func. 
  291.    --  Since: gtk+ 2.6 
  292.    --  Deprecated since 2.24, Use the 
  293.    --  Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal 
  294.    --  "func": a function to call when a URL link is activated. 
  295.    --  "data": data to pass to Func 
  296.    --  "destroy": Glib.G_Destroy_Notify_Address for Data 
  297.  
  298.    ---------------- 
  299.    -- Interfaces -- 
  300.    ---------------- 
  301.    --  This class implements several interfaces. See Glib.Types 
  302.    -- 
  303.    --  - "Buildable" 
  304.  
  305.    package Implements_Buildable is new Glib.Types.Implements 
  306.      (Gtk.Buildable.Gtk_Buildable, Gtk_About_Dialog_Record, Gtk_About_Dialog); 
  307.    function "+" 
  308.      (Widget : access Gtk_About_Dialog_Record'Class) 
  309.    return Gtk.Buildable.Gtk_Buildable 
  310.    renames Implements_Buildable.To_Interface; 
  311.    function "-" 
  312.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  313.    return Gtk_About_Dialog 
  314.    renames Implements_Buildable.To_Object; 
  315.  
  316.    ---------------- 
  317.    -- Properties -- 
  318.    ---------------- 
  319.    --  The following properties are defined for this widget. See 
  320.    --  Glib.Properties for more information on properties) 
  321.    -- 
  322.    --  Name: Comments_Property 
  323.    --  Type: UTF8_String 
  324.    --  Flags: read-write 
  325.    --  Comments about the program. This string is displayed in a label in the 
  326.    --  main dialog, thus it should be a short explanation of the main purpose 
  327.    --  of the program, not a detailed list of features. 
  328.    -- 
  329.    --  Name: Copyright_Property 
  330.    --  Type: UTF8_String 
  331.    --  Flags: read-write 
  332.    --  Copyright information for the program. 
  333.    -- 
  334.    --  Name: License_Property 
  335.    --  Type: UTF8_String 
  336.    --  Flags: read-write 
  337.    --  The license of the program. This string is displayed in a text view in 
  338.    --  a secondary dialog, therefore it is fine to use a long multi-paragraph 
  339.    --  text. Note that the text is only wrapped in the text view if the 
  340.    --  "wrap-license" property is set to True; otherwise the text itself must 
  341.    --  contain the intended linebreaks. 
  342.    -- 
  343.    --  Name: Logo_Property 
  344.    --  Type: Gdk.Pixbuf.Gdk_Pixbuf 
  345.    --  Flags: read-write 
  346.    --  A logo for the about box. If this is not set, it defaults to 
  347.    --  gtk_window_get_default_icon_list. 
  348.    -- 
  349.    --  Name: Logo_Icon_Name_Property 
  350.    --  Type: UTF8_String 
  351.    --  Flags: read-write 
  352.    --  A named icon to use as the logo for the about box. This property 
  353.    --  overrides the Gtk.About_Dialog.Gtk_About_Dialog:logo property. 
  354.    -- 
  355.    --  Name: Program_Name_Property 
  356.    --  Type: UTF8_String 
  357.    --  Flags: read-write 
  358.    --  The name of the program. If this is not set, it defaults to 
  359.    --  g_get_application_name. 
  360.    -- 
  361.    --  Name: Translator_Credits_Property 
  362.    --  Type: UTF8_String 
  363.    --  Flags: read-write 
  364.    --  Credits to the translators. This string should be marked as 
  365.    --  translatable. The string may contain email addresses and URLs, which 
  366.    --  will be displayed as links, see the introduction for more details. 
  367.    -- 
  368.    --  Name: Version_Property 
  369.    --  Type: UTF8_String 
  370.    --  Flags: read-write 
  371.    --  The version of the program. 
  372.    -- 
  373.    --  Name: Website_Property 
  374.    --  Type: UTF8_String 
  375.    --  Flags: read-write 
  376.    --  The URL for the link to the website of the program. This should be a 
  377.    --  string starting with "http://. 
  378.    -- 
  379.    --  Name: Website_Label_Property 
  380.    --  Type: UTF8_String 
  381.    --  Flags: read-write 
  382.    --  The label for the link to the website of the program. If this is not 
  383.    --  set, it defaults to the URL specified in the 
  384.    --  Gtk.About_Dialog.Gtk_About_Dialog:website property. 
  385.    -- 
  386.    --  Name: Wrap_License_Property 
  387.    --  Type: Boolean 
  388.    --  Flags: read-write 
  389.    --  Whether to wrap the text in the license dialog. 
  390.  
  391.    Comments_Property : constant Glib.Properties.Property_String; 
  392.    Copyright_Property : constant Glib.Properties.Property_String; 
  393.    License_Property : constant Glib.Properties.Property_String; 
  394.    Logo_Property : constant Glib.Properties.Property_Object; 
  395.    Logo_Icon_Name_Property : constant Glib.Properties.Property_String; 
  396.    Program_Name_Property : constant Glib.Properties.Property_String; 
  397.    Translator_Credits_Property : constant Glib.Properties.Property_String; 
  398.    Version_Property : constant Glib.Properties.Property_String; 
  399.    Website_Property : constant Glib.Properties.Property_String; 
  400.    Website_Label_Property : constant Glib.Properties.Property_String; 
  401.    Wrap_License_Property : constant Glib.Properties.Property_Boolean; 
  402.  
  403.    ------------- 
  404.    -- Signals -- 
  405.    ------------- 
  406.    --  The following new signals are defined for this widget: 
  407.    -- 
  408.    --  "activate-link" 
  409.    --     function Handler 
  410.    --       (Self : access Gtk_About_Dialog_Record'Class; 
  411.    --        Uri  : UTF8_String) return Boolean; 
  412.    --    --  "uri": the URI that is activated 
  413.    --  The signal which gets emitted to activate a URI. Applications may 
  414.    --  connect to it to override the default behaviour, which is to call 
  415.    --  gtk_show_uri(). 
  416.    --  Returns True if the link has been activated 
  417.  
  418.    Signal_Activate_Link : constant Glib.Signal_Name := "activate-link"; 
  419.  
  420. private 
  421.    Comments_Property : constant Glib.Properties.Property_String := 
  422.      Glib.Properties.Build ("comments"); 
  423.    Copyright_Property : constant Glib.Properties.Property_String := 
  424.      Glib.Properties.Build ("copyright"); 
  425.    License_Property : constant Glib.Properties.Property_String := 
  426.      Glib.Properties.Build ("license"); 
  427.    Logo_Property : constant Glib.Properties.Property_Object := 
  428.      Glib.Properties.Build ("logo"); 
  429.    Logo_Icon_Name_Property : constant Glib.Properties.Property_String := 
  430.      Glib.Properties.Build ("logo-icon-name"); 
  431.    Program_Name_Property : constant Glib.Properties.Property_String := 
  432.      Glib.Properties.Build ("program-name"); 
  433.    Translator_Credits_Property : constant Glib.Properties.Property_String := 
  434.      Glib.Properties.Build ("translator-credits"); 
  435.    Version_Property : constant Glib.Properties.Property_String := 
  436.      Glib.Properties.Build ("version"); 
  437.    Website_Property : constant Glib.Properties.Property_String := 
  438.      Glib.Properties.Build ("website"); 
  439.    Website_Label_Property : constant Glib.Properties.Property_String := 
  440.      Glib.Properties.Build ("website-label"); 
  441.    Wrap_License_Property : constant Glib.Properties.Property_Boolean := 
  442.      Glib.Properties.Build ("wrap-license"); 
  443. end Gtk.About_Dialog;