Difference between revisions of "Updating your Extension for 1.0"
(→Changes to parameter definitions: not done yet.) |
|||
Line 38: | Line 38: | ||
*** Choose multiple files (file type restriction possible, too): <code><param name="param_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param></code> | *** Choose multiple files (file type restriction possible, too): <code><param name="param_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param></code> | ||
*** Create a new file: <code><param name="param_file_new" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param></code> | *** Create a new file: <code><param name="param_file_new" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param></code> | ||
** Folders: | ** Folders (these return the path as a string to the Python script): | ||
*** Choose a folder: <code><param name="param_folder" type="path" mode="folder" gui-text="A folder:">my/path/ | *** Choose a folder: <code><param name="param_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param></code> | ||
*** Choose multiple folders: <code><param name="param_folders" type="path" mode="folders" gui-text="Folders:">my/path/ | *** Choose multiple folders: <code><param name="param_folders" type="path" mode="folders" gui-text="Folders:">my/path/</param></code> | ||
*** Create a new folder: <code><param name="param_folder_new" type="path" mode="folder_new" filetypes="png" gui-text="A new folder:">my/path/ | *** Create a new folder: <code><param name="param_folder_new" 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> | * 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> | * Multiline text entry fields are available with <code>appearance="multiline"</code> for parameters of type <code>string</code> |
Revision as of 02:42, 8 February 2020
This is a preliminary and incomplete list of actions to take for updating Python extensions for Inkscape 1.0:
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 available 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 as documented in MR#808.
They include:
- Underscores in inx parameter tags for translation can be dropped entirely
boolean
can be renamed tobool
<param type="enum" />
is deprecated, instead use optiongroups for dropdown selections (comboboxes) and radio buttons (e.g.<param type="optiongroup" appearance="combo" />
, or<param type="optiongroup" appearance="radio" />
).- Appearance value
minimal
is deprecated - Choosing files / folders with
<param type="path" />
:- Files:
- Choose a file, with file type restriction (optional):
<param name="param_file" type="path" mode="file" filetypes="png,jpg" gui-text="A file:">my/path/to/file.png</param>
- Choose multiple files (file type restriction possible, too):
<param name="param_files" type="path" mode="files" gui-text="Multiple files:">my/path/to/file.png</param>
- Create a new file:
<param name="param_file_new" type="path" mode="file_new" filetypes="png" gui-text="A new file:">my/path/to/file.png</param>
- Choose a file, with file type restriction (optional):
- Folders (these return the path as a string to the Python script):
- Choose a folder:
<param name="param_folder" type="path" mode="folder" gui-text="A folder:">my/path/</param>
- Choose multiple folders:
<param name="param_folders" type="path" mode="folders" gui-text="Folders:">my/path/</param>
- Create a new folder:
<param name="param_folder_new" type="path" mode="folder_new" filetypes="png" gui-text="A new folder:">my/path/</param>
- Choose a folder:
- Files:
- Color choosers: make them more compact with
appearance="colorbutton"
for parameters of typecolor
- Multiline text entry fields are available with
appearance="multiline"
for parameters of typestring
- The following new widgets (static, do not need to be read in by the .py file:
label
: (<label>Some text</label>
), replaces parameters of typedescription
(which never really were parameters in the actual sense)hbox
/vbox
for lay-outing purposes (allow to pack child widgets into horizontally/vertically oriented boxes)spacer
/separator
which add a variable space or separating line between child widgets.image
which allows to display an image in the extension UI
Updating *.py files
Collecting the options of the extension
- Instead of
inkex.Effect.OptionParser.add_option
, your extension should now useinkex.Effect.arg_parser.add_argument
. - The 'type' option now works with variables instead of strings. Use
int
instead of"int"
(same for float,...). - The 'inkbool' type is now
inkex.inkbool
. action="store"
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
pathmodifier.zsort()
is nowinkex.zsort()
(more info: https://gitlab.com/inkscape/extensions/issues/24).
Lots more, someone needs to flesh this out.
Test run your extension
Many functions, when run, will still work, but they will give you a deprecation warning, with instructions what to replace them by.
E.g. inkex.Effect.selected
is replaced by inkex.Effect.svg.selected
- however, most replacements do not follow this naming scheme translation.
These changes are not backwards compatible.
Python 3 / Python 2 compatibility
Test your extension with both Python 2 and Python 3. 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 (for testing).
Getting your extension added to Inkscape's stock extensions
Inkscape now has a 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
TODO
API documentation
The 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.