Difference between revisions of "INX extension descriptor format"

From Inkscape Wiki
Jump to navigation Jump to search
(→‎Attributes description: clarify "needs-document" (can likely be dropped in future as it was only important for help menu extensions which were dropped for 1.0)
m (fix link)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Introduction ==  
== Introduction ==  


In order for Inkscape to make use of an external script or program, you must describe that script to inkscape using an INX file. See the inkscape share directory for examples. The INX file allows the author to:
In order for Inkscape to make use of an external script or program, you must describe that script to inkscape using an INX file. The INX file is an XML file with Inkscape-specific content that can be edited in a plain-text editor.
* label strings for translation
 
* define parameters
The INX file allows the author to:
* chain extensions
* Specify what type of extension it is, for example input, output, or effect
* etc
* Identify [[Extension_Interpreters|which interpreter]] should be used to run the extension
Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.
* List dependencies; files or other extensions required for operation
* Define parameters that can be set in the extension
* Create [[Extensions:_INX_widgets_and_parameters|a GUI with control widgets]] for those parameters
* Add a submenu to the Extensions menu for the extension to reside in
* Label strings for translation
* Chain extensions
* Etc
 
Nothing beats a working example, and Inkscape includes a great number of extensions with INX files that you can read. To find the location of your Inkscape extensions directory, where included extensions and their INX files are located, look in the System pane of Inkscape Preferences, under "Inkscape extensions".
 


== Translation of extensions ==
== Translation of extensions ==


Extension dialog windows, described in INX files, can be prepared for translation or localisation by adding an <code>_</code> (underscore) to the XML tags or attributes. Only add underscores when text need to be translated (not numeric values, for example!).
Extension dialog windows, described in INX files, can be prepared for translation or localisation by adding an <code>_</code> (underscore) to the XML tags or attributes. Only add underscores when text needs to be translated (not numeric values, for example!).


Example:
Example:
Line 37: Line 46:
| <code>implements-custom-gui</code> (''new in 1.0'')
| <code>implements-custom-gui</code> (''new in 1.0'')
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> ''(default)''
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> ''(default)''
| If set to <code>true</code> '''requires''' effect extension to implement custom GUI. Implementation detail: "extension is working" window is not show for this kind of extensions.  
| If set to <code>true</code> '''requires''' an effect extension to implement custom GUI.<br>''Implementation detail: The "extension is working" window is not shown for this kind of extensions. This means user interaction with the Inkscape interface is blocked until the extension returns, with no way for the user to abort the running extension! It is therefore '''absolutely essential''' that your extension provides the necessary visual feedback for the user and has proper error handling, to rule out any dead-locking behavior.''
|-
|-
| <code>needs-document</code>
| <code>needs-document</code>
| <code>"true"</code> ''(default)'' <nowiki>|</nowiki> <code>"false"</code>  
| <code>"true"</code> ''(default)'' <nowiki>|</nowiki> <code>"false"</code>  
| If set to <code>false</code> the effect extension will not be passed a document nor will a document be read back ("no-op" effect). This is currently a hack to make extension manager work and will likely be removed/replaced in future, so use at your '''own risk'''!
| If set to <code>false</code> an effect extension will not be passed a document nor will a document be read back ("no-op" effect). This is currently a hack to make extension manager work and will likely be removed/replaced in future, so use at your '''own risk'''!
|-
|-
| <code>needs-live-preview</code>
| <code>needs-live-preview</code>
| <code>"true"</code> ''(default)'' <nowiki>|</nowiki> <code>"false"</code> (default)
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
| '''''(please fill in!)'''''
| If set to <code>true</code> in an effect extension, it will offer a "Live preview" checkbox in its GUI. When the user checks that box, it will run the extension in a "preview mode", visually showing the effect of the extension, but not making any changes to the SVG document, unless the user clicks the Apply button. While "Live preview" is checked in the GUI, any changes that the user makes to parameters accessible in the GUI will generate an updated preview.
|-
| <code>savecopyonly</code> (''new in 1.2'')
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
| If set to <code>true</code> in an '''output''' extension, it will limit the extension to being available only in the "Save a Copy" menu.
|-
|-
|}
|}
Line 60: Line 73:
   <param name="tab" type="notebook">   
   <param name="tab" type="notebook">   
     <page name="controls" _gui-text="Controls">
     <page name="controls" _gui-text="Controls">
       <param name="{argumentName}" type="[int|float|string|boolean|description]" min="{number}" max="{number}"
       <param name="{argumentName}" type="[int|float|string|bool]" min="{number}" max="{number}"
         _gui-text="{Friendly Argument Name}">{default value}</param>
         _gui-text="{Friendly Argument Name}">{default value}</param>
     </page>
     </page>
Line 82: Line 95:


== DTD XML schema==
== DTD XML schema==
The following XML schema may not fully describe the current ING file structure. The actual XML schema used is described in the [[INX extension descriptor format#RELAX NG XML schema|next paragraph]].
The following XML schema may not fully describe the current INX file structure. The actual XML schema used is described in the [[INX extension descriptor format#RELAX NG XML schema|next paragraph]].
<small><pre>
<small><pre>
  <!ELEMENT inkscape-extension (name, id, dependency*, param*,(input|output|effect),(script|plugin))>
  <!ELEMENT inkscape-extension (name, id, dependency*, param*,(input|output|effect),(script|plugin))>
Line 107: Line 120:
  <!ELEMENT helper_extension (#PCDATA)>
  <!ELEMENT helper_extension (#PCDATA)>
  <!ELEMENT output_extension (#PCDATA)>
  <!ELEMENT output_extension (#PCDATA)>
<!ELEMENT menu-tip (#PCDATA)>
   
   
  <!ATTLIST check reldir (absolute|path|extensions|plugins) #REQUIRED>
  <!ATTLIST check reldir (absolute|path|extensions|plugins) #REQUIRED>
Line 116: Line 130:
  <!ATTLIST effect needs-live-preview (true|false) #REQUIRED>
  <!ATTLIST effect needs-live-preview (true|false) #REQUIRED>
  <!ATTLIST effect implements-custom-gui (true|false) #IMPLIED>
  <!ATTLIST effect implements-custom-gui (true|false) #IMPLIED>
<!ATTLIST effect needs-document (true|false) #IMPLIED>
  <!ATTLIST page name CDATA #REQUIRED>
  <!ATTLIST page name CDATA #REQUIRED>
  <!ATTLIST page gui-text CDATA #IMPLIED>
  <!ATTLIST page gui-text CDATA #IMPLIED>
  <!ATTLIST param name CDATA #REQUIRED>
  <!ATTLIST param name CDATA #REQUIRED>
  <!ATTLIST param type (int|float|string|boolean|enum|notebook|description|optiongroup|color) #REQUIRED>
  <!ATTLIST param type (int|float|string|bool|notebook|path|optiongroup|color) #REQUIRED>
  <!ATTLIST param min CDATA #IMPLIED>
  <!ATTLIST param min CDATA #IMPLIED>
  <!ATTLIST param max CDATA #IMPLIED>
  <!ATTLIST param max CDATA #IMPLIED>
Line 137: Line 152:


== See Also ==
== See Also ==
*[[INX Parameters]]
*[[Extensions:_INX_widgets_and_parameters|INX Parameters]]
*[[ScriptingHOWTO]]
*[[ScriptingHOWTO]]



Latest revision as of 21:31, 18 November 2021

Introduction

In order for Inkscape to make use of an external script or program, you must describe that script to inkscape using an INX file. The INX file is an XML file with Inkscape-specific content that can be edited in a plain-text editor.

The INX file allows the author to:

  • Specify what type of extension it is, for example input, output, or effect
  • Identify which interpreter should be used to run the extension
  • List dependencies; files or other extensions required for operation
  • Define parameters that can be set in the extension
  • Create a GUI with control widgets for those parameters
  • Add a submenu to the Extensions menu for the extension to reside in
  • Label strings for translation
  • Chain extensions
  • Etc

Nothing beats a working example, and Inkscape includes a great number of extensions with INX files that you can read. To find the location of your Inkscape extensions directory, where included extensions and their INX files are located, look in the System pane of Inkscape Preferences, under "Inkscape extensions".


Translation of extensions

Extension dialog windows, described in INX files, can be prepared for translation or localisation by adding an _ (underscore) to the XML tags or attributes. Only add underscores when text needs to be translated (not numeric values, for example!).

Example:

<_name>Some translatable extension name</_name>

Or:

<param name="..." type="..." _gui-text="Some translatable label text">

When extensions are included in the Inkscape Extensions Repository, various scripts will scan each INX file for translatable text and prepare translation files for others to translate.

See also: Ted's blog.


Attributes description

Attribute name Allowed values Comment
implements-custom-gui (new in 1.0) "true" | "false" (default) If set to true requires an effect extension to implement custom GUI.
Implementation detail: The "extension is working" window is not shown for this kind of extensions. This means user interaction with the Inkscape interface is blocked until the extension returns, with no way for the user to abort the running extension! It is therefore absolutely essential that your extension provides the necessary visual feedback for the user and has proper error handling, to rule out any dead-locking behavior.
needs-document "true" (default) | "false" If set to false an effect extension will not be passed a document nor will a document be read back ("no-op" effect). This is currently a hack to make extension manager work and will likely be removed/replaced in future, so use at your own risk!
needs-live-preview "true" | "false" (default) If set to true in an effect extension, it will offer a "Live preview" checkbox in its GUI. When the user checks that box, it will run the extension in a "preview mode", visually showing the effect of the extension, but not making any changes to the SVG document, unless the user clicks the Apply button. While "Live preview" is checked in the GUI, any changes that the user makes to parameters accessible in the GUI will generate an updated preview.
savecopyonly (new in 1.2) "true" | "false" (default) If set to true in an output extension, it will limit the extension to being available only in the "Save a Copy" menu.

Example

More example INX files are available in the Inkscape distribution, which takes its files from the Inkscape Extensions Repository.

<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
  <_name>{Friendly Extension Name}</_name>
  <id>{org.domain.sub-domain.extension-name}</id>
  <dependency type="executable" location="[extensions|path|plugins|{location}]">program.ext</dependency>
  <param name="tab" type="notebook">  
    <page name="controls" _gui-text="Controls">
      <param name="{argumentName}" type="[int|float|string|bool]" min="{number}" max="{number}"
        _gui-text="{Friendly Argument Name}">{default value}</param>
    </page>
    <page name="help" _gui-text="Help">
      <param name="help_text" type="description">{Friendly Extension Help}</param>
    </page>
  </param>
  <effect>
    <object-type>[all|{element type}]</object-type>
      <effects-menu>
        <submenu _name="{Extension Group Name}"/>
      </effects-menu>
  </effect>
  <script>
    <command reldir="extensions" interpreter="[python|perl|ruby|bash|{some other}]">program.ext</command>
  </script>
</inkscape-extension>

For a full list of currently supported interpreters, please see Extension Interpreters.

DTD XML schema

The following XML schema may not fully describe the current INX file structure. The actual XML schema used is described in the next paragraph.

 <!ELEMENT inkscape-extension (name, id, dependency*, param*,(input|output|effect),(script|plugin))>
 <!ELEMENT input (extension, mimetype, filetype, filetypetooltip, output_extension?)>
 <!ELEMENT output (extension, mimetype, filetype, filetypetooltip, dataloss?)>
 <!ELEMENT effect (object-type|submenu?)>
 <!ELEMENT script (command, helper_extension*, check*)>
 <!ELEMENT plugin (name)>
 <!ELEMENT name (#PCDATA)>
 <!ELEMENT id (#PCDATA)>
 <!ELEMENT item (#PCDATA)>
 <!ELEMENT option (#PCDATA)>
 <!ELEMENT dependency (#PCDATA)>
 <!ELEMENT param (#PCDATA|page|item|option)*>
 <!ELEMENT page (#PCDATA, param*)>
 <!ELEMENT extension (#PCDATA)>
 <!ELEMENT mimetype (#PCDATA)>
 <!ELEMENT filetype (#PCDATA)>
 <!ELEMENT filetooltip (#PCDATA)>
 <!ELEMENT object-type (#PCDATA)>
 <!ELEMENT command (#PCDATA)>
 <!ELEMENT check (#PCDATA)>
 <!ELEMENT dataloss (#PCDATA)>
 <!ELEMENT helper_extension (#PCDATA)>
 <!ELEMENT output_extension (#PCDATA)>
 <!ELEMENT menu-tip (#PCDATA)>
 
 <!ATTLIST check reldir (absolute|path|extensions|plugins) #REQUIRED>
 <!ATTLIST command reldir (absolute|path|extensions|plugins) #REQUIRED>
 <!ATTLIST command interpreter CDATA #REQUIRED>
 <!ATTLIST dependency type (executable|extension) #REQUIRED>
 <!ATTLIST dependency location (absolute|path|extensions|plugins) #IMPLIED>
 <!ATTLIST dependency description CDATA #IMPLIED>
 <!ATTLIST effect needs-live-preview (true|false) #REQUIRED>
 <!ATTLIST effect implements-custom-gui (true|false) #IMPLIED>
 <!ATTLIST effect needs-document (true|false) #IMPLIED>
 <!ATTLIST page name CDATA #REQUIRED>
 <!ATTLIST page gui-text CDATA #IMPLIED>
 <!ATTLIST param name CDATA #REQUIRED>
 <!ATTLIST param type (int|float|string|bool|notebook|path|optiongroup|color) #REQUIRED>
 <!ATTLIST param min CDATA #IMPLIED>
 <!ATTLIST param max CDATA #IMPLIED>
 <!ATTLIST param max_length CDATA #IMPLIED>
 <!ATTLIST param precision CDATA #IMPLIED>
 <!ATTLIST param gui-text CDATA #IMPLIED>
 <!ATTLIST param gui-tip CDATA #IMPLIED>
 <!ATTLIST param gui-description CDATA #IMPLIED>
 <!ATTLIST param scope CDATA #IMPLIED>
 <!ATTLIST param gui-hidden CDATA #IMPLIED>
 <!ATTLIST param appearance (minimal|) "">
 <!ATTLIST submenu name CDATA #REQUIRED>

RELAX NG XML schema

The XML schema for INX files is available in the Inkscape extensions Git repository. This is a RELAX NG schema.

See Also