------------------------------------------------------------------------------
-- --
-- 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/>. --
-- --
------------------------------------------------------------------------------
pragma Ada_2005;
pragma Warnings (Off, "*is already use-visible*");
with Gdk.Device; use Gdk.Device;
with Gdk.Event; use Gdk.Event;
with Gdk.Types; use Gdk.Types;
with Gtk.Widget; use Gtk.Widget;
with Pango.Language; use Pango.Language;
package Gtk.Main is
---------------
-- Callbacks --
---------------
type Gtk_Key_Snoop_Func is access function
(Grab_Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Event : Gdk.Event.Gdk_Event_Key) return Gint;
-- Key snooper functions are called before normal event delivery. They can
-- be used to implement custom key event handling.
-- "grab_widget": the widget to which the event will be delivered
-- "event": the key event
-------------
-- Methods --
-------------
function Key_Snooper_Install (Snooper : Gtk_Key_Snoop_Func) return Guint;
pragma Obsolescent (Key_Snooper_Install);
-- Installs a key snooper function, which will get called on all key
-- events before delivering them normally.
-- Deprecated since 3.4, Key snooping should not be done. Events should be
-- handled by widgets.
-- "snooper": a Gtk_Key_Snoop_Func
generic
type User_Data_Type (<>) is private;
with procedure Destroy (Data : in out User_Data_Type) is null;
package Key_Snooper_Install_User_Data is
type Gtk_Key_Snoop_Func is access function
(Grab_Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Event : Gdk.Event.Gdk_Event_Key;
Func_Data : User_Data_Type) return Gint;
-- Key snooper functions are called before normal event delivery. They can
-- be used to implement custom key event handling.
-- "grab_widget": the widget to which the event will be delivered
-- "event": the key event
-- "func_data": data supplied to Gtk.Main.Key_Snooper_Install
function Key_Snooper_Install
(Snooper : Gtk_Key_Snoop_Func;
Func_Data : User_Data_Type) return Guint;
pragma Obsolescent (Key_Snooper_Install);
-- Installs a key snooper function, which will get called on all key
-- events before delivering them normally.
-- Deprecated since 3.4, Key snooping should not be done. Events should
-- be handled by widgets.
-- "snooper": a Gtk_Key_Snoop_Func
-- "func_data": data to pass to Snooper
end Key_Snooper_Install_User_Data;
----------------------
-- GtkAda additions --
----------------------
procedure Init;
-- Initialize GtkAda's internal structures.
-- This subprogram should be called before any other one in GtkAda.
-- If GtkAda could not be initialized (no access to the display, etc.), the
-- application exits with an error
function Init_Check return Boolean;
-- Initialize GtkAda's internal structures.
-- Return False if there was an error (no access to the display, etc.)
---------------
-- Functions --
---------------
function Get_Major_Version return Guint;
-- Returns the major version number of the GTK+ library. (e.g. in GTK+
-- version 3.1.5 this is 3.)
-- This function is in the library, so it represents the GTK+ library your
-- code is running against. Contrast with the GTK_MAJOR_VERSION macro,
-- which represents the major version of the GTK+ headers you have included
-- when compiling your code.
-- Since: gtk+ 3.0
function Get_Minor_Version return Guint;
-- Returns the minor version number of the GTK+ library. (e.g. in GTK+
-- version 3.1.5 this is 1.)
-- This function is in the library, so it represents the GTK+ library your
-- code is are running against. Contrast with the GTK_MINOR_VERSION macro,
-- which represents the minor version of the GTK+ headers you have included
-- when compiling your code.
-- Since: gtk+ 3.0
function Get_Micro_Version return Guint;
-- Returns the micro version number of the GTK+ library. (e.g. in GTK+
-- version 3.1.5 this is 5.)
-- This function is in the library, so it represents the GTK+ library your
-- code is are running against. Contrast with the GTK_MICRO_VERSION macro,
-- which represents the micro version of the GTK+ headers you have included
-- when compiling your code.
-- Since: gtk+ 3.0
function Get_Binary_Age return Guint;
-- Returns the binary age as passed to <application>libtool</application>
-- when building the GTK+ library the process is running against. If
-- <application>libtool</application> means nothing to you, don't worry
-- about it.
-- Since: gtk+ 3.0
function Get_Interface_Age return Guint;
-- Returns the interface age as passed to
-- <application>libtool</application> when building the GTK+ library the
-- process is running against. If <application>libtool</application> means
-- nothing to you, don't worry about it.
-- Since: gtk+ 3.0
function Check_Version
(Required_Major : Guint;
Required_Minor : Guint;
Required_Micro : Guint) return UTF8_String;
-- Checks that the GTK+ library in use is compatible with the given
-- version. Generally you would pass in the constants GTK_MAJOR_VERSION,
-- GTK_MINOR_VERSION, GTK_MICRO_VERSION as the three arguments to this
-- function; that produces a check that the library in use is compatible
-- with the version of GTK+ the application or module was compiled against.
-- Compatibility is defined by two things: first the version of the
-- running library is newer than the version
-- Required_Major.required_minor.Required_Micro. Second the running library
-- must be binary compatible with the version
-- Required_Major.required_minor.Required_Micro (same major version.)
-- This function is primarily for GTK+ modules; the module can call this
-- function to check that it wasn't loaded into an incompatible version of
-- GTK+. However, such a check isn't completely reliable, since the module
-- may be linked against an old version of GTK+ and calling the old version
-- of Gtk.Main.Check_Version, but still get loaded into an application
-- using a newer version of GTK+.
-- "required_major": the required major version
-- "required_minor": the required minor version
-- "required_micro": the required micro version
procedure Disable_Setlocale;
-- Prevents gtk_init, gtk_init_check, gtk_init_with_args and
-- gtk_parse_args from automatically calling 'setlocale (LC_ALL, "")'. You
-- would want to use this function if you wanted to set the locale for your
-- program to something other than the user's locale, or if you wanted to
-- set different values for different locale categories.
-- Most programs should not need to call this function.
function Get_Default_Language return Pango.Language.Pango_Language;
-- Returns the Pango.Language.Pango_Language for the default language
-- currently in effect. (Note that this can change over the life of an
-- application.) The default language is derived from the current locale.
-- It determines, for example, whether GTK+ uses the right-to-left or
-- left-to-right text direction.
-- This function is equivalent to Pango.Language.Get_Default. See that
-- function for details.
function Events_Pending return Boolean;
-- Checks if any events are pending.
-- This can be used to update the UI and invoke timeouts etc. while doing
-- some time intensive computation.
-- == Updating the UI during a long computation ==
-- /* computation going on... */
-- while (gtk_events_pending ())
-- gtk_main_iteration ();
-- /* ...computation continued */
procedure Main_Do_Event (Event : Gdk.Event.Gdk_Event);
-- Processes a single GDK event.
-- This is public only to allow filtering of events between GDK and GTK+.
-- You will not usually need to call this function directly.
-- While you should not call this function directly, you might want to
-- know how exactly events are handled. So here is what this function does
-- with the event:
-- * Compress enter/leave notify events. If the event passed build an
-- enter/leave pair together with the next event (peeked from GDK), both
-- events are thrown away. This is to avoid a backlog of (de-)highlighting
-- widgets crossed by the pointer.
-- * Find the widget which got the event. If the widget can't be
-- determined the event is thrown away unless it belongs to a INCR
-- transaction.
-- * Then the event is pushed onto a stack so you can query the
-- currently handled event with Gtk.Main.Get_Current_Event.
-- * The event is sent to a widget. If a grab is active all events for
-- widgets that are not in the contained in the grab widget are sent to the
-- latter with a few exceptions:
-- * Deletion and destruction events are still sent to the event widget
-- for obvious reasons.
-- * Events which directly relate to the visual representation of the
-- event widget.
-- * Leave events are delivered to the event widget if there was an
-- enter event delivered to it before without the paired leave event.
-- * Drag events are not redirected because it is unclear what the
-- semantics of that would be. Another point of interest might be that all
-- key events are first passed through the key snooper functions if there
-- are any. Read the description of Gtk.Main.Key_Snooper_Install if you
-- need this feature.
-- * After finishing the delivery the event is popped from the event
-- stack.
-- "event": An event to process (normally passed by GDK)
procedure Main;
-- Runs the main loop until Gtk.Main.Main_Quit is called.
-- You can nest calls to Gtk.Main.Main. In that case Gtk.Main.Main_Quit
-- will make the innermost invocation of the main loop return.
function Main_Level return Guint;
-- Asks for the current nesting level of the main loop.
procedure Main_Quit;
-- Makes the innermost invocation of the main loop return when it regains
-- control.
function Main_Iteration return Boolean;
-- Runs a single iteration of the mainloop.
-- If no events are waiting to be processed GTK+ will block until the next
-- event is noticed. If you don't want to block look at
-- Gtk.Main.Main_Iteration_Do or check if any events are pending with
-- Gtk.Main.Events_Pending first.
function Main_Iteration_Do (Blocking : Boolean) return Boolean;
-- Runs a single iteration of the mainloop. If no events are available
-- either return or block depending on the value of Blocking.
-- "blocking": True if you want GTK+ to block if no events are pending
function True return Boolean;
-- All this function does it to return True.
-- This can be useful for example if you want to inhibit the deletion of a
-- window. Of course you should not do this as the user expects a reaction
-- from clicking the close icon of the window...
-- == A persistent window ==
-- include <gtk/gtk.h><
-- int
-- main (int argc, char **argv)
-- {
-- GtkWidget *win, *but;
-- gtk_init (&argc, &argv);
-- win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
-- g_signal_connect (win, "delete-event",
-- G_CALLBACK (gtk_true), NULL);
-- g_signal_connect (win, "destroy",
-- G_CALLBACK (gtk_main_quit), NULL);
-- but = gtk_button_new_with_label ("Close yourself. I mean it!");
-- g_signal_connect_swapped (but, "clicked",
-- G_CALLBACK (gtk_object_destroy), win);
-- gtk_container_add (GTK_CONTAINER (win), but);
-- gtk_widget_show_all (win);
-- gtk_main ();
-- return 0;
-- }
function False return Boolean;
-- Analogical to Gtk.Main.True, this function does nothing but always
-- returns False.
function Grab_Get_Current return Gtk.Widget.Gtk_Widget;
-- Queries the current grab of the default window group.
procedure Device_Grab_Add
(Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Device : not null access Gdk.Device.Gdk_Device_Record'Class;
Block_Others : Boolean);
-- Adds a GTK+ grab on Device, so all the events on Device and its
-- associated pointer or keyboard (if any) are delivered to Widget. If the
-- Block_Others parameter is True, any other devices will be unable to
-- interact with Widget during the grab.
-- Since: gtk+ 3.0
-- "widget": a Gtk.Widget.Gtk_Widget
-- "device": a Gdk.Device.Gdk_Device to grab on.
-- "block_others": True to prevent other devices to interact with Widget.
procedure Device_Grab_Remove
(Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Device : not null access Gdk.Device.Gdk_Device_Record'Class);
-- Removes a device grab from the given widget.
-- You have to pair calls to Gtk.Main.Device_Grab_Add and
-- Gtk.Main.Device_Grab_Remove.
-- Since: gtk+ 3.0
-- "widget": a Gtk.Widget.Gtk_Widget
-- "device": a Gdk.Device.Gdk_Device
procedure Key_Snooper_Remove (Snooper_Handler_Id : Guint);
pragma Obsolescent (Key_Snooper_Remove);
-- Removes the key snooper function with the given id.
-- Deprecated since 3.4, Key snooping should not be done. Events should be
-- handled by widgets.
-- "snooper_handler_id": Identifies the key snooper to remove
function Get_Current_Event return Gdk.Event.Gdk_Event;
-- Obtains a copy of the event currently being processed by GTK+.
-- For example, if you are handling a Gtk.Button.Gtk_Button::clicked
-- signal, the current event will be the Gdk.Event.Gdk_Event_Button that
-- triggered the ::clicked signal.
function Get_Current_Event_Time return Guint32;
-- If there is a current event and it has a timestamp, return that
-- timestamp, otherwise return GDK_CURRENT_TIME.
procedure Get_Current_Event_State
(State : out Gdk.Types.Gdk_Modifier_Type;
Has_Current_Event : out Boolean);
-- If there is a current event and it has a state field, place that state
-- field in State and return True, otherwise return False.
-- "state": a location to store the state of the current event
function Get_Current_Event_Device return Gdk.Device.Gdk_Device;
-- If there is a current event and it has a device, return that device,
-- otherwise return null.
function Get_Event_Widget
(Event : Gdk.Event.Gdk_Event) return Gtk.Widget.Gtk_Widget;
-- If Event is null or the event was not associated with any widget,
-- returns null, otherwise returns the widget that received the event
-- originally.
-- "event": a Gdk.Event.Gdk_Event
procedure Propagate_Event
(Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Event : Gdk.Event.Gdk_Event);
-- Sends an event to a widget, propagating the event to parent widgets if
-- the event remains unhandled.
-- Events received by GTK+ from GDK normally begin in
-- Gtk.Main.Main_Do_Event. Depending on the type of event, existence of
-- modal dialogs, grabs, etc., the event may be propagated; if so, this
-- function is used.
-- Gtk.Main.Propagate_Event calls Gtk.Widget.Event on each widget it
-- decides to send the event to. So Gtk.Widget.Event is the lowest-level
-- function; it simply emits the Gtk.Widget.Gtk_Widget::event and possibly
-- an event-specific signal on a widget. Gtk.Main.Propagate_Event is a bit
-- higher-level, and Gtk.Main.Main_Do_Event is the highest level.
-- All that said, you most likely don't want to use any of these
-- functions; synthesizing events is rarely needed. There are almost
-- certainly better ways to achieve your goals. For example, use
-- Gdk.Window.Invalidate_Rect or Gtk.Widget.Queue_Draw instead of making up
-- expose events.
-- "widget": a Gtk.Widget.Gtk_Widget
-- "event": an event
end Gtk.Main;