This is gtkada_rm.info, produced by makeinfo version 4.5 from
gtkada_rm.texi.

INFO-DIR-SECTION User Interface Toolkit
START-INFO-DIR-ENTRY
* GtkAda_Rm: (gtkada_rm).           Ada95 graphical tookit based on GTK+ (Reference Manual)
END-INFO-DIR-ENTRY


File: gtkada_rm.info,  Node: Gtk.Label Subprograms,  Prev: Gtk.Label Widget Hierarchy,  Up: Package_Gtk.Label

Subprograms
===========

procedure Gtk_New
       (Label              : out    Gtk_Label;
        Str                :        UTF8_String := "");

Create a new label.
Str is the string to be displayed.
procedure Gtk_New_With_Mnemonic
       (Label              : out    Gtk_Label;
        Str                :        UTF8_String);

Create a new label containing the text in Str.
If characters in Str are preceded by an underscore, they are underlined
indicating that they represent a keyboard accelerator called a
mnemonic.   The mnemonic key can be used to activate another widget,
chosen  automatically or explicitely using Set_Mnemonic_Widget.
procedure Initialize_With_Mnemonic
       (Label              : access Gtk_Label_Record'Class;
        Str                :        UTF8_String);

Internal initialization function.
function Get_Justify
       (Label              : access Gtk_Label_Record)
        return Enums.Gtk_Justification;

Returns the justification of the label. See Set_Justify.
function Get_Line_Wrap
       (Label              : access Gtk_Label_Record)
        return Boolean;

Returns True if the lines of the label are automatically wrapped.
function Get_Selectable
       (Label              : access Gtk_Label_Record)
        return Boolean;

Returns True if the user can copy text from the label.
function Get_Type              return Glib.GType;


Return the internal value associated with a Gtk_Label.
function Get_Use_Markup
       (Label              : access Gtk_Label_Record)
        return Boolean;

Return True if the label's text will be parsed for markup.
function Get_Use_Underline
       (Label              : access Gtk_Label_Record)
        return Boolean;

Return True whether an embedded underline in the label indicates
the mnemonic accelerator keys.
function Get_Mnemonic_Keyval
       (Label              : access Gtk_Label_Record)
        return Gdk.Types.Gdk_Key_Type;

Return the key value of the mnemonic accelerator key indicated by an
embedded underline in the label. If there is no mnemonic set up it
returns Gdk.Types.Keysyms.GDK_VoidSymbol.
procedure Set_Text
       (Label              : access Gtk_Label_Record;
        Str                :        UTF8_String);

Change the text of the label.
The new text is visible on the screen at once. Note that the underline
pattern is not modified.
procedure Set_Text_With_Mnemonic
       (Label              : access Gtk_Label_Record;
        Str                :        UTF8_String);

Change the text and mnemonic key of the label.
The new text and mnemonic are visible on the screen at once.   The
mnemonic key can be used to activate another widget, chosen
automatically or explicitely using Set_Mnemonic_Widget.
function Get_Text
       (Label              : access Gtk_Label_Record)
        return UTF8_String;

Get the current value of the text displayed in the label.
procedure Set_Markup
       (Label              : access Gtk_Label_Record;
        Str                :        UTF8_String);

Parses Str which is marked up with the Pango text markup language,
setting the label's text and attribute list based on the parse results.
procedure Set_Markup_With_Mnemonic
       (Label              : access Gtk_Label_Record;
        Str                :        UTF8_String);

Parse Str which is marked up with the Pango text markup language,
setting the label's text and attribute list based on the parse results.
If characters in Str are preceded by an underscore, they are underlined
indicating that they represent a mnemonic.   The mnemonic key can be
used to activate another widget, chosen  automatically or explicitely
using Set_Mnemonic_Widget.
procedure Set_Mnemonic_Widget
       (Label              : access Gtk_Label_Record;
        Widget             : access Gtk.Widget.Gtk_Widget_Record'Class);

If the label has been set so that it has an mnemonic key, the label can
be associated with a widget that is the target of the mnemonic.   When
the label is inside a widget (like a Gtk_Button or a Gtk_Notebook
tab), it is automatically associated with the correct widget, but
sometimes (i.e. when the target is a Gtk_Entry next to the label),  you
need to set it explicitly using this procedure.   The target widget
will be accelerated by emitting "mnemonic_activate"  on it. The default
handler for this signal will activate the widget if  there are no
mnemonic collisions and toggle focus between the colliding  widgets
otherwise.
procedure Select_Region
       (Label              : access Gtk_Label_Record;
        Start_Offset       :        Integer := -1;
        End_Offset         :        Integer := -1);

Selects a range of characters in the label, if the label is
selectable.  If Start or End are -1, then the end of the label  will be
substituted.
procedure Set_Justify
       (Label              : access Gtk_Label_Record;
        Jtype              :        Enums.Gtk_Justification);

Set the justification for the label.
The default value is Justify_Center, which means that the text will be
centered in the label. Note that this setting has an impact only when
the Gtk_Label is larger than the text (its default width is the same
as the text) and contains multiple lines.   To justify a single line
label, you should instead call Set_Alignment  and make sure that the
label or any surrounding container fills its  horizontal allocated
space.
procedure Set_Pattern
       (Label              : access Gtk_Label_Record;
        Pattern            :        String);

Change the underlines pattern.
Pattern is a simple string made of underscore and space characters,
matching the ones in the string. GtkAda will underline every letter
that matches an underscore.   An empty string disables the underlines.
example: If the text is FooBarBaz and the Pattern is "___   ___"  then
both "Foo" and "Baz" will be underlined, but not "Bar".
procedure Set_Selectable
       (Label              : access Gtk_Label_Record;
        Selectable         :        Boolean);

Selectable labels allow the user to select text from the label,
for copy-and-paste.
procedure Set_Line_Wrap
       (Label              : access Gtk_Label_Record;
        Wrap               :        Boolean);

Toggle line wrapping within Label.
if Wrap is True, then Label will break lines if the text is larger
then the widget's size. If Wrap is False, then the text is simply  cut
off.
procedure Set_Use_Markup
       (Label              : access Gtk_Label_Record;
        Markup             :        Boolean);

Sets whether the text of the label contains markup in Pango's
text markup language.  If Markup is True, then Label will be  parsed
for markup.
procedure Set_Use_Underline
       (Label              : access Gtk_Label_Record;
        Underline          :        Boolean);

Sets whether the text of the label should be underlined.
If Underline is True, then Label will be underlined.

File: gtkada_rm.info,  Node: Package_Gtk.Layout,  Next: Package_Gtk.Main,  Prev: Package_Gtk.Label,  Up: Top

Package Gtk.Layout
******************

A Gtk_Layout is a widget that can have an almost infinite size, without
occupying a lot of memory. Its children can be located anywhere within
it, but will only appear on the screen if the visible area of the
layout  contains them.   Just like a Gtk_Viewport, its visible area is
indicated by two  Gtk_Adjustment widgets, and thus a Gtk_Layout can be
put as is in a  Gtk_Scrolled_Window.   As for Gtk_Fixed containers, the
children can be located anywhere in the  layout (no automatic
organization is done). But, as opposed to Gtk_Fixed  widgets, a
Gtk_Layout does not try to resize itself to show all its  children.

   Starting from GtkAda 2.0, you have to call Set_Size and specify the
maximum  size of the layout, otherwise children added with Put outside
the size  defined for the layout will never be visible.   One way to do
this is to systematically call Set_Size before calling Put,  and make
sure you specify a size big enough for the layout.

* Menu:

* Gtk.Layout Widget Hierarchy::
* Gtk.Layout Signals::
* Gtk.Layout Subprograms::


File: gtkada_rm.info,  Node: Gtk.Layout Widget Hierarchy,  Next: Gtk.Layout Signals,  Up: Package_Gtk.Layout

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Container      (*note Package_Gtk.Container::)
              \___ Gtk_Layout      (*note Package_Gtk.Layout::)


File: gtkada_rm.info,  Node: Gtk.Layout Signals,  Next: Gtk.Layout Subprograms,  Prev: Gtk.Layout Widget Hierarchy,  Up: Package_Gtk.Layout

Signals
=======

   * "set_scroll_adjustments"

     procedure Handler (Layout : access Gtk_Layout_Record'Class;
     Hadj   : in Gtk.Adjustment.Gtk_Adjustment;
     Vadj   : in Gtk.Adjustment.Gtk_Adjustment);
     Emitted whenever at least one of the adjustment of the layout is
     changed.



File: gtkada_rm.info,  Node: Gtk.Layout Subprograms,  Prev: Gtk.Layout Signals,  Up: Package_Gtk.Layout

Subprograms
===========

procedure Gtk_New
       (Layout             : out    Gtk_Layout;
        Hadjustment        :        Adjustment.Gtk_Adjustment
                            := Adjustment.Null_Adjustment;
        Vadjustment        :        Adjustment.Gtk_Adjustment
                            := Adjustment.Null_Adjustment);

Create new layout.
You can either give an explicit couple of adjustments, that will
indicate the current visible area. If you don't specify any, they will
be created automatically by GtkAda, which is the usual way to do.   The
Layout does not occupy any area on the screen, and you have to
explicitly specify one with Set_Size below.
function Get_Type              return Gtk.Gtk_Type;


Return the internal value associated with a Gtk_Layout.
procedure Put
       (Layout             : access Gtk_Layout_Record;
        Widget             : access Gtk.Widget.Gtk_Widget_Record'Class;
        X                  :        Gint;
        Y                  :        Gint);

Insert a new child in the layout.
The child will be displayed on the screen only if at least part of  it
intersects the visible area of the layout.   The layout does not resize
itself to automatically show the widget.   You also need to call
Set_Size, if the size you initially defined is  smaller than (X, Y), or
the child will never be visible even if the  layout is scrolled.
procedure Move
       (Layout             : access Gtk_Layout_Record;
        Widget             : access Gtk.Widget.Gtk_Widget_Record'Class;
        X                  :        Gint;
        Y                  :        Gint);

Move a child of the layout.
Nothing is done if Widget is not already a child of Layout.
function Get_Bin_Window
       (Widget             : access Gtk_Layout_Record)
        return Gdk.Window.Gdk_Window;

Return the window associated with the layout.
You should use this one rather than Gtk.Widget.Get_Window.
procedure Set_Size
       (Layout             : access Gtk_Layout_Record;
        Width              :        Guint;
        Height             :        Guint);

Specify an absolute size for the layout.
This is not the size on the screen, but the internal size of the widget.
The screen's size can be set with Gtk.Widget.Set_Usize.
procedure Get_Size
       (Layout             : access Gtk_Layout_Record;
        Width              : out    Guint;
        Height             : out    Guint);

Get the current size in pixels of the layout, as set with Set_Size
function Get_Hadjustment
       (Layout             : access Gtk_Layout_Record)
        return Gtk.Adjustment.Gtk_Adjustment;

Return the adjustment that indicate the horizontal visual area
of the layout.   You generally do not have to modify the value of this
adjustment  yourself, since this is done automatically when the layout
has  been put in a Gtk_Scrolled_Window.
function Get_Vadjustment
       (Layout             : access Gtk_Layout_Record)
        return Gtk.Adjustment.Gtk_Adjustment;

Return the adjustment that indicate the vertical visual area
of the layout.   You generally do not have to modify the value of this
adjustment  yourself, since this is done automatically when the layout
has  been put in a Gtk_Scrolled_Window.
procedure Set_Hadjustment
       (Layout             : access Gtk_Layout_Record;
        Adjustment         :        Gtk.Adjustment.Gtk_Adjustment);

Specify a new adjustment to use for the horizontal visual area.
procedure Set_Vadjustment
       (Layout             : access Gtk_Layout_Record;
        Adjustment         :        Gtk.Adjustment.Gtk_Adjustment);

Specify a new adjustment to use for the vertical visual area.

File: gtkada_rm.info,  Node: Package_Gtk.Main,  Next: Package_Gtk.Marshallers,  Prev: Package_Gtk.Layout,  Up: Top

Package Gtk.Main
****************

This package contains top-level subprograms that are used to initialize
GtkAda and interact with the main event loop.

   It also provides a set of packages to set up idle functions, timeout
functions, and functions to be called before and after entering the
main loop.

* Menu:

* Gtk.Main Types::
* Gtk.Main Subprograms::


File: gtkada_rm.info,  Node: Gtk.Main Types,  Next: Gtk.Main Subprograms,  Up: Package_Gtk.Main

Types
=====

type Idle_Callback is access function return Boolean;


Function that can be called automatically whenever GtkAda is not
processing events.   It should return True if the function should be
called again as soon  as possible, False if it should be unregistered.
type Idle_Handler_Id is new Guint;


Id for Idle handlers.
type Idle_Priority is new Guint;


Priorities that can be set for idle handlers.   The higher the
priority, the less urgent the task. Handlers whose  priority is lower
will be called before others.
type Init_Function is access procedure
         (Data : System.Address);

Function called just before starting the main loop.   This can be
registered with Init_Add below.
type Quit_Function is access function return Boolean;


Type of function that can be called when the main loop exits.   It
should return False if it should not be called again when another  main
loop exits.
type Quit_Handler_Id is new Guint;


registration ID for functions that will be called before the  main loop
exits.
type Timeout_Callback is access function return Boolean;


Function that can be called automatically at precise time intervals.
It should return True if the function should be called again as soon
as possible, False if it should be unregistered.
type Timeout_Handler_Id is new Guint;


Id for Timeout handlers.

File: gtkada_rm.info,  Node: Gtk.Main Subprograms,  Prev: Gtk.Main Types,  Up: Package_Gtk.Main

Subprograms
===========

Initialization and exit routines
--------------------------------

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.)
function Set_Locale            return String;


Read and parse the local settings, such as time format, ...
Return the name of the local settings, which can also be set with  the
environment variable LOCALE
procedure Set_Locale;


Read and parse the local settings, such as time format, ...
Init and Quit functions
-----------------------

procedure Init_Add
       (Func               :        Init_Function;
        Data               :        System.Address);

Register a function to be called just before starting a main loop.
This function is called only once, even if a new main loop is started
recursively.
function Quit_Add
       (Main_Level         :        Guint;
        Func               :        Quit_Function)
        return Quit_Handler_Id;

Register a new function to be called when the current main loop exits.
The function will be called once when the current main loop exists.
If it returns False, it will then be deleted from the list of  quit
functions, and won't be called again next time a main loop is  exited.
The function will only be called when exiting a main loop at level
Main_Level. If Main_Level is 0, the function will be called for the
current main_loop.
function Quit_Add_Destroy
       (Main_Level         :        Guint;
        Object             : access Gtk.Object.Gtk_Object_Record'Class)
        return Quit_Handler_Id;

Ensure that Object is destroyed when exiting the main loop at Main_Level
(or the current main loop level is 0).
procedure Quit_Remove
       (Id                 :        Quit_Handler_Id);

Remove a Quit Handler, that has been previously set by Quit_Add.
The main loop
-------------

function Events_Pending        return Boolean;


Return True if there are some events waiting in the event queue.
procedure Main;


Start the main loop, and returns only when the main loop is exited.
This subprogram can be called recursively, to start new internal
loops. Each of these loops is exited through a call to Main_Quit.
This is the recommended method to use when you want to popup a dialog
and wait for the user answer before going any further.   Note that this
procedure can only be called within a single task.
function Main_Level            return Guint;


Return the level of the current main loop.
Since there can be nested loops, this returns the depth of the  current
one, starting from 1 (0 if there is none).
procedure Main_Quit;


Quit the current main loop.
If this was the last active main loop, no more events will be processed
by GtkAda.
function Main_Iteration
       (Blocking           :        Boolean := True)
        return Boolean;

Do one iteration of the main loop.
Blocking indicates whether GtkAda should wait for an event to be
available, or simply exit if there is none.   Returns True if no main
loop is running  When doing some heavy calculations in an application,
it is recommended  that you check from time to time if there are any
events pending and  process them, so that your application still reacts
to events.   To do that, you would add a loop like:

   while Gtk.Main.Events_Pending loop        Dead :=
Gtk.Main.Main_Iteration;    end loop;
procedure Do_Event
       (Event              :        Gdk.Event.Gdk_Event);

Process Event as if it was in the event queue.
This function should almost never be used in your own application, this
is the core function for event processing in GtkAda.   The user should
not free Event, this is already done by GtkAda.
function Get_Event_Widget
       (Event              :        Gdk.Event.Gdk_Event)
        return Gtk.Widget.Gtk_Widget;

Return the widget to which Event applies.
function Get_Current_Event     return Gdk.Event.Gdk_Event;


Return a copy of the event being processed by gtk+. The returned
value must be freed by the caller.   If there is no current event, null
is returned.
Grab functions
--------------

procedure Grab_Add
       (Widget             : access Gtk.Widget.Gtk_Widget_Record'Class);

Add a new widget to the grab list.
The widget at the front of this list gets all the events even if it does
not have the focus. This feature should be used with care.   If you
want a whole window to get the events, it is better to use
Gtk.Window.Set_Modal instead which does the grabbing and ungrabbing for
you.   The grab is only done for the application. Events outside the
application are still sent to their respective windows.
procedure Grab_Remove
       (Widget             : access Gtk.Widget.Gtk_Widget_Record'Class);

Remove a widget from the grab list.
function Grab_Get_Current      return Gtk.Widget.Gtk_Widget;


Return the widget that currently has the focus.
Idle
----

GtkAda gives the possibility to register Idle functions.
These are called every time there is no more event to process in the
queue, and are used for instance internally to redraw widgets (so that
the application keeps reacting to user input even if there is a heavy
redrawing to do).   The Idle function returns a boolean, which should
be True if the idle  remains active and should be called again, or
False if the idle should  be unregistered.   The priority of these idle
callbacks can also be modified, so that  the scheduling calls one
callback before another.

   Two versions are given, either with a user data or with none.

function Idle_Add
       (Cb                 : in     Idle_Callback;
        Priority           : in     Idle_Priority
                            := Priority_Default_Idle)
        return Idle_Handler_Id;

Register an idle callback with no user data.
procedure Idle_Remove
       (Id                 : in     Idle_Handler_Id);

Remove an idle callback, when its Id is known.
Timeout
-------

A timeout is a function that is called after a specified amount
of time. You can of course use Ada tasks for the same role, however
this might provide an easier way of doing things.

   In case your timeout function takes longer to execute than the
specific  delay (for instance it takes 200ms for an internal of 100ms),
then  no invocation is queued, and they are simply discarded. There is
no  queue of expired timers. On the other hand, standard events are
still  processed, but slowly (since they have the same priority as
timeouts).

   The redrawing and resizing of widgets, which are being done as idles
with lower priority will not take place.

function Timeout_Add
       (Interval           : in     Guint32;
        Func               :        Timeout_Callback)
        return Timeout_Handler_Id;

Add a new timeout. Func will be called after Interval milliseconds.
The function will be called as long as it returns True.
procedure Timeout_Remove
       (Id                 :        Timeout_Handler_Id);

Unregister a timeout function.

File: gtkada_rm.info,  Node: Package_Gtk.Marshallers,  Next: Package_Gtk.Menu,  Prev: Package_Gtk.Main,  Up: Top

Package Gtk.Marshallers
***********************

This package provides a set of generic packages to easily create  some
Marshallers. Although this package has been designed to be  easily
reusable, its primary aim is to simplify the use of callbacks.

   Note that most users don't need to understand or even look at this
package, since the main functions are also renamed in the Gtk.Handlers
package (They are called To_Marshaller). This package is rather
complex (generic packages inside generic packages), and thus you should
understand correctly how Gtk.Handlers work before looking at this one.

   To understand the paradigm used in this package, some definitions
are necessary:

   A Handler, or Callback, is a subprogram provided by the user.
This handler, when attached to a particular object, will be     called
when certain events happen during the life of this     object. All
handlers take as a first argument an access to     the object they were
attached to. Depending on the signal, this     handler can also have
some extra parameters; most of the time,     only one extra parameter
will be used. For more information about     Handlers, refer to the
package Gtk.Handlers, where this notion is     explained in more
details.

   A General_Handler is an access to any Handler. Note that this is
a type used internally, most users should *not* be using it. It is
publicly declared so that users can create new marshallers that
would not be already provided here.

   A Handler_Proxy is a subprogram that calls its associated
handler with the appropriate arguments (from an array of arguments
stored in Glib.Values.GValues)

   A Marshaller is the association of a General_Handler and a
Handler_Proxy.

   This package is divided in four generic packages. Each package has
been designed to cover a certain kind of callback by providing the
associated marshallers. There are two primary factors that describe  a
callback, and that decide which marshaller to use: Does the  callback
have access to some user data?  Does the callback return  some value?

   Depending on that, the appropriate generic package should be chosen.
For example, if the callback returns a value, but does not expect
user data, then the "Return_Marshallers" package should be used.   More
details about the usage of each package is provided individually  below.

   Each of these packages is in turn divided into three generic
sub-packages.  The organization of these subpackages is always the
same :     o The type "Handler" is defined. It describes the profile of
the       Handler covered in this generic package.      o a
"To_Marshaller" function is provided to build a Marshaller       from
any Handler.      o A "Emit_By_Name" procedure is also provided to
allow the user       to "emit" a signal. This service is explained in
more details in       Gtk.Handlers.      o A private function "Call" is
also defined. This is the actual       Handler_Proxy that will be used
when creating Marshallers with       the "To_Marshaller" service.

   Once again, selecting the right generic sub-package depends on the
callback. For instance, the first sub-package, always called
"Generic_Marshaller", is to be used when the handler has one extra
argument which is a simple non-tagged type. More details about the
usage of each sub-package is also provided individually.

   Although most of the cases are covered by the packages below, some
unusual cases may appear. This is the case for example when the
callback accepts several extra parameters. In such cases, two options
are available: The first option is to use the "standard" callback
mechanism with one parameter, this parameter being an array of
arguments that you will parse yourself. The second option is to  create
a new Marshaller package. This is more interesting if more  than one
callback will follow the same pattern. The body of this  package can be
used as a good model to build such new marshallers.   See also the
example in the GtkAda distribution for how to create your  own
marshallers.

* Menu:


File: gtkada_rm.info,  Node: Package_Gtk.Menu,  Next: Package_Gtk.Menu_Bar,  Prev: Package_Gtk.Marshallers,  Up: Top

Package Gtk.Menu
****************

This widget implements a drop-down menu.   This is basically a simple
box that contains a series of Gtk_Menu_Item  widgets, on which the user
can click to perform actions.

   Such a menu is usually part of a Gtk_Menu_Bar (at the top of the
window),  or activated by clicking on an item in another Gtk_Menu.
*note Package_Gtk.Option_Menu:: for another way of displaying menus.

   All the menus in GtkAda can be "Tear off" menus, i.e you can detach
them from their parent (either a menu bar or another menu) to keep them
visible on the screen at all times).

   It is worth noting that by default, the user of your application
will be  able to dynamically modify the shortcuts associated with each
menu item.   For instance, selecting a menu item and pressing a key
will assign this  new shortcut to the item, possibly removing the
shortcut from any other  item it was associated with.

   Note that pressing <backspace> will simply remove the shortcut.

   This default behavior, somewhat unexpected, can be canceled.   There
are two ways to control this behavior: you can lock a specific menu
item by calling Gtk.Widget.Lock_Accelerators on it. But you can also
lock all the menu items at once by calling Gtk.Accel_Group.Lock for all
the accelerator groups that were used (the GUI builder gate generally
creates a single one), as well as on the group returned by
Gtk.Accel_Group.Get_Default, which is the one used for items that don't
initially have a shortcut.

* Menu:

* Gtk.Menu Widget Hierarchy::
* Gtk.Menu Types::
* Gtk.Menu Subprograms::
* Gtk.Menu Example::


File: gtkada_rm.info,  Node: Gtk.Menu Widget Hierarchy,  Next: Gtk.Menu Types,  Up: Package_Gtk.Menu

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Container      (*note Package_Gtk.Container::)
              \___ Gtk_Menu_Shell  (*note Package_Gtk.Menu_Shell::)
                 \___ Gtk_Menu     (*note Package_Gtk.Menu::)


File: gtkada_rm.info,  Node: Gtk.Menu Types,  Next: Gtk.Menu Subprograms,  Prev: Gtk.Menu Widget Hierarchy,  Up: Package_Gtk.Menu

Types
=====

type Gtk_Menu_Detach_Func is access procedure


type Gtk_Menu_Position_Func is access procedure



File: gtkada_rm.info,  Node: Gtk.Menu Subprograms,  Next: Gtk.Menu Example,  Prev: Gtk.Menu Types,  Up: Package_Gtk.Menu

Subprograms
===========

Creating a menu
---------------

procedure Gtk_New
       (Widget             : out    Gtk_Menu);

Create a new empty menu.
function Get_Type              return Gtk.Gtk_Type;


Return the internal value associated with a Gtk_Menu.
procedure Set_Active
       (Menu               : access Gtk_Menu_Record;
        Index              :        Guint);

Select a specified item in the menu.
You will almost never need this function, it is used internally by
Gtk_Option_Menu.   Note that the item is not considered as being
pressed by the user, and  thus no callback is called as a result.
function Get_Active
       (Menu               : access Gtk_Menu_Record)
        return Gtk.Menu_Item.Gtk_Menu_Item;

Get the active menu item.
In a Gtk_Option_Menu, this is the item that is currently shown in the
button.
procedure Set_Tearoff_State
       (Menu               : access Gtk_Menu_Record;
        Torn_Off           :        Boolean);

Modify the tearoff status of the menu.
If Torn_Off is False, the menu is displayed as a drop down menu which
disappears when the menu is not active. If Torn_Off is True, the menu
persists until it is closed or reattached.   Note that you can give the
user access to this functionality by  inserting a Gtk_Tearoff_Menu_Item
in the menu.
function Get_Tearoff_State
       (Menu               : access Gtk_Menu_Record)
        return Boolean;

Return the tearoff status of the menu.
procedure Set_Title
       (Menu               : access Gtk_Menu_Record;
        Title              :        UTF8_String);

Set the title of the menu.
Title is displayed when the menu is displayed as a tearoff menu in an
independent window.
function Get_Title
       (Menu               : access Gtk_Menu_Record)
        return UTF8_String;

Return the tiel of the menu.
procedure Reorder_Child
       (Menu               : access Gtk_Menu_Record;
        Child              : access Gtk.Widget.Gtk_Widget_Record'Class;
        Position           :        Gint);

Move an existing menu_item within the menu.
Its new position is given by Position, 0 being the first item in the
menu.   If Child does not exist in the menu, nothing is done.
Displaying a menu
-----------------

procedure Popup
       (Menu               : access Gtk_Menu_Record;
        Parent_Menu_Shell  : in     Gtk.Menu_Shell.Gtk_Menu_Shell
                            := null;
        Parent_Menu_Item   : in     Gtk.Menu_Item.Gtk_Menu_Item
                            := null;
        Func               : in     Gtk_Menu_Position_Func := null;
        Button             : in     Guint := 1;
        Activate_Time      : in     Guint32 := 0);

Display a menu on the screen.
This is the function to use to create contextual menus.   Most of the
time, the parameters can have a null value.   Parent_Menu_Shell is the
Gtk_Menu_Shell that contains Parent_Menu_Item,  i.e. the widget that
triggered the display of the menu.   Func is a function that returns
the coordinates for the menu. If it is  null, then a default function
that positions the menu at the pointer  location is used.   Button is
the mouse button that was pressed to initiate the event.
Activate_Time is the time at which the event occurred (you can get it
directly from the Gdk_Event structure).

   Note that a variant of this function is given in the generic package
User_Menu_Popup.
procedure Popup
       (Menu               : access Gtk_Menu_Record;
        Data               : access Data_Type;
        Parent_Menu_Shell  : in     Gtk.Menu_Shell.Gtk_Menu_Shell
                            := null;
        Parent_Menu_Item   : in     Gtk.Menu_Item.Gtk_Menu_Item
                            := null;
        Func               : in     Gtk_Menu_Position_Func := null;
        Button             : in     Guint := 1;
        Activate_Time      : in     Guint32 := 0);

Same as the Popup function above.
Note that Data is not duplicated, thus you should take care of the
memory allocation/deallocation yourself.
procedure Popdown
       (Menu               : access Gtk_Menu_Record);

Remove the menu from the screen
procedure Reposition
       (Menu               : access Gtk_Menu_Record);

Reposition a menu according to its position function.
This function is set when Popup is called.
Modifying the accelerators
--------------------------

procedure Set_Accel_Group
       (Menu               : access Gtk_Menu_Record;
        Accel              :        Accel_Group.Gtk_Accel_Group);

Set the Accel_Group that holds the global accelerators and key bindings
for the menu.
function Get_Accel_Group
       (Menu               : access Gtk_Menu_Record)
        return Accel_Group.Gtk_Accel_Group;

Get the accelerator group used to set the key bindings in the menu.
procedure Set_Accel_Path
       (Menu               : access Gtk_Menu_Record;
        Accel_Path         :        UTF8_String);

Set an accelerator path for this menu from which accelerator paths
for its immediate children, its menu items, can be constructed.   The
main purpose of this function is to spare the programmer the
inconvenience of having to call Gtk.Menu_Item.Set_Accel_Path on  each
menu item that should support runtime user changable accelerators.
Instead, by just calling Gtk.Menu.Set_Accel_Path on their parent,  each
menu item of this menu, that contains a label describing its  purpose,
automatically gets an accel path assigned. For example, a menu
containing menu items "New" and "Exit", will, after  Set_Accel_Path
(menu, "<Gnumeric-Sheet>/File"); has been called, assign  its items the
accel paths:  "<Gnumeric-Sheet>/File/New" and
"<Gnumeric-Sheet>/File/Exit".   Assigning accel paths to menu items
then enables the user to change  their accelerators at runtime.
Attaching a menu to a widget
----------------------------

procedure Attach_To_Widget
       (Menu               : access Gtk_Menu_Record;
        Attach_Widget      : access Gtk.Widget.Gtk_Widget_Record'Class;
        Detacher           :        Gtk_Menu_Detach_Func);

Attach a menu to the widget.
When the menu is detached from the widget (for instance when it is
destroyed), the procedure Detached will be called.   You will almost
never need to use this function, unless you specifically  want a call
back when a widget becomes unavailable.   If Attach_Widget is a
menu_item with a single label in it, the name of  the window created
when Menu is teared-off will be the label in the  menu_item.
procedure Detach
       (Menu               : access Gtk_Menu_Record);

Detach the menu from its widget, and call the Detacher set in
Attach_To_Widget.
function Get_Attach_Widget
       (Menu               : access Gtk_Menu_Record)
        return Gtk.Widget.Gtk_Widget;

Return the widget to which the menu was attached.
If the menu was not attached, this function returns null.

File: gtkada_rm.info,  Node: Gtk.Menu Example,  Prev: Gtk.Menu Subprograms,  Up: Package_Gtk.Menu

Example
=======


      --  This example shows how you create contextual menus with the third mouse
      --  button.
     
      with Gtk.Handlers; use Gtk.Handlers;
      with Gtk.Menu; use Gtk.Menu;
      with Gdk.Event; use Gdk.Event;
      with Glib; use Glib;
      with Gtk.Window; use Gtk.Window;
      with Gtk.Menu_Item; use Gtk.Menu_Item;
      with Gtk.Enums; use Gtk.Enums;
      with Gtk.Main; use Gtk.Main;
     
      procedure Contextual is
     
         package Menu_Cb is new Gtk.Handlers.Return_Callback
           (Widget_Type => Gtk_Menu_Record,  Return_Type => Boolean);
     
         function Popup_Menu_Handler
           (Menu  : access Gtk_Menu_Record'Class;
            Event : Gdk.Event.Gdk_Event) return Boolean is
         begin
            if Gdk.Event.Get_Event_Type (Event) = Button_Press
              and then Gdk.Event.Get_Button (Event) = 3
            then
               Popup (Menu,
                      Button        => Gdk.Event.Get_Button (Event),
                      Activate_Time => Gdk.Event.Get_Time (Event));
            end if;
     
            return False;
         end Popup_Menu_Handler;
     
     
         Menu  : Gtk_Menu;
         Win   : Gtk_Window;
         Item  : Gtk_Menu_Item;
      begin
         Gtk.Main.Init;
     
         --  create the menu as usual
         Gtk_New (Menu);
         Gtk_New (Item, "Item1");
         Append (Menu, Item);
         Show (Item);
     
         --  create the widget on which you want a contextual menu
         --  Prepares it to receive button_press events
         Gtk_New (Win, Window_Toplevel);
         Set_Events (Win, Button_Press_Mask);
     
         --  Finally, connect both:
         Menu_Cb.Object_Connect
            (Win, "button_press_event",
             Menu_Cb.To_Marshaller (Popup_Menu_Handler'Access),
             Slot_Object => Menu);
     
         Show_All (Win);
         Gtk.Main.Main;
      end Contextual;


File: gtkada_rm.info,  Node: Package_Gtk.Menu_Bar,  Next: Package_Gtk.Menu_Item,  Prev: Package_Gtk.Menu,  Up: Top

Package Gtk.Menu`_'Bar
**********************

Gtk_Menu_Bar is a subclass of Gtk_Menu_Shell which contains one to many
Gtk_Menu_Item. The result is a standard menu bar which can hold many
menu  items. Gtk_Menu_Bar allows for a shadow type to be set for
aesthetic  purposes.

* Menu:

* Gtk.Menu_Bar Widget Hierarchy::
* Gtk.Menu_Bar Subprograms::


File: gtkada_rm.info,  Node: Gtk.Menu_Bar Widget Hierarchy,  Next: Gtk.Menu_Bar Subprograms,  Up: Package_Gtk.Menu_Bar

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Container      (*note Package_Gtk.Container::)
              \___ Gtk_Menu_Shell  (*note Package_Gtk.Menu_Shell::)
                 \___ Gtk_Menu_Bar (*note Package_Gtk.Menu_Bar::)


File: gtkada_rm.info,  Node: Gtk.Menu_Bar Subprograms,  Prev: Gtk.Menu_Bar Widget Hierarchy,  Up: Package_Gtk.Menu_Bar

Subprograms
===========

procedure Gtk_New
       (Menu_Bar           : out    Gtk_Menu_Bar);

Create a menu bar.
function Get_Type              return Gtk.Gtk_Type;


Return the internal value associated with a Gtk_Menu_Bar.

File: gtkada_rm.info,  Node: Package_Gtk.Menu_Item,  Next: Package_Gtk.Menu_Shell,  Prev: Package_Gtk.Menu_Bar,  Up: Top

Package Gtk.Menu`_'Item
***********************

This widget represents one of the lines in a menu, on which the user can
click to execute an action. The menu items can be bound to a submenu,
so  that clicking on them will in fact display the submenu on the
screen.

   They can also be associated with key shortcuts (called
accelerators). See  the subprogram Set_Accel_Path, and the subprograms
in the package  Gtk.Accel_Map.

   Activating the proper options in the theme files will allow the user
to  interactively modify the shortcuts.

* Menu:

* Gtk.Menu_Item Widget Hierarchy::
* Gtk.Menu_Item Subprograms::


File: gtkada_rm.info,  Node: Gtk.Menu_Item Widget Hierarchy,  Next: Gtk.Menu_Item Subprograms,  Up: Package_Gtk.Menu_Item

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Container      (*note Package_Gtk.Container::)
              \___ Gtk_Bin         (*note Package_Gtk.Bin::)
                 \___ Gtk_Item     (*note Package_Gtk.Item::)
                    \___ Gtk_Menu_Item (*note Package_Gtk.Menu_Item::)


File: gtkada_rm.info,  Node: Gtk.Menu_Item Subprograms,  Prev: Gtk.Menu_Item Widget Hierarchy,  Up: Package_Gtk.Menu_Item

Subprograms
===========

procedure Gtk_New
       (Menu_Item          : out    Gtk_Menu_Item;
        Label              :        UTF8_String := "");

procedure Gtk_New_With_Mnemonic
       (Menu_Item          : out    Gtk_Menu_Item;
        Label              :        UTF8_String);

Create a new Gtk_Menu_Item containing a label.
The label is created using Gtk.Label.Gtk_New_With_Mnemonic, so
underscores in Label indicate the mnemonic for the menu item.
Warning: the menu_item will not be properly destroyed when you remove
it from its parent menu, if you created it with a non-empty Label. In
this case, you first need to destroy the child of the Menu_Item, and
then remove it from its parent menu.
procedure Initialize_With_Mnemonic
       (Menu_Item          : access Gtk_Menu_Item_Record'Class;
        Label              :        UTF8_String);

Internal initialization procedure.
function Get_Type              return Gtk.Gtk_Type;


Return the internal value associated with a Gtk_Menu_Item.
procedure Set_Submenu
       (Menu_Item          : access Gtk_Menu_Item_Record;
        Submenu            : access Widget.Gtk_Widget_Record'Class);

Set the submenu underneath Menu_Item.
function Get_Submenu
       (Menu_Item          : access Gtk_Menu_Item_Record)
        return Gtk.Widget.Gtk_Widget;

Get the submenu underneath this menu item, if any, null otherwise.
procedure Remove_Submenu
       (Menu_Item          : access Gtk_Menu_Item_Record);

procedure Gtk_Select
       (Menu_Item          : access Gtk_Menu_Item_Record);

procedure Deselect
       (Menu_Item          : access Gtk_Menu_Item_Record);

procedure Activate
       (Menu_Item          : access Gtk_Menu_Item_Record);

procedure Right_Justify
       (Menu_Item          : access Gtk_Menu_Item_Record);

Deprecated. Use Set_Right_Justified with Justify = True instead.
procedure Set_Right_Justified
       (Menu_Item          : access Gtk_Menu_Item_Record;
        Justify            :        Boolean := True);

function Get_Right_Justified
       (Menu_Item          : access Gtk_Menu_Item_Record)
        return Boolean;

procedure Set_Right_Justify
       (Menu_Item          : access Gtk_Menu_Item_Record;
        Justify            :        Boolean);

This procedure is needed by Gate to automate the code generation.
procedure Set_Accel_Path
       (Menu_Item          : access Gtk_Menu_Item_Record;
        Accel_Path         :        UTF8_String);

Set the path that will be used to reference the widget in calls to the
subprograms in Gtk.Accel_Map. This means, for instance, that the widget
is fully setup for interactive modification of the shortcuts by the
user, should he choose to activate this possibility in his themes (see
gtk-accel_map.ads for more information).

File: gtkada_rm.info,  Node: Package_Gtk.Menu_Shell,  Next: Package_Gtk.Misc,  Prev: Package_Gtk.Menu_Item,  Up: Top

Package Gtk.Menu`_'Shell
************************

This widget is a base class for all menu widgets. It contains a list of
items that can be navigated, selected and activated by the user.   It
can not be instantiated directly.

   A menu is considered "active" when it is displayed on the screen,
or, in  the case of a menu_bar when one of its menus is active.

   An item is "selected" if it is displayed in a prelight state and its
submenu (if any) displayed.

* Menu:

* Gtk.Menu_Shell Widget Hierarchy::
* Gtk.Menu_Shell Signals::
* Gtk.Menu_Shell Subprograms::


File: gtkada_rm.info,  Node: Gtk.Menu_Shell Widget Hierarchy,  Next: Gtk.Menu_Shell Signals,  Up: Package_Gtk.Menu_Shell

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Container      (*note Package_Gtk.Container::)
              \___ Gtk_Menu_Shell  (*note Package_Gtk.Menu_Shell::)


File: gtkada_rm.info,  Node: Gtk.Menu_Shell Signals,  Next: Gtk.Menu_Shell Subprograms,  Prev: Gtk.Menu_Shell Widget Hierarchy,  Up: Package_Gtk.Menu_Shell

Signals
=======

   * "activate_current"

     procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class;
     Force_Hide : Gboolean);
     Activates the current menu item within the Menu_Shell.  if
     Force_Hide is True, hide the menu afterwards.

   * "cancel"

     procedure Handler (Menu_Shell : access
     Gtk_Menu_Shell_Record'Class);
     Cancels the selection within the menu_shell. Causes a
     "selection-done" signal to be emitted.

   * "deactivate"

     procedure Handler (Menu_Shell : access
     Gtk_Menu_Shell_Record'Class);
     Emitted when the menu is deactivated, ie is erased from the screen.

   * "move_current"

     procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class;
     Direction  : Gtk_Menu_Direction_Type);
     An action signal which selects another menu item (given by
     direction).  In a menu, this is bound by default to the arrow keys
     to move the the selection.

   * "selection-done"

     procedure Handler (Menu_Shell : access
     Gtk_Menu_Shell_Record'Class);
     Emitted when an item has been selected. The menu shell might not be
     activated when the signal is emitted.



File: gtkada_rm.info,  Node: Gtk.Menu_Shell Subprograms,  Prev: Gtk.Menu_Shell Signals,  Up: Package_Gtk.Menu_Shell

Subprograms
===========

function Get_Type              return Gtk.Gtk_Type;


Return the internal value associated with a Gtk_Menu_Shell.
procedure Append
       (Menu_Shell         : access Gtk_Menu_Shell_Record;
        Child              : access Gtk_Menu_Item_Record'Class);

Add a new item at the end of the menu.
procedure Prepend
       (Menu_Shell         : access Gtk_Menu_Shell_Record;
        Child              : access Gtk_Menu_Item_Record'Class);

Add a new item at the beginning of the menu
procedure Insert
       (Menu_Shell         : access Gtk_Menu_Shell_Record;
        Child              : access Gtk_Menu_Item_Record'Class;
        Position           :        Gint);

Add a new item at a specific position in the menu.
The first item is at position 0. To insert as the last item in the menu,
set Position to -1.
Signals emission
----------------

procedure Deactivate
       (Menu_Shell         : access Gtk_Menu_Shell_Record);

Emit the "deactivate" signal.
This deselects the selected item, ungrabs the mouse and keyboard, and
erase the Menu_Shell from the screen.
procedure Select_Item
       (Menu_Shell         : access Gtk_Menu_Shell_Record;
        Item               : access Gtk_Menu_Item_Record'Class);

Select a new item in the menu, after deselecting the current item.
procedure Deselect
       (Menu_Shell         : access Gtk_Menu_Shell_Record);

Deselect the currently selected item.
procedure Activate_Item
       (Menu_Shell         : access Gtk_Menu_Shell_Record;
        Item               : access Gtk_Menu_Item_Record'Class;
        Force_Deactivate   :        Boolean);

Activate the item.
If Force_Deactivate is True or the menu_shell sets this property,
Menu_Shell and all its parent menus are deactivated and erased from
the screen.

File: gtkada_rm.info,  Node: Package_Gtk.Misc,  Next: Package_Gtk.Notebook,  Prev: Package_Gtk.Menu_Shell,  Up: Top

Package Gtk.Misc
****************

This widget is a base class for all the widgets that require an
alignment and padding.   This widget can not be instantiated directly.

* Menu:

* Gtk.Misc Widget Hierarchy::
* Gtk.Misc Subprograms::


File: gtkada_rm.info,  Node: Gtk.Misc Widget Hierarchy,  Next: Gtk.Misc Subprograms,  Up: Package_Gtk.Misc

Widget Hierarchy
================

     GObject                       (*note Package_Glib.Object::)
     Gtk_Object                    (*note Package_Gtk.Object::)
        \___ Gtk_Widget            (*note Package_Gtk.Widget::)
           \___ Gtk_Misc           (*note Package_Gtk.Misc::)

