ADA INDUSTRIAL CONTROL WIDGET LIBRARY
version 3.25

Dmitry A. Kazakov

(mailbox@dmitry-kazakov.de)

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:		64-	32-	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_25.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

Gtk_Gauge_Round_254	Gtk_Gauge_Round_270_Reversed
Gtk_Gauge_Round_270	Gtk_Gauge_Round_270_Inout
Gtk_Gauge_Round_270_Outer	Gtk_Gauge_Round_270_60s

1.2. Sectors and segments

Gtk_Gauge_Round_180	Gtk_Gauge_Elliptic_180
Gtk_Gauge_Round_90
Gtk_Gauge_Round_110

1.3. Meters

Gtk_Meter_Angular_90	Gtk_Meter_Round_94
Gtk_Meter_Elliptic_90	Gtk_Meter_Round_90
Gtk_Valve_Round_90

Gtk.Meter.Thermo

Gtk_Meter_Thermo_Symmetric

Gtk_Meter_Thermo_Dual

1.4. Flat and rectangular

Gtk_Gauge_Rectangular_70s	Gtk_Gauge_Flat_Vertical
Gtk_Gauge_Rectangular_70s_Slanted
Gtk_Gauge_Flat_Horizontal

1.5. Wall clocks

Gtk_Wall_Clock_Imperial	Gtk_Wall_Clock_Modern
Gtk_Wall_Clock_Classic

1.6. Oscilloscope

Gtk_Oscilloscope

1.7. LEDs

Gtk_Gauge_Led_Round

Gtk_Gauge_Led_Rectangular

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;
• 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;
• Segment 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;
• 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;
• First 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;
• Moved_Centered moves the text to (x, y) 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;
• Rotated moves the text's center to (x, y) rotating the text so that its vertical axis would be parallel to R;
• 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;
• 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;
• 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₁, k₁, α₁). The outer ellipse parameters are (r₂, k₂, α₂). The ticks start at the angle β₁ and end at the angle β₂. 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);
• The radiuses of Inner and Outer 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);
• The first tick position y 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);
• The radius of Ellipse 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;
• Center, 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;
• The annotation length (Length) 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);
• The radius of Ellipse 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;
• 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;
• 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);
• The radius of Ellipse 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;
• Rotated uses Angle as the angle of the horizontal text axis, the parameter Skew 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_Layer) return GDouble;

This function returns the text height.

function Get_Location (Layer : Digital_Layer) return Cairo_Tuple;

This function returns the text position.

function Get_Mode (Layer : Digital_Layer) return Text_Transformation;

This function returns the texts transformation mode.

function Get_Precision (Layer : Digital_Layer) return Integer;

This function returns the precision used for conversion indicated values to text. The precision is specified in valid digits of the current base as returned by Get_Base.

function Get_Put_Plus (Layer : Digital_Layer) return Boolean;

This function returns true if sign is used for positive values.

function Get_Stretch (Layer : Digital_Layer) return GDouble;

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

function Get_Skew (Layer : Digital_Layer) return GDouble;

This function returns the angle between the horizontal text axis and the vertical text axis of the text origin.

function Get_Text (Layer : Digital_Layer) return UTF8_String;

This function returns the text.

function Get_Value (Layer : Digital_Layer) return GDouble;

This function returns currently indicated value. The implementation is task-safe, callable on the context of a task different from the GTK loop task.

function Render (Layer : Digital_Layer; Value : GDouble)
   return UTF8_String;

This function is used to obtain the text indicated by the layer. The function can be overridden to change the layer's behavior.

procedure Set
          (  Layer     : in out Digital_Layer;
             Location  : Cairo_Tuple;
             Face      : Pango_Cairo_Font;
             Height    : GDouble;
             Stretch   : GDouble;
             Mode      : Text_Transformation;
             Color     : Gdk_Color;
             Angle     : GDouble;
             Skew      : GDouble;
             Base      : NumberBase;
             Precision : Integer;
             Absolute  : Boolean;
             Put_Plus  : Boolean
          );

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.

procedure Set_Value (Layer : in out Digital_Layer; Value : GDouble);

This procedure changes the indicated value. It is task-safe, it can be called on the context of a task different from the main loop task.

6.8. Disk needle

The package Gtk.Layered.Disk_Needle provides needles for valve position indicators. The needle is a rotating disk consisting of two halves or four sectors of interleaving colors. One color indicates open state, another does closed state:

The layer type is:

type Disk_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_Disk_Needle
          (  Under      : not null access Layer_Location'Class;
             Center     : Cairo_Tuple := (0.0, 0.0);
             Radius     : GDouble     := 0.5;
             From       : GDouble     := Pi;
             Length     : GDouble     := Pi;
             Sectors    : Boolean     := False;
             On_Color   : Gdk_Color   := Needle_On_Color;
             Off_Color  : Gdk_Color   := Needle_Off_Color;
             Adjustment : access Gtk_Adjustment_Record'Class := null;
             Scaled     : Boolean     := False
          );
function Add_Disk_Needle
         (  Under      : not null access Layer_Location'Class;
            Center     : Cairo_Tuple := (0.0, 0.0);
            Radius     : GDouble     := 0.5;
            From       : GDouble     := Pi;
            Length     : GDouble     := Pi;
            Sectors    : Boolean     := False;
            On_Color   : Gdk_Color   := Needle_On_Color;
            Off_Color  : Gdk_Color   := Needle_Off_Color;
            Adjustment : access Gtk_Adjustment_Record'Class := null;
            Scaled     : Boolean     := False
         )  return not null access Disk_Needle_Layer;

These procedure and function create a needle. The parameter Under specifies the layer location. The parameter Center is the location of needle's center. Radius is the needle's radius. The needle rotates from the angle From to the angle From + Length. The value 0.0 corresponds to From and here is a border line between the on and off colors is located. The value 1.0 corresponds to From + Length. Usually it is the next border line. Sectors when true creates a needle consisting of four sectors. Such needles usually rotate from 0 to Pi / 2 arc. When Sectors is false, the needle consists of two halves. Such needles usually rotate from 0 to Pi.  On_Color and Off_Color are the needle colors (red and green). 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:

• Center's X is multiplied by the widget's size and placed in the co-ordinate system centered in the widget's center as returned by Get_Center;
• Center's Y is multiplied by the widget's size and placed in the co-ordinate system centered in the widget's center as returned by Get_Center;
• Radius is multiplied by the widget's size as returned by Get_Size.

function Get_Center (Layer : Disk_Needle_Layer) return Cairo_Tuple;

This function returns the needle's center.

function Get_From (Layer : Disk_Needle_Layer) return GDouble;

This function returns the angle corresponding to the value 0.0.

function Get_Length (Layer : Disk_Needle_Layer) return GDouble;

This function returns the angular length of the needle positions.

function Get_Off_Color (Layer : Disk_Needle_Layer) return Gdk_Color;

This function returns the off-color.

function Get_On_Color (Layer : Disk_Needle_Layer) return Gdk_Color;

This function returns the on-color.

function Get_Radius (Layer : Disk_Needle_Layer) return GDouble;

This function returns the disk radius.

function Get_Sectors (Layer : Disk_Needle_Layer) return Boolean;

This function returns true if the needle has four sectors and false if it has two halves.

procedure Set
          (  Layer     : in out Disk_Needle_Layer;
             Center    : Cairo_Tuple;
             Radius    : GDouble;
             From      : GDouble;
             Length    : GDouble;
             Sectors   : Boolean;
             On_Color  : Gdk_Color;
             Off_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.

7. Shapes

Layers described in this chapter represent various shapes.

7.1. Arc

The package Gtk.Layered.Arc provides an elliptic arc.

type Arc_Layer (<>) is
   new Abstract_Layer
   and Scalable_Layer
   and Widened_Layer with private;

The following operations are defined in the package:

procedure Add_Arc
          (  Under    : not null access Layer_Location'Class;
             Ellipse  : Ellipse_Parameters := Unit_Circle;
             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_Bar
         (  Under    : not null access Layer_Location'Class;
            Ellipse  : Ellipse_Parameters := Unit_Circle;
            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 Arc_Layer;

These procedure and function create a layer drawing an elliptic arc. The parameter Under specifies the layer location. Ellipse is the parameters of the ellipse to which the arc belongs. From is the angle (between the x-axis and the ellipse point) of the first point of the arc. The parameter Length is the angular length of the arc. When the value of Length is negative the arc is drawn counterclockwise. Width is the width of the line. Color is line color. Line_Cap is the style of the line ends. 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);
• The radius of Ellipse 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 : Arc_Layer) return Ellipse_Parameters;

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

function Get_From (Layer : Arc_Layer) return GDouble;

This function returns the angle of the first point of the arc.

function Get_Length (Layer : Arc_Layer) return GDouble;

This function returns the angular length of the arc.

function Get_Line (Layer : Arc_Layer) return Line_Parameters;

This function returns the line parameters of the bar.

procedure Set
          (  Layer   : in out Arc_Layer;
             Ellipse : Ellipse_Parameters;
             From    : 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.

7.2. Cap

The package Gtk.Layered.Cap provides round caps having a 3-D look:

type Cap_Layer (<>) is new Abstract_Bordered_Layer with private;

The following operations are defined in the package:

procedure Add_Cap
          (  Under         : not null access Layer_Location'Class;
             Center        : Cairo_Tuple       := (0.0, 0.0);
             Radius        : GDouble           := 1.0;
             From          : Gdk_Color         := RGB (1.0, 1.0, 1.0);
             To            : Gdk_Color         := RGB (0.5, 0.5, 0.5);
             Border_Width  : GDouble           := 0.0;
             Border_Depth  : GDouble           := 1.0;
             Border_Color  : Border_Color_Type := Default_Color;
             Border_Shadow : Gtk_Shadow_Type   := Shadow_Out;
             Deepened      : Boolean           := False;
             Scaled        : Boolean           := False;
             Widened       : Boolean           := False
          );
function Add_Cap
         (  Under         : not null access Layer_Location'Class;
            Center        : Cairo_Tuple       := (0.0, 0.0);
            Radius        : GDouble           := 1.0;
            From          : Gdk_Color         := RGB (1.0, 1.0, 1.0);
            To            : Gdk_Color         := RGB (0.5, 0.5, 0.5);
            Border_Width  : GDouble           := 0.0;
            Border_Depth  : GDouble           := 1.0;
            Border_Color  : Border_Color_Type := Default_Color;
            Border_Shadow : Gtk_Shadow_Type   := Shadow_Out;
            Deepened      : Boolean           := False;
            Scaled        : Boolean           := False;
            Widened       : Boolean           := False
         )  return not null access Cap_Layer;

These procedure and function create a cap. The parameter Under specifies the layer location. Center is the cap's center. Radius is the cap's radius. From..To is the range of colors the cap has on its diagonal. The parameters Border_Width, Border_Depth, Border_Color, Border_Shadow are the parameters the cap's border. See the procedure Set for the meaning of these parameters. 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 : Cap_Layer) return Cairo_Tuple;

This function returns the cap's center.

function Get_From (Layer : Cap_Layer) return Gdk_Color;

This function returns the first color of the cap.

function Get_Radius (Layer : Cap_Layer) return GDouble;

This function returns the cap's radius.

function Get_To (Layer : Cap_Layer) return Gdk_Color;

This function returns the last color of the cap.

procedure Set
          (  Layer         : in out Cap_Layer;
             Center        : Cairo_Tuple;
             Radius        : GDouble;
             From          : Gdk_Color;
             To            : Gdk_Color;
             Border_Width  : GDouble;
             Border_Depth  : GDouble;
             Border_Color  : Border_Color_Type;
             Border_Shadow : Gtk_Shadow_Type
          );

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.

7.3. Line

The package Gtk.Layered.Line provides an elliptic arc.

type Line_Layer (<>) is
   new Abstract_Layer
   and Scalable_Layer
   and Widened_Layer with private;

The following operations are defined in the package:

procedure Add_Line
          (  Under    : not null access Layer_Location'Class;
             From     : Cairo_Tuple    := (0.0, 0.0);
             To       : Cairo_Tuple    := (0.0, 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_Line
         (  Under    : not null access Layer_Location'Class;
            From     : Cairo_Tuple    := (0.0, 0.0);
            To       : Cairo_Tuple    := (0.0, 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 Line_Layer;

These procedure and function create a layer drawing a straight line. The parameter Under specifies the layer location. From and To are the line starting and end points. Width is the width of the line. Color is line color. Line_Cap is the style of the line ends. The parameter Scaled when true resizes the layer resizing when the widget is resized. The coordinates of the line 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. 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 line:

procedure Add_Line
          (  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 (0.0, 0.0, 0.0);
             Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;
             Scaled   : Boolean        := False;
             Widened  : Boolean        := False
          );
function Add_Line
         (  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 (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 Line_Layer;

Here instead of the parameter To the end point is specified by Angle and Length.

function Get_Angle (Layer : Line_Layer) return GDouble;

This function returns the angle of the line.

function Get_From (Layer : Line_Layer) return Cairo_Tuple;

This function returns the first point of the line.

function Get_Length (Layer : Line_Layer) return GDouble;

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

function Get_Line (Layer : Line_Layer) return Line_Parameters;

This function returns the line parameters of the bar.

function Get_To (Layer : Line_Layer) return Cairo_Tuple;

This function returns the last point of the line.

procedure Set
          (  Layer : in out Line_Layer;
             From  : Cairo_Tuple;
             To    : Cairo_Tuple;
             Line  : Line_Parameters
          );
procedure Set
          (  Layer  : in out Line_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.

7.4. Text (label)

The package Gtk.Layered.Label provides a layer drawing a text:

type Label_Layer (<>) is
   new Abstract_Layer and Scalable_Layer with private;

The following operations are defined in the package:

procedure Add_Label
          (  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 := Moved_Centered;
             Color    : Gdk_Color           := RGB (0.0, 0.0, 0.0);
             Angle    : GDouble             := 3.0 * Pi / 2.0;
             Skew     : GDouble             := 0.0;
             Markup   : Boolean             := False;
             Scaled   : Boolean             := False
          );
function Add_Label
         (  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 := Moved_Centered;
            Color    : Gdk_Color           := RGB (0.0, 0.0, 0.0);
            Angle    : GDouble             := 3.0 * Pi / 2.0;
            Skew     : GDouble             := 0.0;
            Markup   : Boolean             := False;
            Scaled   : Boolean             := False
         )  return not null access Label_Layer;

These procedure and function create a layer drawing a text. The parameter Under specifies the layer location. Text is the text to draw. When the text uses pango markup the parameter Markup is true. 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;
• Rotated uses Angle as the angle of the horizontal text axis, the parameter Skew 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.

function Get_Angle (Layer : Label_Layer) return GDouble;

This function returns the text angle.

function Get_Color (Layer : Label_Layer) return Gdk_Color;

This function returns the text color.

function Get_Face (Layer : Label_Layer) return Pango_Cairo_Font;

This function returns a handle to the text font.

function Get_Height (Layer : Label_Layer) return GDouble;

This function returns the text height.

function Get_Location (Layer : Label_Layer) return Cairo_Tuple;

This function returns the text position.

function Get_Location (Layer : Label_Layer) return Cairo_Tuple;

This function returns the text position.

function Get_Markup (Layer : Label_Layer) return Boolean;

This function returns true if the label text uses pango markup.

function Get_Stretch (Layer : Label_Layer) return GDouble;

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

function Get_Skew (Layer : Label_Layer) return GDouble;

This function returns the angle between the horizontal text axis and the vertical text axis of the text origin.

function Get_Text (Layer : Label_Layer) return UTF8_String;

This function returns the text.

procedure Set
          (  Layer    : in out Label_Layer;
             Location : Cairo_Tuple;
             Face     : Pango_Cairo_Font;
             Height   : GDouble;
             Stretch  : GDouble;
             Mode     : Text_Transformation;
             Color    : Gdk_Color;
             Angle    : GDouble;
             Skew     : 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.

procedure Set_Text
          (  Layer  : in out Label_Layer;
             Text   : UTF8_String;
             Markup : Boolean := False
          );

This procedure changes the text. It is task-safe, it can be called on the context of a task different from the main loop task.

7.5. Rectangle

The package Gtk.Layered.Rectangle provides a layer drawing a colored rectangle:

type Rectangle_Layer(<>) is
   new Abstract_Layer
   and Scalable_Layer
   and Widened_Layer with private;

The following operations are defined in the package:

procedure Add_Rectangle
          (  Under      : not null access Layer_Location'Class;
             Box        : Cairo_Box;
             Color      : Gdk_Color    := RGB (0.0, 0.0, 0.0);
             Line_Width : GDouble      := 0.0;
             Opacity    : Fill_Opacity := 1.0;
             Scaled     : Boolean      := False;
             Widened    : Boolean      := False
          );
function Add_Rectangle
         (  Under      : not null access Layer_Location'Class;
            Box        : Cairo_Box;
            Color      : Gdk_Color    := RGB (0.0, 0.0, 0.0);
            Line_Width : GDouble      := 0.0;
            Opacity    : Fill_Opacity := 1.0;
            Scaled     : Boolean      := False;
            Widened    : Boolean      := False
         )  return not null access Rectangle_Layer;

These procedure and function create a layer drawing a rectangle. The parameter Under specifies the layer location. Box is the rectangle box. Color is the rectangle color. Line_Width is the width of the line drawn around the rectangle's box. When 0, no line is drawn. Opacity is the opacity Color when used to fill the rectangle. When Opacity is 1 the rectangle is opaque. When 0, the rectangle is not filled. The parameter Scaled when true resizes the layer when the widget is resized:

• The horizontal rectangle coordinates are multiplied by the widget width then horizontal coordinate of the widget's center (as returned by Get_Center) is added;
• The horizontal rectangle coordinates are multiplied by the widget width then horizontal coordinate of the widget's center is added.

When Widened is true the line width is the value of Width multiplied by the widget's size.

function Get_Box (Layer : Rectangle_Layer) return Cairo_Box;

This function returns the rectangle's box.

function Get_Color (Layer : Rectangle_Layer) return Gdk_Color;

This function returns the rectangle's color.

function Get_Line_Width (Layer : Rectangle_Layer) return GDouble;

This function returns the rectangle's line width.

function Get_Opacity (Layer : Rectangle_Layer) return Fill_Opacity;

This function returns the filling opacity.

procedure Set
          (  Layer      : in out Rectangle_Layer;
             Box        : Cairo_Box;
             Color      : Gdk_Color;
             Line_Width : GDouble;
             Opacity    : Fill_Opacity
          );

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.

7.6. SVG image

The package Gtk.Layered.SVG provides a layer drawing an SVG image:

type SVG_Layer(<>) is
   new Abstract_Layer
   and Scalable_Layer with private;

The following operations are defined in the package:

procedure Add_SVG
          (  Under  : not null access Layer_Location'Class;
             Image  : RSVG_Handle;
             Center : Cairo_Tuple := (0.0, 0.0);
             Scaled : Boolean     := False
          );
function Add_SVG
         (  Under  : not null access Layer_Location'Class;
            Image  : RSVG_Handle;
            Center : Cairo_Tuple := (0.0, 0.0);
            Scaled : Boolean     := False
         )  return not null access SVG_Layer;

These procedure and function create a layer drawing an image. The parameter Under specifies the layer location. Image is a handle to the image to draw. Center is the location where the image's center is drawn. The parameter Scaled when true resizes the layer when the widget is resized:

• The SVG's width and height are extended to fill the box without clipping..

function Get_Center (Layer : SVG_Layer) return Cairo_Tuple;

This function returns the image center.

function Get_SVG (Layer : SVG_Layer) return RSVG_Handle;

This function returns a handle to the SVG image. When the result is not null the client is responsible to Unref it.

procedure Set
          (  Layer  : in out SVG_Layer;
             Center : Cairo_Tuple
          );

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

8. Special layers

8.1. Rectangular clip region

The package Gtk.Layered.Rectangular_Clip_Region provides means to clip drawing of other layers to a rectangular area. The package declares two types:

type Rectangular_Clip_Region_On_Layer (<>) is
   new Abstract_Layer and Scalable_Layer with private;

This layer add a rectangular area to the clipping region of the upper layers. This action remains in effect until the layer:

type Rectangular_Clip_Region_Off_Layer (<>) is
   new Abstract_Layer with private;

The package provides the following operations:

procedure Add_Rectangular_Clip_Region
          (  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;
             Scaled         : Boolean     := False
          );
function Add_Rectangular_Clip_Region
         (  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;
            Scaled         : Boolean     := False
         )  return not null access Rectangular_Clip_Region_On_Layer;

These procedure and function create two layers a clipping layer Rectangular_Clip_Region_On_Layer and restoring layer Rectangular_Clip_Region_Off_Layer above it. The parameter Under specifies the layers location. Height is the height of the clipping rectangle. Width is the rectangle's width. Center is the rectangle's center. Rotation_Angle is the angle between the x-axis of the cairo cooredinate system and the rectangle's bottom. Corner_Radius is the radius of the circles rounding the rectangle's corners. The parameter Scaled when true resizes the layer when the widget is resized:

• The coordinates of the rectangle's center are multiplied by the widget's size as returned (by Get_Size), and added to the widget's center as returned (by Get_Center);
• The widget's width and height are multiplied by the widget's size.

The location of the Rectangular_Clip_Region_Off_Layer layer corresponding to the result returned by this function can be obtaining by calling Above on the result.

function Get_Center (Layer : Rectangular_Clip_Region_On_Layer)
   return Cairo_Tuple;

This function returns the rectangle's center.

function Get_Corner_Radius (Layer : Rectangular_Clip_Region_On_Layer)
   return GDouble;

This function returns the corner's radius.

function Get_Height (Layer : Rectangular_Clip_Region_On_Layer)
   return GDouble;

This function returns the rectangle's height.

function Get_Rotation_Angle (Layer : Rectangular_Clip_Region_On_Layer)
   return GDouble;

This function returns the rectangle's angle.

function Get_Width (Layer : Rectangular_Clip_Region_On_Layer)
   return GDouble;

This function returns the rectangle's width.

procedure Set
          (  Layer  : in out Rectangular_Clip_Region_On_Layer;
             Height : GDouble;
             Width  : GDouble;
             Center : Cairo_Tuple;
             Rotation_Angle : GDouble;
             Corner_Radius  : 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.

8.2. Caching layer

Drawing the gauge at full each time its needle moves might be unnecessary expensive. The caching layer provides a way to eliminate unnecessary drawing. The layer can be put between the lower layers, like the background, scale, annotation, which do not change and the needle which should be redrawn each time its value is changed. The layer caches the state of the underlying layers making a snapshot of them. When the widget is redrawn and the layers do not report them updated (see Is_Updated), they are not drawn again, instead the snapshot is taken from the caching layer. The upper layers are drawn upon the snapshot.

The package Gtk.Layered.Cache provides an implementation of caching layer:

type Cache_Layer (<>) is new Abstract_Layer with private;

The package provides the following operations:

procedure Add_Cache (Under : not null access Layer_Location'Class);
function Add_Cache (Under : not null access Layer_Location'Class)
   return not null access Cache_Layer;

These procedure and function create a caching layer. The parameter Under specifies the layers location. Note that the cache layer should not be placed between Rectangular_Clip_Region_On_Layer and Rectangular_Clip_Region_Off_Layer, because clipping cannot be cached. So in effect it will be disabled when cache is used.

9. Waveforms

Waveform represents a function, usually of time, in the form of a running curve. A waveform consists of multiple points (t, v) connected by a line. The points are stored externally from the waveform and held by an object implementing the Waveform_Data_Source interface declared in the package Gtk.Layered.Waveform. The following figure illustrates interaction of a waveform layer with its data source:

The data source usually is designed to maintain a highly frequent massive input. It sends notifications to the waveform object upon source changes, but that does not cause any immediate visual effect. Usually it is a refresh engine which causes the layer to be actually redrawn with a frequency much lower than the source frequency. E.g. the waveform may render 10kHz source data rendered at 50Hz by the engine.

Two adjustment objects are used to amplify the source values at the y-axis and sweep them along the x-axis. Though it is possible to use the standard objects, the package Gtk.Layered.Waveform defines specialized interfaces for the amplifier and sweeper. The amplifier interface Waveform_Amplifier supports the auto-scaling mode to making the waveform fit the vertical range of the box. The sweeper interface Waveform_Sweeper supports freezing/running mode and setting the adjustment using time stamps directly.

Quick reference:

• Data sources and scanners
• Waveform amplifiers
• Waveform sweepers
• Waveform layer
• Graph paper
• Graph paper annotation

The waveform layer is used by a ready-to-use multichannel oscilloscope widget.

9.1. Data sources and scanners

The package Gtk.Layered.Waveform declares the types of the components (t, v) used in the data source interface:

type X_Axis is new GDouble;
type Y_Axis is new GDouble;

These types are compatible with the types used in the GTK+ adjustment objects.

Massive data flows and/or slow data origin interfaces, implementation considerations. When implementing a data source and scanner to interface by some slow external store, e.g. a data base, file, network connection etc holding a massive amount of data, consider the following schema. The data source is a front end to the corresponding store. The data source has no cache, rather the scanners have it. Scanning the source would likely be too slow to complete in one piece. Since scanning is done upon rendering, that would block the waveform and the whole UI. Instead of that the scanner completes signaling End_Error after reading a few items of data into its cache. In the background, the scanner keeps on reading the data up to the requested position and probably ahead. As the cache gets filled the scanner periodically notifies the connected waveforms that the data source is changed by calling Changed. The waveforms rescan the data source showing more and more data as they get cached.

9.1.1. Data source interface

type Waveform_Data_Source is limited interface;

The following primitive operations are defined for a data source:

procedure Connected
          (  Source : in out Waveform_Data_Source;
             Layer  : in out Waveform_Layer'Class
          )  is abstract;

This procedure is called to notify a data source that a waveform was connected to it. A data source can serve many waveforms.

function Create
         (  Source : not null access Waveform_Data_Source
         )  return Waveform_Data_Scanner'Class is abstract;

This function is a factory of the scanner suitable for the source. When a waveform connects to a source it calls this function to create a scanner object, which is then used to access the data from the source.

procedure Disconnected
          (  Source : in out Waveform_Data_Source;
             Layer  : in out Waveform_Layer'Class
          )  is abstract;

This procedure is called to notify a data source that a waveform was disconnected from it.

9.1.2. Data scanner interface

The package Gtk.Layered.Waveform declares the data scanner interface:

type Waveform_Data_Scanner is interface;

The following primitive operations are defined for a data scanner:

procedure Backward
          (  Source : in out Waveform_Data_Scanner;
             T      : in out X_Axis;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          )  is abstract;

These procedures scan the source backwards. They decrease T to the nearest available point in the data source of the scanner. T is then set to the position of the point, V is to the point's value. Got_It is returned false or else End_Error is propagated when the data source beginning is reached.

procedure First
          (  Source : in out Waveform_Data_Scanner;
             T      : out X_Axis;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          )  is abstract;

This procedure returns the first point in the data source. Got_It is returned false or else End_Error is propagated when the data source is empty.

procedure Forward
          (  Source : in out Waveform_Data_Scanner;
             T      : in out X_Axis;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          )  is abstract;

These procedures scan the source forward. They increase T to the nearest available point in the data source of the scanner. T is then set to the position of the point, V is to the point's value. Got_It is returned false or else End_Error is propagated when the data source beginning is reached.

function Is_In
         (  Source : Source_Scanner;
            T      : X_Axis
         )  return Boolean is abstract;

This function returns true if T is within the bounds of the data source.

procedure Last
          (  Source : in out Waveform_Data_Scanner;
             T      : out X_Axis;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          )  is abstract;

This procedure returns the last point in the data source. Got_It is returned false or else End_Error is propagated when the data source is empty.

The class-wide operation defined on the scanner:

procedure Get
          (  Source : in out Waveform_Data_Scanner'Class;
             T      : X_Axis;
             Mode   : Interpolation_Mode;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          );

This procedure searches the source connected to the scanner Source for the value V corresponding to the parameter T. The interpolation mode is specified by the parameter Mode. The procedure does not extrapolate the data source values, Got_It is returned false or else End_Error is propagated when there is no defined values around T.

9.1.3. Data source feed interface

The package Gtk.Layered.Waveform declares the data source feed interface:

type Waveform_Data_Feed is limited interface
   and Waveform_Data_Source;

The following primitive operations are defined:

procedure Erase (Source : in out Waveform_Data_Feed) is abstract;

This procedure erases the contents of Source.

procedure Put
          (  Source : in out Waveform_Data_Feed;
             T      : X_Axis;
             V      : Y_Axis
          )  is abstract;

This procedure is used to put a new point (T, V) into the buffer Source. When the buffer contains a value with same T, the value in the buffer is replaced. When the buffer is full, the value with the least T is dropped, unless the new value has a lesser T, in which case the operation is void.

9.1.4. Ring buffer implementation

The package Gtk_Waveform_Ring_Data_Buffer provides an implementation of waveform data source interface:

type Gtk_Waveform_Ring_Data_Buffer_Record (Size : Positive) is
   new GObject_Record
   and Waveform_Data_Feed with private;
type Gtk_Waveform_Ring_Data_Buffer is
   access all Gtk_Waveform_Ring_Data_Buffer_Record'Class;

The discriminant Size specifies the maximal number of points in the buffer. The buffer can be written from one task and scanned from several other tasks without interlocking. When more than two tasks write the buffer it must be protected from concurrent access. The implementation of Put must be called from only one task at a time. Gtk_Waveform_Ring_Data_Buffer_Record is a proper GTK+ object, subject of reference counting. It is created using typical means:

procedure Gtk_New
          (  Source : out Gtk_Waveform_Ring_Data_Buffer;
             Size   : Positive
          );

This procedure creates a new buffer object Source.

procedure Initialize
          (  Source : not null access
                      Gtk_Waveform_Ring_Data_Buffer_Record'Class
          );

When a custom type is derived from Gtk_Waveform_Ring_Data_Buffer_Record it must call this procedure from its implementation of Initialize.

type Source_Scanner is new Waveform_Data_Scanner with private;

This type is an implementation of Waveform_Data_Scanner returned by Create of Ring_Data_Buffer.

9.2. Waveform amplifiers

An amplifier is used to adjust the vertical axis of the waveform. Several waveforms may share one amplifier in order to have the same vertical axis scale.

9.2.1. Amplifier interface

The package Gtk.Layered.Waveform declares the data amplifier adjustment interface:

type Waveform_Amplifier is interface;

The following primitive operations are defined for an amplifier:

procedure Add_Range
          (  Amplifier    : not null access Waveform_Amplifier;
             Layer        : Waveform_Layer'Class;
             From,  To    : X_Axis;
             Lower, Upper : Y_Axis
          )  is abstract;

The procedure is called upon sampling the waveform source. The amplifier may change its parameters, for example in order to make the whole range visible on the y-axis. The parameters From..To specify the range of values on the horizontal axis. The parameters Lower..Upper specify the range of values on the vertical axis. Note that the amplifier can be shared between several layers sharing same y-axis. Therefore an implementation should prepare itself to multiple calls to this procedure.

9.2.2. Amplifier implementation

The package Gtk.Layered.Waveform.Amplifier provides an implementation of the waveform amplifier interface. The implementation supports automatic scaling. The object is a descendant of the standard adjustment object:

type Gtk_Waveform_Amplifier_Record is
   new Gtk_Adjustment_Record
   and Waveform_Amplifier with private;
type Gtk_Waveform_Amplifier is
   access all Gtk_Waveform_Amplifier_Record'Class;

The following primitive operations are defined for the amplifier:

function Get_Auto_Scaling
         (  Amplifier : not null access constant
                        Gtk_Waveform_Amplifier_Record
         )  return Boolean;

This function returns the current scaling mode as set by the procedure Set_Auto_Scaling.

function Get_Raster_Scaling
         (  Amplifier : not null access constant
                        Gtk_Waveform_Amplifier_Record
         )  return Boolean;

This function returns the current raster scaling mode as set by the procedure Set_Raster_Scaling.

function Get_Scaling
         (  Amplifier : not null access constant
                        Gtk_Waveform_Amplifier_Record
         )  return Waveform_Scaling;

This function returns the scaling factor as set by the procedure Set_Scaling.

function Get_Tick_Length
         (  Amplifier : not null access constant
                        Gtk_Waveform_Amplifier_Record
         )  return Positive;

This function returns the value set by Set_Tick_Length.

procedure Gtk_New (Amplifier : out Gtk_Waveform_Amplifier);

This procedure creates a new amplifier object.

procedure Initialize
          (  Amplifier : not null access
                         Gtk_Waveform_Amplifier_Record'Class
          );

This procedure must be called from the Initialize procedure of a type derived from this one.

procedure Set_Auto_Scaling
          (  Amplifier : not null access
                         Gtk_Waveform_Amplifier_Record;
             Auto      : Boolean
          );

When Auto is true the amplifier automatically adjusts its upper and lower bounds to fit the vertical range of its waveforms. When Auto is false the amplifier retains its parameters. Initially auto-scaling is active.

procedure Set_Raster_Scaling
          (  Amplifier : not null access
                         Gtk_Waveform_Amplifier_Record;
             Raster    : Boolean
          );

This procedure sets raster fitting mode. When auto-scaling mode is active (see Set_Auto_Scaling), the Amplifier adjusts its upper and lower bounds so that they values would have "good-looking" decimal representations.

procedure Set_Scaling
          (  Amplifier : not null access
                         Gtk_Waveform_Amplifier_Record;
             Scaling   : Waveform_Scaling
          );

This function sets the amount of in advance scaling when the waveform is in auto-scaling mode. The following figure illustrates the behavior when the waveform leaves the range and must be scaled to a larger range:

The new range is calculated as shown above. Larger values of the Scaling parameter prevent too frequent change of the range when the curve is ascending. Similarly when the curve is descending staying within a narrower range defined by Scaling as shown on the figure below:

it scaled down to that range. The default value is 0.2.

procedure Set_Tick_Length
          (  Amplifier : not null access
                         Gtk_Waveform_Amplifier_Record;
             Length    : Positive
          );

This procedure sets the approximate length of the major tick when the scaling is fitted at the raster. The raster is selected so that the waveform box would contain approximately

the box's height

Length

ticks corresponding to "good" values. The default value is 50.

The following additional signals are emitted by the object:

• autoscaling-changed is emitted when automatic scaling is turned on or off (see Set_Auto_Scaling);
• raster-mode-changed is emitted when raster scaling mode is turned on or off (see Set_Raster_Scaling).

9.3. Waveform sweepers

A sweeper is used to adjust the horizontal axis of the waveform. Several waveforms may share one sweeper.

9.3.1. Sweeper interface

The package Gtk.Layered.Waveform declares the sweeper interface:

type Waveform_Sweeper is interface;

The following primitive operations are defined for a sweeper:

procedure Set_Current_Time
          (  Sweeper : not null access Waveform_Sweeper;
             Stamp   : Time;
             Active  : Boolean := False
          )  is abstract;

This procedure is called before drawing the waveform layer. The implementation can change the adjustment to sweep the waveform. Note that it can be called multiple times when the sweeper object is shared by several waveforms. Usually Stamp changes the adjustment value so that the right margin of the adjustment page would correspond to Stamp. When Active is passed true the active count is increased and decreased again before return from Set_Current_Time. Is_Active then returns true if the count is greater than zero.

function Is_Active
         (  Sweeper : not null access Waveform_Sweeper
         )  return Boolean is abstract;

Layers during preparation to drawing may call Set_Current_Time with Active set true. When they receive the changed signal from the sweeper they use
this function to decide not to a new queue drawing request (when Is_Active returns true).

9.3.2. Time operations

The package Gtk.Layered.Waveform provides operations to convert time to the adjustment values.

function Get_Epoch return Ada.Calendar.Time;
function Get_Epoch return Time;

These functions return the time of the epoch used in conversions. The value 0 corresponds to the time returned by this function. The epoch is chosen to be at the beginning of a day.

function To_Double (Value : Time) return GDouble;
function To_Double (Value : Ada.Calendar.Time) return GDouble;

These functions return the time corresponding to Value time. The result is the number of seconds between Value and Get_Epoch. Constraint_Error is propagated when conversion is impossible.

function To_Time (Value : GDouble) return Time;
function To_Time (Value : GDouble) return Ada.Calendar.Time;

These functions return the value corresponding to Value. The time is calculated as Get_Epoch + Value interpreted as seconds. Constraint_Error is propagated when conversion is impossible.

9.3.3. Sweeper implementation

The package Gtk.Layered.Waveform.Sweeper provides an implementation of the waveform sweeper interface. This is a specialized adjustment object used to sweep one or more waveforms. When not frozen the sweeper changes itself before the waveforms are drawn so that the right margin of all boxes of the waveforms would correspond to the time of drawing minus a fixed offset. The offset can be changed. When the sweeper is frozen the right margin does change but the offset is incremented to compensate time:

type Gtk_Waveform_Sweeper_Record is
   new Gtk_Adjustment_Record
   and Waveform_Sweeper with private;
type Gtk_Waveform_Sweeper is
   access all Gtk_Waveform_Sweeper_Record'Class;

The following primitive operations are defined for the amplifier:

function Get_From
         (  Sweeper : not null access Gtk_Waveform_Sweeper_Record
         )  return [Ada.Calendar.]Time;

This function returns the time corresponding to the lower value of the sweeper, i.e. the first time available. The result is either Ada.Real_Time.Time or Ada.Calendar.Time.

function Get_Frozen
         (  Sweeper : not null access constant Gtk_Waveform_Sweeper_Record
         )  return Boolean;

This function returns true if the sweeper is frozen.

function Get_Offset
         (  Sweeper : not null access constant Gtk_Waveform_Sweeper_Record
         )  return Duration;

This function returns the duration between the right margin of the Sweeper's page and the most recent time as notified by Set_Current_Time. When the sweeper is frozen offset is incremented with the time. Otherwise the offset is constant.

function Get_Page_Span
         (  Sweeper : not null access Gtk_Waveform_Sweeper_Record
         )  return Duration;

This function returns the page size in seconds.

function Get_Time
         (  Sweeper : not null access Gtk_Waveform_Sweeper_Record
         )  return [Ada.Calendar.]Time;

The time corresponding to the end (right margin) of the page. Note that Get_Value returns a value (GDouble) corresponding to the beginning of the page. The result is either Ada.Real_Time.Time or Ada.Calendar.Time.

function Get_To
         (  Sweeper : not null access Gtk_Waveform_Sweeper_Record
         )  return [Ada.Calendar.]Time;

This function returns the time corresponding to the upper value of the sweeper, i.e. the last time available. The result is either Ada.Real_Time.Time or Ada.Calendar.Time.

procedure Gtk_New (Sweeper : out Gtk_Waveform_Sweeper);

This procedure creates a new sweeper object.

procedure Initialize
          (  Sweeper : not null access Gtk_Waveform_Sweeper_Record'Class
          );

This procedure must be called from the derived type's Initialize, if any.

procedure Set
          (  Sweeper : not null access Gtk_Waveform_Sweeper_Record;
             Date           : [Ada.Calendar.]Time;
             From           : [Ada.Calendar.]Time;
             To             : [Ada.Calendar.]Time;
             Step_Increment : Duration;
             Page_Increment : Duration;
             Page_Span      : Duration
          );

This procedure changes all settings controlling the sweeper's page. The time arguments can be either of Ada.Real_Time.Time or of Ada.Calendar.Time type.

procedure Set_Frozen
          (  Sweeper : not null access Gtk_Waveform_Sweeper_Record;
             Frozen  : Boolean
          );

This procedure sets Sweeper's freezing mode. When frozen the sweeper maintains its page setting constant. When Set_Current_Time is called the offset is increased to keep the page margins. When the sweeper is not frozen, Set_Current_Time slides the sweeper's page and keeps the offset is unchanged.

procedure Set_Page_Span
          (  Sweeper   : not null access Gtk_Waveform_Sweeper_Record;
             Page_Span : Duration
          );

This procedure changes page span of the sweeper.

procedure Set_Time
          (  Sweeper : not null access Gtk_Waveform_Sweeper_Record;
             Stamp   : [Ada.Calendar.]Time
          );

This procedure changes the right margin of Sweeper to Stamp. Stamp is either Ada.Real_Time.Time or Ada.Calendar.Time.

The following additional signals are emitted by the object:

• freezing-changed is emitted when the freezing state is changed;
• offset-changed is emitted when the offset is changed.

9.4. Waveform layer

The package Gtk.Layered.Waveform declares the type of the waveform layer:

type Waveform_Layer (<>) is
   new Abstract_Layer
   and Scalable_Layer
   and Widened_Layer with private;

The following operations are defined on the waveform layers:

procedure Add_Waveform
          (  Under     : not null access Layer_Location'Class;
             Box       : Cairo_Box;
             Width     : GDouble            := 1.0;
             Color     : Gdk_Color          := RGB (1.0, 0.0, 0.0);
             Line_Cap  : Cairo_Line_Cap     := CAIRO_LINE_CAP_BUTT;
             Sweeper   : access Gtk_Adjustment_Record'Class := null;
             Amplifier : access Gtk_Adjustment_Record'Class := null;
             Mode      : Interpolation_Mode := Linear;
             Left      : Boolean            := False;
             Right     : Boolean            := False;
             Opacity   : Fill_Opacity       := 1.0;
             Scaled    : Boolean            := False;
             Widened   : Boolean            := False
          );
function Add_Waveform
         (  Under     : not null access Layer_Location'Class;
            Box       : Cairo_Box;
            Width     : GDouble            := 1.0;
            Color     : Gdk_Color          := RGB (1.0, 0.0, 0.0);
            Line_Cap  : Cairo_Line_Cap     := CAIRO_LINE_CAP_BUTT;
            Sweeper   : access Gtk_Adjustment_Record'Class := null;
            Amplifier : access Gtk_Adjustment_Record'Class := null;
            Mode      : Interpolation_Mode := Linear;
            Left      : Boolean            := False;
            Right     : Boolean            := False;
            Opacity   : Fill_Opacity       := 1.0;
            Scaled    : Boolean            := False;
            Widened   : Boolean            := False
         )  return not null access Waveform_Layer;

These procedure and function create a waveform layer. The parameter Under specifies the layer location. The parameter Box is the box bounding the waveform. Width specifies the width of the waveform line. Color is the line color. The type of the line ends is determined by the parameter Line_Cap. The parameter Opacity determines the transparency of the filling under the waveform curve. The parameter Sweeper is the object controlling how the horizontal axis of the waveform is scaled. It is analogous to the sweeper section of an oscilloscope. Several waveforms may share one sweeper object. When this parameter is null the waveform must be swept manually using the procedure Sweep. The parameter Amplifier is the object controlling the vertical axis. When this parameter is null the waveform must be scaled using explicit calls to the procedure Amplify. The parameter Mode specified the interpolation mode as defined by the type Interpolation_Mode. The parameters Left and Right when set true allow extrapolation to the left and to the right correspondingly. The extrapolation uses the first or last sampled value accordingly. When the parameter Scaled is true the layer is scaled to fit the parent widget. The scaling s performed as follows:

• The x-coordinates of the box are multiplied by the widget's horizontal size and then added to the x-coordinate of the widget's center as returned by Get_Center;
• The y-coordinates of the box are multiplied by the widget's vertical size and then added to the y-coordinate of the widget's center.

Widened when true indicates that the line width is increased proportionally to the widget's size. Constraint_Error is propagated when some of the parameters are illegal.

procedure Amplify
          (  Layer : in out Waveform_Layer;
             Lower : Y_Axis;
             Upper : Y_Axis
          );

This procedure explicitly sets the value Upper to correspond to the top of the waveform box. The value Lower is set to correspond to the bottom of the box. page. Constraint_Error is propagated when Lower..Upper is an illegal range. Normally these values are set implicitly using an amplifier object.

procedure Changed
          (  Layer : in out Waveform_Layer;
             From  : X_Axis;
             To    : X_Axis
          );

This procedure is called by an implementation of the Waveform_Data_Source interface in order to notify that a part of source was changed. This procedure is not intended to perform actual rendering, rather to remember which parts need to be redrawn when the time comes.

function Get (Layer : Waveform_Layer; X : GDouble) return Y_Axis;

This function returns the waveform value corresponding to the coordinate X, relative to the widget. End_Error is propagated when there is no defined values around X. See also Get_Point, which returns values on both axes.

procedure Get
          (  Layer   : Waveform_Layer;
             X       : GDouble;
             Y       : out Y_Axis;
             Got_It  : out Boolean
          );

This variant does not use End_Error exception.

function Get_Amplifier (Layer : Waveform_Layer)
   return Gtk_Adjustment;

This function returns the amplifier object of Layer or null.

function Get_Box (Layer : Waveform_Layer) return Cairo_Box;

This function returns the Layer's box.

function Get_Interpolation_Mode (Layer : Waveform_Layer)
   return Interpolation_Mode;

This function returns the waveform's interpolation mode. The interpolation modes are defined by the type Interpolation_Mode declared in the package Gtk.Layered.

function Get_Left_Extrapolation_Mode (Layer : Waveform_Layer)
   return Boolean;

This function returns true if the waveform extrapolates data left of the first sampled value.

function Get_Line (Layer : Waveform_Layer) return Line_Parameters;

This function returns the line parameters of the waveform.

function Get_Method (Layer : Waveform_Layer)
   return Waveform_Drawing_Method;

This function returns the current rendering method used for the waveform.

function Get_Opacity (Layer : Waveform_Layer) return Fill_Opacity;

This function returns the opacity of the filled part under the waveform.

procedure Get_Point
          (  Layer  : Waveform_Layer;
             X      : GDouble;
             T      : out X_Axis;
             V      : out Y_Axis;
           [ Got_It : out Boolean ]
          );

This procedure returns the waveform point (T, V) corresponding to the coordinate X, relative to the widget. Got_It is returned false or else End_Error is propagated when there is no defined values around X.

function Get_Preferred_Method (Layer : Waveform_Layer)
   return Waveform_Drawing_Method;

This function returns the preferred rendering method used for the waveform.

function Get_Right_Extrapolation_Mode (Layer : Waveform_Layer)
   return Boolean;

This function returns true if the waveform extrapolates data right of the first sampled value.

function Get_Source
         (  Layer : Waveform_Layer
         )  return access Waveform_Data_Source'Class;

This function returns the waveform's data source or null.

function Get_Sweeper (Layer : Waveform_Layer) return Gtk_Adjustment;

This function returns the sweeper object of Layer or null.

function Get_T (Layer : Waveform_Layer; X : GDouble) return X_Axis;
function Get_V (Layer : Waveform_Layer; Y : GDouble) return Y_Axis;

These functions convert the Layer's widget coordinates to the corresponding data source values. The widget's coordinates are relative, the top left corner of the widget has the coordinates (0, 0).

function Get_T1 (Layer : Waveform_Layer) return X_Axis;
function Get_T2 (Layer : Waveform_Layer) return X_Axis;
function Get_V1 (Layer : Waveform_Layer) return Y_Axis;
function Get_V2 (Layer : Waveform_Layer) return Y_Axis;

These functions return the values corresponding margins the margins of the waveform box. E.g. Get_T1 is same as Get_T with X set at the left margin of the box. Note that the value returned by Get_V1 is normally greater than one of Get_V2.

function Get_X (Layer : Waveform_Layer; T : X_Axis) return GDouble;
function Get_Y (Layer : Waveform_Layer; V : Y_Axis) return GDouble;

These functions convert the data source values to the Layer's widget coordinates. The widget's coordinates are relative, the top left corner of the widget has the coordinates (0, 0).

procedure Set
          (  Layer   : in out Waveform_Layer;
             Box     : Cairo_Box;
             Line    : Line_Parameters;
             Mode    : Interpolation_Mode;
             Opacity : Fill_Opacity
          );

This procedure changes parameters of a waveform layer.

procedure Set_Amplifier
          (  Layer     : in out Waveform_Layer;
             Amplifier : access Gtk_Adjustment_Record'Class := null
          );

This procedure changes or removes the amplifier object of Layer.

procedure Set_Color
          (  Layer : in out Waveform_Layer;
             Color : Gdk_Color
          );

This procedure changes the waveform line color to Color.

procedure Set_Extrapolation_Mode
          (  Layer : in out Waveform_Layer;
             Left  : Boolean;
             Right : Boolean
          );

This procedure sets the extrapolation mode. The parameters Left and Right determine the extrapolation to the left and to the right correspondingly.

procedure Set_Interpolation_Mode
          (  Layer : in out Waveform_Layer;
             Mode  : Interpolation_Mode
          );

This procedure sets the interpolation mode of the waveform line.

procedure Set_Opacity
          (  Layer   : in out Waveform_Layer;
             Opacity : Fill_Opacity
          );

This procedure sets the filling opacity under the wave curve. The opacity 0.0 turns the filling off.

procedure Set_Preferred_Method
          (  Layer  : in out Waveform_Layer;
             Method : Waveform_Drawing_Method
          );

This procedure sets the preferred drawing method. The method will be applied when possible:

type Waveform_Drawing_Method is
     (  Resample_New_And_Stroke,
        Resample_All_And_Stroke
     );

The available methods:

• Resample_All_And_Stroke samples the waveform points which would be visible and draws the corresponding line using cairo Stroke. Note that drawing lines is very inefficient in the current implementation of cairo;
• Resample_New_And_Stroke is same as above, but it tries to keep sampled points of the line. Only new points are sampled. The old ones are adjusted without requesting them anew from the source. As it was already said, Stroke is relatively inefficient, so the difference between these two methods might be marginal.

procedure Set_Source
          (  Layer  : in out Waveform_Layer;
             Source : in out Waveform_Data_Source'Class
          );
procedure Set_Source (Layer : in out Waveform_Layer);

This procedure connects the waveform to a data source. Without the Source parameter it disconnects the waveform from its current source if any. Note that the connected data source object shall not be destroyed before the waveform layer.

procedure Set_Sweeper
          (  Layer   : in out Waveform_Layer;
             Sweeper : access Gtk_Adjustment_Record'Class := null
          );

This procedure changes or removes the sweeper object of Layer.

procedure Sweep
          (  Layer : in out Waveform_Layer;
           [ From  : X_Axis; ]
             To    : X_Axis
          );

This procedure explicitly sets values corresponding to the left and right margins of the box. When the parameter From is omitted the left margin is moved to preserve the values range. Constraint_Error is propagated when From..To is an illegal range. Normally these values are set implicitly using an sweeper object.

9.5. Graph paper

The package Gtk.Layered.Graph_Paper declares the type of the graph paper layer:

type Graph_Paper_Layer (<>) is
   new Abstract_Layer
   and Scalable_Layer
   and Widened_Layer with private;

Graph paper is a set of vertical and horizontal lines to ease reading out values of waveform curves. A graph paper is amplified and swept synchronously with the waveforms drawn over it.

The following operations are defined on the graph paper layers:

procedure Add_Graph_Paper
          (  Under : not null access Layer_Location'Class;
             Box            : Cairo_Box;
             X_Tick_Length  : Positive  := 50;
             Y_Tick_Length  : Positive  := 50;
             Major_Width    : GDouble   := 1.0;
             Minor_Width    : GDouble   := 1.0;
             Major_Color    : Gdk_Color := RGB (0.0, 0.0, 0.0);
             Minor_Color    : Gdk_Color := RGB (0.5, 0.5, 0.5);
             Major_Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;
             Minor_Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;
             X_Axis  : access Gtk_Adjustment_Record'Class := null;
             Y_Axis  : access Gtk_Adjustment_Record'Class := null;
             Scaled  : Boolean := False;
             Widened : Boolean := False
          );
function Add_Graph_Paper
         (  Under : not null access Layer_Location'Class;
            Box            : Cairo_Box;
            X_Tick_Length  : Positive  := 50;
            Y_Tick_Length  : Positive  := 50;
            Major_Width    : GDouble   := 1.0;
            Minor_Width    : GDouble   := 1.0;
            Major_Color    : Gdk_Color := RGB (0.0, 0.0, 0.0);
            Minor_Color    : Gdk_Color := RGB (0.5, 0.5, 0.5);
            Major_Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;
            Minor_Line_Cap : Cairo_Line_Cap := CAIRO_LINE_CAP_BUTT;
            X_Axis  : access Gtk_Adjustment_Record'Class := null;
            Y_Axis  : access Gtk_Adjustment_Record'Class := null;
            Scaled  : Boolean := False;
            Widened : Boolean := False
         )  return not null access Graph_Paper_Layer;

These procedure and function create a graph paper layer. The parameter Under specifies the layer location. The parameter Box is the box bounding the graph paper. X_Tick_Length is the approximate pixel distance between graph paper vertical lines corresponding to the major ticks. Y_Tick_Length is the approximate pixel distance between graph paper horizontal lines corresponding to the major ticks. The distances between lines are chosen to correspond round values. Major_Width specifies the width of the major tick lines. Major ticks are lines which would have values shown by an annotation. Minor_Tick specifies the width of the minor tick lines. Minor ticks lines are drawn between major tick lines. Depending on the values there could one or four minor tick lines between two major tick lines. The colors of the major and minor tick lines are specified by the Major_Color and Minor_Color parameters correspondingly. The type of the tick lines ends are determined by the parameters Major_Line_Cap and Minor_Line_Cap. The parameter X_Axis is the sweeper adjustment used by the graph paper. When this parameter is specified as null, no vertical lines are drawn. The parameter Y_Axis is the amplifier adjustment used by the graph paper. When specified as null, no horizontal lines are drawn. The parameter Widened define the tick line width behavior upon the widget's layer sizing as described in Set_Widened. The parameter Scaled controls the layer resizing (see Set_Scaled). The parameter Scaled when true resizes the layer when the widget is resized:

• The x-coordinates of the box are multiplied by the widget's width and then added to the x-coordinate of the widget's center as returned by Get_Center;
• The y-coordinates of the box are multiplied by the widget's height and then added to the y-coordinate of the widget's center.

Constraint_Error is propagated when some of the parameters are illegal.

procedure Attach
          (  Layer      : in out Graph_Paper_Layer;
             Annotation : in out Graph_Paper_Annotation_Interface'Class
          );

This procedure attaches an annotation specified by the parameter Annotation to the graph paper Layer. When attached the annotation receives notification callbacks. The attached annotation must be detached using Detach. Upon layer destruction all attached annotations are automatically detached.

procedure Detach
          (  Layer      : in out Graph_Paper_Layer;
             Annotation : in out Graph_Paper_Annotation_Interface'Class
          );

This procedure detaches annotation specified by the parameter Annotation from the graph paper Layer. Nothing happens when annotation is not attached to Layer.