Difference between revisions of "Updating your Extension for 1.2"

From Inkscape Wiki
Jump to navigation Jump to search
(Move documentation)
Tags: Replaced Visual edit
 
Line 1: Line 1:
This page is intended for extension authors who want to use the new capabilities of inkex in Inkscape 1.2. As of the Release of 1.2alpha (Feb 5, 2022), no more breaking changes will be introduced until the final release of 1.2.
This page was intended for extension authors who want to use the new capabilities of inkex in Inkscape 1.2. It has been moved to the [https://inkscape.gitlab.io/extensions/documentation/authors/update1.2.html extensions repository documentation].
 
There are no breaking changes in this release, but a few methods have been deprecated.
 
== Deprecating changes ==
 
*The Transforms multiplication operator has been changed from <code>*</code> (<code>*=</code>) to <code>@</code> (<code>@=</code>), in accordance with [https://www.python.org/dev/peps/pep-0465/ PEP-465] ([https://gitlab.com/inkscape/extensions/-/merge_requests/389 MR extensions#389], [https://gitlab.com/inkscape/extensions/-/issues/327 Issue extensions#327])
*<code>svg.width</code> and <code>svg.height</code> have been deprecated, and replaced with <code>svg.viewbox_width</code>, <code>svg.viewport_width</code>, <code>svg.viewbox_height</code> and <code>svg.viewport_height</code>, see [[Updating your Extension for 1.2#New Units API|New Units API]].
*<code>selection.paint_order</code> has been renamed to <code>selection.rendering_order</code> to be conformant with the specification ([https://gitlab.com/inkscape/extensions/-/merge_requests/344 MR extensions#344], [https://gitlab.com/inkscape/extensions/-/issues/310 Issue extensions#310])
*<code>FallbackStyle</code> has been deprecated in favor of <code>Style</code>, see  [[Updating your Extension for 1.2#New Style API|New Style API]].
 
==New Style API==
[[File:Comparison of Lighter extension in Inkscape 1.1.2 and 1.2.png|thumb|Top: W3C SVG1.1 Test suite, test [https://www.w3.org/Graphics/SVG/Test/20110816/harness/htmlObjectApproved/styling-css-04-f.html styling-css-04-f.svg]. This test includes various CSS selectors, and includes group inheritance and pseudo-selectors. It is rendered correctly in Inkscape 1.2. Bottom left: Output of the "Lighter" extension in Inkscape 1.1.2, only two squares are processed correctly, two squares have a wrong color and the other 14 raise unhandled exceptions. Bottom right: Correct output in Inkscape 1.2. This shows that inkex correctly handles different types of CSS selectors.]]
Added in [https://gitlab.com/inkscape/extensions/-/merge_requests/294 MR extensions#294], [https://gitlab.com/inkscape/extensions/-/merge_requests/296 MR extensions#296], [https://gitlab.com/inkscape/extensions/-/merge_requests/298 MR extensions#298], [https://gitlab.com/inkscape/extensions/-/merge_requests/300 MR extensions#300], [https://gitlab.com/inkscape/extensions/-/merge_requests/352 MR extensions#352], [https://gitlab.com/inkscape/extensions/-/merge_requests/403 MR extensions#403]
 
Inkex now exposes styles to extensions authors as intended by the SVG specification. This means:
*<code>BaseElement</code> now has functions <code>cascaded_style</code>, <code>specified_style</code> and <code>presentation_style</code>.
*In most use cases, extensions querying a style will use <code>specified_style</code>. This computes the [https://www.w3.org/TR/CSS22/cascade.html#specified-value effective style] of the element, including CSS classes / pseudo-selectors, inherited styles, presentation attributes etc.
*While <code>style.get()</code> and <code>style[key]</code> has been unchaged, a new getter has been added in form of <code>style(key)</code> (similar to a function call), which attempts to parse the attribute in a reasonable datatype. If the attribute is unset, the (parsed) default value will be returned.  For example:
**<code>style("fill")</code> returns a <code>Color</code> / <code>Gradient</code> / <code>Pattern</code> / <code>None</code>,
**<code>style("opacity")</code> returns a value between 0 and 1, regardless if opacity is defined as percentage or as float, is out of bounds or undefined,
**<code>style("stroke-dasharray")</code> returns a list of floats of dash/gap/dash/gap in user units.
*Not for all attributes there is a parser defined - in that case, a string will be returned. Additional parsers may be added in the future, so if you handle the string value, typecheck it first!
 
=== Using the new Style API in your extension ===
The following calls can probably be simplified:
{| class="wikitable"
|+
!Old code (pre-1.2)
!New code (1.2+)
|-
|<syntaxhighlight lang="python3">
if "fill-opacity" in self.style:
    alpha = self.style["fill-opacity"]
else:
    alpha = 1
</syntaxhighlight>
|<syntaxhighlight lang="python3">
alpha = self.style("fill-opacity")
</syntaxhighlight>
|-
|<syntaxhighlight lang="python3">
if not node.style.get(attr, '').startswith('url(#'):
    continue
 
marker_id = node.style[attr][5:-1]
marker_node = self.svg.getElement('/svg:svg//svg:marker[@id="%s"]' % marker_id)
 
 
</syntaxhighlight>
|<syntaxhighlight lang="python3">
marker_node = node.style(attr)
</syntaxhighlight>
|-
|<syntaxhighlight lang="python3">
obj.style['fill'] = pattern.get_id(2)
</syntaxhighlight>
|<syntaxhighlight lang="python3">
obj.style['fill'] = pattern
</syntaxhighlight>
|}
Checkout [https://gitlab.com/inkscape/extensions/-/merge_requests/298 MR extensions#298] for additional examples of simplifications.
 
==New Units API==
[[File:Viewport and viewbox coordinate system.png|thumb|500x500px|The user coordinate system is defined with the viewbox attribute, while the <code>viewport</code> coordinate system is defined with the <code>width</code> and <code>height</code> attributes of the <code><svg></code> element.]]
Added in [https://gitlab.com/inkscape/extensions/-/merge_requests/329 MR extensions#329], [https://gitlab.com/inkscape/extensions/-/merge_requests/343 MR extensions#343], [https://gitlab.com/inkscape/extensions/-/merge_requests/415 MR extensions#415]
 
The existing functions <code>unittouu</code> and <code>uutounit</code> are widely used, but for different purposes. Different extension authors try to answer different questions using these function, and, inevitably, some answers were incorrect (see linked issues in [https://gitlab.com/inkscape/extensions/-/merge_requests/329 MR extensions#329]).
 
In Inkscape 1.2, new methods have been added to make working with dimensional values easier. These are <code>to_dimensionless</code>, <code>to_dimensional</code>, <code>viewport_to_unit</code> and <code>unit_to_viewport</code>. The existing functions <code>unittouu</code> and <code>uutounit</code> are not deprecated, but discouraged; in most cases, the new functions are more reliable.
*<code>to_dimensionless(value)</code> fulfills the following task:  '''Convert this string from the XML into a number, while processing the unit. When using this function on any SVG attribute and replace the original value with the result, the output doesn't change visually.'''
*<code>viewport_to_unit(value, target_unit="px")</code> answers the following questions:
**'''What is the length (e.g. the length of a rectangle, without a unit) of an object that has size <code>value</code> on the viewport?'''  This is relevant because in Inkscape toolbars / tools, all dimensions are shown in "viewport units".
**In other words: '''What is the SVG representation of entering <code>value</code> in the width/height widget of the selection tool (set to the unit of value)?''' Consider  <code><svg width="210mm" viewBox="0 0 105 147.5"><rect width="?" height="?"/></svg></code>,  i.e. a "mm-based" SVG with scale=2. When typing <code>200</code> in the rectangle tool, set to mm, the XML editor shows <code>100</code> = <code>100px</code>. That's what <code>viewport_to_unit("200mm") = 100</code> does.
**Note that this is different than <code>viewport_to_unit("200", "mm")</code>, which would be for a rectangle with a width (in the width/height widget of the rectangle tool) of 200 (px), while writing the width in <code>mm</code> ''in the SVG'':  <code><rect width="7.00043mm" height="7.00043mm"/>.</code>
*<code>to_dimensional</code> simply converts a float to its equivalent with attached unit. It's the opposite of <code>to_dimensionless</code>.
*<code>unit_to_viewport(value, unit="px")</code> answers the following question: '''What does the the width/height widget of the selection tool (set to <code>unit</code>) show when selecting an element with width <code>value</code> as defined in the SVG?''' Consider again  <code><svg width="210mm" viewBox="0 0 105 147.5"><rect width="100" height="100"/></svg></code>,  i.e. a "mm-based" document with scale=2. To create this rectangle, one has to type <code>viewport_to_unit("100", unit="mm") = 200</code> into the rectangle tool, if the rectangle tool is set to mm.
With the same spirit, the functions for width/height of the document have been updated. <code>svg.width</code> and <code>svg.height</code> have been deprecated, and replaced with <code>svg.viewbox_width</code>, <code>svg.viewport_width</code>, <code>svg.viewbox_height</code> and <code>svg.viewport_height</code>.
 
There is also <code>svg.scale</code>, which returns the ratio of the viewport and viewbox width, and <code>svg.inkscape_scale</code> which is the scale reported in the Document properties dialog.
 
See the [https://inkscape.gitlab.io/extensions/documentation/units.html inkex documentation] for additional information.
==Other additions to inkex==
*The path conversion for arcs and stars have been added, so when extensions create these objects, they are rendered in a browser as well and can be processed further by the same extension. ([https://gitlab.com/inkscape/extensions/-/merge_requests/387 MR extensions#387], [https://gitlab.com/inkscape/extensions/-/issues/240 Issue extensions#240])
*<code>ColorExtension</code>s can now process in RGBA space. Previously, opacity and color were processed independently. By setting the class variable <code>pass_rgba = True</code>, the <code>modify_color</code> method gets passed a color with alpha channel computed from matching property pairs, e.g. <code>fill</code> and <code>fill-opacity</code>. (This value takes CSS styling and style inheritance into account. ([https://gitlab.com/inkscape/extensions/-/merge_requests/392 MR extensions#392] , [https://gitlab.com/inkscape/extensions/-/issues/419 Issue extensions#419]).
*API functions for the new [[Release notes/1.2#Page tool|multipage feature]] have been added: [https://gitlab.com/inkscape/extensions/-/merge_requests/399 MR extensions#499].

Latest revision as of 19:03, 3 March 2022

This page was intended for extension authors who want to use the new capabilities of inkex in Inkscape 1.2. It has been moved to the extensions repository documentation.

Retrieved from "https://wiki.inkscape.org/wiki/index.php?title=Updating_your_Extension_for_1.2&oldid=120964"