Krita

Document.h
1 /*
2  * SPDX-FileCopyrightText: 2016 Boudewijn Rempt <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 #ifndef LIBKIS_DOCUMENT_H
7 #define LIBKIS_DOCUMENT_H
8 
9 #include <QObject>
10 
11 #include "kritalibkis_export.h"
12 #include "libkis.h"
13 
14 #include "GroupLayer.h"
15 #include "CloneLayer.h"
16 #include "FileLayer.h"
17 #include "FilterLayer.h"
18 #include "FillLayer.h"
19 #include "VectorLayer.h"
20 #include "FilterMask.h"
21 #include "SelectionMask.h"
22 #include "TransparencyMask.h"
23 #include "TransformMask.h"
24 #include "ColorizeMask.h"
25 
26 class KisDocument;
27 
28 /**
29  * The Document class encapsulates a Krita Document/Image. A Krita document is an Image with
30  * a filename. Libkis does not differentiate between a document and an image, like Krita does
31  * internally.
32  */
33 class KRITALIBKIS_EXPORT Document : public QObject
34 {
35  Q_OBJECT
37 
38 public:
39  explicit Document(KisDocument *document, bool ownsDocument, QObject *parent = 0);
40  ~Document() override;
41 
42  bool operator==(const Document &other) const;
43  bool operator!=(const Document &other) const;
44 
45  /**
46  * @brief horizontalGuides
47  * The horizontal guides.
48  * @return a list of the horizontal positions of guides.
49  */
50  QList<qreal> horizontalGuides() const;
51  /**
52  * @brief verticalGuides
53  * The vertical guide lines.
54  * @return a list of vertical guides.
55  */
56  QList<qreal> verticalGuides() const;
57 
58  /**
59  * @brief guidesVisible
60  * Returns guide visibility.
61  * @return whether the guides are visible.
62  */
63  bool guidesVisible() const;
64  /**
65  * @brief guidesLocked
66  * Returns guide lockedness.
67  * @return whether the guides are locked.
68  */
69  bool guidesLocked() const;
70 
71 public Q_SLOTS:
72 
73  /**
74  * @brief clone create a shallow clone of this document.
75  * @return a new Document that should be identical to this one in every respect.
76  */
77  Document *clone() const;
78 
79  /**
80  * Batchmode means that no actions on the document should show dialogs or popups.
81  * @return true if the document is in batchmode.
82  */
83  bool batchmode() const;
84 
85  /**
86  * Set batchmode to @p value. If batchmode is true, then there should be no popups
87  * or dialogs shown to the user.
88  */
89  void setBatchmode(bool value);
90 
91  /**
92  * @brief activeNode retrieve the node that is currently active in the currently active window
93  * @return the active node. If there is no active window, the first child node is returned.
94  */
95  Node* activeNode() const;
96 
97  /**
98  * @brief setActiveNode make the given node active in the currently active view and window
99  * @param value the node to make active.
100  */
101  void setActiveNode(Node* value);
102 
103  /**
104  * @brief toplevelNodes return a list with all top level nodes in the image graph
105  */
106  QList<Node*> topLevelNodes() const;
107 
108  /**
109  * @brief nodeByName searches the node tree for a node with the given name and returns it
110  * @param name the name of the node
111  * @return the first node with the given name or 0 if no node is found
112  */
113  Node *nodeByName(const QString &name) const;
114 
115 
116  /**
117  * @brief nodeByUniqueID searches the node tree for a node with the given name and returns it.
118  * @param uuid the unique id of the node
119  * @return the node with the given unique id, or 0 if no node is found.
120  */
121  Node *nodeByUniqueID(const QUuid &id) const;
122 
123  /**
124  * colorDepth A string describing the color depth of the image:
125  * <ul>
126  * <li>U8: unsigned 8 bits integer, the most common type</li>
127  * <li>U16: unsigned 16 bits integer</li>
128  * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
129  * <li>F32: 32 bits floating point</li>
130  * </ul>
131  * @return the color depth.
132  */
133  QString colorDepth() const;
134 
135  /**
136  * @brief colorModel retrieve the current color model of this document:
137  * <ul>
138  * <li>A: Alpha mask</li>
139  * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
140  * <li>XYZA: XYZ with alpha channel</li>
141  * <li>LABA: LAB with alpha channel</li>
142  * <li>CMYKA: CMYK with alpha channel</li>
143  * <li>GRAYA: Gray with alpha channel</li>
144  * <li>YCbCrA: YCbCr with alpha channel</li>
145  * </ul>
146  * @return the internal color model string.
147  */
148  QString colorModel() const;
149 
150  /**
151  * @return the name of the current color profile
152  */
153  QString colorProfile() const;
154 
155  /**
156  * @brief setColorProfile set the color profile of the image to the given profile. The profile has to
157  * be registered with krita and be compatible with the current color model and depth; the image data
158  * is <i>not</i> converted.
159  * @param colorProfile
160  * @return false if the colorProfile name does not correspond to to a registered profile or if assigning
161  * the profile failed.
162  */
163  bool setColorProfile(const QString &colorProfile);
164 
165  /**
166  * @brief setColorSpace convert the nodes and the image to the given colorspace. The conversion is
167  * done with Perceptual as intent, High Quality and No LCMS Optimizations as flags and no blackpoint
168  * compensation.
169  *
170  * @param colorModel A string describing the color model of the image:
171  * <ul>
172  * <li>A: Alpha mask</li>
173  * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
174  * <li>XYZA: XYZ with alpha channel</li>
175  * <li>LABA: LAB with alpha channel</li>
176  * <li>CMYKA: CMYK with alpha channel</li>
177  * <li>GRAYA: Gray with alpha channel</li>
178  * <li>YCbCrA: YCbCr with alpha channel</li>
179  * </ul>
180  * @param colorDepth A string describing the color depth of the image:
181  * <ul>
182  * <li>U8: unsigned 8 bits integer, the most common type</li>
183  * <li>U16: unsigned 16 bits integer</li>
184  * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
185  * <li>F32: 32 bits floating point</li>
186  * </ul>
187  * @param colorProfile a valid color profile for this color model and color depth combination.
188  * @return false the combination of these arguments does not correspond to a colorspace.
189  */
190  bool setColorSpace(const QString &colorModel, const QString &colorDepth, const QString &colorProfile);
191 
192  /**
193  * @brief backgroundColor returns the current background color of the document. The color will
194  * also include the opacity.
195  *
196  * @return QColor
197  */
198  QColor backgroundColor();
199 
200  /**
201  * @brief setBackgroundColor sets the background color of the document. It will trigger a projection
202  * update.
203  *
204  * @param color A QColor. The color will be converted from sRGB.
205  * @return bool
206  */
207  bool setBackgroundColor(const QColor &color);
208 
209  /**
210  * @brief documentInfo creates and XML document representing document and author information.
211  * @return a string containing a valid XML document with the right information about the document
212  * and author. The DTD can be found here:
213  *
214  * https://phabricator.kde.org/source/krita/browse/master/krita/dtd/
215  *
216  * @code
217  * <?xml version="1.0" encoding="UTF-8"?>
218  * <!DOCTYPE document-info PUBLIC '-//KDE//DTD document-info 1.1//EN' 'http://www.calligra.org/DTD/document-info-1.1.dtd'>
219  * <document-info xmlns="http://www.calligra.org/DTD/document-info">
220  * <about>
221  * <title>My Document</title>
222  * <description></description>
223  * <subject></subject>
224  * <abstract><![CDATA[]]></abstract>
225  * <keyword></keyword>
226  * <initial-creator>Unknown</initial-creator>
227  * <editing-cycles>1</editing-cycles>
228  * <editing-time>35</editing-time>
229  * <date>2017-02-27T20:15:09</date>
230  * <creation-date>2017-02-27T20:14:33</creation-date>
231  * <language></language>
232  * </about>
233  * <author>
234  * <full-name>Boudewijn Rempt</full-name>
235  * <initial></initial>
236  * <author-title></author-title>
237  * <email></email>
238  * <telephone></telephone>
239  * <telephone-work></telephone-work>
240  * <fax></fax>
241  * <country></country>
242  * <postal-code></postal-code>
243  * <city></city>
244  * <street></street>
245  * <position></position>
246  * <company></company>
247  * </author>
248  * </document-info>
249  * @endcode
250  *
251  */
252  QString documentInfo() const;
253 
254  /**
255  * @brief setDocumentInfo set the Document information to the information contained in document
256  * @param document A string containing a valid XML document that conforms to the document-info DTD
257  * that can be found here:
258  *
259  * https://phabricator.kde.org/source/krita/browse/master/krita/dtd/
260  */
261  void setDocumentInfo(const QString &document);
262 
263  /**
264  * @return the full path to the document, if it has been set.
265  */
266  QString fileName() const;
267 
268  /**
269  * @brief setFileName set the full path of the document to @param value
270  */
271  void setFileName(QString value);
272 
273  /**
274  * @return the height of the image in pixels
275  */
276  int height() const;
277 
278  /**
279  * @brief setHeight resize the document to @param value height. This is a canvas resize, not a scale.
280  */
281  void setHeight(int value);
282 
283  /**
284  * @return the name of the document. This is the title field in the @ref documentInfo
285  */
286  QString name() const;
287 
288  /**
289  * @brief setName sets the name of the document to @p value. This is the title field in the @ref documentInfo
290  */
291  void setName(QString value);
292 
293  /**
294  * @return the resolution in pixels per inch
295  */
296  int resolution() const;
297  /**
298  * @brief setResolution set the resolution of the image; this does not scale the image
299  * @param value the resolution in pixels per inch
300  */
301  void setResolution(int value);
302 
303  /**
304  * @brief rootNode the root node is the invisible group layer that contains the entire node
305  * hierarchy.
306  * @return the root of the image
307  */
308  Node* rootNode() const;
309 
310  /**
311  * @brief selection Create a Selection object around the global selection, if there is one.
312  * @return the global selection or None if there is no global selection.
313  */
314  Selection* selection() const;
315 
316  /**
317  * @brief setSelection set or replace the global selection
318  * @param value a valid selection object.
319  */
320  void setSelection(Selection* value);
321 
322  /**
323  * @return the width of the image in pixels.
324  */
325  int width() const;
326 
327  /**
328  * @brief setWidth resize the document to @param value width. This is a canvas resize, not a scale.
329  */
330  void setWidth(int value);
331 
332  /**
333  * @return the left edge of the canvas in pixels.
334  */
335  int xOffset() const;
336 
337  /**
338  * @brief setXOffset sets the left edge of the canvas to @p x.
339  */
340  void setXOffset(int x);
341 
342  /**
343  * @return the top edge of the canvas in pixels.
344  */
345  int yOffset() const;
346 
347  /**
348  * @brief setYOffset sets the top edge of the canvas to @p y.
349  */
350  void setYOffset(int y);
351 
352  /**
353  * @return xRes the horizontal resolution of the image in pixels
354  * per inch
355  */
356 
357  double xRes() const;
358 
359  /**
360  * @brief setXRes set the horizontal resolution of the image to
361  * xRes in pixels per inch
362  */
363  void setXRes(double xRes) const;
364 
365  /**
366  * @return yRes the vertical resolution of the image in pixels per
367  * inch
368  */
369  double yRes() const;
370 
371  /**
372  * @brief setYRes set the vertical resolution of the image to yRes
373  * in pixels per inch
374  */
375  void setYRes(double yRes) const;
376 
377  /**
378  * @brief pixelData reads the given rectangle from the image projection and returns it as a byte
379  * array. The pixel data starts top-left, and is ordered row-first.
380  *
381  * The byte array can be interpreted as follows: 8 bits images have one byte per channel,
382  * and as many bytes as there are channels. 16 bits integer images have two bytes per channel,
383  * representing an unsigned short. 16 bits float images have two bytes per channel, representing
384  * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a
385  * float.
386  *
387  * You can read outside the image boundaries; those pixels will be transparent black.
388  *
389  * The order of channels is:
390  *
391  * <ul>
392  * <li>Integer RGBA: Blue, Green, Red, Alpha
393  * <li>Float RGBA: Red, Green, Blue, Alpha
394  * <li>LabA: L, a, b, Alpha
395  * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha
396  * <li>XYZA: X, Y, Z, A
397  * <li>YCbCrA: Y, Cb, Cr, Alpha
398  * </ul>
399  *
400  * The byte array is a copy of the original image data. In Python, you can use bytes, bytearray
401  * and the struct module to interpret the data and construct, for instance, a Pillow Image object.
402  *
403  * @param x x position from where to start reading
404  * @param y y position from where to start reading
405  * @param w row length to read
406  * @param h number of rows to read
407  * @return a QByteArray with the pixel data. The byte array may be empty.
408  */
409  QByteArray pixelData(int x, int y, int w, int h) const;
410 
411  /**
412  * @brief close Close the document: remove it from Krita's internal list of documents and
413  * close all views. If the document is modified, you should save it first. There will be
414  * no prompt for saving.
415  *
416  * After closing the document it becomes invalid.
417  *
418  * @return true if the document is closed.
419  */
420  bool close();
421 
422  /**
423  * @brief crop the image to rectangle described by @p x, @p y,
424  * @p w and @p h
425  * @param x x coordinate of the top left corner
426  * @param y y coordinate of the top left corner
427  * @param w width
428  * @param h height
429  */
430  void crop(int x, int y, int w, int h);
431 
432  /**
433  * @brief exportImage export the image, without changing its URL to the given path.
434  * @param filename the full path to which the image is to be saved
435  * @param exportConfiguration a configuration object appropriate to the file format.
436  * An InfoObject will used to that configuration.
437  *
438  * The supported formats have specific configurations that must be used when in
439  * batchmode. They are described below:
440  *
441  *\b png
442  * <ul>
443  * <li>alpha: bool (True or False)
444  * <li>compression: int (1 to 9)
445  * <li>forceSRGB: bool (True or False)
446  * <li>indexed: bool (True or False)
447  * <li>interlaced: bool (True or False)
448  * <li>saveSRGBProfile: bool (True or False)
449  * <li>transparencyFillcolor: rgb (Ex:[255,255,255])
450  * </ul>
451  *
452  *\b jpeg
453  * <ul>
454  * <li>baseline: bool (True or False)
455  * <li>exif: bool (True or False)
456  * <li>filters: bool (['ToolInfo', 'Anonymizer'])
457  * <li>forceSRGB: bool (True or False)
458  * <li>iptc: bool (True or False)
459  * <li>is_sRGB: bool (True or False)
460  * <li>optimize: bool (True or False)
461  * <li>progressive: bool (True or False)
462  * <li>quality: int (0 to 100)
463  * <li>saveProfile: bool (True or False)
464  * <li>smoothing: int (0 to 100)
465  * <li>subsampling: int (0 to 3)
466  * <li>transparencyFillcolor: rgb (Ex:[255,255,255])
467  * <li>xmp: bool (True or False)
468  * </ul>
469  * @return true if the export succeeded, false if it failed.
470  */
471  bool exportImage(const QString &filename, const InfoObject &exportConfiguration);
472 
473  /**
474  * @brief flatten all layers in the image
475  */
476  void flatten();
477 
478  /**
479  * @brief resizeImage resizes the canvas to the given left edge, top edge, width and height.
480  * Note: This doesn't scale, use scale image for that.
481  * @param x the new left edge
482  * @param y the new top edge
483  * @param w the new width
484  * @param h the new height
485  */
486  void resizeImage(int x, int y, int w, int h);
487 
488  /**
489  * @brief scaleImage
490  * @param w the new width
491  * @param h the new height
492  * @param xres the new xres
493  * @param yres the new yres
494  * @param strategy the scaling strategy. There's several ones amongst these that aren't available in the regular UI.
495  * The list of filters is extensible and can be retrieved with Krita::filter
496  * <ul>
497  * <li>Hermite</li>
498  * <li>Bicubic - Adds pixels using the color of surrounding pixels. Produces smoother tonal gradations than Bilinear.</li>
499  * <li>Box - Replicate pixels in the image. Preserves all the original detail, but can produce jagged effects.</li>
500  * <li>Bilinear - Adds pixels averaging the color values of surrounding pixels. Produces medium quality results when the image is scaled from half to two times the original size.</li>
501  * <li>Bell</li>
502  * <li>BSpline</li>
503  * <li>Kanczos3 - Offers similar results than Bicubic, but maybe a little bit sharper. Can produce light and dark halos along strong edges.</li>
504  * <li>Mitchell</li>
505  * </ul>
506  */
507  void scaleImage(int w, int h, int xres, int yres, QString strategy);
508 
509  /**
510  * @brief rotateImage
511  * Rotate the image by the given radians.
512  * @param radians the amount you wish to rotate the image in radians
513  */
514  void rotateImage(double radians);
515 
516  /**
517  * @brief shearImage shear the whole image.
518  * @param angleX the X-angle in degrees to shear by
519  * @param angleY the Y-angle in degrees to shear by
520  */
521  void shearImage(double angleX, double angleY);
522 
523  /**
524  * @brief save the image to its currently set path. The modified flag of the
525  * document will be reset
526  * @return true if saving succeeded, false otherwise.
527  */
528  bool save();
529 
530  /**
531  * @brief saveAs save the document under the @p filename. The document's
532  * filename will be reset to @p filename.
533  * @param filename the new filename (full path) for the document
534  * @return true if saving succeeded, false otherwise.
535  */
536  bool saveAs(const QString &filename);
537 
538  /**
539  * @brief createNode create a new node of the given type. The node is not added
540  * to the node hierarchy; you need to do that by finding the right parent node,
541  * getting its list of child nodes and adding the node in the right place, then
542  * calling Node::SetChildNodes
543  *
544  * @param name The name of the node
545  *
546  * @param nodeType The type of the node. Valid types are:
547  * <ul>
548  * <li>paintlayer
549  * <li>grouplayer
550  * <li>filelayer
551  * <li>filterlayer
552  * <li>filllayer
553  * <li>clonelayer
554  * <li>vectorlayer
555  * <li>transparencymask
556  * <li>filtermask
557  * <li>transformmask
558  * <li>selectionmask
559  * </ul>
560  *
561  * When relevant, the new Node will have the colorspace of the image by default;
562  * that can be changed with Node::setColorSpace.
563  *
564  * The settings and selections for relevant layer and mask types can also be set
565  * after the Node has been created.
566  *
567 @code
568 d = Application.createDocument(1000, 1000, "Test", "RGBA", "U8", "", 120.0)
569 root = d.rootNode();
570 print(root.childNodes())
571 l2 = d.createNode("layer2", "paintLayer")
572 print(l2)
573 root.addChildNode(l2, None)
574 print(root.childNodes())
575 @endcode
576  *
577  *
578  * @return the new Node.
579  */
580  Node* createNode(const QString &name, const QString &nodeType);
581  /**
582  * @brief createGroupLayer
583  * Returns a grouplayer object. Grouplayers are nodes that can have
584  * other layers as children and have the passthrough mode.
585  * @param name the name of the layer.
586  * @return a GroupLayer object.
587  */
588  GroupLayer* createGroupLayer(const QString &name);
589  /**
590  * @brief createFileLayer returns a layer that shows an external image.
591  * @param name name of the file layer.
592  * @param fileName the absolute filename of the file referenced. Symlinks will be resolved.
593  * @param scalingMethod how the dimensions of the file are interpreted
594  * can be either "None", "ImageToSize" or "ImageToPPI"
595  * @param scalingFilter filter used to scale the file
596  * can be "Bicubic", "Hermite", "NearestNeighbor", "Bilinear", "Bell", "BSpline", "Lanczos3", "Mitchell"
597  * @return a FileLayer
598  */
599  FileLayer* createFileLayer(const QString &name, const QString fileName, const QString scalingMethod, const QString scalingFilter = "Bicubic");
600 
601  /**
602  * @brief createFilterLayer creates a filter layer, which is a layer that represents a filter
603  * applied non-destructively.
604  * @param name name of the filterLayer
605  * @param filter the filter that this filter layer will us.
606  * @param selection the selection.
607  * @return a filter layer object.
608  */
609  FilterLayer* createFilterLayer(const QString &name, Filter &filter, Selection &selection);
610 
611  /**
612  * @brief createFillLayer creates a fill layer object, which is a layer
613  * @param name
614  * @param generatorName - name of the generation filter.
615  * @param configuration - the configuration for the generation filter.
616  * @param selection - the selection.
617  * @return a filllayer object.
618  *
619  * @code
620  * from krita import *
621  * d = Krita.instance().activeDocument()
622  * i = InfoObject();
623  * i.setProperty("pattern", "Cross01.pat")
624  * s = Selection();
625  * s.select(0, 0, d.width(), d.height(), 255)
626  * n = d.createFillLayer("test", "pattern", i, s)
627  * r = d.rootNode();
628  * c = r.childNodes();
629  * r.addChildNode(n, c[0])
630  * d.refreshProjection()
631  * @endcode
632  */
633  FillLayer* createFillLayer(const QString &name, const QString generatorName, InfoObject &configuration, Selection &selection);
634 
635  /**
636  * @brief createCloneLayer
637  * @param name
638  * @param source
639  * @return
640  */
641  CloneLayer* createCloneLayer(const QString &name, const Node* source);
642 
643  /**
644  * @brief createVectorLayer
645  * Creates a vector layer that can contain vector shapes.
646  * @param name the name of this layer.
647  * @return a VectorLayer.
648  */
649  VectorLayer* createVectorLayer(const QString &name);
650 
651  /**
652  * @brief createFilterMask
653  * Creates a filter mask object that much like a filterlayer can apply a filter non-destructively.
654  * @param name the name of the layer.
655  * @param filter the filter assigned.
656  * @param selection the selection to be used by the filter mask
657  * @return a FilterMask
658  */
659  FilterMask* createFilterMask(const QString &name, Filter &filter, Selection &selection);
660 
661  /**
662  * @brief createFilterMask
663  * Creates a filter mask object that much like a filterlayer can apply a filter non-destructively.
664  * @param name the name of the layer.
665  * @param filter the filter assigned.
666  * @param selection_source a node from which the selection should be initialized
667  * @return a FilterMask
668  */
669  FilterMask* createFilterMask(const QString &name, Filter &filter, const Node* selection_source);
670 
671  /**
672  * @brief createSelectionMask
673  * Creates a selection mask, which can be used to store selections.
674  * @param name - the name of the layer.
675  * @return a SelectionMask
676  */
677  SelectionMask* createSelectionMask(const QString &name);
678 
679  /**
680  * @brief createTransparencyMask
681  * Creates a transparency mask, which can be used to assign transparency to regions.
682  * @param name - the name of the layer.
683  * @return a TransparencyMask
684  */
685  TransparencyMask* createTransparencyMask(const QString &name);
686 
687  /**
688  * @brief createTransformMask
689  * Creates a transform mask, which can be used to apply a transformation non-destructively.
690  * @param name - the name of the layer mask.
691  * @return a TransformMask
692  */
693  TransformMask* createTransformMask(const QString &name);
694 
695  /**
696  * @brief createColorizeMask
697  * Creates a colorize mask, which can be used to color fill via keystrokes.
698  * @param name - the name of the layer.
699  * @return a TransparencyMask
700  */
701  ColorizeMask* createColorizeMask(const QString &name);
702 
703  /**
704  * @brief projection creates a QImage from the rendered image or
705  * a cutout rectangle.
706  */
707  QImage projection(int x = 0, int y = 0, int w = 0, int h = 0) const;
708 
709  /**
710  * @brief thumbnail create a thumbnail of the given dimensions.
711  *
712  * If the requested size is too big a null QImage is created.
713  *
714  * @return a QImage representing the layer contents.
715  */
716  QImage thumbnail(int w, int h) const;
717 
718 
719  /**
720  * [low-level] Lock the image without waiting for all the internal job queues are processed
721  *
722  * WARNING: Don't use it unless you really know what you are doing! Use barrierLock() instead!
723  *
724  * Waits for all the **currently running** internal jobs to complete and locks the image
725  * for writing. Please note that this function does **not** wait for all the internal
726  * queues to process, so there might be some non-finished actions pending. It means that
727  * you just postpone these actions until you unlock() the image back. Until then, then image
728  * might easily be frozen in some inconsistent state.
729  *
730  * The only sane usage for this function is to lock the image for **emergency**
731  * processing, when some internal action or scheduler got hung up, and you just want
732  * to fetch some data from the image without races.
733  *
734  * In all other cases, please use barrierLock() instead!
735  */
736  void lock();
737 
738  /**
739  * Unlocks the image and starts/resumes all the pending internal jobs. If the image
740  * has been locked for a non-readOnly access, then all the internal caches of the image
741  * (e.g. lod-planes) are reset and regeneration jobs are scheduled.
742  */
743  void unlock();
744 
745  /**
746  * Wait for all the internal image jobs to complete and return without locking
747  * the image. This function is handly for tests or other synchronous actions,
748  * when one needs to wait for the result of his actions.
749  */
750  void waitForDone();
751 
752  /**
753  * @brief Tries to lock the image without waiting for the jobs to finish
754  *
755  * Same as barrierLock(), but doesn't block execution of the calling thread
756  * until all the background jobs are finished. Instead, in case of presence of
757  * unfinished jobs in the queue, it just returns false
758  *
759  * @return whether the lock has been acquired
760  */
761  bool tryBarrierLock();
762 
763  /**
764  * Starts a synchronous recomposition of the projection: everything will
765  * wait until the image is fully recomputed.
766  */
767  void refreshProjection();
768 
769  /**
770  * @brief setHorizontalGuides
771  * replace all existing horizontal guides with the entries in the list.
772  * @param lines a list of floats containing the new guides.
773  */
774  void setHorizontalGuides(const QList<qreal> &lines);
775  /**
776  * @brief setVerticalGuides
777  * replace all existing horizontal guides with the entries in the list.
778  * @param lines a list of floats containing the new guides.
779  */
780  void setVerticalGuides(const QList<qreal> &lines);
781 
782  /**
783  * @brief setGuidesVisible
784  * set guides visible on this document.
785  * @param visible whether or not the guides are visible.
786  */
787  void setGuidesVisible(bool visible);
788 
789  /**
790  * @brief setGuidesLocked
791  * set guides locked on this document
792  * @param locked whether or not to lock the guides on this document.
793  */
794  void setGuidesLocked(bool locked);
795 
796  /**
797  * @brief modified returns true if the document has unsaved modifications.
798  */
799  bool modified() const;
800 
801  /**
802  * @brief setModified sets the modified status of the document
803  * @param modified if true, the document is considered modified and closing it will ask for saving.
804  */
805  void setModified(bool modified);
806 
807  /**
808  * @brief bounds return the bounds of the image
809  * @return the bounds
810  */
811  QRect bounds() const;
812 
813  /****
814  * Animation Related API
815  *****/
816 
817 
818  /**
819  * @brief Import an image sequence of files from a directory. This will grab all
820  * images from the directory and import them with a potential offset (firstFrame)
821  * and step (images on 2s, 3s, etc)
822  * @returns whether the animation import was successful
823  */
824  bool importAnimation(const QList<QString> &files, int firstFrame, int step);
825 
826  /**
827  * @brief frames per second of document
828  * @return the fps of the document
829  */
830  int framesPerSecond();
831 
832  /**
833  * @brief set frames per second of document
834  */
835  void setFramesPerSecond(int fps);
836 
837  /**
838  * @brief set start time of animation
839  */
840  void setFullClipRangeStartTime(int startTime);
841 
842  /**
843  * @brief get the full clip range start time
844  * @return full clip range start time
845  */
846  int fullClipRangeStartTime();
847 
848 
849  /**
850  * @brief set full clip range end time
851  */
852  void setFullClipRangeEndTime(int endTime);
853 
854  /**
855  * @brief get the full clip range end time
856  * @return full clip range end time
857  */
858  int fullClipRangeEndTime();
859 
860  /**
861  * @brief get total frame range for animation
862  * @return total frame range for animation
863  */
864  int animationLength();
865 
866  /**
867  * @brief set temporary playback range of document
868  */
869  void setPlayBackRange(int start, int stop);
870 
871  /**
872  * @brief get start time of current playback
873  * @return start time of current playback
874  */
875  int playBackStartTime();
876 
877  /**
878  * @brief get end time of current playback
879  * @return end time of current playback
880  */
881  int playBackEndTime();
882 
883  /**
884  * @brief get current frame selected of animation
885  * @return current frame selected of animation
886  */
887  int currentTime();
888 
889  /**
890  * @brief set current time of document's animation
891  */
892  void setCurrentTime(int time);
893 
894  /**
895  * @brief annotationTypes returns the list of annotations present in the document.
896  * Each annotation type is unique.
897  */
898  QStringList annotationTypes() const;
899 
900  /**
901  * @brief annotationDescription gets the pretty description for the current annotation
902  * @param type the type of the annotation
903  * @return a string that can be presented to the user
904  */
905  QString annotationDescription(const QString &type) const;
906 
907  /**
908  * @brief annotation the actual data for the annotation for this type. It's a simple
909  * QByteArray, what's in it depends on the type of the annotation
910  * @param type the type of the annotation
911  * @return a bytearray, possibly empty if this type of annotation doesn't exist
912  */
913  QByteArray annotation(const QString &type);
914 
915  /**
916  * @brief setAnnotation Add the given annotation to the document
917  * @param type the unique type of the annotation
918  * @param description the user-visible description of the annotation
919  * @param annotation the annotation itself
920  */
921  void setAnnotation(const QString &type, const QString &description, const QByteArray &annotation);
922 
923  /**
924  * @brief removeAnnotation remove the specified annotation from the image
925  * @param type the type defining the annotation
926  */
927  void removeAnnotation(const QString &type);
928 private:
929 
930  friend class Krita;
931  friend class Window;
932  friend class Filter;
933  friend class View;
934  friend class VectorLayer;
935  friend class Shape;
936  QPointer<KisDocument> document() const;
937  void setOwnsDocument(bool ownsDocument);
938 
939 private:
940  struct Private;
941  Private *const d;
942 
943 };
944 
945 #endif // LIBKIS_DOCUMENT_H
InfoObject wrap a properties map.
Definition: InfoObject.h:19
Q_SLOTSQ_SLOTS
void stop(Ekos::AlignState mode)
Window represents one Krita mainwindow.
Definition: Window.h:22
Q_SCRIPTABLE Q_NOREPLY void start()
The ColorizeMask class A colorize mask is a mask type node that can be used to color in line art.
Definition: ColorizeMask.h:59
The GroupLayer class A group layer is a layer that can contain other layers.
Definition: GroupLayer.h:29
The Document class encapsulates a Krita Document/Image.
Definition: Document.h:33
View represents one view on a document.
Definition: View.h:24
The Shape class The shape class is a wrapper around Krita's vector objects.
Definition: Shape.h:37
Selection represents a selection on Krita.
Definition: Selection.h:30
The TransformMask class A transform mask is a mask type node that can be used to store transformation...
Definition: TransformMask.h:22
The SelectionMask class A selection mask is a mask type node that can be used to store selections.
Definition: SelectionMask.h:26
The CloneLayer class A clone layer is a layer that takes a reference inside the image and shows the e...
Definition: CloneLayer.h:25
Filter: represents a filter and its configuration.
Definition: Filter.h:30
Krita is a singleton class that offers the root access to the Krita object hierarchy.
Definition: Krita.h:27
The TransparencyMask class A transparency mask is a mask type node that can be used to show and hide ...
The FillLayer class A fill layer is much like a filter layer in that it takes a name and filter.
Definition: FillLayer.h:24
The FileLayer class A file layer is a layer that can reference an external image and show said refere...
Definition: FileLayer.h:26
Node represents a layer or mask in a Krita image's Node hierarchy.
Definition: Node.h:21
The VectorLayer class A vector layer is a special layer that stores and shows vector shapes.
Definition: VectorLayer.h:31
The FilterMask class A filter mask, unlike a filter layer, will add a non-destructive filter to the c...
Definition: FilterMask.h:28
Q_DISABLE_COPY(Class)
The FilterLayer class A filter layer will, when compositing, take the composited image up to the poin...
Definition: FilterLayer.h:33
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 04:08:41 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.