----------------------------------------------------------------------- -- GtkAda - Ada95 binding for Gtk+/Gnome -- -- -- -- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet -- -- Copyright (C) 2000-2011, AdaCore -- -- -- -- This library is free software; you can redistribute it and/or -- -- modify it under the terms of the GNU General Public -- -- License as published by the Free Software Foundation; either -- -- version 2 of the License, or (at your option) any later version. -- -- -- -- This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- -- General Public License for more details. -- -- -- -- You should have received a copy of the GNU General Public -- -- License along with this library; if not, write to the -- -- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- -- Boston, MA 02111-1307, USA. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ----------------------------------------------------------------------- -- -- The Gtk_About_Dialog offers a simple way to display information about a -- program like its logo, name, copyright, website and license. It is also -- possible to give credits to the authors, documenters, translators and -- artists who have worked on the program. An about dialog is typically opened -- when the user selects the About option from the Help menu. All parts of the -- dialog are optional. -- -- About dialog often contain links and email addresses. Gtk_About_Dialog -- supports this by offering global hooks, which are called when the user -- clicks on a link or email address, see Set_Email_Hook and Set_Url_Hook. -- Email addresses in the authors, documenters and artists properties are -- recognized by looking for , URLs are recognized by looking for -- http://url, with url extending to the next space, tab or line break. -- -- To make constructing a Gtk_About_Dialog as convenient as possible, you can -- use the function gtk_show_about_dialog which constructs and shows a dialog -- and keeps it around so that it can be shown again. -- -- -- Windows -- create_about.adb pragma Warnings (Off, "*is already use-visible*"); with GNAT.Strings; use GNAT.Strings; with Gdk.Pixbuf; use Gdk.Pixbuf; with Glib; use Glib; with Glib.Properties; use Glib.Properties; with Glib.Types; use Glib.Types; with Gtk.Buildable; use Gtk.Buildable; with Gtk.Dialog; use Gtk.Dialog; with Gtk.Widget; use Gtk.Widget; with Interfaces.C.Strings; use Interfaces.C.Strings; package Gtk.About_Dialog is type Gtk_About_Dialog_Record is new Gtk_Dialog_Record with null record; type Gtk_About_Dialog is access all Gtk_About_Dialog_Record'Class; type Activate_Link_Func is access procedure (About : System.Address; Link : Interfaces.C.Strings.chars_ptr; Data : System.Address); pragma Convention (C, Activate_Link_Func); -- A callback called when the user presses an hyper link in the about -- dialog. This is a low-level function, and you'll need to convert the -- parameters to more useful types with: -- Stub : Gtk_About_Dialog_Record; -- A : constant Gtk_About_Dialog := -- Gtk_About_Dialog (Get_User_Data (About, Stub)); -- L : constant String := Interfaces.C.Strings.Value (Link); ------------------ -- Constructors -- ------------------ procedure Gtk_New (About : out Gtk_About_Dialog); procedure Initialize (About : access Gtk_About_Dialog_Record'Class); -- Creates a new Gtk.About_Dialog.Gtk_About_Dialog. -- Since: gtk+ 2.6 function Get_Type return Glib.GType; pragma Import (C, Get_Type, "gtk_about_dialog_get_type"); ------------- -- Methods -- ------------- function Get_Artists (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; procedure Set_Artists (About : access Gtk_About_Dialog_Record; Artists : GNAT.Strings.String_List); -- Sets the strings which are displayed in the artists tab of the -- secondary credits dialog. -- Since: gtk+ 2.6 -- "artists": a null-terminated array of strings function Get_Authors (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; procedure Set_Authors (About : access Gtk_About_Dialog_Record; Authors : GNAT.Strings.String_List); -- Sets the strings which are displayed in the authors tab of the -- secondary credits dialog. -- Since: gtk+ 2.6 -- "authors": a null-terminated array of strings function Get_Comments (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Comments (About : access Gtk_About_Dialog_Record; Comments : UTF8_String); -- Sets the comments string to display in the about dialog. This should be -- a short string of one or two lines. -- Since: gtk+ 2.6 -- "comments": a comments string function Get_Copyright (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Copyright (About : access Gtk_About_Dialog_Record; Copyright : UTF8_String); -- Sets the copyright string to display in the about dialog. This should -- be a short string of one or two lines. -- Since: gtk+ 2.6 -- "copyright": (allow-none) the copyright string function Get_Documenters (About : access Gtk_About_Dialog_Record) return GNAT.Strings.String_List; procedure Set_Documenters (About : access Gtk_About_Dialog_Record; Documenters : GNAT.Strings.String_List); -- Sets the strings which are displayed in the documenters tab of the -- secondary credits dialog. -- Since: gtk+ 2.6 -- "documenters": a null-terminated array of strings function Get_License (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_License (About : access Gtk_About_Dialog_Record; License : UTF8_String); -- Sets the license information to be displayed in the secondary license -- dialog. If License is null, the license button is hidden. -- Since: gtk+ 2.6 -- "license": the license information or null function Get_Logo (About : access Gtk_About_Dialog_Record) return Gdk.Pixbuf.Gdk_Pixbuf; procedure Set_Logo (About : access Gtk_About_Dialog_Record; Logo : access Gdk.Pixbuf.Gdk_Pixbuf_Record'Class); -- Sets the pixbuf to be displayed as logo in the about dialog. If it is -- null, the default window icon set with Gtk.Window.Set_Default_Icon will -- be used. -- Since: gtk+ 2.6 -- "logo": a Gdk.Pixbuf.Gdk_Pixbuf, or null function Get_Logo_Icon_Name (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Logo_Icon_Name (About : access Gtk_About_Dialog_Record; Icon_Name : UTF8_String); -- Sets the pixbuf to be displayed as logo in the about dialog. If it is -- null, the default window icon set with Gtk.Window.Set_Default_Icon will -- be used. -- Since: gtk+ 2.6 -- "icon_name": an icon name, or null function Get_Name (About : access Gtk_About_Dialog_Record) return UTF8_String; pragma Obsolescent (Get_Name); procedure Set_Name (About : access Gtk_About_Dialog_Record; Name : UTF8_String); pragma Obsolescent (Set_Name); -- Sets the name to display in the about dialog. If this is not set, it -- defaults to g_get_application_name. -- Since: gtk+ 2.6 -- Deprecated since 2.12, Use Gtk.About_Dialog.Set_Program_Name instead. -- "name": the program name function Get_Program_Name (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Program_Name (About : access Gtk_About_Dialog_Record; Name : UTF8_String); -- Sets the name to display in the about dialog. If this is not set, it -- defaults to g_get_application_name. -- Since: gtk+ 2.12 -- "name": the program name function Get_Translator_Credits (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Translator_Credits (About : access Gtk_About_Dialog_Record; Translator_Credits : UTF8_String); -- Sets the translator credits string which is displayed in the -- translators tab of the secondary credits dialog. The intended use for -- this string is to display the translator of the language which is -- currently used in the user interface. Using gettext, a simple way to -- achieve that is to mark the string for translation: |[ -- gtk_about_dialog_set_translator_credits (about, -- _("translator-credits")); ]| It is a good idea to use the customary -- msgid "translator-credits" for this purpose, since translators will -- already know the purpose of that msgid, and since -- Gtk.About_Dialog.Gtk_About_Dialog will detect if "translator-credits" is -- untranslated and hide the tab. -- Since: gtk+ 2.6 -- "translator_credits": the translator credits function Get_Version (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Version (About : access Gtk_About_Dialog_Record; Version : UTF8_String); -- Sets the version string to display in the about dialog. -- Since: gtk+ 2.6 -- "version": the version string function Get_Website (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Website (About : access Gtk_About_Dialog_Record; Website : UTF8_String); -- Sets the URL to use for the website link. Note that that the hook -- functions need to be set up before calling this function. -- Since: gtk+ 2.6 -- "website": a URL string starting with "http://" function Get_Website_Label (About : access Gtk_About_Dialog_Record) return UTF8_String; procedure Set_Website_Label (About : access Gtk_About_Dialog_Record; Website_Label : UTF8_String); -- Sets the label to be used for the website link. It defaults to the -- website URL. -- Since: gtk+ 2.6 -- "website_label": the label used for the website link function Get_Wrap_License (About : access Gtk_About_Dialog_Record) return Boolean; procedure Set_Wrap_License (About : access Gtk_About_Dialog_Record; Wrap_License : Boolean); -- Sets whether the license text in About is automatically wrapped. -- Since: gtk+ 2.8 -- "wrap_license": whether to wrap the license --------------- -- Functions -- --------------- function Set_Email_Hook (Func : Activate_Link_Func; Data : System.Address; Destroy : Glib.G_Destroy_Notify_Address) return Activate_Link_Func; pragma Obsolescent (Set_Email_Hook); -- Installs a global function to be called whenever the user activates an -- email link in an about dialog. Since 2.18 there exists a default -- function which uses gtk_show_uri(). To deactivate it, you can pass null -- for Func. -- Since: gtk+ 2.6 -- Returns the previous email hook. -- Deprecated since 2.24, Use the -- Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal -- "func": a function to call when an email link is activated. -- "data": data to pass to Func -- "destroy": Glib.G_Destroy_Notify_Address for Data function Set_Url_Hook (Func : Activate_Link_Func; Data : System.Address; Destroy : Glib.G_Destroy_Notify_Address) return Activate_Link_Func; pragma Obsolescent (Set_Url_Hook); -- Installs a global function to be called whenever the user activates a -- URL link in an about dialog. Since 2.18 there exists a default function -- which uses gtk_show_uri(). To deactivate it, you can pass null for Func. -- Since: gtk+ 2.6 -- Returns the previous URL hook. -- Deprecated since 2.24, Use the -- Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal -- "func": a function to call when a URL link is activated. -- "data": data to pass to Func -- "destroy": Glib.G_Destroy_Notify_Address for Data ---------------- -- Interfaces -- ---------------- -- This class implements several interfaces. See Glib.Types -- -- - "Buildable" package Implements_Buildable is new Glib.Types.Implements (Gtk.Buildable.Gtk_Buildable, Gtk_About_Dialog_Record, Gtk_About_Dialog); function "+" (Widget : access Gtk_About_Dialog_Record'Class) return Gtk.Buildable.Gtk_Buildable renames Implements_Buildable.To_Interface; function "-" (Interf : Gtk.Buildable.Gtk_Buildable) return Gtk_About_Dialog renames Implements_Buildable.To_Object; ---------------- -- Properties -- ---------------- -- The following properties are defined for this widget. See -- Glib.Properties for more information on properties) -- -- Name: Comments_Property -- Type: UTF8_String -- Flags: read-write -- Comments about the program. This string is displayed in a label in the -- main dialog, thus it should be a short explanation of the main purpose -- of the program, not a detailed list of features. -- -- Name: Copyright_Property -- Type: UTF8_String -- Flags: read-write -- Copyright information for the program. -- -- Name: License_Property -- Type: UTF8_String -- Flags: read-write -- The license of the program. This string is displayed in a text view in -- a secondary dialog, therefore it is fine to use a long multi-paragraph -- text. Note that the text is only wrapped in the text view if the -- "wrap-license" property is set to True; otherwise the text itself must -- contain the intended linebreaks. -- -- Name: Logo_Property -- Type: Gdk.Pixbuf.Gdk_Pixbuf -- Flags: read-write -- A logo for the about box. If this is not set, it defaults to -- gtk_window_get_default_icon_list. -- -- Name: Logo_Icon_Name_Property -- Type: UTF8_String -- Flags: read-write -- A named icon to use as the logo for the about box. This property -- overrides the Gtk.About_Dialog.Gtk_About_Dialog:logo property. -- -- Name: Program_Name_Property -- Type: UTF8_String -- Flags: read-write -- The name of the program. If this is not set, it defaults to -- g_get_application_name. -- -- Name: Translator_Credits_Property -- Type: UTF8_String -- Flags: read-write -- Credits to the translators. This string should be marked as -- translatable. The string may contain email addresses and URLs, which -- will be displayed as links, see the introduction for more details. -- -- Name: Version_Property -- Type: UTF8_String -- Flags: read-write -- The version of the program. -- -- Name: Website_Property -- Type: UTF8_String -- Flags: read-write -- The URL for the link to the website of the program. This should be a -- string starting with "http://. -- -- Name: Website_Label_Property -- Type: UTF8_String -- Flags: read-write -- The label for the link to the website of the program. If this is not -- set, it defaults to the URL specified in the -- Gtk.About_Dialog.Gtk_About_Dialog:website property. -- -- Name: Wrap_License_Property -- Type: Boolean -- Flags: read-write -- Whether to wrap the text in the license dialog. Comments_Property : constant Glib.Properties.Property_String; Copyright_Property : constant Glib.Properties.Property_String; License_Property : constant Glib.Properties.Property_String; Logo_Property : constant Glib.Properties.Property_Object; Logo_Icon_Name_Property : constant Glib.Properties.Property_String; Program_Name_Property : constant Glib.Properties.Property_String; Translator_Credits_Property : constant Glib.Properties.Property_String; Version_Property : constant Glib.Properties.Property_String; Website_Property : constant Glib.Properties.Property_String; Website_Label_Property : constant Glib.Properties.Property_String; Wrap_License_Property : constant Glib.Properties.Property_Boolean; ------------- -- Signals -- ------------- -- The following new signals are defined for this widget: -- -- "activate-link" -- function Handler -- (Self : access Gtk_About_Dialog_Record'Class; -- Uri : UTF8_String) return Boolean; -- -- "uri": the URI that is activated -- The signal which gets emitted to activate a URI. Applications may -- connect to it to override the default behaviour, which is to call -- gtk_show_uri(). -- Returns True if the link has been activated Signal_Activate_Link : constant Glib.Signal_Name := "activate-link"; private Comments_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("comments"); Copyright_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("copyright"); License_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("license"); Logo_Property : constant Glib.Properties.Property_Object := Glib.Properties.Build ("logo"); Logo_Icon_Name_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("logo-icon-name"); Program_Name_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("program-name"); Translator_Credits_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("translator-credits"); Version_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("version"); Website_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("website"); Website_Label_Property : constant Glib.Properties.Property_String := Glib.Properties.Build ("website-label"); Wrap_License_Property : constant Glib.Properties.Property_Boolean := Glib.Properties.Build ("wrap-license"); end Gtk.About_Dialog;