Skip to content

Get started with PrestoPlot API

In this section you will get familiar with basic PrestoPlot plugin concepts and main steps to create a PrestoPlot plugin.

Programming language

First of all, the PrestoPlot plugins have to be written in Tcl programming language, if don't know this language, you can have a look at the following Internet resources :

The PrestoPlot plugin API is Object Oriented.

Here below are described the steps to create a plugin from scratch.

Plugins structure

A PrestoPlot plugin consists of a simple file with .plugin extension. This file is the minimum required for a plugin to be loaded in PrestoPlot.

There are multiple places where you can install your plugin :

  • In the PrestoPlot directory, near the executable file
  • On linux systems, you can also place the plugin file in the ~/.PrestoPlot directory.

If your plugin is quite complex, or require external ressources or Tcl libraries, you could also place your .plugin file into a dedicated directory (in the same locations). In this case, you are invited to use the following directories structure :

  • assets : Place here all your plugin assets, like icons for toolbars. You will be able to access them using paths relative to the .plugin file.
  • libs : Place here the Tcl packages you way want to use in your plugin. Keep in mind that a Tcl package is a directory containing a pkgIndex.tcl file. Those directory must be placed in the libs one.

Plugin basics

All plugins have to first import the PrestoPlotAPI package, which provides access to PrestoPlot features.

The below line should always be on top of your plugin :

package require PrestoPlotAPI

For stability aspects over PrestoPlot versions, please refer to API versions page.

There is basically two ways to interact with PrestoPlot and perform actions :

  • Adding custom buttons or entry menu in the User Interface. When the user click on them, your code will be executed. Use the UserInterface class to do so.
  • React to PrestoPlot events. PrestoPlot will execute your code on agreed hooks, when some events occurs. You will find more information in the Public Callbacks sections of classes descriptions

The entry point to interact with PrestoPlot is the PrestoPlot class. It gives access to high level and application features. A singleton is available through the PP global function. For example, to get the DatasetManager and create a dataset, you simply need :

set datasetManager [PP datasetManager]
set newDataset [$datasetManager createDataset "MyParameter"]

There are also convenient global functions to get a quick access to the PrestoPlot underlying managers (datasets, graphs, ...). You are encouraged to use them. See the PrestoPlot class documentation.

The above example can be simplified like this :

set newDataset [Datasets createDataset "MyParameter"]

Plugin informations

When you create a plugin, you can give to PrestoPlot some information about it. It is essentially :

  • A plugin name
  • A plugin version
  • A plugin description
  • Some help text with the purpose of helping the users of your plugin. This help will be displayed in the Loaded plugins section.

To do so, you should use the current Plugin object. Here is an example : 

# Get the current plugin object
set plugin [PP currentPlugin]

# Give it a name
$plugin set name "Sample Custom Loader"

# Give it a version
$plugin set version 1.0

# Give it a description
$plugin set description "Demo plugin to load some custom files"

# Give a help text in markdown format
$plugin set help {

## Plugin purpose

This is a demonstration plugin to load some specific text data file.

The specificity of the file format this plugin will load is that the date and time is separated by a field separator.
}

Go further

To further, you can go to the plugin samples page, then have a look at the whole documentation and the API reference.