Document.h

/*
 *  SPDX-FileCopyrightText: 2016 Boudewijn Rempt <boud@valdyas.org>
 *
 *  SPDX-License-Identifier: LGPL-2.0-or-later
 */
#ifndef LIBKIS_DOCUMENT_H
#define LIBKIS_DOCUMENT_H
 
#include <QFileInfo>
 
#include "kritalibkis_export.h"
#include "libkis.h"
 
#include "GroupLayer.h"
#include "CloneLayer.h"
#include "FileLayer.h"
#include "FilterLayer.h"
#include "FillLayer.h"
#include "VectorLayer.h"
#include "FilterMask.h"
#include "SelectionMask.h"
#include "TransparencyMask.h"
#include "TransformMask.h"
#include "ColorizeMask.h"
 
#include "GuidesConfig.h"
#include "GridConfig.h"
 
class KisDocument;
 
/**
 * The Document class encapsulates a Krita Document/Image. A Krita document is an Image with
 * a filename. Libkis does not differentiate between a document and an image, like Krita does
 * internally.
 */
class KRITALIBKIS_EXPORT Document : public QObject
{
    Q_OBJECT
    Q_DISABLE_COPY(Document)
 
public:
    explicit Document(KisDocument *document, bool ownsDocument, QObject *parent = 0);
    ~Document() override;
 
    bool operator==(const Document &other) const;
    bool operator!=(const Document &other) const;
 
public Q_SLOTS:
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * The horizontal guides.
     * @return a list of the horizontal positions of guides.
     */
    Q_DECL_DEPRECATED QList<qreal> horizontalGuides() const;
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * The vertical guide lines.
     * @return a list of vertical guides.
     */
    Q_DECL_DEPRECATED QList<qreal> verticalGuides() const;
 
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * Returns guide visibility.
     * @return whether the guides are visible.
     */
    Q_DECL_DEPRECATED bool guidesVisible() const;
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * Returns guide lockedness.
     * @return whether the guides are locked.
     */
    Q_DECL_DEPRECATED bool guidesLocked() const;
 
    /**
     * @brief clone create a shallow clone of this document.
     * @return a new Document that should be identical to this one in every respect.
     */
    Document *clone() const;
 
    /**
     * Batchmode means that no actions on the document should show dialogs or popups.
     * @return true if the document is in batchmode.
     */
    bool batchmode() const;
 
    /**
     * Set batchmode to @p value. If batchmode is true, then there should be no popups
     * or dialogs shown to the user.
     */
    void setBatchmode(bool value);
 
    /**
     * @brief activeNode retrieve the node that is currently active in the currently active window
     * @return the active node. If there is no active window, the first child node is returned.
     */
    Node* activeNode() const;
 
    /**
     * @brief setActiveNode make the given node active in the currently active view and window
     * @param value the node to make active.
     */
    void setActiveNode(Node* value);
 
    /**
     * @brief toplevelNodes return a list with all top level nodes in the image graph
     */
    QList<Node*> topLevelNodes() const;
 
    /**
     * @brief nodeByName searches the node tree for a node with the given name and returns it
     * @param name the name of the node
     * @return the first node with the given name or 0 if no node is found
     */
    Node *nodeByName(const QString &name) const;
 
    /**
     * @brief nodeByUniqueID searches the node tree for a node with the given name and returns it.
     * @param uuid the unique id of the node
     * @return the node with the given unique id, or 0 if no node is found.
     */
    Node *nodeByUniqueID(const QUuid &id) const;
 
    /**
     * colorDepth A string describing the color depth of the image:
     * <ul>
     * <li>U8: unsigned 8 bits integer, the most common type</li>
     * <li>U16: unsigned 16 bits integer</li>
     * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
     * <li>F32: 32 bits floating point</li>
     * </ul>
     * @return the color depth.
     */
    QString colorDepth() const;
 
    /**
     * @brief colorModel retrieve the current color model of this document:
     * <ul>
     * <li>A: Alpha mask</li>
     * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
     * <li>XYZA: XYZ with alpha channel</li>
     * <li>LABA: LAB with alpha channel</li>
     * <li>CMYKA: CMYK with alpha channel</li>
     * <li>GRAYA: Gray with alpha channel</li>
     * <li>YCbCrA: YCbCr with alpha channel</li>
     * </ul>
     * @return the internal color model string.
     */
    QString colorModel() const;
 
    /**
     * @return the name of the current color profile
     */
    QString colorProfile() const;
 
    /**
     * @brief setColorProfile set the color profile of the image to the given profile. The profile has to
     * be registered with krita and be compatible with the current color model and depth; the image data
     * is <i>not</i> converted.
     * @param colorProfile
     * @return false if the colorProfile name does not correspond to to a registered profile or if assigning
     * the profile failed.
     */
    bool setColorProfile(const QString &colorProfile);
 
    /**
     * @brief setColorSpace convert the nodes and the image to the given colorspace. The conversion is
     * done with Perceptual as intent, High Quality and No LCMS Optimizations as flags and no blackpoint
     * compensation.
     *
     * @param colorModel A string describing the color model of the image:
     * <ul>
     * <li>A: Alpha mask</li>
     * <li>RGBA: RGB with alpha channel (The actual order of channels is most often BGR!)</li>
     * <li>XYZA: XYZ with alpha channel</li>
     * <li>LABA: LAB with alpha channel</li>
     * <li>CMYKA: CMYK with alpha channel</li>
     * <li>GRAYA: Gray with alpha channel</li>
     * <li>YCbCrA: YCbCr with alpha channel</li>
     * </ul>
     * @param colorDepth A string describing the color depth of the image:
     * <ul>
     * <li>U8: unsigned 8 bits integer, the most common type</li>
     * <li>U16: unsigned 16 bits integer</li>
     * <li>F16: half, 16 bits floating point. Only available if Krita was built with OpenEXR</li>
     * <li>F32: 32 bits floating point</li>
     * </ul>
     * @param colorProfile a valid color profile for this color model and color depth combination.
     * @return false the combination of these arguments does not correspond to a colorspace.
     */
    bool setColorSpace(const QString &colorModel, const QString &colorDepth, const QString &colorProfile);
 
    /**
     * @brief backgroundColor returns the current background color of the document. The color will
     * also include the opacity.
     *
     * @return QColor
     */
    QColor backgroundColor();
 
    /**
     * @brief setBackgroundColor sets the background color of the document. It will trigger a projection
     * update.
     *
     * @param color A QColor. The color will be converted from sRGB.
     * @return bool
     */
    bool setBackgroundColor(const QColor &color);
 
    /**
     * @brief documentInfo creates and XML document representing document and author information.
     * @return a string containing a valid XML document with the right information about the document
     * and author. The DTD can be found here:
     *
     * https://phabricator.kde.org/source/krita/browse/master/krita/dtd/
     *
     * @code
     * <?xml version="1.0" encoding="UTF-8"?>
     * <!DOCTYPE document-info PUBLIC '-//KDE//DTD document-info 1.1//EN' 'http://www.calligra.org/DTD/document-info-1.1.dtd'>
     * <document-info xmlns="http://www.calligra.org/DTD/document-info">
     * <about>
     *  <title>My Document</title>
     *   <description></description>
     *   <subject></subject>
     *   <abstract><![CDATA[]]></abstract>
     *   <keyword></keyword>
     *   <initial-creator>Unknown</initial-creator>
     *   <editing-cycles>1</editing-cycles>
     *   <editing-time>35</editing-time>
     *   <date>2017-02-27T20:15:09</date>
     *   <creation-date>2017-02-27T20:14:33</creation-date>
     *   <language></language>
     *  </about>
     *  <author>
     *   <full-name>Boudewijn Rempt</full-name>
     *   <initial></initial>
     *   <author-title></author-title>
     *   <email></email>
     *   <telephone></telephone>
     *   <telephone-work></telephone-work>
     *   <fax></fax>
     *   <country></country>
     *   <postal-code></postal-code>
     *   <city></city>
     *   <street></street>
     *   <position></position>
     *   <company></company>
     *  </author>
     * </document-info>
     * @endcode
     *
     */
    QString documentInfo() const;
 
    /**
     * @brief setDocumentInfo set the Document information to the information contained in document
     * @param document A string containing a valid XML document that conforms to the document-info DTD
     * that can be found here:
     *
     * https://phabricator.kde.org/source/krita/browse/master/krita/dtd/
     */
    void setDocumentInfo(const QString &document);
 
    /**
     * @return the full path to the document, if it has been set.
     */
    QString fileName() const;
 
    /**
     * @brief setFileName set the full path of the document to @param value
     */
    void setFileName(QString value);
 
    /**
     * @return the height of the image in pixels
     */
    int height() const;
 
    /**
     * @brief setHeight resize the document to @param value height. This is a canvas resize, not a scale.
     */
    void setHeight(int value);
 
    /**
     * @return the name of the document. This is the title field in the @ref documentInfo
     */
    QString name() const;
 
    /**
     * @brief setName sets the name of the document to @p value. This is the title field in the @ref documentInfo
     */
    void setName(QString value);
 
    /**
     * @return the resolution in pixels per inch
     */
    int resolution() const;
    /**
     * @brief setResolution set the resolution of the image; this does not scale the image
     * @param value the resolution in pixels per inch
     */
    void setResolution(int value);
 
    /**
     * @brief rootNode the root node is the invisible group layer that contains the entire node
     * hierarchy.
     * @return the root of the image
     */
    Node* rootNode() const;
 
    /**
     * @brief selection Create a Selection object around the global selection, if there is one.
     * @return the global selection or None if there is no global selection.
     */
    Selection* selection() const;
 
    /**
     * @brief setSelection set or replace the global selection
     * @param value a valid selection object.
     */
    void setSelection(Selection* value);
 
    /**
     * @return the width of the image in pixels.
     */
    int width() const;
 
    /**
     * @brief setWidth resize the document to @param value width. This is a canvas resize, not a scale.
     */
    void setWidth(int value);
 
    /**
     * @return the left edge of the canvas in pixels.
     */
    int xOffset() const;
 
    /**
     * @brief setXOffset sets the left edge of the canvas to @p x.
     */
    void setXOffset(int x);
 
    /**
     * @return the top edge of the canvas in pixels.
     */
    int yOffset() const;
 
    /**
     * @brief setYOffset sets the top edge of the canvas to @p y.
     */
    void setYOffset(int y);
 
    /**
     * @return xRes the horizontal resolution of the image in pixels
     * per inch
     */
 
    double xRes() const;
 
    /**
     * @brief setXRes set the horizontal resolution of the image to
     * xRes in pixels per inch
     */
    void setXRes(double xRes) const;
 
    /**
     * @return yRes the vertical resolution of the image in pixels per
     * inch
     */
    double yRes() const;
 
    /**
     * @brief setYRes set the vertical resolution of the image to yRes
     * in pixels per inch
     */
    void setYRes(double yRes) const;
 
    /**
     * @brief pixelData reads the given rectangle from the image projection and returns it as a byte
     * array. The pixel data starts top-left, and is ordered row-first.
     *
     * The byte array can be interpreted as follows: 8 bits images have one byte per channel,
     * and as many bytes as there are channels. 16 bits integer images have two bytes per channel,
     * representing an unsigned short. 16 bits float images have two bytes per channel, representing
     * a half, or 16 bits float. 32 bits float images have four bytes per channel, representing a
     * float.
     *
     * You can read outside the image boundaries; those pixels will be transparent black.
     *
     * The order of channels is:
     *
     * <ul>
     * <li>Integer RGBA: Blue, Green, Red, Alpha
     * <li>Float RGBA: Red, Green, Blue, Alpha
     * <li>LabA: L, a, b, Alpha
     * <li>CMYKA: Cyan, Magenta, Yellow, Key, Alpha
     * <li>XYZA: X, Y, Z, A
     * <li>YCbCrA: Y, Cb, Cr, Alpha
     * </ul>
     *
     * The byte array is a copy of the original image data. In Python, you can use bytes, bytearray
     * and the struct module to interpret the data and construct, for instance, a Pillow Image object.
     *
     * @param x x position from where to start reading
     * @param y y position from where to start reading
     * @param w row length to read
     * @param h number of rows to read
     * @return a QByteArray with the pixel data. The byte array may be empty.
     */
    QByteArray pixelData(int x, int y, int w, int h) const;
 
    /**
     * @brief close Close the document: remove it from Krita's internal list of documents and
     * close all views. If the document is modified, you should save it first. There will be
     * no prompt for saving.
     *
     * After closing the document it becomes invalid.
     *
     * @return true if the document is closed.
     */
    bool close();
 
    /**
     * @brief crop the image to rectangle described by @p x, @p y,
     * @p w and @p h
     * @param x x coordinate of the top left corner
     * @param y y coordinate of the top left corner
     * @param w width
     * @param h height
     */
    void crop(int x, int y, int w, int h);
 
    /**
     * @brief exportImage export the image, without changing its URL to the given path.
     * @param filename the full path to which the image is to be saved
     * @param exportConfiguration a configuration object appropriate to the file format.
     * An InfoObject will used to that configuration.
     *
     * The supported formats have specific configurations that must be used when in
     * batchmode. They are described below:
     *
     *\b png
     * <ul>
     * <li>alpha: bool (True or False)
     * <li>compression: int (1 to 9)
     * <li>forceSRGB: bool (True or False)
     * <li>indexed: bool (True or False)
     * <li>interlaced: bool (True or False)
     * <li>saveSRGBProfile: bool (True or False)
     * <li>transparencyFillcolor: rgb (Ex:[255,255,255])
     * </ul>
     *
     *\b jpeg
     * <ul>
     * <li>baseline: bool (True or False)
     * <li>exif: bool (True or False)
     * <li>filters: bool (['ToolInfo', 'Anonymizer'])
     * <li>forceSRGB: bool (True or False)
     * <li>iptc: bool (True or False)
     * <li>is_sRGB: bool (True or False)
     * <li>optimize: bool (True or False)
     * <li>progressive: bool (True or False)
     * <li>quality: int (0 to 100)
     * <li>saveProfile: bool (True or False)
     * <li>smoothing: int (0 to 100)
     * <li>subsampling: int (0 to 3)
     * <li>transparencyFillcolor: rgb (Ex:[255,255,255])
     * <li>xmp: bool (True or False)
     * </ul>
     * @return true if the export succeeded, false if it failed.
     */
    bool exportImage(const QString &filename, const InfoObject &exportConfiguration);
 
    /**
     * @brief flatten all layers in the image
     */
    void flatten();
 
    /**
     * @brief resizeImage resizes the canvas to the given left edge, top edge, width and height.
     * Note: This doesn't scale, use scale image for that.
     * @param x the new left edge
     * @param y the new top edge
     * @param w the new width
     * @param h the new height
     */
    void resizeImage(int x, int y, int w, int h);
 
    /**
    * @brief scaleImage
    * @param w the new width
    * @param h the new height
    * @param xres the new xres
    * @param yres the new yres
    * @param strategy the scaling strategy. There's several ones amongst these that aren't available in the regular UI.
    * The list of filters is extensible and can be retrieved with Krita::filter
    * <ul>
    * <li>Hermite</li>
    * <li>Bicubic - Adds pixels using the color of surrounding pixels. Produces smoother tonal gradations than Bilinear.</li>
    * <li>Box - Replicate pixels in the image. Preserves all the original detail, but can produce jagged effects.</li>
    * <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>
    * <li>Bell</li>
    * <li>BSpline</li>
    * <li>Kanczos3 - Offers similar results than Bicubic, but maybe a little bit sharper. Can produce light and dark halos along strong edges.</li>
    * <li>Mitchell</li>
    * </ul>
    */
   void scaleImage(int w, int h, int xres, int yres, QString strategy);
 
   /**
    * @brief rotateImage
    * Rotate the image by the given radians.
    * @param radians the amount you wish to rotate the image in radians
    */
   void rotateImage(double radians);
 
   /**
    * @brief shearImage shear the whole image.
    * @param angleX the X-angle in degrees to shear by
    * @param angleY the Y-angle in degrees to shear by
    */
   void shearImage(double angleX, double angleY);
 
    /**
     * @brief save the image to its currently set path. The modified flag of the
     * document will be reset
     * @return true if saving succeeded, false otherwise.
     */
    bool save();
 
    /**
     * @brief saveAs save the document under the @p filename. The document's
     * filename will be reset to @p filename.
     * @param filename the new filename (full path) for the document
     * @return true if saving succeeded, false otherwise.
     */
    bool saveAs(const QString &filename);
 
    /**
     * @brief createNode create a new node of the given type. The node is not added
     * to the node hierarchy; you need to do that by finding the right parent node,
     * getting its list of child nodes and adding the node in the right place, then
     * calling Node::SetChildNodes
     *
     * @param name The name of the node
     *
     * @param nodeType The type of the node. Valid types are:
     * <ul>
     *  <li>paintlayer
     *  <li>grouplayer
     *  <li>filelayer
     *  <li>filterlayer
     *  <li>filllayer
     *  <li>clonelayer
     *  <li>vectorlayer
     *  <li>transparencymask
     *  <li>filtermask
     *  <li>transformmask
     *  <li>selectionmask
     * </ul>
     *
     * When relevant, the new Node will have the colorspace of the image by default;
     * that can be changed with Node::setColorSpace.
     *
     * The settings and selections for relevant layer and mask types can also be set
     * after the Node has been created.
     *
@code
d = Application.createDocument(1000, 1000, "Test", "RGBA", "U8", "", 120.0)
root = d.rootNode();
print(root.childNodes())
l2 = d.createNode("layer2", "paintLayer")
print(l2)
root.addChildNode(l2, None)
print(root.childNodes())
@endcode
     *
     *
     * @return the new Node.
     */
    Node* createNode(const QString &name, const QString &nodeType);
    /**
     * @brief createGroupLayer
     * Returns a grouplayer object. Grouplayers are nodes that can have
     * other layers as children and have the passthrough mode.
     * @param name the name of the layer.
     * @return a GroupLayer object.
     */
    GroupLayer* createGroupLayer(const QString &name);
    /**
     * @brief createFileLayer returns a layer that shows an external image.
     * @param name name of the file layer.
     * @param fileName the absolute filename of the file referenced. Symlinks will be resolved.
     * @param scalingMethod how the dimensions of the file are interpreted
     *        can be either "None", "ImageToSize" or "ImageToPPI"
     * @param scalingFilter filter used to scale the file
     *        can be "Bicubic", "Hermite", "NearestNeighbor", "Bilinear", "Bell", "BSpline", "Lanczos3", "Mitchell"
     * @return a FileLayer
     */
    FileLayer* createFileLayer(const QString &name, const QString fileName, const QString scalingMethod, const QString scalingFilter = "Bicubic");
 
    /**
     * @brief createFilterLayer creates a filter layer, which is a layer that represents a filter
     * applied non-destructively.
     * @param name name of the filterLayer
     * @param filter the filter that this filter layer will us.
     * @param selection the selection.
     * @return a filter layer object.
     */
    FilterLayer* createFilterLayer(const QString &name, Filter &filter, Selection &selection);
 
    /**
     * @brief createFillLayer creates a fill layer object, which is a layer
     * @param name
     * @param generatorName - name of the generation filter.
     * @param configuration - the configuration for the generation filter.
     * @param selection - the selection.
     * @return a filllayer object.
     *
     * @code
     * from krita import *
     * d = Krita.instance().activeDocument()
     * i = InfoObject();
     * i.setProperty("pattern", "Cross01.pat")
     * s = Selection();
     * s.select(0, 0, d.width(), d.height(), 255)
     * n = d.createFillLayer("test", "pattern", i, s)
     * r = d.rootNode();
     * c = r.childNodes();
     * r.addChildNode(n, c[0])
     * d.refreshProjection()
     * @endcode
     */
    FillLayer* createFillLayer(const QString &name, const QString generatorName, InfoObject &configuration, Selection &selection);
 
    /**
     * @brief createCloneLayer
     * @param name
     * @param source
     * @return
     */
    CloneLayer* createCloneLayer(const QString &name, const Node* source);
 
    /**
     * @brief createVectorLayer
     * Creates a vector layer that can contain vector shapes.
     * @param name the name of this layer.
     * @return a VectorLayer.
     */
    VectorLayer* createVectorLayer(const QString &name);
 
    /**
     * @brief createFilterMask
     * Creates a filter mask object that much like a filterlayer can apply a filter non-destructively.
     * @param name the name of the layer.
     * @param filter the filter assigned.
     * @param selection the selection to be used by the filter mask
     * @return a FilterMask
     */
    FilterMask* createFilterMask(const QString &name, Filter &filter, Selection &selection);
 
    /**
     * @brief createFilterMask
     * Creates a filter mask object that much like a filterlayer can apply a filter non-destructively.
     * @param name the name of the layer.
     * @param filter the filter assigned.
     * @param selection_source a node from which the selection should be initialized
     * @return a FilterMask
     */
    FilterMask* createFilterMask(const QString &name, Filter &filter, const Node* selection_source);
 
    /**
     * @brief createSelectionMask
     * Creates a selection mask, which can be used to store selections.
     * @param name - the name of the layer.
     * @return a SelectionMask
     */
    SelectionMask* createSelectionMask(const QString &name);
 
    /**
     * @brief createTransparencyMask
     * Creates a transparency mask, which can be used to assign transparency to regions.
     * @param name - the name of the layer.
     * @return a TransparencyMask
     */
    TransparencyMask* createTransparencyMask(const QString &name);
 
    /**
     * @brief createTransformMask
     * Creates a transform mask, which can be used to apply a transformation non-destructively.
     * @param name - the name of the layer mask.
     * @return a TransformMask
     */
    TransformMask* createTransformMask(const QString &name);
 
    /**
     * @brief createColorizeMask
     * Creates a colorize mask, which can be used to color fill via keystrokes.
     * @param name - the name of the layer.
     * @return a TransparencyMask
     */
    ColorizeMask* createColorizeMask(const QString &name);
 
    /**
     * @brief projection creates a QImage from the rendered image or
     * a cutout rectangle.
     */
    QImage projection(int x = 0, int y = 0, int w = 0, int h = 0) const;
 
    /**
     * @brief thumbnail create a thumbnail of the given dimensions.
     *
     * If the requested size is too big a null QImage is created.
     *
     * @return a QImage representing the layer contents.
     */
    QImage thumbnail(int w, int h) const;
 
 
    /**
     * [low-level] Lock the image without waiting for all the internal job queues are processed
     *
     * WARNING: Don't use it unless you really know what you are doing! Use barrierLock() instead!
     *
     * Waits for all the **currently running** internal jobs to complete and locks the image
     * for writing. Please note that this function does **not** wait for all the internal
     * queues to process, so there might be some non-finished actions pending. It means that
     * you just postpone these actions until you unlock() the image back. Until then, then image
     * might easily be frozen in some inconsistent state.
     *
     * The only sane usage for this function is to lock the image for **emergency**
     * processing, when some internal action or scheduler got hung up, and you just want
     * to fetch some data from the image without races.
     *
     * In all other cases, please use barrierLock() instead!
     */
    void lock();
 
    /**
     * Unlocks the image and starts/resumes all the pending internal jobs. If the image
     * has been locked for a non-readOnly access, then all the internal caches of the image
     * (e.g. lod-planes) are reset and regeneration jobs are scheduled.
     */
    void unlock();
 
    /**
     * Wait for all the internal image jobs to complete and return without locking
     * the image. This function is handy for tests or other synchronous actions,
     * when one needs to wait for the result of his actions.
     */
    void waitForDone();
 
    /**
     * @brief Tries to lock the image without waiting for the jobs to finish
     *
     * Same as barrierLock(), but doesn't block execution of the calling thread
     * until all the background jobs are finished. Instead, in case of presence of
     * unfinished jobs in the queue, it just returns false
     *
     * @return whether the lock has been acquired
     */
    bool tryBarrierLock();
 
    /**
     * Starts a synchronous recomposition of the projection: everything will
     * wait until the image is fully recomputed.
     */
    void refreshProjection();
 
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * replace all existing horizontal guides with the entries in the list.
     * @param lines a list of floats containing the new guides.
     */
    Q_DECL_DEPRECATED void setHorizontalGuides(const QList<qreal> &lines);
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * replace all existing horizontal guides with the entries in the list.
     * @param lines a list of floats containing the new guides.
     */
    Q_DECL_DEPRECATED void setVerticalGuides(const QList<qreal> &lines);
 
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * set guides visible on this document.
     * @param visible whether or not the guides are visible.
     */
    Q_DECL_DEPRECATED void setGuidesVisible(bool visible);
 
    /**
     * @brief DEPRECATED - use guidesConfig() instead
     * set guides locked on this document
     * @param locked whether or not to lock the guides on this document.
     */
    Q_DECL_DEPRECATED void setGuidesLocked(bool locked);
 
    /**
     * @brief modified returns true if the document has unsaved modifications.
     */
    bool modified() const;
 
    /**
     * @brief setModified sets the modified status of the document
     * @param modified if true, the document is considered modified and closing it will ask for saving.
     */
    void setModified(bool modified);
 
    /**
     * @brief bounds return the bounds of the image
     * @return the bounds
     */
    QRect bounds() const;
 
    /****
     * Animation Related API
     *****/
 
 
    /**
     * @brief Import an image sequence of files from a directory. This will grab all
     * images from the directory and import them with a potential offset (firstFrame)
     * and step (images on 2s, 3s, etc)
     * @returns whether the animation import was successful
     */
    bool importAnimation(const QList<QString> &files, int firstFrame, int step);
 
    /**
     * @brief frames per second of document
     * @return the fps of the document
     */
    int framesPerSecond();
 
    /**
     * @brief set frames per second of document
     */
    void setFramesPerSecond(int fps);
 
    /**
     * @brief set start time of animation
     */
    void setFullClipRangeStartTime(int startTime);
 
    /**
     * @brief get the full clip range start time
     * @return full clip range start time
     */
    int fullClipRangeStartTime();
 
    /**
     * @brief set full clip range end time
     */
    void setFullClipRangeEndTime(int endTime);
 
    /**
     * @brief get the full clip range end time
     * @return full clip range end time
     */
    int fullClipRangeEndTime();
 
    /**
     * @brief get total frame range for animation
     * @return total frame range for animation
     */
    int animationLength();
 
    /**
     * @brief set temporary playback range of document
     */
    void setPlayBackRange(int start, int stop);
 
    /**
     * @brief get start time of current playback
     * @return start time of current playback
     */
    int playBackStartTime();
 
    /**
     * @brief get end time of current playback
     * @return end time of current playback
     */
    int playBackEndTime();
 
    /**
     * @brief get current frame selected of animation
     * @return current frame selected of animation
     */
    int currentTime();
 
    /**
     * @brief set current time of document's animation
     */
    void setCurrentTime(int time);
 
    /**
     * @brief annotationTypes returns the list of annotations present in the document.
     * Each annotation type is unique.
     */
    QStringList annotationTypes() const;
 
    /**
     * @brief annotationDescription gets the pretty description for the current annotation
     * @param type the type of the annotation
     * @return a string that can be presented to the user
     */
    QString annotationDescription(const QString &type) const;
 
    /**
     * @brief annotation the actual data for the annotation for this type. It's a simple
     * QByteArray, what's in it depends on the type of the annotation
     * @param type the type of the annotation
     * @return a bytearray, possibly empty if this type of annotation doesn't exist
     */
    QByteArray annotation(const QString &type);
 
    /**
     * @brief setAnnotation Add the given annotation to the document
     * @param type the unique type of the annotation
     * @param description the user-visible description of the annotation
     * @param annotation the annotation itself
     */
    void setAnnotation(const QString &type, const QString &description, const QByteArray &annotation);
 
    /**
     * @brief removeAnnotation remove the specified annotation from the image
     * @param type the type defining the annotation
     */
    void removeAnnotation(const QString &type);
 
    /**
     * @brief Allow to activate/deactivate autosave for document
     * When activated, it will use default Krita autosave settings
     * It means that even when autosave is set to True, under condition Krita will not proceed to automatic save of document:
     * - autosave is globally deactivated
     * - document is read-only
     *
     * Being able to deactivate autosave on a document can make sense when a plugin use internal document
     * (document is not exposed in a view, only created for intenal process purposes)
     *
     * @param active True to activate autosave
     */
    void setAutosave(bool active);
 
    /**
     * @brief Return autosave status for document
     * Notes:
     * - returned value is Autosave flag value
     *   Even if autosave is set to True, under condition Krita will not proceed to automatic save of document:
     *   - autosave is globally deactivated
     *   - document is read-only
     * - When autosave is set to False, Krita never execute automatic save for document
     *
     * @return True if autosave is active, otherwise False
     */
    bool autosave();
 
    /**
     * @brief Returns a GuidesConfig guides configuration for current document
     * @return a GuidesConfig object with guides configuration
     */
    GuidesConfig *guidesConfig();
 
    /**
     * @brief Set guides configuration for current document
     * @param guidesConfig a GuidesConfig object to apply for guides configuration
     *
     * To modify/set guides property on a document
@code
# get document (create one or get active one for example)
newDoc = Krita.instance().createDocument(500, 500, "Test", "RGBA", "U8", "", 300)
 
# retrieve document guides configuration
newDocGuides = newDoc.guidesConfig()
 
# update properties
newDocGuides.setColor(QColor('#ff00ff'))
newDocGuides.setLineType('dotted')
newDocGuides.setVisible(True)
newDocGuides.setLocked(True)
newDocGuides.setSnap(True)
newDocGuides.setHorizontalGuides([100,200])
 
# set guides configuration to document
newDoc.setGuidesConfig(newDocGuides)
@endcode
     */
    void setGuidesConfig(GuidesConfig *guidesConfig);
 
    /**
     * @brief Returns a GridConfig grid configuration for current document
     * @return a GridConfig object with grid configuration
     */
    GridConfig *gridConfig();
 
    /**
     * @brief Set grid configuration for current document
     * @param gridConfig a GridConfig object to apply for grid configuration
     *
     * To modify/set grid property on a document
@code
# get document (create one or get active one for example)
newDoc = Krita.instance().createDocument(500, 500, "Test", "RGBA", "U8", "", 300)
 
# retrieve document grid configuration
newDocGrid = newDoc.gridConfig()
 
# update properties
newDocGrid.setColorMain(QColor('#ff00ff'))
newDocGrid.setLineTypeMain('dashed')
newDocGrid.setVisible(True)
newDocGrid.setAngleLeft(30)
newDocGrid.setAngleRight(15)
newDocGrid.setType('isometric')
 
# set grid configuration to document
newDoc.setGridConfig(newDocGrid)
@endcode
     */
    void setGridConfig(GridConfig *gridConfig);
 
    /**
     * @brief Return current audio level for document
     * @return A value between 0.0 and 1.0 (1.0 = 100%)
     */
    qreal audioLevel() const;
 
    /**
     * @brief Set current audio level for document
     * @param level Audio volumne between 0.0 and 1.0 (1.0 = 100%)
     */
    void setAudioLevel(const qreal level);
 
    /**
     * @brief Return a list of current audio tracks for document
     * @return List of absolute path/file name of audio files
     */
    QList<QString> audioTracks() const;
 
    /**
     * @brief Set a list of audio tracks for document
     * Note: the function allows to add more than one file while from Krita's UI, importing a file
     * will replace the complete list
     *
     * The reason why this method let the ability to provide more than one file is related to
     * the internal's Krita method from KisDocument class:
     * void KisDocument::setAudioTracks(QVector<QFileInfo> f)
     *
     * @param files List of absolute path/file name of audio files
     * @return True if all files from list have been added, otherwise False (a file was not found)
     */
    bool setAudioTracks(const QList<QString> files) const;
 
private:
 
    friend class Krita;
    friend class Window;
    friend class Filter;
    friend class View;
    friend class VectorLayer;
    friend class Shape;
    QPointer<KisDocument> document() const;
    void setOwnsDocument(bool ownsDocument);
 
private:
    struct Private;
    Private *const d;
 
};
 
#endif // LIBKIS_DOCUMENT_H