Development/Tutorials/KAuth/KCM HowTo

Development/Tutorials/KAuth/KAuth Actions

Creating a KCM requiring authorization upon saving

Tutorial Series	KAuth Tutorial
Previous	How to use KAuth Actions
What's Next	reading=KCModule Namespace Reference
Further Reading	n/a

Introduction

A very common use case for KAuth helper are KCModules, which sometimes need to obtain high privileges upon saving. For this reason, KAuth has been integrated into KCModule API and kcmshell's appearance, to grant developers an extremely easy way to deploy privileged KCMs, and at the same time a very consistent and usable interface to your users.

This tutorial assumes you have a basic knowledge in creating KCModules.

Creating a KCModule with KAuth

The coding part is extremely easy, although this comes at the price of following some strict conventions, which also help KCM permissions to stay consistent

Creating the save action

The action name has to follow this format:

org.kde.kcontrol.<modulename>.save

Where <modulename> is the output of aboutData()->appName(), also known as the very first parameter you supply to KAboutData constructor.

Following this format is compulsory to make the KCM work.

Adding the needed code in your KCModule's constructor

In your KCModule's constructor, supposing you created the action as described above, you have to do the following:

setNeedsAuthorization(true);

This function automatically does the following:

Creates the needed action
Crafts the Apply and Ok buttons (if any) into KPushButtons integrated with the action
Adds some visual elements to the KCM to notify the user about the status of the action (for example, if he needs to authenticate or if he's not authorized at all).

So everything is done for you. The only requirement is that setNeedsAuthorization should be called after setAboutData and setButtons, otherwise it will fail.

Adding the needed code to the save() function

To save your module, here's what needs to be done in the save() function of your KCM:

void KclockModule::save() {

 QVariantMap helperargs;
 // Populate....

 Action *action = authAction();
 action->setArguments(helperargs);

 ActionReply reply = action->execute();

 if (reply.failed())
 {
   if (reply.type() == ActionReply::KAuthError) {
         // There has been an internal KAuth error
         KMessageBox::error(this, i18n("Unable to authenticate/execute the action: %1, %2", reply.errorCode(), reply.errorDescription()));
   } else {
          // Our helper triggered a custom error
          // Act accordingly...
   }
 }

}