-----------------------------------------------------------------------
-- GtkAda - Ada95 binding for Gtk+/Gnome --
-- --
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet --
-- Copyright (C) 2000-2006 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. --
-- --
-----------------------------------------------------------------------
--
-- A Gtk_Label is a light widget associated with some text you want
-- to display on the screen. You can change the text dynamically if
-- needed.
--
-- The text can be on multiple lines if you separate each line with
-- the ASCII.LF character. However, this is not the recommended way
-- to display long texts (see the Gtk_Text widget instead).
--
-- Mnemonics
-- =========
-- Labels may contain mnemonics. Mnemonics are underlined characters in the
-- label, used for keyboard navigation. Mnemonics are created by providing
-- string with an underscore before the mnemonic character, such as "_File",
-- to the functions gtk_new_with_mnemonic or set_text_with_mnemonic().
--
-- Mnemonics automatically activate any activatable widget the label is
-- inside, such as a Gtk_Button; if the label is not inside the mnemonic's
-- target widget, you have to tell the label about the target using
-- set_mnemonic_widget(). For instance:
-- declare
-- Button : Gtk_Button;
-- Label : Gtk_Label;
-- begin
-- Gtk_New (Button);
-- Gtk_New_With_Mnemonic (Label, "_File");
-- Add (Button, Label);
-- end;
-- However, there exists a convenience function in Gtk.Button to create such
-- a button already.
--
-- Markup
-- ======
-- To make it easy to format text in a label (changing colors, fonts, etc.),
-- label text can be provided in a simple markup format. Here's how to create
-- a label with a small font:
-- Gtk_New (Label, "hello");
--
-- The markup must be valid, and <>& characters must be escaped with
-- < > and &
--
-- Markup strings are just a convenient way to set the Pango_Attr_List on
-- label; Set_Attributes() may be a simpler way to set attributes in some
-- cases. Be careful though; Pango_Attr_List tends to cause
-- internationalization problems, unless you're applying attributes to the
-- entire string (i.e. unless you set the range of each attribute to [0,
-- G_MAXINT)). The reason is that specifying the start_index and end_index for
-- a Pango_Attribute requires knowledge of the exact string being displayed,
-- so translations will cause problems.
--
-- Selectable labels
-- =================
-- Labels can be made selectable with Set_Selectable. Selectable
-- labels allow the user to copy the label contents to the clipboard. Only
-- should be made selectable.
--
-- 2.8.17
-- Display widgets
-- create_label.adb
-- gtk-label
with Gdk.Types;
with Glib.Properties;
with Gtk.Enums;
with Gtk.Misc;
with Gtk.Widget;
with Pango.Attributes;
with Pango.Layout;
package Gtk.Label is
type Gtk_Label_Record is new Misc.Gtk_Misc_Record with private;
type Gtk_Label is access all Gtk_Label_Record'Class;
procedure Gtk_New (Label : out Gtk_Label; Str : UTF8_String := "");
procedure Initialize
(Label : access Gtk_Label_Record'Class; Str : UTF8_String);
-- Creates or initializes a new label.
-- Str is the string to be displayed.
procedure Gtk_New_With_Mnemonic (Label : out Gtk_Label; Str : UTF8_String);
procedure Initialize_With_Mnemonic
(Label : access Gtk_Label_Record'Class; Str : UTF8_String);
-- Creates or initializes 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.
function Get_Type return Glib.GType;
-- Return the internal value associated with a Gtk_Label.
procedure Set_Justify
(Label : access Gtk_Label_Record;
Jtype : Enums.Gtk_Justification);
function Get_Justify
(Label : access Gtk_Label_Record) return 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_Line_Wrap (Label : access Gtk_Label_Record; Wrap : Boolean);
function Get_Line_Wrap (Label : access Gtk_Label_Record) return 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_Selectable
(Label : access Gtk_Label_Record; Selectable : Boolean);
function Get_Selectable (Label : access Gtk_Label_Record) return Boolean;
-- Selectable labels allow the user to select text from the label,
-- for copy-and-paste.
procedure Set_Use_Markup
(Label : access Gtk_Label_Record; Markup : Boolean);
function Get_Use_Markup (Label : access Gtk_Label_Record) return 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);
function Get_Use_Underline (Label : access Gtk_Label_Record) return Boolean;
-- Indicates wether an embedded underline in the label indicates the
-- mnemonic accelerator key.
procedure Set_Angle (Label : access Gtk_Label_Record; Angle : Gdouble);
function Get_Angle (Label : access Gtk_Label_Record) return Gdouble;
-- Sets the angle of rotation for the label. An angle of 90 reads from
-- from bottom to top, an angle of 270, from top to bottom. The angle
-- setting for the label is ignored if the label is selectable,
-- wrapped, or ellipsized.
procedure Set_Ellipsize
(Label : access Gtk_Label_Record;
Mode : Pango.Layout.Pango_Ellipsize_Mode);
function Get_Ellipsize
(Label : access Gtk_Label_Record)
return Pango.Layout.Pango_Ellipsize_Mode;
-- Sets the mode used to ellipsize (add an ellipsis: "...") to the text if
-- there is not enough space to render the entire string.
procedure Set_Text (Label : access Gtk_Label_Record; Str : UTF8_String);
function Get_Text (Label : access Gtk_Label_Record) return 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_Label (Label : access Gtk_Label_Record; Str : String);
function Get_Label (Label : access Gtk_Label_Record) return String;
-- Sets the text of the label. The label is interpreted as
-- including embedded underlines and/or Pango markup depending
-- on the values of label->use_underline and label->use_markup.
function Get_Layout
(Label : access Gtk_Label_Record) return Pango.Layout.Pango_Layout;
-- Gets the layout used to display the label.
-- The layout is useful to e.g. convert text positions to pixel positions,
-- in combination with Get_Layout_Offsets(). The returned layout is owned
-- by the label so need not be freed by the caller.
procedure Get_Layout_Offsets
(Label : access Gtk_Label_Record;
X, Y : out Gint);
-- Obtains the coordinates where the label will draw the layout
-- representing the text in the label; useful to convert mouse events into
-- coordinates inside the layout, e.g. to take some action if some part of
-- the label is clicked. Of course you will need to create a Gtk_Event_Box
-- to receive the events, and pack the label inside it, since labels are a
-- #GTK_NO_WINDOW widget. Remember when using the layout functions you need
-- to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE.
procedure Set_Max_Width_Chars
(Label : access Gtk_Label_Record; N_Chars : Gint);
function Get_Max_Width_Chars (Label : access Gtk_Label_Record) return Gint;
-- Sets the desired maximum width in characters of Label
procedure Set_Width_Chars (Label : access Gtk_Label_Record; N_Chars : Gint);
function Get_Width_Chars (Label : access Gtk_Label_Record) return Gint;
-- Sets the desired width in characters of Label.
procedure Set_Single_Line_Mode
(Label : access Gtk_Label_Record;
Single_Line_Mode : Boolean);
function Get_Single_Line_Mode
(Label : access Gtk_Label_Record) return Boolean;
-- Sets whether the label is in single line mode.
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_Attributes
(Label : access Gtk_Label_Record;
Attrs : Pango.Attributes.Pango_Attr_List);
function Get_Attributes
(Label : access Gtk_Label_Record) return Pango.Attributes.Pango_Attr_List;
-- Sets a list of attributes to be applied to the label text. These
-- attributes will be ignored if the use_underline or use_markup
-- properties are set.
-- Get_Attributes does not reflect attributes that come from the label's
-- markup (see Set_Markup). If you want to get the effective attributes for
-- the label, use Pango.Layout.Get_Attribute (Get_Layout (Label)).
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.
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);
function Get_Mnemonic_Widget
(Label : access Gtk_Label_Record) return Gtk.Widget.Gtk_Widget;
-- 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 Get_Selection_Bounds
(Label : access Gtk_Label_Record;
First, Last : out Gint;
Has_Selection : out Boolean);
-- Gets the selected range of characters in the label, returning True
-- if there's a selection.
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".
-----------------
-- Obsolescent --
-----------------
-- All subprograms below are now obsolescent in gtk+. They might be removed
-- from future versions of gtk+ (and therefore GtkAda).
-- To find out whether your code uses any of these, we recommend compiling
-- with the -gnatwj switch
--
function Get
(Label : access Gtk_Label_Record) return UTF8_String renames Get_Text;
-- pragma Obsolescent;
-- Same as Get_Text.
--
----------------
-- Properties --
----------------
--
-- The following properties are defined for this widget. See
-- Glib.Properties for more information on properties.
--
-- Name: Label_Property
-- Type: UTF8_String
-- Flags: read-write
-- Descr: The text of the label.
-- See also: Set_Text and Get_Text
--
-- Name: Attributes_Property
-- Type: Pango_Type_Attr_List
-- Flags: read-write
-- Descr: A list of style attributes to apply to the text of the label.
-- See also: ??? Unsupported yet
--
-- Name: Use_Markup_Property
-- Type: Boolean
-- Flags: read-write
-- Descr: The text of the label includes XML markup.
-- See pango_parse_markup().
-- See also:
--
-- Name: Use_Underline_Property
-- Type: Boolean
-- Flags: read-write
-- Descr: If set, an underline in the text indicates the next character
-- should be used for the mnemonic accelerator key
-- See also:
--
-- Name: Justify_Property
-- Type: Gtk_Justification
-- Flags: read-write
-- Descr: The alignment of the lines in the text of the label relative to
-- each other. This does NOT affect the alignment of the label
-- within its allocation.
-- See also: Set_Justify
--
-- Name: Pattern_Property
-- Type: String
-- Flags: read-write
-- Descr: A string with _ characters in positions correspond to
-- characters in the text to underline.
-- See also: Set_Pattern
--
-- Name: Wrap_Property
-- Type: Boolean
-- Flags: read-write
-- Descr: If set, wrap lines if the text becomes too wide.
-- See also: Set_Line_Wrap
--
-- Name: Selectable_Property
-- Type: Boolean
-- Flags: read-write
-- Descr: Whether the label text can be selected with the mouse.
-- See also:
--
-- Name: Mnemonic_Keyval_Property
-- Type: Guint
-- Flags: readable
-- Descr: The mnemonic accelerator key for this label.
-- See also: Gtk_New_With_Mnemonic
--
-- Name: Mnemonic_Widget_Property
-- Type: Gtk_Widget_Record'Class
-- Flags: read-write
-- Descr: The widget to be activated when the label's mnemonic key is
-- pressed
--
-- Name: Angle_Property
-- Type: Double
-- Descr: Angle at which the label is rotated
--
-- Name: Cursor_Position_Property
-- Type: Int
-- Descr: The current position of the insertion cursor in chars
--
-- Name: Ellipsize_Property
-- Type: Enum
-- Descr: The preferred place to ellipsize the string, if the label does
-- not have enough room to display the entire string, if at all
--
-- Name: Max_Width_Chars_Property
-- Type: Int
-- Descr: The desired maximum width of the label, in characters
--
-- Name: Selection_Bound_Property
-- Type: Int
-- Descr: The position of the opposite end of the selection from the cursor
-- in chars
--
-- Name: Single_Line_Mode_Property
-- Type: Boolean
-- Descr: Whether the label is in single line mode
--
-- Name: Width_Chars_Property
-- Type: Int
-- Descr: The desired width of the label, in characters
--
--
Label_Property : constant Glib.Properties.Property_String;
-- Attributes_Property : constant ???
Use_Markup_Property : constant Glib.Properties.Property_Boolean;
Use_Underline_Property : constant Glib.Properties.Property_Boolean;
Justify_Property : constant Gtk.Enums.Property_Gtk_Justification;
Pattern_Property : constant Glib.Properties.Property_String;
Wrap_Property : constant Glib.Properties.Property_Boolean;
Selectable_Property : constant Glib.Properties.Property_Boolean;
Mnemonic_Keyval_Property : constant Glib.Properties.Property_Uint_RO;
Mnemonic_Widget_Property : constant Glib.Properties.Property_Object;
Angle_Property : constant Glib.Properties.Property_Double;
Cursor_Position_Property : constant Glib.Properties.Property_Int;
-- Ellipsize_Property : constant Glib.Properties.Property_Enum;
Max_Width_Chars_Property : constant Glib.Properties.Property_Int;
Selection_Bound_Property : constant Glib.Properties.Property_Int;
Single_Line_Mode_Property : constant Glib.Properties.Property_Boolean;
Width_Chars_Property : constant Glib.Properties.Property_Int;
-------------
-- Signals --
-------------
--
-- The following new signals are defined for this widget:
--
-- - "copy_clipboard"
-- procedure Handler (Label : access Gtk_Label_Record'Class);
-- Request a copy the label's text into the clipboard. This should be
-- bound to a key.
--
-- - "move_cursor"
-- procedure Handler
-- (Label : access Gtk_Label_Record'Class;
-- Step : Gtk_Movement_Step;
-- Amount : Gint;
-- Extend_Selection : Boolean);
-- You should emit this signal to request that the cursor be moved inside
-- the label. This is mostly useful from a keybinding. The cursor is
-- also used as the insertion point when modifying the label
--
-- - "populate_popup"
-- procedure Handler
-- (Label : access Gtk_Label_Record'Class;
-- Menu : access Gtk_Menu_Record'Class);
-- ???
--
--
Signal_Copy_Clipboard : constant String := "copy_clipboard";
Signal_Move_Cursor : constant String := "move_cursor";
Signal_Populate_Popup : constant String := "populate_popup";
private
type Gtk_Label_Record is new Misc.Gtk_Misc_Record with null record;
Label_Property : constant Glib.Properties.Property_String :=
Glib.Properties.Build ("label");
Use_Markup_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("use_markup");
Use_Underline_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("use_underline");
Justify_Property : constant Gtk.Enums.Property_Gtk_Justification :=
Gtk.Enums.Build ("justify");
Pattern_Property : constant Glib.Properties.Property_String :=
Glib.Properties.Build ("pattern");
Wrap_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("wrap");
Selectable_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("selectable");
Mnemonic_Keyval_Property : constant Glib.Properties.Property_Uint_RO :=
Glib.Properties.Build ("mnemonic_keyval");
Mnemonic_Widget_Property : constant Glib.Properties.Property_Object :=
Glib.Properties.Build ("mnemonic_widget");
Angle_Property : constant Glib.Properties.Property_Double :=
Glib.Properties.Build ("angle");
Cursor_Position_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("cursor-position");
-- Ellipsize_Property : constant Glib.Properties.Property_Enum :=
-- Glib.Properties.Build ("ellipsize");
Max_Width_Chars_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("max-width-chars");
Selection_Bound_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("selection-bound");
Single_Line_Mode_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("single-line-mode");
Width_Chars_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("width-chars");
pragma Import (C, Get_Type, "gtk_label_get_type");
end Gtk.Label;
-- These subprograms never had a binding, but are now obsolescent:
-- No binding: gtk_label_get
-- No binding: gtk_label_parse_uline