Difference between revisions of "Manual/Plugins"

From Knotter
Jump to navigation Jump to search
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
{{vbox|0.9.6}}
 +
 
==Available Plugins==
 
==Available Plugins==
−
{{plugin list begin}}
+
See the [[Manual/Plugins/List|list of available plugins]].
−
{{plugin list item|Example cusp plugin|An implementation of the built-in rounded cusp as a plugin}}
 
−
{{plugin list item|Star cusp|A cusp that looks like a star}}
 
−
{{plugin list item|Insert Lattice|Insert a square lattice}}
 
−
{{plugin list end}}
 
  
−
==Plugin Structure==
+
==Plugin Data==
 
A plugin is described by a JSON file containing the metadata for the given plugin.
 
A plugin is described by a JSON file containing the metadata for the given plugin.
  
−
The JSON contains an object with the following fields:
+
This data is available in scripts as attributes of the {{js|plugin}} object.
−
; name
 
−
: Recommended, an unique string that identifies the plugin.
 
−
: If missing is deduced from the file name.
 
−
; type
 
−
: Mandatory. Plugin type, see below for valid values.
 
−
: If missing or with an invalid value the plugin won't be loaded.
 
−
; 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 form the theme or a file name.
 
−
: How this is used can change depending on the plugin type.
 
−
; script
 
−
: 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.
 
−
; auto_enable
 
−
: Optional, whether the plugin is enabled by default. If omitted it's considered true.
 
−
: Test plugins ignore this and are always disabled by default.
 
  
−
The following fields are added at runtime and will be overwritten if present in the JSON file:
+
{| class="wikitable"
−
; plugin_file
+
|-
−
: Absolute path to the plugin JSON file.
+
! Parameter  !! Presence !! Description
−
; plugin_dir
+
|-
−
: Directory containing the JSON file.
+
! script
 +
|bgcolor=red| 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.
 +
|-
 +
! name
 +
|bgcolor=orange| Recommended || A unique string that identifies the plugin. If missing is deduced from the file name.
 +
|-
 +
! type
 +
|bgcolor=orange| Recommended || Plugin type, see below for valid values.  If missing or with an invalid value will be overwritten to '''script''' .
 +
|-
 +
! description
 +
|bgcolor=orange| Recommended ||A textual description of the use of the plugin.
 +
|-
 +
! requires
 +
|bgcolor=orange| Recommended || String for the minimum version of Knotter required to run the script. (Eg: '''{{Download Version}}''')
 +
|-
 +
! author
 +
|bgcolor=yellow| Suggested || Name of the author of the plugin.
 +
|-
 +
! version
 +
|bgcolor=yellow| Suggested || Plugin version.
 +
|-
 +
! license
 +
|bgcolor=yellow| Suggested || Short identifier of the software license covering the plugin.
 +
|-
 +
! icon
 +
|bgcolor=#6495ED| Optional || A named icon from the theme or a file name. How this is used can change depending on the plugin type.
 +
|-
 +
! auto_enable
 +
|bgcolor=#6495ED|Optional || Whether the plugin is enabled by default. If omitted it's considered true.
 +
|-
 +
! ui
 +
|bgcolor=#6495ED| Optional || Name or array of names of Ui files that are loaded by the plugin. The widgets will be available to the script from their object name.
 +
|-
 +
! category
 +
|bgcolor=#6495ED| Optional || For '''script''' plugins, the name of the menu that will contain it. Defaults to ''Other''.
 +
|-
 +
! plugin_file
 +
|bgcolor=silver| Automatic || Absolute path to the plugin JSON file.
 +
|-
 +
! plugin_dir
 +
|bgcolor=silver| Automatic || Directory containing the JSON file.
 +
|-
 +
! plugin_shortname
 +
|bgcolor=silver| Automatic || A unique name deduced from the file name.
 +
|-
 +
! plugin_deprecated
 +
|bgcolor=silver| Automatic || Added with a value of {{js|true}} when there's a newer version of the plugin already installed.
 +
|-
 +
! plugin_settings
 +
|bgcolor=#6495ED| Optional || Name of the JSON file used to store the plugin settings. If missing a unique value (not shared by any other plugin) is used.
 +
|-
 +
! settings
 +
|bgcolor=#6495ED| Optional || (Recommended if using settings) An object with values from the plugin setting. If the plugin has not yet saved any settings, this will be read from the plugin definition file, otherwise from the settings file.
 +
|}
 +
 
 +
===Reserved attributes===
 +
With the exception of {{js|plugin_settings}}, all attributes starting with {{js|plugin_}} are reserved for internal use and my be overwritten by Knotter or the plugin repository.
  
 
==Plugin Locations==
 
==Plugin Locations==
Line 48: Line 79:
  
 
==Plugin Types==
 
==Plugin Types==
−
; test
+
 
−
: A plugin for testing has no other use.
+
{|
−
; cusp
+
|-
−
: A new cusp style.
+
! cusp
−
===Planned Plugin Types===
+
| A new cusp style.
−
; insert
+
|-
−
: Inserts new shapes
+
! script
−
; transform
+
| Execute an arbitrary script, when enabled will be available from the {{app menu|Plugin}} menu.
−
: Operates on the selection
+
|-
−
; edge
+
! crossing
−
: A new edge type;
+
| A new crossing style.
 +
|}

Latest revision as of 10:30, 11 November 2013

This page is updated to Knotter version 0.9.6

Available Plugins

See the list of available plugins.

Plugin Data

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

This data is available in scripts as attributes of the plugin object.

Parameter Presence Description
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.
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.
requires Recommended String for the minimum version of Knotter required to run the script. (Eg: 0.9.6)
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.
auto_enable Optional Whether the plugin is enabled by default. If omitted it's considered true.
ui Optional Name or array of names of Ui files that are loaded by the plugin. The widgets will be available to the script from their object name.
category Optional For script plugins, the name of the menu that will contain it. Defaults to Other.
plugin_file Automatic Absolute path to the plugin JSON file.
plugin_dir Automatic Directory containing the JSON file.
plugin_shortname Automatic A unique name deduced from the file name.
plugin_deprecated Automatic Added with a value of true when there's a newer version of the plugin already installed.
plugin_settings Optional Name of the JSON file used to store the plugin settings. If missing a unique value (not shared by any other plugin) is used.
settings Optional (Recommended if using settings) An object with values from the plugin setting. If the plugin has not yet saved any settings, this will be read from the plugin definition file, otherwise from the settings file.

Reserved attributes

With the exception of plugin_settings, all attributes starting with plugin_ are reserved for internal use and my be overwritten by Knotter or the plugin repository.

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

cusp A new cusp style.
script Execute an arbitrary script, when enabled will be available from the Plugin menu.
crossing A new crossing style.
Retrieved from "https://knotter.mattbas.org/index.php?title=Manual/Plugins&oldid=878"