Development/Tutorials/KAuth/KCM HowTo - Revision history

AnneW at 15:35, 19 July 2012

2012-07-19T15:35:19Z

Agateau: header: Add link to KCM HowTo

2012-04-10T12:28:54Z

header: Add link to KCM HowTo

Neverendingo: Text replace - "" to ""

2011-06-29T19:42:17Z

Text replace - "</code>" to "</syntaxhighlight>"

Neverendingo: Text replace - "`" to ""`


2011-06-29T19:38:49Z
Text replace - "<code cpp>" to "<syntaxhighlight lang="cpp">"

				
				
				
				
			
			← Older revision
			Revision as of 19:38, 29 June 2011
			
Line 32:
Line 32:
  In your KCModule's constructor, supposing you created the action as described above, you have to do the following:   In your KCModule's constructor, supposing you created the action as described above, you have to do the following:
    
− <code cpp>setNeedsAuthorization(true);</code> + <syntaxhighlight lang="cpp">setNeedsAuthorization(true);</code>
    
  This function automatically does the following:   This function automatically does the following:
Line 45:
Line 45:
  To save your module, here's what needs to be done in the ''save()'' function of your KCM:   To save your module, here's what needs to be done in the ''save()'' function of your KCM:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  void MyKCM::save()   void MyKCM::save()
  {   {



Drf at 12:59, 12 February 2010
2010-02-12T12:59:31Z


				
				
				
				
			
			← Older revision
			Revision as of 12:59, 12 February 2010
			
Line 7:
Line 7:
  name=Creating a KCM requiring authorization upon saving|   name=Creating a KCM requiring authorization upon saving|
    
− pre=[[Development/Tutorials/KAuth/KAuth_Actions|How to use KAuth Actions]]|[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper]]| + pre=[[Development/Tutorials/KAuth/KAuth_Actions|How to use KAuth Actions]], [[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper]], Basic knowledge in creating a KCModule|
    
  next=|   next=|
Line 16:
Line 16:
  ==Introduction==   ==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.   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==   ==Creating a KCModule with KAuth==



Drf at 12:57, 12 February 2010
2010-02-12T12:57:18Z


				
				
				
				
			
			← Older revision
			Revision as of 12:57, 12 February 2010
			
Line 9:
Line 9:
  pre=[[Development/Tutorials/KAuth/KAuth_Actions|How to use KAuth Actions]]|[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper]]|   pre=[[Development/Tutorials/KAuth/KAuth_Actions|How to use KAuth Actions]]|[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper]]|
    
− next= + next=|
    
  reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html KCModule Class Reference]   reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html KCModule Class Reference]
Line 78:
Line 78:
  You should already [[Development/Tutorials/KAuth/Helper_HowTo|know how to create a KAuth helper]], so this part won't be covered here. There are, however, some strict requirements to the helper format, just like for the action name.   You should already [[Development/Tutorials/KAuth/Helper_HowTo|know how to create a KAuth helper]], so this part won't be covered here. There are, however, some strict requirements to the helper format, just like for the action name.
    
− *The helper id must be org.kde.kcontrol.<modulename>, just like in the action + *The helper id must be '''org.kde.kcontrol.<modulename>''', just like in the action
− *The helper '''must''' implement the save action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper) + *The helper '''must''' implement the ''save'' action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper)
    
  ===CMake and additional macros===   ===CMake and additional macros===



Drf at 12:55, 12 February 2010
2010-02-12T12:55:38Z


				
				
				
				
			
			← Older revision
			Revision as of 12:55, 12 February 2010
			
Line 11:
Line 11:
  next=   next=
    
− reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html KCModule Namespace Reference] + reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html KCModule Class Reference]
  }}   }}
    
Line 81:
Line 81:
  *The helper '''must''' implement the save action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper)   *The helper '''must''' implement the save action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper)
    
− ===CMake and additional macros== + ===CMake and additional macros===
  No additional macros are needed, except the [[Development/Tutorials/KAuth/Helper_HowTo|ones already shown to build the helper]].   No additional macros are needed, except the [[Development/Tutorials/KAuth/Helper_HowTo|ones already shown to build the helper]].
    
  ==Conclusion==   ==Conclusion==
− As you have seen, there are almost no differences with a KCM not requiring high privileges, especially when deploying and building the module. In fact, porting a module requiring high privileges to KAuth is extremely easy and strongly advised, both for security and consistency, since your user will be provided with a better and more integrated overall experience. + As you have seen, there are almost no differences with a KCM not requiring high privileges, especially when deploying and building the module.
  +  
  + Porting a module requiring high privileges to KAuth is extremely easy and strongly advised, both for security and consistency, since your user will be provided with a better and more integrated overall experience.



Drf at 12:54, 12 February 2010
2010-02-12T12:54:19Z


				
				
				
				
			
			← Older revision
			Revision as of 12:54, 12 February 2010
			
Line 20:
Line 20:
    
  ==Creating a KCModule with KAuth==   ==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 + The coding part is extremely easy, although this comes at the price of following some strict conventions, which also help KCM permission handling to stay consistent.
    
  ===Creating the save action===   ===Creating the save action===
Line 47:
Line 47:
  To save your module, here's what needs to be done in the ''save()'' function of your KCM:   To save your module, here's what needs to be done in the ''save()'' function of your KCM:
    
− <code> + <code cpp>
− void KclockModule::save() + void MyKCM::save()
  {   {
     QVariantMap helperargs;      QVariantMap helperargs;
Line 70:
Line 70:
  }   }
  </code>   </code>
  + 
  + The only difference you'll find with what you [[Development/Tutorials/KAuth/KAuth_Actions|are used to do when executing KAuth Actions]] is the ''authAction()'' method. This method belongs to KCModule's API and returns the action internally created by ''setNeedsAuthorization(true)'', or 0 if no action was created.
  + 
  + This action is already associated to the correct helper (see below) and ready to be executed: you just have to supply any additional arguments to it.
  + 
  + ===Creating the helper===
  + You should already [[Development/Tutorials/KAuth/Helper_HowTo|know how to create a KAuth helper]], so this part won't be covered here. There are, however, some strict requirements to the helper format, just like for the action name.
  + 
  + *The helper id must be org.kde.kcontrol.<modulename>, just like in the action
  + *The helper '''must''' implement the save action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper)
  + 
  + ===CMake and additional macros==
  + No additional macros are needed, except the [[Development/Tutorials/KAuth/Helper_HowTo|ones already shown to build the helper]].
  + 
  + ==Conclusion==
  + As you have seen, there are almost no differences with a KCM not requiring high privileges, especially when deploying and building the module. In fact, porting a module requiring high privileges to KAuth is extremely easy and strongly advised, both for security and consistency, since your user will be provided with a better and more integrated overall experience.



Drf: First draft
2010-02-12T12:39:18Z
First draft
New page
{{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}} 



{{TutorialBrowser|



series=KAuth Tutorial|



name=Creating a KCM requiring authorization upon saving|



pre=[[Development/Tutorials/KAuth/KAuth_Actions|How to use KAuth Actions]]|[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper]]|



next=



reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html KCModule Namespace Reference]

}}



==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:



<code cpp>setNeedsAuthorization(true);</code>



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:



<code>

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...

    }

  }

}

</code>

← Older revision		Revision as of 15:35, 19 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KAuth/KAuth Actions}}~~

	{{TutorialBrowser\|		{{TutorialBrowser\|