Difference between revisions of "Development/Tutorials/Plasma/PythonRunner"

Jump to: navigation, search
m (Distributing the plugin)
(bit more text, use "hello world", clarify)
Line 1: Line 1:
In this example, we're going to be writing a sample KRunner plugin, that will just display the entered text in a messagebox. Then we'll test it and finally package it up for distribution.
+
In this example, we're going to be writing a sample KRunner plugin, that will just display the entered text in a messagebox. It is also demonstrated how to use a keyword, and how to add help to krunner.
 +
 
 +
After creating the plugin, we'll test it and finally package it up for distribution.
  
 
= Building =
 
= Building =
Line 48: Line 50:
  
 
     def init(self)
 
     def init(self)
 +
        # called upon creation to let us run any intialization
 
         # tell the user how to use this runner
 
         # tell the user how to use this runner
 
         self.addSyntax(Plasma.RunnerSyntax("msg :q:", "Display :q: in a messagebox"))
 
         self.addSyntax(Plasma.RunnerSyntax("msg :q:", "Display :q: in a messagebox"))
Line 62: Line 65:
 
             return
 
             return
  
         # ignore less than 3 characters
+
         # ignore less than 3 characters (in addition to the keyword)
 
         if q.length < 7:
 
         if q.length < 7:
 
             return
 
             return
Line 85: Line 88:
  
 
def CreateRunner(parent):
 
def CreateRunner(parent):
 +
    # called by krunner, must simply return an instance of the runner object
 
     return MsgBoxRunner(parent)
 
     return MsgBoxRunner(parent)
 
</code>
 
</code>
Line 94: Line 98:
 
= Test the plugin =
 
= Test the plugin =
  
Now you should be ready to test the plugin, to install it, simply run
+
Now you should be ready to test the plugin, to install it, simply run (given the plugin is in directory "runner_msgbox")
  
  $ plasmapkg --type runner --install <directory>
+
  $ plasmapkg --type runner --install runner_msgbox
  
Now press ALT + F2 and type 'something', and you should see the command "Message 'something' in the match list, and if you run it, a messagebox should show, telling you "something"
+
Now press ALT + F2 and type 'msg hello world', and you should see the command "Message 'hello world' in the match list, and if you run it, a messagebox should show, greeting "hello world"
  
 
I have learned that krunner should be restarted between updates, so if you change your script and reinstall it, restart krunner:
 
I have learned that krunner should be restarted between updates, so if you change your script and reinstall it, restart krunner:
  
  $ plasmapkg --type runner --upgrade <directory>
+
  $ plasmapkg --type runner --upgrade runner_msgbox
 
  $ kquitapp krunner
 
  $ kquitapp krunner
 
  $ # wait a moment
 
  $ # wait a moment

Revision as of 21:28, 12 March 2011

In this example, we're going to be writing a sample KRunner plugin, that will just display the entered text in a messagebox. It is also demonstrated how to use a keyword, and how to add help to krunner.

After creating the plugin, we'll test it and finally package it up for distribution.

Contents

Building

First and foremost, make sure you have Python support enabled.

Next, you need to setup your plasmoid's development environment. For this example, our package will be called 'runner_msgbox'. Make a directory to put everything in. Plasma expects a certain set of files and directories to exist when loading a plasmoid package:

  • / - The root of the package
    • metadata.desktop - Metadata about the plasmoid
    • contents/ - The directory plasma looks in for all your resources
      • code/ - 'code' type resources
        • main.py - The plugin's code. You can change this in metadata.desktop.

The metadata.desktop file

First, edit the metadata.desktop file, to look simlar to this:

[Desktop Entry]

Name=Msgbox runner Comment=Sample python krunner plugin, that will show the entered text in a messagebox Type=Service Icon=dialog-information ServiceTypes=Plasma/Runner X-Plasma-API=python X-Plasma-MainScript=code/main.py X-KDE-PluginInfo-Author=<your name> X-KDE-PluginInfo-Email=<your email> X-KDE-PluginInfo-Name=msgbox_runner X-KDE-PluginInfo-Version=0.1 X-KDE-PluginInfo-Website=http://plasma.kde.org/ X-KDE-PluginInfo-License=LGPLv3 X-KDE-PluginInfo-EnabledByDefault=true

The last line is not strictly nessecary, but convenient. Notice the ServiceType, which differs from other Plasma objects.

Code

The runner is a python class, and additionally you must provide a method for Plasma to create an instance.

from PyKDE4 import plasmascript

from PyKDE4.plasma import Plasma from PyKDE4.kdeui import KIcon, KMessageBox

class MsgBoxRunner(plasmascript.Runner):

   def init(self)
       # called upon creation to let us run any intialization
       # tell the user how to use this runner
       self.addSyntax(Plasma.RunnerSyntax("msg :q:", "Display :q: in a messagebox"))
       
   def match(self, context):
       # called by krunner to let us add actions for the user
       if not context.isValid():
           return
       
       q = context.query()
       # look for our keyword 'msg'
       if not q.startsWith("msg "):
            return
       # ignore less than 3 characters (in addition to the keyword)
       if q.length < 7:
           return
       
       # strip the keyword and leading space
       q = q[3:]
       q = q.trimmed()
       # now create an action for the user, and send it to krunner
       m = Plasma.QueryMatch(self.runner)
       m.setText("Message: '%s'" % q)
       m.setType(Plasma.QueryMatch.ExactMatch)
       m.setIcon(KIcon("dialog-information"))
       m.setData(q)
       context.addMatch(q, m)
       
   def run(self, context, match):
       # called by KRunner when the user selects our action,        
       # so lets keep our promise
       KMessageBox.messageBox(None, KMessageBox.Information, match.data().toString())


def CreateRunner(parent):

   # called by krunner, must simply return an instance of the runner object
   return MsgBoxRunner(parent)

It is as simple as that. Note that the CreateRunner function must be present, and return an instance of your runner class.

This code is about minimal. Plasmascript. Runner is a Plasma.AbstractRunner

Test the plugin

Now you should be ready to test the plugin, to install it, simply run (given the plugin is in directory "runner_msgbox")

$ plasmapkg --type runner --install runner_msgbox

Now press ALT + F2 and type 'msg hello world', and you should see the command "Message 'hello world' in the match list, and if you run it, a messagebox should show, greeting "hello world"

I have learned that krunner should be restarted between updates, so if you change your script and reinstall it, restart krunner:

$ plasmapkg --type runner --upgrade runner_msgbox
$ kquitapp krunner
$ # wait a moment
$ krunner

Distributing the plugin

Should you want to distribute your plugin, it is practical to pack it in a zip file that users can download:

$ zip -r runner_msgbox runner_msgbox

The zip archive can be installed with plasmapkg, just as the directory:

$ plasmapkg -t runner -i runner_msgbox.zip

That's all, happy coding :-)


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal