view release on metacpan or  search on metacpan

lib/IUP/PPlot.pod  view on Meta::CPAN

=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/ctrl/iup_pplot.html

=head1 NAME

IUP::Plot - [GUI element] canvas-like element for creating 2D plots

=head1 DESCRIPTION

Creates a PPlot-based plot. PPlot is a library for creating plots that is system independent. 

It is available at SourceForge L<http://pplot.sourceforge.net|http://pplot.sourceforge.net/>.
However the standard PPlot distribution source code was changed for iup_pplot library 
(to improve features and visual appearance).

=begin HTML

<p>
  <table border="1">
    <tbody>
    <tr>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot0.gif" border="0"></td>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot1.gif" border="0"></td>
    </tr>
    <tr>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot2.gif" border="0"></td>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot3.gif" border="0"></td>
    </tr>
    <tr>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot4.gif" border="0"></td>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_pplot5.gif" border="0"></td>
    </tr>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $pplot = IUP::PPlot->new( TITLE=>"Simple Data", GRID=>"YES" );

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 Guide

Each plot can contain 2 B<axis> (X and Y), a B<title>, a B<legend>
B<box>, a B<grid>, a B<dataset> B<area> and as many B<datasets> you
want.

Each data set is added using the L<IUP::PPlotAdd |IUP::PPlotAdd> function. All other plot
parameters are configured by attributes.

If no attribute is set, the default values were selected to best
display the plot.

When setting attributes the plot is NOT redrawn until the REDRAW
attribute is set or a redraw event occurs.

The B<dataset area> is delimited by a margin. Data is only plotted
inside the dataset area. Axis and main title are positioned independent
of this margin. It is very important to set the margins when using axis
automatic scaling or the axis maybe hidden.

The B<legend box> is a list of the dataset names, each one drawn with
the same color of the correspondent dataset. The box is located in one
of the four corners of the dataset area.

The B<grid> is automatically spaced accordingly the current axis
displayed values.

The B<title> is always centered in the top of the plot.

The B<axis> are always positioned at the origin, except when
CrossOrigin is disabled, then it is positioned at the left-bottom. If
values are only positive then the origin will be placed in left bottom
position. If values are negative and positive then origin will be
placed inside the plot. The ticks in the axis are also automatically
distributed.

PPlot implementation demands that the MARGIN* attributes must be set so
the plot is not cropped.

=head2 Interaction

=head2 Zoom

Zoom in can be done selecting a region using the left mouse button.
Zoom out is done with a single click of the left mouse button. If the
B<Ctrl+X> key combination is pressed the zoom selection is restricted
to the X axis, the Y axis will be left unchanged. If the B<Ctrl+Y> key
combination is pressed the zoom selection is restricted to the Y axis,
the X axis will be left unchanged. If the B<Ctrl+R> key combination is
pressed the zoom selection is restored to a free rectangle.

Each zoom in operation is stacked, so each zoom out operation goes back
the the previous zoom selection.

Zoom operates on B<AXS_XMAX, AXS_XMIN, AXS_YMAX, AXS_YMIN> even 
if B<AUTOMIN/MAX> is enabled. The axis may be hidden depending on the
selected rectangle.

=head2 CrossHair Cursor

If you press the B<Ctrl+Shift> key combination, while holding the left
mouse button down, a cross hair cursor will be displayed for each
dataset in the plot. The X coordinate will control the cursor, the Y
coordinate will reflect each dataset correspondent value.

=head2 Selection and Editing

Selection and editing of a dataset can be enabled using the B<DS_EDIT>
attribute.

To select all the samples in the dataset press the B<Shift> key while
clicking with the left mouse button near a sample in the dataset. To
deselect all samples press the B<Shift> key while clicking with the
left mouse button in the background.

To select or deselect individual samples press the B<Ctrl> key while
clicking with the left mouse button near the sample in the dataset.

After selecting samples use the B<Del> key to remove the selected
samples. Also use the arrow keys to move the Y coordinate of the
selected samples. Press the B<Ctrl> key to increase the step size when

lib/IUP/PPlot.pod  view on Meta::CPAN

 $plot->PlotInsert2D($index, $sample_index, \@x, \@y);

Inserts an array of samples in the dataset B<ds_index> at the given
B<sample_index>. Can be used only after the dataset is added to the plot
(after L<PlotBegin|/"PlotBegin()">). B<sample_index> can be after the
last sample so data is appended to the array. Current data is shifted if necessary.

=head3 PlotTransform()

 ($ix, $iy) = $plot->PlotTransform($x, $y);

Converts coordinates in plot units to pixels. It should be used in
PREDRAW_CB and POSTDRAW_CB callbacks only. Output variables can be C<undef>
if not used. It can be used inside other callbacks, but make sure that
the drawing after a resize is done.

=head3 PlotPaintTo()

 $plot->PlotPaintTo($canvas);
 
Plots to the given canvas instead of the display canvas.

Handy if you want to save the plot into L<IUP::Canvas::SVG> or L<IUP::Canvas::EMF> like this:

  my $cnv = IUP::Canvas::SVG->new(filename=>"output.svg", width=>300, height=>210, resolution=>4);
  $mainplot->PlotPaintTo($cnv);
  $cnv->cdKillCanvas();

=head2 ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.)
see L<IUP::Manual::03_Attributes|IUP::Manual::03_Attributes>. Attributes specific to this element:

=head3 Basic

=over

=item B<REDRAW>

I<(write-only, non inheritable)> Redraw the plot and update
the display. Value is ignored. All other attributes will B<NOT> update
the display, so you can set many attributes without visual output.

=item B<USE_IMAGERGB>

I<(non inheritable)> Defines if the double buffer will
use standard driver image (NO - faster) or an RGB image (YES - slower).
Default: NO. The IMAGERGB driver has anti-aliasing which can improve
the line drawing.

=item B<USE_GDI+>

I<[Windows Only] (non inheritable)> Defines if the double
buffer will use GDI+ (YES) for drawing or standard GDI (NO). Default:
NO. The GDI+ driver has anti-aliasing which can improve the line
drawing.

=item B<L<FONT|IUP::Manual::03_Attributes/FONT>>

The font used in all text elements
of the plot: title, legend and labels.

=item B<L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>>

The background color. The
default value is white "255 255 255".

=item B<L<FGCOLOR|IUP::Manual::03_Attributes/FGCOLOR>>

The title color. The default
value is black "0 0 0".

=item B<TITLE>

I<(non inheritable)> The title. Located always at the top center area.

=item B<TITLEFONTSIZE, TITLEFONTSTYLE>

I<(non inheritable)> The title font size
and style. The default values depends on the FONT attribute and the
returned value is C<undef>. Set to C<undef>, to use the FONT attribute values.
Style can be "PLAIN", "BOLD", "ITALIC" or "BOLDITALIC".

=item B<MARGINLEFT, MARGINRIGHT, MARGINTOP, MARGINBOTTOM>

I<(non inheritable)> Margin of the dataset area. PPlot implementation demands that margins
must be set so the plot is not cropped. Default: "15", "15", "30", "15".

=back

=head3 Legend Configuration (non inheritable)

=over

=item B<LEGENDSHOW>

Shows or hides the legend box. Can be YES or NO.
Default: NO.

=item B<LEGENDPOS>

Legend box position. Can be: "TOPLEFT", "TOPRIGHT",
"BOTTOMLEFT", or "BOTTOMRIGHT. Default: "TOPRIGHT".

=item B<LEGENDFONTSIZE, LEGENDFONTSTYLE>

The legend box text font size and style.

=back

=head3 Grid Configuration (non inheritable)

=over

=item B<GRIDLINESTYLE>

Line style of the grid. Can be: "CONTINUOUS",
"DASHED", "DOTTED", "DASH_DOT", "DASH_DOT_DOT". Default is
"CONTINUOUS".

=item B<GRIDCOLOR>

Grid color. Default: "200 200 200".

=item B<GRID>

Shows or hides the grid in both or a specific axis. Can be:
YES (both), HORIZONTAL, VERTICAL or NO. Default: NO.

=back

=head3 Dataset Management (non inheritable)

=over

=item B<REMOVE>

I<(write-only)> Removes a dataset given its index.

=item B<CLEAR>

I<(write-only)> Removes all datasets. Value is ignored.

=item B<COUNT>

I<[read-only]> Total number of datasets.

=item B<CURRENT>

Current dataset index. Default is -1. When a dataset is
added it becomes the current dataset. The index starts at 0. All "DS_*"
attributes are dependent on this value.

=item B<DS_LEGEND>

Legend text of the current dataset. Default is
dynamically generated: "plot 0", "plot 1", "plot 2", ...

=item B<DS_COLOR>

Color of the current dataset and it legend text. Default
is dynamically generated for the 6 first datasets, others are default
to black "0 0 0". The first 6 are: 0="255 0 0", 1="0 0 255", 2="0 255
0", 3="0 255 255", 4="255 0 255", 5="255 255 0".

=item B<DS_MODE>

Drawing mode of the current dataset. Can be: "LINE", "BAR",
"MARK" or "MARKLINE". Default: "LINE". This must be set before other
"DS_*" attributes.

=item B<DS_LINESTYLE>

Line style of the current dataset. Can be:
"CONTINUOUS", "DASHED", "DOTTED", "DASH_DOT", "DASH_DOT_DOT". Default
is "CONTINUOUS".

=item B<DS_LINEWIDTH>

Line width of the current dataset. Default: 1.

=item B<DS_MARKSTYLE>

Mark style of the current dataset. Can be: "PLUS",
"STAR", "CIRCLE", "X", "BOX", "DIAMOND", "HOLLOW_CIRCLE", "HOLLOW_BOX",
"HOLLOW_DIAMOND". Default is "X".

=item B<DS_MARKSIZE>

Mark size of the current dataset. Default: 7.

=item B<DS_SHOWVALUES>

Enable or disable the display of the values near each
sample. Can be YES or NO. Default: NO.

=item B<DS_REMOVE>

I<(write-only)> Removes a sample from the current dataset given its index.

=item B<DS_EDIT>

Enable or disable the current dataset selection and
editing. Can be YES or NO. Default: NO.

=back

=head3 Axis Configuration (non inheritable)

=over

=item B<AXS_XCOLOR, AXS_YCOLOR>

Axis, ticks and label color. Default: "0 0 0".

=item B<AXS_XMAX, AXS_XMIN, AXS_YMAX, AXS_YMIN>

Minimum and maximum
displayed values of the respective axis. Automatically calculated
values when AUTOMIN or AUTOMAX are enabled.