Difference between revisions of "INX extension descriptor format"

From Inkscape Wiki
Jump to navigation Jump to search
(→‎Attributes description: add missing needs-document and needs-live-preview attributes)
(9 intermediate revisions by 4 users not shown)
Line 8: Line 8:
Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.
Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.


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


To allow localisation of strings in extension for Inkscape, some xml tags have to be adapted to variant readable by intltool. It means that tags or parameters has to have "_" prepended to their name, e.g. <tt><_name>name of extension</_name></tt>
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!).


Also the path to the extension has to be included in POTFILES.in file to tell intltool where to look for translatable content.
Example:
<pre>
<_name>Some translatable extension name</_name>
</pre>


Useful information, before this section gets fully updated, can be found at [http://gould.cx/ted/blog/Translating_Custom_XML Ted's blog].
Or:
<pre>
<param name="..." type="..." _gui-text="Some translatable label text">
</pre>
 
When extensions are included in the [http://bazaar.launchpad.net/~inkscape.dev/inkscape/trunk/files/head%3A/share/extensions/ Inkscape BZR Repository], various scripts will scan each INX file for translatable text and prepare [http://bazaar.launchpad.net/~inkscape.dev/inkscape/trunk/files/head%3A/po/ translation files] for others to translate.
 
See also: [http://gould.cx/ted/blog/Translating_Custom_XML Ted's blog].
 
 
== Attributes description ==
 
{| class="wikitable"
|-
! Attribute name
! Allowed values
! Comment
|-
| <code>implements-custom-gui</code> (''new in 1.0'')
| <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.
|-
| <code>needs-document</code>
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
| '''''(please fill in!)'''''
|-
| <code>needs-live-preview</code>
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
| '''''(please fill in!)'''''
|-
|}


== Example ==
== Example ==
More example INX files are available in the Inkscape distribution or in the Inkscape [http://inkscape.svn.sourceforge.net/viewvc/inkscape/inkscape/trunk/share/extensions/ SVN repository].
More example INX files are available in the Inkscape distribution or in the Inkscape [http://bazaar.launchpad.net/~inkscape.dev/inkscape/trunk/files/head%3A/share/extensions/ BZR repository].


<small><code><pre>
<small><pre>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
Line 44: Line 77:
   </script>
   </script>
</inkscape-extension>
</inkscape-extension>
</pre></code></small>
</pre></small>


== DTD ==
For a full list of currently supported interpreters, please see [[Extension Interpreters]].
<small><code><pre>
 
== 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]].
<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))>
  <!ELEMENT input (extension, mimetype, filetype, filetypetooltip, output_extension?)>
  <!ELEMENT input (extension, mimetype, filetype, filetypetooltip, output_extension?)>
Line 79: Line 115:
  <!ATTLIST dependency description CDATA #IMPLIED>
  <!ATTLIST dependency description CDATA #IMPLIED>
  <!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 page name CDATA #REQUIRED>
  <!ATTLIST page name CDATA #REQUIRED>
  <!ATTLIST page gui-text CDATA #IMPLIED>
  <!ATTLIST page gui-text CDATA #IMPLIED>
Line 94: Line 131:
  <!ATTLIST param appearance (minimal|) "">
  <!ATTLIST param appearance (minimal|) "">
  <!ATTLIST submenu name CDATA #REQUIRED>
  <!ATTLIST submenu name CDATA #REQUIRED>
</pre></code></small>
</pre></small>
 
 
 
== Relax NG Compact (RNC) ==
<small><code><pre>
datatypes xs = 'http://www.w3.org/2001/XMLSchema-datatypes'
namespace inkscape = 'http://www.inkscape.org/namespaces/inkscape'
default namespace local = ''
 
 
# Initially created from a Trang conversion.
# Edited for readability.
#
# @author Zearin
# @date 2010-07-21T11:02:00
 
 
 
start = inkscape-extension
 
#-------------------------------------------------------------------------------
# ELEMENTS
#===============================================================================
inkscape-extension =
    element inkscape-extension
    {
        name,
        id,
        dependency*,
        param*,
        (input | output | effect),
        (script | plugin)
    }
 
input =
    element input
    {
        extension,
        mimetype,
        filetype,
        filetypetooltip,
        output_extension?
    }
 
output =
    element output
    {
        extension,
        mimetype,
        filetype,
        filetypetooltip,
        dataloss?
    }
 
effect = element effect { attlist.effect, (object-type | submenu?) }
script = element script { command, helper_extension*, check* }
plugin = element plugin { name }
name = element name { text }
id = element id { text }
item = element item { text }
option = element option { text }
dependency = element dependency { attlist.dependency, text }
param = element param { attlist.param, (text | page | item | option)* }
page = element page {text, param*}
extension = element extension { text }
mimetype = element mimetype { text }
filetype = element filetype { text }
filetooltip = element filetooltip { text }
object-type = element object-type { text }
command = element command { attlist.command, text }
check = element check { attlist.check, text }
dataloss = element dataloss { text }
helper_extension= element helper_extension { text }
output_extension= element output_extension { text }
 
 
#-------------------------------------------------------------------------------
# ATTRIBUTE LISTS
#===============================================================================
attlist.check =
    attribute reldir { "absolute" | "path" | "extensions" | "plugins" }
 
attlist.command =
(
    attribute reldir { "absolute" | "path" | "extensions" | "plugins" },
    attribute interpreter { text }
)
 
attlist.dependency =
(
    attribute type { "executable" | "extension" },
    attribute location { "absolute" | "path" | "extensions" | "plugins" }?,
    attribute description { text }?
)
 
attlist.effect =
    attribute needs-live-preview { "true" | "false" }
 
attlist.page =
(
    attribute name { text },
    attribute gui-text { text }?
)
 
attlist.param =
(
    attribute name { text },
    attribute type {
        "int"
        | "float"
        | "string"
        | "boolean"
        | "enum"
        | "notebook"
        | "description"
        | "optiongroup"
        | "color"
    },
    attribute min { text }?,
    attribute max { text }?,
    attribute max_length { text }?,
    attribute precision { text }?,
    attribute gui-text { text }?,
    attribute gui-tip { text }?,
    attribute gui-description { text }?,
    attribute scope { text }?,
    attribute gui-hidden { text }?,
    attribute appearance {'minimal'|''}
)


attlist.submenu = attribute name { text }
== RELAX NG XML schema ==
The XML schema for ING files is available in the [http://bazaar.launchpad.net/~inkscape.dev/inkscape/trunk/annotate/head%3A/share/extensions/inkscape.extension.rng Inkscape BZR repository]. This is a [http://www.relaxng.org/ RELAX NG schema].


A compactly formatted version of the schema (created on 2 November 2010 using [http://www.thaiopensource.com/relaxng/trang.html Trang]):
<small><pre>
default namespace =
  "http://www.inkscape.org/namespace/inkscape/extension"


#-------------------------------------------------------------------------------
start =
# MISC
  element inkscape-extension {
#===============================================================================
    element _name { text },
filetypetooltip |= notAllowed
    element id { text },
page |= notAllowed
    element dependency {
submenu |= notAllowed
      attribute type { inx.dependency-type.values },
</pre></code></small>
      attribute location { inx.location.values }?,
      attribute _description { text }?,
      text
    }*,
    (inx.parameters
    | element param {
        attribute name { text },
        attribute type { "notebook" },
        element page {
          attribute name { text },
          attribute _gui-text { text },
          inx.parameters+
        }+
      })*,
    (element input {
      inx.io.common,
      element output_extension { text }?
    }
    | element output {
        inx.io.common,
        element dataloss { xsd:boolean }?
      }
    | element effect {
        attribute needs-document { xsd:boolean }?,
        attribute needs-live-preview { xsd:boolean }?,
        element object-type {
          xsd:token "all" | xsd:token "path" | xsd:token "rect"
        },
        element effects-menu {
          attribute hidden { xsd:boolean "true" }
          | element submenu {
              attribute _name { text },
              empty
            }
        }
      }
    | element path-effect { empty }
    | element print { empty }),
    (element script {
      element command {
        inx.reldir.attr,
        attribute interpreter { "python" | "perl" }?,
        text
      },
      element helper_extension { xsd:NMTOKEN }?,
      element check { inx.reldir.attr, text }*
    }
    | element xslt {
        element file { inx.reldir.attr, text }
      }
    | element plugin {
        element name { text }
      })
  }
inx.reldir.attr = attribute reldir { inx.location.values }
inx.location.values = "extensions" | "path" | "plugins"
inx.dependency-type.values = "extension" | "executable" | "plugin"
inx.io.common =
  element extension { text },
  element mimetype { text },
  element _filetypename { text }?,
  element _filetypetooltip { text }?
inx.parameter =
  attribute name { xsd:token },
  attribute gui-hidden { xsd:boolean }?,
  attribute _gui-text { text }?,
  ((attribute type { "int" },
    attribute min { xsd:integer }?,
    attribute max { xsd:integer }?,
    (empty | xsd:integer))
  | (attribute type { "float" },
      attribute precision { xsd:integer }?,
      attribute min { xsd:float }?,
      attribute max { xsd:float }?,
      xsd:float)
  | (attribute type { "boolean" },
      xsd:boolean)
  | (attribute type { "string" },
      attribute max_length { xsd:integer }?,
      (empty | text))
  | (attribute type { "description" },
      text)
  | (attribute type { "enum" },
      (element _item { inx.parameter.enum.item }
      | element item { inx.parameter.enum.item })+)
  | (attribute type { "optiongroup" },
      attribute appearance { "minimal" }?,
      (element option { inx.parameter.optiongroup.option }
      | element _option { inx.parameter.optiongroup.option })+))
inx.parameters =
  element param { inx.parameter }
  | element _param { inx.parameter }
inx.parameter.enum.item =
  attribute value { text },
  xsd:token
inx.parameter.optiongroup.option =
  attribute value { text }?,
  text
</pre></small>


== See Also ==
== See Also ==

Revision as of 21:02, 19 June 2019

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:

  • label strings for translation
  • define parameters
  • chain extensions
  • etc

Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.

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 need 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 BZR 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 effect extension to implement custom GUI. Implementation detail: "extension is working" window is not show for this kind of extensions.
needs-document "true" | "false" (default) (please fill in!)
needs-live-preview "true" | "false" (default) (please fill in!)

Example

More example INX files are available in the Inkscape distribution or in the Inkscape BZR 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|boolean|description]" 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 ING 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)>
 
 <!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 page name CDATA #REQUIRED>
 <!ATTLIST page gui-text CDATA #IMPLIED>
 <!ATTLIST param name CDATA #REQUIRED>
 <!ATTLIST param type (int|float|string|boolean|enum|notebook|description|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 ING files is available in the Inkscape BZR repository. This is a RELAX NG schema.

A compactly formatted version of the schema (created on 2 November 2010 using Trang):

default namespace =
  "http://www.inkscape.org/namespace/inkscape/extension"

start =
  element inkscape-extension {
    element _name { text },
    element id { text },
    element dependency {
      attribute type { inx.dependency-type.values },
      attribute location { inx.location.values }?,
      attribute _description { text }?,
      text
    }*,
    (inx.parameters
     | element param {
         attribute name { text },
         attribute type { "notebook" },
         element page {
           attribute name { text },
           attribute _gui-text { text },
           inx.parameters+
         }+
       })*,
    (element input {
       inx.io.common,
       element output_extension { text }?
     }
     | element output {
         inx.io.common,
         element dataloss { xsd:boolean }?
       }
     | element effect {
         attribute needs-document { xsd:boolean }?,
         attribute needs-live-preview { xsd:boolean }?,
         element object-type {
           xsd:token "all" | xsd:token "path" | xsd:token "rect"
         },
         element effects-menu {
           attribute hidden { xsd:boolean "true" }
           | element submenu {
               attribute _name { text },
               empty
             }
         }
       }
     | element path-effect { empty }
     | element print { empty }),
    (element script {
       element command {
         inx.reldir.attr,
         attribute interpreter { "python" | "perl" }?,
         text
       },
       element helper_extension { xsd:NMTOKEN }?,
       element check { inx.reldir.attr, text }*
     }
     | element xslt {
         element file { inx.reldir.attr, text }
       }
     | element plugin {
         element name { text }
       })
  }
inx.reldir.attr = attribute reldir { inx.location.values }
inx.location.values = "extensions" | "path" | "plugins"
inx.dependency-type.values = "extension" | "executable" | "plugin"
inx.io.common =
  element extension { text },
  element mimetype { text },
  element _filetypename { text }?,
  element _filetypetooltip { text }?
inx.parameter =
  attribute name { xsd:token },
  attribute gui-hidden { xsd:boolean }?,
  attribute _gui-text { text }?,
  ((attribute type { "int" },
    attribute min { xsd:integer }?,
    attribute max { xsd:integer }?,
    (empty | xsd:integer))
   | (attribute type { "float" },
      attribute precision { xsd:integer }?,
      attribute min { xsd:float }?,
      attribute max { xsd:float }?,
      xsd:float)
   | (attribute type { "boolean" },
      xsd:boolean)
   | (attribute type { "string" },
      attribute max_length { xsd:integer }?,
      (empty | text))
   | (attribute type { "description" },
      text)
   | (attribute type { "enum" },
      (element _item { inx.parameter.enum.item }
       | element item { inx.parameter.enum.item })+)
   | (attribute type { "optiongroup" },
      attribute appearance { "minimal" }?,
      (element option { inx.parameter.optiongroup.option }
       | element _option { inx.parameter.optiongroup.option })+))
inx.parameters =
  element param { inx.parameter }
  | element _param { inx.parameter }
inx.parameter.enum.item =
  attribute value { text },
  xsd:token
inx.parameter.optiongroup.option =
  attribute value { text }?,
  text

See Also