Development/Tutorials/Plasma4/PythonRunner: Difference between revisions

    From KDE TechBase
    m (→‎Code: fix code indentation)
    m (→‎The metadata.desktop file: fix code indentation)
    Line 18: Line 18:
    <code ini>
    <code ini>
      [Desktop Entry]
      [Desktop Entry]
    Name=Msgbox runner
    Name=Msgbox runner
    Comment=Sample python krunner plugin, that will show the entered text in a messagebox
    Comment=Sample python krunner plugin, that will show the entered text in a messagebox
    Type=Service
    Type=Service
    Icon=dialog-information
    Icon=dialog-information
    ServiceTypes=Plasma/Runner
    ServiceTypes=Plasma/Runner
    X-Plasma-API=python
    X-Plasma-API=python
    X-Plasma-MainScript=code/main.py
    X-Plasma-MainScript=code/main.py
    X-KDE-PluginInfo-Author=<your name>   
    X-KDE-PluginInfo-Author=<your name>   
    X-KDE-PluginInfo-Email=<your email>
    X-KDE-PluginInfo-Email=<your email>
    X-KDE-PluginInfo-Name=msgbox_runner
    X-KDE-PluginInfo-Name=msgbox_runner
    X-KDE-PluginInfo-Version=0.1
    X-KDE-PluginInfo-Version=0.1
    X-KDE-PluginInfo-Website=http://plasma.kde.org/
    X-KDE-PluginInfo-Website=http://plasma.kde.org/
    X-KDE-PluginInfo-License=LGPLv3
    X-KDE-PluginInfo-License=LGPLv3
    X-KDE-PluginInfo-EnabledByDefault=true
    X-KDE-PluginInfo-EnabledByDefault=true
    </code>
    </code>



    Revision as of 17:41, 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. Then we'll test it and finally package it up for distribution.

    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

    from PyKDE4 import plasmascript
    

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

    class MsgBoxRunner(plasmascript.Runner):
           
       def match(self, context):
           if not context.isValid():
               return
           
           q = context.query()
    
           if q.length < 2:
                return
          
           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):
           KMessageBox.messageBox(None, KMessageBox.Information, match.data().toString())
    


    def CreateRunner(parent):

       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

    $ plasmapkg --type runner --install <directory>
    

    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"

    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>
    $ 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 <directory>
    

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

    $ plasmapkg -t runner -i mypackage.zip
    

    That's all, happy coding :-)