ADA INDUSTRIAL CONTROL WIDGET LIBRARY

version 3.24



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.

As a special exception, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.

ARM Intel Download AICWL Platform: v7 64- 32bit Fedora packages precompiled and packaged using RPM (see also release notes on the download page, for limitations of the packaged distribution) CentOS packages precompiled and packaged using RPM (see also release notes on the download page, for limitations of the packaged distribution) Debian packages precompiled and packaged for dpkg (see also release notes on the download page, for limitations of the packaged distribution) Ubuntu packages precompiled and packaged for dpkg (see also release notes on the download page, for limitations of the packaged distribution) Source distribution (any platform) aicwl_3_24.tgz (tar + gzip, Windows users may use WinZip)

The described here packages are provided for design high-quality industrial control widgets for Ada applications. The software is based on GtkAda, Ada bindings to GTK+ and cairo. The key features of the library:

Widgets composed of transparent layers drawn by cairo;

Fully scalable graphics;

Support of time controlled refresh policy for real-time and heavy-duty applications;

Caching graphical operations;

Stream I/O support for serialization and deserialization;

Ready-to-use gauge, meter, oscilloscope widgets;

Editor widget for WYSIWYG design of complex dashboards.

See also changes log.

1. Widgets gallery

The widget gallery shows some examples of widgets implemented using the library. These are provided rather as usable samples due to variability of requirements on the style used in projects. The implementations are very straightforward and can be used as templates for customization.

1.1. Gauges

1.2. Sectors and segments

1.3. Meters

1.4. Flat and rectangular

1.5. Wall clocks

1.6. Oscilloscope

1.7. LEDs

2. Layered widget

Layered widget is a GTK+ widget encapsulating stacked layers performing cairo drawing operations when the widget is redrawn. The widget can implement a single gauge, but it is not necessary. One widget can well implement the whole dashboard.

2.1. Anatomy of a gauge

A gauge consists of several superimposed transparent layers:

The layers are stacked up on each other.

2.2. Abstract layer

The type Abstract_Layer declared in the package Gtk.Layered is the base type of all layers of a layered widget:

type Abstract_Layer is

abstract new Ada.Finalization.Limited_Controlled

and Layer_Object

and Layer_Location with private;

The type Abstract_Layer implements the interfaces Layer_Location and Layer_Object.

2.2.1. Primitive operations

The following primitive operations are provided by Abstract_Layer:

function Above (Layer : Abstract_Layer)

return access Abstract_Layer'Class;

This function returns the layer above Layer or null if Layer is the topmost layer of the widget.

function Atop (Layer : Abstract_Layer)

return not null access Layer_Location'Class;

This function returns the location atop Layer. Constraint_Error is propagated when Layer does not belong to any widget.

function Below (Layer : Abstract_Layer)

return access Abstract_Layer'Class;

This function returns the layer below Layer or null if Layer is the deepest layer of the widget.

procedure Finalize (Layer : in out Abstract_Layer);

This procedure performs finalization of the layer. When overridden it must be called from the override.

function Get_Position (Layer : Abstract_Layer) return Natural;

This function returns the layer's position or else 0, when the layer does not belong to any widget.

function Is_Caching (Layer : Abstract_Layer) return Boolean;

This function returns true if the layer performs caching of the underlying layers. Caching layers receive special treatment upon drawing. The default implementation returns false .

procedure Property_Set

( Layer : in out Abstract_Layer;

Param : Param_Spec

) is null ;

This procedure is called when a property of the widget is set. The parameter Param describes the property. The layer may change some of its data when necessary. The default implementation does nothing.

function Get_Widget (Layer : Abstract_Layer)

return not null access Gtk_Layered_Record'Class;

This function returns the widget of the layer.

procedure Prepare

( Layer : in out Abstract_Layer;

Context : Cairo_Context;

Area : Gdk_Rectangle

) is null ;

This procedure is called for all layers before drawing occurs. The implementation shall not change the list of widget layers nor perform drawing onto Context. The default implementation does nothing.

procedure Resized

( Layer : in out Abstract_Layer;

Area : Gdk_Rectangle

) is null;

This procedure is called when the layer's widget is resized. The default implementation does nothing.

procedure Store

( Layer : in out Abstract_Layer;

Context : Cairo_Context

) is null;

This procedure is called only for the layers which return true from Is_Caching. It is done when all underlying layers are drawn. The layer should cache the image drawn. Later when the widget need to be redrawn and the underlying layers return false from their Is_Updated, they are excluded from drawing and only the Draw operation of the caching layer is called.

procedure Style_Set (Layer : in out Abstract_Layer) is null ;

The procedure is called when the widget's style properties were set. The default implementation does nothing.

2.2.2. Abstract operations

The following abstract primitive operations must be implemented:

function Add

( Under : not null access Layer_Location'Class;

Stream : not null access Root_Stream_Type'Class

) return not null access Abstract_Layer is abstract ;

This function adds a new layer under the location specified by the parameter Under. The layer parameters are read from Stream. The function returns a pointer to the added layer. Constraint_Error is propagated when layer parameters are illegal. Other exceptions may indicate input errors.

procedure Draw

( Layer : in out Abstract_Layer;

Context : Cairo_Context;

Area : Gdk_Rectangle

) is abstract ;

This procedure is called when the layer need to be redrawn. The parameter Context is the current cairo drawing context. The context must be used for all drawing operations the implementation performs. The parameter Area is the widget's area need to be updated. The implementation need not to draw outside Area rectangle, when it does this the output is clipped out. After a successful call to Draw, Is_Updated should return false . The layer, when scalable should consider the widget's center in Get_Center and its size of Get_Size.

function Get_Properties_Number (Layer : Abstract_Layer)

return Natural is abstract ;

Layers are not GLib objects and thus do not have properties of their own. But they support properties interface. The layer can be asked for its "properties" and their values can be get and set thus influencing the layer's parameters. This can be used by the layered widget in different ways. The styles and properties of the widget may map to the layer's "properties." An application can control layers of a widget in a generic way by setting the "properties" of the layers.

function Get_Property_Specification

( Layer : Abstract_Layer;

Property : Positive

) return Param_Spec is abstract ;

This function returns the specification of a property specified by its number. The result must be released using Unref unless used in some container type which decrements the reference count internally. Constraint_Error is propagated when Property is not in the range 1..Get_Properties_Number.

function Get_Property_Value

( Layer : Abstract_Layer;

Property : Positive

) return GValue is abstract ;

This function returns the value of a property specified by its number. The result must be released using Unset. Constraint_Error is propagated when Property is not in the range 1..Get_Properties_Number.

function Is_Updated (Layer : Abstract_Layer)

return Boolean is abstract ;

An implementation of this function should return true when the layer contents must be redrawn because the layer's state was changed.

procedure Move

( Layer : in out Abstract_Layer;

Offset : Cairo_Tuple

) is abstract ;

The implementation moves all geometric shapes the layer draws from the original position (x,y) to the position (x,y) + Offset. Note that when the layer implements the interface Scalable_Layer, and Get_Scaled returns true , then the effective Offset in cairo coordinates will depend on the current widget's size (see Get_Size), on which Offset is multiplied. Therefore to move the scalable layer in cairo coordinates, Offset must be divided to the widget's size. Note also that some layers, e.g. ones with border, influence Get_Size of the layers above.

procedure Restore

( Stream : in out Root_Stream_Type'Class;

Layer : in out Abstract_Layer

) is abstract;

This procedure reads Layer parameters from Stream. The layer parameters must be written using Store. Constraint_Error is propagated when some of the parameters are illegal. Other exceptions may indicate input errors.

procedure Scale

( Layer : in out Abstract_Layer;

Factor : GDouble

) is abstract ;

The implementation magnifies all geometric shapes the layer draws by Factor. Constraint_Error is propagated when Factor is illegal.

procedure Set_Property_Value

( Layer : in out Abstract_Layer;

Property : Positive;

Value : GValue

) is abstract ;

This procedure sets a property specified by its number. Constraint_Error is propagated when Property is not in the range 1..Get_Properties_Number or when the property value is invalid.

procedure Store

( Stream : in out Root_Stream_Type'Class;

Layer : Abstract_Layer

) is abstract;

This procedure writes Layer parameters into Stream. The parameters written this way can be used to restore layer state using Restore. An exception may indicate output error.

2.3. Layered widget

The package Gtk.Layered defines a widget painted using cairo drawing.

type Gtk_Layered_Record is

new Gtk_Widget_Record and Layer_Location with private ;

type Gtk_Layered is access all Gtk_Layered_Record'Class;

The objects of the type process GTK+ events in order to prepare cairo context for drawing into the widget. The widget emits the following signals:

layer-added is emitted when the layer has been added. The first parameter of the type GUInt is the position of the layer. The layers have positions starting from 1 at the widget's bottom;

is emitted when the layer has been added. The first parameter of the type GUInt is the position of the layer. The layers have positions starting from 1 at the widget's bottom; layer-removed is emitted when the layer has been removed. The first parameter of the type GUInt is the position the removed layer had. Note that the layer is already removed when the signal is emitted.

The widget contains layers derived from the type Abstract_Layer:

function Get_Type return GType;

This function returns the GTK type of Gtk_Layered_Record.

2.3.1. Primitive operations

The following primitive operations are provided by Gtk_Layered_Record:

procedure Erase (Widget : in out Gtk_Layered_Record);

This procedure removes all layers of a widget.

procedure Finalize (Widget : in out Gtk_Layered_Record) is null ;

This procedure is called upon widget destruction. The default implementation destroys all layers attached to the widget.

function Get_Aspect_Ratio

( Widget : not null access constant Gtk_Layered_Record

) return GDouble;

This function returns the aspect ratio of the widget. The aspect ratio is the widget's width divided to the widget's height. The aspect ratio may influence the behavior of the widget's layer when the size of the widget is changed. The default implementation returns the value set using the procedure Set_Aspect_Ratio.

function Get_Bottom (Widget : not null access Gtk_Layered_Record)

return not null access Layer_Location'Class;

This function returns the location of the deepest layer of Widget. When the widget has no layers the result is the widget itself.

function Get_Center

( Widget : not null access constant Gtk_Layered_Record

) return Cairo_Tuple;

This function returns the coordinates of the widget's center. When the widget layers are scaled according to the widget size it should use this function in order to determine the widget's center.

function Get_Depth

( Widget : not null access constant Gtk_Layered_Record

) return Natural;

This function returns the number of its layers.

function Get_Drawing_Time

( Widget : not null access constant Gtk_Layered_Record

) return Time;

This function returns the time of drawing. The widgets which state depends on real time should use this value when draw their states.

function Get_Layer

( Widget : not null access constant Gtk_Layered_Record;

Layer : Positive

) return access Abstract_Layer'Class;

This function returns the layer by its number. The layers are numbered bottom to top. The deepest layer has the number 1. The result null if there is no such layer.

function Get_Lower (Widget : not null access Gtk_Layered_Record)

return access Abstract_Layer'Class;

This function returns the bottom layer of Widget or null if there is none.

function Get_Size

( Widget : not null access constant Gtk_Layered_Record

) return GDouble;

This function returns the widget's size. When the widget layers are scaled according to the widget size it should use this function in order to determine the widget's size. The size of the widget is calculated from its width and height taking into account its aspect ratio as returned by Get_Aspect_Ratio. When the widget's aspect ratio is less than Get_Aspect_Ratio the widget size is set to its height multiplied by the value returned by Get_Aspect_Ratio. Otherwise the widget size is set to its width. In particular when the aspect ratio is 1, the result is minimum of height and width. The widget size can be considered the effective widget's width. Thus when a layer is designed, which should be resizable, its vertical dimensions should be calculated relatively to the horizontal dimensions. The maximal horizontal dimension should be 1.0, when the layer should cover whole widget's area.

function Get_Upper (Widget : not null access Gtk_Layered_Record)

return access Abstract_Layer'Class;

This function returns the topmost layer of Widget or null if there is none.

procedure Refresh

( Widget : not null access Gtk_Layered_Record;

Context : Cairo_Context

);

This procedure performs drawing of the widget's layers when the widget must be redrawn. It should not be used directly. If the widget need to be redrawn the Queue_Draw should be used instead. Context is the cairo context to draw onto.

procedure Remove

( Widget : not null access Gtk_Layered_Record;

Layer : Positive

);

This procedure removes the layer by its position. The resources allocated by the layer are freed. The layers are numbered from 1 starting from the bottom layer. Nothing happens when there is no layer with this number. A layer can also be removed implicitly when the corresponding layer object is destroyed.

procedure Resized

( Widget : not null access Gtk_Layered_Record;

Allocation : Gtk_Allocation

) is null ;

This procedure is called when the widget is resized. Allocation describes the new widget's size.

procedure Set_Aspect_Ratio

( Widget : not null access Gtk_Layered_Record;

Aspect_Ratio : GDouble

);

This procedure sets the widget's aspect ratio. The default value is 1.0. Constraint_Error is propagated when the aspect ratio is negative.

procedure Snapshot

( Widget : not null access Gtk_Layered_Record;

Target : Cairo_Surface_Handle / Cairo_Surface_Handle

);

This procedure is used for taking snapshots of the widget. E.g. for rendering its contents into a PDF file etc. The parameter Target is the surface or a context onto which the widget contents has to be drawn.

procedure Style_Changed

( Widget : not null access Gtk_Layered_Record

) is null ;

This is called when the widget's style properties are set. The default implementation does nothing.

2.3.2. Class-wide operations

procedure Initialize

( Widget : not null access Gtk_Layered_Record'Class

);

This procedure is used to initialize the widget's object. When overridden the implementation must call the parent's version from its body.

procedure Insert

( Widget : not null access Gtk_Layered_Record'Class;

Layer : in out Abstract_Layer'Class;

Position : Positive

);

This procedure inserts or moves the layer to the specified position. This procedure can be moved from one widget to another. The bottom layer has the position 1. The topmost layer has the position of the widget's depth. If Position is greater than the number of layers in the widget, Layer is moved to the widget's top. Note that the operation may also move other layers dependant on Layer.

2.4. Abstract bordered layer

The package Gtk.Layered.Abstract_Bordered provides an abstract type for creation of layers with borders:

type Abstract_Bordered_Layer is

abstract new Abstract_Layer

and Scalable_Layer

and Widened_Layer with private ;

A bordered layer when created automatically adds a foreground layer above itself. The foreground layer has the type:

type Foreground_Layer is new Abstract_Layer with private ;

The function of the foreground layer is to have a bracket for the layers visually belonging to the bordered layer. When the bordered layer is resized together with the widget, the layers within the brackets are sized in same relation as the are inside the border. In order to maintain this behavior the bordered layer changes the current size of the widget as returned by Get_Size. The foreground layer restores the effective widget size back. So the layers which visually belong to the bordered area should be put under the foreground layer returned by the function Get_Foreground.

The package declares further types:

type Border_Color_Type (Style_Color : Boolean := True) is record

case Style_Color is

when True => null ;

when False => Color : Gdk_Color;

end case ;

end record ;

This type describe the border's color. When the discriminant Style_Color is true , the border has the color of the widget's background as set in the widget's style. When Style_Color is false , the border has the color defined by the field Color.

Default_Color : constant Border_Color_Type := (Style_Color => True);

This constant defines the default border color.

2.4.1. Primitive operations

The following primitive operations are defined on Abstract_Bordered_Layer:

function Get_Aspected (Layer : Abstract_Bordered_Layer)

return Boolean;

This function returns the value set by Set_Aspected.

function Get_Border_Color (Layer : Abstract_Bordered_Layer)

return Border_Color_Type;

This function returns the border color. The result has the type Border_Color_Type.

function Get_Border_Depth (Layer : Abstract_Bordered_Layer)

return GDouble;

This function returns the visible border depth. The visible depth of the border is the projection of the z-axis onto the xy-surface.

function Get_Border_Shadow (Layer : Abstract_Bordered_Layer)

return Gtk_Shadow_Type;

This function returns the border shadow type. The types of shadows are defined in the package Gtk.Enums.

function Get_Border_Width (Layer : Abstract_Bordered_Layer)

return GDouble;

This function returns the border width. The visible border width does not include the shadows produced by its visual depth. The effective border width is computed as according to the Widened_Layer interface.

function Get_Deepened (Layer : Abstract_Bordered_Layer)

return Boolean;

This function returns true when the layer's visual depth is changed with the widget's size.

function Get_Foreground (Layer : Abstract_Bordered_Layer)

return access Foreground_Layer'Class;

This function returns the foreground layer corresponding to the bordered layer or null when there is none.

function Get_Lens_Reflex (Layer : Abstract_Bordered_Layer) return Gdk_RGBA;

function Get_Lens_Reflex (Layer : Abstract_Bordered_Layer) return Gdk_Color};

This function returns the color used for the light reflex on the lens. When not used it is transparent (the alpha channel is 0). The reflex is rendered on the foreground of the border so that all layers between it and the background appear under the lens.

function Get_Lens_Shadow (Layer : Abstract_Bordered_Layer) return Gdk_RGBA;

function Get_Lens_Shadow (Layer : Abstract_Bordered_Layer) return Gdk_Color;

This function returns the color used for the lens light shadow. When not used it is transparent (the alpha channel is 0). The reflex is rendered on the foreground of the border so that all layers between it and the background appear under the lens. The shadow is rendered on the foreground of the border so that all layers between it and the background appear under the lens.

function Has_Lens_Reflex (Layer : Abstract_Bordered_Layer)

return Boolean;

This function returns true if the border has a lens on top of all layers it contains. The lens shows a light reflex.

function Has_Lens_Shadow (Layer : Abstract_Bordered_Layer)

return Boolean;

This function returns true if the border has a lens on top of all layers it contains. The lens shows a light shadow.

procedure Set

( Layer : in out Abstract_Bordered_Layer;

Border_Width : GDouble;

Border_Depth : GDouble;

Border_Color : Border_Color_Type;

Border_Shadow : Gtk_Shadow_Type;

Lens_Reflex : Gdk_RGBA;

Lens_Shadow : Gdk_RGBA

);

This procedure sets parameters of the border. Border_Width is the width of the border without the border shadow. The border width can be 0.0. Border_Depth is the visual width of the border shadows. The parameter Border_Color of the type Border_Color_Type specifies the border color. The parameter Border_Shadow defines the border shadow type as defined in the package Gtk.Enums. The parameters Lens_Reflex and Lens_Shadow specify the colors used for the lens on top of all layers under its foreground. The lens can have reflex and shadow when alpha channel of the corresponding color is not 0.

procedure Set_Aspected

( Layer : in out Abstract_Bordered_Layer;

Aspected : Boolean

);

If Aspected is set to false , when the widget is resized the border width's aspect remains constant in all directions. I.e. the border width is proportional to the widget size in the corresponding direction. The option has no visible effect when the widget's aspect ratio is 1. For widgets having rectangular border this option should be true , otherwise vertical and horizontal borders would have different widths. The widgets having circular borders should have this set to false .

procedure Set_Deepened

( Layer : in out Abstract_Bordered_Layer;

Deepened : Boolean

);

This procedure is called to change the behavior upon widget's resizing. When the parameter Deepened is set to true , the visual border shadows will have the width set by the parameter Set_Border_Depth of Set multiplied by the widget's size as returned by Get_Size. Otherwise Set_Border_Depth is the absolute width.

2.4.2. Abstract operations

A derived type must implement the following abstract primitive operations:

procedure Draw_Contents

( Layer : in out Abstract_Bordered_Layer;

Context : Cairo_Context;

Area : Gdk_Rectangle

) is abstract ;

This procedure is called to draw the layer's contents within the border. When called, the border around the contents is already drawn. The path set by Set_Contents_Path is scaled to the required size. E.g. when it is an area to fill, the implementation would simply set the color and call Fill (Context). The context is translated and scaled according to the required location and size of the contents.

procedure Set_Contents_Path

( Layer : in out Abstract_Bordered_Layer;

Context : Cairo_Context;

Area : Gdk_Rectangle

) is abstract ;

This procedure is called before drawing the border. An implementation should create a path in Context. The border will be drawn around the path when the border layer is not scalable (see also Set_Scaled). When the layer is scalable, it is drawn inside the path, which is appropriately scaled. Finally Draw_Contents is called with the path to perform actual drawing.

2.5. Layer interfaces

Layers may implement additional interfaces declared in the package Gtk.Layered.

2.5.1. Layer location and object interfaces

The Layer_Location interface describes location of a layer in stack of the layers of the Gtk_Layered_Record widget:

type Layer_Location is limited interface ;

The Layer_Object interface describes a layer in stack of the layers of the Gtk_Layered_Record widget:

type Layer_Object is limited interface ;

The interface declares the abstract primitive operation:

procedure Add

( Layer : not null access Layer_Object;

Under : not null access Layer_Location'Class

) is abstract ;

This procedure places Layer under the location specified by the parameter Under.

2.5.2. Scalable layer interface

When the layer can be scaled when the widget is resized, it implements the interface:

type Scalable_Layer is limited interface ;

The interface declares the abstract primitive operations:

function Get_Scaled (Layer : Scalable_Layer)

return Boolean is abstract ;

This function returns true when the layer is scaled when the widget is resized. When the result is false the layer size is absolute and does not change.

procedure Set_Scaled

( Layer : in out Scalable_Layer;

Scaled : Boolean

) is abstract ;

This procedure changes the layer's behaviour when the widget is resized. When Scaled is set to true the layer is scaled together with the widget. The layer size is computed as the specified size multiplied by the widget's size as returned by Get_Size.

2.5.3. Widened layer interface

When the layer draws some lines widened when the widget is resized, it implements the interface:

type Widened_Layer is limited interface ;

The interface declares the abstract primitive operations:

function Get_Widened (Layer : Scalable_Layer)

return Boolean is abstract ;

This function returns true when the layer's lines are widened when the widget is resized. When the result is false the layer lines' widths remain unchanged.

procedure Set_Widened

( Layer : in out Scalable_Layer;

Widened : Boolean

) is abstract ;

This procedure changes the layer's behavior when the widget is resized. When Widened is set to true the lines of the layer are widened together with the widget. The line width is computed as the specified width multiplied by the widget's size as returned by Get_Size.

2.5.4. Annotation layer interface

Annotation layer draws a set of texts attached to some scale. The interface of these layers:

type Annotation_Layer is limited interface ;

The interface declares the abstract primitive operations:

function Get_Face (Layer : Annotation_Layer) return Pango_Cairo_Font;

This function returns a handle to the font used of the annotation texts.

function Get_Height (Layer : Annotation_Layer) return GDouble;

This function returns the parameters of the outer ellipse bounding the scale ticks.

function Get_Markup

( Layer : Annotation_Layer;

Position : Positive

) return Boolean;

This function returns true if the corresponding annotation text uses pango markup. The texts are enumerated from 1. Constraint_Error is propagated when Position greater than the number returned by Get_Text_Number.

function Get_Stretch (Layer : Annotation_Layer) return GDouble;

This function returns the factor by which the text original width is stretched.

function Get_Text

( Layer : Annotation_Layer;

Position : Positive

) return UTF8_String;

This function returns the annotation text by its number. The texts are enumerated from 1. Constraint_Error is propagated when Position greater than the number returned by Get_Text_Number.

function Get_Texts_Number (Layer : Annotation_Layer) return Natural;

This function returns the number of annotation texts.

function Get_Ticks (Layer : Annotation_Layer) return Tick_Parameters;

This function returns the parameters of the ticks at which the annotation texts are drawn.

procedure Set_Face

( Layer : in out Annotation_Layer;

Face : Pango_Cairo_Font

);

This procedure changes the annotation texts font.

procedure Set_Text

( Layer : in out Annotation_Layer;

Position : Positive;

Text : UTF8_String;

Markup : Boolean := False

);

This procedure changes the annotation text by its number. The texts are enumerated from 1. Constraint_Error is propagated when Position greater than the number returned by Get_Text_Number + 1. When Markup is set to true the text contains pango markup.

procedure Set_Texts

( Layer : in out Annotation_Layer;

Texts : Gtk.Enums.String_List.GList;

Markup : Boolean := False

) is abstract ;

procedure Set_Texts

( Layer : in out Annotation_Layer;

Texts : UTF8_String;

Delimiter : Character := ' ';

Markup : Boolean := False

) is abstract;

This procedure changes all texts of the annotation text. When Markup is set to true the text contains pango markup.

The following operation is class-wide (internally dispatching):

procedure Set_Texts

( Layer : in out Annotation_Layer'Class;

Texts : Controlled_String_List;

Markup : Boolean := False

);

2.5.5. Needle interface

Needle layers implement the interface:

type Gauge_Needle is limited interface ;

The interface declares the abstract primitive operations:

function Get_Adjustment (Layer : Gauge_Needle)

return Gtk_Adjustment is abstract ;

This function returns the adjustment object used by the needle. There result is null when no adjustment object is used.

function Get_Value (Layer : Gauge_Needle)

return GDouble is abstract ;

This function returns value indicated by the needle. The result range is 0.0..1.0. The implementation of this function shall be task-safe.

procedure Set_Value

( Layer : in out Gauge_Needle;

Value : GDouble

) is abstract ;

This procedure sets the needle's value. When Value is not in the range 0.0..1.0 it is saturated to the nearest bound. The implementation of this procedure shall be task-safe. Note that changing the value does not cause layer redrawing. If necessary, this must be done explicitly.

2.6. Other types declared

2.6.1. Closures of elliptic arcs

The type Elliptic_Shape_Type describes the way an elliptic arc is closed:

type Elliptic_Shape_Type is (Sector, Segment, Bagel);

The values are:

Sector corresponds to an arc with the ends connected by two straight lines meeting in a point;

corresponds to an arc with the ends connected by two straight lines meeting in a point; Segment corresponds to an arc with the ends connected by a straight line;

corresponds to an arc with the ends connected by a straight line; Bagel corresponds to an arc with the ends connected by straight lines with the ends of another elliptic arc.

The type Elliptic_Arc_Closure describes the closure of an elliptic arc:

type Elliptic_Arc_Closure

( Shape : Elliptic_Shape_Type := Sector

) is

record

case Shape is

when Sector => Center : Cairo_Tuple;

when Bagel => Arc : Ellipse_Parameters;

when Segment => null ;

end case ;

end record ;

2.6.2. Line parameters

type Line_Parameters is record

Width : GDouble;

Color : Gdk_Color;

Line_Cap : Cairo_Line_Cap;

end record ;

The type Line_Parameters describes the parameters of a line:

Width is the line width;

is the line width; Color is the line color;

is the line color; Line_Cap is the style used for the line ends.

2.6.3. Tick parameters

subtype Tick_Number is Positive range 1 .. 1_000_000 ;

type Tick_Parameters is record

Step : GDouble;

First : Tick_Number;

Skipped : Tick_Number;

end record ;

The type Tick_Parameters describes the parameters of a set of ticks:

Step is the distance between two consequent ticks;

is the distance between two consequent ticks; First is the number of the first tick. The ticks are numbered from 1 to Skipped;

is the number of the first tick. The ticks are numbered from 1 to Skipped; Skipped is the number of skipped ticks.

2.6.4. Text transformation

type Text_Transformation is

( Moved_Inside,

Moved_Centered,

Moved_Outside,

Rotated,

Skewed

);

The type Text_Transformation describes the way texts are aligned along a curve:

The text is transformed and aligned in accordance to a curve. Here (x, y) are coordinates of a point at the curve where the text is to be shown and R is the line going through (x, y) and the curve's center:

Moved_Inside moves the text to ( x , y ) shifted along R towards the center by halves of the projection lengths of the text's height and width onto R ;

moves the text to ( , ) shifted along towards the center by halves of the projection lengths of the text's height and width onto ; Moved_Centered moves the text to ( x , y ) so that the curve would cross the text's center;

moves the text to ( , ) so that the curve would cross the text's center; Moved_Outside moves the text to ( x , y ) shifted along R away from the center by halves of the projection lengths of the text's height and width onto R ;

moves the text to ( , ) shifted along away from the center by halves of the projection lengths of the text's height and width onto ; Rotated moves the text's center to ( x , y ) rotating the text so that its vertical axis would be parallel to R ;

moves the text's center to ( , ) rotating the text so that its vertical axis would be parallel to ; Skewed moves the text's center to (x, y) skewing and rotating the text so that the text vertical axis would become parallel to R, and the text's horizontal axis would be parallel to some third vector (e.g. the major axis of some ellipse). The height of the text's parallelogram is kept equal to the original height of the text.

2.7. Refresh engine

There are two ways to implement a user interface application. One, used in GTK+, is event-driven. That is when the interface immediately responds to user action and other inputs, e.g. when the values indicated by gauges are read from the sensors. This approach may become very resource consuming when the user interface must render highly dynamic data. The input events at millisecond rate would likely block the interface. It is also meaningless to refresh the user interface at such high rates because human eye cannot track such rapid changes anyway.

An alternative approach is time-driven, when the user interface is updated at fixed rate, usually at about 50Hz, independently on the input events. Any of the approaches can used with Gtk_Layered_Record. It is also possible to mix them. In order to use event-driven updates of a widget, there is nothing to care about. The Gtk_Layered_Record widget responds to the expose event signal as any other widget. E.g. when the widget is resized or exposed it is redrawn automatically.

For time-driven refresh the package Gtk.Layered.Refresh_Engine is provided. The package defines a refresh engine type, which redraws the widgets connected to the engine object at the specified rate. The engine type is

type Layered_Refresh_Engine is tagged limited private ;

The following operation are defined on the refresh engines:

procedure Add

( Engine : in out Layered_Refresh_Engine;

Widget : not null access Gtk_Layered_Record'Class

);

This procedure adds Widget to the list of widgets refreshed by Engine. Nothing happens if the widget is already in the list. The same widget may participate several lists. The refresh engine holds a weak reference to the widget. This means that the widget is automatically removed from the list when destructed. Use_Error is propagated when this procedure is called when the engine is refreshing the widgets from its list, i.e. when called from a handler triggered by the engine.

procedure Delete

( Engine : in out Layered_Refresh_Engine;

Widget : not null access Gtk_Layered_Record'Class

);

This procedure removes Widget from the list of widgets refreshed by Engine. Nothing happens if the widget is not in the list. Use_Error is propagated when this procedure is called when the engine is about to refresh the widgets from its list.

procedure Delete

( Engine : in out Layered_Refresh_Engine;

Widget : not null access Gtk_Layered_Record'Class

);

This procedure removes Widget from the list of widgets refreshed by Engine. Nothing happens if the widget is not in the list. Use_Error is propagated when this procedure is called when the engine is about to refresh the widgets from its list.

function Get_Period (Engine : Layered_Refresh_Engine)

return Duration;

This function returns the refresh period of the engine.

procedure Refresh (Engine : in out Layered_Refresh_Engine);

This procedure performs actions driven by the engine. When overridden it must be called from the override..

procedure Set_Period

( Engine : in out Layered_Refresh_Engine;

Period : Duration

);

This procedure sets the refresh period of the engine. Initially the engine does not refresh, so this procedure should be called at least once. Constraint_Error is propagated when the period is out of range.

Implementation notes . The refresh engine uses GTK+ timeout functions. Current implementation of this feature may appear not real-time in the sense that the period set as the timeout is not absolute. In particular the effective period may be the sum of the specified period and the time required for drawing the widgets attached to the engine. If the drawing takes considerable time it must be taken into account when choosing the period. For example, to draw each 20ms widgets requiring 15ms to draw, the period should be set to 20-15ms = 5ms. See the function Get_Drawing_Time, which can be used in drawing time measurements.

3. Backgrounds

3.1. Elliptic background

The package Gtk.Layered.Elliptic_Background provides background layer bound by elliptic curves:

type Elliptic_Background_Layer (<>) is

new Abstract_Bordered_Layer with private ;

The following operations are defined in the package:

procedure Add_Elliptic_Background

( Under : not null access Layer_Location'Class;

Outer : Ellipse_Parameters := Unit_Circle;

[ Inner : Ellipse_Parameters / Center : Cairo_Tuple; ]

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Border_Width : GDouble := 0.0 ;

Border_Depth : GDouble := 1.0 ;

Border_Color : Border_Color_Type := Default_Color;

Border_Shadow : Gtk_Shadow_Type := Shadow_In;

Deepened : Boolean := False;

Lens_Reflex : Gdk_RGBA := ( 1.0 , 1.0 , 1.0 , 0.0 );

Lens_Shadow : Gdk_RGBA := ( 0.0 , 0.0 , 0.0 , 0.0 );

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Elliptic_Background

( Under : not null access Layer_Location'Class;

Outer : Ellipse_Parameters := Unit_Circle;

[ Inner : Ellipse_Parameters / Center : Cairo_Tuple; ]

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Border_Width : GDouble := 0.0 ;

Border_Depth : GDouble := 1.0 ;

Border_Color : Border_Color_Type := Default_Color;

Border_Shadow : Gtk_Shadow_Type := Shadow_In;

Deepened : Boolean := False;

Lens_Reflex : Gdk_RGBA := ( 1.0 , 1.0 , 1.0 , 0.0 );

Lens_Shadow : Gdk_RGBA := ( 0.0 , 0.0 , 0.0 , 0.0 );

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Elliptic_Background_Layer;

These procedure and function create an elliptic background. The parameter Under specifies the layer location. The background layers outer bound is an elliptic arc of the ellipse specified by the parameter Outer. The arc starts at the angle From and goes to the angle From + Length. Note that both angles are in the cairo coordinate system (absolute). The parameter Length can be negative.

The inner bound of the background can be another elliptic arc, of which ellipse is specified by the parameter Inner . The inner arc absolute angles are From to From + Length . The ends of two arcs are connected by straight lines;

. The inner arc absolute angles are to + . The ends of two arcs are connected by straight lines; When the parameter Center is specified rather than Inner , the ends of the elliptic arc are connected by two straight lines meeting in the point defined by Center . In this case the layer has the shape of an elliptic sector;

is specified rather than , the ends of the elliptic arc are connected by two straight lines meeting in the point defined by . In this case the layer has the shape of an elliptic sector; When neither Inner or Center parameter is specified, the ends of the elliptic arc are connected by a straight line. In this case shape is an elliptic sector.

The parameter Color specifies the background color. The parameters Border_Width, Border_Depth, Border_Color, Border_Shadow are the parameters the background layer's border. See the procedure Set for the meaning of these parameters. The parameters Lens_Reflex and Lens_Shadow are colors used for the lens on top of the layers between the background and the foreground. The lens has a light reflex and/or shadow with the colors specified. The alpha channel of the color when transparent (0) disables rendering the corresponding effect. Otherwise it is typically half-transparent 0.5. The parameters Deepened and Widened define the border's behavior upon the widget's layer sizing as described in Set_Deepened and Set_Widened. The parameter Scaled controls the layer and border resizing (see Set_Scaled). Constraint_Error is propagated when some of the parameters are illegal.

function Get_Color (Layer : Elliptic_Background_Layer) return Gdk_Color;

This function returns the background color.

function Get_From (Layer : Elliptic_Background_Layer) return GDouble;

This function returns the angle at the starting point of the elliptic arc.

function Get_Inner (Layer : Elliptic_Background_Layer)

return Elliptic_Arc_Closure;

This function returns the parameters of the inner bound of the background shape. The result has the type Elliptic_Arc_Closure.

function Get_Length (Layer : Elliptic_Background_Layer)

return GDouble;

This function returns the angular length of the outer elliptic arc bounding the background layer.

function Get_Outer (Layer : Elliptic_Background_Layer)

return Ellipse_Parameters;

This function returns the parameters of the outer elliptic arc bounding the background layer.

procedure Set

( Layer : in out Elliptic_Background_Layer;

Outer : Ellipse_Parameters;

Inner : Elliptic_Arc_Closure;

From : GDouble;

Length : GDouble;

Color : Gdk_Color;

Border_Width : GDouble;

Border_Depth : GDouble;

Border_Color : Border_Color_Type;

Border_Shadow : Gtk_Shadow_Type;

Lens_Reflex : Gdk_RGBA;

Lens_Shadow : Gdk_RGBA

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines.

3.2. Rectangular background

The package Gtk.Layered.Rectangular_Background provides background layer bound by a rectangle with rounded corners:

type Rectangular_Background_Layer (<>) is

new Abstract_Bordered_Layer with private ;

The following operations are defined in the package:

procedure Add_Rectangular_Background

( Under : not null access Layer_Location'Class;

Height : GDouble := 1.0 ;

Width : GDouble := 1.0 ;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

Rotation_Angle : GDouble := 0.0 ;

Corner_Radius : GDouble := 0.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Border_Width : GDouble := 0.0 ;

Border_Depth : GDouble := 1.0 ;

Border_Color : Border_Color_Type := Default_Color;

Border_Shadow : Gtk_Shadow_Type := Shadow_In;

Deepened : Boolean := False;

Lens_Reflex : Gdk_RGBA := ( 1.0 , 1.0 , 1.0 , 0.0 );

Lens_Shadow : Gdk_RGBA := ( 0.0 , 0.0 , 0.0 , 0.0 );

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Elliptic_Background

( Under : not null access Layer_Location'Class;

Height : GDouble := 1.0 ;

Width : GDouble := 1.0 ;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

Rotation_Angle : GDouble := 0.0 ;

Corner_Radius : GDouble := 0.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Border_Width : GDouble := 0.0 ;

Border_Depth : GDouble := 1.0 ;

Border_Color : Border_Color_Type := Default_Color;

Border_Shadow : Gtk_Shadow_Type := Shadow_In;

Lens_Reflex : Gdk_RGBA := ( 1.0 , 1.0 , 1.0 , 0.0 );

Lens_Shadow : Gdk_RGBA := ( 0.0 , 0.0 , 0.0 , 0.0 );

Deepened : Boolean := False;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Rectangular_Background_Layer;

These procedure and function create a rectangular background. The parameter Under specifies the layer location. The rectangle height and width are specified by the parameters Height and Width. The parameter Center is the rectangle's center. The parameter Rotation_Angle is the angle between the horizontal axis of the rectangle and the x-axis of the cairo coordinate system. Corner_Radius is the radius of the curves rounding the rectangle corners. The parameter Color specifies the background color. The parameters Border_Width, Border_Depth, Border_Color, Border_Shadow are the parameters the background layer's border. See the procedure Set for the meaning of these parameters. The parameters Lens_Reflex and Lens_Shadow are colors used for the lens on top of the layers between the background and the foreground. The lens has a light reflex and/or shadow with the colors specified. The alpha channel of the color when transparent (0) disables rendering the corresponding effect. Otherwise it is typically half-transparent 0.5. The parameters Deepened and Widened define the border's behavior upon the widget's layer sizing as described in Set_Deepened and Set_Widened. The parameter Scaled controls the layer and border resizing (see Set_Scaled). Constraint_Error is propagated when some of the parameters are illegal.

function Get_Center (Layer : Rectangular_Background_Layer)

return Cairo_Tuple;

This function returns the position of the background's rectangle.

function Get_Color (Layer : Rectangular_Background_Layer) return Gdk_Color;

This function returns the background color.

function Get_Corner_Radius (Layer : Rectangular_Background_Layer)

return GDouble;

This function returns the radius of the rectangle corners.

function Get_Height (Layer : Rectangular_Background_Layer) return GDouble;

This function returns the height of the rectangular border.

function Get_Rotation_Angle (Layer : Rectangular_Background_Layer)

return GDouble;

This function returns the angle between the width-axis of the rectangle and the x-axis of the cairo coordinate system.

function Get_Width (Layer : Rectangular_Background_Layer)

return GDouble;

This function returns the width of the rectangular border.

procedure Set

( Layer : in out Elliptic_Background_Layer;

Height : GDouble;

Width : GDouble;

Center : Cairo_Tuple;

Rotation_Angle : GDouble;

Corner_Radius : GDouble;

Color : Gdk_Color;

Border_Width : GDouble;

Border_Depth : GDouble;

Border_Color : Border_Color_Type;

Border_Shadow : Gtk_Shadow_Type;

Lens_Reflex : Gdk_RGBA;

Lens_Shadow : Gdk_RGBA

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines.

4. Scales

Scale is a set of ticks used to visually underline special values indicated by the instrument. A set of ticks is controlled by three parameters Step, First, Skipped:

Step is the distance between two ticks;

First is the number of the tick corresponding to the beginning of the scale;

Skipped is the number of the tick to skip. E.g. when 5 then ticks with the numbers 5, 10, 15 etc are not drawn.

4.1. Elliptic scale

The package Gtk.Layered.Elliptic_Scale provides scales bound by two elliptic curves:

The ticks are drawn from inner to outer bounding ellipses. Both ellipses have the same center. On the figure above the inner ellipse parameters are (r 1 , k 1 , α 1 ). The outer ellipse parameters are (r 2 , k 2 , α 2 ). The ticks start at the angle β 1 and end at the angle β 2 . The ticks are numbered 1, 2, 3, 4 until the skipped tick, which is not drawn. On the figure the skipped tick has the number 5. The number of the first tick can be different from 1. For example, in our example the first tick has the number 1. Should the first tick skipped, then its number must be set to 5.

type Elliptic_Scale_Layer (<>) is

new Abstract_Bordered_Layer

and Scalable_Layer

and Widened_Layer with private ;

The following operations are defined in the package:

procedure Add_Elliptic_Scale

( Under : not null access Layer_Location'Class;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

Outer : Ellipse_Parameters := Unit_Circle;

Inner : Ellipse_Parameters := Unit_Circle / 2.0 ;

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Elliptic_Scale

( Under : not null access Layer_Location'Class;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

Outer : Ellipse_Parameters := Unit_Circle;

Inner : Ellipse_Parameters := Unit_Circle / 2.0 ;

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Elliptic_Scale_Layer;

These procedure and function create a scale with the ticks bound by two ellipses. The parameter Under specifies the layer location. The parameter Step is the angular distance between two ticks. The angle is in the cairo coordinates. The parameters Step, First and Skipped describe the set of ticks. The parameters Outer and Inner are the outer and inner bounds of the ticks. The center of the inner ellipse is ignored and considered same as the center of the outer ellipse. The parameter From is the angular value corresponding to the first tick of the scale. The parameter Length is the angular length of the scale. Both angles are absolute in the cairo coordinates. Length can be negative when ticks go counterclockwise. The parameters Width, Color, Line_Cap describe the tick line. Width is the tick line width. When Widened is true , the effective tick width is Width multiplied by the widget's size as returned by Get_Size. Color is the line color. Line_Cap is the style used for the line ends. The parameter Scaled when true resizes the layer when the widget is resized:

The curvatures of Inner and Outer are divided by the widget's size (as returned by Get_Size);

and are divided by the widget's size (as returned by Get_Size); The radiuses of Inner and Outer are multiplied by the size;

and are multiplied by the size; The coordinates of the ellipses center are multiplied by the size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_From (Layer : Elliptic_Scale_Layer) return GDouble;

This function returns the angle of the first tick in cairo coordinates.

function Get_Inner (Layer : Elliptic_Scale_Layer)

return Ellipse_Parameters;

This function returns the parameters of the inner ellipse bounding the scale ticks.

function Get_Length (Layer : Elliptic_Scale_Layer) return GDouble;

This function returns the angular length of the scale.

function Get_Line (Layer : Elliptic_Scale_Layer)

return Line_Parameters;

This function returns line parameters of the scale ticks.

function Get_Outer (Layer : Elliptic_Scale_Layer)

return Ellipse_Parameters;

This function returns the parameters of the outer ellipse bounding the scale ticks.

function Get_Ticks (Layer : Elliptic_Scale_Layer)

return Tick_Parameters;

This function returns the scale ticks parameters.

procedure Set

( Layer : in out Elliptic_Scale_Layer;

Outer : Ellipse_Parameters;

Inner : Ellipse_Parameters;

Line : Line_Parameters;

Ticks : Tick_Parameters;

From : GDouble;

Length : GDouble

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

4.2. Flat scale

The package Gtk.Layered.Flat_Scale provides scales with the ticks arranged along a straight line. The ticks are drawn perpendicularly to the line. The tick centers lie on the line. The ticks are numbered 1, 2, 3, 4 until the skipped tick, which is not drawn. The number of the first tick can be different from 1.

type Flat_Scale_Layer (<>) is

new Abstract_Layer

and Scalable_Layer

and Widened_Layer with private ;

The following operations are defined in the package:

procedure Add_Flat_Scale

( Under : not null access Layer_Location'Class;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Length : GDouble := 1.0 ;

Breadth : GDouble := 1.0 ;

Angle : GDouble := 0.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Elliptic_Scale

( Under : not null access Layer_Location'Class;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Length : GDouble := 1.0 ;

Breadth : GDouble := 1.0 ;

Angle : GDouble := 0.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Flat_Scale_Layer;

These procedure and function create a scale with the ticks arranged along a straight line. The parameter Under specifies the layer location. The parameter Step is the distance between two ticks. The parameters Step, First and Skipped describe the set of ticks. The parameter From is the coordinates of the first tick center. The parameter Length is the length of the scale. Breadth is the length of a tick. Angle is the angle between the x-axis of cairo coordinate system and the scale. The parameters Width, Color, Line_Cap describe the tick line. Width is the tick line width. When Widened is true , the effective tick width is Width multiplied by the widget's size as returned by Get_Size. Color is the line color. Line_Cap is the style used for the line ends. The parameter Scaled when true resizes the layer when the widget is resized:

The first tick position x is multiplied by the widget's size (see Get_Size) and placed in the coordinate system centered in the widget's center (see Get_Center);

is multiplied by the widget's size (see Get_Size) and placed in the coordinate system centered in the widget's center (see Get_Center); The first tick position y is multiplied by the widget's size and placed in the coordinate system centered in the widget's center;

is multiplied by the widget's size and placed in the coordinate system centered in the widget's center; Length, width, step are multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Angle (Layer : Flat_Scale_Layer) return GDouble;

This function returns the angle between the scale and x-axis of cairo coordinates.

function Get_Breadth (Layer : Flat_Scale_Layer) return GDouble;

This function returns the tick length.

function Get_From (Layer : Flat_Scale_Layer) return Cairo_Tuple;

This function returns the first tick's center in cairo coordinates.

function Get_Length (Layer : Flat_Scale_Layer) return GDouble;

This function returns the length of the scale.

function Get_Line (Layer : Flat_Scale_Layer) return Line_Parameters;

This function returns line parameters of the scale ticks.

function Get_Ticks (Layer : Flat_Scale_Layer) return Tick_Parameters;

This function returns the scale ticks parameters.

procedure Set

( Layer : in out Flat_Scale_Layer;

Line : Line_Parameters;

Ticks : Tick_Parameters;

From : Cairo_Tuple;

Length : GDouble;

Breadth : GDouble;

Angle : GDouble

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

5. Annotations

Annotation is a set of texts usually placed nearby corresponding scale ticks. Similarly to scales annotations can be elliptic and flat.

5.1. Elliptic annotation

The package Gtk.Layered.Elliptic_Annotation provides annotations for elliptic scales:

type Elliptic_Annotation_Layer (<>) is

new Abstract_Layer and Scalable_Layer with private ;

The following operations are defined in the package:

procedure Add_Elliptic_Annotation

( Under : not null access Layer_Location'Class;

Texts : texts specification;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

Ellipse : Ellipse_Parameters := Unit_Circle;

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " arial ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Mode : Text_Transformation := Moved_Centered;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

[ Delimiter : Character := ' '; ]

Markup : Boolean := False;

Scaled : Boolean := False

);

function Add_Elliptic_Annotation

( Under : not null access Layer_Location'Class;

Texts : texts specification;

Step : Double;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

Ellipse : Ellipse_Parameters := Unit_Circle;

From : GDouble := 0.0 ;

Length : GDouble := 2.0 * Pi;

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " arial ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Mode : Text_Transformation := Moved_Centered;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

[ Delimiter : Character := ' '; ]

Markup : Boolean := False;

Scaled : Boolean := False

) return not null access Elliptic_Annotation_Layer;

These procedure and function create annotation arranged along an elliptic arc. The parameter Under specifies the layer location. The parameter Texts defines the set of texts used for the annotation. It may take one of three forms:

A list of strings:

Texts : Gtk.Enums.String_List.GList;

A controlled list of strings:

Texts : Controlled_String_List; The list can be created using expressions like " A "/" B "/" C " .

A string of annotation texts separated using the delimiter character:

Texts : UTF8_String;

Missing texts cause no error, they are not indicated. The parameter Markup is false for plain texts. Otherwise, text are assumed containing pango markup. The parameter Step is the angular distance between two ticks at which annotation texts to be shown. The angle is in the cairo coordinates. The parameters Step, First and Skipped describe the set of ticks. The parameter Ellipse is specifies the ellipse of the arc where annotation texts are placed. The parameter From is the angular value corresponding to the first annotation text. The parameter Length is the angular length of the annotation. Both angles are absolute in the cairo coordinates. Length can be negative when annotation texts go counterclockwise. Face is the font used for annotation texts. Height is the height of the annotation texts. Stretch is the factor by which the original text width is stretched. When Stretch is 1.0, the text's height to width relation is not changed. Mode is annotation text transformation mode. Color is the text color. The parameter Scaled when true resizes the layer when the widget is resized:

The curvature of Ellipse is divided by the widget's size (as returned by Get_Size);

is divided by the widget's size (as returned by Get_Size); The radius of Ellipse is multiplied by the size;

is multiplied by the size; The coordinates of the ellipse center are multiplied by the size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

The text size is multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Color (Layer : Elliptic_Annotation_Layer)

return Gdk_Color;

This function returns the text color.

function Get_Ellipse (Layer : Elliptic_Annotation_Layer)

return Ellipse_Parameters;

This function returns the parameters of the ellipse where the annotation texts are placed.

function Get_From (Layer : Elliptic_Annotation_Layer) return GDouble;

This function returns the angle of the first annotation text.

function Get_Length (Layer : Elliptic_Annotation_Layer)

return GDouble;

This function returns the angular length of the annotation.

function Get_Mode (Layer : Elliptic_Annotation_Layer)

return Text_Transformation;

This function returns the annotation texts transformation mode.

procedure Set

( Layer : in out Elliptic_Annotation_Layer;

Ellipse : Ellipse_Parameters;

Ticks : Tick_Parameters;

From : GDouble;

Length : GDouble;

Face : Pango_Cairo_Font;

Mode : Text_Transformation;

Height : GDouble;

Stretch : GDouble;

Color : Gdk_Color

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

5.2. Flat annotation

The package Gtk.Layered.Flat_Annotation provides annotations for flat scales:

type Flat_Annotation_Layer (<>) is

new Abstract_Layer and Scalable_Layer with private ;

The following operations are defined in the package:

procedure Add_Flat_Annotation

( Under : not null access Layer_Location'Class;

Texts : texts specification;

Step : GDouble;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Length : GDouble := 2.0 * Pi;

Scale_Angle : GDouble := 0.0 ;

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " arial ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Text_Angle : GDouble := 0.0 ;

Justify : Alignment := Center;

[ Delimiter : Character := ' '; ]

Markup : Boolean := False;

Scaled : Boolean := False

);

function Add_Flat_Annotation

( Under : not null access Layer_Location'Class;

Texts : texts specification;

Step : Double;

First : Tick_Number := Tick_Number'Last;

Skipped : Tick_Number := Tick_Number'Last;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Length : GDouble := 2.0 * Pi;

Scale_Angle : GDouble := 0.0 ;

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " arial ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Text_Angle : GDouble := 0.0 ;

Justify : Alignment := Center;

[ Delimiter : Character := ' '; ]

Markup : Boolean := False;

Scaled : Boolean := False

) return not null access Flat_Annotation_Layer;

These procedure and function create annotation arranged along a straight line. The parameter Under specifies the layer location. The parameter Texts defines the set of annotation texts. Missing texts cause no error, they are not indicated. The parameter Markup is false for plain texts. Otherwise, text are assumed containing pango markup. The parameter Step is the distance between two ticks annotation texts to be shown. The parameters Step, First and Skipped describe the set of ticks. The parameter From is the position of the first annotation text. The parameter Length is the length of the annotation. Scale_Angle is the angle between the x-axis of cairo coordinate system and the line along which annotation texts are placed. Face is the font used for annotation texts. Height is the height of the annotation texts. Stretch is the factor by which the original text width is stretched. When Stretch is 1.0, the text's height to width relation is not changed. Color is the text color. Text_Angle is the angle between the x-axis of cairo coordinate system and horizontal axis of the annotation texts. Justify specifies the way the annotation texts are aligned:

Left , the text's right margin is the text location;

, the text's right margin is the text location; Center , the text's center is the text location;

, the text's center is the text location; Right, the text's left margin is the text location.

The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the annotation beginning ( From ) are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

) are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center; The annotation length ( Length ) is multiplied by the widget's size;

) is multiplied by the widget's size; The text size is multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Color (Layer : Flat_Annotation_Layer) return Gdk_Color;

This function returns the text color.

function Get_From (Layer : Flat_Annotation_Layer) return Cairo_Tuple;

This function returns the coordinates of the first annotation text.

function Get_Justify (Layer : Flat_Annotation_Layer)

return Alignment;

This function returns the way the annotation texts are aligned.

function Get_Length (Layer : Flat_Annotation_Layer) return GDouble;

This function returns the angular length of the annotation.

function Get_Scale_Angle (Layer : Flat_Annotation_Layer)

return GDouble;

This function returns the angle of the straight line along which the annotation texts are arranged.

procedure Set

( Layer : in out Flat_Annotation_Layer;

Ticks : Tick_Parameters;

From : Cairo_Tuple;

Length : GDouble;

Scale_Angle : GDouble;

Face : Pango_Cairo_Font;

Height : GDouble;

Stretch : GDouble;

Color : Gdk_Color;

Text_Angle : GDouble;

Justify : Alignment

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6. Needles

The needle layers draw a shape which location reflect some changing value. The value may be set explicitly using the needle interface. It also can be set using an adjustment object.

6.1. Needle

The package Gtk.Layered.Needle provides gauge a needle rotating around its center:

The needle tip indicates the value on a circular scale with the center in the needle's center. The layer type is:

type Needle_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated value. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Needle

( Under : not null access Layer_Location'Class;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Needle

( Under : not null access Layer_Location'Class;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Needle_Layer;

These procedure and function create a needle. The parameter Under specifies the layer location. The parameter Center specifies the position of the needle's center in cairo coordinates. The parameter From is the angle corresponding to the value 0.0. The parameter Length is the angular length of the value 1.0. The needle moves between From and From + Length. When the value of Length is negative the needle moves counterclockwise. The parameter Tip_Length is the distance between the needle's center and its tip. Tip_Width is the width of the needle at its tip. Tip_Cap is the style of the needle tip. The parameters Rear_Length, Rear_Width, Rear_Cap specify the needle rear end. Rear_Length can be negative. Color is needle's color. Adjustment is the adjustment object, which state needle would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to From + Length. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the needle's center are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

The needle's lengths and widths are multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Center (Layer : Needle_Layer) return Cairo_Tuple;

This function returns the needle's center.

function Get_Color (Layer : Needle_Layer) return Gdk_Color;

This function returns the needle's color.

function Get_From (Layer : Needle_Layer) return GDouble;

This function returns the angle of the value 0.0.

function Get_Length (Layer : Needle_Layer) return GDouble;

This function returns the angular length of the needle values range [0.0..1.0].

function Get_Rear (Layer : Needle_Layer) return End_Parameters;

This function returns the line parameters of the needle's rear end.

function Get_Tip (Layer : Needle_Layer) return End_Parameters;

This function returns the line parameters of the needle's tip.

procedure Set

( Layer : in out Needle_Layer;

Center : Cairo_Tuple;

From : GDouble;

Length : GDouble;

Tip : End_Parameters;

Rear : End_Parameters;

Color : Gdk_Color

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.2. Clock hand

The package Gtk.Layered.Clock_Hand provides a needle shaped as a clock hand:

The hand's tip indicates the time on a circular dial with the center in the hand's center. The layer type is:

type Clock_Hand_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated time. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Clock_Hand

( Under : not null access Layer_Location'Class;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Bulb_Position : GDouble := 13.0 ;

Bulb_Radius : GDouble := 5.0 ;

Bulb_Width : GDouble := 2.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Clock_Hand

( Under : not null access Layer_Location'Class;

Center : Cairo_Tuple := ( 0.0 , 0.0 );

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Bulb_Position : GDouble := 13.0 ;

Bulb_Radius : GDouble := 5.0 ;

Bulb_Width : GDouble := 2.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Clock_Hand _Layer;

These procedure and function create a hand. The parameter Under specifies the layer location. The parameter Center specifies the position of the hand's center in cairo coordinates. The parameter From is the angle corresponding to the value 0.0. The parameter Length is the angular length of the value 1.0. The hand moves between From and From + Length. When the value of Length is negative the hand moves counterclockwise. The parameter Tip_Length is the distance between the center and the hand's tip. Tip_Width is the width of the hand at its tip. Tip_Cap is the style of the hand tip. The parameters Rear_Length, Rear_Width, Rear_Cap specify the hand rear end. Rear_Length can be negative. Bulb_Position is the distance from the hand's center to the bulb's center. Bulb_Radius is the radius of the bulb. Bulb_Width is the width of the bulb's line. Color is hand's color. Adjustment is the adjustment object, which state hand would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to From + Length. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the hand's center are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

The needle's lengths and widths are multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Bulb_Position (Layer : Clock_Hand_Layer)

return Cairo_Tuple;

This function returns the hand bulb's position.

function Get_Bulb_Radius (Layer : Clock_Hand_Layer)

return Cairo_Tuple;

This function returns the hand bulb's radius.

function Get_Bulb_Width (Layer : Clock_Hand_Layer) return Cairo_Tuple;

This function returns the bulb's line width.

function Get_Center (Layer : Clock_Hand_Layer) return Cairo_Tuple;

This function returns the hand's center.

function Get_Color (Layer : Clock_Hand_Layer) return Gdk_Color;

This function returns the hand's color.

function Get_From (Layer : Clock_Hand_Layer) return GDouble;

This function returns the angle of the value 0.0.

function Get_Length (Layer : Clock_Hand_Layer) return GDouble;

This function returns the angular length of the hand values range [0.0..1.0].

function Get_Rear (Layer : Clock_Hand_Layer) return End_Parameters;

This function returns the line parameters of the hand's rear end.

function Get_Tip (Layer : Clock_Hand_Layer) return End_Parameters;

This function returns the line parameters of the hand's tip.

procedure Set

( Layer : in out Clock_Hand_Layer;

Center : Cairo_Tuple;

From : GDouble;

Length : GDouble;

Tip : End_Parameters;

Rear : End_Parameters;

Bulb_Position : GDouble;

Bulb_Radius : GDouble;

Bulb_Width : GDouble;

Color : Gdk_Color

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.3. Elliptic bar needle

The package Gtk.Layered.Elliptic_Bar provides needles shaped as an elliptic arc from some starting angle to the angle indicating the value:

The needle tip indicates the value on a circular scale with the center in the needle's center. The layer type is:

type Elliptic_Bar_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer

and Widened_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated value. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Elliptic_Bar

( Under : not null access Layer_Location'Class;

Ellipse : Ellipse_Parameters := Unit_Circle;

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Elliptic_Bar

( Under : not null access Layer_Location'Class;

Ellipse : Ellipse_Parameters := Unit_Circle;

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Elliptic_Bar_Layer;

These procedure and function create an elliptic bar. The parameter Under specifies the layer location. Ellipse is the parameters of the ellipse to which the bar belongs. From is the angle (between the x-axis and the ellipse point) corresponding to the value 0.0. The parameter Length is the angular length of the value 1.0. The bar is an arc From and From + Length. When the value of Length is negative the needle moves counterclockwise. Width is the width of the bar line. Color is bar's color. Line_Cap is the style of the bar line ends. Adjustment is the adjustment object, which state needle would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to From + Length. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The curvature of Ellipse is divided by the widget's size (as returned by Get_Size);

is divided by the widget's size (as returned by Get_Size); The radius of Ellipse is multiplied by the size;

is multiplied by the size; The coordinates of the ellipse center are multiplied by the size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center.

When Widened is true the line width is the value of Width multiplied by the widget's size. Constraint_Error is propagated when some of the parameters are illegal.

function Get_Ellipse (Layer : Elliptic_Bar_Layer)

return Ellipse_Parameters;

This function returns the ellipse parameters of the bar's line.

function Get_From (Layer : Elliptic_Bar_Layer) return GDouble;

This function returns the angle corresponding to the value 0.0.

function Get_Length (Layer : Elliptic_Bar_Layer) return GDouble;

This function returns the angular length of the values range [0.0..1.0].

function Get_Line (Layer : Elliptic_Bar_Layer) return Line_Parameters;

This function returns the line parameters of the bar.

procedure Set

( Layer : in out Elliptic_Bar_Layer;

Ellipse : Ellipse_Parameters;

From : GDouble;

Length : GDouble;

Line : Line_Parameters

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.4. Filled shape needle

The package Gtk.Layered.Sector_Needle provides needles shaped as elliptic bagels, sectors and segments:

The layer type is:

type Sector_Needle_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated value. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Sector_Needle

( Under : not null access Layer_Location'Class;

Outer : Ellipse_Parameters := Unit_Circle;

[ Inner : Ellipse_Parameters / Center : Cairo_Tuple; ]

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Sector_Needle

( Under : not null access Layer_Location'Class;

Outer : Ellipse_Parameters := Unit_Circle;

[ Inner : Ellipse_Parameters / Center : Cairo_Tuple; ]

From : GDouble := 3.0 * Pi / 4.0 ;

Length : GDouble := 3.0 * Pi / 2.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Sector_Needle_Layer;

These procedures and functions create an sector needle. The parameter Under specifies the layer location. The outer bound of the shape is an elliptic arc of the ellipse specified by the parameter Outer. The arc starts at the angle From and goes to the angle corresponding to the current value. The value 0.0 corresponds to the angle From. The value 1.0 corresponds to the angle From + Length. Note that both angles are in the cairo coordinate system (absolute). The parameter Length can be negative.

The inner bound of the background can be another elliptic arc, of which ellipse is specified by the parameter Inner . The inner arc absolute angles are From to From + Length . The ends of two arcs are connected by straight lines;

. The inner arc absolute angles are to + . The ends of two arcs are connected by straight lines; When the parameter Center is specified rather than Inner , the ends of the elliptic arc are connected by two straight lines meeting in the point defined by Center . In this case the layer has the shape of an elliptic sector;

is specified rather than , the ends of the elliptic arc are connected by two straight lines meeting in the point defined by . In this case the layer has the shape of an elliptic sector; When neither Inner or Center parameter is specified, the ends of the elliptic arc are connected by a straight line. In this case shape is an elliptic sector.

Color is the color used to fill the shape. Adjustment is the adjustment object, which state needle would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to From + Length. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The curvature of Ellipse is divided by the widget's size (as returned by Get_Size);

is divided by the widget's size (as returned by Get_Size); The radius of Ellipse is multiplied by the size;

is multiplied by the size; The coordinates of the ellipse center are multiplied by the size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center.

function Get_Color (Layer : Sector_Needle_Layer) return Gdk_Color;

This function returns the fill color.

function Get_From (Layer : Sector_Needle_Layer) return GDouble;

This function returns the angle corresponding to the value 0.0.

function Get_Inner (Layer : Sector_Needle_Layer)

return Elliptic_Arc_Closure;

This function returns the parameters of the inner bound of the background shape. The result has the type Elliptic_Arc_Closure.

function Get_Length (Layer : Sector_Needle_Layer) return GDouble;

This function returns the angular length of the values range [0.0..1.0].

function Get_Outer (Layer : Sector_Needle_Layer)

return Ellipse_Parameters;

This function returns the parameters of the outer elliptic arc bounding the background layer.

procedure Set

( Layer : in out Elliptic_Background_Layer;

Outer : Ellipse_Parameters;

Inner : Elliptic_Arc_Closure;

From : GDouble;

Length : GDouble;

Color : Gdk_Color;

);

This procedure changes parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.5. Flat needle

The package Gtk.Layered.Flat_Needle provides needles for flat scales. The needle moves along a straight line going through the needle's center:

type Flat_Needle_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated value. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Flat_Needle

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

To : Cairo_Tuple := ( 0.0 , 1.0 );

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Flat_Needle

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

To : Cairo_Tuple := ( 0.0 , 1.0 );

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Flat_Needle_Layer;

These procedure and function create a needle. The parameter Under specifies the layer location. The needle's center moves between the points From and To. The value 0.0 corresponds to From. The value 1.0 corresponds to To. The parameter Tip_Length is the distance between the center and the needle tip. Tip_Width is the width of the needle at its tip. Tip_Cap is the style of the needle tip. The parameters Rear_Length, Rear_Width, Rear_Cap specify the needle rear end. Rear_Length can be negative. Color is needle's color. Adjustment is the adjustment object, which state needle would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to To. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the line along which the needle's moves are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

The needle's lengths and widths are multiplied by the widget's size.

Constraint_Error is propagated when some of the parameters are illegal. There exist two alternative subroutines to create a flat needle:

procedure Add_Flat_Needle

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Length : GDouble := 1.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Flat_Needle

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Length : GDouble := 1.0 ;

Tip_Length : GDouble := 20.0 ;

Tip_Width : GDouble := 2.0 ;

Tip_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Rear_Length : GDouble := 3.0 ;

Rear_Width : GDouble := 3.0 ;

Rear_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Flat_Needle_Layer;

Here instead of the parameter To the point corresponding to the value 1.0 is specified by Angle and Length.

function Get_Angle (Layer : Flat_Needle_Layer) return GDouble;

This function returns the angle of the line along which needle's center moves.

function Get_Color (Layer : Flat_Needle_Layer) return Gdk_Color;

This function returns the needle's color.

function Get_From (Layer : Flat_Needle_Layer) return Cairo_Tuple;

This function returns the point corresponding to the value 0.0.

function Get_Length (Layer : Flat_Needle_Layer) return GDouble;

This function returns the distance between the points corresponding to the values 0.0 and 1.0.

function Get_Rear (Layer : Flat_Needle_Layer) return End_Parameters;

This function returns the line parameters of the needle's rear end.

function Get_Tip (Layer : Flat_Needle_Layer) return End_Parameters;

This function returns the line parameters of the needle's tip.

function Get_To (Layer : Flat_Needle_Layer) return Cairo_Tuple;

This function returns the point corresponding to the value 1.0.

procedure Set

( Layer : in out Flat_Needle_Layer;

From : Cairo_Tuple;

To : Cairo_Tuple;

Tip : End_Parameters;

Rear : End_Parameters;

Color : Gdk_Color

);

procedure Set

( Layer : in out Flat_Needle_Layer;

From : Cairo_Tuple;

Angle : GDouble;

Length : GDouble;

Tip : End_Parameters;

Rear : End_Parameters;

Color : Gdk_Color

);

These procedures change parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.6. Bar needle

The package Gtk.Layered.Bar provides needles for flat scales shaped as a bar:

The layer type is:

type Bar_Layer (<>) is

new Abstract_Layer

and Gauge_Needle

and Scalable_Layer

and Widened_Layer with private ;

The type implements the Gauge_Needle interface, which can be used to get and set the indicated value. Another way to do this is to use an adjustment object. The following operations are defined in the package:

procedure Add_Bar

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

To : Cairo_Tuple := ( 0.0 , 1.0 );

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Bar

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

To : Cairo_Tuple := ( 0.0 , 1.0 );

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Bar_Layer;

These procedure and function create a needle. The parameter Under specifies the layer location. The needle's center moves between the points From and To. The value 0.0 corresponds to From. The value 1.0 corresponds to To. Width is the width of the needle's line. Cap is the style of the line ends. Color is needle's color. Adjustment is the adjustment object, which state needle would reflect. The lower adjustment's value corresponds to From. The upper adjustment's value corresponds to To. When Adjustment is null , no adjustment is used. The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the line along which the needle's moves are multiplied by the size as returned by Get_Size and the result is used as the center's coordinates relatively to the widget's center as returned by Get_Center;

The needle's lengths and widths are multiplied by the widget's size.

When Widened is true the line width is the value of Width multiplied by the widget's size. Constraint_Error is propagated when some of the parameters are illegal. There exist two alternative subroutines to create a flat needle:

procedure Add_Bar

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Length : GDouble := 1.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

);

function Add_Bar

( Under : not null access Layer_Location'Class;

From : Cairo_Tuple := ( 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Length : GDouble := 1.0 ;

Width : GDouble := 1.0 ;

Color : Gdk_Color := RGB ( 1.0 , 0.0 , 0.0 );

Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False;

Widened : Boolean := False

) return not null access Bar_Layer;

Here instead of the parameter To the point corresponding to the value 1.0 is specified by Angle and Length.

function Get_Angle (Layer : Bar_Layer) return GDouble;

This function returns the angle of the line along which needle's center moves.

function Get_From (Layer : Bar_Layer) return Cairo_Tuple;

This function returns the point corresponding to the value 0.0.

function Get_Length (Layer : Bar_Layer) return GDouble;

This function returns the distance between the points corresponding to the values 0.0 and 1.0.

function Get_Line (Layer : Bar_Layer) return Line_Parameters;

This function returns the line parameters of the bar.

function Get_To (Layer : Bar_Layer) return Cairo_Tuple;

This function returns the point corresponding to the value 1.0.

procedure Set

( Layer : in out Bar_Layer;

From : Cairo_Tuple;

To : Cairo_Tuple;

Line : Line_Parameters

);

procedure Set

( Layer : in out Bar_Layer;

From : Cairo_Tuple;

Angle : GDouble;

Length : GDouble;

Line : Line_Parameters

);

These procedures change parameters of the layer. The meaning of the parameters is same as in the corresponding Add-subroutines. Constraint_Error is propagated when some of the parameters are illegal.

6.7. Digital value

The package Gtk.Layered.Digital provides a layer indicating a value as a text:

Here the value 13.5 is indicated in 1 ½ π rotated text. The layer is basically Label_Layer which text is determined by the indicated value. Value to text conversion is performed by a primitive operation Render which can be overridden when necessary. The layer type is declared as follows:

type Digital_Layer (<>) is new Label _Layer with private ;

The following operations are defined in the package:

procedure Add_Digital

( Under : not null access Layer_Location'Class;

Text : UTF8_String := "";

Location : Cairo_Tuple := ( 0.0 , 0.0 );

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " sans ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Mode : Text_Transformation := Rotated;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Skew : GDouble := 0.0 ;

Base : NumberBase := 10 ;

Precision : Integer := 0 ;

Absolute : Boolean := True;

Put_Plus : Boolean := False;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

);

function Add_Digital

( Under : not null access Layer_Location'Class;

Text : UTF8_String := "";

Location : Cairo_Tuple := ( 0.0 , 0.0 );

Face : Pango_Cairo_Font :=

Create_Toy

( Family => " sans ",

Slant => CAIRO_FONT_SLANT_NORMAL,

Weight => CAIRO_FONT_WEIGHT_NORMAL

);

Height : GDouble := 12.0 ;

Stretch : GDouble := 1.0 ;

Mode : Text_Transformation := Rotated;

Color : Gdk_Color := RGB ( 0.0 , 0.0 , 0.0 );

Angle : GDouble := 0.0 ;

Skew : GDouble := 0.0 ;

Base : NumberBase := 10 ;

Precision : Integer := 0 ;

Absolute : Boolean := True;

Put_Plus : Boolean := False;

Adjustment : access Gtk_Adjustment_Record'Class := null ;

Scaled : Boolean := False

) return not null access Digital_Layer;

These procedure and function create a layer representing a changing value as a text. The parameter Under specifies the layer location. Text is the text to draw. Location is the point where the text should be placed. Face is the font used for annotation texts. Height is the height of the annotation texts. Stretch is the factor by which the original text width is stretched. When Stretch is 1.0, the text's height to width relation is not changed. Mode is text transformation mode:

Move_Centered , Move_Inside , Move_Outside use the line which angle is specified by the parameter Angle to align the text as defined for these text transformation modes, the parameter Skew is ignored. Note that the text itself is not rotated;

, , use the line which angle is specified by the parameter to align the text as defined for these text transformation modes, the parameter is ignored. Note that the text itself is not rotated; Rotated uses Angle as the angle of the horizontal text axis, the parameter Skew is ignored;

uses as the angle of the horizontal text axis, the parameter is ignored; Skewed uses Angle as the angle of the horizontal text axis and does Skew as the angle between the horizontal text axis and the vertical text axis of the text origin.

Color is the text color. The parameter Scaled when true resizes the layer when the widget is resized:

The coordinates of the text location are multiplied by the widget's size (as returned by Get_Size), and the result is used as the center's coordinates relatively to the widget's center (as returned by Get_Center);

The text height is multiplied by the widget's size.

Base is the base used for the value representation: 2..16. Precision and Absolute specify the precision of the value in the digits specified by Base. When Absolute is true , Precision is absolute, e.g. Precision = -3 specifies that all digits of the value are valid up to third digit after the point. When Absolute is false , Precision is relative and specifies the total number of valid digits starting from the most significant digit. The parameter Put_Plus when true forces sign for positive values.

function Get_Absolute (Layer : Digital_Layer) return Boolean;

This function returns true if the absolute precision is used.

function Get_Adjustment (Layer : Digital_Layer)

return Gtk_Adjustment;

This function returns the adjustment object which state is indicated by the layer. The result is null when no adjustment is used.

function Get_Angle (Layer : Digital_Layer) return GDouble;

This function returns the text angle.

function Get_Base (Layer : Digital_Layer) return NumberBase;

This function returns the base used for conversion indicated value to text.

function Get_Color (Layer : Digital_Layer) return Gdk_Color;

This function returns the text color.

function Get_Face (Layer : Digital_Layer) return Pango_Cairo_Font;

This function returns a handle to the text font.

function Get_Height (Layer : Digital_Lay