KIO

thumbsequencecreator.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2009 David Nolden <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef _THUMBSEQUENCECREATOR_H_
9 #define _THUMBSEQUENCECREATOR_H_
10 
11 #include "thumbcreator.h"
12 
13 #include <qglobal.h>
14 
15 #include <memory>
16 
17 class ThumbSequenceCreatorPrivate;
18 
19 /**
20  * @class ThumbSequenceCreator thumbsequencecreator.h <KIO/ThumbSequenceCreator>
21  *
22  * @see ThumbCreator
23  *
24  * This is an extension of ThumbCreator that allows creating a thumbnail sequence for
25  * a file. If your thumbnail plugin can create a thumbnail sequence, you should base it
26  * on ThumbSequenceCreator instead of ThumbCreator, and should use sequenceIndex()
27  * to decide what thumbnail you generate.
28  *
29  * You also need to set the following key in the thumbcreator .desktop file
30  * \code
31  * HandleSequences=true;
32  * \endcode
33  *
34  * @since 4.3
35  */
36 // KF6 TODO: put this in the KIO namespace
37 class KIOWIDGETS_EXPORT ThumbSequenceCreator : public ThumbCreator
38 {
39 public:
40  Q_DISABLE_COPY(ThumbSequenceCreator)
42  ~ThumbSequenceCreator() override;
43 
44  /**
45  * If this thumb-creator can create a sequence of thumbnails,
46  * it should use this to decide what sequence item to use.
47  *
48  * If the value is zero, the standard thumbnail should be created.
49  *
50  * This can be used for example to create thumbnails for different
51  * timeframes in videos(For example 0m, 10m, 20m, ...).
52  *
53  * If your thumb-creator supports a high granularity, like a video,
54  * you can respect the sub-integer precision coming from the float.
55  * Else, just round the index to an integer.
56  *
57  * If the end of your sequence is reached, the sequence should start
58  * from the beginning, or continue in some other way.
59  */
60  float sequenceIndex() const;
61 
62  /**
63  * Sets the sequence-index for this thumb creator.
64  * @see sequenceIndex
65  */
66  void setSequenceIndex(float index);
67 
68  /**
69  * Returns the point at which this thumb-creator's sequence indices
70  * will wrap around (loop).
71  *
72  * Usually, the frontend will call setSequenceIndex() with indices
73  * that increase indefinitely with time, e.g. as long as the user
74  * keeps hovering a video file. Most thumb-creators however only
75  * want to display a finite sequence of thumbs, after which their
76  * sequence repeats.
77  *
78  * This method can return the sequence index at which this
79  * thumb-creator's sequence starts wrapping around to the start
80  * again ("looping"). The frontend may use this to generate only
81  * thumbs up to this index, and then use cached versions for the
82  * repeating sequence instead.
83  *
84  * Like sequenceIndex(), fractional values can be used if the
85  * wraparound does not happen at an integer position, but
86  * frontends handling only integer sequence indices may choose
87  * to round it down.
88  *
89  * By default, this method returns a negative index, which signals
90  * the frontend that it can't rely on this fixed-length sequence.
91  *
92  * @since 5.80
93  */
94  float sequenceIndexWraparoundPoint() const;
95 
96 protected:
97  /**
98  * Sets the point at which this thumb-creator's sequence indices
99  * will wrap around.
100  *
101  * @see sequenceIndexWraparoundPoint()
102  * @since 5.80
103  */
104  void setSequenceIndexWraparoundPoint(float wraparoundPoint);
105 
106 private:
107  std::unique_ptr<ThumbSequenceCreatorPrivate> d;
108 };
109 
110 typedef ThumbCreator *(*newCreator)();
111 
112 #endif
Base class for thumbnail generator plugins.
Definition: thumbcreator.h:85
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Nov 29 2021 22:53:08 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.