diff --git a/src/plasma/containmentactions.h b/src/plasma/containmentactions.h index e331992e5..3dca10e23 100644 --- a/src/plasma/containmentactions.h +++ b/src/plasma/containmentactions.h @@ -1,177 +1,177 @@ /* * Copyright (c) 2009 Chani Armitage * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details * * You should have received a copy of the GNU Library General Public * License along with this program; if not, write to the * Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef PLASMA_CONTAINMENTACTIONS_H #define PLASMA_CONTAINMENTACTIONS_H #include #include #include #include class QAction; class KPluginMetaData; namespace Plasma { class DataEngine; class Containment; class ContainmentActionsPrivate; /** * @class ContainmentActions plasma/containmentactions.h * * @short The base ContainmentActions class * * "ContainmentActions" are components that provide actions (usually displaying a contextmenu) in * response to an event with a position (usually a mouse event). * * ContainmentActions plugins are registered using .desktop files. These files should be * named using the following naming scheme: * * plasma-containmentactions-\.desktop * */ class PLASMA_EXPORT ContainmentActions : public QObject { Q_OBJECT public: /** * Default constructor for an empty or null containmentactions */ explicit ContainmentActions(QObject *parent = nullptr); ~ContainmentActions(); -#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 64) +#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67) /** * @return the plugin info for this ContainmentActions instance, * including name, pluginName and icon * @since 5.0 * * @deprecated since 5.67, use metadata */ PLASMA_DEPRECATED_VERSION(5, 67, "use metadata()") KPluginInfo pluginInfo() const; #endif /** * @return metadata for this ContainmentActions instance * including name, pluginName and icon - * @since 5.62 + * @since 5.67 */ KPluginMetaData metadata() const; /** * This method should be called once the plugin is loaded or settings are changed. * @param config Config group to load settings * @see init **/ virtual void restore(const KConfigGroup &config); /** * This method is called when settings need to be saved. * @param config Config group to save settings **/ virtual void save(KConfigGroup &config); /** * Returns the widget used in the configuration dialog. * Add the configuration interface of the containmentactions to this widget. */ virtual QWidget *createConfigurationInterface(QWidget *parent); /** * This method is called when the user's configuration changes are accepted */ virtual void configurationAccepted(); /** * Called when a "next" action is triggered (e.g. by mouse wheel scroll). This * can be used to scroll through a list of items this plugin manages such as * windows, virtual desktops, activities, etc. * @see performPrevious */ virtual void performNextAction(); /** * Called when a "previous" action is triggered (e.g. by mouse wheel scroll). This * can be used to scroll through a list of items this plugin manages such as * windows, virtual desktops, activities, etc. * @see performNext */ virtual void performPreviousAction(); /** * Implement this to provide a list of actions that can be added to another menu * for example, when right-clicking an applet, the "Activity Options" submenu is populated * with this. */ virtual QList contextualActions(); /** * Turns a mouse or wheel event into a string suitable for a ContainmentActions * @return the string representation of the event */ static QString eventToString(QEvent *event); /** * @p newContainment the containment the plugin should be associated with. * @since 4.6 */ void setContainment(Containment *newContainment); /** * @return the containment the plugin is associated with. */ Containment *containment(); protected: /** * This constructor is to be used with the plugin loading systems * found in KPluginInfo and KService. The argument list is expected * to have one element: the KService service ID for the desktop entry. * * @param parent a QObject parent; you probably want to pass in 0 * @param args a list of strings containing one entry: the service id */ ContainmentActions(QObject *parent, const QVariantList &args); private: ContainmentActionsPrivate *const d; }; } // Plasma namespace /** * Register a containmentactions when it is contained in a loadable module */ #define K_EXPORT_PLASMA_CONTAINMENTACTIONS_WITH_JSON(libname, classname, jsonFile) \ K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) Q_DECLARE_METATYPE(Plasma::ContainmentActions *) #endif // PLASMA_CONTAINMENTACTIONS_H diff --git a/src/plasma/dataengine.h b/src/plasma/dataengine.h index d7db23478..193e59a04 100644 --- a/src/plasma/dataengine.h +++ b/src/plasma/dataengine.h @@ -1,492 +1,492 @@ /* * Copyright 2006-2007 Aaron Seigo * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details * * You should have received a copy of the GNU Library General Public * License along with this program; if not, write to the * Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef PLASMA_DATAENGINE_H #define PLASMA_DATAENGINE_H #include #include #include #include #include #include #include #include class QAbstractItemModel; namespace Plasma { class DataContainer; class DataEngineScript; class Package; class Service; class DataEnginePrivate; /** * @class DataEngine plasma/dataengine.h * * @short Data provider for plasmoids (Plasma plugins) * * This is the base class for DataEngines, which provide access to bodies of * data via a common and consistent interface. The common use of a DataEngine * is to provide data to a widget for display. This allows a user interface * element to show all sorts of data: as long as there is a DataEngine, the * data is retrievable. * * DataEngines are loaded as plugins on demand and provide zero, one or more * data sources which are identified by name. For instance, a network * DataEngine might provide a data source for each network interface. **/ class PLASMA_EXPORT DataEngine : public QObject { Q_OBJECT public: typedef QHash Dict; typedef QMap Data; typedef QMapIterator DataIterator; typedef QHash SourceDict; -#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 64) +#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67) /** * Constructor. * * @param parent The parent object. * @param plugin plugin info that describes the engine * * @deprecated since 5.67 **/ PLASMA_DEPRECATED_VERSION(5, 67, "Use KPluginMetaData") explicit DataEngine(const KPluginInfo &plugin, QObject *parent = nullptr); #endif /** * Constructor. * * @param parent The parent object. * @param plugin metadata that describes the engine * - * @since 5.62 + * @since 5.67 */ explicit DataEngine(const KPluginMetaData &plugin, QObject *parent = nullptr); explicit DataEngine(QObject *parent = nullptr, const QVariantList &args = QVariantList()); ~DataEngine() override; /** * @return a list of all the data sources available via this DataEngine * Whether these sources are currently available (which is what * the default implementation provides) or not is up to the * DataEngine to decide. **/ virtual QStringList sources() const; /** * @param source the source to target the Service at * @return a Service that has the source as a destination. The service * is parented to the DataEngine, but should be deleted by the * caller when finished with it */ Q_INVOKABLE virtual Service *serviceForSource(const QString &source); -#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 64) +#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67) /** * @return description of the plugin that implements this DataEngine * * @deprecated since 5.67, use metadata */ PLASMA_DEPRECATED_VERSION(5, 67, "Use metadata()") KPluginInfo pluginInfo() const; #endif /** * @return description of the plugin that implements this DataEngine * - * @since 5.62 + * @since 5.67 */ KPluginMetaData metadata() const; /** * Connects a source to an object for data updates. The object must * have a slot with the following signature: * @code * void dataUpdated(const QString &sourceName, const Plasma::DataEngine::Data &data); * @endcode * * The data is a QHash of QVariants keyed by QString names, allowing * one data source to provide sets of related data. * * @param source the name of the data source * @param visualization the object to connect the data source to * @param pollingInterval the frequency, in milliseconds, with which to check for updates; * a value of 0 (the default) means to update only * when there is new data spontaneously generated * (e.g. by the engine); any other value results in * periodic updates from this source. This value is * per-visualization and can be handy for items that require * constant updates such as scrolling graphs or clocks. * If the data has not changed, no update will be sent. * @param intervalAlignment the number of ms to align the interval to **/ Q_INVOKABLE void connectSource( const QString &source, QObject *visualization, uint pollingInterval = 0, Plasma::Types::IntervalAlignment intervalAlignment = Types::NoAlignment) const; /** * Connects all currently existing sources to an object for data updates. * The object must have a slot with the following signature: * @code * void dataUpdated(const QString &sourceName, const Plasma::DataEngine::Data &data); * @endcode * * The data is a QHash of QVariants keyed by QString names, allowing * one data source to provide sets of related data. * * This method may be called multiple times for the same visualization * without side-effects. This can be useful to change the pollingInterval. * * Note that this method does not automatically connect sources that * may appear later on. Connecting and responding to the sourceAdded signal * is still required to achieve that. * * @param visualization the object to connect the data source to * @param pollingInterval the frequency, in milliseconds, with which to check for updates; * a value of 0 (the default) means to update only * when there is new data spontaneously generated * (e.g. by the engine); any other value results in * periodic updates from this source. This value is * per-visualization and can be handy for items that require * constant updates such as scrolling graphs or clocks. * If the data has not changed, no update will be sent. * @param intervalAlignment the number of ms to align the interval to **/ Q_INVOKABLE void connectAllSources(QObject *visualization, uint pollingInterval = 0, Plasma::Types::IntervalAlignment intervalAlignment = Types::NoAlignment) const; /** * Disconnects a source from an object that was receiving data updates. * * @param source the name of the data source * @param visualization the object to connect the data source to **/ Q_INVOKABLE void disconnectSource(const QString &source, QObject *visualization) const; /** * Retrieves a pointer to the DataContainer for a given source. This method * should not be used if possible. An exception is for script engines that * can not provide a QMetaObject as required by connectSource for the initial * call to dataUpdated. Using this method, such engines can provide their own * connectSource API. * * @param source the name of the source. * @return pointer to a DataContainer, or zero on failure **/ Q_INVOKABLE DataContainer *containerForSource(const QString &source); /** * @return The model associated to a source if any. The ownership of the model stays with the DataContainer. * Returns 0 if there isn't any model associated or if the source doesn't exists. */ QAbstractItemModel *modelForSource(const QString &source); /** * Returns true if this engine is valid, otherwise returns false * * @return true if the engine is valid **/ bool isValid() const; /** * Returns true if the data engine is empty, which is to say that it has no * data sources currently. * * @return true if the engine has no sources currently */ bool isEmpty() const; /** * @return the name of the icon for this data engine; and empty string * is returned if there is no associated icon. **/ QString icon() const; /** * Accessor for the associated Package object if any. * * @return the Package object, or 0 if none **/ Package package() const; Q_SIGNALS: /** * Emitted when a new data source is created * * Note that you do not need to emit this yourself unless * you are reimplementing sources() and want to advertise * that a new source is available (but hasn't been created * yet). * * @param source the name of the new data source **/ void sourceAdded(const QString &source); /** * Emitted when a data source is removed. * * Note that you do not need to emit this yourself unless * you have reimplemented sources() and want to signal that * a source that was available but was never created is no * longer available. * * @param source the name of the data source that was removed **/ void sourceRemoved(const QString &source); protected: /** * When a source that does not currently exist is requested by the * consumer, this method is called to give the DataEngine the * opportunity to create one. * * The name of the data source (e.g. the source parameter passed into * setData) must be the same as the name passed to sourceRequestEvent * otherwise the requesting visualization may not receive notice of a * data update. * * If the source can not be populated with data immediately (e.g. due to * an asynchronous data acquisition method such as an HTTP request) * the source must still be created, even if it is empty. This can * be accomplished in these cases with the follow line: * * setData(name, DataEngine::Data()); * * @param source the name of the source that has been requested * @return true if a DataContainer was set up, false otherwise */ virtual bool sourceRequestEvent(const QString &source); /** * Called by internal updating mechanisms to trigger the engine * to refresh the data contained in a given source. Reimplement this * method when using facilities such as setPollingInterval. * @see setPollingInterval * * @param source the name of the source that should be updated * @return true if the data was changed, or false if there was no * change or if the change will occur later **/ virtual bool updateSourceEvent(const QString &source); /** * Sets a value for a data source. If the source * doesn't exist then it is created. * * @param source the name of the data source * @param value the data to associated with the source **/ void setData(const QString &source, const QVariant &value); /** * Sets a value for a data source. If the source * doesn't exist then it is created. * * @param source the name of the data source * @param key the key to use for the data * @param value the data to associated with the source **/ void setData(const QString &source, const QString &key, const QVariant &value); /** * Adds a set of data to a data source. If the source * doesn't exist then it is created. * * @param source the name of the data source * @param data the data to add to the source **/ void setData(const QString &source, const QVariantMap &data); /** * Removes all the data associated with a data source. * * @param source the name of the data source **/ void removeAllData(const QString &source); /** * Removes a data entry from a source * * @param source the name of the data source * @param key the data entry to remove **/ void removeData(const QString &source, const QString &key); /** * Associates a model to a data source. If the source * doesn't exist then it is created. The source will have the key "HasModel" to easily indicate there is a model present. * * The ownership of the model is transferred to the DataContainer, * so the model will be deleted when a new one is set or when the * DataContainer itself is deleted. As the DataContainer, it will be * deleted when there won't be any * visualization associated to this source. * * @param source the name of the data source * @param model the model instance */ void setModel(const QString &source, QAbstractItemModel *model); /** * Adds an already constructed data source. The DataEngine takes * ownership of the DataContainer object. The objectName of the source * is used for the source name. * * @param source the DataContainer to add to the DataEngine **/ void addSource(DataContainer *source); /** * Sets the minimum amount of time, in milliseconds, that must pass between * successive updates of data. This can help prevent too many updates happening * due to multiple update requests coming in, which can be useful for * expensive (time- or resource-wise) update mechanisms. * * The default minimumPollingInterval is -1, or "never perform automatic updates" * * @param minimumMs the minimum time lapse, in milliseconds, between updates. * A value less than 0 means to never perform automatic updates, * a value of 0 means update immediately on every update request, * a value >0 will result in a minimum time lapse being enforced. **/ void setMinimumPollingInterval(int minimumMs); /** * @return the minimum time between updates. @see setMinimumPollingInterval **/ int minimumPollingInterval() const; /** * Sets up an internal update tick for all data sources. On every update, * updateSourceEvent will be called for each applicable source. * @see updateSourceEvent * * @param frequency the time, in milliseconds, between updates. A value of 0 * will stop internally triggered updates. **/ void setPollingInterval(uint frequency); /** * Removes all data sources **/ void removeAllSources(); /** * Sets whether or not this engine is valid, e.g. can be used. * In practice, only the internal fall-back engine, the NullEngine * should have need for this. * * @param valid whether or not the engine is valid **/ void setValid(bool valid); /** * @return the list of active DataContainers. */ QHash containerDict() const; /** * Reimplemented from QObject **/ void timerEvent(QTimerEvent *event) override; /** * Sets the icon for this data engine **/ void setIcon(const QString &icon); /** * Sets a source to be stored for easy retrieval * when the real source of the data (usually a network connection) * is unavailable. * @param source the name of the source * @param store if source should be stored * @since 4.6 */ void setStorageEnabled(const QString &source, bool store); protected Q_SLOTS: /** * Removes a data source. * @param source the name of the data source to remove **/ void removeSource(const QString &source); /** * Immediately updates all existing sources when called */ void updateAllSources(); /** * Forces an immediate update to all connected sources, even those with * timeouts that haven't yet expired. This should _only_ be used when * there was no data available, e.g. due to network non-availability, * and then it becomes available. Normal changes in data values due to * calls to updateSource or in the natural progression of the monitored * object (e.g. CPU heat) should not result in a call to this method! * * @since 4.4 */ void forceImmediateUpdateOfAllVisualizations(); private: friend class DataEnginePrivate; friend class DataEngineScript; friend class DataEngineManager; friend class PlasmoidServiceJob; friend class NullEngine; Q_PRIVATE_SLOT(d, void internalUpdateSource(DataContainer *source)) Q_PRIVATE_SLOT(d, void sourceDestroyed(QObject *object)) Q_PRIVATE_SLOT(d, void scheduleSourcesUpdated()) DataEnginePrivate *const d; }; } // Plasma namespace /** * Register a data engine when it is contained in a loadable module */ #define K_EXPORT_PLASMA_DATAENGINE(libname, classname) \ K_PLUGIN_FACTORY(factory, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) #define K_EXPORT_PLASMA_DATAENGINE_WITH_JSON(libname, classname, jsonFile) \ K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) Q_DECLARE_METATYPE(Plasma::DataEngine *) #endif // multiple inclusion guard diff --git a/src/plasma/scripting/dataenginescript.h b/src/plasma/scripting/dataenginescript.h index 903066c3d..cf3f23177 100644 --- a/src/plasma/scripting/dataenginescript.h +++ b/src/plasma/scripting/dataenginescript.h @@ -1,166 +1,166 @@ /* * Copyright 2007 by Aaron Seigo * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details * * You should have received a copy of the GNU Library General Public * License along with this program; if not, write to the * Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef PLASMA_DATAENGINESCRIPT_H #define PLASMA_DATAENGINESCRIPT_H #include #include #include #include namespace Plasma { class DataEngineScriptPrivate; class Service; /** * @class DataEngineScript plasma/scripting/dataenginescript.h * * @short Provides a restricted interface for scripting a DataEngine */ class PLASMA_EXPORT DataEngineScript : public ScriptEngine { Q_OBJECT public: /** * Default constructor for a DataEngineScript. * Subclasses should not attempt to access the Plasma::DataEngine * associated with this DataEngineScript in the constructor. All * such set up that requires the DataEngine itself should be done * in the init() method. */ explicit DataEngineScript(QObject *parent = nullptr); ~DataEngineScript() override; /** * Sets the Plasma::DataEngine associated with this DataEngineScript */ void setDataEngine(DataEngine *dataEngine); /** * Returns the Plasma::DataEngine associated with this script component */ DataEngine *dataEngine() const; /** * @return a list of all the data sources available via this DataEngine * Whether these sources are currently available (which is what * the default implementation provides) or not is up to the * DataEngine to decide. By default, this returns dataEngine()->sources() */ virtual QStringList sources() const; /** * Called when the script should create a source that does not currently * exist. * * @param name the name of the source that should be created * @return true if a DataContainer was set up, false otherwise */ virtual bool sourceRequestEvent(const QString &name); /** * Called when the script should refresh the data contained in a given * source. * * @param source the name of the source that should be updated * @return true if the data was changed, or false if there was no * change or if the change will occur later **/ virtual bool updateSourceEvent(const QString &source); /** * @param source the source to targe the Service at * @return a Service that has the source as a destination. The service * is parented to the DataEngine, but may be deleted by the * caller when finished with it */ virtual Service *serviceForSource(const QString &source); protected: /** * @return absolute path to the main script file for this plasmoid */ QString mainScript() const override; /** * @return the Package associated with this plasmoid which can * be used to request resources, such as images and * interface files. */ Package package() const override; #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67) /** * @return the KPluginInfo associated with this dataengine * * @deprecated since 5.67 use metadata() */ PLASMA_DEPRECATED_VERSION(5, 67, "Use KPluginMetaData metadata()") KPluginInfo description() const; #endif /** * @return the KPluginMetaData associated with this dataengine * - * @since 5.62 + * @since 5.67 */ KPluginMetaData metadata() const; void setData(const QString &source, const QString &key, const QVariant &value); void setData(const QString &source, const QVariant &value); /** * Adds a set of values to a source * @param source the name of the source to set the data on * @values a key/value collection to add to the source * @since 4.5 */ void setData(const QString &source, const DataEngine::Data &values); void removeAllData(const QString &source); void removeData(const QString &source, const QString &key); void setMinimumPollingInterval(int minimumMs); int minimumPollingInterval() const; void setPollingInterval(uint frequency); void removeAllSources(); void addSource(DataContainer *source); DataEngine::SourceDict containerDict() const; void removeSource(const QString &source); void updateAllSources(); void forceImmediateUpdateOfAllVisualizations(); private: DataEngineScriptPrivate *const d; }; #define K_EXPORT_PLASMA_DATAENGINESCRIPTENGINE(libname, classname) \ K_PLUGIN_FACTORY(factory, registerPlugin();) #define K_EXPORT_PLASMA_DATAENGINESCRIPTENGINE_WITH_JSON(libname, classname, jsonFile) \ K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) } //Plasma namespace #endif diff --git a/src/plasma/theme.h b/src/plasma/theme.h index 80327281d..7b5822007 100644 --- a/src/plasma/theme.h +++ b/src/plasma/theme.h @@ -1,463 +1,463 @@ /* * Copyright 2006-2007 Aaron Seigo * Copyright 2013 Marco Martin * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details * * You should have received a copy of the GNU Library General Public * License along with this program; if not, write to the * Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef PLASMA_THEME_H #define PLASMA_THEME_H #include #include #include #include #include #include class KPluginMetaData; namespace Plasma { class ThemePrivate; class SvgPrivate; /** * @class Theme plasma/theme.h * * @short Interface to the Plasma theme * * * Plasma::Theme provides access to a common and standardized set of graphic * elements stored in SVG format. This allows artists to create single packages * of SVGs that will affect the look and feel of all workspace components. * * Plasma::Svg uses Plasma::Theme internally to locate and load the appropriate * SVG data. Alternatively, Plasma::Theme can be used directly to retrieve * file system paths to SVGs by name. */ class PLASMA_EXPORT Theme : public QObject { Q_OBJECT Q_PROPERTY(QString themeName READ themeName NOTIFY themeChanged) Q_PROPERTY(bool useGlobalSettings READ useGlobalSettings NOTIFY themeChanged) Q_PROPERTY(QString wallpaperPath READ wallpaperPath NOTIFY themeChanged) //fonts Q_PROPERTY(QFont defaultFont READ defaultFont NOTIFY defaultFontChanged) Q_PROPERTY(QFont smallestFont READ smallestFont NOTIFY smallestFontChanged) // stylesheet Q_PROPERTY(QString styleSheet READ styleSheet NOTIFY themeChanged) public: enum ColorRole { TextColor = 0, /**< the text color to be used by items resting on the background */ BackgroundColor = 1, /**< the default background color */ HighlightColor = 2, /**< the text highlight color to be used by items resting on the background */ HoverColor = 3, /**< color for hover effect on view */ FocusColor = 4, /**< color for focus effect on view */ LinkColor = 5, /**< color for clickable links */ VisitedLinkColor = 6, /**< color visited clickable links */ HighlightedTextColor = 7,/**< color contrasting with HighlightColor, to be used for instance with */ PositiveTextColor = 8, /**< color of foreground objects with a "positive message" connotation (usually green) */ NeutralTextColor = 9, /**< color of foreground objects with a "neutral message" connotation (usually yellow) */ NegativeTextColor = 10, /**< color of foreground objects with a "negative message" connotation (usually red) */ DisabledTextColor = 11 /**< color of disabled text @since 5.64 */ }; enum ColorGroup { NormalColorGroup = 0, ButtonColorGroup = 1, ViewColorGroup = 2, ComplementaryColorGroup = 3 }; Q_ENUM(ColorGroup) /** * Default constructor. It will be the global theme configured in plasmarc * @param parent the parent object */ explicit Theme(QObject *parent = nullptr); /** * Construct a theme. It will be a custom theme instance of themeName. * @param themeName the name of the theme to create * @param parent the parent object * @since 4.3 */ explicit Theme(const QString &themeName, QObject *parent = nullptr); ~Theme(); /** * Sets the current theme being used. */ void setThemeName(const QString &themeName); /** * @return the name of the theme. */ QString themeName() const; /** * Retrieve the path for an SVG image in the current theme. * * @param name the name of the file in the theme directory (without the * ".svg" part or a leading slash) * @return the full path to the requested file for the current theme */ QString imagePath(const QString &name) const; /** * Retrieves the default wallpaper associated with this theme. * * @param size the target height and width of the wallpaper; if an invalid size * is passed in, then a default size will be provided instead. * @return the full path to the wallpaper image */ QString wallpaperPath(const QSize &size = QSize()) const; Q_INVOKABLE QString wallpaperPathForSize(int width = -1, int height = -1) const; /** * Checks if this theme has an image named in a certain way * * @param name the name of the file in the theme directory (without the * ".svg" part or a leading slash) * @return true if the image exists for this theme */ bool currentThemeHasImage(const QString &name) const; /** * Returns the color scheme configurationthat goes along this theme. * This can be used with KStatefulBrush and KColorScheme to determine * the proper colours to use along with the visual elements in this theme. */ KSharedConfigPtr colorScheme() const; /** * Returns the text color to be used by items resting on the background * * @param role which role (usage pattern) to get the color for * @param group which group we want a color of */ QColor color(ColorRole role, ColorGroup group = NormalColorGroup) const; /** * Tells the theme whether to follow the global settings or use application * specific settings * * @param useGlobal pass in true to follow the global settings */ void setUseGlobalSettings(bool useGlobal); /** * @return true if the global settings are followed, false if application * specific settings are used. */ bool useGlobalSettings() const; /** * Provides a Plasma::Theme-themed stylesheet for hybrid (web / native Plasma) widgets. * * You can use this method to retrieve a basic default stylesheet, or to theme your * custom stylesheet you use for example in Plasma::WebView. The QString you can pass * into this method does not have to be a valid stylesheet, in fact you can use this * method to replace color placeholders with the theme's color in any QString. * * In order to use this method with a custom stylesheet, just put for example %textcolor * in your QString and it will be replaced with the theme's text (or foreground) color. * * Just like in many other methods for retrieving theme information, do not forget to * update your stylesheet upon the themeChanged() signal. * * The following tags will be replaced by corresponding colors from Plasma::Theme: * * %textcolor * %backgroundcolor * %buttonbackgroundcolor * * %link * %activatedlink * %hoveredlink * %visitedlink * * %fontfamily * %fontsize * %smallfontsize * * @param css a stylesheet to theme, leave empty for a default stylesheet containing * theming for some commonly used elements, body text and links, for example. * * @return a piece of CSS that sets the most commonly used style elements to a theme * matching Plasma::Theme. * * @since 4.5 */ QString styleSheet(const QString &css = QString()) const; /** * This is an overloaded member provided to check with file timestamp * where cache is still valid. * * @param key the name to use in the cache for this image * @param pix the pixmap object to populate with the resulting data if found * @param lastModified if non-zero, the time stamp is also checked on the file, * and must be newer than the timestamp to be loaded * * @return true when pixmap was found and loaded from cache, false otherwise * @since 4.3 **/ bool findInCache(const QString &key, QPixmap &pix, unsigned int lastModified = 0); /** * Insert specified pixmap into the cache. * If the cache already contains pixmap with the specified key then it is * overwritten. * * @param key the name to use in the cache for this pixmap * @param pix the pixmap data to store in the cache **/ void insertIntoCache(const QString &key, const QPixmap &pix); /** * Insert specified pixmap into the cache. * If the cache already contains pixmap with the specified key then it is * overwritten. * The actual insert is delayed for optimization reasons and the id * parameter is used to discard repeated inserts in the delay time, useful * when for instance the graphics to insert comes from a quickly resizing * object: the frames between the start and destination sizes aren't * useful in the cache and just cause overhead. * * @param key the name to use in the cache for this pixmap * @param pix the pixmap data to store in the cache * @param id a name that identifies the caller class of this function in an unique fashion. * This is needed to limit disk writes of the cache. * If an image with the same id changes quickly, * only the last size where insertIntoCache was called is actually stored on disk * @since 4.3 **/ void insertIntoCache(const QString &key, const QPixmap &pix, const QString &id); /** * Sets the maximum size of the cache (in kilobytes). If cache gets bigger * the limit then some entries are removed * Setting cache limit to 0 disables automatic cache size limiting. * * Note that the cleanup might not be done immediately, so the cache might * temporarily (for a few seconds) grow bigger than the limit. **/ void setCacheLimit(int kbytes); /** * Tries to load the rect of a sub element from a disk cache * * @param image path of the image we want to check * @param element sub element we want to retrieve * @param rect output parameter of the element rect found in cache * if not found or if we are sure it doesn't exist it will be QRect() * @return true if the element was found in cache or if we are sure the element doesn't exist **/ bool findInRectsCache(const QString &image, const QString &element, QRectF &rect) const; /** * Returns a list of all keys of cached rects for the given image. * * @param image path of the image for which the keys should be returned * * @return a QStringList whose elements are the entry keys in the rects cache * * @since 4.6 */ QStringList listCachedRectKeys(const QString &image) const; /** * Inserts a rectangle of a sub element of an image into a disk cache * * @param image path of the image we want to insert information * @param element sub element we want insert the rect * @param rect element rectangle **/ void insertIntoRectsCache(const QString &image, const QString &element, const QRectF &rect); /** * Discards all the information about a given image from the rectangle disk cache * * @param image the path to the image the cache is associated with **/ void invalidateRectsCache(const QString &image); /** * Frees up memory used by cached information for a given image without removing * the permanent record of it on disk. * @see invalidateRectsCache * * @param image the path to the image the cache is associated with */ void releaseRectsCache(const QString &image); -#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 64) +#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67) /** * @return plugin info for this theme, with information such as * name, description, author, website etc * @since 5.0 * * @deprecated since 5.67, use KPluginMetaData */ PLASMA_DEPRECATED_VERSION(5, 67, "Use KPluginMetaData metadata()") KPluginInfo pluginInfo() const; #endif /** * @return metadata for this theme, with information such as * name, description, author, website etc - * @since 5.64 + * @since 5.67 */ KPluginMetaData metadata() const; /** * @return The default application font * @since 5.0 */ QFont defaultFont() const; /** * @return The smallest readable font * @since 5.0 */ QFont smallestFont() const; /** This method allows Plasma to enable and disable the background * contrast effect for a given theme, improving readability. The * value is read from the "enabled" key in the "ContrastEffect" * group in the Theme's metadata file. * The configuration in the metadata.desktop file of the theme * could look like this (for a lighter background): * \code * [ContrastEffect] * enabled=true * contrast=0.45 * intensity=0.45 * saturation=1.7 * \endcode * @return Whether or not to enable the contrasteffect * @since 5.0 */ bool backgroundContrastEnabled() const; /** This method allows Plasma to set a background contrast effect * for a given theme, improving readability. The value is read * from the "contrast" key in the "ContrastEffect" group in the * Theme's metadata file. * @return The contrast provided to the contrasteffect * @since 5.0 * @see backgroundContrastEnabled */ qreal backgroundContrast() const; /** This method allows Plasma to set a background contrast effect * for a given theme, improving readability. The value is read * from the "intensity" key in the "ContrastEffect" group in the * Theme's metadata file. * @return The intensity provided to the contrasteffect * @since 5.0 * @see backgroundContrastEnabled */ qreal backgroundIntensity() const; /** This method allows Plasma to set a background contrast effect * for a given theme, improving readability. The value is read * from the "saturation" key in the "ContrastEffect" group in the * Theme's metadata file. * @return The saturation provided to the contrasteffect * @since 5.0 * @see backgroundContrastEnabled */ qreal backgroundSaturation() const; /** This method allows Plasma to enable and disable the blurring * of what is behind the background for a given theme. The * value is read from the "enabled" key in the "BlurBehindEffect" * group in the Theme's metadata file. Default is @c true. * * The configuration in the metadata.desktop file of the theme * could look like this: * \code * [BlurBehindEffect] * enabled=false * \endcode * @return Whether or not to enable blurring of what is behind * @since 5.57 */ bool blurBehindEnabled() const; /** * Returns the size of the letter "M" as rendered on the screen with the given font. * This values gives you a base size that: * * scales dependent on the DPI of the screen * * Scales with the default font as set by the user * You can use it like this in QML Items: * \code * Item { * width: theme.mSize(theme.defaultFont).height * height: width * } * \endcode * This allows you to dynamically scale elements of your user interface with different font settings and * different physical outputs (with different DPI). * @param font The font to use for the metrics. * @return The size of the letter "M" as rendered on the screen with the given font. * @since 5.0 */ Q_INVOKABLE QSizeF mSize(const QFont &font = QGuiApplication::font()) const; QString backgroundPath(const QString &image) const; Q_SIGNALS: /** * Emitted when the user changes the theme. Stylesheet usage, colors, etc. should * be updated at this point. However, SVGs should *not* be repainted in response * to this signal; connect to Svg::repaintNeeded() instead for that, as Svg objects * need repainting not only when themeChanged() is emitted; moreover Svg objects * connect to and respond appropriately to themeChanged() internally, emitting * Svg::repaintNeeded() at an appropriate time. */ void themeChanged(); /** Notifier for change of defaultFont property */ void defaultFontChanged(); /** Notifier for change of smallestFont property */ void smallestFontChanged(); private: friend class SvgPrivate; friend class FrameSvg; friend class FrameSvgPrivate; friend class ThemePrivate; ThemePrivate *d; }; } // Plasma namespace #endif // multiple inclusion guard