IupPPlot

Creates a plot of one or more data sets. It inherits from IupCanvas. Uses the PPlot library.

PPlot is a library for creating plots that is system independent. It is maintained by Pier Philipsen (pierphil@xs4all.nl) and available at SourceForge http://pplot.sourceforge.net/ with a very flexible BSD License). IupPPlot library includes the PPlot source code so no external references are needed. Also the standard PPlot distribution source code was changed to improve features and visual appearance.

IupPPlot first implementation was written by Marian Trifon (mtrif@katamail.com), then completed and documented by the IUP team.

Initialization and Usage

The IupPPlotOpen function must be called after a IupOpen, so that the control can be used. The "iup_pplot.h" file must also be included in the source code. The program must be linked to the controls library (iup_pplot), and with the CD library.

To make the control available in Lua use require"iuplua_pplot" or manually call the initialization function in C, iuppplotlua_open, after calling iuplua_open.  When manually calling the function the iuplua_pplot.h file must also be included in the source code and the program must be linked to the Lua control library (iuplua_pplot).

Guide

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

Each data set is added using the Auxiliary Functions. 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 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 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 grid is automatically spaced accordingly the current axis displayed values.

The title is always centered in the top of the plot.

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

Interaction

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 Ctrl+X key combination is pressed the zoom selection is restricted to the X axis, the Y axis will be left unchanged. If the Ctrl+Y key combination is pressed the zoom selection is restricted to the Y axis, the X axis will be left unchanged. If the Ctrl+R key combination is pressed the zoom selection is restored to a free rectangle.

The mouse Wheel will pan in the vertical direction, and when Shift is pressed will pan in the horizontal direction. (Since 3.9)

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

Zoom operates on AXS_XMAX, AXS_XMIN, AXS_YMAX, AXS_YMIN even if AUTOMIN/MAX is enabled. The axis may be hidden depending on the selected rectangle. The AUTOMIN/MAX attributes will be disabled during zoom in, and restored when zoom out completely.

CrossHair Cursor

If you press the 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.

Selection and Editing

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

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

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

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

Creation

Ihandle* IupPPlot(void); [in C]
iup.pplot{} -> (elem: ihandle) [in Lua]
pplot() [in LED]

This function returns the identifier of the created plot, or NULL if an error occurs.

Auxiliary Functions

void IupPPlotBegin(Ihandle* ih, int strXdata); [in C]
iup.PPlotBegin(ih: ihandle, strXdata: number) [in Lua]

Prepares a dataset to receive samples. If strXdata is 1 then the X axis value is a string.


void IupPPlotAdd(Ihandle* ih, float x, float y); [in C]
iup.PPlotAdd(ih: ihandle, x, y: number) [in Lua]

Adds a sample to the dataset. Can only be called if IupPPlotBegin was called with strXdata=0.


void IupPPlotAddStr(Ihandle* ih, const char* x, float y); [in C]
iup.PPlotAddStr(ih: ihandle, x: string, y: number) [in Lua]

Same as IupPPlotAdd, but allows to use a string as the X axis value. Can only be called if IupPPlotBegin was called with strXdata=1.


int IupPPlotEnd(Ihandle* ih); [in C]
iup.PPlotEnd(ih: ihandle) -> (index: number) [in Lua]

Adds a 2D dataset to the plot and returns the dataset index. The data set can be empty. Redraw is NOT done until the REDRAW attribute is set. Also it will change the current dataset index to the return value. You can only set attributes of a dataset AFTER you added the dataset.  Can only be called if IupPPlotBegin was called. Whenever you create a dataset all its "DS_*" attributes will be set to the default values. Notice that DS_MODE must be set before other "DS_*" attributes.


void IupPPlotInsert(Ihandle *ih, int index, int sample_index, float x, float y); [in C]
void IupPPlotInsertStr(Ihandle *ih, int index, int sample_index, const char* x, float y);
iup.PPlotInsert(ih: ihandle, index, sample_index, x, y: number) [in Lua]
iup.PPlotInsertStr(ih: ihandle, index, sample_index: number, x: string, y: number)

Inserts a sample in a dataset at the given sample_index. Can be used only after the dataset is added to the plot.


void IupPPlotInsertPoints(Ihandle *ih, int index, int sample_index, float* x, float* y, int count); [in C]
void IupPPlotInsertStrPoints(Ihandle *ih, int index, int sample_index, const char** x, float* y, int count);
iup.PPlotInsertPoints(ih: ihandle, index, sample_index: number, x, y: table of number) [in Lua]
iup.PPlotInsertStrPoints(ih: ihandle, index, sample_index: number, x, y: table of number)

Inserts an array of samples in a dataset at the given sample_index. Can be used only after the dataset is added to the plot. (Since 3.4)


void IupPPlotAddPoints(Ihandle *ih, int index, float* x, float* y, int count); [in C]
void IupPPlotAddStrPoints(Ihandle *ih, int index, const char** x, float* y, int count);
iup.PPlotAddPoints(ih: ihandle, index: number, x, y: table of number) [in Lua]
iup.PPlotAddStrPoints(ih: ihandle, index: number, x, y: table of number)

Adds an array of samples in a dataset at the end. Can be used only after the dataset is added to the plot. (Since 3.4)


void IupPPlotGetSample(Ihandle *ih, int index, int sample_index, float *x, float *y); [in C]
void IupPPlotGetSampleStr(Ihandle *ih, int index, int sample_index, const char* *x, float *y);
iup.PPlotGetSample(ih: ihandle, index, sample_index: number) -> (x, y: number) [in Lua]
iup.PPlotGetSampleStr(ih: ihandle, index, sample_index: number) -> (x: string, y: number)

Returns the sample value in a dataset at the given sample_index. Can be used only after the dataset is added to the plot. (since 3.11)


void IupPPlotTransform(Ihandle* ih, float x, float y, int *ix, int *iy); [in C]
iup.PPlotTransform(ih: ihandle, x, y: number) -> (ix, iy: number) [in Lua]

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


void IupPPlotPaintTo(Ihandle* ih, cdCanvas* cnv); [in C]
iup.PPlotPaintTo(ih: ihandle, cnv: cdCanvas) [in Lua]

Plots to the given CD canvas instead of the display canvas.

Attributes

CANVAS (read-only) (non inheritable): returns the internal CD canvas where the draw operation occurs. (since 3.11)

REDRAW (write-only) (non inheritable): redraw all plots and update the display. All other attributes will NOT update the display, so you can set many attributes without visual output. Value can be NULL. If value is "NOFLUSH" rendering is performed internally but display is not updated. If value is "CURRENT" only the current plot defined by "PLOT_CURRENT" will be updated and it will behave as "NOFLUSH" (since 3.11).

SYNCVIEW (non inheritable): when a plot view is changed by interactive zoom or pan, the other plots are zoomed or panned accordingly. (since 3.9)

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

USE_CONTEXTPLUS (non inheritable): defines if the CD canvas will use ContextPlus drivers (YES) for drawing or standard drivers (NO). Default: NO. The ContextPlus drivers has anti-aliasing which can improve the line drawing. (renamed from USE_GDI+ in 3.8)

Multiple Plots Management (non inheritable) (since 3.9)

PLOT_COUNT: defines the number of multiple plots in the same control. Default: 1. The minimum value is 1. If set to a smaller value will automatically remove the remaining plots. If set to a larger value will automatically add new plots at the end. The maximum number of plots is 20.

PLOT_NUMCOL: defines the number of columns for multiple plot. Default: 1. The plots will fill the space starting at the first line at the top from left to right. If there is not enough plots to fill all columns an empty space will be displayed.

PLOT_CURRENT: current plot index. Default: 0. All plot attributes are dependent on this value. When set can use also the TITLE name as value.

PLOT_INSERT (write-only): inserts a new plot at the given index. If value is NULL will append after the last plot. Value can also be the TITLE of an existing plot. When a new plot is inserted it becomes the current plot.

PLOT_REMOVE (write-only): removes a plot given its index. If value is NULL the current plot is removed. Value can also be the TITLE of an existing plot.

Plot Configuration (non inheritable)

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

BGCOLOR: the background color of the plot. The default value is white "255 255 255".

MARGINLEFT, MARGINRIGHT, MARGINTOP, MARGINBOTTOM (non inheritable): margin of the dataset area in pixels. PPlot implementation demands that margins must be set so the plot is not cropped. Default: "15", "15", "30", "15".

Title Configuration (non inheritable)

FGCOLOR: the title color. The default value is black "0 0 0".

TITLE (non inheritable): the title. Located always at the top center area.

TITLEFONTSIZE, TITLEFONTSTYLE (non inheritable): the title font size and style. The default values depends on the FONT attribute and the returned value is NULL. Set to NULL, to use the FONT attribute values. Style can be "PLAIN", "BOLD", "ITALIC" or "BOLDITALIC". The size is provided in points (1/72 inch) or in pixels (using negative values).

Legend Configuration (non inheritable)

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

LEGENDPOS: legend box position. Can be: "TOPLEFT", "TOPRIGHT", "BOTTOMLEFT", "BOTTOMRIGHT, or "BOTTOMCENTER". Default: "TOPRIGHT". The legend box is displayed inside the plot area, except for BOTTOMCENTER that is displayed bellow the plot area, along with the axis. ("BOTTOMCENTER" since 3.9)

LEGENDFONTSIZE, LEGENDFONTSTYLE: the legend box text font size and style.

Grid Configuration (non inheritable)

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

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

GRIDCOLOR: grid color. Default: "200 200 200".

Dataset List Management (non inheritable)

REMOVE (write-only): removes a dataset given its index or its DS_LEGEND name (DS_LEGEND since 3.9). Notice that after removing a dataset the other datasets indices that are greater than the given index will be updated.

CLEAR (write-only): removes all datasets. Value is ignored.

COUNT [read-only]: total number of datasets.

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. When set can use also the DS_LEGEND name as value (since 3.9).

Dataset Configuration (non inheritable)

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

DS_COLOR: color of the current dataset and it legend text. Default is dynamically set from the list "255 0 0", "0 255 0", "0 0 255", "0 255 255", "255 0 255", "255 255 0", "128 0 0", "0 128 0", "0 0 128", "0 128 128", "128 0 128", "128 128 0". If the color is not already being used in an existent dataset then it is used as the new default. If all defaults are used then black is used "0 0 0". (added more colors and existing check since 3.9)

DS_COUNT: returns the number of samples of the current dataset. (since 3.6)

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.

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

DS_LINEWIDTH: line width of the current dataset. Default: 1.

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

DS_MARKSIZE: mark size of the current dataset in pixels. Default: 7.

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

DS_REMOVE (write-only): removes a sample from the current dataset given its index.

DS_EDIT: enable or disable the current dataset interactive selection and editing. Can be YES or NO. Default: NO.

Axis Configuration (non inheritable)

AXS_XCOLOR, AXS_YCOLOR: axis, ticks and label color. Default: "0 0 0".

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. Interactive zoom will change this values during run time.

AXS_XAUTOMIN, AXS_XAUTOMAX, AXS_YAUTOMIN, AXS_YAUTOMAX: configures the automatic scaling of the minimum and maximum display values. Can be YES or NO. Default: YES. They will be disabled during zoom in and restored when zoom out completely.

AXS_XLABEL, AXS_YLABEL: text label of the  respective axis.

AXS_XLABELCENTERED, AXS_YLABELCENTERED: text label position at center (YES) or at top/right (NO). Default: YES.

AXS_XREVERSE, AXS_YREVERSE: reverse the axis direction. Can be YES or NO. Default: NO. Default is Y oriented bottom to top, and X oriented from left to right.

AXS_XCROSSORIGIN, AXS_YCROSSORIGIN: allow the axis to cross the origin and to be placed inside the dataset area. Can be YES or NO. Default: YES.

AXS_XSCALE, AXS_YSCALE: configures the scale of the respective axis. Can be: LIN (liner), LOG10 (base 10), LOG2 (base 2) and LOGN (base e). Default: LIN.

AXS_XFONTSIZE, AXS_YFONTSIZE, AXS_XFONTSTYLE, AXS_YFONTSTYLE: axis label text font size and style. See TITLEFONTSIZE and TITLEFONTSTYLE.

Axis Ticks Configuration (non inheritable)

AXS_XTICK, AXS_YTICK: enable or disable the axis tick display. Can be YES or NO. Default: YES.

AXS_XTICKFORMAT, AXS_YTICKFORMAT: axis tick number C format string. Default: "%.0f".

AXS_XTICKFONTSIZE, AXS_YTICKFONTSIZE, AXS_XTICKFONTSTYLE, AXS_YTICKFONTSTYLE: axis tick number font size and style.  See TITLEFONTSIZE and TITLEFONTSTYLE.

AXS_XAUTOTICK, AXS_YAUTOTICK: configures the automatic tick spacing. Can be YES or NO. Default: YES. Notice that when enabled the attributes *TICKMAJORSPAN, *TICKDIVISION, and *TICKFORMAT are affected during tick computation.

AXS_XTICKMAJORSPAN, AXS_YTICKMAJORSPAN: The spacing between major ticks. Default is 1 when AUTOTICK is disabled.

AXS_XTICKDIVISION, AXS_YTICKDIVISION: number of minor ticks intervals between each major tick. Default is 5 when AUTOTICK is disabled.

AXS_XAUTOTICKSIZE, AXS_YAUTOTICKSIZE: configures the automatic tick size. Can be YES or NO. Default: YES.

AXS_XTICKSIZE, AXS_YTICKSIZE: size of minor ticks in pixels. Default is 5 when AUTOTICKSIZE is disabled.

AXS_XTICKMAJORSIZE, AXS_YTICKMAJORSIZE: size of major ticks in pixels. Default is 8 when AUTOTICKSIZE is disabled.


ACTIVE, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE: also accepted. 

Callbacks

DELETE_CB: Action generated when the Del key is pressed to removed a sample from a dataset. If multiple points are selected it is called once for each selected point.

int function(Ihandle *ih, int index, int sample_index, float x, float y); [in C]
elem:delete_cb(index, sample_index, x, y: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
index: index of the dataset
sample_index: index of the sample in the dataset
x
: X coordinate value of the sample
y: Y coordinate value of the sample

Returns: If IUP_IGNORE then the sample is not deleted.

DELETEBEGIN_CB, DELETEEND_CB: Actions generated when a delete operation will begin or end. But they are called only if DELETE_CB is also defined.

int function(Ihandle *ih); [in C]
elem:deletebegin_cb() -> (ret: number) [in Lua]
elem:deleteend_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

Returns: If DELETEBEGIN_CB returns IUP_IGNORE the delete operation for all the selected samples are aborted.

SELECT_CB: Action generated when a sample is selected. If multiple points are selected it is called once for each new selected point. It is called only if the selection state of the sample is about to be changed.

int function(Ihandle *ih, int index, int sample_index, float x, float y, int select); [in C]
elem:select_cb(index, sample_index, x, y, select: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
index: index of the dataset
sample_index: index of the sample in the dataset
x
: X coordinate value of the sample
y: Y coordinate value of the sample
select: boolean value that a non zero value indicates if the point is to be selected.

Returns: If IUP_IGNORE then the sample is not selected.

SELECTBEGIN_CB, SELECTEND_CB: Actions generated when a selection operation will begin or end. But they are called only if SELECT_CB is also defined.

int function(Ihandle *ih); [in C]
elem:selectbegin_cb() -> (ret: number) [in Lua]
elem:selectend_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

Returns: If SELECTBEGIN_CB returns IUP_IGNORE the selection operation is aborted.

EDIT_CB: Action generated when a sample is selected. If multiple points are selected it is called once for each new selected point. It is called only if the selection state of the sample is about to be changed.

int function(Ihandle *ih, int index, int sample_index, float x, float y, float *new_x, float *new_y); [in C]
elem:edit_cb(index, sample_index, x, y, new_x, new_y: number) -> (new_x, new_y, ret: number) [in Lua]

ih: identifier of the element that activated the event.
index: index of the dataset
sample_index: index of the sample in the dataset
x
: X coordinate value of the sample
y: Y coordinate value of the sample
new_x: the new X coordinate value of the sample
new_y: the new Y coordinate value of the sample

Returns: If IUP_IGNORE then the sample is not edited. The application can changed the new value before it is edited.

EDITBEGIN_CB, EDITEND_CB: Actions generated when an editing operation will begin or end. But they are called only if EDIT_CB is also defined.

int function(Ihandle *ih); [in C]
elem:editbegin_cb() -> (ret: number) [in Lua]
elem:editend_cb() -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.

Returns: If EDITBEGIN_CB returns IUP_IGNORE the editing operation is aborted.

PLOTBUTTON_CB: similar to BUTTON_CB but coordinates are float in plot scale. It is called before the internal processing, if returns IUP_IGNORE internal processing will not be done. (since 3.9)

PLOTMOTION_CB: similar to MOTION_CB but coordinates are float in plot scale. It is called before the internal processing, if returns IUP_IGNORE internal processing will not be done. (since 3.9)

PREDRAW_CB, POSTDRAW_CB: Actions generated before and after the redraw operation. Predraw can be used to draw a different background and Postdraw can be used to draw additional information in the plot. Predraw has no restrictions, but Postdraw is clipped to the dataset area. To position elements in plot units, use the IupPPlotTransform function.

int function(Ihandle *ih, cdCanvas* cnv); [in C]
elem:predraw_cb(cnv: cdCanvas) -> (ret: number) [in Lua]
elem:postdraw_cb(cnv: cdCanvas) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
cnv
: the internal CD canvas where the draw operation occurs.


MAP_CB, UNMAP_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

Examples

Browse for Example Files

See Also

IupCanvas, IupMglPlot