------------------------------------------------------------------------------ -- -- -- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet -- -- Copyright (C) 2000-2014, AdaCore -- -- -- -- This library is free software; you can redistribute it and/or modify it -- -- under terms of the GNU General Public License as published by the Free -- -- Software Foundation; either version 3, 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 MERCHAN- -- -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. -- -- -- -- As a special exception under Section 7 of GPL version 3, you are granted -- -- additional permissions described in the GCC Runtime Library Exception, -- -- version 3.1, as published by the Free Software Foundation. -- -- -- -- You should have received a copy of the GNU General Public License and -- -- a copy of the GCC Runtime Library Exception along with this program; -- -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- -- <http://www.gnu.org/licenses/>. -- -- -- ------------------------------------------------------------------------------ -- <description> -- Gtk.Application.Gtk_Application is a class that handles many important -- aspects of a GTK+ application in a convenient fashion, without enforcing a -- one-size-fits-all application model. -- -- Currently, GtkApplication handles GTK+ initialization, application -- uniqueness, session management, provides some basic scriptability and -- desktop shell integration by exporting actions and menus and manages a list -- of toplevel windows whose life-cycle is automatically tied to the -- life-cycle of your application. -- -- While GtkApplication works fine with plain Gtk_Windows, it is recommended -- to use it together with Gtk.Application_Window.Gtk_Application_Window. -- -- When GDK threads are enabled, GtkApplication will acquire the GDK lock -- when invoking actions that arrive from other processes. The GDK lock is not -- touched for local action invocations. In order to have actions invoked in a -- predictable context it is therefore recommended that the GDK lock be held -- while invoking actions locally with Glib.Action_Group.Activate_Action. The -- same applies to actions associated with -- Gtk.Application_Window.Gtk_Application_Window and to the 'activate' and -- 'open' Glib.Application.Gapplication methods. -- -- To set an application menu for a GtkApplication, use -- Gtk.Application.Set_App_Menu. The Glib.Menu_Model.Gmenu_Model that this -- function expects is usually constructed using Gtk.Builder.Gtk_Builder, as -- seen in the following example. To specify a menubar that will be shown by -- Gtk_Application_Windows, use Gtk.Application.Set_Menubar. Use the base -- Glib.Action_Map.Gaction_Map interface to add actions, to respond to the -- user selecting these menu items. -- -- GTK+ displays these menus as expected, depending on the platform the -- application is running on. -- -- <figure label="Menu integration in OS X"> <graphic -- fileref="bloatpad-osx.png" format="PNG"/> </figure> -- <figure label="Menu integration in GNOME"> <graphic -- fileref="bloatpad-gnome.png" format="PNG"/> </figure> -- <figure label="Menu integration in Xfce"> <graphic -- fileref="bloatpad-xfce.png" format="PNG"/> </figure> -- <example id="gtkapplication"> -- == A simple application == -- -- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c"> -- <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> -- </xi:include> -- GtkApplication optionally registers with a session manager of the users -- session (if you set the Gtk.Application.Gtk_Application:register-session -- property) and offers various functionality related to the session -- life-cycle. -- -- An application can block various ways to end the session with the -- Gtk.Application.Inhibit function. Typical use cases for this kind of -- inhibiting are long-running, uninterruptible operations, such as burning a -- CD or performing a disk backup. The session manager may not honor the -- inhibitor, but it can be expected to inform the user about the negative -- consequences of ending the session while inhibitors are present. -- -- </description> pragma Ada_2005; pragma Warnings (Off, "*is already use-visible*");
with GNAT.Strings; use GNAT.Strings;
with Glib; use Glib;
with Glib.Action; use Glib.Action;
with Glib.Action_Group; use Glib.Action_Group;
with Glib.Action_Map; use Glib.Action_Map;
with Glib.Application; use Glib.Application;
with Glib.Generic_Properties; use Glib.Generic_Properties;
with Glib.Menu_Model; use Glib.Menu_Model;
with Glib.Object; use Glib.Object;
with Glib.Properties; use Glib.Properties;
with Glib.Types; use Glib.Types;
with Glib.Variant; use Glib.Variant;
with Gtk.Widget; use Gtk.Widget;
with Gtk.Window; use Gtk.Window;
package Gtk.Application is
type Gtk_Application_Record is new Gapplication_Record with null record;
type Gtk_Application is access all Gtk_Application_Record'Class;
type Gtk_Application_Inhibit_Flags is mod 2 ** Integer'Size;
pragma Convention (C, Gtk_Application_Inhibit_Flags);
-- Types of user actions that may be blocked by Gtk.Application.Inhibit. Application_Inhibit_Logout : constant Gtk_Application_Inhibit_Flags := 1;
Application_Inhibit_Switch : constant Gtk_Application_Inhibit_Flags := 2;
Application_Inhibit_Suspend : constant Gtk_Application_Inhibit_Flags := 4;
Application_Inhibit_Idle : constant Gtk_Application_Inhibit_Flags := 8;
---------------------------- -- Enumeration Properties -- ---------------------------- package Gtk_Application_Inhibit_Flags_Properties is
new Generic_Internal_Discrete_Property (Gtk_Application_Inhibit_Flags);
type Property_Gtk_Application_Inhibit_Flags is new Gtk_Application_Inhibit_Flags_Properties.Property;
------------------ -- Constructors -- ------------------ procedure Gtk_New
(Self : out Gtk_Application;
Application_Id : UTF8_String := "";
Flags : Glib.Application.GApplication_Flags);
procedure Initialize
(Self : not null access Gtk_Application_Record'Class;
Application_Id : UTF8_String := "";
Flags : Glib.Application.GApplication_Flags);
-- Creates a new Gtk.Application.Gtk_Application instance. -- When using Gtk.Application.Gtk_Application, it is not necessary to call -- gtk_init manually. It is called as soon as the application gets -- registered as the primary instance. -- Concretely, gtk_init is called in the default handler for the -- Glib.Application.Gapplication::startup signal. Therefore, -- Gtk.Application.Gtk_Application subclasses should chain up in their -- Glib.Application.Gapplication:startup handler before using any GTK+ API. -- Note that commandline arguments are not passed to gtk_init. All GTK+ -- functionality that is available via commandline arguments can also be -- achieved by setting suitable environment variables such as -- <envar>G_DEBUG</envar>, so this should not be a big problem. If you -- absolutely must support GTK+ commandline arguments, you can explicitly -- call gtk_init before creating the application instance. -- If non-null, the application ID must be valid. See -- Glib.Application.Id_Is_Valid. -- If no application ID is given then some features (most notably -- application uniqueness) will be disabled. A null application ID is only -- allowed with GTK+ 3.6 or later. -- Since: gtk+ 3.0 -- "application_id": The application ID. -- "flags": the application flags function Gtk_Application_New
(Application_Id : UTF8_String := "";
Flags : Glib.Application.GApplication_Flags)
return Gtk_Application;
-- Creates a new Gtk.Application.Gtk_Application instance. -- When using Gtk.Application.Gtk_Application, it is not necessary to call -- gtk_init manually. It is called as soon as the application gets -- registered as the primary instance. -- Concretely, gtk_init is called in the default handler for the -- Glib.Application.Gapplication::startup signal. Therefore, -- Gtk.Application.Gtk_Application subclasses should chain up in their -- Glib.Application.Gapplication:startup handler before using any GTK+ API. -- Note that commandline arguments are not passed to gtk_init. All GTK+ -- functionality that is available via commandline arguments can also be -- achieved by setting suitable environment variables such as -- <envar>G_DEBUG</envar>, so this should not be a big problem. If you -- absolutely must support GTK+ commandline arguments, you can explicitly -- call gtk_init before creating the application instance. -- If non-null, the application ID must be valid. See -- Glib.Application.Id_Is_Valid. -- If no application ID is given then some features (most notably -- application uniqueness) will be disabled. A null application ID is only -- allowed with GTK+ 3.6 or later. -- Since: gtk+ 3.0 -- "application_id": The application ID. -- "flags": the application flags function Get_Type return Glib.GType;
pragma Import (C, Get_Type, "gtk_application_get_type");
------------- -- Methods -- ------------- procedure Add_Accelerator
(Self : not null access Gtk_Application_Record;
Accelerator : UTF8_String;
Action_Name : UTF8_String;
Parameter : Glib.Variant.Gvariant);
-- Installs an accelerator that will cause the named action to be -- activated when the key combination specificed by Accelerator is pressed. -- Accelerator must be a string that can be parsed by -- Gtk.Accel_Group.Accelerator_Parse, e.g. "<Primary>q" or -- "<Control><Alt>p". -- Action_Name must be the name of an action as it would be used in the -- app menu, i.e. actions that have been added to the application are -- referred to with an "app." prefix, and window-specific actions with a -- "win." prefix. -- GtkApplication also extracts accelerators out of 'accel' attributes in -- the GMenu_Models passed to Gtk.Application.Set_App_Menu and -- Gtk.Application.Set_Menubar, which is usually more convenient than -- calling this function for each accelerator. -- Since: gtk+ 3.4 -- "accelerator": accelerator string -- "action_name": the name of the action to activate -- "parameter": parameter to pass when activating the action, or null if -- the action does not accept an activation parameter procedure Add_Window
(Self : not null access Gtk_Application_Record;
Window : not null access Gtk.Window.Gtk_Window_Record'Class);
-- Adds a window to Application. -- This call is equivalent to setting the -- Gtk.Window.Gtk_Window:application property of Window to Application. -- Normally, the connection between the application and the window will -- remain until the window is destroyed, but you can explicitly remove it -- with Gtk.Application.Remove_Window. -- GTK+ will keep the application running as long as it has any windows. -- Since: gtk+ 3.0 -- "window": a Gtk.Window.Gtk_Window function Get_Active_Window
(Self : not null access Gtk_Application_Record)
return Gtk.Window.Gtk_Window;
-- Gets the "active" window for the application. -- The active window is the one that was most recently focused (within the -- application). This window may not have the focus at the moment if -- another application has it -- this is just the most recently-focused -- window within this application. -- Since: gtk+ 3.6 function Get_App_Menu
(Self : not null access Gtk_Application_Record)
return Glib.Menu_Model.Gmenu_Model;
-- Returns the menu model that has been set with -- Gtk.Application.Set_App_Menu. -- Since: gtk+ 3.4 procedure Set_App_Menu
(Self : not null access Gtk_Application_Record;
App_Menu : access Glib.Menu_Model.Gmenu_Model_Record'Class);
-- Sets or unsets the application menu for Application. -- This can only be done in the primary instance of the application, after -- it has been registered. Glib.Application.Gapplication:startup is a good -- place to call this. -- The application menu is a single menu containing items that typically -- impact the application as a whole, rather than acting on a specific -- window or document. For example, you would expect to see "Preferences" -- or "Quit" in an application menu, but not "Save" or "Print". -- If supported, the application menu will be rendered by the desktop -- environment. -- Use the base Glib.Action_Map.Gaction_Map interface to add actions, to -- respond to the user selecting these menu items. -- Since: gtk+ 3.4 -- "app_menu": a Glib.Menu_Model.Gmenu_Model, or null function Get_Menubar
(Self : not null access Gtk_Application_Record)
return Glib.Menu_Model.Gmenu_Model;
-- Returns the menu model that has been set with -- Gtk.Application.Set_Menubar. -- Since: gtk+ 3.4 procedure Set_Menubar
(Self : not null access Gtk_Application_Record;
Menubar : access Glib.Menu_Model.Gmenu_Model_Record'Class);
-- Sets or unsets the menubar for windows of Application. -- This is a menubar in the traditional sense. -- This can only be done in the primary instance of the application, after -- it has been registered. Glib.Application.Gapplication:startup is a good -- place to call this. -- Depending on the desktop environment, this may appear at the top of -- each window, or at the top of the screen. In some environments, if both -- the application menu and the menubar are set, the application menu will -- be presented as if it were the first item of the menubar. Other -- environments treat the two as completely separate -- for example, the -- application menu may be rendered by the desktop shell while the menubar -- (if set) remains in each individual window. -- Use the base Glib.Action_Map.Gaction_Map interface to add actions, to -- respond to the user selecting these menu items. -- Since: gtk+ 3.4 -- "menubar": a Glib.Menu_Model.Gmenu_Model, or null function Get_Window_By_Id
(Self : not null access Gtk_Application_Record;
Id : Guint) return Gtk.Window.Gtk_Window;
-- Returns the Gtk.Application_Window.Gtk_Application_Window with the -- given ID. -- Since: gtk+ 3.6 -- "id": an identifier number function Get_Windows
(Self : not null access Gtk_Application_Record)
return Gtk.Widget.Widget_List.Glist;
-- Gets a list of the Gtk_Windows associated with Application. -- The list is sorted by most recently focused window, such that the first -- element is the currently focused window. (Useful for choosing a parent -- for a transient window.) -- The list that is returned should not be modified in any way. It will -- only remain valid until the next focus change or window creation or -- deletion. -- Since: gtk+ 3.0 function Inhibit
(Self : not null access Gtk_Application_Record;
Window : access Gtk.Window.Gtk_Window_Record'Class;
Flags : Gtk_Application_Inhibit_Flags;
Reason : UTF8_String := "") return Guint;
-- Inform the session manager that certain types of actions should be -- inhibited. This is not guaranteed to work on all platforms and for all -- types of actions. -- Applications should invoke this method when they begin an operation -- that should not be interrupted, such as creating a CD or DVD. The types -- of actions that may be blocked are specified by the Flags parameter. -- When the application completes the operation it should call -- Gtk.Application.Uninhibit to remove the inhibitor. Note that an -- application can have multiple inhibitors, and all of the must be -- individually removed. Inhibitors are also cleared when the application -- exits. -- Applications should not expect that they will always be able to block -- the action. In most cases, users will be given the option to force the -- action to take place. -- Reasons should be short and to the point. -- If Window is given, the session manager may point the user to this -- window to find out more about why the action is inhibited. -- Since: gtk+ 3.4 -- "window": a Gtk.Window.Gtk_Window, or null -- "flags": what types of actions should be inhibited -- "reason": a short, human-readable string that explains why these -- operations are inhibited function Is_Inhibited
(Self : not null access Gtk_Application_Record;
Flags : Gtk_Application_Inhibit_Flags) return Boolean;
-- Determines if any of the actions specified in Flags are currently -- inhibited (possibly by another application). -- Since: gtk+ 3.4 -- "flags": what types of actions should be queried procedure Remove_Accelerator
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
Parameter : Glib.Variant.Gvariant);
-- Removes an accelerator that has been previously added with -- Gtk.Application.Add_Accelerator. -- Since: gtk+ 3.4 -- "action_name": the name of the action to activate -- "parameter": parameter to pass when activating the action, or null if -- the action does not accept an activation parameter procedure Remove_Window
(Self : not null access Gtk_Application_Record;
Window : not null access Gtk.Window.Gtk_Window_Record'Class);
-- Remove a window from Application. -- If Window belongs to Application then this call is equivalent to -- setting the Gtk.Window.Gtk_Window:application property of Window to -- null. -- The application may stop running as a result of a call to this -- function. -- Since: gtk+ 3.0 -- "window": a Gtk.Window.Gtk_Window procedure Uninhibit
(Self : not null access Gtk_Application_Record;
Cookie : Guint);
-- Removes an inhibitor that has been established with -- Gtk.Application.Inhibit. Inhibitors are also cleared when the -- application exits. -- Since: gtk+ 3.4 -- "cookie": a cookie that was returned by Gtk.Application.Inhibit --------------------------------------------- -- Inherited subprograms (from interfaces) -- --------------------------------------------- procedure Action_Added
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String);
procedure Action_Enabled_Changed
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
Enabled : Boolean);
procedure Action_Removed
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String);
procedure Action_State_Changed
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
State : Glib.Variant.Gvariant);
procedure Activate_Action
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
Parameter : Glib.Variant.Gvariant);
procedure Change_Action_State
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
Value : Glib.Variant.Gvariant);
function Get_Action_Enabled
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Boolean;
function Get_Action_Parameter_Type
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Glib.Variant.Gvariant_Type;
function Get_Action_State
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Glib.Variant.Gvariant;
function Get_Action_State_Hint
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Glib.Variant.Gvariant;
function Get_Action_State_Type
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Glib.Variant.Gvariant_Type;
function Has_Action
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Boolean;
function List_Actions
(Self : not null access Gtk_Application_Record)
return GNAT.Strings.String_List; function Query_Action
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String;
Enabled : access Boolean;
Parameter_Type : access Glib.Variant.Gvariant_Type;
State_Type : access Glib.Variant.Gvariant_Type;
State_Hint : access Glib.Variant.Gvariant;
State : access Glib.Variant.Gvariant) return Boolean;
procedure Add_Action
(Self : not null access Gtk_Application_Record;
Action : Glib.Action.Gaction);
procedure Add_Action_Entries
(Self : not null access Gtk_Application_Record;
Entries : GAction_Entry_Array;
User_Data : System.Address := System.Null_Address);
function Lookup_Action
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String) return Glib.Action.Gaction;
procedure Remove_Action
(Self : not null access Gtk_Application_Record;
Action_Name : UTF8_String);
---------------- -- Properties -- ---------------- -- The following properties are defined for this widget. See -- Glib.Properties for more information on properties) Active_Window_Property : constant Glib.Properties.Property_Object;
-- Type: Gtk.Window.Gtk_Window App_Menu_Property : constant Glib.Properties.Property_Boxed;
-- Type: Gio.Menu_Model Menubar_Property : constant Glib.Properties.Property_Boxed;
-- Type: Gio.Menu_Model Register_Session_Property : constant Glib.Properties.Property_Boolean;
-- Set this property to True to register with the session manager. ------------- -- Signals -- ------------- type Cb_Gtk_Application_Gtk_Window_Void is not null access procedure
(Self : access Gtk_Application_Record'Class;
Window : not null access Gtk.Window.Gtk_Window_Record'Class);
type Cb_GObject_Gtk_Window_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Window : not null access Gtk.Window.Gtk_Window_Record'Class);
Signal_Window_Added : constant Glib.Signal_Name := "window-added";
procedure On_Window_Added
(Self : not null access Gtk_Application_Record;
Call : Cb_Gtk_Application_Gtk_Window_Void;
After : Boolean := False);
procedure On_Window_Added
(Self : not null access Gtk_Application_Record;
Call : Cb_GObject_Gtk_Window_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- Emitted when a Gtk.Window.Gtk_Window is added to Application through -- Gtk.Application.Add_Window. Signal_Window_Removed : constant Glib.Signal_Name := "window-removed";
procedure On_Window_Removed
(Self : not null access Gtk_Application_Record;
Call : Cb_Gtk_Application_Gtk_Window_Void;
After : Boolean := False);
procedure On_Window_Removed
(Self : not null access Gtk_Application_Record;
Call : Cb_GObject_Gtk_Window_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- Emitted when a Gtk.Window.Gtk_Window is removed from Application, -- either as a side-effect of being destroyed or explicitly through -- Gtk.Application.Remove_Window. ---------------- -- Interfaces -- ---------------- -- This class implements several interfaces. See Glib.Types -- -- - "Gio.ActionGroup" -- -- - "Gio.ActionMap" package Implements_Gaction_Group is new Glib.Types.Implements
(Glib.Action_Group.Gaction_Group, Gtk_Application_Record, Gtk_Application);
function "+"
(Widget : access Gtk_Application_Record'Class)
return Glib.Action_Group.Gaction_Group
renames Implements_Gaction_Group.To_Interface;
function "-"
(Interf : Glib.Action_Group.Gaction_Group)
return Gtk_Application
renames Implements_Gaction_Group.To_Object;
package Implements_Gaction_Map is new Glib.Types.Implements
(Glib.Action_Map.Gaction_Map, Gtk_Application_Record, Gtk_Application);
function "+"
(Widget : access Gtk_Application_Record'Class)
return Glib.Action_Map.Gaction_Map
renames Implements_Gaction_Map.To_Interface;
function "-"
(Interf : Glib.Action_Map.Gaction_Map)
return Gtk_Application
renames Implements_Gaction_Map.To_Object;
private Register_Session_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("register-session");
Menubar_Property : constant Glib.Properties.Property_Boxed :=
Glib.Properties.Build ("menubar");
App_Menu_Property : constant Glib.Properties.Property_Boxed :=
Glib.Properties.Build ("app-menu");
Active_Window_Property : constant Glib.Properties.Property_Object :=
Glib.Properties.Build ("active-window");
end Gtk.Application;