[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Gtk.Extra.Plot`_`Data

This package defines the root of the plot hierarchy. It defines several display strategies that can be used to show scientific data on the screen (see the children for 3D, polar, bars,...)

All coordinates are in percent of the total size allocates for the data set (ie the actual position is (x * width, y * height), where (x, y) is the value stored in the data set and (width, height) its allocated screen size.

- Gtk.Extra.Plot_Data Widget Hierarchy
- Gtk.Extra.Plot_Data Types
- Gtk.Extra.Plot_Data Subprograms

## Widget Hierarchy

    Gtk_Object                    (see section Package Gtk.Object)
       \___ Gtk_Widget            (see section Package Gtk.Widget)
          \___ Gtk_Plot_Data      (see section Package Gtk.Extra.Plot_Data)

## Types

    type Gdouble_Array_Access is access all Glib.Gdouble_Array;

| The reason we use this type in the functions below is because gtk+-extra does not keep a copy of the arrays, but points to the one given in argument. Thus, the Ada arrays should not be allocated on the stack, or at least they should be at library level. Using this 'Access will force the compiler to do the check for us.

    type No_Range_Gdouble_Array is array (Natural) of Gdouble;

| An array of values. This is used to represent the data values displayed in the plot. This array does not have any range information (so that it can be easily returned from a C function, without requiring an extra copy of the table). You can not use 'Range on this array.

    type No_Range_Gdouble_Array_Access is access all No_Range_Gdouble_Array;

| An access to a flat array.

    type Plot_Connector is
        (Connect_None,
            -- No connection

         Connect_Straight,
            -- straight line

         Connect_Spline,
            -- spline or Bezier curve

         Connect_Hv_Step,
            -- Horizontal then vertical

         Connect_Vh_Step,
            -- Vertical then horizontal

         Connect_Middle_Step
            -- Split in the middle
         );

| The type of connection between two adjacent points in a graph.

    type Plot_Function is access function
        (Plot  : System.Address;

    type Plot_Gradient is new Integer;

| Indicate which color components vary along the gradient

    type Plot_Line_Style is
        (Line_None,
         Line_Solid,
         Line_Dotted,
         Line_Dashed,
         Line_Dot_Dash,
         Line_Dot_Dot_Dash,
         Line_Dot_Dash_Dash);

| Lines used to connect two adjacent points in a graph.

    type Plot_Symbol_Style is
        (Symbol_Empty,
         Symbol_Filled,
         Symbol_Opaque);

| Style used to draw the points in a graph.

    type Plot_Symbol_Type is
        (Symbol_None,
         Symbol_Square,
         Symbol_Circle,
         Symbol_Up_Triangle,
         Symbol_Down_Triangle,
         Symbol_Right_Triangle,
         Symbol_Left_Triangle,
         Symbol_Diamond,
         Symbol_Plus,
         Symbol_Cross,
         Symbol_Star,
         Symbol_Dot,
         Symbol_Impulse);

| Type of symbol used to represent the points in a graph.

    type Points_Array is record
        Points     : No_Range_Gdouble_Array_Access;
        Num_Points : Gint := 0;
        end record;

| The points are indexed from 0 to Num_Points-1. Note that you can't use 'Range, 'First or 'Last on Points.

## Subprograms

### Creating a Data set

    procedure Gtk_New
      (Data               : out    Gtk_Plot_Data;
       Func               :        Plot_Function := null);

| Creates a new data set. Its values can either be generated automatically from Func, or will have to be set explicitely using the other subprograms in this package.

    function Get_Type              return Gtk.Gtk_Type;

| Return the internal value associated with a Gtk_Plot_Data.

    procedure Set_Name
      (Data               : access Gtk_Plot_Data_Record;
       Name               :        String);

| Set the name used internally for that dataset. This name does not appear anywhere on the screen, but it is easier to find the dataset afterward by using this name.

### Drawing a set

Although a set is basically a list of values, it is closely associated with its representation on the screen (see the children of Gtk_Plot_Data for various possible representations). The Gtk.Extra packages are designed so that the drawing can be done either to the screen (through a Gdk adapter), to a postscript file for easy printing, or to any other media.

    procedure Paint
      (Data               : access Gtk_Plot_Data_Record);

| Emits the "draw_data" signal to request a redrawing of the data set.

    procedure Draw_Points
      (Data               : access Gtk_Plot_Data_Record;
       N                  :        Gint);

| Draw at most N values of the Data set on the screen. If N is greater than the actual number of values in Data, then they are all displayed.

    procedure Draw_Symbol
      (Data               : access Gtk_Plot_Data_Record;
       X, Y               :        Gdouble);

| Draw the current symbol (see Set_Symbol) at specific coordinates on the screen.

### Manipulating values

    procedure Set_Points
      (Data               : access Gtk_Plot_Data_Record;
       X                  :        Gdouble_Array_Access;
       Y                  :        Gdouble_Array_Access;
       Dx                 :        Gdouble_Array_Access;
       Dy                 :        Gdouble_Array_Access);

Set some explicit points in the set.
Note that the set must not be associated with a function, or the points will simply be ignored. All of the arrays must have the same length, the behavior is undefined otherwise. X and Y are the list of coordinates of the points. Dx and Dy are the list of size (precision) of these points. A bigger symbol will be displayed for the point whose (Dx, Dy) value is bigger.

    procedure Get_Points
      (Data               : access Gtk_Plot_Data_Record;
       X                  : out    Points_Array;
       Y                  : out    Points_Array;
       Dx                 : out    Points_Array;
       Dy                 : out    Points_Array);

| Return the value of the points in the set. Null-length arrays are returned if the set is associated with a function, since no explicit point has been set. See Set_Points for a definition of X, Y, Dx and Dy.

    procedure Set_X
      (Data               : access Gtk_Plot_Data_Record;
       X                  :        Gdouble_Array_Access);

    procedure Set_Z
      (Data               : access Gtk_Plot_Data_Record;
       Z                  :        Gdouble_Array_Access);

    procedure Set_Dx
      (Data               : access Gtk_Plot_Data_Record;
       Dx                 :        Gdouble_Array_Access);

    procedure Set_Dz
      (Data               : access Gtk_Plot_Data_Record;
       Dz                 :        Gdouble_Array_Access);

| Set the precision of the points in the set. A bigger symbol is displayed for the points whose (Dx, Dy, Dz) is bigger. The array must have a length of Get_Numpoints (if GtkAda was compiled with assertions enabled, an exception will be raised if the length are different). No copy of the array is made for efficiency reasons, thus modifying the array content later on will also modify the plot.

    procedure Set_Da
      (Data               : access Gtk_Plot_Data_Record;
       Da                 :        Gdouble_Array_Access);

| Specifies the colors to use for the points. The color of the symbols is detemined using the gradient. the gradient has (min, max) values, and corresponding colors. The symbol's color is interpolated between these values using hue/saturation/value depending on the gradient_mask.

    function Get_X
      (Data               : access Gtk_Plot_Data_Record)
       return Points_Array;

    function Get_Z
      (Data               : access Gtk_Plot_Data_Record)
       return Points_Array;

    function Get_Dx
      (Data               : access Gtk_Plot_Data_Record)
       return Points_Array;

    function Get_Dz
      (Data               : access Gtk_Plot_Data_Record)
       return Points_Array;

    procedure Set_Numpoints
      (Data               : access Gtk_Plot_Data_Record;
       Num                :        Gint);

| Set the number of points that should be expected in the graph. Note that this does not automatically resize all the internal structure, it just indicates what size the parameters to Set_X, Set_Y,... should have.

    function Get_Numpoints
      (Data               : access Gtk_Plot_Data_Record)
       return Gint;

| Return the number of points expected in the graph.

### Labels

Each point in the data set can be associated with a label that describes it. This is only relevant for data sets where you explicitely give values, not when the values are generated by a function.

    procedure Set_Labels
      (Data               : access Gtk_Plot_Data_Record;
       Labels             :        Gtkada.Types.Chars_Ptr_Array);

| Set the labels associated which each point in the canvas. There must be at least Get_Numpoints elements in Labels, or the behavior is undefined

    function Get_Labels
      (Data               : access Gtk_Plot_Data_Record)
       return Gtkada.Types.Chars_Ptr_Array;

| Return the labels associated with the points in the data set. Note that this returns a *copy* of the actual array, and thus might be expensive to call.

    procedure Show_Labels
      (Data               : access Gtk_Plot_Data_Record;
       Show               :        Boolean);

| Indicate whether the labels should be displayed next to each point in the data set. This has no effect if no labels were specified.

    procedure Labels_Set_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Font               :        String;
       Height             :        Gint;
       Angle              :        Gint;
       Foreground         :        Gdk.Color.Gdk_Color;
       Background         :        Gdk.Color.Gdk_Color);

| Set the properties of the labels

### Symbols and Connectors

Each point that is explicitely set in the data set through the
Set_X, Set_Y,... subprograms is visually associated with a symbol. There are several representations for the symbols.

All these symbols are then connected by a line, a curve or any other link. These are called connectors.

Each symbol, in addition to being connected to the next one with a connector, can also be linked to the axis X=0, Y=0 or Z=0 so that it is easier to read its coordinates. These are called errbars, and they must be explicitely shown.

    procedure Set_Symbol
      (Data               : access Gtk_Plot_Data_Record;
       The_Type           :        Plot_Symbol_Type;
       Style              :        Plot_Symbol_Style;
       Size               :        Gint;
       Line_Width         :        Gfloat;
       Color              :        Gdk.Color.Gdk_Color;
       Border_Color       :        Gdk.Color.Gdk_Color);

| Set the visual aspect of the symbols.

    procedure Get_Symbol
      (Data               : access Gtk_Plot_Data_Record;
       The_Type           : out    Plot_Symbol_Type;
       Style              : out    Plot_Symbol_Style;
       Size               : out    Gint;
       Line_Width         : out    Gint;
       Color              : out    Gdk.Color.Gdk_Color;
       Border_Color       : out    Gdk.Color.Gdk_Color);

| Return the visual characteristics of the symbols.

    procedure Set_Connector
      (Data               : access Gtk_Plot_Data_Record;
       Connector          :        Plot_Connector);

| Set the style of the connectors.

    function Get_Connector
      (Data               : access Gtk_Plot_Data_Record)
       return Plot_Connector;

| Return the connector style used for the data set.

    procedure Set_Line_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Style              :        Plot_Line_Style;
       Width              :        Gfloat;
       Color              :        Gdk.Color.Gdk_Color);

| Set the line style used for the connectors.

    procedure Get_Line_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Style              : out    Plot_Line_Style;
       Width              : out    Gfloat;
       Color              : out    Gdk.Color.Gdk_Color);

| Return the line attributes used for the connectors.

    procedure Set_X_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Style              :        Plot_Line_Style;
       Width              :        Gfloat;
       Color              :        Gdk.Color.Gdk_Color);

| Set the style of the lines used to connect the symbols to the X axis.

    procedure Set_Y_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Style              :        Plot_Line_Style;
       Width              :        Gfloat;
       Color              :        Gdk.Color.Gdk_Color);

| Set the style of the lines used to connect the symbols to the Y axis.

    procedure Set_Z_Attributes
      (Data               : access Gtk_Plot_Data_Record;
       Style              :        Plot_Line_Style;
       Width              :        Gfloat;
       Color              :        Gdk.Color.Gdk_Color);

| Set the style of the lines used to connect the symbols to the Z axis.

    procedure Show_Xerrbars
      (Data               : access Gtk_Plot_Data_Record);

    procedure Show_Zerrbars
      (Data               : access Gtk_Plot_Data_Record);

| Indicate that each symbol should be connected to the various axis

    procedure Hide_Xerrbars
      (Data               : access Gtk_Plot_Data_Record);

    procedure Hide_Zerrbars
      (Data               : access Gtk_Plot_Data_Record);

| Indicate the the symbol should not be connected to the axis.

    procedure Fill_Area
      (Data               : access Gtk_Plot_Data_Record;
       Fill               :        Boolean);

| Indicate whether the area between two points should be filled or not.

    function Area_Is_Filled
      (Data               : access Gtk_Plot_Data_Record)
       return Boolean;

| Indicate whether the area between two points is filled.

### Legends

In addition to the drawing corresponding to the data set, it is possible to display a box that contains a legend. This is particulary useful when multiple data sets are displayed on the same plot.

    procedure Set_Legend
      (Data               : access Gtk_Plot_Data_Record;
       Legend             :        String);

| Set the string printed in the legend for that data set. Note that an entry can exist in the legend even if there is no name associated with the graph.

    procedure Show_Legend
      (Data               : access Gtk_Plot_Data_Record);

| An entry will be made in the plot's legend for that dataset.

    procedure Hide_Legend
      (Data               : access Gtk_Plot_Data_Record);

| No entry will appear in the plot's legend for that dataset.

    procedure Set_Legend_Precision
      (Data               : access Gtk_Plot_Data_Record;
       Precision          :        Gint);

| Number of digits to display when the legends is associated with values, as is the case for gradients.

    function Get_Legend_Precision
      (Data               : access Gtk_Plot_Data_Record)
       return Gint;

| Return the number of digits used for values in the legend

### Gradients

The symbols displayed in the plot can be assigned specific colors. But they can also compute their own color by picking it in a gradient, depending on the value.

    procedure Set_Gradient_Mask
      (Data               : access Gtk_Plot_Data_Record;
       Mask               :        Plot_Gradient);

| Indicates which component of the colors vary along the gradient.

    function Get_Gradient_Mask
      (Data               : access Gtk_Plot_Data_Record)
       return Plot_Gradient;

| Return the mask used for the gradient.

    procedure Gradient_Set_Visible
      (Data               : access Gtk_Plot_Data_Record;
       Visible            :        Boolean);

| Indicates whether the gradient should be visible

    function Gradient_Visible
      (Data               : access Gtk_Plot_Data_Record)
       return Boolean;

| Return True if the gradient is currently visible

    procedure Set_Gradient_Colors
      (Data               : access Gtk_Plot_Data_Record;
       Min, Max           :        Gdk.Color.Gdk_Color);

| Set the colors that define the gradient. The colors will vary from Min to Max along the components specified in Set_Gradient_Mask.

    procedure Get_Gradient_Colors
      (Data               : access Gtk_Plot_Data_Record;
       Min, Max           : out    Gdk.Color.Gdk_Color);

| Return the colors that define the range

    procedure Set_Gradient
      (Data               : access Gtk_Plot_Data_Record;
       Min, Max           :        Gdouble;
       Nlevels            :        Gint);

| Define the values associated with the minimal color and the maximal color. Any value in between will have a color computed in between. Nlevels is the number of ticks to display in the gradient.

    procedure Get_Gradient
      (Data               : access Gtk_Plot_Data_Record;
       Min, Max           : out    Gdouble;
       Nlevels            : out    Gint);

| Return the values associated with the minimal and maximal colors.

    procedure Get_Gradient_Level
      (Data               : access Gtk_Plot_Data_Record;
       Level              :        Gdouble;
       Color              : out    Gdk.Color.Gdk_Color);

| Return the color associated with a specific level. The color depends on the parameters to Set_Gradient and Set_Gradient_Colors.

### User Data

It is possible to associated your own user data with a plot. This is the mechanism provided by the C version of gtkextra. However, the best way to do this in Ada is to inherit from Gtk_Plot_Data_Record (or one of its children), and add your own fields.

    procedure Set_Link
      (Data               : access Gtk_Plot_Data_Record;
       Link               :        System.Address);

| Associate some user data with Data. It is the responsability of the user to do some convert conversion to System.Address.

    function Get_Link
      (Data               : access Gtk_Plot_Data_Record)
       return System.Address;

| Return the user data associated with Data, or Null_Address if there is none.

    procedure Remove_Link
      (Data               : access Gtk_Plot_Data_Record);

| Remove the user data associated with Data.

[Contents] [Back] [Prev] [Up] [Next] [Forward]