Extensions: INX widgets and parameters - Revision history

Moini at 19:55, 3 February 2023

2023-02-03T19:55:24Z

← Older revision		Revision as of 19:55, 3 February 2023
Line 1:		Line 1:
	~~The documentation for INX widgets and parameters has been moved to the [~~https://inkscape.gitlab.io/extensions/documentation/authors/inx-widgets.html ~~documentation of the extensions repository].~~		{{Template:MovedToOtherSite\|topic=Extension development\|new_url=https://inkscape.gitlab.io/extensions/documentation/authors/inx-widgets.html\|new_site=GitLab}}

	~~{\| class="wikitable" style="vertical~~-~~align:top;" valign="top"~~		----
	\|- ~~style="border:none;background:none"~~

	\|}

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

Joneuhauser at 20:14, 10 March 2022

2022-03-10T20:14:39Z

← Older revision		Revision as of 20:14, 10 March 2022
Line 1:		Line 1:
	The documentation for INX widgets and parameters has been moved to the [https://inkscape.gitlab.io/extensions/documentation/authors/inx.html documentation of the extensions repository].		The documentation for INX widgets and parameters has been moved to the [https://inkscape.gitlab.io/extensions/documentation/authors/inx-widgets.html documentation of the extensions repository].

	{\| class="wikitable" style="vertical-align:top;" valign="top"		{\| class="wikitable" style="vertical-align:top;" valign="top"

Joneuhauser: Move documentation.

2022-03-03T18:55:59Z

Move documentation.

Show changes

Nathanal: /* Parameters */ Add mandatory attribute to example (gitlab inbox#4614)

2021-05-08T01:57:10Z

Parameters: Add mandatory attribute to example (gitlab inbox#4614)

← Older revision		Revision as of 01:57, 8 May 2021
Line 227:		Line 227:

	<source lang="xml">		<source lang="xml">
	<param name="name" type="color">0x000000ff</param>		<param name="name" type="color" gui-text="Some label text">0x000000ff</param>
	</source>		</source>

Leyghis at 09:24, 27 April 2021

2021-04-27T09:24:33Z

← Older revision		Revision as of 09:24, 27 April 2021
Line 145:		Line 145:

	<source lang="xml">		<source lang="xml">
	<image>path/to/image.svg</~~label~~>		<image>path/to/image.svg</image>
	</source>		</source>

Patrick87: /* Parameters */

2021-03-22T23:42:37Z

Parameters

← Older revision		Revision as of 23:42, 22 March 2021
Line 342:		Line 342:

	\|		\|
	[[File:INX_sample-string.png\|frame\|none\|default]]		[[File:INX_sample-string.png\|frame\|none\|<ul><li>default (top)</li><li><code>appearance="multiline"</code> (bottom)</li></ul>]]

	~~[[File:INX_sample-multiline-string.png\|frame\|none\|~~<code>appearance="multiline"</code>]]

	\|}		\|}

Patrick87 at 00:06, 22 March 2021

2021-03-22T00:06:23Z

← Older revision		Revision as of 00:06, 22 March 2021
Line 70:		Line 70:
	\|- style="vertical-align:top;"		\|- style="vertical-align:top;"
	\| style="white-space:nowrap" \| <code>indent</code>		\| style="white-space:nowrap" \| <code>indent</code>
	\| <code>0,1,2,~~...~~</code>		\| <code>0,1,2,…</code>
	\| <code>0</code>		\| <code>0</code>
	\| optional		\| optional
Line 127:		Line 127:

	<source lang="xml">		<source lang="xml">
	<hbox>~~...~~</hbox>		<hbox>…</hbox>
	<vbox>~~...~~</vbox>		<vbox>…</vbox>
	</source>		</source>

Line 279:		Line 279:
	<param name="name" type="notebook">		<param name="name" type="notebook">
	<page name="page_1" gui-text="First page">		<page name="page_1" gui-text="First page">
	~~...~~		…
	</page>		</page>
	<page name="page_2" gui-text="Second page">		<page name="page_2" gui-text="Second page">
	~~...~~		…
	</page>		</page>
	</param>		</param>
Line 368:		Line 368:
	\|-		\|-
	! boolean{{deprecated_in\|1.0}}		! boolean{{deprecated_in\|1.0}}
	\|'''Replace with <code><param type="bool" ~~...~~/></code> parameter.'''		\|'''Replace with <code><param type="bool" …/></code> parameter.'''

	Creates a checkbox to set a '''boolean value'''. Allowed values are <code>true</code> or <code>false</code> (default value: <code>true</code>).		Creates a checkbox to set a '''boolean value'''. Allowed values are <code>true</code> or <code>false</code> (default value: <code>true</code>).
Line 380:		Line 380:
	\|-		\|-
	! description{{deprecated_in\|1.0}}		! description{{deprecated_in\|1.0}}
	\|'''Replace with <code><label>~~...~~</label></code> widget.'''		\|'''Replace with <code><label>…</label></code> widget.'''

	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.		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.
Line 400:		Line 400:
	\|-		\|-
	! enum{{deprecated_in\|1.0}}		! enum{{deprecated_in\|1.0}}
	\|'''Replace with <code><optiongroup appearance="combo" ~~...~~></code> parameter.'''		\|'''Replace with <code><optiongroup appearance="combo" …></code> parameter.'''

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

Patrick87: /* Widgets */

2021-03-21T23:58:51Z

Widgets

← Older revision		Revision as of 23:58, 21 March 2021
Line 200:		Line 200:

	\|}		\|}


	~~; TODO:~~
	~~<source lang="xml">~~
	~~<image>some/inx/relative/path/to/img.svg</image>~~
	~~<spacer/>~~
	~~<separator [indent="1"]/>~~
	~~<hbox [indent="1"]></hbox>~~
	~~<vbox [indent="1"]></vbox>~~
	~~</source>~~

	== Parameters ==		== Parameters ==

Patrick87: /* Widgets */

2021-03-21T23:58:35Z

Widgets

← Older revision		Revision as of 23:58, 21 March 2021
Line 121:		Line 121:
	! Description / Code		! Description / Code
	! Result		! Result

			\|-
			! hbox/vbox
			\|Creates a container for other widgets. No visual rendering but provides a possibility to align and layout other widgets. Child widgets are either added in horizontal (<code>hbox</code>) or vertical (<code>vbox</code>) direction.

			<source lang="xml">
			<hbox>...</hbox>
			<vbox>...</vbox>
			</source>

			A box can contain an arbitrary number of other widgets and parameters (including other boxes) to fine-tune the layout of the GUI.

			''Note: When you start with an empty extension GUI, you're basically starting with a <code>vbox</code>. Also <code>notebook</code> pages behave like vertically oriented boxes.

			\|
			[[File:INX_sample-separators.png]]



			\|-
			! image
			\|Creates a widget displaying an image. The content of the <code><image></code> node specifies the path of the image file (ideally specify a path relative to the .inx file itself).

			<source lang="xml">
			<image>path/to/image.svg</label>
			</source>

			By default the image will be rendered at it's actual size. Use attributes <code>width/heigth</code> to override the default size (in this case ''both'' attributes need to be supplied; units are pixels).

			''Implementation note: Loadable image formats are determined by GdkPixbuf and therefore system-specific. PNG should always work and is the safe choice. SVG should mostly work and is the preferred choice for obvious reasons.''

			\|
			[[File:INX_sample-image.png]]

	\|-		\|-
	! label		! label
	\|Creates a text ~~element~~. ~~Specifying~~ the ~~attribute~~ <code>~~xml:space="preserve"~~</code> ~~preserves whitespace in~~ the text content ~~of the label and enables multiline text~~.		\|Creates a widget showing text. The content of the <code><label></code> node corresponds to the text content that will be rendered.

	<source lang="xml">		<source lang="xml">
Line 130:		Line 163:
	</source>		</source>

	''Note: Labels are intended to provide additional information / help. ~~Do label~~ parameters use the <code>gui-text</code> attribute ~~instead~~; for short help texts that are specific to a single parameter ~~consider using~~ <code>gui-description</code> which will render as a tooltip.''		''Note: Labels are intended to provide additional information / help. For labeling parameters use the <code>gui-text</code> attribute; for short help texts that are specific to a single parameter prefer <code>gui-description</code> which will render as a tooltip.''

			* When setting the attribute <code>appearance="header"</code> the text is styled as a heading and can be used as another possibility to group parameters.
			* When setting the attribute <code>appearance="url"</code> the text is rendered as a clickable link.<br/>''Note: The text is escaped and used as the link target as-is. Creating a link text that differs from the URL is prevented for security reasons.''
			* When setting the attribute <code>xml:space="preserve"</code> any white-space (spaces, tabs, line-breaks, etc.) in the label will be preserved, allowing to format the label accordingly. By default all leading/tailing and intermediary whitespace is collapsed into a single space character.

			\|
			[[File:INX_sample-labels.png\|frame\|none\|Different label types (in order):<ul><li>default</li><li><code>appearance="header"</code></li><li><code>appearance="url"</code></li><li><code>xml:space="preserve"</code></li></ul>]]

	~~When setting the attribute <code>appearance="header"</code> the text is styled~~ as a ~~heading and can be used as another possibility to group parameters~~.		\|-
	~~<source lang="xml"><label appearance="header">Header</label></source>~~		! separator
			\|Creates a separator for visual separation of other widgets. Renders as a horizontal/vertical line.

	~~When setting the attribute <code>appearance="url"</code> the text is rendered as a clickable link.~~		<source lang="xml">
	<source lang="xml"><~~label appearance="url">https:~~/~~/inkscape.org</label~~></source>		<separator />
	~~''Note: The text is escaped and used as the link target as-is. Creating a link text that differs from the URL is prevented for security reasons.''~~		</source>

	~~\|[[File:INX_sample-description.png]]~~<br><~~small~~>~~default appearance<~~/~~small>~~<br><br><br><br>		The direction of the separator will automatically adjust depending on direction of the current container (vertical for "empty" extension GUIs and <code>notebook</code> pages; vertical/horizontal for <code>vbox</code> and <code>hbox</code> respectively).
	[[File:INX_sample-~~description_header~~.png]]~~<br><small>with <code>appearance="header"</code></small><br><br><br> ~~		\|
	~~<!-- TODO: image for appearance="url" -->~~		[[File:INX_sample-separators.png]]

	\|-		\|-
			! spacer
			\|Creates a spacer for visual separation of other widgets. No visual rendering but provides variable spacing.

			<source lang="xml">
			<spacer />
			</source>

			The direction of the spacer will automatically adjust depending on direction of the current container (vertical for "empty" extension GUIs and <code>notebook</code> pages; vertical/horizontal for <code>vbox</code> and <code>hbox</code> respectively).

			Use the <code>size</code> attribute to set the spacing in pixels (default: <code>size="10"</code>). The special value <code>expand</code> results in a spacer that grows dynamically and always uses up as much space as possible (useful for aligning content).

			\|
			[[File:INX_sample-spacers.png\|frame\|none\|Different spacer types:<ol><li>default</li><li><code>size="20"</code></li><li><code>size="expand"</code></li></ol>]]

	\|}		\|}
Line 150:		Line 204:
	; TODO:		; TODO:
	<source lang="xml">		<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>		<image>some/inx/relative/path/to/img.svg</image>
	<spacer/>		<spacer/>
Line 158:		Line 210:
	<vbox [indent="1"]></vbox>		<vbox [indent="1"]></vbox>
	</source>		</source>


	== Parameters ==		== Parameters ==

Patrick87 at 21:00, 21 March 2021

2021-03-21T21:00:37Z

← Older revision		Revision as of 21:00, 21 March 2021
Line 22:		Line 22:
	where <code>widget_name</code> specifies the name of the widget and is one of the following:		where <code>widget_name</code> specifies the name of the widget and is one of the following:

	* <code>label</code>		* <code>label</code>{{added_in\|1.0}}
	* <code>hbox</code>/<code>vbox</code>		* <code>hbox</code>{{added_in\|1.0}}/<code>vbox</code>{{added_in\|1.0}}
	* <code>separator</code>/<code>spacer</code>		* <code>separator</code>{{added_in\|1.0}}/<code>spacer</code>{{added_in\|1.0}}
	* <code>image</code>		* <code>image</code>{{added_in\|1.0}}
	* <code>param</code> (for all Parameter types)		* <code>param</code> (for all Parameter types)

Line 38:		Line 38:
	where <code>parameter_type</code> specifies the type of the parameter and is one of the following:		where <code>parameter_type</code> specifies the type of the parameter and is one of the following:

	* <code>bool</code>		* <code>bool</code>{{added_in\|1.0}}
	* <code>int</code>		* <code>int</code>
	* <code>float</code>		* <code>float</code>
	* <code>string</code>		* <code>string</code>
	* <code>path</code>		* <code>path</code>{{added_in\|1.0}}
	* <code>optiongroup</code>		* <code>optiongroup</code>
	* <code>notebook</code>		* <code>notebook</code>
Line 172:		Line 172:

	\|-		\|-
	! ~~boolean~~		! bool{{added_in\|1.0}}
	\|Creates a checkbox to set a '''boolean value'''. Allowed values are <code>true</code> or <code>false</code> (default value: <code>true</code>).		\|Creates a checkbox to set a '''boolean value'''. Allowed values are <code>true</code> or <code>false</code> (default value: <code>true</code>).

Line 324:		Line 324:
	! Description / Code		! Description / Code
	! Result		! Result

			\|-
			! boolean{{deprecated_in\|1.0}}
			\|'''Replace with <code><param type="bool" .../></code> parameter.'''

			Creates a checkbox to set a '''boolean value'''. Allowed values are <code>true</code> or <code>false</code> (default value: <code>true</code>).

			<source lang="xml">
			<param name="name" type="boolean" gui-text="Some label text">false</param>
			</source>

			\|[[File:INX_sample-boolean.png]]

	\|-		\|-