File indexing completed on 2024-06-16 10:06:24

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2009 David Nolden <david.nolden.kdevelop@art-master.de>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef _THUMBSEQUENCECREATOR_H_
0009 #define _THUMBSEQUENCECREATOR_H_
0010 
0011 #include "thumbcreator.h"
0012 
0013 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 101)
0014 
0015 #include <qglobal.h>
0016 
0017 #include <memory>
0018 
0019 class ThumbSequenceCreatorPrivate;
0020 
0021 /**
0022  * @class ThumbSequenceCreator thumbsequencecreator.h <KIO/ThumbSequenceCreator>
0023  *
0024  * @see ThumbCreator
0025  *
0026  * This is an extension of ThumbCreator that allows creating a thumbnail sequence for
0027  * a file. If your thumbnail plugin can create a thumbnail sequence, you should base it
0028  * on ThumbSequenceCreator instead of ThumbCreator, and should use sequenceIndex()
0029  * to decide what thumbnail you generate.
0030  *
0031  * You also need to set the following key in the thumbcreator .desktop file
0032  * \code
0033  * HandleSequences=true;
0034  * \endcode
0035  *
0036  * @deprecated since 5.101, use KIO::ThumbnailCreator instead
0037  *
0038  * @since 4.3
0039  */
0040 // KF6 TODO: put this in the KIO namespace
0041 class KIOWIDGETS_EXPORT ThumbSequenceCreator : public ThumbCreator
0042 {
0043 public:
0044     Q_DISABLE_COPY(ThumbSequenceCreator)
0045 
0046     /**
0047      * @deprecated since 5.101, use KIO::ThumbnailCreator instead
0048      */
0049     KIOWIDGETS_DEPRECATED_VERSION(5, 101, "Use KIO::ThumbnailCreator instead")
0050     ThumbSequenceCreator();
0051     ~ThumbSequenceCreator() override;
0052 
0053     /**
0054      * If this thumb-creator can create a sequence of thumbnails,
0055      * it should use this to decide what sequence item to use.
0056      *
0057      * If the value is zero, the standard thumbnail should be created.
0058      *
0059      * This can be used for example to create thumbnails for different
0060      * timeframes in videos(For example 0m, 10m, 20m, ...).
0061      *
0062      * If your thumb-creator supports a high granularity, like a video,
0063      * you can respect the sub-integer precision coming from the float.
0064      * Else, just round the index to an integer.
0065      *
0066      * If the end of your sequence is reached, the sequence should start
0067      * from the beginning, or continue in some other way.
0068      */
0069     float sequenceIndex() const;
0070 
0071     /**
0072      * Sets the sequence-index for this thumb creator.
0073      * @see sequenceIndex
0074      */
0075     void setSequenceIndex(float index);
0076 
0077     /**
0078      * Returns the point at which this thumb-creator's sequence indices
0079      * will wrap around (loop).
0080      *
0081      * Usually, the frontend will call setSequenceIndex() with indices
0082      * that increase indefinitely with time, e.g. as long as the user
0083      * keeps hovering a video file. Most thumb-creators however only
0084      * want to display a finite sequence of thumbs, after which their
0085      * sequence repeats.
0086      *
0087      * This method can return the sequence index at which this
0088      * thumb-creator's sequence starts wrapping around to the start
0089      * again ("looping"). The frontend may use this to generate only
0090      * thumbs up to this index, and then use cached versions for the
0091      * repeating sequence instead.
0092      *
0093      * Like sequenceIndex(), fractional values can be used if the
0094      * wraparound does not happen at an integer position, but
0095      * frontends handling only integer sequence indices may choose
0096      * to round it down.
0097      *
0098      * By default, this method returns a negative index, which signals
0099      * the frontend that it can't rely on this fixed-length sequence.
0100      *
0101      * @since 5.80
0102      */
0103     float sequenceIndexWraparoundPoint() const;
0104 
0105 protected:
0106     /**
0107      * Sets the point at which this thumb-creator's sequence indices
0108      * will wrap around.
0109      *
0110      * @see sequenceIndexWraparoundPoint()
0111      * @since 5.80
0112      */
0113     void setSequenceIndexWraparoundPoint(float wraparoundPoint);
0114 
0115 private:
0116     std::unique_ptr<ThumbSequenceCreatorPrivate> d;
0117 };
0118 
0119 typedef ThumbCreator *(*newCreator)();
0120 
0121 #endif
0122 
0123 #endif