KQuickAddons::ConfigModule
#include <KQuickAddons/ConfigModule>

Public Types | |
enum | Button { NoAdditionalButton = 0, Help = 1, Default = 2, Apply = 4 } |
typedef QFlags< Button > | Buttons |
Properties | |
KQuickAddons::ConfigModule::Buttons | buttons |
int | columnWidth |
int | currentIndex |
int | defaultsIndicatorsVisible |
int | depth |
QString | description |
QQuickItem | mainUi |
QString | name |
bool | needsAuthorization |
bool | needsSave |
QString | quickHelp |
bool | representsDefaults |
QString | rootOnlyMessage |
bool | useRootOnlyMessage |
![]() | |
objectName | |
Signals | |
void | authActionNameChanged () |
void | buttonsChanged () |
void | columnWidthChanged (int width) |
void | currentIndexChanged (int index) |
void | defaultsIndicatorsVisibleChanged () |
void | depthChanged (int index) |
void | needsAuthorizationChanged () |
void | needsSaveChanged () |
void | pagePushed (QQuickItem *page) |
void | pageRemoved () |
void | passiveNotificationRequested (const QString &message, const QVariant &timeout, const QString &actionText, const QJSValue &callBack) |
void | quickHelpChanged () |
void | representsDefaultsChanged () |
void | rootOnlyMessageChanged () |
void | useRootOnlyMessageChanged () |
Public Slots | |
virtual void | defaults () |
virtual void | load () |
void | pop () |
void | push (const QString &fileName, const QVariantMap &propertyMap=QVariantMap()) |
void | push (QQuickItem *item) |
virtual void | save () |
void | setDefaultsIndicatorsVisible (bool visible) |
void | showPassiveNotification (const QString &message, const QVariant &timeout=QVariant(), const QString &actionText=QString(), const QJSValue &callBack=QJSValue()) |
QQuickItem * | takeLast () |
Public Member Functions | |
ConfigModule (const KAboutData *aboutData, QObject *parent=nullptr, const QVariantList &args=QVariantList()) | |
ConfigModule (const KPluginMetaData &metaData, QObject *parent=nullptr, const QVariantList &args=QVariantList()) | |
ConfigModule (QObject *parent, const KPluginMetaData &metaData, const QVariantList &args=QVariantList()) | |
ConfigModule (QObject *parent=nullptr, const QVariantList &args=QVariantList()) | |
~ConfigModule () override | |
const KAboutData * | aboutData () const |
QString | authActionName () const |
Buttons | buttons () const |
int | columnWidth () const |
int | currentIndex () const |
bool | defaultsIndicatorsVisible () const |
int | depth () const |
QString | description () const |
QQmlEngine * | engine () const |
QString | errorString () const |
QQuickItem * | mainUi () |
QString | name () const |
bool | needsAuthorization () const |
bool | needsSave () const |
QString | quickHelp () const |
bool | representsDefaults () const |
QString | rootOnlyMessage () const |
void | setAboutData (const KAboutData *about) |
void | setAuthActionName (const QString &action) |
void | setButtons (const Buttons btn) |
void | setColumnWidth (int width) |
void | setCurrentIndex (int index) |
void | setNeedsAuthorization (bool needsAuth) |
void | setNeedsSave (bool needs) |
void | setQuickHelp (const QString &help) |
void | setRepresentsDefaults (bool defaults) |
void | setRootOnlyMessage (const QString &message) |
void | setUseRootOnlyMessage (bool on) |
QQmlComponent::Status | status () const |
QQuickItem * | subPage (int index) const |
bool | useRootOnlyMessage () const |
![]() | |
QObject (QObject *parent) | |
bool | blockSignals (bool block) |
const QObjectList & | children () const const |
QMetaObject::Connection | connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const |
void | deleteLater () |
void | destroyed (QObject *obj) |
bool | disconnect (const char *signal, const QObject *receiver, const char *method) const const |
bool | disconnect (const QObject *receiver, const char *method) const const |
void | dumpObjectInfo () |
void | dumpObjectInfo () const const |
void | dumpObjectTree () |
void | dumpObjectTree () const const |
QList< QByteArray > | dynamicPropertyNames () const const |
virtual bool | event (QEvent *e) |
virtual bool | eventFilter (QObject *watched, QEvent *event) |
T | findChild (const QString &name, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QRegExp ®Exp, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QString &name, Qt::FindChildOptions options) const const |
bool | inherits (const char *className) const const |
void | installEventFilter (QObject *filterObj) |
bool | isWidgetType () const const |
bool | isWindowType () const const |
void | killTimer (int id) |
virtual const QMetaObject * | metaObject () const const |
void | moveToThread (QThread *targetThread) |
QString | objectName () const const |
void | objectNameChanged (const QString &objectName) |
QObject * | parent () const const |
QVariant | property (const char *name) const const |
Q_CLASSINFO (Name, Value) | |
Q_DISABLE_COPY (Class) | |
Q_DISABLE_COPY_MOVE (Class) | |
Q_DISABLE_MOVE (Class) | |
Q_EMIT Q_EMIT | |
Q_ENUM (...) | |
Q_ENUM_NS (...) | |
Q_ENUMS (...) | |
Q_FLAG (...) | |
Q_FLAG_NS (...) | |
Q_FLAGS (...) | |
Q_GADGET Q_GADGET | |
Q_INTERFACES (...) | |
Q_INVOKABLE Q_INVOKABLE | |
Q_NAMESPACE Q_NAMESPACE | |
Q_NAMESPACE_EXPORT (EXPORT_MACRO) | |
Q_OBJECT Q_OBJECT | |
Q_PROPERTY (...) | |
Q_REVISION Q_REVISION | |
Q_SET_OBJECT_NAME (Object) | |
Q_SIGNAL Q_SIGNAL | |
Q_SIGNALS Q_SIGNALS | |
Q_SLOT Q_SLOT | |
Q_SLOTS Q_SLOTS | |
T | qFindChild (const QObject *obj, const QString &name) |
QList< T > | qFindChildren (const QObject *obj, const QRegExp ®Exp) |
QList< T > | qFindChildren (const QObject *obj, const QString &name) |
T | qobject_cast (const QObject *object) |
T | qobject_cast (QObject *object) |
QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT | |
void | removeEventFilter (QObject *obj) |
void | setObjectName (const QString &name) |
void | setParent (QObject *parent) |
bool | setProperty (const char *name, const QVariant &value) |
bool | signalsBlocked () const const |
int | startTimer (int interval, Qt::TimerType timerType) |
int | startTimer (std::chrono::milliseconds time, Qt::TimerType timerType) |
QThread * | thread () const const |
Static Public Member Functions | |
static ConfigModule * | qmlAttachedProperties (QObject *object) |
![]() | |
QMetaObject::Connection | connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, Functor functor) |
bool | disconnect (const QMetaObject::Connection &connection) |
bool | disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method) |
bool | disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method) |
bool | disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method) |
QString | tr (const char *sourceText, const char *disambiguation, int n) |
QString | trUtf8 (const char *sourceText, const char *disambiguation, int n) |
Additional Inherited Members | |
![]() | |
typedef | QObjectList |
![]() | |
virtual void | childEvent (QChildEvent *event) |
virtual void | connectNotify (const QMetaMethod &signal) |
virtual void | customEvent (QEvent *event) |
virtual void | disconnectNotify (const QMetaMethod &signal) |
bool | isSignalConnected (const QMetaMethod &signal) const const |
int | receivers (const char *signal) const const |
QObject * | sender () const const |
int | senderSignalIndex () const const |
virtual void | timerEvent (QTimerEvent *event) |
Detailed Description
The base class for configuration modules.
Configuration modules are realized as plugins that are loaded only when needed.
The module in principle is a simple widget displaying the item to be changed. The module has a very small interface.
All the necessary glue logic and the GUI bells and whistles are provided by the control center and must not concern the module author.
To write a config module, you have to create a C++ library and an accompaning QML user interface. The library must contain a factory function like the following:
The constructor of the ConfigModule then looks like this:
The QML part must be in the KPackage format, installed under share/kpackage/kcms.
- See also
- KPackage::Package
The package must have the same name as the KAboutData componentName, to be installed by CMake with the command:
The "packagedir" is the subdirectory in the source tree where the package sources are located, and "kcm_componentName" is the componentname passed to the KAboutData in the C++ part. Finally "kcms" is the literal string "kcms", so that the package is installed as a configuration module (and not some other kind of package). The main config dialog UI will be the file ui/main.qml from the package (or what X-KPackage-MainScript value is in the package metadata desktop file).
The QML part can access all the properties of ConfigModule (together with the properties defined in its subclass) by accessing to the global object "kcm", or with the import of "org.kde.kcm 1.0" the ConfigModule attached property.
See https://techbase.kde.org/Development/Tutorials/KCM_HowTo for more detailed documentation.
Definition at line 118 of file configmodule.h.
Member Enumeration Documentation
◆ Button
An enumeration type for the buttons used by this module.
You should only use Help, Default and Apply. The rest is obsolete. NoAdditionalButton can be used when we do not want have other button that Ok Cancel
- See also
- ConfigModule::buttons
- ConfigModule::setButtons
Definition at line 145 of file configmodule.h.
Constructor & Destructor Documentation
◆ ConfigModule() [1/4]
|
explicit |
Base class for all KControlModules.
- Note
- do not emit changed signals here, since they are not yet connected to any slot.
- Parameters
-
aboutData becomes owned by the ConfigModule
- Deprecated:
- since 5.88, use ConfigModule(QObject*, KPluginMetaData, QVariantList)
Definition at line 86 of file configmodule.cpp.
◆ ConfigModule() [2/4]
|
explicit |
- Note
- do not emit changed signals here, since they are not yet connected to any slot.
- Parameters
-
metaData description for the plugin: it will generate a KAboutData from that
- Since
- 5.11
- Deprecated:
- since 5.88, use ConfigModule(QObject*, KPluginMetaData, QVariantList)
Definition at line 95 of file configmodule.cpp.
◆ ConfigModule() [3/4]
|
explicit |
Base class for all KControlModules.
- Note
- do not emit changed signals here, since they are not yet connected to any slot.
- Since
- 5.88
Definition at line 116 of file configmodule.cpp.
◆ ConfigModule() [4/4]
|
explicit |
Base class for all KControlModules.
- Note
- do not emit changed signals here, since they are not yet connected to any slot.
Definition at line 110 of file configmodule.cpp.
◆ ~ConfigModule()
|
override |
Destroys the module.
Definition at line 123 of file configmodule.cpp.
Member Function Documentation
◆ aboutData()
const KAboutData * KQuickAddons::ConfigModule::aboutData | ( | ) | const |
This is generally only called for the KBugReport.
If you override you should have it return a pointer to a constant.
- Returns
- the KAboutData for this module
- Deprecated:
- since 5.88. Use the KPluginMetaData the ConfigModule was instantiated from.
Definition at line 424 of file configmodule.cpp.
◆ authActionName()
QString KQuickAddons::ConfigModule::authActionName | ( | ) | const |
Returns the action previously set with setAuthActionName().
By default its an invalid action.
- Returns
- The action that has to be authorized to execute the save() method.
Definition at line 385 of file configmodule.cpp.
◆ authActionNameChanged
|
signal |
The auth action name has changed: this signal will relay it to the actual KCM.
◆ buttons()
Buttons KQuickAddons::ConfigModule::buttons | ( | ) | const |
Indicate which buttons will be used.
The return value is a value or'ed together from the Button enumeration type.
- See also
- ConfigModule::setButtons
◆ buttonsChanged
|
signal |
Buttons to display changed.
◆ columnWidth()
int KQuickAddons::ConfigModule::columnWidth | ( | ) | const |
returns the width the kcm wants in column mode.
If a columnWidth is valid ( > 0 ) and less than the systemsettings' view width, more than one will be visible at once, and the first page will be a sidebar to the last page pushed. As default, this is -1 which will make the shell always show only one page at a time.
- Since
- 5.50
◆ columnWidthChanged
|
signal |
Emitted when the wanted column width of the kcm changes.
- Since
- 5.50
◆ currentIndex()
int KQuickAddons::ConfigModule::currentIndex | ( | ) | const |
- Returns
- the index of the page this kcm should display
- Since
- 5.53
◆ currentIndexChanged
|
signal |
Emitted when the current page changed.
- Since
- 5.53
◆ defaults
|
virtualslot |
Sets the configuration to sensible default values.
This method is called when the user clicks the "Default" button. It should set the display to useful values.
Definition at line 419 of file configmodule.cpp.
◆ defaultsIndicatorsVisible()
bool KQuickAddons::ConfigModule::defaultsIndicatorsVisible | ( | ) | const |
- Returns
- defaultness indicator visibility
- Since
- 5.73
◆ defaultsIndicatorsVisibleChanged
|
signal |
Emitted when kcm need to display indicators for field with non default value.
- Since
- 5.73
◆ depth()
int KQuickAddons::ConfigModule::depth | ( | ) | const |
- Returns
- how many pages this kcm has. It is guaranteed to be at least 1 (the main ui) plus how many times a new page has been pushed without pop
◆ depthChanged
|
signal |
Emitted when the number of pages changed.
- Since
- 5.53
◆ description()
QString KQuickAddons::ConfigModule::description | ( | ) | const |
- Returns
- the description of the config module
- Since
- 5.41
◆ engine()
QQmlEngine * KQuickAddons::ConfigModule::engine | ( | ) | const |
- Returns
- the qml engine that built the main config UI
Definition at line 390 of file configmodule.cpp.
◆ errorString()
QString KQuickAddons::ConfigModule::errorString | ( | ) | const |
The error string in case the mainUi failed to load.
- Returns
- 5.64
Definition at line 404 of file configmodule.cpp.
◆ load
|
virtualslot |
Load the configuration data into the module.
The load method sets the user interface elements of the module to reflect the current settings stored in the configuration files.
This method is invoked whenever the module should read its configuration (most of the times from a config file) and update the user interface. This happens when the user clicks the "Reset" button in the control center, to undo all of his changes and restore the currently valid settings. It is also called right after construction.
Definition at line 409 of file configmodule.cpp.
◆ mainUi()
QQuickItem* KQuickAddons::ConfigModule::mainUi | ( | ) |
- Returns
- The main UI for this configuration module. It's a QQuickItem coming from the QML package named the same as the KAboutData's component name for this config module
◆ name()
QString KQuickAddons::ConfigModule::name | ( | ) | const |
- Returns
- the name of the config module
- Since
- 5.41
◆ needsAuthorization()
bool KQuickAddons::ConfigModule::needsAuthorization | ( | ) | const |
Returns the value previously set with setNeedsAuthorization() or setAuthActionName().
By default it's false
.
- Returns
true
if the module's save() method requires authorization,false
otherwise
◆ needsAuthorizationChanged
|
signal |
Emits this signal whenever the need for root authorization to save changes.
◆ needsSave()
bool KQuickAddons::ConfigModule::needsSave | ( | ) | const |
True when the module has something changed and needs save.
◆ needsSaveChanged
|
signal |
Indicate that the state of the modules contents has changed.
This signal is emitted whenever the state of the configuration shown in the module changes. It allows the module container to keep track of unsaved changes.
◆ pagePushed
|
signal |
Emitted when a new sub page is pushed.
- Since
- 5.50
◆ pageRemoved
|
signal |
Emitted when a sub page is popped.
- Since
- 5.50
◆ passiveNotificationRequested
|
signal |
Emitted when the kcm wants the shell to display a passive notification.
- Since
- 5.68
◆ pop
|
slot |
pop the last page of the KCM hierarchy, the page is destroyed
- Since
- 5.50
Definition at line 257 of file configmodule.cpp.
◆ push
|
slot |
Push a new sub page in the KCM hierarchy: pages will be seen as a Kirigami PageRow.
- Since
- 5.50
Definition at line 213 of file configmodule.cpp.
◆ quickHelp()
QString KQuickAddons::ConfigModule::quickHelp | ( | ) | const |
Return a quick-help text.
This method is called when the module is docked. The quick-help text should contain a short description of the module and links to the module's help files. You can use HTML formatting tags in the text.
- Note
- make sure the quick help text gets translated (use i18n()).
◆ quickHelpChanged
|
signal |
Indicate that the module's quickhelp has changed.
Emit this signal whenever the module's quickhelp changes. Modules implemented as tabbed dialogs might want to implement per-tab quickhelp for example.
◆ representsDefaults()
bool KQuickAddons::ConfigModule::representsDefaults | ( | ) | const |
True when the module state represents the default settings.
◆ representsDefaultsChanged
|
signal |
Indicate that the state of the modules contents has changed in a way that it might represents the defaults settings, or stopped representing them.
◆ rootOnlyMessage()
QString KQuickAddons::ConfigModule::rootOnlyMessage | ( | ) | const |
Get the RootOnly message for this module.
When the module must be run as root, or acts differently for root and a normal user, it is sometimes useful to customize the message that appears at the top of the module when used as a normal user. This function returns this customized message. If none has been set, a default message will be used.
- See also
- ConfigModule::setRootOnlyMessage
◆ rootOnlyMessageChanged
|
signal |
Indicate that the module's root message has changed.
Emits this signal whenever the module's root message changes.
◆ save
|
virtualslot |
Save the configuration data.
The save method stores the config information as shown in the user interface in the config files.
If necessary, this method also updates the running system, e.g. by restarting applications. This normally does not apply for KSettings::Dialog modules where the updating is taken care of by KSettings::Dispatcher.
save is called when the user clicks "Apply" or "Ok".
Definition at line 414 of file configmodule.cpp.
◆ setAboutData()
void KQuickAddons::ConfigModule::setAboutData | ( | const KAboutData * | about | ) |
This sets the KAboutData returned by aboutData() The about data is now owned by ConfigModule.
Definition at line 446 of file configmodule.cpp.
◆ setAuthActionName()
void KQuickAddons::ConfigModule::setAuthActionName | ( | const QString & | action | ) |
Set if the module's save() method requires authorization to be executed.
It will still have to execute the action itself using the KAuth library, so this method is not technically needed to perform the action, but using this method will ensure that hosting applications like System Settings or kcmshell behave correctly.
- Parameters
-
action the action that will be used by this ConfigModule
Definition at line 372 of file configmodule.cpp.
◆ setButtons()
void KQuickAddons::ConfigModule::setButtons | ( | const Buttons | btn | ) |
Sets the buttons to display.
Help: shows a "Help" button.
Default: shows a "Use Defaults" button.
Apply: in kcontrol this will show an "Apply" and "Reset" button, in kcmshell this will show an "Ok", "Apply" and "Cancel" button.
If Apply is not specified, kcmshell will show a "Close" button.
- See also
- ConfigModule::buttons
Definition at line 286 of file configmodule.cpp.
◆ setColumnWidth()
void KQuickAddons::ConfigModule::setColumnWidth | ( | int | width | ) |
◆ setCurrentIndex()
void KQuickAddons::ConfigModule::setCurrentIndex | ( | int | index | ) |
Sets the current page index this kcm should display.
- Since
- 5.53
Definition at line 356 of file configmodule.cpp.
◆ setDefaultsIndicatorsVisible
|
slot |
Change defaultness indicator visibility.
- Parameters
-
visible
- Since
- 5.73
Definition at line 546 of file configmodule.cpp.
◆ setNeedsAuthorization()
void KQuickAddons::ConfigModule::setNeedsAuthorization | ( | bool | needsAuth | ) |
Set if the module's save() method requires authorization to be executed.
The module can set this property to true
if it requires authorization. It will still have to execute the action itself using the KAuth library, so this method is not technically needed to perform the action, but using this and/or the setAuthActionName() method will ensure that hosting applications like System Settings or kcmshell behave correctly.
Called with true
, this method will set the action to "org.kde.kcontrol.name.save" where "name" is aboutData()->appName() return value. This default action won't be set if the aboutData() object is not valid.
Note that called with false
, this method will reset the action name set with setAuthActionName().
- Parameters
-
needsAuth Tells if the module's save() method requires authorization to be executed.
Definition at line 296 of file configmodule.cpp.
◆ setNeedsSave()
void KQuickAddons::ConfigModule::setNeedsSave | ( | bool | needs | ) |
Set this property to true when the user changes something in the module, signaling that a save (such as user pressing Ok or Apply) is needed.
Definition at line 503 of file configmodule.cpp.
◆ setQuickHelp()
void KQuickAddons::ConfigModule::setQuickHelp | ( | const QString & | help | ) |
Sets the quick help.
Definition at line 487 of file configmodule.cpp.
◆ setRepresentsDefaults()
void KQuickAddons::ConfigModule::setRepresentsDefaults | ( | bool | defaults | ) |
Set this property to true when the user sets the state of the module to the default settings (e.g.
clicking Defaults would do nothing).
Definition at line 522 of file configmodule.cpp.
◆ setRootOnlyMessage()
void KQuickAddons::ConfigModule::setRootOnlyMessage | ( | const QString & | message | ) |
Sets the RootOnly message.
This message will be shown at the top of the module if useRootOnlyMessage is set. If no message is set, a default one will be used.
- See also
- ConfigModule::rootOnlyMessage
Definition at line 451 of file configmodule.cpp.
◆ setUseRootOnlyMessage()
void KQuickAddons::ConfigModule::setUseRootOnlyMessage | ( | bool | on | ) |
Change whether or not the RootOnly message should be shown.
Following the value of on
, the RootOnly message will be shown or not.
- See also
- ConfigModule::useRootOnlyMessage
Definition at line 466 of file configmodule.cpp.
◆ showPassiveNotification
|
slot |
Ask the shell to show a passive notification.
- Parameters
-
message The message text to display timeout (optional) the timeout, either in milliseconds or the strings "short" and "long" actionText (optional) The notification can have a button with this text callBack (optional) If actionText is set and callBack is a JavaScript function, it will be called when the use clicks the button.
- Since
- 5.68
Definition at line 276 of file configmodule.cpp.
◆ status()
QQmlComponent::Status KQuickAddons::ConfigModule::status | ( | ) | const |
◆ takeLast
|
slot |
remove and return the last page of the KCM hierarchy: the popped page won't be deleted, it's the caller's responsibility to manage the lifetime of the returned item
- Returns
- the last page if any, nullptr otherwise
- Since
- 5.89
Definition at line 264 of file configmodule.cpp.
◆ useRootOnlyMessage()
bool KQuickAddons::ConfigModule::useRootOnlyMessage | ( | ) | const |
Tell if KControl should show a RootOnly message when run as a normal user.
In some cases, the module don't want a RootOnly message to appear (for example if it has already one). This function tells KControl if a RootOnly message should be shown
◆ useRootOnlyMessageChanged
|
signal |
Emits this signal whenever the root only message gets used or discarded.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Feb 3 2023 04:13:02 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.