Improve Python API - Document + Notifier
This MR is a first set of improvements for Python API.
The goal here is to try to provides additional methods to manage documents and let users being able to work with some Krita's UI commands without trying to tweak/hack UI like it is currently made.
In synthesis, this MR:
- Update
Documentclass - Update
Notifierclass - Add new classes
GuidesConfig,GridConfigandMirrorAxisConfig - Improve API documentation (update
.hfiles used to generate API documentation) - Improve class cast (to get right cast from SIP binding instead of having generic QObject -- especially from Signals)
Notes
- Some methods in classes have been deprecated (use of
Q_DECL_DEPRECATED)
These methods are still here and are still usable to ensure compatibility with plugins
For each deprecated method, documentation inform the DEPRECATED state of method For each deprecated method, when called aqWarning()will generate a message to inform plugin developer to update the plugin or to not use the method anymore (the warning mean the plugin developer takes care about messages in log console or in terminal...)- For implementation of Mirror Axis, due to Krita's internal architecture, some choice have been made (ie: mirror axis are provided as a
Documentproperty instead of aViewresource)- For implementation of some signals, I've used signal compressor to avoid plugins to consume too much resources, but I didn't used compressor for all signals
Example: used compressor on fg/bg color update, but not on brush size (because in my mind, plugins that connect signal on color change will probably generate more intensive computation than a plugin that is connected to brush size signal)
Class GuidesConfig
New class
This class is a wrapper on KisGuidesConfig and is used with Document class.
| Method | Description |
|---|---|
color() |
Return guides color |
setColor() |
Define guides color |
lineType() |
Return Guides line type |
setLineType() |
Define guides lines type |
hasGuides() |
indicate if there's guides defined |
hasSamePositionAs() |
indicate if position from current guides configuration match positions from another guides configuration |
horizontalGuides() |
The horizontal guides |
setHorizontalGuides() |
Set the horizontal guides |
verticalGuides() |
The vertical guides |
setVerticalGuides |
Set the vertical guides |
fromXml() |
Load guides definition from an XML document |
toXml() |
Save guides definition as an XML document |
removeAllGuides() |
Remove all guides |
visible() |
Returns guides visibility status |
setVisible() |
Set guides visibility status |
locked() |
Returns guide lock status |
setLocked() |
Set guides lock status |
snap() |
Returns guide snap status |
setSnap() |
Set guides snap status |
Class GridConfig
New class
This class is a wrapper on KisGridConfig and is used with Document class.
| Method | Description |
|---|---|
visible() |
Returns guides visibility status |
setVisible() |
Set guides visibility status |
snap() |
Returns guide snap status |
setSnap() |
Set guides snap status |
offset() |
Return grid offset |
setOffset() |
Set grid offset |
spacing() |
Return grid spacing |
setSpacing() |
Set grid spacing |
spacingActiveHorizontal() |
Return if horizontal grid spacing is active |
setSpacingActiveHorizontal() |
Set if horizontal grid spacing is active |
spacingActiveVertical() |
Return if vertical grid spacing is active |
setSpacingActiveVertical() |
Set if vertical grid spacing is active |
subdivision() |
Return number of grid subdivision |
setSubdivision() |
Set number of grid subdivision |
angleLeft() |
Return left angle value (in degree) |
setAngleLeft() |
Set left angle value (in degree) |
angleRight() |
Return right angle value (in degree) |
setAngleRight() |
Set right angle value (in degree) |
angleLeftActive() |
Return if left angle grid is active |
setAngleLeftActive() |
Set if left angle value grid is active |
angleRightActive() |
Return if right angle value grid is active |
setAngleRightActive() |
Set if right angle value grid is active |
cellSpacing() |
Return grid cell spacing |
setCellSpacing() |
Set grid cell spacing |
cellSize() |
Return grid cell size |
setCellSize() |
Set grid cell size |
type() |
Return grid type |
setType() |
Set grid type |
offsetAspectLocked() |
Returns offset aspect ratio lock status |
setOffsetAspectLocked() |
Set offset aspect ratio lock status |
spacingAspectLocked() |
Returns spacing aspect ratio lock status |
setSpacingAspectLocked() |
Set spacing aspect ratio lock status |
angleAspectLocked() |
Returns angle aspect ratio lock status |
setAngleAspectLocked() |
Set angle aspect ratio lock status |
lineTypeMain() |
Return main grid line type |
setLineTypeMain() |
Define main grid lines type |
lineTypeSubdivision() |
Return subdivision grid line type |
setLineTypeSubdivision() |
Define subdivision grid lines type |
lineTypeVertical() |
Return vertical grid line type |
setLineTypeVertical() |
Define vertical grid lines type |
colorMain() |
Return main grid color |
setColorMain() |
Set main grid color |
colorSubdivision() |
Return subdivision grid color |
setColorSubdivision() |
Set subdivision grid color |
colorVertical() |
Return vertical grid color |
setColorVertical() |
Set vertical grid color |
fromXml() |
Load guides definition from an XML document |
toXml() |
Save guides definition as an XML document |
Class MirrorAxisConfig
New class
This class is a wrapper on KisMirrorAxisConfig and is used with Document class.
| Method | Description |
|---|---|
horizontal() |
return the horizontal mirror axis status (active/inactive) |
setHorizontal() |
set the horizontal mirror axis status (active/inactive) |
vertical() |
return the vertical mirror axis status (active/inactive) |
setVertical() |
set the vertical mirror axis status (active/inactive) |
horizontalLock() |
return the horizontal mirror axis lock status (locked/unlocked) |
setHorizontalLock() |
set the horizontal mirror axis lock status (locked/unlocked) |
verticalLock() |
return the vertical mirror axis lock status (locked/unlocked) |
setVerticalLock() |
set the vertical mirror axis lock status (locked/unlocked) |
horizontalDecorationHidden() |
return the horizontal mirror axis visibility status (visible/hidden) |
setHorizontalDecorationHidden() |
set the horizontal mirror axis visibility status (visible/hidden) |
verticalDecorationHidden() |
return the vertical mirror axis visibility status (visible/hidden) |
setVerticalDecorationHidden() |
set the vertical mirror axis visibility status (visible/hidden) |
handleSize() |
return the mirror axis handle size |
setHandleSize() |
set the mirror axis handle size |
horizontalHandlePosition() |
return the horizontal mirror axis handle position |
setHorizontalHandlePosition() |
set the horizontal mirror axis handle position |
verticalHandlePosition() |
return the vertical mirror axis handle position |
setVerticalHandlePosition() |
set the vertical mirror axis handle position |
horizontalAxisPosition() |
return the horizontal mirror axis position |
setHorizontalAxisPosition() |
set the horizontal mirror axis position |
verticalAxisPosition() |
return the vertical mirror axis position |
setVerticalAxisPosition() |
set the vertical mirror axis position |
fromXml() |
Load mirror axis definition from an XML string |
toXml() |
Save mirror axis definition as an XML string |
Class Document
Updated class
Class has been updated to provide new methods
| Method | Description |
|---|---|
guidesConfig() |
Returns a GuidesConfig guides configuration for current document |
setGuidesConfig() |
Set guides configuration for current document |
gridConfig() |
Returns a GridConfig grid configuration for current document |
setGridConfig() |
Set grid configuration for current document |
mirrorAxisConfig() |
Returns a MirrorAxisConfig configuration for current document |
setMirrorAxisConfig() |
Set mirror axis configuration for current document |
autosave() |
Return autosave status for document |
setAutosave() |
Allow to activate/deactivate autosave for document |
audioLevel() |
Return audio level for document |
setAudioLevel() |
Allow to define audio level for document |
audioTracks() |
Return list of audio tracks used by document |
setAudioTracks() |
Set list of audio tracks used by document |
Deprecated methods
| Method | Description |
|---|---|
horizontalGuides() |
use guidesConfig() instead |
verticalGuides() |
use guidesConfig() instead |
guidesVisible() |
use guidesConfig() instead |
guidesLocked() |
use guidesConfig() instead |
setHorizontalGuides() |
use guidesConfig() instead |
setVerticalGuides() |
use guidesConfig() instead |
setGuidesVisible() |
use guidesConfig() instead |
setGuidesLocked() |
use guidesConfig() instead |
Class Notifier
Updated class
| Signal | Description |
|---|---|
documentCreated() |
replace imageCreated()
|
documentSaved() |
replace imageSaved()
|
documentIsBeingSaved() |
Emitted when document is about to be saved |
documentClosed() |
replace imageClosed()
|
documentModified() |
Emitted when modified status of document change |
documentUpdated() |
Emitted when document is updated in any way |
documentGuidesUpdated() |
Emitted when document guides settings are modified |
documentGridUpdated() |
Emitted when document grid settings are modified |
documentAudioLevelUpdated() |
Emitted when document audio level is modified |
documentAudioTracksUpdated() |
Emitted when document audio tracks list is modified |
viewChanged() |
Current active view has changed |
viewBrushForegroundColorChanged() |
Emitted when current foreground brush color is modified |
viewBrushBackgroundColorChanged() |
Emitted when current background brush color is modified |
viewBrushForegroundColorUsed() |
Emitted when current foreground brush color is used for the time |
viewBrushOpacityChanged() |
Emitted when current brush opacity is modified |
viewBrushPresetChanged() |
Emitted when current brush preset is modified |
viewBrushBlendingModeChanged() |
Emitted when current brush blending mode is modified |
viewBrushEraserModeChanged() |
Emitted when current brush eraser mode is modified |
viewBrushFlowChanged() |
Emitted when current brush flow is modified |
viewBrushSizeChanged() |
Emitted when current brush size is modified |
viewBrushRotationChanged() |
Emitted when current brush rotation is modified |
viewBrushPatternSizeChanged() |
Emitted when current brush pattern size is modified |
viewBrushGlobalAlphaLockChanged() |
Emitted when current brush alpha lock status is modified |
viewBrushDisabledPressureChanged() |
Emitted when current brush pen pressure status is modified |
viewResourceGradientChanged() |
Emitted when current brush gradient is modified |
viewResourcePatternChanged() |
Emitted when current brush pattern is modified |
viewHDRExposureChanged() |
Emitted when current HDR Exposure value is modified |
viewHDRGammaChanged() |
Emitted when current HDR Gamma value is modified |
viewNodeChanged() |
Emitted when current active node is modified |
viewMirrorChanged() |
Emitted when current mirror view mode is modified |
Deprecated methods
| Method | Description |
|---|---|
imageCreated() |
use documentCreated() instead |
imageSaved() |
use documentSaved() instead |
imageClosed() |
use documentClosed() instead |
Test Plan
Check files for tests implementation:
| File | Test |
|---|---|
plugins/extensions/pykrita/manual_tests/notifier_test_script.py |
Manual tests for Notifier class |
plugins/extensions/pykrita/manual_tests/documents_test_script.py |
Manual tests for Document, GuidesConfig, GridConfig , MirrorAxisConfig classes |
Formalities Checklist
-
I confirmed this builds. -
I confirmed Krita ran and the relevant functions work. -
I tested the relevant unit tests and can confirm they are not broken. (If not possible, don't hesitate to ask for help!) -
I made sure my commits build individually and have good descriptions as per KDE guidelines. -
I made sure my code conforms to the standards set in the HACKING file. -
I can confirm the code is licensed and attributed appropriately, and that unattributed code is mine, as per KDE Licensing Policy. -
Does the patch add a user-visible feature? If yes, is there a documentation MR ready for it at Krita Documentation Repository?
Reminder: the reviewer is responsible for merging the patch, this is to ensure at the least two people can build the patch. In case a patch breaks the build, both the author and the reviewer should be contacted to fix the build. If this is not possible, the commits shall be reverted, and a notification with the reasoning and any relevant logs shall be sent to the mailing list, kimageshop@kde.org.