Difference between revisions of "INX extension descriptor format"

From Inkscape Wiki
Jump to navigation Jump to search
(Created a Relax NG-Compact example from the DTD. Used Trang for initial conversion, then edited to enhance readability and leverage RNC syntax.)
m (Tweaked markup for code examples (and made smaller to reduce vertical scrolling; these examples are obviously intended for copy-pasting :))
Line 19: Line 19:
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://inkscape.svn.sourceforge.net/viewvc/inkscape/inkscape/trunk/share/extensions/ SVN repository].


<pre>
<small><code><pre>
<inkscape-extension>
<inkscape-extension>
   <_name>{Friendly Extension Name}</_name>
   <_name>{Friendly Extension Name}</_name>
Line 43: Line 43:
   </script>
   </script>
</inkscape-extension>
</inkscape-extension>
</pre>
</pre></code></small>


== DTD ==
== DTD ==
 
<small><code><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 93: Line 93:
  <!ATTLIST param appearance (minimal|) "">
  <!ATTLIST param appearance (minimal|) "">
  <!ATTLIST submenu name CDATA #REQUIRED>
  <!ATTLIST submenu name CDATA #REQUIRED>
</pre></code></small>




== Relax NG Compact (RNC) ==
== Relax NG Compact (RNC) ==
<code><pre>
<small><code><pre>
datatypes xs = 'http://www.w3.org/2001/XMLSchema-datatypes'
datatypes xs = 'http://www.w3.org/2001/XMLSchema-datatypes'
namespace inkscape = 'http://www.inkscape.org/namespaces/inkscape'
namespace inkscape = 'http://www.inkscape.org/namespaces/inkscape'
Line 231: Line 233:
page |= notAllowed
page |= notAllowed
submenu |= notAllowed
submenu |= notAllowed
</pre></code>
</pre></code></small>


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

Revision as of 15:27, 21 July 2010

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.

Localisation 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. <_name>name of extension</_name>

Also the path to the extension has to be included in POTFILES.in file to tell intltool where to look for translatable content.

Useful information, before this section gets fully updated, can be found at Ted's blog.

Example

More example INX files are available in the Inkscape distribution or in the Inkscape SVN repository.

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

DTD

 <!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 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 Compact (RNC)

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 }


#-------------------------------------------------------------------------------
#	MISC
#===============================================================================
filetypetooltip |= notAllowed
page |= notAllowed
submenu |= notAllowed

See Also