Krita

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

KDE's Doxygen guidelines are available online.