IupPlot

IupPlot (since 3.12)

Creates a plot of one or more data sets. It inherits from IupCanvas.

This is an additional control that depends on the CD library. It is included in the IupControls library.

It completely replaces the old IupPPlot control. This control eliminates all the limitations and issues we have with the PPlot library. But we reused several PPlot source code parts, so we would like to thank the author Pier Philipsen for making it with a with a very flexible BSD License. We also would like to thank Marian Trifon for the first IupPPlot implementation which part was also reused here.

Initialization and Usage

The IupPlotOpen function must be called after a IupOpen, so that the control can be used. The "iup_plot.h" file must also be included in the source code. The program must be linked to the controls library (iup_plot). When statically linking must be linked with the main CD library cd, with the cdgl library, with the cdcontextplus library, and with the iupgl library, notice that cdpdl depends on ftgl and cdcontextplus depends on gdiplus on Windows.

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

Guide

The control can contain more than one plot in a rectangular grid. Each plot will then has an exclusive plot area inside the control. When it is just one plot this area will occupy the whole control area. The plot attributes are set based on the current plot.

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. IupPlot support plots of linear sequential data, as a sequence of 2D samples ([x1,y1],[x2,y2],...) coordinates. The dataset attributes are set based on the current dataset.

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.

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

The grid is automatically spaced accordingly the current axis major ticks.

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

The axis are positioned at the left-bottom by default. When cross-origin is enabled, then it is positioned at the origin and zoom and pan will affect its position. Cross-origin will be automatically disabled in the other axis if a logarithm scale is used.

Interaction

Zoom & Pan

Zoom can be done while pressing the Ctrl key and interacting with the control. A single click is with the left mouse button will zoom in by 10%, a single click with the right mouse button will zoom out by 10%. The same result can be obtained by moving the mouse wheel. To zoom in to a region, click with the left mouse button, drag to form a selection rectangle and release the button. In all cases the Ctrl key must be pressed during the interaction.

Zoom can be reset by double clicking with the left mouse button or pressing the "." key. Zoom in and out can also be performed using the "+" and "-" keys respectively.

Pan is performed after zoom in and it does not uses the Ctrl key. Simply click with the left mouse button and drag the plot to pan. The mouse wheel will pan in the vertical direction by default, and when Shift is pressed will pan in the horizontal direction. Pan can also be performed using the arrow keys, and with the PgDn/PgUp keys. A single click with the middle mouse button will try to position the origin at that coordinate.

Zoom and Pan operate 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. The zoom out and pan are limited to the original attribute values when zoom in started.

Cross Hair & TIP

The cross hair cursor is activated and deactivated using the Ctrl+H or Ctrl+V key combinations. When Ctrl+H is used the X coordinate will control the cursor, the Y coordinate will reflect each dataset correspondent value (an Horizontaly controlled cross-hair). When Ctrl+V is used the Y coordinate will control the cursor, the X coordinate will reflect each dataset correspondent value (a Vertically controlled cross-hair).

When the cursor is close to a sample, a TIP will be shown with the dataset name, sample index and coordinate values.

Selection

Selection can be done while pressing the Shift key and interacting with the control. To select all the samples inside a region, click with the left mouse button, drag to form a selection rectangle and release the button (while pressing the Shift key). The new selection will always replace the previous one.

To clear the selection just select an empty region or select an area with no samples. Pressing the Esc key will also clear the selection.

After selecting samples use the Del key to remove the selected samples, but this will only work if READONLY=NO.

Selection and delete behavior can be controlled using the respective callbacks.

Context Menu

The context menu is shown by a single click with the right mouse button when MENUCONTEXT=Yes. The default menu contains the following items:

Zoom In  +
Zoom Out -
Reset Zoom  .
-----------
Show/Hide Legend
Show/Hide Grid 
-----------
Copy As Picture      (copy to clipboard, EMF format)
Copy As Bitmap
-----------
Export to SVG...     (export the plot to a metafile, SVG format)
Export to EPS...     ( " , EPS format )
Export to CGM...     ( " , CGM format) 
Export to EMF...     ( " , EMF format, windows only)
Export to WMF...     ( " , EMF format, windows only)
-----------
Print...
-----------
Data Set Values...      (only when MENUITEMPROPERTIES=Yes)
Data Set Properties...  (only when MENUITEMPROPERTIES=Yes)
Properties...           (only when MENUITEMPROPERTIES=Yes)

The "Data Set Values..." dialog is available only if the IupMatrixEx control is initialized and ready to be used. Also the dialog in read-only by default, to enable the editing of values on the dialog set EDITABLEVALUES=Yes. It is shown for the current Dataset. (since 3.21)

The "Data Set Properties..." dialog is shown for the current Dataset. The "Properties..." dialog is shown for the current Plot.

Context menu behavior can be controlled using the respective callbacks.

Creation

Ihandle* IupPlot(void); [in C]
iup.plot{} -> (ih: ihandle) [in Lua]
plot() [in LED]

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

Auxiliary Functions

void IupPlotBegin(Ihandle* ih, int strXdata); [in C]
iup.PlotBegin(ih: ihandle, strXdata: number) [in Lua]
or ih:Begin(strXdata: number) [in Lua]

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

void IupPlotAdd(Ihandle* ih, double x, double y); [in C]
iup.PlotAdd(ih: ihandle, x, y: number) [in Lua]
or ih:Add(x, y: number) [in Lua]

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

void IupPlotAddSegment(Ihandle* ih, double x, double y); [in C]
iup.PlotAddSegment(ih: ihandle, x, y: number) [in Lua]
or ih:AddSegment(x, y: number) [in Lua]

Same as IupPlotAdd, but the sample starts a new segment. In drawing mode where samples are connected by lines this will create an empty space. (since 3.13)

void IupPlotAddStr(Ihandle* ih, const char* x, double y); [in C]
iup.PlotAddStr(ih: ihandle, x: string, y: number) [in Lua]
or ih:AddStr(x: string, y: number) [in Lua]

Same as IupPlotAdd, but allows to use a string as the X axis value. Can only be called if IupPlotBegin was called with strXdata=1. Strings will be shown only in linear scale, they will not be shown in Logarithm scale.

int IupPlotEnd(Ihandle* ih); [in C]
iup.PlotEnd(ih: ihandle) -> (ds_index: number) [in Lua]
or ih:End() -> (ds_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 IupPlotBegin was called. Whenever you create a dataset all its "DS_*" attributes will be set to the default values.

int IupPlotLoadData(Ihandle *ih, const char* filename, int strXdata); [in C]
iup.PlotLoadData(ih: ihandle, filename: string, strXdata: number) -> (ret: number) [in Lua]
or ih:LoadData(filename: string, strXdata: number) -> (ret: number) [in Lua]

Creates new datasets from data stored in a file. The file must contains space (' '), tab ('\t') or semicolon (';') separated numeric data in text format. The text can contains line comments starting with '#'. The file can have more than one dataset but the first column will always be the X coordinate of all datasets. If strXdata=1 then the first column is treated as a string. The first line will define the number of datasets. The file must have at least two columns of data. Returns a non zero value is successful, or a zero value if failed. Notice that if it fails during data read, but after the fist line, the datasets were already created and they will not be destroyed when the function returns.

void IupPlotInsert(Ihandle *ih, int ds_index, int sample_index, double x, double y); [in C]
void IupPlotInsertSegment(Ihandle *ih, int ds_index, int sample_index, const char* x, double y);
void IupPlotInsertStr(Ihandle *ih, int ds_index, int sample_index, const char* x, double y);
iup.PlotInsert(ih: ihandle, ds_index, sample_index, x, y: number) [in Lua]
or ih:Insert(ds_index, sample_index, x, y: number) [in Lua]
iup.PlotInsertSegment(ih: ihandle, ds_index, sample_index: number, x: string, y: number)
or ih:InsertSegment(ds_index, sample_index: number, x: string, y: number)
iup.PlotInsertStr(ih: ihandle, ds_index, sample_index: number, x: string, y: number)
or ih:InsertStr(ds_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 IupPlotInsertSamples(Ihandle *ih, int ds_index, int sample_index, double* x, double* y, int count); [in C]
void IupPlotInsertStrSamples(Ihandle *ih, int ds_index, int sample_index, const char** x, double* y, int count);
iup.PlotInsertSamples(ih: ihandle, ds_index, sample_index: number, x, y: table of number, count: number) [in Lua]
or ih:InsertSamples(ds_index, sample_index: number, x, y: table of number, count: number) [in Lua]
iup.PlotInsertStrSamples(ih: ihandle, ds_index, sample_index: number, x, y: table of number, count: number)
or ih:InsertStrSamples(ds_index, sample_index: number, x, y: table of number, count: 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.

void IupPlotAddSamples(Ihandle *ih, int ds_index, double* x, double* y, int count); [in C]
void IupPlotAddStrSamples(Ihandle *ih, int ds_index, const char** x, double* y, int count);
iup.PlotAddSamples(ih: ihandle, ds_index: number, x, y: table of number, count: number) [in Lua]
or ih:AddSamples(ds_index: number, x, y: table of number, count: number) [in Lua]
iup.PlotAddStrSamples(ih: ihandle, ds_index: number, x, y: table of number, count: number)
or ih:AddStrSamples(ds_index: number, x, y: table of number, count: number)

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

void IupPlotGetSample(Ihandle *ih, int ds_index, int sample_index, double *x, double *y); [in C]
void IupPlotGetSampleStr(Ihandle *ih, int ds_index, int sample_index, const char* *x, double *y);
iup.PlotGetSample(ih: ihandle, ds_index, sample_index: number) -> (x, y: number) [in Lua]
or ih:GetSample(ds_index, sample_index: number) -> (x, y: number) [in Lua]
iup.PlotGetSampleStr(ih: ihandle, ds_index, sample_index: number) -> (x: string, y: number)
or ih:GetSampleStr(ds_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.

int IupPlotGetSampleSelection(Ihandle *ih, int ds_index, int sample_index); [in C]
iup.PlotGetSampleSelection(ih: ihandle, ds_index, sample_index: number) -> (selected: number) [in Lua]
or ih:GetSampleSelection(ds_index, sample_index: number) -> (selected: number) [in Lua]

Returns the sample selected state in a dataset at the given sample_index. Can be used only after the dataset is added to the plot. By default all samples are not selected. Returns -1 if an error occurred.

double IupPlotGetSampleExtra(Ihandle *ih, int ds_index, int sample_index); [in C]
iup.PlotGetSampleExtra(ih: ihandle, ds_index, sample_index: number) -> (extra: number) [in Lua]
or ih:GetSampleExtra(ds_index, sample_index: number) -> (extra: number) [in Lua]

Returns the sample extra value in a dataset at the given sample_index. Can be used only after the dataset is added to the plot. By default all samples have an extra of 0. Returns -1 if an error occurred. (since 3.18)

void IupPlotSetSample(Ihandle *ih, int ds_index, int sample_index, double x, double y); [in C]
void IupPlotSetSampleStr(Ihandle *ih, int ds_index, int sample_index, const char* x, double y);
iup.PlotSetSample(ih: ihandle, ds_index, sample_index, x, y: number) [in Lua]
or ih:SetSample(ds_index, sample_index, x, y: number) [in Lua]
iup.PlotSetSampleStr(ih: ihandle, ds_index, sample_index, x: string, y: number) [in Lua]
or ih:SetSampleStr(ds_index, sample_index: number, x: string, y: number) [in Lua]

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

void IupPlotSetSampleSelection(Ihandle *ih, int ds_index, int sample_index, int selected); [in C]
iup.PlotSetSampleSelection(ih: ihandle, ds_index, sample_index, selected: number) [in Lua]
or ih:SetSampleSelection(ds_index, sample_index, selected: number) [in Lua]

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

void IupPlotSetSampleExtra(Ihandle *ih, int ds_index, int sample_index, double extra); [in C]
iup.PlotSetSampleExtra(ih: ihandle, ds_index, sample_index, extra: number) [in Lua]
or ih:SetSampleExtra(ds_index, sample_index, extra: number) [in Lua]

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

void IupPlotTransform(Ihandle* ih, double x, double y, double *cnv_x, double *cnv_y); [in C]
iup.PlotTransform(ih: ihandle, x, y: number) -> (cnv_x, cnv_y: number) [in Lua]
or ih:Transform(x, y: number) -> (cnv_x, cnv_y: number) [in Lua]

Converts coordinates in plot units to pixels. It should be used inside callbacks only. Output variables can be NULL if not used. Y canvas coordinates is in CD bottom to top orientation.

void IupPlotTransformTo(Ihandle* ih, double cnv_x, double cnv_y, double *x, double *y); [in C]
iup.PlotTransformTo(ih: ihandle, cnv_x, cnv_y: number) -> (x, y: number) [in Lua]
or ih:TransformTo(cnv_x, cnv_y: number) -> (x, y: number) [in Lua]

Converts coordinates from pixels to plot coordinates. It should be used inside callbacks only. Output variables can be NULL if not used. Y canvas coordinates is in CD bottom to top orientation.

int IupPlotFindSample(Ihandle* ih, double cnv_x, double cnv_y, int *ds_index, int *sample_index); [in C]
iup.PlotFindSample(ih: ihandle, cnv_x, cnv_y: number) -> (ret, ds_index, sample_index: number) [in Lua]
or ih:FindSample(cnv_x, cnv_y: number) -> (ret, ds_index, sample_index: number) [in Lua]

Returns the nearest sample of the nearest dataset within a tolerance neighborhood. Tolerance can be set in SCREENTOLERANCE attribute. Returns a non zero value is successful, or a zero value if failed. It should be used inside callbacks only. Output variables can be NULL if not used. The datasets are searched in reverse order they are drawn. Y canvas coordinates is in CD bottom to top orientation. (since 3.13)

int IupPlotFindSegment(Ihandle* ih, double cnv_x, double cnv_y, int *ds_index, int *sample_index1, int *sample_index2); [in C]
iup.PlotFindSegment(ih: ihandle, cnv_x, cnv_y: number) -> (ret, ds_index, sample_index1, sample_index2: number) [in Lua]
or ih:FindSegment(cnv_x, cnv_y: number) -> (ret, ds_index, sample_index1, sample_index2: number) [in Lua]

Returns the nearest segment of the nearest dataset within a tolerance neighborhood. Tolerance can be set in SCREENTOLERANCE attribute. Returns a non zero value is successful, or a zero value if failed. It should be used inside callbacks only. Output variables can be NULL if not used. The datasets are searched in reverse order they are drawn. Y canvas coordinates is in CD bottom to top orientation. Only works when DS_MODE is LINE, MARKLINE, AREA, STEP or ERRORBAR.(since 3.21)

void IupPlotPaintTo(Ihandle* ih, cdCanvas* cnv); [in C]
iup.PlotPaintTo(ih: ihandle, cnv: cdCanvas) [in Lua]
or ih:PaintTo(cnv: cdCanvas) [in Lua]

Plots to the given CD canvas instead of the display canvas. The element does not need to be mapped neither to be inside a dialog for this function to work.

void IupPlotSetFormula(Ihandle* ih, int sample_count, const char* formula, const char* init); [in C]
iup.PlotSetFormula(ih: ihandle, sample_count: number, formula: string [init: string]) [in Lua]
or ih:SetFormula(sample_count: number, formula: string [init: string]) [in Lua]

Creates a new dataset and generate samples using the formula (since 3.13). The formula is executed for each sample within the dataset. Internally uses Lua to parse the formula. init is an optional Lua initialization code that is called only once (can be NULL). The callback "int FORMULAINIT_CB(Ihandle* ih, lua_State *L);" can also be used to initialize the Lua state. All Lua standard libraries are pre-loaded.

This function is available in the "iupluaplot" library but it does not requires an active Lua context, because it uses a temporary Lua context. If called from Lua it will also be independent from the application's Lua context. To use it in C/C++ you must link also with Lua and iuplua even when not using theses libraries directly.

The formula will be encapsulated within an internal Lua function so it will not affect the call of subsequent samples. This internal function receives two parameters "sample_index" and "x" correspondent to the current sample being processed during script execution. "y" will be calculated by the formula. The formula can contain only one valid Lua statement that will be retuned by the internal Lua function. The formula can evaluate to numbers only. The x parameter will vary from FORMULA_MIN and FORMULA_MAX attributes those default values are 0.0 and 1.0. The interval will be divided in sample_count-1 steps.

If the attribute FORMULA_PARAMETRIC is set to Yes, then the second attribute is replaced by "t". The interval and the steps are the same BUT the formula must then return 2 numeric parameters: "x, y".

The most commonly used tokens are:

+  (addition) 
-  (subtraction and negation) 
*  (multiplication) 
/  (division) 
%  (modulo)
^  (exponentiation)
== (equal)
~= (different)
<  (less than)
>  (greater than)
<= (less than or equal)
>= (greater than or equal)
and (logical and)
or  (logical or)
not (logical not)

The Lua Math Functions are loaded also at the global level, so there is no need for the "math." prefix. The most commonly used functions are:

abs(x)    acos(x)    asin(x)    atan(x)    atan2(y,x)    ceil(x)    cos(x)
deg(x)    exp(x)     floor(x)   log(x)     min(x,...)    max(x,...) pow(x,y)
sin(x)    sqrt(x)    tan(x)

Some formula examples:

"cos(pi*x)"
"x^2"
"cos(t), sin(t)"

Attributes (All non inheritable, except when noted)

ANTIALIAS: Enable or disable the anti-aliasing support when available. Default: Yes.

CANVAS (read-only): returns the internal CD canvas where the draw operation occurs. Works only after mapped.

GRAPHICSMODE: the internal graphics mode. Can be set only before map. Can be OPENGL, IMAGERGB, NATIVEPLUS or NATIVE. OPENGL will use OpenGL, it is faster for big data sets but text has a slightly slower quality, and has alpha and anti-aliasing support. IMAGERGB is the slowest, has the same text issues as OpenGL, but also has alpha and anti-aliasing support. NATIVE is the system default (GDI in Windows, GDK/Cairo in GTK 2/3, X11 in Motif) it has the best text render, it is fast for regular datasets, but it does not have anti-aliasing nor alpha (except in GTK 3). NATIVEPLUS uses GDI+ in Windows and Cairo in GTK 2, so it has anti-aliasing and alpha support. Default: NATIVEPLUS.

READONLY: allow the selected samples to be removed when the Del key is pressed.

REDRAW (write-only): 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". Works only after mapped.

SYNCVIEW: when a plot view is changed by interactive zoom or pan, the other plots are zoomed or panned accordingly.

MERGEVIEW: all plots are drawn in the same area. The margins are changed to define a single area in the same space. Interaction is done with the plot 0 by default, but can be altered for plot 1 (Shift key), plot 2 (Ctrl key) or plot 3 (Alt key). (since 3.27)

SHOWCROSSHAIR: shows the crosshair cursor. Can be: NONE, HORIZONTAL, VERTICAL. This attribute can be changed by the user when Ctrl+H or Ctrl+V is pressed. (since 3.30)

TIPFORMAT: format of the automatic TIP when mouse is over a sample. Default: "%s (%s, %s)". First parameter is DS_NAME, then X and Y sample values converted to strings using AXS_XTIPFORMAT and AXS_YTIPFORMAT accordingly. (since 3.13)

VIEWPORTSQUARE: force the plot area to be a square. (since 3.14)

ZOOM (write-only): controls the zoom in a simple way. Can be set to "+" (zoom in), "-" (zoom out), or "0" (reset). (since 3.21)

All color attributes accept an extra component for alpha. The default alpha is always 255 (opaque).

BGCOLOR (inheritable): the default background color. Default: "255 255 255". When set BACKCOLOR and LEGENDBOXBACKCOLOR of all plots will be reset to the same value.

FGCOLOR (inheritable): the default text and line color. Default: "0 0 0 255". When set, TITLE, AXIS, BOX and LEGENDBOX colors of all plots will be reset to the same value.

FONT (inheritable): the default font used in all text elements of the plot: title, legend and labels. Use "Plain" or "" to reset "Bold"/"Italic" styles. When set, will not overwrite *FONTSTYLE nor *FONTSIZE attributes.

MENUCONTEXT: enable the context menu. Can be Yes or No. Default: Yes.

MENUITEMPROPERTIES: enable the properties menu items and dataset values menu item in the context menu. Can be Yes or No. Default: No. (since 3.13)

MENUITEMVALUES: enable only the dataset menu item in the context menu. Can be Yes, No, or Hide. Hide can be used to hide it when MENUITEMPROPERTIES=Yes. Default: No. (since 3.29)

SHOWMENUCONTEXT (write-only): show the context menu in the given position. Value has the "x:y" format and is relative to the left-top corner of the screen.

EDITABLEVALUES: enable the editing of values when the "DataSet Values..." dialog is displayed. Can be Yes or No. Default: No. (since 3.21)

Multiple Plots Management

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_CURRENT: current plot index. Default: 0. When set can use also the TITLE name as value. All plot attributes and callbacks are dependent on this value.

IMPORTANT: When an IupCanvas mouse event occurs, such as BUTTON_CB, WHELL_CB or MOTION_CB, the current plot is set to the plot where the event occurred.

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_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_REMOVE (write-only): removes a plot given its index. If value is "CURRENT" or NULL the current plot is removed. Value can also be the TITLE of an existing plot.

IMPORTANT: All the following attributes and callbacks are dependent on the PLOT_CURRENT attribute.

Interaction Configuration

HIGHLIGHTMODE: enable the highlight of a curve and/or sample when cursor is over it. Can be: NONE, SAMPLE, CURVE or BOTH. CURVE highlight only works when DS_MODE is LINE, MARKLINE, AREA, STEP or ERRORBAR. Sample and curves are searched using IupPlotFindSample and IupPlotFindSegment. (since 3.21)

SCREENTOLERANCE: tolerance in pixels for highlight and click. Default: 5 (since 3.21)

Background Configuration

MARGINLEFT, MARGINRIGHT, MARGINTOP, MARGINBOTTOM: margin of the dataset area in pixels. If set to AUTO the margins are automatically calculated to fit all visible elements. Default: "AUTO". When consulted return the last calculated margin.

MARGINLEFTAUTO, MARGINRIGHTAUTO, MARGINTOPAUTO, MARGINBOTTOMAUTO: returns if the margin is set to AUTO. When set to NO the margin values will re-use the last calculated margin. Default: "YES". (since 3.13)

PADDING: internal margin used to complement the MARGIN* attributes. Default value: "5x5". (since 3.27)

BACKCOLOR: background color of the plot. Default: BGCOLOR.

BACKIMAGE: background image name. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. The image will be positioned using the BACKIMAGE_*MIN/MAX coordinates in plot scale. (since 3.13)

BACKIMAGE_XMIN, BACKIMAGE_XMAX, BACKIMAGE_YMIN, BACKIMAGE_YMAX: coordinates in plot scale to position the background image. The anchors in the image are the left-bottom and the top-right corners. (since 3.13)

DATASETCLIPPING: controls the clipping the dataset drawing. Can be: NONE, AREA or AREAOFFSET. Default: AREA. When AREA clipping is set to the regular dataset area. When AREAOFFSET clipping area is extended by a 2% offset or at least 10 pixels, but only when not in zoom. When NONE area is extended up to the plot limits. (since 3.22)

Title Configuration

TITLE: the title. If NULL will not be displayed.

TITLECOLOR: title color. Default: FGCOLOR.

TITLEFONTSIZE, TITLEFONTSTYLE: the title font size and style. Default: FONT, but size is increased by 6 points.

TITLEPOSAUTO: If Yes will position the title at top-center of the plot area, else it will use TITLEPOSXY to position the title. If set to NO it will disable the automatic position but reuse the last calculated position, and it will enable the interactive change of the title position. Default: Yes. (since 3.13)

TITLEPOSXY: position of the title in the format "x,y" in pixels inside the plot area relative to the bottom-left corner of the plot, oriented left to right and bottom to top, and anchored at the north-center point of the title bounding box. When set will also set TITLEPOSAUTO to No. Notice that when this value is used, if the plot is resized the value must also be manually updated to maintain the same appearace. (since 3.13) (relative position changed in 3.26)

Legend Configuration

LEGEND: shows or hides the legend box. Can be YES or NO. Default: NO. LEGENDSHOW is also accepted.

The Legend text color uses the DS_COLOR attribute of the respective dataset.

LEGENDBOX: draws a box around the legend area. Default: YES.

LEGENDBOXCOLOR: box line color. Default: FGCOLOR.

LEGENDBOXBACKCOLOR: box background color. Default: BGCOLOR.

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

LEGENDBOXLINEWIDTH: line width of the legend box. Default: 1.

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

LEGENDPOS: legend box position. Can be: "TOPLEFT", "TOPRIGHT", "BOTTOMLEFT", "BOTTOMRIGHT, "BOTTOMCENTER" or "XY". Default: "TOPRIGHT". The legend box is positioned inside the dataset area, except for BOTTOMCENTER that is displayed bellow the dataset area along with the X axis, and for XY that it will be positioned at the LEGENDPOSXY attribute value. If value is set to "XY" then the last calculated position is re-used, and it will enable the interactive change of the legend box position. ("XY" since 3.13)

LEGENDPOSXY: legend box position in the format "x,y". When set will change LEGENDPOS to "XY". Position is in pixels inside the plot area relative to the bottom-left corner of the plot, oriented left to right and bottom to top, and anchored at the bottom-left corner of the legend box. Notice that when this value is used, if the plot is resized the values must also be manually updated to maintain the same appearace. (since 3.13) (relative position changed in 3.26)

Grid Configuration

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

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

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

GRIDLINEWIDTH: line width of the box. Default: 1.

GRIDMINOR, GRIDMINORCOLOR, GRIDLINESTYLE and GRIDLINEWIDTH: are the same attributes for a grid at the minor ticks, but they are visible only if the major ticks grid are visible too. (since 3.13)

Box Configuration

BOX: draws a box around the dataset area. Default: NO.

BOXCOLOR: box line color. Default: FGCOLOR.

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

BOXLINEWIDTH: line width of the box. Default: 1.

Data Set List Management

REMOVE (write-only): removes a dataset given its index or its DS_NAME attribute, "CURRENT" or NULL are also accepted to remove the current dataset (since 3.13). 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_NAME attribute as value.

Data Set Configuration

DS_NAME: name of the current dataset. Default is dynamically generated: "plot 0", "plot 1", "plot 2", etc. DS_LEGEND is also accepted.

DS_COLOR: color of the current dataset. 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 in use then black is used "0 0 0".

DS_COUNT: returns the number of samples of the current dataset.

DS_MODE: drawing mode of the current dataset. Can be: "LINE", "MARK", "MARKLINE", "AREA", "BAR", "STEM", "MARKSTEM", "HORIZONTALBAR", "MULTIBAR", "STEP", "ERRORBAR", "PIE". Default: "LINE". (STEM to ERRORBAR since 3.18) (PIE since 3.21)

ERRORBAR is the same as MARKLINE with the additional error bar per sample. ERRORBAR mode depends on the "Extra" value to be set (see IupPlotSetSampleExtra). This extra value is the "error" of each sample.
When BAR, HORIZONTALBAR and MULTIBAR modes are set, AXS_XDISCRETE or AXS_YDISCRETE is also set.
When PIE mode is set only the first dataset is drawn. Each sample is drawn with a different color automatically set, but a custom color can be set using SAMPLECOLORid attribute. Also attributes AXS_*AUTOMIN and AXS_* are set to NO, AXS_*MIN are set to -1, and AXS_*MAX are set to 1. And Legend displays the sample colors not the list of datasets. Only non-zero, positive values, are drawn.

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. If a sample "Extra" value is set (see IupPlotSetSampleExtra) then it will ignore this value and use the sample extra value as mark size, except for ERRORBAR mode (since 3.18).

DS_BAROUTLINE: draws an outline when mode is BAR, HORIZONTALBAR or MULTIBAR. (since 3.18)

DS_BAROUTLINECOLOR: color of the outline. Default: "0 0 0". (since 3.18)

DS_BARSPACING: blank spacing percent between bars when mode is BAR, HORIZONTALBAR or MULTIBAR. Can be 0 to 100. Default: 10. (since 3.18)

DS_BARMULTICOLOR: enable the use of one color for each sample when mode is BAR or HORIZONTALBAR. The color is automatically set, but a custom color can be set using SAMPLECOLORid attribute. Default: No. (since 3.21)

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

DS_SELECTED: the curve shows a selected feedback. Only works when DS_MODE is LINE, MARKLINE, AREA, STEP or ERRORBAR. (since 3.29)

DS_USERDATA: user data associated with the dataset. (since 3.13)

DS_AREATRANSPARENCY: transparency for the AREA mode. It will be added to the dataset color. Can be 0 (fully transparent) to 255 (opaque). Used only for AREA mode. When different then 255 a line with dataset line attributes and using the regular dataset color will be drawn as an outline of the area. Default: 255. (since 3.21)

DS_PIERADIUS: radius of the pie. Notice that the pie will be a circle only if the viewport area is a perfect square or if VIEWPORTSQUARE=Yes, other wise it will be an ellipse. Used only for PIE mode. Default: 0.95 (since 3.21)

DS_PIESTARTANGLE: The angle where the first sample sector starts in degrees. Used only for PIE mode. Default: 0º (since 3.21)

DS_PIECONTOUR: enable a contour separating each sector, the external ring and the internal ring (when there is a hole). Can be Yes or No. Used only for PIE mode. The line is drawn with DS_COLOR, DS_LINEWIDTH and DS_LINESTYLE. (since 3.21)

DS_PIEHOLE: size of the hole as a factor of DS_PIERADIUS. Can be 0.0 to 1.0. Used only for PIE mode. If not zero the pie will look like a donut. The hole is filled with the plot background color given by BACKCOLOR. (since 3.21)

DS_PIESLICELABEL: show a text inside each slice. Can be NONE, X, Y or PERCENT. Text is drawn using AXS_YCOLOR, AXS_YFONTSIZE, AXS_YFONTSTYLE and AXS_YTICKFORMAT (for Y and PERCENT). When X is set the string value is used or the index of the sample. Used only for PIE mode. Default: NONE. (since 3.21)

DS_PIESLICELABELPOS: position of the text as a factor of the radius. The text reference point is at the bisectrix of the slice. The value of 1 position the reference point at the border. The value can be greater than 1, the text will be oriented inwards. The value can be negative to orient the text outwards. Used only for PIE mode. Default: 0.95 (since 3.21)

DS_STRXDATA [read-only]: returns if the dataset has strings for X coordinates, i.e. the strXdata parameter in IupPlotBegin was non zero. Can be: Yes or No. (since 3.21)

DS_EXTRA [read-only]: returns if the dataset has extra values, i.e. IupPlotSetSampleExtra was called for the dataset. Can be: Yes or No. (since 3.21)

DS_ORDEREDX: informs if the dataset X values are ordered. If so the FindSample and FindSample routines are optimized to be faster (does not affect BAR modes nor PIE mode). Default: No. (since 3.21)

Axis Configuration

AXS_SCALEEQUAL: force the auto scale to use a single minimum and maximum values for X and Y. It will combine AXS_XMAX/AXS_XMIN with AXS_YMAX/AXS_YMIN to obtain a single minimum and maximum values. (since 3.14) It does not need that automatic scaling is enabled (since 3.16).

AXS_X, AXS_Y: enable or disable the axis display. Can be YES or NO. Default: YES.

AXS_XCOLOR, AXS_YCOLOR: axis, ticks and label color. Default: FGCOLOR.

AXS_XDISCRETE, AXS_YDISCRETE: shift axis position by -0.5 to better display discrete data in BAR mode. Default: NO. (since 3.16)

AXS_XLINEWIDTH, AXS_YLINEWIDTH: line width of the axis and ticks. Default: 1.

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_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: NO. It is a simple interface to AXS_*ORIGINPOS when CROSSORIGIN is used or not (since 3.27).

AXS_XPOSITION, AXS_YPOSITION: position the axis. Can be START (left or bottom), CROSSORIGIN (cross the origin), and END (right or top). Default: START. If AXS_*SCALE is logarithmic then it is always START. (since 3.27)

AXS_XREVERSETICKSLABEL, AXS_YREVERSETICKSLABEL: reverse ticks and label position. By default the position is at left for the Y axis, and at bottom for the X axis. Can be YES or NO. Default: NO. When AXS_*POSITION is START is always NO, when AXS_*POSITION is END is always YES, and when AXS_*POSITION is CROSSORIGIN can be YES or NO. (since 3.27)

AXS_XARROW, AXS_YARROW: enable or disable the axis arrow display. Can be YES or NO. Default: YES.

AXS_XSCALE, AXS_YSCALE: configures the scale of the respective axis. Can be: LIN (linear), LOG10 (logarithmic base 10), LOG2 (logarithmic base 2) and LOGN (logarithmic base e). Default: LIN. If a logarithmic scale is set then the other axis position is set to START.

AXS_XTIPFORMAT, AXS_YTIPFORMAT: format to numeric conversion when an automatic tip is shown. See TIPFORMAT attribute. Default: "%.2f". (since 3.13)

AXS_XTIPFORMATPRECISION, AXS_YTIPFORMATPRECISION: will set the sprintf "precision" field in the AXS_*TIPFORMAT attributes string if the format "%.<precision>f". It is just a simple form to set and get the precision of the format attribute. (since 3.13)

Axis Label Configuration

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_XLABELSPACING, AXS_YLABELSPACING: label spacing from the ticks numbers. Can be: AUTO (or -1 = 10% of the font height), or any positive integer in pixels. Default: AUTO. (since 3.20)

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

Axis Ticks Configuration

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

AXS_XTICKAUTO, AXS_YTICKAUTO: configures the automatic tick spacing. Can be YES or NO. Default: YES. AXS_XAUTOTICK and AXS_YAUTOTICK are also accepted.

AXS_XTICKMAJORSPAN, AXS_YTICKMAJORSPAN: The spacing between major ticks in plot units. Default: 1. Automatically calculated when AUTOTICK=Yes.

AXS_XTICKMINORDIVISION, AXS_YTICKMINORDIVISION: number of minor ticks intervals between each major tick. Default: 5. Automatically calculated when AUTOTICK=Yes. AXS_XTICKDIVISION and AXS_YTICKDIVISION are also accepted.

AXS_XTICKSIZEAUTO, AXS_YTICKSIZEAUTO: configures the automatic tick size. Can be YES or NO. Default: YES. AXS_XAUTOTICKSIZE and AXS_XAUTOTICKSIZE are also accepted.

AXS_XTICKMINORSIZE, AXS_YTICKMINORSIZE: size of minor ticks in pixels. Default: 5. Automatically calculated when AUTOTICKSIZE=Yes. AXS_XTICKSIZE and AXS_YTICKSIZE are also accepted.

AXS_XTICKMAJORSIZE, AXS_YTICKMAJORSIZE: size of major ticks in pixels. Default is 8. Automatically calculated when AUTOTICKSIZE=Yes.

Axis Ticks Number Configuration

AXS_XTICKNUMBER, AXS_YTICKNUMBER: enable or disable the axis tick number display. Can be YES or NO. Default: YES.

AXS_XTICKROTATENUMBER, AXS_YTICKROTATENUMBER: enable the rotation of the axis tick number to the vertical position. Can be YES or NO. Default: NO.

AXS_XTICKROTATENUMBERANGLE, AXS_YTICKROTATENUMBERANGLE: angle of rotation in degrees. Use values between 90º and 45º for better results. Default: 90. (since 3.13)

AXS_XTICKFORMATAUTO, AXS_YTICKFORMATAUTO: enable the automatic axis tick number format. For the log scale axis the format is dynamically changed for every major tick. Default: "Yes". (since 3.13)

AXS_XTICKFORMAT, AXS_YTICKFORMAT: axis tick number C format string. If set will also set AXS_*TICKFORMATAUTO to NO. Default: "%.0f". The decimal symbol will follow the DEFAULTDECIMALSYMBOL global attribute definition if any (since 3.13).

AXS_XTICKFORMATPRECISION, AXS_YTICKFORMATPRECISION: will set the sprintf "precision" field in the AXS_*TICKFORMAT attributes string if the format "%.<precision>f". It is just a simple form to set and get the precision of the format attribute. (since 3.13)

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

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

Callbacks

CLICKSAMPLE_CB: Action generated when a sample is clicked. Called when the mouse button is released, with no Ctrl key and IUP_BUTTON3 only when Shift is pressed, to avoid conflict with zoom and context menu situations. The sample is searched using IupPlotFindSample.

int function(Ihandle *ih, int ds_index, int sample_index, double x, double y, int button); [in C]
ih:clicksample_cb(ds_index, sample_index, x, y, button: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
ds_index: index of the dataset
sample_index: index of the sample in the dataset
x: X coordinate value of the sample. When DS_STRXDATA=Yes, contains just the sample_index.
y: Y coordinate value of the sample
button: identifies the activated mouse button
    IUP_BUTTON1 - left mouse button (button 1)
    IUP_BUTTON2 - middle mouse button (button 2)
    IUP_BUTTON3 - right mouse button (button 3)

CLICKSEGMENT_CB: Action generated when a segment is clicked. The segment is identified by the two samples that connects the segment. Called when the mouse button is released, with no Ctrl key and IUP_BUTTON3 only when Shift is pressed, to avoid conflict with zoom and context menu situations. If a sample is clicked this callback is ignored. The segment is searched using IupPlotFindSegment. (since 3.21)

int function(Ihandle *ih, int ds_index, int sample_index1, double x1, double y1, int sample_index2, double x2, double y2, int button); [in C]
ih:clicksample_cb(ds_index, sample_index1, x1, y1, sample_index2, x2, y2, button: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
ds_index: index of the dataset
sample_index1: index of the sample in the dataset
x1: X coordinate value of the sample
y1: Y coordinate value of the sample
sample_index2: index of the sample in the dataset
x2: X coordinate value of the sample
y2: Y coordinate value of the sample
button: identifies the activated mouse button
    IUP_BUTTON1 - left mouse button (button 1)
    IUP_BUTTON2 - middle mouse button (button 2)
    IUP_BUTTON3 - right mouse button (button 3)

EDITSAMPLE_CB: Action generated when a sample coordinates are changed in the "Data Set Values..." dialog if EDITABLEVALUES=Yes. (since 3.24)

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

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

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

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]
ih:deletebegin_cb() -> (ret: number) [in Lua]
ih: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.

DRAWSAMPLE_CB: Action generated when a sample is drawn. When the plot is redraw, it is called for each sample, then it is called again for all selected samples, and this repeats for each data set., and this repeats for each data set.

int function(Ihandle *ih, int ds_index, int sample_index, double x, double y, int selected); [in C]
ih:drawsample_cb(ds_index, sample_index, x, y, selected: 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. When DS_STRXDATA=Yes, contains just the sample_index.
y: Y coordinate value of the sample
select: indicates if the sample is selected.

Returns: When called by the second time for a selected sample, if IUP_IGNORE is returned the selection is not dawn.

MENUCONTEXT_CB: Action generated after the context menu (right click) is created but before it is displayed, so the application can add or removed items from the menu. Called when the mouse button is pressed, with no Ctrl nor Shift keys. Only shown if MENUCONTEXT=Yes.

int function(Ihandle* ih, Ihandle* menu, int cnv_x, int cnv_y); [in C]
ih:menucontext_cb(menu: ihandle, cnv_x, cnv_y: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
menu: identifier of the menu that will be shown to the user.
cnv_x, cnv_y: canvas coordinates inside the current plot.

MENUCONTEXTCLOSE_CB: Same as MENUCONTEXT_CB, but called after the context menu is closed. Only shown if MENUCONTEXT=Yes.

DSPROPERTIESCHANGED_CB: Called after the user changed dataset attributes using the "Data Set Properties..." dialog. (since 3.24)

int function(Ihandle *ih, int ds_index); [in C]
ih:dspropertieschanged_cb(ds_index: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
ds_index: index of the dataset

DSPROPERTIESVALIDATE_CB: Called when the user pressed OK to change dataset attributes using the "Data Set Properties..." dialog. Called only once. (since 3.29)

int function(Ihandle *ih, Ihandle* param_dialog, int ds_index); [in C]
ih:dspropertiesvalidate_cb(param_dialog: ihandle, ds_index: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
param_dialog: internal handle of the IupGetParam dialog so the application can consult the PARAMid attributes to check their values.
ds_index: index of the dataset

Returns: if IUP_IGNORE is returned the dialog is not closed.

PROPERTIESCHANGED_CB: Called when the user changed plot attributes using the "Properties..." dialog. (since 3.24)

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

ih: identifier of the element that activated the event.

PROPERTIESVALIDATE_CB: Called for each attribute in the page, when the user pressed Apply to change plot attributes using the "Properties..." dialog. (since 3.29)

int function(Ihandle *ih, char* name, char* value); [in C]
ih:propertiesvalidate_cb(name, value: string) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
name: name of the attribute
value: new value for the attribute

Returns: if IUP_IGNORE is returned that attribute is not changed.

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

int function(Ihandle *ih, int ds_index, int sample_index, double x, double y, int selected); [in C]
ih:select_cb(ds_index, sample_index, x, y, selected: number) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event.
ds_index: index of the dataset
sample_index: index of the sample in the dataset
x: X coordinate value of the sample. When DS_STRXDATA=Yes, contains just the sample_index.
y: Y coordinate value of the sample
select: indicates if the sample 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]
ih:selectbegin_cb() -> (ret: number) [in Lua]
ih: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.

PLOTBUTTON_CB: similar to BUTTON_CB but coordinates are in plot scale with double precision. It is called before the internal processing, if returns IUP_IGNORE internal processing will not be done.

PLOTMOTION_CB: similar to MOTION_CB but coordinates are in plot scale with double precision. It is called before the internal processing, if returns IUP_IGNORE internal processing will not be done.

XTICKFORMATNUMBER_CB: allows to modify the displayed string of a tick number in the X axis. If the callback is not defined the internal function is used. (since 3.28)

int function(Ihandle *ih, char* buffer, char* format, double x, char* decimal_symbol); [in C]
ih:xtickformatnumber_cb(format: string, x: number, decimal_symbol: string) -> (ret: number, buffer: string) [in Lua]

ih: identifier of the element that activated the event.
buffer: buffer that will receive the string with the formatted number. In Lua the string is returned by the callback, then copied to the buffer. The buffer is limited to 128 characters.
format: the format string used by the internal function to format the number.
x: X coordinate value of the tick number.
decimal_symbol: the decimal symbol used by the internal function.

Returns: If IUP_IGNORE the number is not plotted. If IUP_CONTINUE the internal function is used.

YTICKFORMATNUMBER_CB: allows to modify the displayed string of a tick number in the Y axis. If the callback is not defined the internal function is used. (since 3.28)

int function(Ihandle *ih, char* buffer, char* format, double y, char* decimal_symbol); [in C]
ih:ytickformatnumber_cb(format: string, y: number, decimal_symbol: string) -> (ret: number, buffer: string) [in Lua]

ih: identifier of the element that activated the event.
buffer: buffer that will receive the string with the formatted number. In Lua the string is returned by the callback, then copied to the buffer. The buffer is limited to 128 characters.
format: the format string used by the internal function to format the number.
y: Y coordinate value of the tick number.
decimal_symbol: the decimal symbol used by the internal function.

Returns: If IUP_IGNORE the number is not plotted. If IUP_CONTINUE the internal function is used.

PREDRAW_CB, POSTDRAW_CB: Actions generated before and after the draw 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. Predraw is called after the background is drawn, and Postdraw is called before the legend and title are drawn (the last drawn elements). To position primitives in plot units, use the IupPlotTransform function.

int function(Ihandle *ih, cdCanvas* cnv); [in C]
ih:predraw_cb(cnv: cdCanvas) -> (ret: number) [in Lua]
ih: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, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

Examples

Browse for Example Files

IupPlot (since 3.12)

Initialization and Usage

Guide

Interaction

Zoom & Pan

Cross Hair & TIP

Selection

Context Menu

Creation

Auxiliary Functions

Attributes (All non inheritable, except when noted)

Multiple Plots Management

IMPORTANT: All the following attributes and callbacks are dependent on the PLOT_CURRENT attribute.

Interaction Configuration

Background Configuration

Title Configuration

Legend Configuration

Grid Configuration

Box Configuration

Data Set List Management

Data Set Configuration

Axis Configuration

Axis Label Configuration

Axis Ticks Configuration

Axis Ticks Number Configuration

Callbacks

Examples

See Also