KQuickAddons::ConfigModule

#include <KQuickAddons/ConfigModule>

Inheritance diagram for KQuickAddons::ConfigModule:

Public Types

enum  Button { NoAdditionalButton = 0, Help = 1, Default = 2, Apply = 4 }
 
typedef QFlags< ButtonButtons
 

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
 
- Properties inherited from QObject
 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())
 

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=nullptr, const QVariantList &args=QVariantList())
 
 ~ConfigModule ()
 
const KAboutDataaboutData () const
 
QString authActionName () const
 
Buttons buttons () const
 
int columnWidth () const
 
int currentIndex () const
 
bool defaultsIndicatorsVisible () const
 
int depth () const
 
QString description () const
 
QQmlEngineengine () const
 
QString errorString () const
 
QQuickItemmainUi ()
 
QString name () const
 
bool needsAuthorization () const
 
bool needsSave ()
 
QString quickHelp () const
 
bool representsDefaults ()
 
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
 
QQuickItemsubPage (int index) const
 
bool useRootOnlyMessage () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () 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< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, 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 QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () 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
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const 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)
 
QThreadthread () const const
 

Static Public Member Functions

static ConfigModuleqmlAttachedProperties (QObject *object)
 
- Static Public Member Functions inherited from QObject
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 *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
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, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 

Additional Inherited Members

- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
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
 
QObjectsender () 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:

#include <KPluginFactory>
K_PLUGIN_FACTORY(MyConfigModuleFactory, registerPlugin<MyConfigModule>() )

The constructor of the ConfigModule then looks like this:

YourConfigModule::YourConfigModule( QObject* parent )
: ConfigModule( parent )
{
<kcm name>, i18n( "..." ),
KDE_VERSION_STRING, QString(), KAboutLicense::GPL,
i18n( "Copyright 2006 ..." ) );
about->addAuthor( i18n(...) );
setAboutData( about );
.
.
.
}

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: kpackage_install_package(package kcm_componentName kcms) given "package" 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. 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.

import QtQuick 2.1
import QtQuick.Controls 1.0 as QtControls
import org.kde.kcm 1.0
import org.kde.plasma.core 2.0 as PlasmaCore
Item {
//implicitWidth and implicitHeight will be used as initial size
//when loaded in kcmshell5
implicitWidth: units.gridUnit * 20
implicitHeight: units.gridUnit * 20
text: kcm.needsSave
}
}

See https://techbase.kde.org/Development/Tutorials/KCM_HowTo for more detailed documentation.

Definition at line 114 of file configmodule.h.

Member Enumeration Documentation

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 142 of file configmodule.h.

Constructor & Destructor Documentation

KQuickAddons::ConfigModule::ConfigModule ( const KAboutData aboutData,
QObject parent = nullptr,
const QVariantList &  args = QVariantList() 
)
explicit

Base class for all KControlModules.

Note
do not emit changed signals here, since they are not yet connected to any slot.
Parameters
aboutDatabecomes owned by the ConfigModule

Definition at line 75 of file configmodule.cpp.

KQuickAddons::ConfigModule::ConfigModule ( const KPluginMetaData metaData,
QObject parent = nullptr,
const QVariantList &  args = QVariantList() 
)
explicit
Note
do not emit changed signals here, since they are not yet connected to any slot.
Parameters
metaDatadescription for the plugin: it will generate a KAboutData from that
Since
5.11

Definition at line 81 of file configmodule.cpp.

KQuickAddons::ConfigModule::ConfigModule ( QObject parent = nullptr,
const QVariantList &  args = QVariantList() 
)
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 93 of file configmodule.cpp.

KQuickAddons::ConfigModule::~ConfigModule ( )

Destroys the module.

Definition at line 98 of file configmodule.cpp.

Member Function Documentation

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

Definition at line 388 of file configmodule.cpp.

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 350 of file configmodule.cpp.

void KQuickAddons::ConfigModule::authActionNameChanged ( )
signal

The auth action name has changed: this signal will relay it to the actual KCM.

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
void KQuickAddons::ConfigModule::buttonsChanged ( )
signal

Buttons to display changed.

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
void KQuickAddons::ConfigModule::columnWidthChanged ( int  width)
signal

Emitted when the wanted column width of the kcm changes.

Since
5.50
int KQuickAddons::ConfigModule::currentIndex ( ) const
Returns
the index of the page this kcm should display
Since
5.53
void KQuickAddons::ConfigModule::currentIndexChanged ( int  index)
signal

Emitted when the current page changed.

Since
5.53
void KQuickAddons::ConfigModule::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 384 of file configmodule.cpp.

bool KQuickAddons::ConfigModule::defaultsIndicatorsVisible ( ) const
Returns
defaultness indicator visibility
Since
5.73
void KQuickAddons::ConfigModule::defaultsIndicatorsVisibleChanged ( )
signal

Emitted when kcm need to display indicators for field with non default value.

Since
5.73
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
void KQuickAddons::ConfigModule::depthChanged ( int  index)
signal

Emitted when the number of pages changed.

Since
5.53
QString KQuickAddons::ConfigModule::description ( ) const
Returns
the description of the config module
Since
5.41
QQmlEngine * KQuickAddons::ConfigModule::engine ( ) const
Returns
the qml engine that built the main config UI

Definition at line 355 of file configmodule.cpp.

QString KQuickAddons::ConfigModule::errorString ( ) const

The error string in case the mainUi failed to load.

Returns
5.64

Definition at line 369 of file configmodule.cpp.

void KQuickAddons::ConfigModule::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 374 of file configmodule.cpp.

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
QString KQuickAddons::ConfigModule::name ( ) const
Returns
the name of the config module
Since
5.41
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
void KQuickAddons::ConfigModule::needsAuthorizationChanged ( )
signal

Emits this signal whenever the need for root authorization to save changes.

bool KQuickAddons::ConfigModule::needsSave ( )

True when the module has something changed and needs save.

void KQuickAddons::ConfigModule::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.

void KQuickAddons::ConfigModule::pagePushed ( QQuickItem page)
signal

Emitted when a new sub page is pushed.

Since
5.50
void KQuickAddons::ConfigModule::pageRemoved ( )
signal

Emitted when a sub page is popped.

Since
5.50
void KQuickAddons::ConfigModule::passiveNotificationRequested ( const QString message,
const QVariant timeout,
const QString actionText,
const QJSValue callBack 
)
signal

Emitted when the kcm wants the shell to display a passive notification.

Since
5.68
void KQuickAddons::ConfigModule::pop ( )
slot

pop the last page of the KCM hierarchy

Since
5.50

Definition at line 234 of file configmodule.cpp.

void KQuickAddons::ConfigModule::push ( const QString fileName,
const QVariantMap &  propertyMap = QVariantMap() 
)
slot

Push a new sub page in the KCM hierarchy: pages will be seen as a Kirigami PageRow.

Since
5.50

Definition at line 188 of file configmodule.cpp.

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()).
void KQuickAddons::ConfigModule::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.

bool KQuickAddons::ConfigModule::representsDefaults ( )

True when the module state represents the default settings.

void KQuickAddons::ConfigModule::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.

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
void KQuickAddons::ConfigModule::rootOnlyMessageChanged ( )
signal

Indicate that the module's root message has changed.

Emits this signal whenever the module's root message changes.

void KQuickAddons::ConfigModule::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 379 of file configmodule.cpp.

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 393 of file configmodule.cpp.

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
actionthe action that will be used by this ConfigModule

Definition at line 337 of file configmodule.cpp.

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 257 of file configmodule.cpp.

void KQuickAddons::ConfigModule::setColumnWidth ( int  width)

Sets the column width we want.

Since
5.50

Definition at line 306 of file configmodule.cpp.

void KQuickAddons::ConfigModule::setCurrentIndex ( int  index)

Sets the current page index this kcm should display.

Since
5.53

Definition at line 321 of file configmodule.cpp.

void KQuickAddons::ConfigModule::setDefaultsIndicatorsVisible ( bool  visible)
slot

Change defaultness indicator visibility.

Parameters
visible
Since
5.73

Definition at line 488 of file configmodule.cpp.

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
needsAuthTells if the module's save() method requires authorization to be executed.

Definition at line 267 of file configmodule.cpp.

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 453 of file configmodule.cpp.

void KQuickAddons::ConfigModule::setQuickHelp ( const QString help)

Sets the quick help.

Definition at line 437 of file configmodule.cpp.

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 468 of file configmodule.cpp.

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 401 of file configmodule.cpp.

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 416 of file configmodule.cpp.

void KQuickAddons::ConfigModule::showPassiveNotification ( const QString message,
const QVariant timeout = QVariant(),
const QString actionText = QString(),
const QJSValue callBack = QJSValue() 
)
slot

Ask the shell to show a passive notification.

Parameters
messageThe 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 247 of file configmodule.cpp.

QQmlComponent::Status KQuickAddons::ConfigModule::status ( ) const

The status of the mainUi component.

Since
5.64

Definition at line 360 of file configmodule.cpp.

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

See also
ConfigModule::setUseRootOnlyMessage
void KQuickAddons::ConfigModule::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:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Dec 3 2020 22:39:31 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.