INX extension descriptor format
===============================


.. highlight:: xml

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 :ref:`which interpreter <supported_interpreters>` 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 :ref:`a GUI with control widgets <inx-widgets>` for those parameters
-  Add a submenu to the Extensions menu for the extension to reside in
-  Label strings for translation

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 types
---------------

``<effect>`` extensions
^^^^^^^^^^^^^^^^^^^^^^^

**Corresponding inkex class:** :class:`~inkex.extensions.EffectExtension`

Effect extensions are given an SVG file on stdin and are expected to return a
modified SVG file on stdout. Any additional messages to be displayed to the user
can be passed on stderr. 

XML Attributes
``````````````

+---------------------------+-------------------------+
| Attribute name            | Allowed values          |
+===========================+=========================+
| ``implements-custom-gui`` | ``"true"`` |            |
|                           | ``"false"`` (default)   |
| .. versionadded:: 1.0     |                         |
+---------------------------+-------------------------+
| If set to ``true`` **requires** an effect           |
| extension to implement custom GUI.                  |
|                                                     |
| .. hint::                                           |
|    *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. It is also assumed    |
|    that the extension displays any content written  |
|    to stderr on its own (see ``show-stderr`` to     |
|    change this behavior).                           |
+---------------------------+-------------------------+
| ``show-stderr``           | ``"true"`` |            |
|                           | ``"false"`` (default)   |
| .. versionadded:: 1.4     |                         |
+---------------------------+-------------------------+
| Only evaluated for extensions which implement a     |
| custom gui. If set to ``true`` Inkscape will        |
| display any content written to stderr in a dialog   |
| after the extension is closed or has crashed.       |
+---------------------------+-------------------------+
| ``needs-document``        | ``"true"`` (default) |  |
|                           | ``"false"``             |
| .. versionadded:: 1.0     |                         |
+---------------------------+-------------------------+
| If set to ``false`` the 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"`` (default) |  |
|                           | ``"false"``             |
| .. versionadded:: 1.0     |                         |
+---------------------------+-------------------------+
| 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.                                            |
+---------------------------+-------------------------+
| ``refresh-extensions``    | ``"true"``  |           |
|                           | ``"false"`` (default)   |
+---------------------------+-------------------------+
| Reloads the extension list after the current        |
| extension finishes. Useful for bootstrapping        |
| extensions, currently used only by the extensions   |
| manager.                                            |
+---------------------------+-------------------------+

XML Children
````````````

- ``<effects-menu>``: Place of the extension in the menu. Example:

  .. code-block:: xml

    <effects-menu>
      <submenu name="Render">
          <submenu name="Grids"/>
      </submenu>
    </effects-menu>

- ``<menu-tip>Tooltip</menu-tip>``: Tooltip of the extension.
- ``<object-type>type|all</object-type>``: Specify for which selection of SVG
  elements the extension is enabled and can be triggered from within Inkscape.
  
  .. warning::

    This setting currently has no effect, see `inbox#723 <https://gitlab.com/inkscape/inbox/-/issues/723>`_.

  

``<input>`` extensions
^^^^^^^^^^^^^^^^^^^^^^

Input extensions are given an arbitrary file on stdin and are expected to return the 
contents of the file, converted to SVG, on stdout. 
Any additional messages to be displayed to the user can be passed on stderr. 

**Corresponding inkex class:** :class:`~inkex.extensions.InputExtension`

XML Attributes
``````````````

+---------------------------+-------------------------+
| Attribute name            | Allowed values          |
+===========================+=========================+
| ``priority``              | ``<int>`` |             |
|                           | not specified (default) |
| .. versionadded:: 1.3     |                         |
+---------------------------+-------------------------+
| In the Open dialog, the ``priority`` parameter      |
| determines the order of extensions.                 |
| When multiple extensions are registered as          |
| import for a given file extension, the extension    |
| with the lowest priority wins.                      |
| If no priority is specified, sort order is          |
| determined alphabetically.                          |
+---------------------------+-------------------------+
| ``savecopyonly``          | ``"true"`` |            |
|                           | ``"false"`` (default)   |
| .. versionadded:: 1.2     |                         |
+---------------------------+-------------------------+

XML Children
````````````

- ``<extension>.svg</extension>``: the file extension
- ``<mimetype>text/xml+svg</mimetype>``: mime type. Needs to be specified if the 
  extension should be called on clipboard data.
- ``<filetypename>Scalable Vector Graphics (*.svg)</filetypename>``: 
  this string is displayed in the filter of the Open dialog
- ``<filetypetooltip>Additional details</filetypetooltip>``


``<output>`` extensions
^^^^^^^^^^^^^^^^^^^^^^^

Output extensions are given an SVG file on stdin and are expected to return the 
exported representation of the file contents on stdout. 
Any additional messages to be displayed to the user can be passed on stderr. 

**Corresponding inkex class:** :class:`~inkex.extensions.OutputExtension`

XML Attributes
``````````````

+---------------------------+-------------------------+
| Attribute name            | Allowed values          |
+===========================+=========================+
| ``is_exported``           | ``"true"`` |            |
|                           | ``"false"`` (default)   |
| .. versionadded:: 1.2     |                         |
+---------------------------+-------------------------+
| If set to ``true`` in an **output** extensions, the |
| the extension will be available in the export       |
| dialog.                                             |
+---------------------------+-------------------------+
| ``priority``              | ``<int>`` |             |
|                           | not specified (default) |
| .. versionadded:: 1.3     |                         |
+---------------------------+-------------------------+
| In the Save / Save As dialog, the ``priority``      |
| parameter determines the order of extensions.       |
| If no priority is specified, sort order is          |
| determined alphabetically.                          |
+---------------------------+-------------------------+
| ``savecopyonly``          | ``"true"`` |            |
|                           | ``"false"`` (default)   |
| .. versionadded:: 1.2     |                         |
+---------------------------+-------------------------+
| If set to ``true`` in an **output** extension, it   |
| will limit the extension to being available only    |
| in the "Save a Copy" menu.                          |
+---------------------------+-------------------------+

XML Children
````````````

- ``<extension>.sif</extension>``: The file extension
- ``<mimetype>image/sif</mimetype>``: Needs to be specified if the 
  extension should be called when this particular clipboard format is requested.
- ``<filetypename>Synfig Animation (*.sif)</filetypename>``:
  this string is displayed in the filter of the Open dialog
- ``<filetypetooltip>Additional details</filetypetooltip>``
- ``<dataloss>true</dataloss>``: If the conversion to the output format is lossy,
  Inkscape will prompt the user to save the file as SVG on close.

Example
-------

.. code-block:: xml

   <?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 location="[inx|extensions]" interpreter="[python|perl|ruby|bash|{some other}]">program.ext</command>
     </script>
   </inkscape-extension>

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

For a full list of currently supported interpreters, please see 
:ref:`supported_interpreters`.

.. _dtd_xml_schema:

Translation of extensions
-------------------------

Inkscape extensions repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

Use ``translatable="no"`` to make an item (e.g. a unit name) untranslatable.

Third party extensions
~~~~~~~~~~~~~~~~~~~~~~

Third party extensions can set their own translation files by setting up their own unique
translation domain.

Example::

    <inkscape-extension translationdomain="my_extension" xmlns="http://www.inkscape.org/namespace/inkscape/extension">

Use the `inx.its`_ file from the Inkscape main repo and run
``xgettext my_extension.inx --its=inx.its -o my_extension.pot``. This will generate the pot file,
which you can distribute to translators. Use the .mo files generated from those in a special
structure:

::

    locale/
    ├── ar
    │   └── LC_MESSAGES
    │       └── my_extension.mo
    ├── as
    │   └── LC_MESSAGES
    │       └── my_extension.mo
    ├── az
    │   └── LC_MESSAGES
    │       └── my_extension.mo
    ...

If the files are, for instance, in
``.config/inkscape/extensions/my_extension/locale/<lang>/LC_MESSAGES/my_extension.mo``, then an inx
file at ``.config/inkscape/extensions/my_extension/my_extension.inx`` with the translationdomain
``my_extension`` will be translated in the interface.

The following three locations are recursively searched for "${translationdomain}.mo":

-  the 'locale' directory in the .inx file's folder
-  the 'locale' directory in the "extensions" folder containing the .inx file
-  the system location for gettext catalogs, i.e. where Inkscape's own catalog is located


.. _attributes_description:


DTD XML schema
--------------

.. warning:: This section contains slightly outdated information.

The following XML schema may not fully describe the current INX file
structure. The actual XML schema used is described in the :ref:`next
paragraph <relax_ng_xml_schema>`.

::

    <!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:

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:

.. _next paragraph: INX_extension_descriptor_format#RELAX_NG_XML_schema
.. _Inkscape extensions Git repository: https://gitlab.com/inkscape/extensions/-/blob/master/inkex/tester/inkscape.extension.rng
.. _RELAX NG schema: http://www.relaxng.org/
.. _INX Parameters: Extensions:_INX_widgets_and_parameters
.. _ScriptingHOWTO: ScriptingHOWTO

.. _Inkscape Extensions Repository: https://gitlab.com/inkscape/extensions
.. _a GUI with control widgets: Extensions:_INX_widgets_and_parameters
.. _translation files: https://gitlab.com/inkscape/inkscape/-/tree/master/po
.. _inx.its: https://gitlab.com/inkscape/inkscape/-/raw/master/po/its/inx.its