|
|
| (3 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| This page is intended for extension authors who want to use the new capabilities of inkex in Inkscape 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 [[Release notes/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 [[Release notes/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>
| |
| |}
| |
| | |
| ==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].
| |