Difference between revisions of "Manual/Plugins"

From Knotter
Jump to navigation Jump to search
Line 10: Line 10:
  
 
The JSON contains an object with the following fields:
 
The JSON contains an object with the following fields:
; name
+
{| class="wikitable"
: Recommended, an unique string that identifies the plugin.  
+
|-
: If missing is deduced from the file name.
+
! Parameter  !! Presence !! Description
; type
+
|-
: Mandatory. Plugin type, see below for valid values.
+
! name
: If missing or with an invalid value the plugin won't be loaded.
+
| Recommended || A unique string that identifies the plugin. If missing is deduced from the file name.
; description
+
|-
: Recommended. A textual description of the use of the plugin.
+
! type
; author
+
| Recommended || Plugin type, see below for valid values. If missing or with an invalid value will be overwritten to '''script''' .
: Suggested, name of the author of the plugin.
+
|-
; version
+
! description
: Suggested, plugin version.
+
| Recommended ||A textual description of the use of the plugin.
; license
+
|-
: Suggested, short identifier of the software license covering the plugin.
+
! author
; icon
+
| Suggested || Name of the author of the plugin.
: Optional, a named icon form the theme or a file name.
+
|-
: How this is used can change depending on the plugin type.
+
! version
; script
+
| Suggested || Plugin version.
: Mandatory (Optional if {{js|type}} is {{js|"test"}}). Location of the script file that is to be executed by the plugin. The location is considered relative to the directory containing the JSON file.
+
|-
: See {{rl|Scripting}} for a description of the language.
+
! license  
; auto_enable
+
| Suggested || Short identifier of the software license covering the plugin.
: Optional, whether the plugin is enabled by default. If omitted it's considered true.
+
|-
: Test plugins ignore this and are always disabled by default.
+
! icon
 
+
| Optional || A named icon from the theme or a file name. How this is used can change depending on the plugin type.
The following fields are added at runtime and will be overwritten if present in the JSON file:
+
|-
; plugin_file
+
! script
: Absolute path to the plugin JSON file.
+
| Mandatory || Location of the script file that is to be executed by the plugin. The location is considered relative to the directory containing the JSON file. See {{rl|Scripting}} for a description of the language.
; plugin_dir
+
|-
: Directory containing the JSON file.
+
! auto_enable
 +
| Optional || Whether the plugin is enabled by default. If omitted it's considered true.
 +
|-
 +
! plugin_file
 +
| Automatic || Absolute path to the plugin JSON file.
 +
|-
 +
! plugin_dir
 +
| Automatic || Directory containing the JSON file.
 +
|}
  
 
==Plugin Locations==
 
==Plugin Locations==

Revision as of 09:32, 3 June 2013

Available Plugins

Name Description Download
Example cusp plugin An implementation of the built-in rounded cusp as a plugin Included in the default installation.
Star cusp A cusp that looks like a star Included in the default installation.
Insert Lattice Insert a square lattice Included in the default installation.

Plugin Structure

A plugin is described by a JSON file containing the metadata for the given plugin.

The JSON contains an object with the following fields:

Parameter Presence Description
name Recommended A unique string that identifies the plugin. If missing is deduced from the file name.
type Recommended Plugin type, see below for valid values. If missing or with an invalid value will be overwritten to script .
description Recommended A textual description of the use of the plugin.
author Suggested Name of the author of the plugin.
version Suggested Plugin version.
license Suggested Short identifier of the software license covering the plugin.
icon Optional A named icon from the theme or a file name. How this is used can change depending on the plugin type.
script Mandatory Location of the script file that is to be executed by the plugin. The location is considered relative to the directory containing the JSON file. See Scripting for a description of the language.
auto_enable Optional Whether the plugin is enabled by default. If omitted it's considered true.
plugin_file Automatic Absolute path to the plugin JSON file.
plugin_dir Automatic Directory containing the JSON file.

Plugin Locations

Plugins are searched in the available data directories, the following directories are always searched:

  • datadir as per configure.sh.
  • current working directory/data
  • executable directory/data

Other directories depend on the system and Qt version. Check Help → About → Plugins for details

Plugin Types

test
A plugin for testing has no other use.
cusp
A new cusp style.

Planned Plugin Types

insert
Inserts new shapes
transform
Operates on the selection
edge
A new edge type;