Inkscape Wiki - User contributions [en]

User talk:Moini

2020-04-11T15:59:53Z

KBenoit: Embed video

== User rename ==

Hi Maren,

I remember you got bureaucrat permissions during the hack-fest. Could you rename my Wiki user (see [[Special:RenameUser]]) to either "Patrick" or "Patrick87" (depending on whether you want to remove the unused user [[Special:Contributions/Patrick]] or not)?

Cheers, [[User:Eduard|Eduard]] ([[User talk:Eduard|talk]]) 18:25, 23 November 2018 (UTC)

Hi Patrick,

done. I can't remove users, only rename - and who knows, maybe that unknown Patrick will some day come back and claim his account. So you're Patrick87 now.

[[User:Moini|Moini]] ([[User talk:Moini|talk]])

: Danke! [[User:Patrick87|Patrick87]] ([[User talk:Patrick87|talk]]) 14:13, 24 November 2018 (UTC)

Hi Moini, I cleaned the discussion on INX Parameter as I did not realized you answered. We should add at the end, not inline the discussion. Like an email thread and sign our addition with four ~
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 14:59, 9 April 2020 (UTC)

Hi Moini, I see that you are probably the wiki maintainer? I tried to put a Youtube video on a page using template, seems hard/impossible. I saw found this [https://stackoverflow.com/questions/8374709/embedding-iframe-in-wikimedia-based-wiki/40921449 way of doing it], but that probably give us a lot much control. Another solution seems to be with [https://www.mediawiki.org/wiki/Extension:Widgets widgets]. [[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 15:59, 11 April 2020 (UTC)

Template talk:YouTube

2020-04-10T20:30:12Z

KBenoit:

Did not work, please delete this page ...
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 20:30, 10 April 2020 (UTC)

Template talk:YouTube

2020-04-10T20:29:50Z

KBenoit: Created page with "Did not work, please delete this page ..."

Did not work, please delete this page ...

Inkcards

2020-04-10T19:04:47Z

KBenoit: /* Summary of an inkcards SVG */

=Basic description=
Inkcards is an extension to create cards using layers, I say cards, but could be any tiles, like tokens, origami instructions, etc. The basic idea is you activate only the layers used by a specific card and save the information of which layers are visible for this card. By reusing the layers, it's much easier to customize your deck than copy/paste elements. With it, you can make modifications to the list/deck of cards by adding/removing cards, activating/deactivating the layers to show a specific card, or reordering the card list. ''It could be used to create video games?'', but the main idea is that once your cards are designed, you can tile them on a different document size in order to print them, read this [https://boardgamegeek.com/thread/490643/making-cards-youll-never-use-your-old-method-again thread] to know what I'm talking about. Rachel summarize her learning from the thread in a [https://www.youtube.com/watch?v=K5y3xeMN6Rs&feature=youtu.be video] which was also greatly inspired by this [https://www.youtube.com/watch?v=n_8q4V3TAzc video] from the Dinning Table (probably more pertinent).

=Design evolution=
For this my design is being updated for 1.0. I think of placing the cards in a card sized <code>rect</code> in which you draw the cards. From an extension, you manage the deck content by adding/removing cards which are using the visible layers perhaps under a "<code>cards</code>" named layer? Adding a card imply adding a <code><g></code> of multiple <code><use></code> of all layers used by this card in <code>defs</code>. Then adding another <code><use></code> of the <code><g></code> (card) entry just made in <code><defs></code>, inside the document's <code>viewBox</code>, more than one <code><use></code> if your deck has more than one instance of a card. This <code><use></code> of the card would be in a "<code>page X</code>" layer (where X is the floor of the card number divided by the number of card that fit in a page).

==Extensions needed==

* For this I think I should use an extension to initialize an Inkcards document by adding a <code>"Inkcards:cards"</code> named <code>rect</code> outside the <code>viewBox</code>. That <code>rect</code> would be the size of a card. Knowing the card size, in this extension I could reserve the place to tile the cards?
* If the user adjust the size of the card <code>rect</code>, he could use an extension (a second <code>inx</code>) to recalculate the tiles position in the document. Perhaps instead of a <code>rect</code>, it could be a <code>circle</code> and the extension could adjust the tiling to imbricate them with an optimize option, else it would align them.
* One extension to be able to move the card document (set <code>inkscape:groupmode="layer"</code>) and <code>sodipodi:insensitive="false"</code>. It would automatically set it back on the next use of the extension.
* An extension should save one SVG for every page layers and convert that into a single PDF using image magick convert.

==Summary of an inkcards SVG==
I wrote it as ideas where popping in my mind, so is useful documentation:

<source lang=xml>
<svg viewBox="0 0 279.4 215.9" width="11in" height="8.5in">
<defs>
<g id="card1" inkscape:groupmode="inkcards:card" inkcards:name="fireball" inkcards:nbCopy="2">
<use xlink:href="#layer1"/>
<use xlink:href="#layer2"/>
<use xlink:href="#layer3"/>
</g>
<g id="card2" inkscape:groupmode="inkcards:card" inkcards:name="dragon">
<use xlink:href="#layer1"/>

</g>

</defs>

<g inkscape:groupmode="layer" inkscape:label="Base card layers">
<g inkscape:groupmode="inkcards:cardFramingSize" sodipodi:insensitive="true">
<rect id="inkcards:cards" x="-100" y="0" width="80" height="80"/>
</g>

<g id="layer1" inkscape:groupmode="layer" inkscape:label="background1">

</g>
<g id="layer2" inkscape:groupmode="layer" inkscape:label="spell">

</g>
<g id="layer3" inkscape:groupmode="layer" inkscape:label="fireball">

</g>

</g>

<g inkscape:groupmode="layer" inkscape:label="pages">
<g inkscape:groupmode="layer" inkscape:label="page1">
<use xlink:href="#card1" x="20" y="20"/>
<use xlink:href="#card1" x="120" y="20"/>
<use xlink:href="#card2" x="220" y="20"/>

</g>
<g inkscape:groupmode="layer" inkscape:label="page2">

</g>

</g>
</svg>
</source>

==Questions==

* I use the <code>inkscape:groupmode="inkcards:card"</code>, is it something I can do for an inkscape extension or it's reserved for internal use ?
* The <code>inkscape:groupmode="inkcards:cardFramingSize"</code> is a way I think of having sort a dual document, the user could manage/resize it with an extension, perhaps be able to set it to layer for the resizing and the next time he uses any inkcards extension his <code>inkscape:groupmode</code> get back to <code>inkcards:cardFramingSize</code> so he could not play with it like he want, as it would move the cards. I also thought of using a group so that the cards layers are at origin, just moved by an underlying group.
* Is there a way to add a layer content, but not for other (sub)layers ? The problem is that layers are a tree and if i add a branch, all sub-branches are added. One way I thought to get around this is for a parent layer, have the content in a content sublayer which as all, but the sublayers, so that if I <code><use></code> it, it does not <code><use></code> all the sublayers. Perhaps inkscape could have an optional mode to separate the content from layers in a special layer with <code>inkscape:groupmode="layer-content"</code>?
* More will be added ...

==Exemple==
You can see an svg example of what [https://media.inkscape.org/media/resources/file/smiley-new2.svg inkcards could generate].

Inkcards

2020-04-10T19:02:01Z

KBenoit: Define sections

=Basic description=
Inkcards is an extension to create cards using layers, I say cards, but could be any tiles, like tokens, origami instructions, etc. The basic idea is you activate only the layers used by a specific card and save the information of which layers are visible for this card. By reusing the layers, it's much easier to customize your deck than copy/paste elements. With it, you can make modifications to the list/deck of cards by adding/removing cards, activating/deactivating the layers to show a specific card, or reordering the card list. ''It could be used to create video games?'', but the main idea is that once your cards are designed, you can tile them on a different document size in order to print them, read this [https://boardgamegeek.com/thread/490643/making-cards-youll-never-use-your-old-method-again thread] to know what I'm talking about. Rachel summarize her learning from the thread in a [https://www.youtube.com/watch?v=K5y3xeMN6Rs&feature=youtu.be video] which was also greatly inspired by this [https://www.youtube.com/watch?v=n_8q4V3TAzc video] from the Dinning Table (probably more pertinent).

=Design evolution=
For this my design is being updated for 1.0. I think of placing the cards in a card sized <code>rect</code> in which you draw the cards. From an extension, you manage the deck content by adding/removing cards which are using the visible layers perhaps under a "<code>cards</code>" named layer? Adding a card imply adding a <code><g></code> of multiple <code><use></code> of all layers used by this card in <code>defs</code>. Then adding another <code><use></code> of the <code><g></code> (card) entry just made in <code><defs></code>, inside the document's <code>viewBox</code>, more than one <code><use></code> if your deck has more than one instance of a card. This <code><use></code> of the card would be in a "<code>page X</code>" layer (where X is the floor of the card number divided by the number of card that fit in a page).

==Extensions needed==

* For this I think I should use an extension to initialize an Inkcards document by adding a <code>"Inkcards:cards"</code> named <code>rect</code> outside the <code>viewBox</code>. That <code>rect</code> would be the size of a card. Knowing the card size, in this extension I could reserve the place to tile the cards?
* If the user adjust the size of the card <code>rect</code>, he could use an extension (a second <code>inx</code>) to recalculate the tiles position in the document. Perhaps instead of a <code>rect</code>, it could be a <code>circle</code> and the extension could adjust the tiling to imbricate them with an optimize option, else it would align them.
* One extension to be able to move the card document (set <code>inkscape:groupmode="layer"</code>) and <code>sodipodi:insensitive="false"</code>. It would automatically set it back on the next use of the extension.
* An extension should save one SVG for every page layers and convert that into a single PDF using image magick convert.

==Summary of an inkcards SVG==
Written as ideas are coming to my mind, so will be useful documentation:

<source lang=xml>
<svg viewBox="0 0 279.4 215.9" width="11in" height="8.5in">
<defs>
<g id="card1" inkscape:groupmode="inkcards:card" inkcards:name="fireball" inkcards:nbCopy="2">
<use xlink:href="#layer1"/>
<use xlink:href="#layer2"/>
<use xlink:href="#layer3"/>
</g>
<g id="card2" inkscape:groupmode="inkcards:card" inkcards:name="dragon">
<use xlink:href="#layer1"/>

</g>

</defs>

<g inkscape:groupmode="layer" inkscape:label="Base card layers">
<g inkscape:groupmode="inkcards:cardFramingSize" sodipodi:insensitive="true">
<rect id="inkcards:cards" x="-100" y="0" width="80" height="80"/>
</g>

<g id="layer1" inkscape:groupmode="layer" inkscape:label="background1">

</g>
<g id="layer2" inkscape:groupmode="layer" inkscape:label="spell">

</g>
<g id="layer3" inkscape:groupmode="layer" inkscape:label="fireball">

</g>

</g>

<g inkscape:groupmode="layer" inkscape:label="pages">
<g inkscape:groupmode="layer" inkscape:label="page1">
<use xlink:href="#card1" x="20" y="20"/>
<use xlink:href="#card1" x="120" y="20"/>
<use xlink:href="#card2" x="220" y="20"/>

</g>
<g inkscape:groupmode="layer" inkscape:label="page2">

</g>

</g>
</svg>
</source>

==Questions==

* I use the <code>inkscape:groupmode="inkcards:card"</code>, is it something I can do for an inkscape extension or it's reserved for internal use ?
* The <code>inkscape:groupmode="inkcards:cardFramingSize"</code> is a way I think of having sort a dual document, the user could manage/resize it with an extension, perhaps be able to set it to layer for the resizing and the next time he uses any inkcards extension his <code>inkscape:groupmode</code> get back to <code>inkcards:cardFramingSize</code> so he could not play with it like he want, as it would move the cards. I also thought of using a group so that the cards layers are at origin, just moved by an underlying group.
* Is there a way to add a layer content, but not for other (sub)layers ? The problem is that layers are a tree and if i add a branch, all sub-branches are added. One way I thought to get around this is for a parent layer, have the content in a content sublayer which as all, but the sublayers, so that if I <code><use></code> it, it does not <code><use></code> all the sublayers. Perhaps inkscape could have an optional mode to separate the content from layers in a special layer with <code>inkscape:groupmode="layer-content"</code>?
* More will be added ...

==Exemple==
You can see an svg example of what [https://media.inkscape.org/media/resources/file/smiley-new2.svg inkcards could generate].

Inkcards

2020-04-10T16:38:42Z

KBenoit: Switch inkcards development description / perhaps discussion to the wiki instead of the forum.

Inkcards is an extension to create cards using layers, I say cards, but could be any tiles, like tokens, origami instructions, etc. The basic idea is you activate only the layers used by a specific card and save the information of which layers are visible for this card. By reusing the layers, it's much easier to customize your deck than copy/paste elements. With it, you can make modifications to the list/deck of cards by adding/removing cards, activating/deactivating the layers to show a specific card, or reordering the card list. ''It could be used to create video games?'', but the main idea is that once your cards are designed, you can tile them on a different document size in order to print them, read this [https://boardgamegeek.com/thread/490643/making-cards-youll-never-use-your-old-method-again thread] to know what I'm talking about. Rachel summarize her learning from the thread in a [https://www.youtube.com/watch?v=K5y3xeMN6Rs&feature=youtu.be video] which was also greatly inspired by this [https://www.youtube.com/watch?v=n_8q4V3TAzc video] from the Dinning Table (probably more pertinent).

For this my design is being updated for 1.0. I think of placing the cards in a card sized <code>rect</code> in which you draw the cards. From an extension, you manage the deck content by adding/removing cards which are using the visible layers perhaps under a "<code>cards</code>" named layer? Adding a card imply adding a <code><g></code> of multiple <code><use></code> of all layers used by this card in <code>defs</code>. Then adding another <code><use></code> of the <code><g></code> (card) entry just made in <code><defs></code>, inside the document's <code>viewBox</code>, more than one <code><use></code> if your deck has more than one instance of a card. This <code><use></code> of the card would be in a "<code>page X</code>" layer (where X is the floor of the card number divided by the number of card that fit in a page).

Extensions needed:

* For this I think I should use an extension to initialize an Inkcards document by adding a <code>"Inkcards:cards"</code> named <code>rect</code> outside the <code>viewBox</code>. That <code>rect</code> would be the size of a card. Knowing the card size, in this extension I could reserve the place to tile the cards?
* If the user adjust the size of the card <code>rect</code>, he could use an extension (a second <code>inx</code>) to recalculate the tiles position in the document. Perhaps instead of a <code>rect</code>, it could be a <code>circle</code> and the extension could adjust the tiling to imbricate them with an optimize option, else it would align them.
* One extension to be able to move the card document (set <code>inkscape:groupmode="layer"</code>) and <code>sodipodi:insensitive="false"</code>. It would automatically set it back on the next use of the extension.
* An extension should save one SVG for every page layers and convert that into a single PDF using image magick convert.

Here's a summary of an inkcards SVG ... written as ideas are coming to my mind, so will be useful documentation:
<source lang=xml>
<svg viewBox="0 0 279.4 215.9" width="11in" height="8.5in">
<defs>
<g id="card1" inkscape:groupmode="inkcards:card" inkcards:name="fireball" inkcards:nbCopy="2">
<use xlink:href="#layer1"/>
<use xlink:href="#layer2"/>
<use xlink:href="#layer3"/>
</g>
<g id="card2" inkscape:groupmode="inkcards:card" inkcards:name="dragon">
<use xlink:href="#layer1"/>

</g>

</defs>

<g inkscape:groupmode="layer" inkscape:label="Base card layers">
<g inkscape:groupmode="inkcards:cardFramingSize" sodipodi:insensitive="true">
<rect id="inkcards:cards" x="-100" y="0" width="80" height="80"/>
</g>

<g id="layer1" inkscape:groupmode="layer" inkscape:label="background1">

</g>
<g id="layer2" inkscape:groupmode="layer" inkscape:label="spell">

</g>
<g id="layer3" inkscape:groupmode="layer" inkscape:label="fireball">

</g>

</g>

<g inkscape:groupmode="layer" inkscape:label="pages">
<g inkscape:groupmode="layer" inkscape:label="page1">
<use xlink:href="#card1" x="20" y="20"/>
<use xlink:href="#card1" x="120" y="20"/>
<use xlink:href="#card2" x="220" y="20"/>

</g>
<g inkscape:groupmode="layer" inkscape:label="page2">

</g>

</g>
</svg>
</source>
Questions:

* I use the <code>inkscape:groupmode="inkcards:card"</code>, is it something I can do for an inkscape extension or it's reserved for internal use ?
* The <code>inkscape:groupmode="inkcards:cardFramingSize"</code> is a way I think of having sort a dual document, the user could manage/resize it with an extension, perhaps be able to set it to layer for the resizing and the next time he uses any inkcards extension his <code>inkscape:groupmode</code> get back to <code>inkcards:cardFramingSize</code> so he could not play with it like he want, as it would move the cards. I also thought of using a group so that the cards layers are at origin, just moved by an underlying group.
* Is there a way to add a layer content, but not for other (sub)layers ? The problem is that layers are a tree and if i add a branch, all sub-branches are added. One way I thought to get around this is for a parent layer, have the content in a content sublayer which as all, but the sublayers, so that if I <code><use></code> it, it does not <code><use></code> all the sublayers. Perhaps inkscape could have an optional mode to separate the content from layers in a special layer with <code>inkscape:groupmode="layer-content"</code>?
* More will be added ...

Example of what [https://media.inkscape.org/media/resources/file/smiley-new2.svg inkcards could generate].

Extension reference

2020-04-10T15:05:05Z

KBenoit: Adding an inkcards link/page

{{Other languages|en=Extension reference}}

''A page with info about the extensions and particularly some PNGs / screenshots. (some parts may be outdated)
''

This page is '''partially outdated''' and needs an overhaul. If you can help with updating the page, please contact the [https://inkscape.org/en/community/mailing-lists/ Inkscape developers mailing list, or the docs mailing list].

For '''alternative information sources''', also see:

* [http://tavmjong.free.fr/INKSCAPE/MANUAL/html/Extensions.html The comprehensive guide by Tavmjong Bah (refers to Inkscape 0.48)]

* More info about other, user-created extensions can be found
** [https://inkscape.org/en/download/addons/ in our website's addon gallery]
** and in the [[Extension_repository | Extension Repository page]] of the Wiki.

=Color=

==Brighter==
Brightens the color(s) by dividing each RGB channel by 0.9. Channels with a value of 0 remain unaffected. Although brighter and darker are inverse operations, the results of a series of invocations will cause inconstancies due to rounding errors. Use '''More Light''' if you want to brighten up black areas as well.

==Custom...==

Allows you to evaluate different functions for each channel. '''r''', '''g''' and '''b''' are the ''normalized'' values of the red, green and blue channels. The resulting RGB values are automatically clamped.

'''Note:''' This effect is half broken in 0.45! The original values are overwritten by the new ones, which means things like the last example won't work as expected.

===Examples===
Default (doesn't change anything):
:Red Function:'''r'''
:Green Function:'''g'''
:Blue Function:'''b'''

Half the red, swap green and blue:
:Red Function:'''r*0.5'''
:Green Function:'''b'''
:Blue Function:'''g'''

ITU-R Recommendation BT.709 for grayscale:
:Red Function:'''0.2125 * r + 0.7154 * g + 0.0721 * b'''
:Green Function:'''0.2125 * r + 0.7154 * g + 0.0721 * b'''
:Blue Function:'''0.2125 * r + 0.7154 * g + 0.0721 * b'''

==Darker==

Darkens the color(s) by multiplying each RGB channel with 0.9. Although brighter and darker are inverse operations, the results of a series of invocations will cause inconstancies due to rounding errors. '''Less Light''' is usually a better option, because it operates in the HSL color space.

==Desaturate==

Desaturates the color(s) by dividing the sum of the minimum and maximum channel values by two. Use '''Grayscale''' if you want something closer to the human perception of luminance.

==Grayscale==

Creates a grayscale version of the color(s) via the PAL/NTSC formula (0.299 * RED + 0.587 * GREEN + 0.114 * BLUE).

==Less Hue==

Converts to HSL color space, subtracts 0.05 from the hue, wraps if necessary, and converts it back to RGB again.

==Less Light==

Converts to HSL color space, subtracts 0.05 from the lightness, clamps if necessary, and converts it back to RGB again.

==Less Saturation==

Converts to HSL color space, subtracts 0.05 from the saturation, clamps if necessary, and converts it back to RGB again.

==More Hue==

Converts to HSL color space, adds 0.05 from to hue, wraps if necessary, and converts it back to RGB again.

==More Light==

Converts to HSL color space, adds 0.05 from to lightness, clamps if necessary, and converts it back to RGB again.

==More Saturation==

Converts to HSL color space, adds 0.05 from to saturation, clamps if necessary, and converts it back to RGB again.

==Negative==

Inverts each RGB channel (255-value).

==Randomize==

Converts to HSL, randomizes hue and/or saturation and/or lightness and converts it back to RGB.

==Remove Blue==

Sets the blue channel to 0.

==Remove Green==

Sets the green channel to 0.

==Remove Red==

Sets the red channel to 0.

==Replace Color...==

Replaces a specific color with another one.

==RGB Barrel==

Rotates the RGB channels (RGB->BRG->GBR->RGB...).

=Developer Examples=

=Export=
==Groups to PNGs==

=Generate from Path=
==Inset/Outset Halo==

[[Image:InsetOutsetExample.png]]

Parameters:
; Width: 20
; Number of steps: 5

Creates translucent copies of the path inside and outside the path.

==Extrude==
[[Image:ExtrudeExample.png]]

Parameters:
; Magnitude: 20
; Angle: 45

==Interpolate==
===Outline===
Iterpolate does a linear interpolation between 2 or more paths. It basically means that it "fills in the gaps" between the paths according to the number of steps given.

===Basic Usage===
To use the interpolation effect, select the paths that you wish to interpolate, and go to Effects > Generate From Path > Interpolate. Choose your options, and Click OK.

===Basic Example===
View figure 1 below, where there are 2 identical paths.

[[Image:Interpolate1.png]]

Here is the result when the interpolation effect is called with a "Steps" value of 6.

[[Image:Interpolate2.png]]

===Options===
One of the great features of the inkscape interpolation is "transform style", which transforms the

It appears that you need to convert an object to a path first (Path > Object to path ; Shift-Ctrl-c). You can alter the number of steps used and choose one of two methods.

[[Image:interpolate_blueSquare-redCircle.png]]
==Pattern along Path==

Star pattern and a line path:

[[Image:PatternAlongPathExample1.png]]

Pattern along path:

[[Image:PatternAlongPathExample2.png]]

Parameters:
; Copies of the pattern: repeated
; Deformation type: snake
; Space between copies: 0
; Normal offset: 0
; Tangential offset: 0
; Pattern is vertical: unchecked
; Duplicate the pattern before deformation: checked

[[Image:PatternAlongPathExample3.png]]

Modified parameter:
; Deformation type: ribbon

=Images=

=Modify Path=
==Envelope==
==Add Nodes==

Adds extra nodes to the segments of a shape according to the options set.

[[File:AddNodes.png]]

==Color Markers to Match Stroke==
==Flatten Beziers==
[[Image:FlattenBeziersExample.png]]

Parameters:
; Flatness: 10

==Fractalize==
[[Image:FractalizeExample.png]]

Parameters:
; Subdivisions: 6
; Smoothness: 4.0

==Jitter nodes==
[[Image:JitterNodesExample.png]]

Parameters:
; Maximum Displacement: 50.0
; Shift Nodes: checked
; Shift Node Handles: checked
; Use Normal Distribution: checked

==Perspective==
==Straighten Segments==
[[Image:StraightenSegmentsExample.png]]

Parameters:
; Percent: 50
; Behavior: 1

=Render=

==3D polyhedron==

'''3D polyhedron''' draws polyhedra stored in OBJ files. A selection of polygons are provided with Inkscape, and others can be used by selection <tt>Load From File...</tt> in the extension dialogue.

[[image:3D_polyhedron_-_snub_dodecahedron.png|thumb|Drawing faces]]

==Alphabet soup==

'''Alphabet Soup''' generates a series of shapes that resemble a given text string.

[[file:Alphabet_soup_-_Inkscape.png‎|thumb|250px|Output for "Inkscape"]]

==Barcode==

Renders a data string as various types of barcode. Choices are:
*EAN8
*EAN13
*UPC-A
*UPC-E
*Code39
*Code39Ext
*Code93
*Code128
*RM4CC/RM4SCC

[[File:BarcodeEffect.png]]

==Calendar==

Generates a rather impressive calendar according to your own colours, month/day names etc.

[[File:CalendarEffect.png]]

==Cartesian grid==

Generates a Cartesian Grid according to your parameters. The default looks like this:

[[File:CartesianGridEffect.png]]

==Draw from triangle==

Draws various shapes based on a triangle you have selected.

[[File:DrawfromtriangleEffect.png]]

==Foldable box==

Produces a net that you could print out and fold & stick into a box. Nets look something like this:

[[File:FoldableBoxEffect.png]]

==Function plotter==

Generates the plot of a function using a selected rectangle as the grid. Can cope with Cartesian and Polar coordinates, uses [http://docs.python.org/library/math.html Python's maths functions].

::I can't get this to work properly; for example y=x (Cartesian) produces this:

::[[File:FunctionPlotterFailure.png]]

::Is this an error in the settings (so I can add information on using the effect) or a problem with the script itself? [[User:Legio noctis|Legio noctis]] 20:54, 11 January 2010 (UTC)

:::I get the expected function plot (straight diagonal line) by either activating the checkbox for 'Calculate first derivative numerically' or setting the first derivative to '1' (the slope of the curve '''f(x)=x''' is '''f’(x) = 1''') --[[User:~suv|~suv]] 18:09, 12 January 2010 (UTC)

==Gear==

Produces a gear/cog shape with a chosen number of teeth, pitch and pressure angle.

[[File:GearEffect.png]]

==Grid==

Generates a grid similar to the [[Effect_reference#Cartesian_grid|Cartesian grid]] but without the bolded lines (which could be used for axes etc.).

[[File:GridEffect.png]]

==Guides==
Allows you to render guides onto the page at regular positions horizontally and vertically.

For example, choosing Vertical 1/3 and Horizontal 1/3 renders 'rule of thirds' guides—three horizontal and three vertical, equally spaced.

==LaTeX formula==
Renders a string as a formula in [[LaTeX]]. You probably need a TeX distribution installed to do this (is it included? I don't know, I already have MiKTeX). If you do not have one, try installing [http://miktex.org/ MiKTeX] or the [http://www.lyx.org/ LyX] bundle (which includes TeX and LaTeX configured).

[[File:LatexFormulaEffect.png]]

==L-system==

Produces this sort of thing:

[[File:LSystemEffect.png]]

==Parametric curves==

==Perfect-bound cover template==

==Polar grid==

==Printing marks==

==Random tree==

==Sequential labels==

==Spirograph==

==Triangle==
Renders a certain size triangle. Also achievable (although to a less fine degree) with the <tt>Create stars and polygons</tt> tool set up correctly.

==Wireframe sphere==

=Visualise Path=

==Number Nodes==
[[Image:NumberNodesExample.png]]

Parameters:
; Font Size: 20
; Dot Size: 10px

==Kochify==
To use, select one path consisting of only line segments and apply the effect. Kochify will replace the given path with a path that has a copy of the original path in between each two adjacent nodes in the original path. If the original path input has bezier curves, the effect will effectively replace them with lines and then apply the effect. For more information about Kochify from a developers perspective, look [http://www.ekips.org/comp/inkscape/koch.php here]. Requires: python.

[[Category:Extensions]]

=In developpement=
* [[inkcards]]

Talk:Extensions: INX widgets and parameters

2020-04-09T16:30:36Z

KBenoit:

== User [[User:Moini|Moini]] Added this talk into the page : ==
To document:
* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:53, 23 March 2020‎ (UTC)

# Multiline text fields: appearance="multiline"
#* I could not figure out how to set the height to something else than one row ?
# type "description"
#* A param of type description is replaced by label. The old format (still supported) should be put in another section.
# translatable="no"
#* Have to be done, but I'm not certain how it works. In some cases, the translatable element is the tag value and in other, it's an attribute.
# implements-custom-gui
#* Never used it, what is it ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 01:01, 26 March 2020 (UTC)

# Hi :) Here's a screenshot:
#: https://imgur.com/Sn6B1UZ.png
#: and here's the corresponding inx file:
#: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions (click on 'Expand')
# Right! Sorry about the wrong info.
# I don't know any more than what is written here: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions - ask ede123 / Patrick if there's anything else that you need to know.
# See https://wiki.inkscape.org/wiki/index.php?title=Release_notes/1.0#Extension_dialogs (last item)
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:43, 27 March 2020‎ (UTC)

For (1) what I dont get is how to set the height to a minumum of more than one line ? Does it has to be done by other (side) elements and cover the extra left automatically ? Is there other way? For (4), there's no reference to custom-gui?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 15:31, 9 April 2020 (UTC)

Talk:Extensions: INX widgets and parameters

2020-04-09T16:17:42Z

KBenoit: /* User Moini Added this talk into the page : */

== User [[User:Moini|Moini]] Added this talk into the page : ==
To document:
* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:53, 23 March 2020‎ (UTC)

# Multiline text fields: appearance="multiline"
#* I could not figure out how to set the height to something else than one row ?
# type "description"
#* A param of type description is replaced by label. The old format (still supported) should be put in another section.
# translatable="no"
#* Have to be done, but I'm not certain how it works. In some cases, the translatable element is the tag value and in other, it's an attribute.
# implements-custom-gui
#* Never used it, what is it ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 01:01, 26 March 2020 (UTC)

# Hi :) Here's a screenshot:
#: https://imgur.com/Sn6B1UZ.png
#: and here's the corresponding inx file:
#: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions (click on 'Expand')
# Right! Sorry about the wrong info.
# I don't know any more than what is written here: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions - ask ede123 / Patrick if there's anything else that you need to know.
# See https://wiki.inkscape.org/wiki/index.php?title=Release_notes/1.0#Extension_dialogs (last item)
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:43, 27 March 2020‎ (UTC)

For (1) what I dont get is how to set the height to a minumum of more than one line ? Does it has to be done by other (side) elements and cover the extra left automatically ? Is there other way? For 4, there's no reference to custom-gui?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 15:31, 9 April 2020 (UTC)

Updating your Extension for 1.0

2020-04-09T16:09:29Z

KBenoit: Add syntax highlighting

This is a preliminary and incomplete list of actions to take for updating Python extensions for Inkscape 1.0:

== Adjusting folder structure ==

For easier extension 'installation' by users and for having a better overview about the installed extensions, you can now put extensions into their own subfolders of the <code>extensions</code> directory. This is optional.

When specifying the command in the .inx file, you can use the new parameter 'location'.

* If you set <code>location="extensions"</code> (de-facto default in 0.92.x), it will assume the path is relative to either user or system extensions folder.
* If it's <code>location="inx"</code> (new and recommended in 1.0), it will assume the path is relative to the .inx file location.

An extension that uses the following snippet:

<source lang="xml">
<script>
<command location="inx" interpreter="python">hello.py</command>
</script>
</source>

can be put into any subfolder in <code>extensions</code> or into the <code>extensions</code> folder itself, as long as the file <code>hello.py</code> is in that same folder, at the same hierarchy level.

The old parameter <code>reldir</code> is deprecated. It is recommended to use Unix style path separators (i.e. <code>/</code>), if your script file is located in a nested subdirectory (should be a very rare case).

== Updating *.inx files ==

=== Remove dependency listings ===

Remove the dependency listings for the following modules:

* bezmisc.py
* coloreffect.py
* cspsubdiv.py
* cubicsuperpath.py
* ffgeom.py
* inkex.py (removal not strictly required)
* pathmodifier.py
* simplepath.py
* simplestyle.py
* simpletransform.py
* more?

This change is backwards compatible (as long as the user has a fully functioning Inkscape installation).
Not removing these will result in the extension not being selectable (disabled) in Inkscape 1.0 or higher.

=== Changes to parameter definitions ===

There are also some updates to the parameter definitions in .inx files. While these are intended to be backwards compatible to 0.92, you may wish to review the changes below:

* '''Underscores''' in inx parameter tags and attributes for translation '''can be dropped''' entirely. Use <code>translatable="no"</code> to make an item (e.g.e a unit name) untranslatable.
* <code>boolean</code> can be renamed to <code>bool</code>
* <code><param type="enum" /></code> is deprecated, instead use optiongroups for dropdown selections (comboboxes) and radio buttons (e.g. <code><param type="optiongroup" appearance="combo" /></code>, or <code><param type="optiongroup" appearance="radio" /></code>).
* Appearance value <code>minimal</code> is deprecated
* Choosing files / folders with <code><param type="path" /></code> (these return the path as a string to the Python script):
** Files:
*** Choose a file, with file type restriction (optional): <code><param name="my_file" type="path" mode="file" filetypes="png,jpg" gui-text="A file:">my/path/to/file.png</param></code>
*** Choose multiple files (file type restriction possible, too): <code><param name="my_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param></code>
*** Create a new file: <code><param name="my_new_file" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param></code>
** Folders:
*** Choose a folder: <code><param name="my_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param></code>
*** Choose multiple folders: <code><param name="my_folders" type="path" mode="folders" gui-text="Folders:">my/path/</param></code>
*** Create a new folder: <code><param name="my_new_folder" type="path" mode="folder_new" filetypes="png" gui-text="A new folder:">my/path/</param></code>
* Color choosers: make them more compact with <code>appearance="colorbutton"</code> for parameters of type <code>color</code>
* Multiline text entry fields are available with <code>appearance="multiline"</code> for parameters of type <code>string</code>
* The following new widgets (static, do not need to be read in by the .py file's option parser anymore):
** <code>label</code>: (<code><label>Some text</label></code>), replaces parameters of type <code>description</code> (which never really were parameters in the actual sense), optionally with <code>appearance="header"</code>.
** <code>hbox</code>/<code>vbox</code>: for layouting purposes (allow to pack child widgets into horizontally/vertically oriented boxes)
** <code><spacer/></code>/<code><separator/></code>: which add a variable space or separating line between child widgets.
** <code><image>my_image.svg</image></code>: which allows to display an image in the extension UI

Example file with many of the new features (click on Expand on the right to show, requires an image in the extensions directory with the correct name):

<div class="mw-collapsible mw-collapsed" style="overflow:auto;">

<source lang="xml>
<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
<name>Layout Demo</name>
<id>org.inkscape.test.layout_demo</id>
<dependency type="executable" location="extensions">pathmodifier.py</dependency>

<hbox>
<vbox>
<label appearance="header">Multiple vboxes packed into an hbox</label>
<hbox>
<vbox>
<label>Vertical stack</label>
<param name="param_bool" type="bool" gui-text="Boolean">true</param>
<param name="param_int" type="int" gui-text="Int:" >12345</param>
<param name="param_float" type="float" gui-text="Float:">1.2345</param>
<param name="param_color" type="color" appearance="colorbutton" gui-text="Color:">0x12345678</param>
</vbox>
<spacer />
<vbox>
<label>Vertical stack with separators</label>
<param name="param_string" type="string" gui-text="Single line string:">a string value</param>
<separator></separator>
<param name="param_string_empty" type="string" gui-text="Empty single line:"></param>
<separator></separator>
<param name="param_string_multiline" type="string" appearance="multiline" gui-text="Multiline string:">a\nmultiline\nstring\nvalue</param>
</vbox>
<spacer />
<vbox>
<label>Vertical stack with spacers</label>
<param name="param_file_new" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param>
<spacer />
<param name="param_file" type="path" mode="file" filetypes="png,jpg" gui-text="A file:">my/path/to/file.png</param>
<spacer />
<param name="param_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param>
<spacer />

</vbox>
<spacer />
<vbox>
<label>Vertical stack with expanding spacer</label>
<spacer size="expand"/>
<param name="param_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param>
<param name="param_folders" type="path" mode="folders" gui-text="Folders:">my/path/to/file.png</param>
<param name="param_folder_new" type="path" mode="folder_new" gui-text="A new folder:">my/path/</param>
</vbox>
<spacer />
<vbox>
<label appearance="header">An image!</label>
<image>ink_icon.svg</image>
<spacer />
<label appearance="header" indent="1">Indented header</label>
<spacer />
<label>For details please refer to</label>
<label appearance="url" indent="1">https://clickable.url</label>
</vbox>
</hbox>
</vbox>
</hbox>

<effect needs-live-preview="false">
<object-type>all</object-type>
<effects-menu>
<submenu _name="Test"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">do_nothing.py</command>
</script>
</inkscape-extension>
</source>
</div>

== Updating *.py files ==

=== Collecting the options of the extension ===

# Instead of <code>inkex.Effect.OptionParser.add_option</code>, your extension should now use <code>inkex.Effect.arg_parser.add_argument</code>.
# The 'type' option now works with variables instead of strings. Use <code>int</code> instead of <code>"int"</code> (same for float,...).
# The 'inkbool' type is now <code>inkex.Boolean</code>.
# <code>action="store"</code> can be removed.

These changes are not backwards compatible. The old options will still work, but are deprecated and should no longer be used when you develop your extension for Inkscape 1.0 or higher.

=== Replace specific functions ===

When the .inx file is valid and not greyed out (meaning: a dependency is missing), you can start building the .py file up again.

In the Inkscape extensions refactoring process for Inkscape 1.0, many inkex functions have been removed, or renamed, or moved, or options have changed. Wherever possible, Inkscape will try to replace the old function by the new one, and will give you a deprecation warning, with instructions what to replace them by.

E.g. <code>inkex.Effect.selected</code> is replaced by <code>inkex.Effect.svg.selected</code> - however, most replacements do not follow this naming scheme translation.

These changes are not backwards compatible.

'''The full Python API documentation is available on [https://inkscape.gitlab.io/extensions/documentation/ GitLab].'''

=== Python 3 / Python 2 compatibility ===

Test your extension with both Python 2 and Python 3, if you want it to work for as many users as possible. With the updated extensions, Inkscape does no longer require Python 2, so some users will probably be using Python 3, and may no longer have Python 2 installed on their system. See [[Extension_Interpreters]] for how to set the Python version for your extension in the preferences file (for testing).

== Getting your extension added to Inkscape's stock extensions ==

Inkscape now has a [https://gitlab.com/inkscape/extensions separate repository for its Python extensions], which is included into Inkscape proper by using a Git submodule.

=== Writing tests ===

Previously Inkscape didn't require any unit testing for code. You should now write test code, if you expect your module to be included into the Inkscape extensions repository and included in the shipped Inkscape release. In this case, a test suite file should be made in the tests directory for your extension. It should test each aspect of your extension and exercise all assumptions.

If you are writing a standalone extension that users will install themselves, there is no strict requirement for tests. But having them will greatly improve your code and your ability to upgrade the code later. You can have tests in your own folders and use the extension's setup.py as a harness to run them (a setup.py file is also useful for installing your python code as a non-inkscape related python module, which might be useful too). See Python documentation for creating packages.

=== Documenting your extension ===

== Docstrings ==

Include docstrings in your extension, so documentation can be built from them automatically (see [https://inkscape.gitlab.io/extensions/documentation/ inkex API documentation]) collects the inline documentation comments into a single document.

== Submitting your extension for inclusion ==

Visit https://gitlab.com/inkscape/extensions, fork the repository, and create a merge request on GitLab.

[[Category:Extensions]]

Updating your Extension for 1.0

2020-04-09T16:06:33Z

KBenoit: Highlight the source

This is a preliminary and incomplete list of actions to take for updating Python extensions for Inkscape 1.0:

== Adjusting folder structure ==

For easier extension 'installation' by users and for having a better overview about the installed extensions, you can now put extensions into their own subfolders of the <code>extensions</code> directory. This is optional.

When specifying the command in the .inx file, you can use the new parameter 'location'.

* If you set <code>location="extensions"</code> (de-facto default in 0.92.x), it will assume the path is relative to either user or system extensions folder.
* If it's <code>location="inx"</code> (new and recommended in 1.0), it will assume the path is relative to the .inx file location.

An extension that uses the following snippet:

<pre>
<script>
<command location="inx" interpreter="python">hello.py</command>
</script>
</pre>

can be put into any subfolder in <code>extensions</code> or into the <code>extensions</code> folder itself, as long as the file <code>hello.py</code> is in that same folder, at the same hierarchy level.

The old parameter <code>reldir</code> is deprecated. It is recommended to use Unix style path separators (i.e. <code>/</code>), if your script file is located in a nested subdirectory (should be a very rare case).

== Updating *.inx files ==

=== Remove dependency listings ===

Remove the dependency listings for the following modules:

* bezmisc.py
* coloreffect.py
* cspsubdiv.py
* cubicsuperpath.py
* ffgeom.py
* inkex.py (removal not strictly required)
* pathmodifier.py
* simplepath.py
* simplestyle.py
* simpletransform.py
* more?

This change is backwards compatible (as long as the user has a fully functioning Inkscape installation).
Not removing these will result in the extension not being selectable (disabled) in Inkscape 1.0 or higher.

=== Changes to parameter definitions ===

There are also some updates to the parameter definitions in .inx files. While these are intended to be backwards compatible to 0.92, you may wish to review the changes below:

* '''Underscores''' in inx parameter tags and attributes for translation '''can be dropped''' entirely. Use <code>translatable="no"</code> to make an item (e.g.e a unit name) untranslatable.
* <code>boolean</code> can be renamed to <code>bool</code>
* <code><param type="enum" /></code> is deprecated, instead use optiongroups for dropdown selections (comboboxes) and radio buttons (e.g. <code><param type="optiongroup" appearance="combo" /></code>, or <code><param type="optiongroup" appearance="radio" /></code>).
* Appearance value <code>minimal</code> is deprecated
* Choosing files / folders with <code><param type="path" /></code> (these return the path as a string to the Python script):
** Files:
*** Choose a file, with file type restriction (optional): <code><param name="my_file" type="path" mode="file" filetypes="png,jpg" gui-text="A file:">my/path/to/file.png</param></code>
*** Choose multiple files (file type restriction possible, too): <code><param name="my_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param></code>
*** Create a new file: <code><param name="my_new_file" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param></code>
** Folders:
*** Choose a folder: <code><param name="my_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param></code>
*** Choose multiple folders: <code><param name="my_folders" type="path" mode="folders" gui-text="Folders:">my/path/</param></code>
*** Create a new folder: <code><param name="my_new_folder" type="path" mode="folder_new" filetypes="png" gui-text="A new folder:">my/path/</param></code>
* Color choosers: make them more compact with <code>appearance="colorbutton"</code> for parameters of type <code>color</code>
* Multiline text entry fields are available with <code>appearance="multiline"</code> for parameters of type <code>string</code>
* The following new widgets (static, do not need to be read in by the .py file's option parser anymore):
** <code>label</code>: (<code><label>Some text</label></code>), replaces parameters of type <code>description</code> (which never really were parameters in the actual sense), optionally with <code>appearance="header"</code>.
** <code>hbox</code>/<code>vbox</code>: for layouting purposes (allow to pack child widgets into horizontally/vertically oriented boxes)
** <code><spacer/></code>/<code><separator/></code>: which add a variable space or separating line between child widgets.
** <code><image>my_image.svg</image></code>: which allows to display an image in the extension UI

Example file with many of the new features (click on Expand on the right to show, requires an image in the extensions directory with the correct name):

<div class="mw-collapsible mw-collapsed" style="overflow:auto;">

<source lang="xml>
<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
<name>Layout Demo</name>
<id>org.inkscape.test.layout_demo</id>
<dependency type="executable" location="extensions">pathmodifier.py</dependency>

<hbox>
<vbox>
<label appearance="header">Multiple vboxes packed into an hbox</label>
<hbox>
<vbox>
<label>Vertical stack</label>
<param name="param_bool" type="bool" gui-text="Boolean">true</param>
<param name="param_int" type="int" gui-text="Int:" >12345</param>
<param name="param_float" type="float" gui-text="Float:">1.2345</param>
<param name="param_color" type="color" appearance="colorbutton" gui-text="Color:">0x12345678</param>
</vbox>
<spacer />
<vbox>
<label>Vertical stack with separators</label>
<param name="param_string" type="string" gui-text="Single line string:">a string value</param>
<separator></separator>
<param name="param_string_empty" type="string" gui-text="Empty single line:"></param>
<separator></separator>
<param name="param_string_multiline" type="string" appearance="multiline" gui-text="Multiline string:">a\nmultiline\nstring\nvalue</param>
</vbox>
<spacer />
<vbox>
<label>Vertical stack with spacers</label>
<param name="param_file_new" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param>
<spacer />
<param name="param_file" type="path" mode="file" filetypes="png,jpg" gui-text="A file:">my/path/to/file.png</param>
<spacer />
<param name="param_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param>
<spacer />

</vbox>
<spacer />
<vbox>
<label>Vertical stack with expanding spacer</label>
<spacer size="expand"/>
<param name="param_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param>
<param name="param_folders" type="path" mode="folders" gui-text="Folders:">my/path/to/file.png</param>
<param name="param_folder_new" type="path" mode="folder_new" gui-text="A new folder:">my/path/</param>
</vbox>
<spacer />
<vbox>
<label appearance="header">An image!</label>
<image>ink_icon.svg</image>
<spacer />
<label appearance="header" indent="1">Indented header</label>
<spacer />
<label>For details please refer to</label>
<label appearance="url" indent="1">https://clickable.url</label>
</vbox>
</hbox>
</vbox>
</hbox>

<effect needs-live-preview="false">
<object-type>all</object-type>
<effects-menu>
<submenu _name="Test"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">do_nothing.py</command>
</script>
</inkscape-extension>
</source>
</div>

== Updating *.py files ==

=== Collecting the options of the extension ===

# Instead of <code>inkex.Effect.OptionParser.add_option</code>, your extension should now use <code>inkex.Effect.arg_parser.add_argument</code>.
# The 'type' option now works with variables instead of strings. Use <code>int</code> instead of <code>"int"</code> (same for float,...).
# The 'inkbool' type is now <code>inkex.Boolean</code>.
# <code>action="store"</code> can be removed.

These changes are not backwards compatible. The old options will still work, but are deprecated and should no longer be used when you develop your extension for Inkscape 1.0 or higher.

=== Replace specific functions ===

When the .inx file is valid and not greyed out (meaning: a dependency is missing), you can start building the .py file up again.

In the Inkscape extensions refactoring process for Inkscape 1.0, many inkex functions have been removed, or renamed, or moved, or options have changed. Wherever possible, Inkscape will try to replace the old function by the new one, and will give you a deprecation warning, with instructions what to replace them by.

E.g. <code>inkex.Effect.selected</code> is replaced by <code>inkex.Effect.svg.selected</code> - however, most replacements do not follow this naming scheme translation.

These changes are not backwards compatible.

'''The full Python API documentation is available on [https://inkscape.gitlab.io/extensions/documentation/ GitLab].'''

=== Python 3 / Python 2 compatibility ===

Test your extension with both Python 2 and Python 3, if you want it to work for as many users as possible. With the updated extensions, Inkscape does no longer require Python 2, so some users will probably be using Python 3, and may no longer have Python 2 installed on their system. See [[Extension_Interpreters]] for how to set the Python version for your extension in the preferences file (for testing).

== Getting your extension added to Inkscape's stock extensions ==

Inkscape now has a [https://gitlab.com/inkscape/extensions separate repository for its Python extensions], which is included into Inkscape proper by using a Git submodule.

=== Writing tests ===

Previously Inkscape didn't require any unit testing for code. You should now write test code, if you expect your module to be included into the Inkscape extensions repository and included in the shipped Inkscape release. In this case, a test suite file should be made in the tests directory for your extension. It should test each aspect of your extension and exercise all assumptions.

If you are writing a standalone extension that users will install themselves, there is no strict requirement for tests. But having them will greatly improve your code and your ability to upgrade the code later. You can have tests in your own folders and use the extension's setup.py as a harness to run them (a setup.py file is also useful for installing your python code as a non-inkscape related python module, which might be useful too). See Python documentation for creating packages.

=== Documenting your extension ===

== Docstrings ==

Include docstrings in your extension, so documentation can be built from them automatically (see [https://inkscape.gitlab.io/extensions/documentation/ inkex API documentation]) collects the inline documentation comments into a single document.

== Submitting your extension for inclusion ==

Visit https://gitlab.com/inkscape/extensions, fork the repository, and create a merge request on GitLab.

[[Category:Extensions]]

Talk:Extensions: INX widgets and parameters

2020-04-09T15:31:20Z

KBenoit: Question about multiline

== User [[User:Moini|Moini]] Added this talk into the page : ==
To document:
* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:53, 23 March 2020‎ (UTC)

# Multiline text fields: appearance="multiline"
#* I could not figure out how to set the height to something else than one row ?
# type "description"
#* A param of type description is replaced by label. The old format (still supported) should be put in another section.
# translatable="no"
#* Have to be done, but I'm not certain how it works. In some cases, the translatable element is the tag value and in other, it's an attribute.
# implements-custom-gui
#* Never used it, what is it ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 01:01, 26 March 2020 (UTC)

# Hi :) Here's a screenshot:
#: https://imgur.com/Sn6B1UZ.png
#: and here's the corresponding inx file:
#: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions (click on 'Expand')
# Right! Sorry about the wrong info.
# I don't know any more than what is written here: https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.0#Changes_to_parameter_definitions - ask ede123 / Patrick if there's anything else that you need to know.
# See https://wiki.inkscape.org/wiki/index.php?title=Release_notes/1.0#Extension_dialogs (last item)
[[User:Moini|Moini]] ([[User talk:Moini|talk]]) 23:43, 27 March 2020‎ (UTC)

For (1) what I dont get is how to set the height to a minumum of more than one line ? It has to be done by other (side) elements and cover the extra left automatically ? Is there other way ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 15:31, 9 April 2020 (UTC)

User talk:Moini

2020-04-09T14:59:29Z

KBenoit: How to use wiki discussion

Talk:Extensions: INX widgets and parameters

2020-04-09T14:51:12Z

KBenoit: Cleanup the discussion to be able to see the flow of conversation.

Extensions: INX widgets and parameters

2020-03-28T20:04:34Z

KBenoit: /* Tags for the parameters */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file (~/.config/inkscape/preferences.xml):
<source lang="xml">
<inkscape>
<group id="extensions" com.attrib.id.param_name="param value"/>
</inkscape>
</source>
The (default) values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"] [max-length="5" | appearance="multiline"]>some text</param>
</source>
|}

You can provide an integer to the attribute <code>max-lenght</code> to limit the number of characters you can get.

=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX path.png|none]] || Default's to the path of the folder containing the script
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
| Default value is the first item
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Talk:Extensions: INX widgets and parameters

2020-03-26T01:03:09Z

KBenoit:

User [[User:Moini|Moini]] Added this talk into the page :

To document:
* Multiline text fields: appearance="multiline"
I could not figure out how to set the height to something else than one row ?
* type "description"
A param of type description is replaced by label. The old format (still supported) should be put in another section.
* translatable="no"
Have to be done, but I'm not certain how it works. In some cases, the translatable element is the tag value and in other, it's an attribute.
* implements-custom-gui
Never used it, what is it ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 01:01, 26 March 2020 (UTC)

Talk:Extensions: INX widgets and parameters

2020-03-26T01:01:37Z

KBenoit: Discussion about Moini's comment

User [[User:Moini|Moini]] :

To document:
* Multiline text fields: appearance="multiline"
I could not figure out how to set the height to something else than one row ?
* type "description"
A param of type description is replaced by label. The old format (still supported) should be put in another section.
* translatable="no"
Have to be done, but I'm not certain how it works. In some cases, the translatable element is the tag value and in other, it's an attribute.
* implements-custom-gui
Never used it, what is it ?
[[User:KBenoit|KBenoit]] ([[User talk:KBenoit|talk]]) 01:01, 26 March 2020 (UTC)

Extensions: INX widgets and parameters

2020-03-25T19:53:09Z

KBenoit: /* A combobox or radio buttons */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"] [max-length="5" | appearance="multiline"]>some text</param>
</source>
|}

You can provide an integer to the attribute <code>max-lenght</code> to limit the number of characters you can get.

=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX path.png|none]] || Default's to the path of the folder containing the script
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
| Default value is the first item
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-25T19:50:20Z

KBenoit: /* File chooser */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"] [max-length="5" | appearance="multiline"]>some text</param>
</source>
|}

You can provide an integer to the attribute <code>max-lenght</code> to limit the number of characters you can get.

=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX path.png|none]] || Default's to the path of the folder containing the script
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-25T17:44:14Z

KBenoit: /* Editing INX Parameters in 1.0 */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"] [max-length="5" | appearance="multiline"]>some text</param>
</source>
|}

You can provide an integer to the attribute <code>max-lenght</code> to limit the number of characters you can get.

=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX path.png|none]] ||
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* type "description"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-25T04:53:07Z

KBenoit: /* File chooser */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX path.png|none]] ||
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

File:INX path.png

2020-03-25T04:47:45Z

KBenoit:

Widget (button) to choose a file/folder name

Extensions: INX widgets and parameters

2020-03-25T04:30:23Z

KBenoit: /* Color */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple views/options in the same dialog window.
|-
| colspan="2" | It helps with layouting, and allows you to retrieve the active page (tab) name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*If the same <code><param name></code> is used in multiple tabs, its value will be taken from the last <code><page></code> it appears on.
**This means that it's best to use different names if the same parameter is used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet
|
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| rowspan="2" scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]
| scope="col" style="width: 240px; height: 35px; background-color:#f0f0f0;" | [[File:INX color-btn.png]]
| Default value is <code>#000000FF</code>
|-
| colspan="2" style="vertical-align: top;" |
{|
| style="padding-left: 6em;" | ↑With↑ the attribute <code>appearance="colorbutton"</code>
|-
| style="height: 100px;" | ⇇ Without <code>appearance="colorbutton"</code>
|}
|-
| colspan=3 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

The parameter value is an RGBA value in hexadecimal notation.

To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

File:INX color-btn.png

2020-03-25T01:30:58Z

KBenoit:

Example of <param type="color" appearance="colorbutton">

Extensions: INX widgets and parameters

2020-03-25T00:55:09Z

KBenoit: /* Color */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple view/options in the same window.
|-
| colspan="2" | It can help with layout, but give you the active page name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*For the same <code><param name></code> used on multiple pages, you get the value from the last <code><page></code> it appear.
**This means that it's best to use a different names for the same parameter used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet
|
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-color.png]]|| Default value is <code>#000000FF</code>
|-
| colspan=2 |
<source lang="xml">
<param type="color" name="varname" [appearance="colorbutton" gui-text="label"] [indent="1"]/>
</source>
|}

You get an RGBA value in hexadecimal

To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-24T22:46:29Z

KBenoit: /* Color */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple view/options in the same window.
|-
| colspan="2" | It can help with layout, but give you the active page name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*For the same <code><param name></code> used on multiple pages, you get the value from the last <code><page></code> it appear.
**This means that it's best to use a different names for the same parameter used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet
|
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet.|| Default value is <code>#000000FF</code>
|-
| colspan=2 |
<source lang="xml">
<param type="color" name="varname" [indent="1"]/>
</source>
|}

You get an RGBA value in hexadecimal

To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-24T22:37:10Z

KBenoit: /* A combobox or radio buttons */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple view/options in the same window.
|-
| colspan="2" | It can help with layout, but give you the active page name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*For the same <code><param name></code> used on multiple pages, you get the value from the last <code><page></code> it appear.
**This means that it's best to use a different names for the same parameter used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet
|
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
|
|-
| colspan="3" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

=== Color ===
{| class="wikitable"
|+ Get a hex color value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet.||
|-
| colspan=2 |
<source lang="xml">
<param name="name" type="color"></param>
</source>
|}
To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-24T22:13:58Z

KBenoit: /* Editing INX Parameters in 1.0 */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Parameter values (when opening the dialog) are set to the last used value, which is saved in the user's preferences file. The values in the inx file are visible only when the user first uses the extension.

=== Notebook ===
{| class="wikitable"
|+ Multiple view/options in the same window.
|-
| colspan="2" | It can help with layout, but give you the active page name.
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-notebook.png|border]]
| It defaults to the first page.
|-
| colspan="2" | <source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
|}
*The value of the selected <code><page name></code> attribute will be passed as an argument to your extension.
**The default value is the name of the first page.
*For the same <code><param name></code> used on multiple pages, you get the value from the last <code><page></code> it appear.
**This means that it's best to use a different names for the same parameter used on multiple pages.

=== Checkbox ===

{| class="wikitable"
|+ To get a boolean value
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-boolean.png]]
| The default value is <code>true</code>
|-
| colspan="2" |
<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>
|}
=== Numeric spinner ===

{| class="wikitable"
|+ To get numbers, int or float
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-float.png]]
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-int.png]]
| The default value is 0
|-
| colspan="3" |
{| style="margin: auto;"
|+ With <code>appearance="full"</code>, you get a full width slider.
|-
| scope="col" style="border: 1px solid #a2a9b1; background-color:#f0f0f0;" | [[File:INX_sample-float_full.png|center]]
|}
|-
| colspan="3" |
<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>
|}
* The widget has a precision of 0.1 for float.
* The default <code>min</code> value is "0".
* The default <code>max</code> value is "10".

=== Text fields ===

{| class="wikitable"
|+ Get text input
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-string.png]]
| The default value is the empty string and with such a value, the parameter is omitted.
|-
| colspan="2" |
<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>
|}
=== File chooser ===

{| class="wikitable"
|+ Get a path, either a file or a directory
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | No image yet
|
|-
| colspan="2" | Use one of:
<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>
|}
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) open a file browser for selecting 1 object.
** The versions ending with a <code>s</code> open a file browser for selecting multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
|+ To get a choice of predefined values
|-
| scope="col" style="width: 240px; background-color:#f0f0f0;" | [[File:INX_sample-optiongroup.png]]
| scope="col" style="background-color:#f0f0f0;" | [[File:INX_sample-optiongroup-minimal.png]]
|-
| colspan="2" |
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
|}
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

To document:

* Multiline text fields: appearance="multiline"
* Links: appearance="url" for INX Parameters of type "description"
* New color chooser option: appearance="colorbutton"
* translatable="no"
* implements-custom-gui

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T22:50:31Z

KBenoit:

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Defaults values are set to the last used value, the defaults values in the inx file are for the first use.

=== Notebook ===

{| class="wikitable"
| These can help with layout. The default value is the name of the first page.
|-
| [[File:INX_sample-notebook.png]]
|}

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>
*You get the value of the selected <code><page name></code> attribute as an argument to your extension.

*For a <code><param></code> used on multiple pages, you get the value of the <code><param></code> from the last <code><page></code>.
** You better give them different parameter names.

=== Checkbox ===

{| class="wikitable"
| The Default value is <code>true</code>
|-
| [[File:INX_sample-boolean.png]]
|}

<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>

=== Numerical input spinner ===

{| class="wikitable"
| colspan="2" | The default value is 0
|-
| [[File:INX_sample-float.png]]
|-
| With <code>appearance="full"</code> use a full width slider.
|-
| [[File:INX_sample-float_full.png]]
|}

<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>

* The widget has a precision of 0.1 for float.
*
* The default <code>min</code> is "0"
* The default <code>max</code> is "10"

=== Textbox ===

{| class="wikitable"
| The default value is the empty string and with such a value, the parameter is omited.
|-
| [[File:INX_sample-string.png]]
|}

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

=== File chooser ===

{| class="wikitable"
| To get a path, either a file or a directory
|-
| No image yet
|}

<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>

* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) means to use a file chooser for 1 object.
** The versions ending with a <code>s</code> mean to use a file chooser for multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

=== A combobox or radio buttons ===

{| class="wikitable"
| colspan="2" | To get a choice of predefined values
|-
| [[File:INX_sample-optiongroup.png]]
| [[File:INX_sample-optiongroup-minimal.png]]
|}

<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>
* The default <code>appearance</code> is <code>"radio"</code>. The appearance <code>"combo"</code> is also valid.

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T20:06:59Z

KBenoit:

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

= Editing INX Parameters in 1.0 =

In this section:
* When an attribute is in square brackets (<code>[name="value"]</code>), it means that <code>name</code> is optional.
* The 1 in <code>indent="1"</code> is the indentation level that you want.

== Tags for the layout ==

<source lang="xml">
<label [indent="1"] [appearance="header"]>Some text</label>
<label [indent="1"] [appearance="url"]>http://some/url</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

== Tags for the parameters ==

* The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get.
* Defaults values are set to the last used value, the defaults values in the inx file are for the first use.

=== Tab view of pages ===
These can help with layout.
* You get the value of the selected <code><page name></code> attribute as an argument to your extension.
* For a <code><param></code> used on multiple pages, you get the value of the <code><param></code> from the last <code><page></code>.
** You better give them different parameter names.

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

=== Checkbox ===

Default value is <code>true</code>.

<source lang="xml">
<param type="bool" name="varname" gui-text="label" [indent="1"]>false</param>
</source>

=== Numerical input spinner ===
The widget has a precision of 0.1 for float.
* With <code>appearance="full"</code> also use a full width slider.
* The default <code>min</code> is "0"
* The default <code>max</code> is "10"
* The default value is 0

<source lang="xml">
<param type="int" name="varname" gui-text="labal" [min="1"] [max="10"] [appearance="full"] [indent="1"]/>
<param type="float" name="varname" gui-text="label" [min="0.5"] [max="5.0"] [appearance="full"] [indent="1"]/>
</source>

=== Textbox ===

The default value is the empty string and with such a value, the parameter is omited.

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

=== File chooser ===
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) means to use a file chooser for 1 object.
** The versions ending with a <code>s</code> mean to use a file chooser for multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>

=== A choice in a list ===
* The default <code>appearance</code> is <code>"radio"</code>, but can be also be <code>"combo"</code>.
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T17:37:26Z

KBenoit:

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

== INX Documentation for 1.0 ==

It the following sections, When you see <code>[name="value"]</code>, it means that <code>name</code> is an optional attribute. <code>att="val1"|"val2"</code> means eithe <code>"val1"</code> or <code>val2</code> are valid values for <code>att</code>. The <code>"1"</code> in <code>indent="1"</code> attributes can be changed by the indentation level you want.

=== Tags for the layout ===

<source lang="xml">
<label [indent="1"] [appearance="header"|"url"]>Some text</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

=== Tags for the parameters ===

The <code>name</code> attribute of tag <code><param></code> means the name of the argument (<code>--name=</code>) your command will get. Defaults are set to the last used value, the defaults in the inx file are for the first use.

==== Tab view of pages ====
These can help with layout.
* You get the selected <code><page></code> as an argument to your extension.
* You get the <code><param></code> arguments of last <code><page></code> containing it. You better give them different parameter names.

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

==== Checkbox. ====

Default's to <code>true</code>.

<source lang="xml">
<param type="boolean" name="varname" gui-text="label" [indent="1"]>false</param>
</source>

==== Numerical input spinner ====
The widget has a precision of 0.1 for float.
* With <code>appearance="full"</code> also use a full width slider.
* The default <code>min</code> is "0"
* The default <code>max</code> is "10"

<source lang="xml">
<param type="int" name="varname" [min="1"] [max="10"] gui-text="labal" [appearance="full"] [indent="1"]/>
<param type="float" name="varname" [min="0.5"] [max="5.0"] gui-text="label" [appearance="full"] [indent="1"]/>
</source>

==== Textbox ====

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

==== File chooser ====
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) means to use a file chooser for 1 object.
** The versions ending with a <code>s</code> mean to use a file chooser for multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>

==== A choice in a list ====
* The default <code>appearance</code> is <code>"radio"</code>, but can be also be <code>"combo"</code>.
<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" [appearance="combo"|appearance="radio"] [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T13:55:13Z

KBenoit: /* Path chooser */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

== INX Documentation for 1.0 ==

It the following sections, When you see <code>[name="value"]</code>, it means that <code>name</code> is an optional attribute. <code>att="val1"|"val2"</code> means eithe <code>"val1"</code> or <code>val2</code> are valid values for <code>att</code>. The <code>"1"</code> in <code>indent="1"</code> attributes can be changed by the indentation level you want.

=== Tags for the layout ===

<source lang="xml">
<label [indent="1"] [appearance="header"|"url"]>Some text</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

=== Tags for the parameters ===

The attribute <code>name</code> of tag <code>param</code> means the name of the argument <code>--name=</code> your command will get.

==== Tab view of pages ====
These can help with layout, but give the info of which <code><page></code> was selected as an argument to your extension. At the same time, it give you arguments of the <code><param></code> of each <code><page></code>. This mean that having the same <code>name</code> attribute for <code><param></code> on 2 or more pages, get in conflict. So if you have an argument that repeat on multiple pages, you need to give different names.

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

==== For checkbox. ====

You can set a default 1 as true or 0 as false value:

<source lang="xml">
<param type="boolean" name="varname" gui-text="{text}" [indent="1"]>1</param>
</source>

==== For numerical input spinner. ====

With the attribute <code>appearance="full"</code> also use a full width slider. The min and max take numeric values.

<source lang="xml">
<param type="int" name="varname" min="1" max="10" gui-text="labal" [appearance="full"] [indent="1"]/>
<param type="float" name="varname" min="0.5" max="5.0" gui-text="label" [appearance="full"] [indent="1"]/>
</source>

==== Textbox ====

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

==== File chooser ====
* The attribute <code>mode</code> with a value of:
** <code>"file"</code> or <code>"folder"</code> (without <code>s</code>) means to use a file chooser for 1 object.
** The versions ending with a <code>s</code> mean to use a file chooser for multiple objects.
** And the ones ending with <code>_new</code> are for creating new objects.
* The <code>filetype</code> attribute contains a list of file extensions to look for. In this example only svg or png files will be displayed.

<source lang="xml">
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="files" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="file_new" filetypes="svg,png"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folders"/>
<param type="path" name="varname" gui-text="label" [indent="1"] mode="folder_new"/>
</source>

==== A choise in a list ====
Presented as combobox or radio buttons.

<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" appearance="combo"|"radio" [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T00:36:56Z

KBenoit: /* Tab view of pages */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

== INX Documentation for 1.0 ==

It the following sections, When you see <code>[name="value"]</code>, it means that <code>name</code> is an optional attribute. <code>att="val1"|"val2"</code> means eithe <code>"val1"</code> or <code>val2</code> are valid values for <code>att</code>. The <code>"1"</code> in <code>indent="1"</code> attributes can be changed by the indentation level you want.

=== Tags for the layout ===

<source lang="xml">
<label [indent="1"] [appearance="header"|"url"]>Some text</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

=== Tags for the parameters ===

The attribute <code>name</code> of tag <code>param</code> means the name of the argument <code>--name=</code> your command will get.

==== Tab view of pages ====
These can help with layout, but give the info of which <code><page></code> was selected as an argument to your extension. At the same time, it give you arguments of the <code><param></code> of each <code><page></code>. This mean that having the same <code>name</code> attribute for <code><param></code> on 2 or more pages, get in conflict. So if you have an argument that repeat on multiple pages, you need to give different names.

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

==== For checkbox. ====

You can set a default 1 as true or 0 as false value:

<source lang="xml">
<param type="boolean" name="varname" gui-text="{text}" [indent="1"]>1</param>
</source>

==== For numerical input spinner. ====

With the attribute <code>appearance="full"</code> also use a full width slider. The min and max take numeric values.

<source lang="xml">
<param type="int" name="varname" min="1" max="10" gui-text="labal" [appearance="full"] [indent="1"]/>
<param type="float" name="varname" min="0.5" max="5.0" gui-text="label" [appearance="full"] [indent="1"]/>
</source>

==== Textbox ====

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

==== Path chooser ====

<source lang="xml">
<param type="path" name="varname" mode="file"|"files"|"file_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
<param type="path" name="varname" mode="folder"|"folders"|"folder_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
</source>

==== A choise in a list ====
Presented as combobox or radio buttons.

<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" appearance="combo"|"radio" [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T00:28:07Z

KBenoit: /* INX Documentation for 1.0 */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

== INX Documentation for 1.0 ==

It the following sections, When you see <code>[name="value"]</code>, it means that <code>name</code> is an optional attribute. <code>att="val1"|"val2"</code> means eithe <code>"val1"</code> or <code>val2</code> are valid values for <code>att</code>. The <code>"1"</code> in <code>indent="1"</code> attributes can be changed by the indentation level you want.

=== Tags for the layout ===

<source lang="xml">
<label [indent="1"] [appearance="header"|"url"]>Some text</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

=== Tags for the parameters ===

The attribute <code>name</code> of tag <code>param</code> means the name of the argument <code>--name=</code> your command will get.

==== Tab view of pages ====
These can help with layout, but give the info of which page was selected as an argument to your extension. At the same time, it give you arguments of the <code>param</code> on each page and having the same name for <code><param></code>

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

==== For checkbox. ====

You can set a default 1 as true or 0 as false value:

<source lang="xml">
<param type="boolean" name="varname" gui-text="{text}" [indent="1"]>1</param>
</source>

==== For numerical input spinner. ====

With the attribute <code>appearance="full"</code> also use a full width slider. The min and max take numeric values.

<source lang="xml">
<param type="int" name="varname" min="1" max="10" gui-text="labal" [appearance="full"] [indent="1"]/>
<param type="float" name="varname" min="0.5" max="5.0" gui-text="label" [appearance="full"] [indent="1"]/>
</source>

==== Textbox ====

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

==== Path chooser ====

<source lang="xml">
<param type="path" name="varname" mode="file"|"files"|"file_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
<param type="path" name="varname" mode="folder"|"folders"|"folder_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
</source>

==== A choise in a list ====
Presented as combobox or radio buttons.

<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" appearance="combo"|"radio" [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-23T00:26:49Z

KBenoit: /* INX Documentation for 1.0 */

Here you will find the different parameter elements you may use in your .inx files (Inkscape Extensions)

== Introduction ==
Use parameter elements to capture user input for further use by a script. The basic structure of the element is:

<source lang="xml">
<param name="some_name" type="some_type">default value</param>
</source>

The default value is the value that is shown in the input control the first time the user opens the dialog window. Inkscape automatically displays the values used last time when the dialog window is opened again.

== Common attributes ==

=== gui-description ===
Tooltip of the parameter, which is shown when the user hovers the mouse cursor over the active area of the parameter in question.

To enable translations for this string use the underscore variant (<code>_gui-description </code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== gui-hidden ===
If the value is set to <code>true</code> the parameter is hidden from the GUI (defaults to <code>false</code>).

=== gui-text ===
Label of the parameter.

To enable translations for this string use the underscore variant (<code>_gui-text</code>, see [[#Localization of parameters|localization of parameters]] below for details).

=== indent ===
Sets indentation level of the parameter (e.g. <code>indent="1"</code>).

=== name ===
The value of the <code>name</code> attribute is used as an identifier of the parameter. It has to be unique since the value of this attribute is used to save and transmit parameter values internally!

=== type ===
The <code>type</code> attribute determines the type of the parameter (for tags <code><param></code>) (possible values are <code>boolean, int, float, string, enum, optiongroup, color, notebook, description</code>), see the extensive description of [[#Available types|available types]] below.

== Available types ==

{| class="wikitable" style="width:100%"

|-
! Type
! Description / Code
! Result

|-
! boolean
|Creates a checkbox input to set a '''boolean value'''. Set the default value to <code>true</code> or <code>1</code>, <code>false</code> or <code>0</code>.

<pre>
<param name="name" type="boolean" gui-text="Some label text">false</param>
</pre>
|[[File:INX_sample-boolean.png]]

|-
! color
|Creates a control to select a '''color value'''.
The '''returned value''' is an RGBA-value.

<pre>
<param name="name" type="color"></param>
</pre>
|[[File:INX_sample-color.png]]

|-
! description
|Creates a text element. Specifying the attribute <code>xml:space="preserve"</code> preserves whitespace in the text content of the description and enables multiline text.

<pre>
<param name="name" type="description">Some text here.</param>
</pre>

When additionally setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
<pre><param name="name" type="description" appearance="header">Header</param></pre>

All <code>description</code> type parameters are purely informational (they do not return any value). They are intended to be used to provide additional information / help on other parameters (Consider using the <code>gui-description</code> attribute for short help texts that are specific to a single parameter, though).

|[[File:INX_sample-description.png]] default appearance 
[[File:INX_sample-description_header.png]] with <code>appearance="header"</code>  

|-
! enum
|Creates a drop-down list from which '''one predefined value''' can be chosen. The different choices are created with <code><item></code> elements. The first <code><item></code> is selected by default.
The '''returned value''' for <code>enum</code> type parameters is the value of the <code>value</code> attribute of the selected <code><item></code>.

<pre>
<param name="name" type="enum" gui-text="Some label text">
<item value="1">First option</item>
<item value="2">Second option</item>
</param>
</pre>
|[[File:INX_sample-enum.png]]

|-
! float
|Creates a textbox input to enter a '''floating point number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes; set the number of decimal places with the <code>precision</code> attribute. (Default: <code>min="0"</code>, <code>max="10"</code> and <code>precision="1"</code>)

<pre>
<param name="name" type="float" precision="3" min="0" max="9999"
gui-text="Some label text">1.234</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the floating point value can be adjusted dynamically over the full range.
|[[File:INX_sample-float.png]] [[File:INX_sample-float_full.png|240px]]

|-
! int
|Creates a textbox input to enter an '''integer number'''. Limit the input range with the <code>min</code> and <code>max</code> attributes. (Default: <code>min="0"</code> and <code>max="10"</code>)

<pre>
<param name="name" type="int" min="1" max="100" gui-text="Some label text">1</param>
</pre>

Use the attribute <code>appearance="full"</code> to create a slider with which the integer value can be adjusted dynamically over the full range.
|[[File:INX_sample-int.png]] [[File:INX_sample-int_full.png|240px]]

|-
! notebook
|Creates a set of pages (aka tab control). The user can switch between individual pages, each page can contain an arbitrary set of other parameters. Individual pages are created with the <code><page></code> element.
The '''returned value''' for <code>notebook</code> type parameters is the value of the <code>name</code> attribute of the selected <code><page></code>.

<pre>
<param name="name" type="notebook">
<page name="page_1" gui-text="First page">
<param>...</param>
</page>
<page name="page_2" gui-text="Second page">
<param>...</param>
</page>
</param>
</pre>
|[[File:INX_sample-notebook.png]]

|-
! optiongroup
|Creates a set of radio buttons from which '''one predefined value''' can be chosen. The different choices are created with <code><option></code> elements. The first <code><option></code> is selected by default.
The '''returned value''' for <code>optiongroup</code> type parameters is the value of the <code>value</code> attribute of the selected <code><option></code>.

<pre>
<param name="name" type="optiongroup"
gui-text="Some label text">
<option value="1">First option</option>
<option value="2">Second option</option>
</param>
</pre>

Set the attribute <code>appearance="minimal"</code> to display a drop-down list instead of radio buttons. 
''The option group will occupy the minimum space on the right hand side of the dialog. Versus the Enum, which expands to fill available space.''
|[[File:INX_sample-optiongroup.png]] [[File:INX_sample-optiongroup-minimal.png]]

|-
! string
|Creates a textbox input to enter a '''character string'''. Limit the number of characters the user is allowed to enter with the <code>max_length</code> attribute. (Default: no limit)

<pre>
<param name="name" type="string" gui-text="Some text label">Some default text</param>
</pre>
|[[File:INX_sample-string.png]]

|}

== Localization of parameters ==

To mark parameters to be included into the translation files (this is done automatically during the build process) there exist special variants of all relevant attributes and tag names that start with an underscore.

* Labels and tooltips can be marked for translation by simply using the attribute names <code>_gui-text</code> and <code>_gui-description</code> instead of their counterparts without underscore.
* For <code><item></code>s and <code><option></code>s (both of which do not use the attributes just explained) add an underscore to the tag name itself: <code><_item value="1">Localized item name</_item></code> and <code><_option value="1">Localized option name</_option></code> respectively.
* Also for <code>description</code> type (and ''only'' for <code>description</code> type!) parameters an underscore is added to the tag name itself: <code><_param type="description">Localized text here.</_param></code>

== INX Documentation for 1.0 ==

It the following sections, When you see <code>[name="value"]</code>, it means that <code>name</code> is an optional attribute. <code>att="val1"|"val2"</code> means eithe <code>"val1"</code> or <code>val2</code> are valid values for <code>att</code>. The <code>"1"</code> in <code>indent="1"</code> attributes can be changed by the indentation level you want.

=== Tags for the layout ===

<source lang="xml">
<label [indent="1"] [appearance="header"|"url"]>Some text</label>
<image>some/inx/relative/path/to/img.svg</image>
<spacer/>
<separator [indent="1"]/>
<hbox [indent="1"]></hbox>
<vbox [indent="1"]></vbox>
</source>

=== Tags for the parameters ===

The attribute <code>name</code> of tag <code>param</code> means the name of the argument <code>--name=</code> your command will get.

==== Tab view of pages ====
These can help with layout, but give the info of which page was selected as an argument to your extension. At the same time, it give you arguments of the <code>param</code> on each page and having the same name for <code><param>

<source lang="xml">
<param type="notebook" name="varname" [indent="1"]>
<page name="value" gui-text="label">

</page>

</param>
</source>

==== For checkbox. ====

You can set a default 1 as true or 0 as false value:

<source lang="xml">
<param type="boolean" name="varname" gui-text="{text}" [indent="1"]>1</param>
</source>

==== For numerical input spinner. ====

With the attribute <code>appearance="full"</code> also use a full width slider. The min and max take numeric values.

<source lang="xml">
<param type="int" name="varname" min="1" max="10" gui-text="labal" [appearance="full"] [indent="1"]/>
<param type="float" name="varname" min="0.5" max="5.0" gui-text="label" [appearance="full"] [indent="1"]/>
</source>

==== Textbox ====

<source lang="xml">
<param type="string" name="varname" gui-text="label" [indent="1"]>some text</param>
</source>

==== Path chooser ====

<source lang="xml">
<param type="path" name="varname" mode="file"|"files"|"file_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
<param type="path" name="varname" mode="folder"|"folders"|"folder_new" filename="fileExt,moreExt" gui-text="label" [indent="1"]>/some/path.ext</param>
</source>

==== A choise in a list ====
Presented as combobox or radio buttons.

<source lang="xml">
<param type="optiongroup" name="varname" gui-text="label" appearance="combo"|"radio" [indent="1"]>
<item value="value">Some text</item>

</param>
</source>

[[Category:Developer Documentation]]
[[Category:Extensions]]

Extensions: INX widgets and parameters

2020-03-22T22:22:02Z

KBenoit: /* For textbox */

Extensions: INX widgets and parameters

2020-03-22T21:24:53Z

KBenoit: /* Localization of parameters */

Extensions: INX widgets and parameters

2020-03-22T19:38:37Z

KBenoit: /* type */ The type is available for param

Extensions: INX widgets and parameters

2020-03-22T19:31:24Z

KBenoit: /* Introduction */ Set highlighting to XML