ADA INDUSTRIAL CONTROL WIDGET LIBRARY
version 3.25

Dmitry A. Kazakov
(mailbox@dmitry-kazakov.de)
[Home]

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 fedora   precompiled and packaged using RPM (see also release notes on the download page, for limitations of the packaged distribution)   [Download page] [Download page] [Download page] [Download page]
CentOS packages CentOS   precompiled and packaged using RPM (see also release notes on the download page, for limitations of the packaged distribution)       [Download page] [Download page]
Debian packages Debian   precompiled and packaged for dpkg (see also release notes on the download page, for limitations of the packaged distribution)   [Download page] [Download page] [Download page] [Download page]
Ubuntu packages Ubuntu      precompiled and packaged for dpkg (see also release notes on the download page, for limitations of the packaged distribution)   [Download page] [Download page] [Download page] [Download page]
Source distribution (any platform)   aicwl_3_25.tgz (tar + gzip, Windows users may use WinZip)     [Download]

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:

See also changes log.

[TOC][Next]

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

gauge round 254
Gtk_Gauge_Round_254
gauge round 270 reversed
Gtk_Gauge_Round_270_Reversed
gauge round 270
Gtk_Gauge_Round_270
gauge round 270 inout
Gtk_Gauge_Round_270_Inout
gauge round 270 out
Gtk_Gauge_Round_270_Outer
gauge round 270 60s
Gtk_Gauge_Round_270_60s

1.2. Sectors and segments

gauge round 180
Gtk_Gauge_Round_180
gauge elliptic 180
Gtk_Gauge_Elliptic_180
gauge round 90
Gtk_Gauge_Round_90
 
gauge round 110
Gtk_Gauge_Round_110

1.3. Meters

meter angular 90
Gtk_Meter_Angular_90
meter round 94
Gtk_Meter_Round_94
meter elliptic 90
Gtk_Meter_Elliptic_90
meter round 90
Gtk_Meter_Round_90
valve round 90
Gtk_Valve_Round_90
 
meter thermo
Gtk.Meter.Thermo
meter thermo symmetric
Gtk_Meter_Thermo_Symmetric
meter thermo dual
Gtk_Meter_Thermo_Dual

1.4. Flat and rectangular

gauge rectangular 70s
Gtk_Gauge_Rectangular_70s
gauge flat vertical
Gtk_Gauge_Flat_Vertical
gauge rectangular 60s slanted
Gtk_Gauge_Rectangular_70s_Slanted
gauge flat horizontal
Gtk_Gauge_Flat_Horizontal

1.5. Wall clocks

clock imperial
Gtk_Wall_Clock_Imperial
clock modern
Gtk_Wall_Clock_Modern
clock classic
Gtk_Wall_Clock_Classic
 

1.6. Oscilloscope

oscilloscope stack
Gtk_Oscilloscope

1.7. LEDs

gauge led round
Gtk_Gauge_Led_Round
gauge led rectangular
Gtk_Gauge_Led_Rectangular

[Back][TOC][Next]

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:

gauge anatomy

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:

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:

gauge border

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:

elliptic backgrounds

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:

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:

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:

text transformation mode

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:

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.


[Back][TOC][Next]

3. Backgrounds

Background layer is an opaque shape which can be used as a background of a gauge.

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 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.


[Back][TOC][Next]

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:

4.1. Elliptic scale

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

elliptic scale

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 (r1, k1, α1). The outer ellipse parameters are (r2, k2, α2). The ticks start at the angle β1 and end at the angle β2. The ticks are numbered 1, 2, 3, 4 until the skipped tick, which is not drawn. On the figure the skipped tick has the number 5. The number of the first tick can be different from 1. For example, in our example the first tick has the number 1. Should the first tick skipped, then its number must be set to 5.

type Elliptic_Scale_Layer (<>) is
   new
Abstract_Bordered_Layer
   and Scalable_Layer
   and Widened_Layer with private;

The following operations are defined in the package:

procedure Add_Elliptic_Scale
          (  Under    : not null access Layer_Location'Class;
             Step     : GDouble;
             First    : Tick_Number        := Tick_Number'Last;
             Skipped  : Tick_Number        := Tick_Number'Last;
             Outer    : Ellipse_Parameters := Unit_Circle;
             Inner    : Ellipse_Parameters := Unit_Circle / 2.0;
             From     : GDouble            := 0.0;
             Length   : GDouble            := 2.0 * Pi;
             Width    : GDouble            := 1.0;
             Color    : Gdk_Color          := RGB (0.0, 0.0, 0.0);
             Line_Cap : Cairo_Line_Cap     := CAIRO_LINE_CAP_BUTT;
             Scaled   : Boolean            := False;
             Widened  : Boolean            := False
          );
function
Add_Elliptic_Scale
         (  Under    : not null access Layer_Location'Class;
            Step     : GDouble;
            First    : Tick_Number        := Tick_Number'Last;
            Skipped  : Tick_Number        := Tick_Number'Last;
            Outer    : Ellipse_Parameters := Unit_Circle;
            Inner    : Ellipse_Parameters := Unit_Circle / 2.0;
            From     : GDouble            := 0.0;
            Length   : GDouble            := 2.0 * Pi;
            Width    : GDouble            := 1.0;
            Color    : Gdk_Color          := RGB (0.0, 0.0, 0.0);
            Line_Cap : Cairo_Line_Cap     := CAIRO_LINE_CAP_BUTT;
            Scaled   : Boolean            := False;
            Widened  : Boolean            := False
         )  return not null access Elliptic_Scale_Layer;

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

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:

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.


[Back][TOC][Next]

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:

Texts : Gtk.Enums.String_List.GList;

Texts : Controlled_String_List;

The list can be created using expressions like "A"/"B"/"C".

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:

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:

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

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.


[Back][TOC][Next]

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:

gauge needle

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:

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:

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:

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:

elliptic bar

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:

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:

gauge sector needle

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.

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:

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:

gauge flat needle

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:

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:

gauge 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:

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:

digital layer

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:

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

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:

disk needle

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:

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.


[Back][TOC][Next]

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:

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:

gauge cap

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:

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

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:

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:

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.


[Back][TOC][Next]

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 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.


[Back][TOC][Next]

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:

waveform objects

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:

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;
             FromTo    : 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:

waveform upscaling

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:

waveform downscaling

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:

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:

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:

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:

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.

waveform graphpaper

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:

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.

function Get_Box (Layer : Graph_Paper_Layer) return Cairo_Box;

This function returns the graph paper box.

function Get_Major_Line (Layer : Graph_Paper_Layer)
   return Line_Parameters;

This function returns the parameters of the major tick lines.

function Get_Minor_Line (Layer : Graph_Paper_Layer)
   return Line_Parameters;

This function returns the parameters of the minor tick lines.

function Get_X_Tick_Length (Layer : Graph_Paper_Layer)
   return Positive;

This function returns approximate distance in pixels between two vertical tick lines. Note that the actual distance will likely differ from this one.

function Get_Y_Tick_Length (Layer : Graph_Paper_Layer)
   return Positive;

This function returns approximate distance in pixels between two horizontal tick lines. Note that the actual distance will likely differ from this one.

function Get_X_Axis (Layer : Graph_Paper_Layer)
   return Gtk_Adjustment;

This function returns the sweeper object used by the graph paper or null.

function Get_Y_Axis (Layer : Graph_Paper_Layer)
   return Gtk_Adjustment;

This function returns the amplifier object used by the graph paper or null.

function Get_X_Raster (Layer : Graph_Paper_Layer)
   return Gtk.Layered.Waveform.Rasters.Scale;

This function returns the scale corresponding to the horizontal axis. The exception Use_Error is propagated when the scale information is not available because the layer has been changed and not yet drawn, so the scale is undetermined. Note that this would be the case if the annotation layer attached to the graph paper is drawn before the graph paper one. In that case the caller probably should re-queue another Draw operation and ignore the exception.

function Get_Y_Raster (Layer : Graph_Paper_Layer)
   return Gtk.Layered.Waveform.Rasters.Scale;

This function returns the scale corresponding to the vertical axis. The exception Use_Error is propagated when the scale information is not available because the layer has been changed and not yet drawn, so the scale is undetermined.

procedure Set
          (  Layer         : in out Graph_Paper_Layer;
             Box           : Cairo_Box;
             X_Tick_Length : Positive;
             Y_Tick_Length : Positive;
             Major_Line    : Line_Parameters;
             Minor_Line    : Line_Parameters
          );

This procedure sets the parameters of graph paper. Constraint_Error is propagated when some parameters are illegal.

procedure Set_X_Axis
          (  Layer      : not null access Graph_Paper_Layer;
             Adjustment : access Gtk_Adjustment_Record'Class
          );

This procedure sets adjustment object of the paper. When the parameter is null the vertical lines are not shown.

procedure Set_X_Tick_Length
          (  Layer  : not null access Graph_Paper_Layer;
             Length : Positive
          );

This procedure sets the approximate pixel distance between two major vertical ticks.

procedure Set_Y_Axis
          (  Layer      : not null access Graph_Paper_Layer;
             Adjustment : access Gtk_Adjustment_Record'Class
          );

This procedure sets adjustment object of the paper. When the parameter is null the horizontal lines are not shown.

procedure Set_Y_Tick_Length
          (  Layer  : not null access Graph_Paper_Layer;
             Length : Positive
          );

This procedure sets the approximate pixel distance between two major horizontal ticks.

9.6. Graph paper annotation

9.6.1. Annotation interface

The package Gtk.Layered.Graph_Paper declares the interface of the graph paper annotations:

type Graph_Paper_Annotation_Interface is limited interface;

The interface has the following primitive operations:

procedure Changed
          (  Annotation   : in out Graph_Paper_Annotation_Interface;
             Layer        : Graph_Paper_Layer'Class;
             Box          : Cairo_Box;
             FromTo    : X_Axis;
             Lower, Upper : Y_Axis
          )  is abstract;

Typically an annotation connected to the layer queries its dimensions and X/Y axis rasters to place its texts accordingly.

procedure Detached
          (  Annotation : in out Graph_Paper_Annotation_Interface
          )  is null;

The procedure is called when Annotation is detached from a graph paper layer.

function Render
         (  Layer  : Graph_Paper_Annotation_Interface;
            Value  : GDouble;
            Raster : Gtk.Layered.Waveform.Rasters.Scale
         )  return UTF8_String is abstract;

This function renders Value to an UTF-8 string using the scale Raster.

9.6.2. Axis annotation implementation

The package Gtk.Layered.Graph_Paper_Annotation provides an implementation of graph paper annotation interface to render plain numbers at the major ticks of a graph paper:

waveform annotation text

The package declares the type:

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

The following operations are defined on the annotation layer:

procedure Add_Graph_Paper_Annotation
          (  Under : not null access Layer_Location'Class;
             Paper : not null access Graph_Paper_Layer'Class;
             Location    : Axis_Location :=
                              (  Orientation => Vertical,
                                 Alignment   => Absolute,
                                 Top         => -0.5,
                                 Bottom      => -0.5,
                                 X_Position  =>  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_X   : Alignment          := Center;
             Justify_Y   : Vertical_Alignment := Center;
             Superscript : Boolean            := True;
             Background  : Gdk_Color          := RGB (1.0, 1.0, 1.0);
             Border      : GDouble            := 2.0;
             Overlap     : GDouble            :=-2.0;
             Opacity     : Fill_Opacity       := 1.0;
             Scaled      : Boolean            := False;
             Enlarged    : Boolean            := False
          );
function Add_Graph_Paper_Annotation
         (  Under : not null access Layer_Location'Class;
            Paper : not null access Graph_Paper_Layer'Class;
            Location    : Axis_Location :=
                             ( Orientation => Vertical,
                                Alignment  => Absolute,
                                Top        => -0.5,
                                Bottom     => -0.5,
                                X_Position =>  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_X   : Alignment          := Center;
            Justify_Y   : Vertical_Alignment := Center;
            Superscript : Boolean            := True;
            Background  : Gdk_Color          := RGB (1.0, 1.0, 1.0);
            Border      : GDouble            := 2.0;
            Overlap     : GDouble            :=-2.0;
            Opacity     : Fill_Opacity       := 1.0;
            Scaled      : Boolean            := False;
            Enlarged    : Boolean            := False
         )  return not null access Graph_Paper_Annotation_Layer;

These procedure and function create a graph paper annotation layer. The parameter Under specifies the layer location. The parameter Paper is the graph paper layer the annotation belongs to. Note that the annotation layer normally should be placed above the graph paper layer. The parameter Location specifies the placement of the annotation relatively to its graph paper. The Axis_Location type is declared in the same package as:

type Axis_Orientation is (Horizontal, Vertical);
type Axis_Alignment is (Absolute, Relative);
type Axis_Location
     (  Orientation : Axis_Orientation := Horizontal;
        Alignment   : Axis_Alignment   := Relative
     ) is
record
   case
Orientation is
      when
Horizontal =>
         Left  : GDouble := -0.5;
         Right : GDouble :=  0.5;
         case Alignment is
            when
Absolute =>
               Y_Position : GDouble := 0.0;
            when Relative =>
               Y_Value : Y_Axis := 0.0;
         end case;
      when Vertical =>
         Top    : GDouble := -0.5;
         Bottom : GDouble :=  0.5;
         case Alignment is
            when
Absolute =>
               X_Position : GDouble := 0.0;
            when Relative =>
               X_Value : X_Axis := 0.0;
         end case;
   end case;
end record;

According to the type Axis_Orientation the axis along which an annotation is oriented can be:

A value of the type Axis_Alignment specify the alignment of the axis:

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_X specifies the way the annotation text box is aligned horizontally relatively to its position on the axis:

Justify_Y specifies the way the annotation text box is aligned vertically relatively to its position on the axis:

Superscript when set true, it allows usage of superscript digits in formatting numbers, e.g. 123∙106. When set false numbers are formatted like 123E6.

Background is the annotation text box color. Border is the box border width around the text. Overlap is the allowed overlap of two consequent text boxes. Usually Overlap is negative, which absolute value is the gap between text boxes. Opacity is the text box color opacity, when the opacity 1, the box becomes invisible. The parameter Scaled when true resizes the layer when the widget is resized:

The parameter Enlarged when true enlarges the annotation text proportionally to the widget's size:

Constraint_Error is propagated when some of the parameters are illegal.

function Get_Background_Color (Layer : Graph_Paper_Annotation_Layer)
   return Gdk_Color;

This function returns the text box color.

function Get_Border (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns the text box border width.

function Get_Color (Layer : Graph_Paper_Annotation_Layer)
   return Gdk_Color;

This function returns the text color.

function Get_Enlarged (Layer : Graph_Paper_Annotation_Layer)
   return Boolean;

This function returns true when the annotation texts are enlarged proportionally to the widget's size.

function Get_Face (Layer : Graph_Paper_Annotation_Layer)
   return Pango_Cairo_Font;

This function returns annotation texts font.

function Get_Justify_X (Layer : Graph_Paper_Annotation_Layer)
   return Alignment;

This function returns annotation text boxes horizontal alignment.

function Get_Justify_Y (Layer : Graph_Paper_Annotation_Layer)
   return Vertical_Alignment;

This function returns annotation text boxes vertical alignment.

function Get_Height (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns annotation texts height.

function Get_Location (Layer : Graph_Paper_Annotation_Layer)
   return Axis_Location;

This function returns annotation texts axis location relative to the graph paper.

function Get_Opacity (Layer : Graph_Paper_Annotation_Layer)
   return Fill_Opacity;

This function returns the opacity of the annotation text box color.

function Get_Overlap (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns amount of the overlap allowed to the consequent annotation text boxes.

function Get_Stretch (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns the annotation text stretch.

function Get_Suffix (Layer : Graph_Paper_Annotation_Layer)
   return UTF8_String;

This function returns the text added to the end all annotation text created by the primitive operation Render or by the function set by Set_Renderer. By default the suffix is empty. It can be set using the procedure Set_Suffix.

function Get_Superscript (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns true if the superscript is allowed when formatting numbers.

function Get_Text_Angle (Layer : Graph_Paper_Annotation_Layer)
   return GDouble;

This function returns the annotation text angle.

function Image
         (  Layer : Graph_Paper_Annotation_Layer;
            Value : GDouble
         )  return UTF8_String;

This function returns the text representing Value in the format the annotation layer would use to render a tick's value.

procedure Set
          (  Layer       : in out Graph_Paper_Annotation_Layer;
             Location    : Axis_Location;
             Face        : Pango_Cairo_Font;
             Height      : GDouble;
             Stretch     : GDouble;
             Color       : Gdk_Color;
             Text_Angle  : Double;
             Justify_X   : Alignment;
             Justify_Y   : Vertical_Alignment;
             Superscript : Boolean;
             Background  : Gdk_Color;
             Border      : GDouble;
             Overlap     : GDouble;
             Opacity     : Fill_Opacity
          );

This procedure changes the parameters of the layer. The parameters are described for Add_Graph_Paper_Annotation.

procedure Set_Enlarged
          (  Layer    : in out Graph_Paper_Annotation_Layer;
             Enlarged : Boolean
          );

This procedure sets the annotation texts enlargement mode.

type Renderer_Function is access function
     (  Layer  : Graph_Paper_Annotation_Layer'Class;
        Value  : GDouble;
        Raster : Gtk.Layered.Waveform.Rasters.Scale
     )  return UTF8_String;
procedure Set_Renderer
          (  Layer    : in out Graph_Paper_Annotation_Layer;
             Renderer : Renderer_Function
          );

This procedure sets the custom annotation texts rendering function. When set not-null it overrides the primitive operation Render. Otherwise the function set is used instead. The function's parameters are similar to ones of Render.

procedure Set_Suffix
          (  Layer  : in out Graph_Paper_Annotation_Layer;
             Suffix : UTF8_String
          );

This procedure sets the text to add to the annotation texts created by the primitive operation Render or else by the function set by Set_Renderer.

9.6.3. Time annotation implementation

When the horizontal axis is time its values require rendering in a human readable format. The package Gtk.Layered.Graph_Paper_Annotation provides a time annotation layer for this purpose:

waveform time annotation

The time format is

<hour>:<minute>:<second>.<fractions of second>

The type declared in Gtk.Layered.Graph_Paper_Annotation is

type Graph_Paper_Time_Annotation_Layer (<>) is
   new
Graph_Paper_Annotation_Layer with private;

The following operations are defined on the time annotation layer:

procedure Add_Graph_Paper_Time_Annotation
          (  Under : not null access Layer_Location'Class;
             Paper : not null access Graph_Paper_Layer'Class;
             Location    : Axis_Location :=
                              (  Orientation => Horizontal,
                                 Alignment   => Absolute,
                                 Left        => -0.5,
                                 Right       => -0.5,
                                 Y_Position  =>  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  : Double             := 0.0;
             Justify_X   : Alignment          := Center;
             Justify_Y   : Vertical_Alignment := Center;
             Superscript : Boolean            := True;
             Background  : Gdk_Color          := RGB (1.0, 1.0, 1.0);
             Border      : GDouble            := 2.0;
             Overlap     : GDouble            :=-2.0;
             Opacity     : Fill_Opacity       := 1.0;
             Scaled      : Boolean            := False;
             Enlarged    : Boolean            := False
          );
function Add_Graph_Paper_Time_Annotation
         (  Under : not null access Layer_Location'Class;
            Paper : not null access Graph_Paper_Layer'Class;
            Location    : Axis_Location :=
                             (  Orientation => Horizontal,
                                Alignment   => Absolute,
                                Left        => -0.5,
                                Right       => -0.5,
                                Y_Position  =>  0.0
                             );
            Face        : Pango_Cairo_Font :=
                             Create_Toy
                             (  Family => "arial",
                                Slant  => CAIRO_FONT_SLANT_NORMAL,
                                Weight => CAIRO_FONT_WEIGHT_NORMAL
                             );
            Height      : Double             := 12.0;
            Stretch     : Double             := 1.0;
            Color       : Gdk_Color          := RGB (0.0, 0.0, 0.0);
            Text_Angle  : GDouble            := 0.0;
            Justify_X   : Alignment          := Center;
            Justify_Y   : Vertical_Alignment := Center;
            Superscript : Boolean            := True;
            Background  : Gdk_Color          := RGB (1.0, 1.0, 1.0);
            Border      : GDouble            := 2.0;
            Overlap     : GDouble            :=-2.0;
            Opacity     : Fill_Opacity       := 1.0;
            Scaled      : Boolean            := False;
            Enlarged    : Boolean            := False
         )  return not null access Graph_Paper_Time_Annotation_Layer;

These procedure and function create a graph paper time annotation layer. The meaning of the parameters is same as for Graph_Paper_Annotation_Layer.

function Image (Stamp : Ada.Calendar.Time) return String;

This function returns a text representation of Stamp,

9.7. Scales

The package Gtk.Layered.Waveform instantiates Strings_Edit.Generic_Scale under the name Rasters.


[Back][TOC][Next]

10. Miscellany

10.1. Elliptic shapes

The package Cairo.Ellipses provides means for drawing elliptic arcs and also defines some convenience types and operations.

type Cairo_Tuple is record
   X : GDouble;
   Y : GDouble;
end record
;

The type Cairo_Tuple defines a point of 2D space.

type Cairo_Box is record
   X1 : GDouble;
   Y1 : GDouble;
   X2 : GDouble;
   Y2 : GDouble;
end record
;

The type Cairo_Box defines a rectangle in 2D space. The following convenience operations are defined on boxes:

function Get_Path_Extents (Context : Cairo_Context)
   return Cairo_Box;

This function returns the box bounding current path in the context.

type Ellipse_Parameters is record
   Center          : Cairo_Tuple;
   Major_Curvature : GDouble;
   Minor_Radius    : GDouble;
   Angle           : GDouble := 0.0;
end record
;

The type Ellipse_Parameters defines parameters of an ellipse. The following figure illustrates the meaning of the ellipse parameters:

ellipse parameters

Note that the cairo coordinate system has the y-axis upside-down. Correspondingly all angles are incremented clockwise. The parameters of the curve are:

The parameters of an elliptic arc are further:

10.1.1. Relative angles

The type Ellipse_Angle specifies the angle relatively to the major axis of the ellipse after scaling the ellipse to a circle:

type Ellipse_Angle is new GDouble;

The angles can be converted to each other using the following operations:

function "*"
         (  Ellipse : Ellipse_Parameters;
            Angle   : GDouble
         )  return Ellipse_Angle;
function "*"
         (  Angle   : GDouble;
            Ellipse : Ellipse_Parameters
         )  return Ellipse_Angle;

These functions convert an absolute angle to the corresponding relative angle of Ellipse.

function "/"
         (  Angle   : Ellipse_Angle;
            Ellipse : Ellipse_Parameters
         )  return GDouble;

This function converts a relative angle to the corresponding absolute angle.

10.1.2. Transformations

The following operations transform ellipses:

function "*"
         (  Ellipse : Ellipse_Parameters;
            Gain    : GDouble
         )  return Ellipse_Parameters;
function "*"
         (  Gain    : GDouble;
            Ellipse : Ellipse_Parameters
         )  return Ellipse_Parameters;
function "/"
         (  Ellipse : Ellipse_Parameters;
            Gain    : GDouble
         )  return Ellipse_Parameters;

Multiplying or dividing by a scalar magnifies or shrinks the ellipse by Gain.

function "+"
         (  Ellipse : Ellipse_Parameters;
            Offset  : Cairo_Tuple
         )  return Ellipse_Parameters;
function "+"
         (  Offset  : Cairo_Tuple;
            Ellipse : Ellipse_Parameters
         )  return Ellipse_Parameters;
function "-"
         (  Ellipse : Ellipse_Parameters;
            Offset  : Cairo_Tuple
         )  return Ellipse_Parameters;
function "-"
         (  Offset  : Cairo_Tuple;
            Ellipse : Ellipse_Parameters
         )  return Ellipse_Parameters;

Adding Offset to the ellipse moves it by adding Offset to its center.

10.1.3. Information functions

function Get_Point
         (  Ellipse : Ellipse_Parameters;
            Angle   : Ellipse_Angle
         )  return Cairo_Tuple;

This function returns the coordinates of an ellipse point at Angle. Angle is the ellipse angle relatively to the major ellipse axis. Constraint_Error is propagated when the result is infinite.

function Get_X
         (  Ellipse : Ellipse_Parameters;
            Angle   : Ellipse_Angle
         )  return GDouble;
function
Get_X
         (  Ellipse : Ellipse_Parameters;
            Angle   : Ellipse_Angle
         )  return GDouble;

These function return the coordinates of the ellipse point at Angle. Angle is the ellipse angle relatively to the major ellipse axis. Constraint_Error is propagated when the result is infinite.

function Is_Bounded (Ellipse : Ellipse_Parameters) return Boolean;

This function returns true if the ellipse is bounded.

10.1.4. Drawing

procedure Elliptic_Arc
          (  Context : Cairo_Context;
             Ellipse : Ellipse_Parameters;
             From    : Ellipse_Angle := 0.0;
             Length  : Ellipse_Angle := 2.0 * Pi
          );

This procedure draws an elliptic arc starting at the angle From to the angle From + Length. Length can be negative. Constraint_Error is propagated when the arc would go into infinity.

10.2. Stream I/O

The package Gtk.Layered.Stream_IO provides stream I/O of layered widgets and the data types related to such I/O. The widget I/O is achieved by the operations:

procedure Restore
          (  Stream : in out Root_Stream_Type'Class;
             Widget : not null access Gtk_Layered_Record'Class
          );

This procedure restores layers stored in Stream. The layers are added on top of Widget. Constraint_Error is propagated when parameters of some layers are illegal. Other exceptions may indicate input errors. At the end of restoring you might wish to call Queue_Draw in order to make the changes visible.

procedure Store
          (  Stream : in out Root_Stream_Type'Class;
             Widget : not null access constant Gtk_Layered_Record'Class
          );

This procedure restores layers stored in Stream. The layers are added on top of Widget. Constraint_Error is propagated when parameters of some layers are illegal. Other exceptions may indicate output errors.

The package also provides Store and Restore operations for types used to describe the parameters of the widget. The implementation of these operations uses character output and the format portable across platforms supporting character streams.

10.3. Interpolation mode

The interpolation modes of waveforms are defined by the type:

type Interpolation_Mode is (Left, Linear);

in the package Gtk.Layered. The modes are:

10.4. Vertical alignment

The types of vertical alignment are defined by:

type Vertical_Alignment is (Top, Center, Bottom);

in the package Gtk.Layered.

10.5. Fonts

The package Pango.Cairo.Fonts provides an abstraction layer above toy and Pango fonts, which are differently handled in cairo. The package defines the type

type Pango_Cairo_Font is private;

which encapsulates different kind of fonts. The object uses reference counting for the underlying face objects.

function Create_Pango
         (  Family  : String;
            Style   : Pango.Enums.Style   := Pango_Style_Normal;
            Variant : Pango.Enums.Variant := Pango_Variant_Normal;
            Weight  : Pango.Enums.Weight  := Pango_Weight_Normal;
            Stretch : Pango.Enums.Stretch := Pango_Stretch_Normal;
            Size    : GInt                := 12
         )  return Pango_Cairo_Font;

This function creates pango font face. The parameters are same as ones of To_Font_Description from Pango.Font.

function Create_Pango_From_Description (Description : UTF8_String)
   return Pango_Cairo_Font;

This function creates pango font face. The parameter Description is same as in From_String from Pango.Font.

function Create_Toy
         (  Family : UTF8_String;
            Slant  : Cairo_Font_Slant  := CAIRO_FONT_SLANT_NORMAL;
            Weight : Cairo_Font_Weight := CAIRO_FONT_WEIGHT_NORMAL
         )  return Pango_Cairo_Font;

This function creates a toy font face. The parameters are same as ones of Toy_Font_Face_Create from Cairo.Font_Face.

function Get_Family
         (  Font : Pango_Cairo_Font
         )  return UTF8_String;

This function returns the font family.

procedure Get_Markup_Extents
          (  Font    : Pango_Cairo_Font;
             Context : Cairo_Context;
             Text    : UTF8_String;
             Extents : out Cairo_Text_Extents
          );

This procedure calculates the extents of the pango markup text specified by the parameter Text. For the toy font the result is equivalent to the extent of the text with all tags stripped. Note that the implementation may change the context settings. The result is set into the parameter Extents.

function Get_Slant
         (  Font : Pango_Cairo_Font
         )  return Cairo_Font_Slant;

This function returns the font slant.

function Get_Size (Font : Pango_Cairo_Font) return GInt;

This function returns the font size in points. For a toy font it is always 12.

procedure Get_Text_Extents
          (  Font    : Pango_Cairo_Font;
             Context : Cairo_Context;
             Text    : UTF8_String;
             Extents : out Cairo_Text_Extents
          );

This procedure calculates the extents of Text. Note that the implementation may change the context settings. The result is set into the parameter Extents.

function Get_Weight
         (  Font : Pango_Cairo_Font
         )  return Cairo_Font_Weight;
function Get_Weight
         (  Font : Pango_Cairo_Font
         )  return Pango.Enums.Weight;

These functions return the font slant as either toy or pango enumeration type. The original slant values is converted as necessary.

procedure Restore
          (  Stream : in out Root_Stream_Type'Class;
             Font   : out Pango_Cairo_ Font
          );

This procedure restores Font from data previously written into Stream using Store.

procedure Set_Family
          (  Font   : in out Pango_Cairo_Font;
             Family : UTF8_String
          );

This procedure sets the font face family.

procedure Set_Slant
          (  Font  : in out Pango_Cairo_Font;
             Slant : Cairo_Font_Slant
          );

This changes the font face slant.

procedure Set_Size
          (  Font : in out Pango_Cairo_Font;
             Size : GInt
          );

This changes the font size. For a toy font the procedure is void.

procedure Set_Weight
          (  Font   : in out Pango_Cairo_Font;
             Weight : Cairo_Font_Weight
          );
procedure Set_Weight
          (  Font   : in out Pango_Cairo_Font;
             Weight : Pango.Enums.Weight
          );

This changes the font face weight. The value is converted as necessary.

procedure Show_Markup
          (  Font    : Pango_Cairo_Font;
             Context : Cairo_Context;
             Text    : UTF8_String
          );

This procedure renders the pango markup text specified by the parameter Text in Context. For the toy font the result is equivalent to the extent of the text with all tags stripped. The text baseline is drawn right of the current position in the context. Note that when Text should not contain multiple lines.

procedure Show_Text
          (  Font    : Pango_Cairo_Font;
             Context : Cairo_Context;
             Text    : UTF8_String
          );

This procedure renders Text right of the current position in Context. Note that when Text should not contain multiple lines.

procedure Store
          (  Stream : in out Root_Stream_Type'Class;
             Font   : Pango_Cairo_Font
          );

This procedure stores Font into Stream. It can be read from stream using Restore.


[Back][TOC][Next]

11. Samples

The software contains widgets provided as usable samples of instruments. Due to great variance of requirements along automation projects it does not make sense to provide widgets of fixed layouts. The sample widgets are rather intended to illustrate the usage of layers in order to achieve the desired appearance of the instruments. The samples can be used as templates for custom instruments design. Note also that sample widgets can be easily enhanced. The test application illustrates this by adding needles and labels to existing widgets without modifying their implementation.

If a needle need to be added to the widget, the widget's background is layer is queried and the new needle layer is inserted under the foreground layer of the background:

Gtk_New (Adjustment, 0.0, 0.0, 100.0, 1.0, 10.0);
Add_Elliptic_Bar
(  Under      => Widget.Get_Background.Get_Foreground,
   Ellipse    => ((0.0, 0.0), 1.0 / 0.47, 0.47, 0.0),
   From       => 1.0 * Pi / 4.0,
   Length     => -3.0 * Pi / 2.0,
   Width      => 0.015,
   Color      => RGB (1.0, 0.6, 0.3),
   Adjustment => Adjustment,
   Scaled     => True,
   Widened    => True
);

Here a round bar needle is added to Widget. If the needle must be under the widget's needle, then the needle layer is used to put the new one needle under. Labels showing texts are usually added under the caching layer of the widget.

11.1. Gauges

The samples of widgets implementing gauges are grouped as child packages of the package Gtk.Gauge.

11.1.1. Gtk.Gauge.Round_254

The package Gtk.Gauge.Round_254 provides the widget:

gauge round 254

type Gtk_Gauge_Round_254_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_254 is
   access all Gtk_Gauge_Round_254_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget      : out Gtk_Gauge_Round_254;
             Major_Texts : texts specification;
             Minor_Texts : texts specification;
           [ Delimiter   : Character := ' '; ]
             Adjustment  : Gtk_Adjustment := null;
             Sectors     : Positive := 17
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_254_Record'Class;
             Major_Texts : texts specification;
             Minor_Texts : texts specification;
           [ Delimiter   : Character; ]
             Adjustment  : Gtk_Adjustment;
             Sectors     : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_254_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_254_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Major_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_254_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Minor_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_254_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's minor annotation layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_254_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_254_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.1.2. Gtk.Gauge.Round_270

The package Gtk.Gauge.Round_270 provides the widget:

gauge round 270

Note that the indicated text mph does not belong to the widget, it was added later placing a Label under the caching layer.

type Gtk_Gauge_Round_270_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_270 is
   access all Gtk_Gauge_Round_270_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_270;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 6
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_270_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.1.3. Gtk.Gauge.Round_270_Outer

The package Gtk.Gauge.Round_270_Outer provides the widget:

gauge round 270 out

Note that the indicated sector does not belong to the widget, it was added later placing a Sector_Needle above the caching layer. The indicated text mph was added later placing a Label under the caching layer.

type Gtk_Gauge_Round_270_Outer_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_270_Outer is
   access all Gtk_Gauge_Round_270_Outer_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_270_Outer;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 6
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_270_Outer_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Outer_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Outer_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Outer_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Outer_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_Outer_Record;
             Value  : GDouble


          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.1.4. Gtk.Gauge.Round_270_Reversed

The package Gtk.Gauge.Round_270_Reversed provides a gauge with the needle moving counterclockwise:

gauge round 270 reversed

type Gtk_Gauge_Round_270_Reversed_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_270_Reversed is
   access all Gtk_Gauge_Round_270_Reversed_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_270_Reversed;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 9
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_270_Reversed_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Reversed_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Reversed_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Reversed_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Reversed_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_Reversed_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.1.5. Gtk.Gauge.Round_270_Inout

The package Gtk.Gauge.Round_270_Inout provides the widget:

gauge round 270 inout

type Gtk_Gauge_Round_270_Inout_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_270_Inout is
   access all Gtk_Gauge_Round_270_Inout_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget      : out Gtk_Gauge_Round_270_Inout;
             Major_Texts : texts specification;
             Minor_Texts : texts specification;
           [ Delimiter   : Character := ' '; ]
             Adjustment  : Gtk_Adjustment := null;
             Sectors     : Positive := 14
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_270_Inout_Record'Class;
             Major_Texts : texts specification;
             Minor_Texts : texts specification;
           [ Delimiter   : Character; ]
             Adjustment  : Gtk_Adjustment;
             Sectors     : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Inout_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Inout_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Major_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Inout_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Minor_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Inout_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's minor annotation layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Inout_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_Inout_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.1.6. Gtk.Gauge.Round_270_60s

The package Gtk.Gauge.Round_270_60s provides the widget styled as the speedometer of a car built in 60's:

gauge round 270 60s

Note that the indicated colored bar does not belong to the widget, it was added later placing a Elliptic_Bar above the caching layer.

type Gtk_Gauge_Round_270_60s_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_270_60s is
   access all Gtk_Gauge_Round_270_60s_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_270_60s;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 12
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_270_60s_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_270_60s_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_270_60s_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_270_60s_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_60s_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_60s_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.2. Sectors and segments

11.2.1. Gtk.Gauge.Round_180

The package Gtk.Gauge.Round_180 provides the widget:

gauge round 180

type Gtk_Gauge_Round_180_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_180 is
   access all Gtk_Gauge_Round_180_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_180;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 12
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_180_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_180_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_180_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_180_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_180_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_180_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.2.2. Gtk.Gauge.Round_90

The package Gtk.Gauge.Round_90 provides the widget:

gauge round 90

type Gtk_Gauge_Round_90_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_90 is
   access all Gtk_Gauge_Round_90_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_90;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 5
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_90_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_90_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_90_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_90_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_90_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_90_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.2.3. Gtk.Gauge.Round_110

The package Gtk.Gauge.Round_110 provides the widget styled as the speedometer of a car from late 50's - early 60's:

gauge round 110

type Gtk_Gauge_Round_110_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Round_110 is
   access all Gtk_Gauge_Round_110_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Round_110;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 9
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Round_110_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Round_110_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Round_110_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Round_110_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_110_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_110_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.2.4. Gtk.Gauge.Elliptic_180

The package Gtk.Gauge.Elliptic_180 provides the widget with the scale shaped as an asymmetric elliptic arrow:

gauge elliptic 180

type Gtk_Gauge_Elliptic_180_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Elliptic_180 is
   access all Gtk_Gauge_Elliptic_180_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Elliptic_180;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 8
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Elliptic_180_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Elliptic_180_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Elliptic_180_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Elliptic_180_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Elliptic_180_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Elliptic_180_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3. Meters

The samples of metering instruments are grouped in the child packages of the package Gtk.Meter.

11.3.1. Gtk.Meter.Angular_90

The package Gtk.Meter.Angular_90 provides the widget with the needle mounted in the right bottom angle. The indicated text V was added later placing a Label under the caching layer.

meter angular 90

type Gtk_Meter_Angular_90_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Angular_90 is
   access all Gtk_Meter_Angular_90_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Meter_Angular_90;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 4
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Angular_90_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Meter_Angular_90_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Meter_Angular_90_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Meter_Angular_90_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Meter_Angular_90_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Meter_Angular_90_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3.2. Gtk.Meter.Elliptic_90

The package Gtk.Meter.Elliptic_90 provides the widget with a scale shaped as an elliptic arc:

meter elliptic 90

type Gtk_Meter_Elliptic_90_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Elliptic_90 is
   access all Gtk_Meter_Elliptic_90_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Meter_Elliptic_90;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 5
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Elliptic_90_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Meter_Elliptic_90_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Meter_Elliptic_90_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Meter_Elliptic_90_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Meter_Elliptic_90_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Meter_Elliptic_90_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3.3. Gtk.Meter.Round_90

The package Gtk.Meter.Round_90 provides the widget shaped as a modern instrument with round 90º scale. The indicated text V was added later placing a Label under the caching layer:

meter round 90

type Gtk_Meter_Round_90_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Round_90 is
   access all Gtk_Meter_Round_90_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Meter_Round_90;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 4
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Round_90_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Meter_Round_90_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Meter_Round_90_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Meter_Round_90_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Meter_Round_90_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Meter_Round_90_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3.4. Gtk.Meter.Round_94

The package Gtk.Meter.Round_94 provides the widget shaped as a classic instrument with round 94º scale. The indicated text V was added later placing a Label under the caching layer:

meter round 94

type Gtk_Meter_Round_94_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Round_94 is
   access all Gtk_Meter_Round_94_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Meter_Round_94;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 5
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Round_94_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Meter_Round_94_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Meter_Round_94_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Meter_Round_94_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Meter_Round_94_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Meter_Round_94_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3.5. Gtk.Meter.Thermo

The package Gtk.Meter.Thermo provides the widget shaped as a thermometer:

meter thermo

type Gtk_Meter_Thermo_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Thermo is
   access all Gtk_Meter_Thermo_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Meter_Thermo;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive  := 10;
             Label      : String    := Celsius;
             Color      : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );

These procedures create the widget. The parameter Sectors specified the number of intervals between major ticks. Label is the text shown by the label. The default is °C. Color is the color of the temperature bar.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive;
             Label      : String;
             Color      : Gdk_Color
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return not null access Flat_Annotation_Layer;

This function returns the widget's annotation layer.

function Get_Background
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Bar
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return not null access Bar_Layer;

This function returns the temperature bar.

function Get_Bar_Color
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return Gdk_Color;

This function returns the color of the temperature bar.

function Get_Label
         (  Widget : not null access Gtk_Meter_Thermo_Record
         )  return not null access Label_Layer;

This function returns the label of the widget.

procedure Set_Bar_Color
          (  Widget : not null access Gtk_Meter_Thermo_Record;
             Color  : Gdk_Color
          );

This procedure changes the color of the temperature bar.

procedure Set_Value
          (  Widget : not null access Gtk_Meter_Thermo_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

Note that the digital value indicated on the left of the widget as seen on the picture does not belong to it. It is added to the widget later as the following code snippet shows:

   Widget     : Gtk_Meter_Thermo;
   Adjustment : Gtk_Adjustment;
begin
   Gtk_New (Adjustment, 0.0, -20.0, 40.0, 1.0, 10.0);
   Gtk_New
   (  Widget     => Widget,
      Texts      => "-20 -10 0 10 20 30 40",
      Sectors    => 6,
      Adjustment => Adjustment
   );
   Add_Digital
   (  Under      => Widget.Get_Background.Get_Foreground,
      Location   => (-0.4, 0.0),
      Mode       => Rotated,
      Angle      => 3.0 * Pi / 2.0,
      Adjustment => Adjustment,
      Precision  => -1,
      Height     => 0.12,
      Scaled     => True
   );

11.3.6. Gtk.Meter.Thermo_Symmetric

The package Gtk.Meter.Thermo_Symmetric provides the widget shaped as a thermometer with two identical scales left and right of the bar:

meter thermo symmetric

type Gtk_Meter_Thermo_Symmetric_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Thermo_Symmetric is
   access all Gtk_Meter_Thermo_Symmetric_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget      : out Gtk_Meter_Thermo_Symmetric;
             Texts       : texts specification;
           [ Delimiter   : Character := ' '; ]
             Adjustment  : Gtk_Adjustment := null;
             Sectors     : Positive  := 10;
             Left_Label  : String    := Celsius;
             Right_Label : String    := Celsius;
             Color       : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );

These procedures create the widget. The parameter Sectors specified the number of intervals between major ticks. Left_Label and Right_Label are the texts shown by the label. The default is °C. Color is the color of the temperature bar.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Symmetric_Record'Class;
             Texts       : texts specification;
           [ Delimiter   : Character; ]
             Adjustment  : Gtk_Adjustment;
             Sectors     : Positive;
             Left_Label  : String;
             Right_Label : String;
             Color       : Gdk_Color
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Bar
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Bar_Layer;

This function returns the temperature bar.

function Get_Bar_Color
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return Gdk_Color;

This function returns the color of the temperature bar.

function Get_Left_Annotation
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Flat_Annotation_Layer;
function
Get_Right_Annotation
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Flat_Annotation_Layer;

These functions return the widget's annotation layers.

function Get_Left_Label
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Label_Layer;
function
Get_Right_Label
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Symmetric_Record
         )  return not null access Label_Layer;

These functions return the corresponding label of the widget.

procedure Set_Bar_Color
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Symmetric_Record;
             Color  : Gdk_Color
          );

This procedure changes the color of the temperature bar.

procedure Set_Value
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Symmetric_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.3.6. Gtk.Meter.Thermo_Dual

The package Gtk.Meter.Thermo_Dual provides the widget shaped as a thermometer with Fahrenheit and Celsius scales left and right of the bar. Since the scales are defined the widget has a more interface specific interface which automatically generates the annotations of the scales from the specified range of indicated temperatures:

meter thermo dual

type Gtk_Meter_Thermo_Dual_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Meter_Thermo_Dual is
   access all Gtk_Meter_Thermo_Dual_Record'Class;

The following operations are provided:

procedure Gtk_New_Celsius
          (  Widget     : out Gtk_Meter_Thermo_Dual;
             Adjustment : not null access
                          Gtk_Adjustment_Record'Class;
             Sectors    : Positive  := 8;
             Color      : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );
procedure
Gtk_New_Fahrenheit
          (  Widget     : out Gtk_Meter_Thermo_Dual;
             Adjustment : not null access
                          Gtk_Adjustment_Record'Class;
             Sectors    : Positive  := 8;
             Color      : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );

These procedures create the widget. The parameter Adjustment is the adjustment the temperature bar will indicate. The range of the adjustment returned by the calls Get_Lower and Get_Upper determines the range of the temperatures indicated. For the procedure Gtk_New_Celsius it the Celsius degrees. For the procedure Gtk_New_Fahrenheit it is the Fahrenheit degrees. The opposite scale is set to correspond this range. The parameter Sectors specified the approximate number of intervals between major ticks on the Celsius or Fahrenheit scale depending on the call. The actual number of ticks is derived from the range and this number. Color is the color of the temperature bar. Constraint_Error is propagated when the temperature range is illegal.

procedure Gtk_New_Celsius
          (  Widget  : out Gtk_Meter_Thermo_Dual;
             Lower   : GDouble    := -40.0;
             Upper   : GDouble    := 50.0;
             Sectors : Positive  := 8;
             Color   : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );
procedure
Gtk_New_Fahrenheit
          (  Widget  : out Gtk_Meter_Thermo_Dual;
             Lower   : GDouble    := 20.0;
             Upper   : GDouble    := 220.0;
             Sectors : Positive  := 8;
             Color   : Gdk_Color := RGB (1.0, 0.0, 0.0)
          );

This procedures creates the widget when the range is specified explicitly and no adjustment is used. Constraint_Error is propagated when the temperature range is illegal.

procedure Initialize_{Celsius|Fahrenheit}
          (  Widget     : not null access
                        
 Gtk_Meter_Thermo_Dual_Record'Class;
             Adjustment : not null access
                          Gtk_Adjustment_Record'Class;
             Sectors    : Positive;
             Color      : Gdk_Color
          );
procedure
Initialize_{Celsius|Fahrenheit}
          (  Widget  : not null access
                     
 Gtk_Meter_Thermo_Dual_Record'Class;
             Lower   : GDouble;
             Upper   : GDouble;
             Sectors : Positive;
             Color   : Gdk_Color
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Bar
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return not null access Bar_Layer;

This function returns the temperature bar.

function Get_Bar_Color
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return Gdk_Color;

This function returns the color of the temperature bar.

function Get_{Celsius|Fahrenheit}_Annotation
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return not null access Flat_Annotation_Layer;

These functions return the widget's annotation layers.

function Get_{Celsius|Fahrenheit}_Label
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return not null access Label_Layer;

These functions return the corresponding label of the widget.

function Get_{Celsius|Fahrenheit}_Value
         (  Widget : not null access
                   
 Gtk_Meter_Thermo_Dual_Record
         )  return Double;

These functions return currently indicated temperature in the specified unit.

procedure Set_Bar_Color
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Symmetric_Record;
             Color  : Gdk_Color
          );

This procedure changes the color of the temperature bar.

procedure Set_{Celsius|Fahrenheit}_Value
          (  Widget : not null access
                    
 Gtk_Meter_Thermo_Dual_Record;
             Value  : GDouble
          );

These procedures change the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.4. Flat and rectangular

11.4.1. Gtk.Gauge.Rectangular_70s

The package Gtk.Gauge.Rectangular_70s provides the widget styled as the speedometer of a car built in 70's:

gauge rectangular 70s

type Gtk_Gauge_Rectangular_70s_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Rectangular_70s is
   access all Gtk_Gauge_Rectangular_70s_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Rectangular_70s;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 12
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Rectangular_70s_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Rectangular_70s_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.4.2. Gtk.Gauge.Rectangular_70s_Slanted

The package Gtk.Gauge.Rectangular_70s_Slanted provides the widget styled as the speedometer of a car built in 70's:

gauge rectangular 70s slanted

type Gtk_Gauge_Rectangular_70s_Slanted_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Rectangular_70s_Slanted is
   access all Gtk_Gauge_Rectangular_70s_Slanted_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Rectangular_70s_Slanted;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 12
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Rectangular_70s_Slanted_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Slanted_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Slanted_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Slanted_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Rectangular_70s_Slanted_Record
         )  return not null access Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Rectangular_70s_Slanted_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.4.3. Gtk.Gauge.Flat_Horizontal

The package Gtk.Gauge.Flat_Horizontal provides the widget:

gauge flat horizontal

Note that the indicated colored bar does not belong to the widget, it was added later placing a Bar above the caching layer.

type Gtk_Gauge_Flat_Horizontal_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Flat_Horizontal is
   access all Gtk_Gauge_Flat_Horizontal_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Flat_Horizontal;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 10
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Flat_Horizontal_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Flat_Horizontal_Record
         )  return not null access Flat_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Flat_Horizontal_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Flat_Horizontal_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Flat_Horizontal_Record
         )  return not null access Flat_Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Flat_Horizontal_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.4.4. Gtk.Gauge.Flat_Vertical

The package Gtk.Gauge.Flat_Vertical provides the widget:

gauge flat vertical

Note that the indicated colored bar does not belong to the widget, it was added later placing a Bar above the caching layer.

type Gtk_Gauge_Flat_Vertical_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_Flat_Vertical is
   access all Gtk_Gauge_Flat_Vertical_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Gauge_Flat_Vertical;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 10
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Gauge_Flat_Vertical_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Gauge_Flat_Vertical_Record
         )  return not null access Flat_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Gauge_Flat_Vertical_Record
         )  return not null access Rectangular_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access
                     Gtk_Gauge_Flat_Vertical_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Flat_Vertical_Record
         )  return not null access Flat_Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Flat_Vertical_Record;
             Value  : GDouble
          );

This procedure the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.5. Clocks

The package Gtk.Wall_Clocks has children packages implementing various wall clocks.

11.5.1. Gtk.Wall_Clock.Imperial

The package Gtk.Wall_Clock.Imperial provides the widget:

clock imperial

type Gtk_Wall_Clock_Imperial_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Wall_Clock_Imperial is
   access all Gtk_Wall_Clock_Imperial_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Wall_Clock_Imperial;
             Adjustment : Gtk_Adjustment := null
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Wall_Clock_Imperial_Record'Class;
             Adjustment : Gtk_Adjustment
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Wall_Clock_Imperial_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Wall_Clock_Imperial_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Hour_Hand
         (  Widget : not null access
                     Gtk_Wall_Clock_Imperial_Record
         )  return not null access Clock_Hand_Layer;

This function returns the widget's hour hand.

function Get_Minute_Hand
         (  Widget : not null access
                     Gtk_Wall_Clock_Imperial_Record
         )  return not null access Clock_Hand_Layer;

This function returns the widget's minute hand.

function Get_Cache
         (  Widget : not null access
                     Gtk_Wall_Clock_Imperial_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Wall_Clock_Imperial_Record;
             Value  : Time
          );

This procedure changes the indicated time. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.5.2. Gtk.Wall_Clock.Classic

The package Gtk.Wall_Clock.Classic provides the widget with two dials:

clock classic

type Gtk_Wall_Clock_Classic_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Wall_Clock_Classic is
   access all Gtk_Wall_Clock_Classic_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Wall_Clock_Imperial;
             Adjustment : Gtk_Adjustment := null
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Wall_Clock_Classic_Record'Class;
             Adjustment : Gtk_Adjustment
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Hour_Hand
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Needle_Layer;

This function returns the widget's hour hand.

function Get_Minute_Hand
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Needle_Layer;

This function returns the widget's minute hand.

function Get_Second_Hand
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Needle_Layer;

This function returns the widget's second hand.

function Get_Cache
         (  Widget : not null access
                     Gtk_Wall_Clock_Classic_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Wall_Clock_Classic_Record;
             Value  : Time
          );

This procedure changes the indicated time. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.5.3. Gtk.Wall_Clock.Modern

The package Gtk.Wall_Clock.Modern provides the widget with two dials:

clock modern

type Gtk_Wall_Clock_Modern_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Wall_Clock_Modern is
   access all Gtk_Wall_Clock_Modern_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Wall_Clock_Modern;
             Adjustment : Gtk_Adjustment := null
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Wall_Clock_Modern_Record'Class;
             Adjustment : Gtk_Adjustment
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Hour_Hand
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Needle_Layer;

This function returns the widget's hour hand.

function Get_Minute_Hand
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Needle_Layer;

This function returns the widget's minute hand.

function Get_Second_Hand
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Needle_Layer;

This function returns the widget's second hand.

function Get_Cache
         (  Widget : not null access Gtk_Wall_Clock_Modern_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

procedure Set_Value
          (  Widget : not null access Gtk_Wall_Clock_Modern_Record;
             Value  : Time
          );

This procedure changes the indicated time. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.6. LEDs

11.6.1. Gtk.Gauge.LED_Round

The package Gtk.Gauge.LED_Round provides the widget with two dials:

gauge led round

type Gtk_Gauge_LED_Round_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_LED_Round is
   access all Gtk_Gauge_LED_Round_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget        : out Gtk_Gauge_LED_Round;
             On_Color      : Gdk_Color := RGB (0.0, 1.0, 0.0);
             Off_Color     : Gdk_Color := RGB (0.5, 0.5, 0.5);
             Border_Shadow : Gtk_Shadow_Type := Shadow_In
          );

This procedure creates a round LED widget. The parameters On_Color and Off_Color define the dominating colors of the LED when on and off, correspondingly. Border_Shadow specifies the LED border shape. The LED is created initially off.

procedure Initialize
          (  Widget        : not null access
                             Gtk_Gauge_LED_Round_Record'Class;
             On_Color      : Gdk_Color;
             Off_Color     : Gdk_Color;
             Border_Shadow : Gtk_Shadow_Type
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access Gtk_Gauge_LED_Round_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access Gtk_Gauge_LED_Round_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Off_Color
         (  Widget : not null access Gtk_Gauge_LED_Round_Record
         )  return Gdk_Color;

This function returns the color used when the LED is off.

function Get_On_Color
         (  Widget : not null access Gtk_Gauge_LED_Round_Record
         )  return Gdk_Color;

This function returns the color used when the LED is on.

procedure Set_Colors
          (  Widget    : not null access Gtk_Gauge_LED_Round_Record;
             On_Color  : Gdk_Color;
             Off_Color : Gdk_Color
          );

This procedure changes LED colors. This is a task-safe operation. Note that it does not emit events. In order to force redraw the widget use Queue_Draw.

procedure Set_State
          (  Widget : not null access Gtk_Wall_Clock_Modern_Record;
             State  : Boolean
          );

This procedure changes the LED state. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.6.2. Gtk.Gauge.LED_Rectangular

The package Gtk.Gauge.LED_Rectangular provides the widget with two dials:

gauge led rectangular

type Gtk_Gauge_LED_Rectangular_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Gauge_LED_Rectangular is
   access all Gtk_Gauge_LED_Rectangular_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget        : out Gtk_Gauge_LED_Rectangular;
             On_Color      : Gdk_Color := RGB (0.0, 1.0, 0.0);
             Off_Color     : Gdk_Color := RGB (0.5, 0.5, 0.5);
             Border_Shadow : Gtk_Shadow_Type := Shadow_In
          );

This procedure creates a rectangular LED widget. The parameters On_Color and Off_Color define the dominating colors of the LED when on and off, correspondingly. Border_Shadow specifies the LED border shape. The LED is created initially off.

procedure Initialize
          (  Widget        : not null access
                             Gtk_Gauge_LED_Rectangular_Record'Class;
             On_Color      : Gdk_Color;
             Off_Color     : Gdk_Color;
             Border_Shadow : Gtk_Shadow_Type
          );

This procedure must be called from Initialize of any derived widget type.

function Get_Background
         (  Widget : not null access Gtk_Gauge_LED_Rectangular_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Cache
         (  Widget : not null access Gtk_Gauge_LED_Rectangular_Record
         )  return not null access Cache_Layer;

This function returns the widget's caching layer.

function Get_Off_Color
         (  Widget : not null access Gtk_Gauge_LED_Rectangular_Record
         )  return Gdk_Color;

This function returns the color used when the LED is off.

function Get_On_Color
         (  Widget : not null access Gtk_Gauge_LED_Rectangular_Record
         )  return Gdk_Color;

This function returns the color used when the LED is on.

procedure Set_Colors
          (  Widget    : not null access Gtk_Gauge_LED_Rectangular_Record;
             On_Color  : Gdk_Color;
             Off_Color : Gdk_Color
          );

This procedure changes LED colors. This is a task-safe operation. Note that it does not emit events. In order to force redraw the widget use Queue_Draw.

procedure Set_State
          (  Widget : not null access Gtk_Gauge_LED_Rectangular_Record;
             State  : Boolean
          );

This procedure changes the LED state. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.

11.7. Valves

11.7.1. Gtk.Valves.Round_90

The package Gtk.Valve.Round_90 provides a valve position indicator:

valve round 90

type Gtk_Valve_Round_90_Record is
   new
Gtk_Layered_Record with private;
type Gtk_Valve_Round_90 is
   access all
Gtk_Valve_Round_90_Record'Class;

The following operations are provided:

procedure Gtk_New
          (  Widget     : out Gtk_Valve_Round_90;
             Texts      : texts specification;
           [ Delimiter  : Character := ' '; ]
             Adjustment : Gtk_Adjustment := null;
             Sectors    : Positive := 5
          );

These procedures create the widget.

procedure Initialize
          (  Widget : not null access
                    
 Gtk_Valve_Round_90_Record'Class;
             Texts      : texts specification;
           [ Delimiter  : Character; ]
             Adjustment : Gtk_Adjustment;
             Sectors    : Positive
          );

One of these procedures must be called from Initialize of any derived widget type.

function Get_Annotation
         (  Widget : not null access
                     Gtk_Valve_Round_90_Record
         )  return not null access Elliptic_Annotation_Layer;

This function returns the widget's major annotation layer.

function Get_Background
         (  Widget : not null access
                     Gtk_Valve_Round_90_Record
         )  return not null access Elliptic_Background_Layer;

This function returns the widget's background.

function Get_Needle
         (  Widget : not null access
                     Gtk_Gauge_Round_270_Outer_Record
         )  return not null access Disk_Needle_Layer;

This function returns the widget's needle.

procedure Set_Value
          (  Widget : not null access
                      Gtk_Gauge_Round_270_Outer_Record;
             Value  : GDouble
          );

This procedure changes the indicated value. The value can also be changed through the widget's needle or its adjustment. Note that the procedure does not emit events. In order to redraw the widget use Queue_Draw.


[Back][TOC][Next]

12. Oscilloscope

The oscilloscope widget is ready-to-use complete widget implementing a multichannel oscilloscope. The widget is designed to indicate real-time channels sampled asynchronously at the rates possibly sufficiently higher than the rendering rate.

oscilloscope

The oscilloscope supports two sweepers and three amplifiers with or without scales, annotation, graph paper. The amplifiers can function in auto-scale or manual modes. The oscilloscope provides tooltips of the values on mouse hovering as well as visual zooming using the mouse cursor with zooming undo and redo.

12.1. Oscilloscope widget

The package Gtk.Oscilloscope provides the oscilloscope widget.

12.1.1. Channels

The oscilloscope supports multiple channels. Each channel is a waveform, a running graph. The channels are fed with data asynchronously to rendering, which can be done from any task. Each channel belong to a group. Channels are numbered from 1. The enumeration is dense, when a channel is removed, the channels with higher numbers get their numbers decremented by one. The following type is defined for channel numbers in the package Gtk.Oscilloscope:

type Channel_Count is new Natural;
subtype Channel_Number is Channel_Count range 1..Channel_Count'Last;

There are built-in data sources specified by the type Drawing_Measurement_Point defined in the package Gtk.Oscilloscope:

type Drawing_Measurement_Point is (Refresh_Period, Drawing_Time);

The type's values are:

So-called derivation channels use these data sources for informational purposes.

12.1.2. Groups

The channels of the same group share an amplifier. The amplifier controls scaling of the channel data. Scaling can be done either automatically or manually (see Set_Auto_Scaling). Automatic scaling adapts itself to the values of the channels of the group. Groups are numbered from 1. The following type is defined for channel group numbers in the package Gtk.Oscilloscope:

type Group_Count is new Natural;
subtype Group_Number is Group_Count range 1..Group_Count'Last;

The group can be assigned to one or more vertical axis using Set_Group. An axis has only one group assigned or none.

12.1.3. Vertical scales and axes

The oscilloscope has three built-in vertical scales. The package Gtk.Oscilloscope defines the vertical axes enumeration type:

type Amplifier_Type is (Left, Right, Middle);

The type's values are:

An axis can be assigned to a group of channels. It can have an annotation rendering the values of the channels in the group (Set_Values_Axis), a scale (slider) to adjust the axis amplifier state, a graph paper of horizontal lines superimposed the waveforms (Set_Values_Grid). Axis can be switched between groups of channels any time (Set_Group).

12.1.4. Horizontal scales and axes

The oscilloscope has two built-in horizontal time scales. The package Gtk.Oscilloscope defines the horizontal axes enumeration type:

type Sweeper_Type is (Upper, Lower);

The type's values are:

Each horizontal axis has a sweeper associated with it. A channel is assigned to a sweepers upon creation (Add_Channel). The axis can have an annotation rendering the time stamps (Set_Time_Axis), a scale (slider) to adjust the sweeper position, a graph paper of vertical lines superimposed the waveforms (Set_Time_Grid).

12.1.5. The widget type and operations

type Gtk_Oscilloscope_Record (<>) is
   new
Gtk_Widget_Record with private;
type Gtk_Oscilloscope is access all Gtk_Oscilloscope_Record'Class;

The following operations are defined in the package:

function Add_Channel
         (  Widget  : not null access Gtk_Oscilloscope_Record;
          [ Group   : Group_Number;  ]
          [ Color   : Gdk_Color; ]
            Mode    : Interpolation_Mode := Linear;
            Left    : Boolean := False;
            Right   : Boolean := False;
            Name    : String  := "";
            Sweeper : Sweeper_Type := Lower;
            Buffer  : access Gtk_Waveform_Ring_Data_Buffer_Record'Class := null
         )  return Channel_Number;

These functions add a new channel to the oscilloscope. The parameter Group is the group the channel belongs to. When omitted, a new group is created for the channel. The parameter Color is the color used for the channel's waveform. When omitted a color is selected automatically. Mode is the interpolation mode of the waveform. Linear interpolation is used by default.  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. Name is the channel name. When empty the channel name is generated using the channel number. Sweeper specifies the time scale and the sweeper used to with the waveform. The parameter Buffer is the channel data buffer. The channel renders the buffer contents. When Buffer is null, a new buffer is created for the channel. Otherwise the specified buffer is used. The returned value is the channel number, which is used in other operations to identify the channel. Constraint_Error is propagated when Group does not specify an existing channel group or when the maximal number of channels is exceeded.

function Add_Deviation_Channel
         (  Widget   : not null access Gtk_Oscilloscope_Record;
            Group    : Group_Number;
            Color    : Gdk_Color;
            Measured : Drawing_Measurement_Point := Refresh_Period;
            Name     : String := "";
            Sweeper  : Sweeper_Type := Lower
         )  return Channel_Number;

These functions add a new derivation channel to the oscilloscope. The parameters and the result are same as in Add_Channel, except for the parameter Measured which indicates which widget's internal data source to render.

function Add_Group
         (  Widget    : not null access Gtk_Oscilloscope_Record;
            Name      : String := "";
            Amplifier : Gtk_Waveform_Amplifier := null
         )  return Group_Number;

This function creates a new, initially empty, group of channels. The parameter Name is the group's name. When empty, the name is generated out for the group number. The parameter Amplifier specifies the amplifier object to use with the group. If null the amplifier is created automatically. The function returns the number of the created group. Constraint_Error is propagated when there is too many groups. The maximal number of groups is equal to the maximal number of channels.

function Add_Shadow_Channel
         (  Widget  : not null access Gtk_Oscilloscope_Record;
            Channel : Positive;
            Color   : Gdk_Color;
            Name    : String := "";
            Sweeper : Sweeper_Type := Upper
         )  return Channel_Number;

These function add a shadow channel. A shadow channel has the same source and the group as the origin channel specified by the parameter Channel. Other parameters and the result are same as in Add_Channel. Normally the shadow channel has another sweeper, so than both the origin and the source can be superimposed and shifted horizontally relatively each other. When Name is an empty string the name of the shadow channel is the origin name plus " (shadow)". Constraint_Error is propagated when Channel does not specify an existing channel or when the maximal number of channels is exceeded.

procedure Capture_{PDF|SVG}
          (  Widget : not null access Gtk_Oscilloscope_Record;
             File   : UTF8_String
          );

These procedures capture the contents of the oscilloscope into the file in the specified format.

function Create_Annotation
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type
          )  return not null access
                    Graph_Paper_Annotation_Layer'Class;
function Create_Annotation
         (  Widget  : not null access Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return not null access
                   Graph_Paper_Annotation_Layer'Class;

These functions are provide factories to create axis annotation. It can be overridden in order to provide custom axis annotation layer.

procedure Delete_Channel
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number
          );

This procedure deletes a channel. Note that this operation will change the channel numbers greater than Channel. Constraint_Error is propagated when Channel does not specify an existing channel.

procedure Erase_Redo_Stack
          (  Widget : not null access Gtk_Oscilloscope_Record
          );

This procedure erases the contents of the zooming redo buffer.

procedure Erase_Undo_Stack
          (  Widget : not null access Gtk_Oscilloscope_Record
          );

This procedure erases the contents of the zooming undo buffer.

procedure Feed
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
           [ T       : [Ada.Calendar.]Time; ]
             V       : GDouble
          );
procedure
Feed
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             T       : GDouble;
             V       : GDouble
          );

These procedures feed the channel specified by the parameter Channel with data. The parameter T when omitted is the current time, either as Ada.Real_Time.Time or as Ada.Calendar.Time. The procedure can be called asynchronously from a concurrent task. Note though that there must be only one task feeding the channel at the time. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Amplifier
         (  Widget    : not null access Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return not null access
                   Gtk_Waveform_Amplifier_Record'Class;
function
Get_Amplifier
         (  Widget  : not null access Gtk_Oscilloscope_Record;
            Channel : Positive
         )  return not null access
                   Gtk_Waveform_Amplifier_Record'Class;
function Get_Amplifier
         (  Widget : not null access Gtk_Oscilloscope_Record;
            Group  : Group_Number
         )  return not null access
                   Gtk_Waveform_Amplifier_Record'Class;
 

These functions return the amplifier of the channel group associated with the vertical axis specified by the parameter Amplifier, or by the channel specified by the parameter Channel. The amplifier can be directly requested by the group number (the parameter Group). Constraint_Error is propagated when no group is associated with Amplifier, or when Channel does not specify an existing channel, or when Group does not specify an existing group.

function Get_Auto_Scaling
         (  Widget    : not null access constant Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Boolean;
function
Get_Auto_Scaling
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record;
            Group  : Group_Number
         )  return Boolean;

These function return current auto-scaling more of the amplifier of the channel group associated with the vertical axis specified by the parameter Amplifier, or directly by the group number  (the parameter Group). When auto-scaling is on the channels of the group as scaled to fit the widget. Constraint_Error is propagated when no group is associated with Amplifier, or when Group does not specify an existing group.

function Get_Box
         (  Widget : not null access constant
                   
 Gtk_Oscilloscope_Record
         )  return Cairo_Box;

This function returns the box where waveforms are drawn. The box coordinates are relative to the widget. The box does not include the space occupied by the scales.

function Get_Buffer
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return not null access
                   Gtk_Waveform_Ring_Data_Buffer_Record'Class;

This function returns the channel's data buffer. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Channel_List
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Gtk_List_Store;

This function returns the list store containing one row for each channel. The store has the following columns containing:

The list store shall not be modified directly.

function Get_Color
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Gdk_Color;

This function returns the channel's color. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Default_Face
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Pango_Cairo_Font;

This function gets the face of the font to use by default when an annotation is added to an axis.

function Get_Enabled_Dropdown_Items
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Dropdown_Items;

This returns the menu item enabled to show in the drop-down menu. The items list is an or-combination of Dropdown_Items constants.

function Get_From
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type := Lower
         )  return [Ada.Calendar.]Time;

These functions return the first time of the sweeper specified by the parameter Sweeper. The result is either Ada.Real_Time.Time or Ada.Calendar.Time.

function Get_Frozen
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type := Lower
         )  return Boolean;

This function returns the state of the sweeper specified by the parameter Sweeper. When the sweeper is frozen the waveforms associated with the sweeper do not move.

procedure Get_Grid_Colors
          (  Widget      : not null access constant
                           Gtk_Oscilloscope_Record;
             Major_Color : out Gdk_Color;
             Minor_Color : out Gdk_Color
          );

This procedure returns the colors of the lines corresponding to the major and minor ticks of the scale when the graph paper is shown.

function Get_Group
         (  Widget    : not null access constant
                        Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Group_Number;
function Get_Group
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Group_Number;

These functions return the number of the group associated with the vertical axis specified by the parameter Amplifier or the group of a channel specified by its number Channel. Constraint_Error is propagated when no group is associated with Amplifier, or when Channel does not specify an existing channel.

function Get_Group_List
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Gtk_List_Store;

This function returns the list store of the widget's groups. It has one row per group. The single column of the store has the type GType_String and contains the group name. The list store shall not be modified directly. A possible use of the store is a combo box widget.

function Get_Groups_Number
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Group_Count;

This function returns the number of groups.

function Get_Interpolation_Mode
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Interpolation_Mode;

This function returns the interpolation mode of the channel. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Left_Extrapolation_Mode
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Boolean;

This function returns true if the waveform extrapolates data left of the first sampled value. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Manual_Sweep
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
         )  return Boolean;

This function returns true if the user can freeze/release the widget sweeper using the dropdown menu.

function Get_Name
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return String;

This function returns the channel name. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Name
         (  Widget : not null access constant
                   
 Gtk_Oscilloscope_Record;
            Group  : Group_Number
         )  return String;

This function returns the group name. Constraint_Error is propagated when Group does not specify an existing group.

function Get_Offset
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Duration;

This function returns the delay before the values of the channels associated with Sweeper appear at the oscilloscope's right margin.

function Get_Page_Span
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Duration;

This function returns the duration between the oscilloscope's right and left margin for the scale indicated by the parameter Sweeper.

function Get_Redo_Stub
         (  Widget : not null access Gtk_Oscilloscope_Record;
            Depth  : Positive := 1
         )  return Boolean;

This function returns the name of a stub on the redo stack. The topmost stub has the depth 1. End_Error is propagated when there is no such stub.

function Get_Release_To_Latest
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record
         )  return Boolean;

This function returns true the sweeper when released by the user from frozen state is also moved to the latest time. By default the sweeper position is not changed (the function returns false). See also Set_Release_To_Latest.

function Get_Right_Extrapolation_Mode
         (  Widget  : not null access constant
                      Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Boolean;

This function returns true if the waveform extrapolates data right of the last sampled value. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Selection_Mode
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Selection_Action;

This function returns the currently used action on selection of a rectangular area in the oscilloscope,

function Get_Snapshot_File
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return UTF8_String;

This function returns the name of the file used to store the snapshot of the oscilloscope's contents when the user chooses the corresponding menu item. When the file is written snapshot-captured is emitted and the handler has an opportunity to change the file name for the following snapshot using Set_Snapshot_File.

function Get_Snapshot_Format
         (  Widget : not null access constant
                     Gtk_Oscilloscope_Record
         )  return Snapshot_Format;

This function returns the format used for the snapshot files. The format is set using the procedure Set_Snapshot_File.

function Get_Superscript
         (  Widget : not null access Gtk_Oscilloscope_Record
         )  return Boolean;

This function returns true if superscripts are allowed when formatting values of the axis. See Set_Superscript.

function Get_Sweeper
         (  Widget  : not null access Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return not null access Gtk_Waveform_Sweeper_Record'Class;

This function returns the sweeper object of the scale specified by the parameter Sweeper.

function Get_Sweeper
         (  Widget  : not null access constant
                     
Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Sweeper_Type;

This function returns the time scale used to with the channel. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_Time
         (  Widget  : not null access constant
                     
Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type;
          [ X       : GInt ]
         )  return Time;

These functions return the time, at the scale specified by the parameter Sweeper, corresponding to the horizontal coordinate X in the widget coordinated. When the parameter X is omitted it is the time at the right margin of the widget.

function Get_Time_Axis
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Boolean;

This function returns the visibility status of the time axis specified by the parameter Sweeper. When the axis is visible, the result is true.

function Get_Time_Axis_Annotation
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return access Graph_Paper_Annotation_Layer'Class;

This functions returns the annotation of the axis specified by the parameter Sweeper. The result is null when no annotation is used.

function Get_Time_Axis_Height
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Natural;

This functions returns height of the time axis specified by the parameter Sweeper, when the axis is visible.

function Get_Time_Grid
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Boolean;

This function returns the visibility status of the time scale grid, for the scale specified by the parameter Sweeper. The grid is a set of vertical lines drawn the scale's ticks. When the grid is visible, the result is true.

function Get_Time_Scale
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Boolean;

This function returns the visibility status of the time scale specified by the parameter Sweeper. See Set_Time_Scale.

function Get_Time_Text_Angle
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return GDouble;

This function returns the angle between the x-axis of the cairo coordinates and the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Color
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Gdk_Color;

This function returns the color of the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Face
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Pango_Cairo_Font;

This function returns the font face used for the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Height
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return GDouble;

This function returns the height of the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Horizontal_Alignment
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Alignment;

This function returns the horizontal alignment of the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Stretch
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return GDouble;

This function returns the stretch of the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Text_Vertical_Alignment
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type
         )  return Vertical_Alignment;

This function returns the vertical alignment of the texts at the time scale specified by the parameter Sweeper.

function Get_Time_Tooltip
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record
         )  return Boolean;

The tooltip when the mouse cursor hovers a waveform indicates the corresponding channel value under the cursor. When the value is accompanied by the corresponding time, this function returns true.

function Get_Time_Tooltip_Suffix
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return UTF8_String;

This function returns the suffix added to the time value shown in the tooltip when the mouse is hovering over a channel. Constraint_Error is propagated when there is no channel with the number Channel. The suffix text is set by the procedure Set_Time_Tooltip_Suffix.

function Get_To
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type := Lower
         )  return [Ada.Calendar.]Time;

These functions return the last time of the sweeper specified by the parameter Sweeper. The result is either Ada.Real_Time.Time or Ada.Calendar.Time.

function Get_Tooltip_Annotation
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return UTF8_String;

This function returns the text introducing the channel specified by Channel in the tooltip text shown when the mouse hovers over the channel curve. Constraint_Error is propagated when there is no channel with the number Channel. The text is set by the procedure Set_Tooltip_Annotation.

function Get_Undo_Stub
         (  Widget : not null access Gtk_Oscilloscope_Record;
            Depth  : Positive := 1
         )  return Boolean;

This function returns the name of a stub on the undo stack. The topmost stub has the depth 1. End_Error is propagated when there is no such stub. Subs are pushed using the procedure Push_Stub.

function Get_Value
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type;
            Y         : GInt
         )  return GDouble;
function Get_Value
         (  Widget : not null access constant
                    
Gtk_Oscilloscope_Record;
            Group  : Group_Number;
            Y      : GInt
         )  return GDouble;

These functions return the value on the vertical axis specified by the parameter Amplifier or Group, corresponding to the vertical coordinate Y (relative to the widget). Constraint_Error is propagated when no group is associated with Amplifier, or when Group does not specify an existing group.

function Get_Values_Axis
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Boolean;

This functions returns true if the axis specified by the parameter Amplifier is visible.

function Get_Values_Axis_Annotation
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return access Graph_Paper_Annotation_Layer'Class;

This functions returns the annotation of the axis specified by the parameter Amplifier. The result is null when no annotation is used.

function Get_Values_Axis_Width
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Natural;

This functions returns width of the axis specified by the parameter Amplifier, when the axis is visible.

function Get_Values_Horizontal_Alignment
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Alignment;

This functions returns the horizontal alignment of the texts shown at the vertical scale specified by the parameter Amplifier.

function Get_Values_Grid
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Boolean;

This functions returns true if the vertical scale specified by the parameter Amplifier has grid visible. The grid is a set of horizontal lines drawn at the vertical scale ticks.

function Get_Values_Scale
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Boolean;

This function returns the visibility status of the time scale specified by the parameter Amplifier. See Set_Values_Scale.

function Get_Values_Text_Angle
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return GDouble;

This function returns the angle between the x-axis of the cairo coordinates and the texts at the axis specified by the parameter Amplifier.

function Get_Values_Text_Color
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Gdk_Color;

This function returns the color of the texts at the axis specified by the parameter Amplifier.

function Get_Values_Text_Face
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Pango_Cairo_Font;

This function returns the font face used for the texts at the axis specified by the parameter Amplifier.

function Get_Values_Text_Height
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return GDouble;

This function returns the height of the texts at the axis specified by the parameter Amplifier.

function Get_Values_Text_Stretch
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return GDouble;

This function returns the stretch of the texts at the axis specified by the parameter Amplifier.

function Get_Values_Tooltip_Suffix
         (  Widget  : not null access constant
                     
Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return UTF8_String;

This function returns the suffix added to the value shown in the tooltip when the mouse is hovering over a channel. Constraint_Error is propagated when there is no channel with the number Channel. The suffix text is set by the procedure Set_Values_Tooltip_Suffix.

function Get_Waveform
         (  Widget  : not null access constant
                     
Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return not null access Waveform_Layer;

This function returns the waveform of Channel. Constraint_Error is propagated when Channel does not specify an existing channel.

function Get_X
         (  Widget  : not null access constant
                    
 Gtk_Oscilloscope_Record;
            Sweeper : Sweeper_Type;
            Stamp   : [Ada.Calendar.]Time;
            Crop    : Boolean := False
         )  return GInt;

These functions return the horizontal coordinate corresponding to the time Stamp according to the axis specified by the parameter Sweeper. The time can be either Ada.Real_Time.Time or Ada.Calendar.Time. The result is relative to the widget coordinates. When Crop is true, the result is cropped to the waveform's box. When Crop is false an the result is not in the waveform's box Layout_Error is propagated.

function Get_Y
         (  Widget    : not null access constant
                      
 Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type;
            Value     : GDouble;
            Crop      : Boolean := False
         )  return GInt;
function Get_Y
         (  Widget : not null access constant
                   
 Gtk_Oscilloscope_Record;
            Group  : Group_Number;
            Value  : GDouble;
            Crop   : Boolean := False
         )  return GInt;

These functions return the vertical coordinate corresponding to Value at the vertical axis specified by the parameter Amplifier or Group. The result is relative to the widget coordinates. When Crop is true, the result is cropped to the waveform's box. When Crop is false an the result is not in the waveform's box Layout_Error is propagated. Constraint_Error is propagated when no group is associated with Amplifier, or when Group does not specify an existing group.

procedure Gtk_New
          (  Widget         : out Gtk_Oscilloscope;
             Lower_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class := null;
             Upper_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class := null;
             Refresh_Engine : not null access Layered_Refresh_Engine'Class;
             Background     : Gdk_Color := RGB (1.0, 1.0, 1.0);
             Buffer_Size    : Positive  := 1024 * 60;
             Max_Channels   : Channel_Number := 64
          );
procedure Gtk_New
          (  Widget         : out Gtk_Oscilloscope;
             Lower_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class := null;
             Upper_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class := null;
             Refresh_Period : Duration  := 0.02;
             Background     : Gdk_Color := RGB (1.0, 1.0, 1.0);
             Buffer_Size    : Positive  := 1024 * 60;
             Max_Channels   : Channel_Number := 64
          );

These functions create a new widget. The result is returned through the parameter Widget. The parameters Lower_Sweeper and Upper_Sweeper are the waveform sweepers used for the lower and upper time axis correspondingly. When a parameter is null a new sweeper is created. Several oscilloscopes can share a sweeper. For example, they can be stacked up being synchronously swept. The parameter  Refresh_Engine specifies the refresh engine updating the widget. Alternatively the parameter Refresh_Period is the update period of the engine newly created for the widget. The parameter Background is the color of the box where the waveforms are drawn. The parameter Buffer_Size is the default size of the source data buffers (in items) used for the channels when created implicitly (see Add_Channel). The parameter Max_Channels specifies the maximal number of channels.

function Has_Group
         (  Widget    : not null access constant Gtk_Oscilloscope_Record;
            Amplifier : Amplifier_Type
         )  return Boolean;

This function returns true if Amplifier has a group of channels assigned to it.

procedure Initialize
          (  Widget         : not null access Gtk_Oscilloscope_Record'Class;
             Lower_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class;
             Upper_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class;
             Refresh_Engine : not null access Layered_Refresh_Engine'Class;
             Background     : Gdk_Color;
             Buffer_Size    : Positive
          );
procedure Initialize
          (  Widget         : not null access Gtk_Oscilloscope_Record'Class;
             Lower_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class;
             Upper_Sweeper  : access Gtk_Waveform_Sweeper_Record'Class;
             Refresh_Period : Duration;
             Background     : Gdk_Color;
             Buffer_Size    : Positive
          );

These procedures initialize a newly allocated object. One of them shall be called from the Initialize of a derived type in the course of the widget initialization.

function Is_Visible
         (  Widget  : not null access constant Gtk_Oscilloscope_Record;
            Channel : Channel_Number
         )  return Boolean;

This function returns true if Channel refers to a visible channel.

procedure Move_Channel
          (  Widget     : not null access Gtk_Oscilloscope_Record;
             Old_Number : Channel_Number;
             New_Number : Channel_Number
          );

This procedure changes the channel number Old_Number to New_Number. This operation also changes the numbers of channels between Old_Number and New_Number. Constraint_Error is propagated when either number does not specify an existing channel.

procedure On_Selection
          (  Widget   : not null access Gtk_Oscilloscope_Record;
             Selected : Cairo_Box
          )  is null;

This procedure is called upon selection of a rectangular area in the oscilloscope when the selection mode is set on User_Action. The parameter Selected specifies the selected rectangle. The default implementation does nothing. It can overridden to provide user-defined behavior on selection.

procedure Push_Stub
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Name   : UTF8_String
          );

The procedure pushes a stub with the name Name onto the the undo stack. All actions after the stub can be reverted using a pattern that matches Name as the parameter Till in Undo.

procedure Push_Undo
          (  Widget : not null access Gtk_Oscilloscope_Record;
             State  : Zooming_State := Values_Zooming or Time_Zooming
          );

The procedure pushes onto the the undo stack the data needed to restore the current zooming state as specified by the parameter State. The state to save is described by the type:

type Zooming_State is mod 2**2;
Values_Zooming : constant Zooming_State := 2**0;
Time_Zooming   : constant Zooming_State := 2**1;

The values of the type are combined using or. When used to keep on track of user actions, the redo stack is also erased using Erase_Redo_Stack.

procedure Redo
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Till   : UTF8_String := "";
             Stub   : UTF8_String := ""
          );

When Till is empty the procedure repeats one reverted user action of zooming stored on the top of the redo stack. The top of the redo stack is popped. The information to revert this action is pushed onto the undo stack. When Till is not empty the procedure repeats all actions until a stub action with the name matched by the wildcard pattern contained by Till. The parameter Stub is the name of a stub to push onto the undo stack when Till is not empty. This allows to undo all actions re-done by the operation by specifying the name of this stub.

procedure Set_Auto_Scaling
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Auto      : Boolean
          );
procedure Set_Auto_Scaling
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Group  : Group_Number;
             Auto   : Boolean
          );

This procedure set the automatic scaling for the group specified either by the axis Amplifier assigned to it or directly by the number Group. Constraint_Error is propagated when Group does not specify an existing group, or Amplifier has no group assigned.

procedure Set_Default_Face
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Face   : Pango_Cairo_Font
          );

This procedure sets the face of the font to use by default when an annotation is added to an axis.

procedure Set_Enabled_Dropdown_Items
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Items  : Dropdown_Items
          );

This procedure sets menu item enabled to show in the drop-down menu. The items list is an or-combination of Dropdown_Items constants.

procedure Set_Extrapolation_Mode
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Left    : Boolean;
             Right   : Boolean
          );

This procedure sets the extrapolation mode of the channel Channel. The parameters Left and Right determine the extrapolation to the left and to the right correspondingly. Constraint_Error is propagated when Channel does not specify a channel.

procedure Set_Frequency
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Frames  : GDouble
          );

This procedure changes the sweeping frequency in frames (pages) per second. The parameter Sweeper is the axis of which sweeper has to be altered. It is alternative to Set_Page_Span, which explicitly sets the page span.

procedure Set_Frozen
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Frozen  : Boolean
          );

This procedure changes the freezing state of the sweeper associated with the axis Sweeper. When frozen the axis maintains the times at the left and right margins of the waveform box. so that the waveform stand still.

procedure Set_Grid_Colors
          (  Widget      : not null access Gtk_Oscilloscope_Record;
             Major_Color : Gdk_Color;
             Minor_Color : Gdk_Color
          );

This procedure sets the colors of the lines corresponding to the major and minor ticks of the scale when the graph paper is shown.

procedure Set_Group
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Group     : Group_Number
          );

This procedure assigns the group Group to the Amplifier axis. An axis can be assigned to only one group. The previously assigned group is detached from the axis. Constraint_Error is propagated when Group does not specify an existing group.

procedure Set_Interpolation_Mode
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Mode    : Interpolation_Mode
          );

This procedure changes the interpolation mode of the channel Channel to Mode. Constraint_Error is propagated when Channel does not specify an existing channel.

procedure Set_Manual_Sweep
          (  Widget  : not null access constant Gtk_Oscilloscope_Record;
             Enable  : Boolean
          );

This procedure enables (when Enable is true) or disables (otherwise) the menu items allowing the user to freeze / release the oscilloscope's sweeper.

procedure Set_Page_Span
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Sweeper   : Sweeper_Type;
             Page_Span : Duration
          );

This procedure changes the duration of the page to Page_Span. The parameter Sweeper is the axis of which sweeper has to be altered.

procedure Set_Preferred_Method
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Method : Waveform_Drawing_Method
          );

This procedure sets the preferred drawing method for the waveforms of Widget.

procedure Set_Release_To_Latest
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Enable : Boolean
          );

This procedure specifies what happens when a frozen sweeper is released by the user. When Enable is false, which is the default, the sweeper position is not changed. When Enable is true the sweeper is moved to the latest time. The current behavior is returned by Get_Release_To_Latest.

procedure Set_Selection_Mode
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Action : Selection_Action
          );

This procedure changes the oscilloscope's behavior when a rectangular area is selected using the right mouse button. The parameter Action specifies the selection action to undertake.

procedure Set_Snapshot_File
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Format : Snapshot_Format := No_Snapshot;
             Name   : String := ""
          );

This procedure sets the format and the name of the file to store oscilloscope's contents when the user chooses the corresponding menu item. The parameter Format has the type:

type Snapshot_Format is (No_Snapshot, PDF_Snapshot, SVG_Snapshot);

When No_Snapshot is selected or Name is empty, no menu item appears.

procedure Set_Superscript
          (  Widget      : not null access Gtk_Oscilloscope_Record;
             Superscript : Boolean
          );

This procedure changes usage of superscript when formatting values of the axis specified by the parameter Amplifier. When true values are formatted using superscript digits, e.g. as 123·106. Otherwise they are formatted as 123E6.

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

This procedure set the time to Stamp at the right margin of the waveform's box for the axis specified by the parameter Sweeper. The time can be specified  either as Ada.Real_Time.Time or Ada.Calendar.Time. It usually makes sense only when the axis is frozen (see Set_Frozen), for manual scrolling the waveforms attached to it.

procedure Set_Time_Axis
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Visible : Boolean;
             As_Time : Boolean := True
          );

This procedure changes the visibility status of the axis specified by the parameter Sweeper. The axis contains the annotation texts drawn at the axis ticks. The texts represent in human-readable form the time corresponding to the scale ticks when As_Time is true. Otherwise, it is rendered as a plain number. When all visible sweepers are rendered as numbers, the right button click pop-up menu does not show the Latest data item.

procedure Set_Time_Axis_Height
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Height  : Natural
          );

This procedure sets the height of the time axis specified by the parameter Sweeper when the axis is visible.

procedure Set_Time_Grid
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Visible : Boolean
          );

This procedure changes the visibility status of the grid for the axis specified by the parameter Sweeper. The grid is a set of vertical lines drawn at the axis ticks through the waveform's box.

procedure Set_Time_Scale
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Visible : Boolean
          );

This procedure changes the visibility status of the scale at the axis specified by the parameter Sweeper. The scale is used to manually move the oscilloscope's contents connected to the axis. When set the invisible, the scale is never shown. When set visible it is shown when the corresponding sweeper is frozen (see Set_Frozen). In running mode scale is not shown.

procedure Set_Time_Text_Alignment
          (  Widget     : not null access Gtk_Oscilloscope_Record;
             Sweeper    : Sweeper_Type;
             Horizontal : Alignment;
             Vertical   : Vertical_Alignment
          );

This procedure changes the horizontal and vertical alignment of the texts drawn at the scale specified by the parameter Sweeper, when the scale is visible.

procedure Set_Time_Text_Font
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Face    : Pango_Cairo_Font;
             Height  : GDouble;
             Stretch : GDouble   := 1.0;
             Color   : Gdk_Color := RGB (0.0, 0.0, 0.0);
             Angle   : GDouble   := 0.0
          );

This procedure changes parameters used for drawing the texts at the scale specified by the parameter Sweeper. The parameter Face is the font face. Height is the font height. Stretch is the text stretch. Color is the color. Angle is the angle between the annotation text and the cairo's x-coordinate.

procedure Set_Time_Tooltip
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Visible : Boolean
          );

This procedure changes the behaviour of the widget tooltip. When Visible is true, the tooltip contains the time specification for the values under the mouse cursor. When Visible is false, only the value is indicated.

procedure Set_Time_Tooltip_Suffix
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Suffix  : UTF8_String
          );

This procedure sets the suffix added to the channel time value shown in the tooltip when the mouse is hovering over the channel curve. Constraint_Error is propagated when there is no channel with the number Channel. The current suffix text is returned by the function Get_Time_Tooltip_Suffix.

procedure Set_Tooltip_Annotation
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Text    : UTF8_String
          );

This procedure sets the text introducing the channel specified by Channel in the tooltip text shown when the mouse hovers over the channel curve. Constraint_Error is propagated when there is no channel with the number Channel. The current text is returned by Get_Tooltip_Annotation.

procedure Set_Values_Alignment
          (  Widget     : not null access Gtk_Oscilloscope_Record;
             Amplifier  : Amplifier_Type;
             Horizontal : Alignment;
             Vertical   : Vertical_Alignment
          );

This procedure changes the horizontal and vertical alignments of the texts at the vertical scale specified by the parameter Amplifier.

procedure Set_Values_Axis
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Visible   : Boolean
          );

This procedure changes the visibility status of the axis specified by the parameter Amplifier. The axis contains the annotation texts drawn at the axis ticks. The texts represent in human-readable form the time corresponding to the scale ticks. Constraint_Error is propagated when Amplifier has no channel group assigned to it.

procedure Set_Values_Axis_Height
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Sweeper : Sweeper_Type;
             Height  : Natural
          );

This procedure sets the height of the horizontal axis specified by the parameter Sweeper, when the axis is visible. The axis height influences the waveform's box, computed as the widget width minus the height of visible top and/or bottom axes.

procedure Set_Values_Axis_Width
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Width     : Natural
          );

This procedure sets the width of the vertical axis specified by the parameter Amplifier, when the axis is visible. The axis width influences the waveform's box, computed as the widget width minus the widths of visible left and/or right axes.

procedure Set_Values_Grid
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Visible   : Boolean
          );

This procedure changes the visibility status of the grid for the axis specified by the parameter Amplifier. The grid is a set of horizontal lines drawn at the axis ticks through the waveform's box. Constraint_Error is propagated when no group is assigned to the axis.

procedure Set_Values_Scale
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Visible   : Boolean
          );

This procedure changes the visibility status of the scale at the axis specified by the parameter Amplifier. The scale is used to manually move the oscilloscope's contents connected to the axis. When set the invisible, the scale is never shown. When set visible it is shown when the corresponding amplifier is in manual scaling mode. In the automatic mode the scale is not shown (see Set_Auto_Scaling).

procedure Set_Values_Text_Font
          (  Widget    : not null access Gtk_Oscilloscope_Record;
             Amplifier : Amplifier_Type;
             Face      : Pango_Cairo_Font;
             Height    : GDouble;
             Stretch   : GDouble   := 1.0;
             Color     : Gdk_Color := RGB (0.0, 0.0, 0.0);
             Angle     : GDouble   := 0.0
          );

This procedure changes parameters used for drawing the texts at the vertical axis specified by the parameter Amplifier. The parameter Face is the font face. Height is the font height. Stretch is the text stretch. Color is the color. Angle is the angle between the annotation text and the cairo's x-coordinate.

procedure Set_Values_Tooltip_Suffix
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Suffix  : UTF8_String
          );

This procedure sets the suffix added to the channel value shown in the tooltip when the mouse is hovering over the channel curve. Constraint_Error is propagated when there is no channel with the number Channel. The current suffix text is returned by the function Get_Values_Tooltip_Suffix.

procedure Set_Visible
          (  Widget  : not null access Gtk_Oscilloscope_Record;
             Channel : Channel_Number;
             Visible : Boolean
          );

This procedure changes the channel visibility status. When the channel is invisible, its waveform is not drawn. Constraint_Error is propagated when Channel does not specify an existing channel.

procedure Undo
          (  Widget : not null access Gtk_Oscilloscope_Record;
             Till   : UTF8_String := "";
             Stub   : UTF8_String := ""
          );

When Till is empty the procedure reverts one user action caused a change of zooming stored on the top of the undo stack. The top of the undo stack is popped. The information to revert this action is pushed onto the redo stack. When Till is not empty the procedure reverts all actions until a stub action with the name matched by the wildcard pattern contained by Till. A stub pushed onto the undo stack using the procedure Push_Stub. The parameter Stub is the name of a stub to push onto the redo stack when Till is not empty. This allows to redo all actions undone by the operation by specifying the name of this stub.

12.1.6. Signals

The oscilloscope widget emits the following signals:

Signal Parameters When emitted
1 2 3
autoscaling-changed Group number
GUInt
    The scaling mode of the group's amplifier has been changed
channel-added Channel number
GUInt
    The channel has been added
channel-deleted Channel number
GUInt
    The channel has been deleted
extrapolation-changed Channel number
GUInt
    The channel extrapolation mode has been changed
freezing-changed Sweeper (Sweeper_Type'Pos)
GUInt
    Freezing mode of the sweeper has been changed
group-changed Amplifier (Amplifier_Type'Pos)
GUInt
    The axis' group has been changed
interpolation-changed Channel number
GUInt
    The channel interpolation mode has been changed
offset-changed Sweeper (Sweeper_Type'Pos)
GUInt
    The offset of the sweeper has been changed
position-changed Sweeper (Sweeper_Type'Pos)
GUInt
Time at the cursor
GType_Double
Duration of the selection box
GType_Double
An operation of getting values was chosen in the drop-down menu when a rectangular area was selected. The width is measured in seconds. The values or values differences are stored in the Get_Channel_List store.
raster-mode-changed Group number
GUInt
    Raster mode of the group's amplifier has been changed
snapshot-captured String     The name of the snapshot file, successfully written
visibility-toggled Channel number
GUInt
    The visibility of the channel has been toggled
x-axis-toggled Sweeper (Sweeper_Type'Pos)
GUInt
    The horizontal axis visibility has been toggled
x-grid-toggled Sweeper (Sweeper_Type'Pos)
GUInt
    The visibility of the grid has been toggled
y-axis-toggled Amplifier (Amplifier_Type'Pos)
GUInt
    The vertical axis visibility has been toggled
y-grid-toggled Amplifier (Amplifier_Type'Pos)
GUInt
    The visibility of the grid has been toggled

12.1.7. Selection and drop-down menu

The widget supports selection and various operations on the selected area of the widget. The selection starts when the left mouse button is pressed. Moving the mouse causes a ribbon box to appear. When the button is released the drop-down menu provides the list of operations:

oscilloscope selection

The oscilloscope's behavior can be altered using Set_Selection_Mode. The selection action is one of the enumeration type defined in the package:

type Selection_Action is
     (  Interactive,
        Zoom_In,
        Zoom_In_Time,
        Zoom_In_Values,
        Zoom_Out,
        Zoom_Out_Time,
        Zoom_Out_Values,
        Copy_Values,
        Copy_Differences,
        Copy_Range,
        User_Action,
        None
     );

The right mouse button drop-down menu provides the following items enumerated by the type Dropdown_Items:

type Dropdown_Items is mod 2**6;
Grid_Item          : constant Dropdown_Items := 2**0;
Hold_Release_Item  : constant Dropdown_Items := 2**1;
Interpolation_Item : constant Dropdown_Items := 2**2;
Latest_Data_Item   : constant Dropdown_Items := 2**3;
Snapshot_Item      : constant Dropdown_Items := 2**4;
Undo_Redo_Item     : constant Dropdown_Items := 2**5;

The individual items can be enabled or disabled. The following type

12.2. Sweeper panel

oscilloscope sweeper panel

The package Gtk.Oscilloscope.Sweeper_Panel provides a widget which can be used to control horizontal axis of the oscilloscope widget:

type Gtk_Oscilloscope_Sweeper_Panel_Record is
   new
Gtk_Table_Record with private;
type Gtk_Oscilloscope_Sweeper_Panel is
   access all
Gtk_Oscilloscope_Sweeper_Panel_Record'Class;

The following operations are defined in the package:

procedure Gtk_New
          (  Widget       : out Gtk_Oscilloscope_Sweeper_Panel;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class;
             Sweeper      : Sweeper_Type := Lower;
             Show_Buttons : Boolean := True;
             Flat         : Boolean := False
          );

This procedure creates a new widget. The parameter Oscilloscope is the oscilloscope widget. Sweeper indicates the time axis the panel will control. When Show_Buttons is false then buttons controlling the visibility of axis and graph paper are not shown. When Flat is true the panel is in a single row.

procedure Initialize
          (  Widget : not null access
                      Gtk_Oscilloscope_Sweeper_Panel_Record'Class;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class;
             Sweeper      : Sweeper_Type;
             Show_Buttons : Boolean;
             Flat         : Boolean
          );

This procedure must be called from the Initialize of the derived type in order to initialize the parent.

12.3. Amplifier panel

oscilloscope amplifier panel

The package Gtk.Oscilloscope.Amplifier_Panel provides a widget which can be used to control horizontal axis of the oscilloscope widget:

type Gtk_Oscilloscope_Amplifier_Panel_Record is
   new
Gtk_Table_Record with private;
type Gtk_Oscilloscope_Amplifier_Panel is
   access all
Gtk_Oscilloscope_Amplifier_Panel_Record'Class;

The following operations are defined in the package:

function Get_Page_Label
        (  Widget : not null access
                    Gtk_Oscilloscope_Amplifier_Panel_Record
        )  return not null access Gtk_Label_Record'Class;;

This function returns the label widget which can be used to place the measurement unit of the controlled axis.

procedure Gtk_New
          (  Widget       : out Gtk_Oscilloscope_Amplifier_Panel;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class;
             Amplifier    : Amplifier_Type := Left
          );

This procedure creates a new widget. The parameter Oscilloscope is the oscilloscope widget. Amplieifer indicates the values axis the panel will control.

procedure Initialize
          (  Widget : not null access
                      Gtk_Oscilloscope_Amplifier_Panel_Record'Class;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class;
             Amplifier    : Amplifier_Type
          );

This procedure must be called from the Initialize of the derived type in order to initialize the parent.

12.4. Channels panel

oscilloscope channels panel

The package Gtk.Oscilloscope.Channels_Panel provides a widget listing the oscilloscope channels: The widget is a tree view with the columns indicating:

The widget has the right button menu:

oscilloscope channels panel menu

The menu allows deletion of channels and changing their order and colors. The widget type is declared as follows:

type Gtk_Oscilloscope_Channels_Panel_Record is
   new
Gtk_Tree_View_Record with private;
type Gtk_Oscilloscope_Channels_Panel is
   access all
Gtk_Oscilloscope_Channels_Panel_Record'Class;

The following operations are defined in the package:

procedure Gtk_New
          (  Widget       : out Gtk_Oscilloscope_Channels_Panel;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class
          );

This procedure creates a new widget. The parameter Oscilloscope is the oscilloscope widget.

procedure Initialize
          (  Widget : not null access
                      Gtk_Oscilloscope_Channels_Panel_Record'Class;
             Oscilloscope : not null access Gtk_Oscilloscope_Record'Class
          );

This procedure must be called from the Initialize of the derived type in order to initialize the parent.

12.5. Plotting data with the oscilloscope

Though the primary usage of the oscilloscope is rendering on-line data in real-time, it can also be used for the purpose of simple plotting. In this case sweepers are set frozen and the channel data are written once and never updated. The horizontal axis can be set into a mode when it renders its values as plain number rather than as time stamps.

The following code sample represents a complete program plotting the function ex·sin7x.

File oscilloscope_plotter.adb:
with Ada.Exceptions;        use Ada.Exceptions;
with Ada.Text_IO;           use Ada.Text_IO;
with Glib;                  use Glib;
with
Gtk.Missed;            use Gtk.Missed;
with Gdk.Event;             use Gdk.Event;
with Gtk.Layered.Waveform;  use Gtk.Layered.Waveform;
with Gtk.Oscilloscope;      use Gtk.Oscilloscope;
with Gtk.Widget;            use Gtk.Widget;
with Gtk.Window;            use Gtk.Window;

with Ada.Numerics.Elementary_Functions;
with Gtk.Main;

procedure Oscilloscope_Plotter is
   Window : Gtk_Window;
begin
   Gtk.Main.Init;
   Gtk.Window.Gtk_New (Window);
   Window.Set_Title ("Test plotting");
   Window.On_Delete_Event (Gtk.Missed.Delete_Event_Handler'Access);
   Window.On_Destroy (Gtk.Missed.Destroy_Handler'Access);

The program begins with standard GTK stuff initializing the main loop, creating a windows, setting its title and connecting the destroy handler that exits the main loop upon termination.

File oscilloscope_plotter.adb (continuation):
   declare
      Curve        : Channel_Number;
      Oscilloscope : Gtk_Oscilloscope;
   begin
      Gtk_New (Oscilloscope);
      Add (Window, Oscilloscope);

Here the oscilloscope widget is created and put into the application's window.

File oscilloscope_plotter.adb (continuation):
      Oscilloscope.Set_Manual_Sweep (False);
      --
      -- Configuring the lower axis
      --

      Oscilloscope.Set_Frozen     (Lower, True);  -- No sweeping
      Oscilloscope.Set_Time_Scale (Lower, False); -- No scale
      Oscilloscope.Set_Time_Grid  (Lower, True);  -- Grid
      Oscilloscope.Set_Time_Axis  (Lower, True, False);
      Oscilloscope.Get_Sweeper (Lower).Configure
      (  Value          => 0.0,
         Lower          => 0.0,
         Upper          => 20.0,
         Step_Increment => 0.1,
         Page_Increment => 5.0,
         Page_Size      => 10.0
      );

Next the lower horizontal axis is configured. A call to Set_Manual_Sweep suppresses the items of the right mouse menu, which would allow the user to hold and release the oscilloscope sweeper, since plotter need not to sweep the waveform. Then a call to Set_Frozen freezes the lower sweeper associated with the axis. The time scale is turned off using Set_Time_Scale, so that the horizontal slider will never appear. The vertical grid corresponding to the lower sweeper is turned on by Set_Time_Grid. Then the time axis of the lower sweeper is shown using Set_Time_Axis. This will render the numbers below the curve. Note the last parameter of the call to Set_Time_Axisfalse instructs to render the time stamps as plain numbers. Finally the lower sweeper is set to indicate the area from 0.0 to 10.0 using the standard call to Configure of Gtk_Adjustment.

File oscilloscope_plotter.adb (continuation):
      --
      -- Adding the channel
      --

      Curve :=
         Add_Channel
         (  Widget  => Oscilloscope,
            Mode    => Gtk.Layered.Linear, -- Linear interpolation
            Color   => RGB (0.0, 0.0, 0.7),
            Sweeper => Lower
         );

Here we add one channel to the oscilloscope using Add_Channel. The channel will show our function. The interpolation mode is set to linear, the color of the curve is set to dark blue. The channel is attached to the lower sweeper. The channel group is created automatically.

File oscilloscope_plotter.adb (continuation):
      --
      -- Configuring the left axis for this channel (and its group)
      --

      Oscilloscope.Set_Group (Left, Oscilloscope.Get_Group (Curve));
      Oscilloscope.Set_Values_Axis  (Left, True);
      Oscilloscope.Set_Values_Scale (Left, False);
      Oscilloscope.Set_Values_Grid  (Left, True);
      Oscilloscope.Set_Values_Axis_Width (Left, 60);

Now, the left axis is configured. First it is attached to the channel's group using Set_Group. Then similarly to the lower axis, it is shown (Set_Values_Axis), its scale (slider) is disabled (Set_Values_Scale), the corresponding horizontal grid is turned on (Set_Values_Grid). Finally the width of the left axis is set to 60 pixels using Set_Values_Axis_Width. This is the space where the values at the axis will be shown. Since the visual width of the annotation numbers is hard to predict, usually Set_Values_Axis_Width need to be attuned in order to achieve an optimal view.

File oscilloscope_plotter.adb (continuation):
      --
      -- Pushing the data into the channel's buffer
      --

      declare
         use Ada.Numerics.Elementary_Functions;
         X : Float := 0.0;
      begin
         loop

            Oscilloscope.Feed
            (  Channel => Curve,
               T => GDouble (X),
               V => GDouble (sin (X * 7.0) * exp (X))
            );
            X := X + 0.001;
            exit when X > 10.0;
         end loop;
      end;
   end;

This part pushes the curve into the channel's buffer. It generates values of ex·sin7x at the interval 0..10 with the step 0.001. The procedure Feed is used to write data points into the channel's buffer. The buffer could also be filled using direct calls to Put on the channel's buffer (see Get_Buffer).

File oscilloscope_plotter.adb (continuation):
   Window.Set_Size_Request (400, 300);
   Show_All (Window);
   Gtk.Main.Main;
exception
   when
Error : others =>
      Put_Line ("Error: " & Exception_Information (Error));
end Oscilloscope_Plotter;

Finally the windows are shown and the main loop entered. The result is indicated on the figure below:

plotter

12.6. Asynchronous plotting

Usually scientific computations take much time which would block the user interface when performed on the context of the main task. The following sample illustrates a typical design when intensive computing is performed asynchronously to the user interface in a separate task.

on-line plotting

The sample uses contributed by Yogeshwarsing Calleecharan code to solve a differential equation of 2nd order describing the frequency of a hydropower generator's rotor as described in "On the dynamics of an hydropower generator subjected to unbalanced magnetic pull: characterisation and analysis", Yogeshwarsing Calleecharan (2010), Luleå University of Technology, Luleå, ISBN13: 978-91-7439-161-9, ISBN10: 9174391615. The sample consists of three files:

File on_line_plotter.adb:
with Ada.Exceptions;        use Ada.Exceptions;
with Ada.Text_IO;           use Ada.Text_IO;
with Gdk.Event;             use Gdk.Event;
with Glib;                  use Glib;
with Gtk.Enums;             use Gtk.Enums;
with Gtk.Box;               use Gtk.Box;
with Gtk.Button;            use Gtk.Button;
with Gtk.Check_Button;      use Gtk.Check_Button;
with Gtk.Toggle_Button;     use Gtk.Toggle_Button;
with Gtk.Dialog;            use Gtk.Dialog;
with Gtk.Frame;             use Gtk.Frame;
with Gtk.GEntry;            use Gtk.GEntry;
with Gtk.Missed;            use Gtk.Missed;
with Gtk.Label;             use Gtk.Label;
with Gtk.Layered.Waveform;  use Gtk.Layered.Waveform;
with Gtk.Oscilloscope;      use Gtk.Oscilloscope;
with Gtk.Progress_Bar;      use Gtk.Progress_Bar;
with Gtk.Table;             use Gtk.Table;
with Gtk.Widget;            use Gtk.Widget;
with Gtk.Window;            use Gtk.Window;

with Ada.Numerics.Elementary_Functions;
with Ada.Unchecked_Conversion;
with Gtk.File_Chooser;
with Gtk.File_Chooser_Dialog;
with Gtk.Main.Router;
with Worker;

procedure On_Line_Plotter is
   Window          : Gtk_Window;
   Calculator      : Worker.Process;
   Start_Button    : Gtk_Button;
   Oscilloscope    : Gtk_Oscilloscope;
   Curve           : Channel_Number;
   Progress        : Gtk_Progress_Bar;
   Start_Frequency : Gtk_Entry;
   Stop_Frequency  : Gtk_Entry;
   Stiffness_Ratio : Gtk_Entry;
   Steps           : Gtk_Entry;
   Autoscale_Check : Gtk_Check_Button;
   Unicode_Check   : Gtk_Check_Button;

The above part declares the main window of the application, the worker task that performs calculation and major widgets.

File on_line_plotter.adb (continuation):
--
-- Delete_Event -- Window closing notification event
--

   function Delete_Event
            (  Widget : access Gtk_Widget_Record'Class;
               Event  : Gdk_Event
            )  return Boolean is
   begin

      Calculator.Stop; -- Stop the computation process
      return False;    -- Confirm completion exception
  
exception
      when
Tasking_Error =>
         return False;
   end Delete_Event;

Destroy is the handler of the signal emitted when the main windows is about to destroyed. It ends the main messages loop in response. Delete_Event is the handler called when the main window is closed by the user. It stops the computation process and then confirms window to close by returning false. Since the task might be already terminated prematurely, Tasking_Error is handled.

File on_line_plotter.adb (continuation):
--
-- Value -- Get floating-point value from an entry widget
--
   function Value
            (  Edit : Gtk_Entry;
               Name : String;
               Min  : GDouble := GDouble'First;
               Max  : GDouble := GDouble'Last
            )  return GDouble is
   begin
      return
Result : GDouble := GDouble'Value (Edit.Get_Text) do
         if Result not in Min..Max then
            raise
Data_Error with Name & " out of range";
         end if;
      end return;
   exception
      when
Constraint_Error =>
        raise Data_Error with "Wrong " & Name;
   end Value;
--
-- Value -- Get integer value from an entry widget
--

   function Value
            (  Edit : Gtk_Entry;
               Name : String;
               Min  : Integer := 1;
               Max  : Integer := Integer'Last
            )  return Integer is
   begin
      return
Result : Integer := Integer'Value (Edit.Get_Text) do
         if
Result not in Min..Max then
            raise
Data_Error with Name & " out of range";
         end if;
      end return;
   exception
      when
Constraint_Error =>
         raise Data_Error with "Wrong " & Name;
   end Value;

The above defines two convenience functions are to get a floating-point or an integer value from an entry field.

File on_line_plotter.adb (continuation):
--
-- Save_Clicked -- Button "save to PDF"
--

   procedure Save_Clicked (Widget : access Gtk_Widget_Record'Class) is
      use
Gtk.File_Chooser;
      use Gtk.File_Chooser_Dialog;
      use Gtk.Main.Router;
      Dialog : Gtk_File_Chooser_Dialog;
      Button : Gtk_Widget;
   begin
      Gtk_New (Dialog, "PDF file to save into", Window, Action_Save);
      Button := Dialog.Add_Button ("OK",     Gtk_Response_OK);
      Button := Dialog.Add_Button ("Cancel", Gtk_Response_Cancel);
      case Dialog.Run is
         when
Gtk_Response_OK =>
            Oscilloscope.Capture_PDF (Get_Filename (+Dialog));
         when others =>
            null;
      end case;
      Dialog.Destroy;
   exception
      when
Error : others =>
         Say (Exception_Information (Error));
   end Save_Clicked;

Save_Clicked is a handler of the signal emitted when the save to PDF button is pressed. The implementation uses file chooser dialog to get the file name name. The dialog is first created. Then the OK button and the Cancel buttons are added to the dialog using Add_Button operation. After that the dialog is activated by calling Run operation. When the dialog is completed this or other way, Run returns the outcome, which is Gtk_Response_OK when a file was selected. The file name is taken using Get_Filename and then passed to Capture_PDF to store the oscilloscope's contents into the file.

File on_line_plotter.adb (continuation):
--
-- Start_Clicked -- Button "start"
--

   procedure Start_Clicked (Widget : access Gtk_Widget_Record'Class) is
      use
Gtk.Main.Router;
      From  : GDouble;
      To    : GDouble;
      Ratio : GDouble;
      Width : GDouble;
      Count : Positive;
   begin
      Start_Button.Set_Sensitive (False);
      From  := Value (Start_Frequency, "start frequency");
      To    := Value (Stop_Frequency,  "stop frequency");
      Count := Value (Steps,           "frequency steps");
      Ratio := Value (Stiffness_Ratio, "stiffness ratio", 0.0, 1.0);
      Width := To - From;

         -- Set page size of the scope
      Oscilloscope.Get_Sweeper (Lower).Configure
      (  Value          => From,
         Lower          => From,
         Upper          => Width,
         Step_Increment => Width / 100.0,
         Page_Increment => Width / 10.0,
         Page_Size      => Width
      );
         -- Initiate calculation process
      Calculator.Start
      (  (  Start     => Long_Float (From),
            Stop      => Long_Float (To),
            Steps     => Count,
            Stiffness => Long_Float (Ratio)
         ),
         Oscilloscope,
         Curve,
         Progress
      );
   exception
      when
Error : Data_Error =>
         Say (Exception_Message (Error));
      when Error : others =>
         Say (Exception_Information (Error));
   end Start_Clicked;

Start_Clicked is a handler of the signal emitted when the Start button is pressed. The implementation makes the button insensitive. Then it gets values from the entry fields of the window. The fields Start and Stop frequency are used to calculate the oscilloscope's horizontal axis width. Then the parameters are passed to the task's entry Start.

File on_line_plotter.adb (continuation):
--
-- Unicode_Toggled -- Check button toggling
--

   procedure Unicode_Toggled
             (  Widget : access Gtk_Widget_Record'Class
             )  is
   begin

      Oscilloscope.Set_Superscript (Unicode_Check.Get_Active);
   end Unicode_Toggled;

This procedure handles toggling the Use Unicode checkbox. It calls Set_Superscript with the checkbox state.

File on_line_plotter.adb (continuation):
--
-- Autoscale_Toggled -- Check button toggling
--

   procedure Autoscale_Toggled
             (  Widget : access Gtk_Widget_Record'Class
             )  is
   begin

      Oscilloscope.Set_Auto_Scaling (Left, Autoscale_Check.Get_Active);
   end Autscale_Toggled;

Autoscale_Toggled is called to handle toggling the Autoscale Y checkbox. It calls directly to Set_Auto_Scaling operation with the first parameter specifying the axis on the left.

File on_line_plotter.adb (continuation):
--
-- Circumvention of accessibility checks
--
   type Local_Widget_Callback is access procedure
        (  Widget : access Gtk_Widget_Record'Class
        );
   function "+" is
      new
Ada.Unchecked_Conversion
          (  Local_Widget_Callback,
             Cb_Gtk_Toggle_Button_Void
          );
   function "+" is
      new
Ada.Unchecked_Conversion
          (  Local_Widget_Callback,
             Cb_Gtk_Button_Void
          );
   type Local_Delete_Callback is access function
        (  Widget : access Gtk_Widget_Record'Class;
           Event  : Gdk_Event
        )  return Boolean;
   function "+" is
      new
Ada.Unchecked_Conversion
          (  Local_Delete_Callback,
             Cb_Gtk_Widget_Gdk_Event_Boolean
          );

Here conversions are defined to circumvent accessibility checks. Normally callbacks are defined at the library level packages. Here callbacks are nested routines which cannot be passed without an unchecked conversion.

File on_line_plotter.adb (continuation):
begin
   Gtk.Main.Init;
   Gtk.Window.Gtk_New (Window);
   Gtk.Main.Router.Init (Window); -- Initialize routing
   Window.Set_Title ("Sample on-line plotting");
   Window.On_Delete_Event (+Delete_Event'Access);
   Window.On_Destroy (Gtk.Missed.Destroy_Handler'Access);

This fragment performs standard initialization of the main window. First it initiates the main messages loop. Then it initializes servicing the requests and messages from Ada tasks. Then the window is created. Its title is set and finally the destroy and delete_event events handlers are connected.

File on_line_plotter.adb (continuation):
   declare
      Main_Box : Gtk_HBox;
   begin
      Gtk_New_HBox (Main_Box);
      Main_Box.Set_Spacing (3);
      Main_Box.Set_Border_Width (3);
      Add (Window, Main_Box);
     

This creates a horizontal box (Main_Box), which is put into the window. The box spacing and border width are set to 3 pixels. The box will contain another box on the left and the oscilloscope on the right.

File on_line_plotter.adb (continuation):
      declare -- Box on the left
         Left_Box : Gtk_VBox;
      begin
         Gtk_New_VBox (Left_Box);
         Left_Box.Set_Spacing (3);
         Main_Box.Pack_Start (Left_Box, False, False);

Here the vertical box (Left_Box) is created and put into the main box. Spacing is set to 3. The packing parameters are set to make the box occupy no more width than required. When the window is expanded or shrinking, the space is given to or taken from the oscilloscope.

File on_line_plotter.adb (continuation):
         declare -- Parameters in the left box
            Parameters : Gtk_Table;
            procedure Create
                      (  Edit  : out Gtk_Entry;
                         Row   : GUInt;
                         Label : String;
                         Init  : String
                      )  is
               Annotation : Gtk_Label;
            begin
               Gtk_New (Annotation, Label);
               Annotation.Set_Alignment (1.0, 0.5);
               Parameters.Attach
               (  Annotation,
                  0, 1, Row, Row + 1,
                  XOptions => Fill,
                  YOptions => Shrink
               );
               Gtk_New (Edit);
               Edit.Set_Width_Chars (10);
               Edit.Set_Text (Init);
               Parameters.Attach
               (  Edit,
                  1, 2, Row, Row + 1,
                  XOptions => Fill or Expand,
                  YOptions => Shrink
               );
            end Create;

The entry fields and their labels in the left box are put in a table which aligns them vertically. The table is named Parameters and a convenience procedure Create is used to create a label and an entry field at the specified row of the table. The labels are aligned to the right horizontally and centred vertically using the operation Set_Alignment. The operation Attach places a child widget into the table. Set_Width controls the number of characters in the entry field.

File on_line_plotter.adb (continuation):
         begin
            Gtk_New (Parameters, 6, 2, False);
            Parameters.Set_Row_Spacings (3);
            Parameters.Set_Col_Spacings (3);
            Left_Box.Pack_Start (Parameters);
            Create (Start_Frequency, 0, "Start frequency", "-44.88");
            Create (Stop_Frequency,  1, "Stop frequency",  "67.32");
            Create (Steps,           2, "Steps",           "300");
            Create (Stiffness_Ratio, 3, "Stiffness ratio", "1");

This creates the table of 6 rows and 2 columns. The parameter false tells that table cells may have different sizes. Table row and columns spacing is set to 3. The table is put into the left box. Then fields and labels are created and put into the table.

File on_line_plotter.adb (continuation):
            declare
               Label : Gtk_Label;
            begin
               Gtk_New (Label, "Autoscale Y");
               Label.Set_Alignment (1.0, 0.5);
               Parameters.Attach
               (  Label,
                  0, 1, 4, 5,
                  XOptions => Fill,
                  YOptions => Shrink
               );
               Gtk_New (Autoscale_Check);
               Autoscale_Check.Set_Active (True);
               Parameters.Attach
               (  Autoscale_Check,
                  1, 2, 4, 5,
                  XOptions => Fill,
                  YOptions => Shrink
               );
               Autoscale_Check.On_Toggled (+Autoscale_Toggled'Access);
            end;

Here the checkbox Autoscale Y and its label is created and put into the table's row 5. Then the event handler is connected.

File on_line_plotter.adb (continuation):
            declare
               Label : Gtk_Label;
            begin
               Gtk_New (Label, "Use Unicode");
               Label.Set_Alignment (1.0, 0.5);
               Parameters.Attach
               (  Label,
                  0, 1, 5, 6,
                  XOptions => Fill,
                  YOptions => Shrink
               );
               Gtk_New (Unicode_Check);
               Unicode_Check.Set_Active (True);
               Parameters.Attach
               (  Unicode_Check,
                  1, 2, 5, 6,
                  XOptions => Fill,
                  YOptions => Shrink
               );
               Unicode_Check.On_Toggled (+Unicode_Toggled'Access);
            end;
         end;

This is basically same for the checkbox Use Unicode.

File on_line_plotter.adb (continuation):
         declare -- Save button
            Box    : Gtk_HBox;
            Button : Gtk_Button;
         begin
            Gtk_New_HBox (Box);
            Box.Set_Spacing (3);
            Left_Box.Pack_Start (Box, False, False);
            Gtk_New (Button, "Save to PDF");
            Box.Pack_Start (Button, False, False);
            Button.On_Clicked (+Save_Clicked'Access);
         end;

This fragment creates a horizontal box, puts it into the left box. Then creates the Save to PDF button and puts it into the former box. The box is needed to prevent the button from being expanded horizontally. Then the button handler is connected to the button.

File on_line_plotter.adb (continuation):
         declare -- Start button and progress bar in the left box
            Box : Gtk_HBox;
         begin
            Gtk_New_HBox (Box);
            Box.Set_Spacing (3);
            Left_Box.Pack_Start (Box, False, False);
            Gtk_New (Start_Button, "Start");
            Box.Pack_Start (Start_Button, False, False);
            Start_Button.On_Clicked (+Start_Clicked'Access);
            Gtk_New (Progress);
            Box.Pack_Start (Progress);
         end;
      end;

This creates the Start button. Then a progress bar is created and put into the box next to the button.

File on_line_plotter.adb (continuation):
      declare -- Frame with the oscilloscope on the right
         Frame : Gtk_Frame;
      begin
         Gtk_New (Frame);
         Frame.Set_Shadow_Type (Shadow_In);
         Main_Box.Pack_Start (Frame);
         Gtk_New (Oscilloscope);
         Frame.Add (Oscilloscope);
         Oscilloscope.Set_Manual_Sweep (False);
         --
         -- Configuring the lower axis
         --

         Oscilloscope.Set_Frozen     (Lower, True);  -- No sweeping
         Oscilloscope.Set_Time_Scale (Lower, False); -- No scale (slider)
         Oscilloscope.Set_Time_Grid  (Lower, True);  -- Grid
         Oscilloscope.Set_Time_Axis
         (  Lower,
            True, -- Visible
            False -- As plain numbers
         );
         --
         -- Adding the channel
         --

         Curve :=
            Add_Channel
            (  Widget  => Oscilloscope,
               Mode    => Gtk.Layered.Linear, -- Linear interpolation
               Color   => RGB (0.0, 0.0, 0.7),
               Sweeper => Lower
            );
         --
         -- Configuring the left axis for this channel (and its group)
         --

         Oscilloscope.Set_Group (Left, Oscilloscope.Get_Group (Curve));
         Oscilloscope.Set_Values_Axis  (Left, True);
         Oscilloscope.Set_Values_Scale (Left, True);
         Oscilloscope.Set_Values_Grid  (Left, True);
         Oscilloscope.Set_Values_Axis_Width (Left, 80);
      end;
   end;

Here the oscilloscope widget is create put into a frame which is then placed into the main box. The oscilloscope's parameters are set the same way it was done as described in the previous plotting example.

File on_line_plotter.adb (continuation):
   Window.Set_Default_Size (800, 400);
   Show_All (Window);
   Gtk.Main.Main;
exception
   when Error : others =>
      Put_Line ("Error: " & Exception_Information (Error));
end On_Line_Plotter;

Finally the window is sized, shown and the main messages loop is entered.

File worker.ads:
with Gtk.Oscilloscope;  use Gtk.Oscilloscope;
with Gtk.Progress_Bar;  use Gtk.Progress_Bar;

package Worker is
--
-- Parameters -- Of a calculation session
--

   type Parameters is record
      Start     : Long_Float;
      Stop      : Long_Float;
      Stiffness : Long_Float;
      Steps     : Positive;
   end record;
--
-- Process -- Calculation process task
--

   task type Process is
   --
   -- Start -- Computations with the parameters specified
   --
   -- Parameters - To use in the computations
   -- Scope      - The oscilloscope
   -- Channel    - The number of the channel to feed
   -- Progress   - The progress bar to update during computations
   --

      entry Start
            (  Data     : Parameters;
               Scope    : Gtk_Oscilloscope;
               Channel  : Channel_Number;
               Progress : Gtk_Progress_Bar
            );
   --
   -- Stop -- Terminate the task prematurely
   --

      entry Stop;
   end Process;
end Worker;

The package worker defines parameters of the task performing computations. Then it declares the task type with two entries. The entry Start initiates computations. The entry Stop requests task completion.

The file worker.adb provides implementation of the package:

File worker.adb:

with Ada.Calendar;     use Ada.Calendar;
with Ada.Exceptions;   use Ada.Exceptions;
with Ada.Numerics;     use Ada.Numerics;
with GLib;             use GLib;
with Gtk.Main.Router;  use Gtk.Main.Router;

with Ada.Numerics.Long_Elementary_Functions;
use  Ada.Numerics.Long_Elementary_Functions;

with Interfaces.C;

package body Worker is
--
-- Update_Request -- Progress bar update refresh
--
-- Since  GTK  is single tasking,  drawing may not be performed on the
-- context of another task. This data type is used to request the main
-- GTK task to perform update of the progress bar state.
--
   type Update_Request is record
      Progress     : Gtk_Progress_Bar;
      Step_No      : Natural;
      Step_Last    : Positive;
      Substep_No   : Natural;
      Substep_Last : Positive;
   end record;
--
-- Messages -- Update_Request marshaller
--

   package Messages is new Generic_Message (Update_Request);
--
-- Service -- Called  on the GTK context to service the request.  This
--            procedure updates the progress bar state.
--

   procedure Service (Data : in out Update_Request) is
   begin

      Data.Progress.Set_Fraction
      (  (  (  GDouble (Data.Substep_No)
            /  GDouble (Data.Substep_Last)
            )
         +  GDouble (Data.Step_No)
         )
      /  GDouble (Data.Step_Last)
      );
      Data.Progress.Set_Text
      (  "step"
      &  Integer'Image (Data.Step_No)
      &  ", index"
      &  Integer'Image (Data.Substep_No)
      );
   end Service;

The package defines the type Update_Requests used to update the progress bar while performing computations. The type is used to instantiate the package Messages. The procedure Service will be called on the context of main GTK task to update the state of the progress bar.

Next follows the code solving the actual problem. The application code is marked as by the pink color (__).

File worker.adb (continuation):
--
-- Vector algebra primitives
--

   type Vector is array (Integer range <>) of Long_Float;

   function "+" (X, Y : Vector) return Vector is
   begin
      return
Z : Vector (X'Range) do
         for
I in X'Range loop
            Z(I) := X(I) + Y(I);
         end loop;
      end return;
   end "+";

   function "*" (S : Long_Float; X : Vector) return Vector is
   begin
      return
Z : Vector (X'Range) do
         for
I in X'Range loop
            Z(I) := S * X(I);
         end loop;
      end return;
   end "*";

   function "/" (X : Vector; S : Long_Float) return Vector is
   begin
      return
Z : Vector (X'Range) do
         for
I in X'Range loop
            Z (I) := X (I) /S;
         end loop;
      end return;
   end "/";

   Young_Modulus   : constant := 200.0E9;
   Second_Moment   : constant := 0.0635;
   Rotor_Length    : constant := 3.6;
   Stiffness_Shaft : constant := 48.0 * Young_Modulus * Second_Moment /
                                 Rotor_Length**3;
   Stiffness_Bearings : constant := 1000.0E6;
   Stiffness_Total    : constant :=
      (  (Stiffness_Shaft * Stiffness_Bearings)
      /  (Stiffness_Shaft + Stiffness_Bearings)
      );
   Rotor_Mass         : constant := 30.0E3;
   Zeta               : constant := 0.1;
   Mean_Airgap_Length : constant := 17.0E-3;

   Two_PI : constant := 2.0 * Pi;

   subtype Actual_Vector is Vector (1..4);
--
-- F -- Calculate the state vector
--

   function F
            (  T                      : Long_Float;
               Y                      : Actual_Vector;
               Force_Z2, Force_Z4     : Long_Float;
               Norm_Driving_Frequency : Long_Float;
               Norm_Radial_Stiffness  : Long_Float;
               Zeta                   : Long_Float
            )  return Actual_Vector is
   begin
      return

      (  1 => Y (2),
         2 => (  Force_Z2 * Cos (Norm_Driving_Frequency * T - Y (3))
              -  2.0 * Zeta * Y (2)
              -  (1.0 - Y (4) * Y (4)) * Y (1)
              +  Norm_Radial_Stiffness * Y (1)
              ),
         3 => Y (4),
         4 => (  Force_Z4 * Sin (Norm_Driving_Frequency * T - Y (3))
              -  2.0 * (Y (2) / Y (1) + Zeta) * Y (4)
      )  );
   end F;

File worker.adb (continuation):
--
-- Process -- The task doing actual computations
--

   task body Process is
      Scope     : Gtk_Oscilloscope;
      Channel   : Channel_Number;
      Progress  : Gtk_Progress_Bar;
      Last_Time : Time := Clock;

The task Process wraps computations.

File worker.adb (continuation):
      Steps     : Positive;

      -- Initial time, final time, no of steps, step size
      A : constant := 0.0;
      B : constant := 10_000.0;
      N : constant := 2_500_000;
      H : constant := (B - A) / Long_Float (N);

File worker.adb (continuation):
      procedure Show_Progress (Step : Natural; I : Natural) is
      begin

         Messages.Send (Service'Access, (Progress, Step, Steps, I, N));
      end Show_Progress;

The procedure Show_Progress is used to update the state of the progress bar. It uses the procedure Send of the package Message. Send marshals the record aggregate to the main GTK task, which later calls the procedure Service with these data.

File worker.adb (continuation):
      T              : Long_Float;
      K1, K2, K3, K4 : Actual_Vector;
      Y              : Actual_Vector;

      Radial_Ump              : constant := 148724.91491;
      Radial_Stiffness        : Long_Float;
      Stiffness_Ratio         : Long_Float;
      Actual_Stiffness        : Long_Float;
      Norm_Radial_Stiffness   : Long_Float;

      Whirl_Frequency         : Long_Float;
      Norm_Forcing_Frequency  : Long_Float;
      Natural_Frequency       : Long_Float;
      Force_Z2, Force_Z4      : Long_Float;

      -- Driving frequencies over whirling range
      Forcing_Frequency_Start : Long_Float;
      Forcing_Frequency_Limit : Long_Float;
      Forcing_Frequency_Step  : Long_Float;

      -- Minmax algorithm
      Largest      : Long_Float;
      Currentvalue : Long_Float;

      procedure Get_Rk_K is
      begin

         K1 :=
            H * F (  T,
                     Y,
                     Force_Z2,
                     Force_Z4,
                     Norm_Forcing_Frequency,
                     Norm_Radial_Stiffness,
                     Zeta
                  );
         K2 :=
            H * F (  T + H / 2.0,
                     Y + K1 / 2.0,
                     Force_Z2,
                     Force_Z4,
                     Norm_Forcing_Frequency,
                     Norm_Radial_Stiffness,
                     Zeta
                  );
         K3 :=
            H * F (  T + H / 2.0,
                     Y + K2 / 2.0,
                     Force_Z2,
                     Force_Z4,
                     Norm_Forcing_Frequency,
                     Norm_Radial_Stiffness,
                     Zeta
                  );
         K4 :=
            H * F (  T + H,
                     Y + K3,
                     Force_Z2,
                     Force_Z4,
                     Norm_Forcing_Frequency,
                     Norm_Radial_Stiffness,
                     Zeta
                  );
      end Get_Rk_K;
   begin

File worker.adb (continuation):
      select -- Waiting for parameters or exit request
         accept Start
                (  Data     : Parameters;
                   Scope    : Gtk_Oscilloscope;
                   Channel  : Channel_Number;
                   Progress : Gtk_Progress_Bar
                )
         do
            Forcing_Frequency_Start := Data.Start;
            Forcing_Frequency_Limit := Data.Stop;
            Forcing_Frequency_Step :=
               (Data.Stop - Data.Start) / Long_Float (Data.Steps);
            Stiffness_Ratio  := Data.Stiffness;
            Process.Scope    := Scope;
            Process.Channel  := Channel;
            Process.Progress := Progress;
            Steps            := Data.Steps;
         end;
      or accept Stop;
         raise Quit_Error;
      end select;

The task starts waiting for configuration parameters accepting the entry Start. Alternatively it accepts the entry Stop and then exit.

File worker.adb (continuation):
      -- Starting computations
      Actual_Stiffness := Stiffness_Ratio * Stiffness_Total;
      Natural_Frequency := Sqrt (Actual_Stiffness / Rotor_Mass);

      -- Looping the whirling frequency range
      Whirl_Frequency := Forcing_Frequency_Start;
      for Step in 0..Steps loop
         Largest := Long_Float'First;

         T := A; -- Initial time
         Y := (others => 0.01);

         -- For each whirling frequency
         for I in 1..N loop
            Radial_Stiffness := Radial_Ump / (Mean_Airgap_Length * 0.1);
            Norm_Radial_Stiffness :=
               Radial_Stiffness / Actual_Stiffness;
            Force_Z2 := 0.1; --new force
            Force_Z4 := 0.1 / Y (1); --new force
            Norm_Forcing_Frequency :=
               Whirl_Frequency / Natural_Frequency;
            Get_Rk_K; -- get the k coefficients
            Y := Y + (K1 + 2.0 * K2 + 2.0 * K3 + K4) / 6.0;
            Y (3) := Long_Float'Remainder (Y (3), Two_Pi);
            if Y (3) < 0.0 then
               Y (3) := Y (3) + Two_PI;
            end if;

            -- Last 25000 values to calculate rmax
            if I >= 2_475_000 then
               Currentvalue := Y (1);
               Largest := Long_Float'Max (Largest, Currentvalue);
            end if;
            T := T + H;

File worker.adb (continuation):
            --
            -- Updating  the progress bar or exiting.  We don't do it on
            -- each iteration, it would only waste resources. Instead of
            -- that we do it each 200ms, which is short enough to appear
            -- "instant" for the user.
            --

            if Clock - Last_Time > 0.2 then -- Update progress bar
               select
                  accept
Stop; -- Check if existing is requested
                  raise Quit_Error;
               else
                  Show_Progress (Step, I);
                  Last_Time := Clock;
               end select;
            end if;
         end loop; -- end for each whirling frequency
         Scope.Feed
         (  Channel => Channel,
            T       => GDouble (Whirl_Frequency),
            V       => GDouble (Largest)
         );

The progress bar is updated approximately each 200ms. This is frequently enough and does not cause much overhead on the computations. The oscilloscope is updated by calling to the procedure Feed. The procedure can be called from any task under the condition that this is single task.

File worker.adb (continuation):
         Whirl_Frequency := Whirl_Frequency + Forcing_Frequency_Step;
      end loop;
      Show_Progress (Steps, N);
      accept Stop;
   exception
      when Quit_Error | Busy_Error => -- Main loop quitted, we follow
         null;
      when Error : others =>
         Say (Exception_Information (Error));
   end Process;

end Worker;

[Back][TOC][Next]

13. Editor widget

The package Gtk.Layered_Editor provides a simple editor widget for visual editing layered widgets:

layered editor

The widget can be used for creation stand-alone editor application or for integration it in a user interface. The package declares the widget type:

type Gtk_Layered_Editor_Record is new Gtk_Widget_Record with private;
type Gtk_Layered_Editor is
   access all
Gtk_Layered_Editor_Record'Class;

The following operations are defined:

function Get
         (  Widget : not null access Gtk_Layered_Editor_Record
         )  return Gtk_Layered;

This function returns the widget being edited. There result is null if there is none.

function Get_Buttons_Box
         (  Widget : not null access Gtk_Layered_Editor_Record
         )  return Gtk_Box;

This function returns the button box on the widget's top. The application may add some custom buttons there, e.g. load and save buttons.

procedure Gtk_New
          (  Widget  : out Gtk_Layered_Editor;
             Layered : access Gtk_Layered_Record'Class := null
          );

This procedure creates a new editor widget. The result is Widget. The parameter Layered is the widget to edit. Note that when omitted, no tooltips will be shown.

procedure Initialize
          (  Widget  : not null access
                          Gtk_Layered_Editor_Record'Class;
             Layered : access Gtk_Layered_Record'Class
          );

This procedure has to be called from Initialize of a derived widget.

procedure Put
          (  Widget  : not null access Gtk_Layered_Editor_Record;
             Layered : access Gtk_Layered_Record'Class := null
          );

This procedure sets the widget to edit. When Layered is null the editor will edit no widget.


[Back][TOC][Next]

14. Installation

The software does not require special installation. The archive's content can be put in a directory and used as-is. For users of GNAT compiler the software provides gpr project files, which can be used in the Gnat Programming Studio (GPS).

The distribution includes:

For CentOS, Debian, Fedora, Ubuntu Linux distributions there are pre-compiled packages, see the links on the top of the page.


[Back][TOC][Next]

15. Changes log

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (22 May 2022) to the version 3.24:

Changes (31 May 2020) to the version 3.23:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (31 January 2020) to the version 3.22:

Changes (14 January 2020) to the version 3.21:

Changes (22 Dec 2018) to the version 3.20:

Changes (8 Nov 2018) to the version 3.19:

Changes (5 Aug 2018) to the version 3.18:

Changes (4 January 2018) to the version 3.17:

Changes (2 October 2017) to the version 3.15:

Changes (25 July 2016) to the version 3.14:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (12 April 2016) to the version 3.13:

Changes (4 March 2016) to the version 3.12:

Changes (18 October 2015) to the version 3.11:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (28 June 2015) to the version 3.10:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (2 April 2015) to the version 3.9:

Changes  (24 July 2014) to the version 3.8:

Changes  (1 June 2014) to the version 2.14:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes  (10 August 2012) to the version 1.3:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes to the version 1.2:

Changes to the version 1.1:

Changes to the version 1.0:

The following versions were tested with the compilers:

and the GtkAda versions:

The version 1.0.


[Back][TOC]

16. Table of Contents

1 Widgets gallery
    1.1. Gauges
    1.2. Sectors and segments
    1.3. Meters
    1.4. Flat and rectangular
    1.5. Wall clocks
    1.6. Oscilloscope
2 Layered widgets
    2.1. Anatomy of a gauge
    2.2. Abstract layer
       2.2.1. Primitive operations
       2.2.2. Abstract operations
    2.3. Layered widget
       2.3.1. Primitive operations
       2.3.2. Class-wide operations
    2.4. Abstract bordered layer
       2.4.1. Primitive operations
       2.4.2. Abstract operations
    2.5. Layer interfaces
       2.5.1. Layer location interface
       2.5.2. Scalable layer interface
       2.5.3. Widened layer interface
       2.5.4. Annotation layer interface
       2.5.5. Needle interface
    2.6. Other types declared
       2.6.1. Closures of elliptic arcs
       2.6.2. Line parameters
       2.6.3. Tick parameters
       2.6.4. Text transformation
    2.7. Refresh engine
3 Backgrounds
    3.1. Elliptic background
    3.2. Rectangular background
4 Scales
    4.1. Elliptic scale
    4.2. Flat scale
5 Annotations
    5.1. Elliptic annotation
    5.2. Flat annotation
6 Needles
    6.1. Needle
    6.2. Clock hand
    6.3. Elliptic bar needle
    6.4. Filled shape needle
    6.5. Flat needle
    6.6. Bar needle
    6.7. Digital value
    6.8. Disk needle
7 Shapes
    7.1. Arc
    7.2. Cap
    7.3. Line
    7.4. Text (label)
    7.5. Rectangle
    7.6. SVG image
8 Special layers
    8.1. Rectangular clip region
    8.2. Caching layer
9 Waveforms
    9.1. Data sources and scanners
       9.1.1. Data source interface
       9.1.2. Data scanner interface
       9.1.3. Data feed interface
       9.1.4. Ring buffer implementation
    9.2. Waveform amplifiers
       9.2.1. Amplifier interface
       9.2.2. Amplifier implementation
    9.3. Waveform sweepers
       9.3.1. Sweeper interface
       9.3.2. Time operations
       9.3.3. Sweeper implementation
    9.4. Waveform layer
    9.5. Graph paper
    9.6. Graph paper annotation
       9.6.1. Annotation interface
       9.6.2. Axis annotation implementation
       9.6.3. Time annotation implementation
    9.7. Scales
10 Miscellany
    10.1. Elliptic shapes
       10.1.1. Relative angles
       10.1.2. Transformations
       10.1.3. Information functions
       10.1.4. Drawing
    10.2. Stream I/O
    10.3. Interpolation mode
    10.4. Vertical alignment
    10.5. Fonts
11 Samples
    11.1. Gauges
       11.1.1. Gtk.Gauge.Round_254
       11.1.2. Gtk.Gauge.Round_270
       11.1.3. Gtk.Gauge.Round_270_Outer
       11.1.4. Gtk.Gauge.Round_270_Reversed
       11.1.5. Gtk.Gauge.Round_270_Inout
       11.1.6. Gtk.Gauge.Round_270_60s
    11.2. Sectors and segments
       11.2.1. Gtk.Gauge.Round_180
       11.2.2. Gtk.Gauge.Round_90
       11.2.3. Gtk.Gauge.Round_110
       11.2.4. Gtk.Gauge.Elliptic_180
    11.3. Meters
       11.3.1. Gtk.Meter.Angular_90
       11.3.2. Gtk.Meter.Elliptic_90
       11.3.3. Gtk.Meter.Round_90
       11.3.4. Gtk.Meter.Round_94
       11.3.5. Gtk.Meter.Thermo
       11.3.6. Gtk.Meter.Thermo_Symmetric
       11.3.7. Gtk.Meter.Thermo_Dual
    11.4. Flat and rectangular
       11.4.1. Gtk.Gauge.Rectangular_70s
       11.4.2. Gtk.Gauge.Rectangular_70s_Slanted
       11.4.3. Gtk.Gauge.Flat_Horizontal
       11.4.4. Gtk.Gauge.Flat_Vertical
    11.5. Wall clocks
       11.5.1. Gtk.Wall_Clock.Imperial
       11.5.2. Gtk.Wall_Clock.Classic
       11.5.3. Gtk.Wall_Clock.Modern
    11.6. LEDs
       11.6.1. Gtk.Gauge.LED_Round
       11.6.2. Gtk.Gauge.LED_Rectangualar
    11.7. Valves
       11.7.1. Gtk.Valve.Round_90
12 Oscilloscope
    12.1. Oscilloscope widget
       12.1.1. Channels
       12.1.2. Groups
       12.1.3. Vertical scales and axes
       12.1.4. Horizontal scales and axes
       12.1.5. The widget type and operations
       12.1.6. Signals
       12.1.7. Selection and drop-down menu
    12.2. Sweeper panel
    12.3. Amplifier panel
    12.4. Channels panel
    12.5. Plotting data with the oscilloscope
    12.6. Asynchronous plotting
13 Editor widget
14 Installation
15 Changes log
16 Table of contents