Development/Tutorials/Plasma4/PythonRunner: Difference between revisions

    From KDE TechBase
    m (→‎Code: fix code indentation)
    (12 intermediate revisions by 4 users not shown)
    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 =
    First and foremost, make sure you have [[Getting Started/Build/KDE4/Python Support|Python support enabled]].
    First and foremost, make sure you have [[Getting Started/Build/KDE4/Python Support|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:
    Next, you need to setup your plasmoid's development environment. For this example, our package will be called 'msgbox_runner'. 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
    * / - The root of the package
    Line 14: Line 16:
    == The metadata.desktop file ==
    == The metadata.desktop file ==


    First, edit the metadata.desktop file, to look simlar to this:
    First, edit the metadata.desktop file so that it looks similar to this:


    <code ini>
    <syntaxhighlight lang="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>
    </syntaxhighlight>


    The last line is not strictly nessecary, but convenient. Notice the ServiceType, which differs from other Plasma objects.
    The last line is not strictly necessary, but convenient. Note that ServiceTypes value is different from other Plasma objects.


    == Code ==
    == Code ==


    <code python>
    The runner is a python class, and additionally you must provide a method for Plasma to create an instance.
    from PyKDE4 import plasmascript
     
    <syntaxhighlight lang="python">
    from PyKDE4 import plasmascript
    from PyKDE4.plasma import Plasma
    from PyKDE4.plasma import Plasma
    from PyKDE4.kdeui import KIcon, KMessageBox
    from PyKDE4.kdeui import KIcon, KMessageBox


    class MsgBoxRunner(plasmascript.Runner):
    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):
         def match(self, context):
            # called by krunner to let us add actions for the user
             if not context.isValid():
             if not context.isValid():
                 return
                 return
    Line 51: Line 61:
             q = context.query()
             q = context.query()


             if q.length < 2:
            # look for our keyword 'msg'
             if not q.startsWith("msg "):
                 return
                 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 = Plasma.QueryMatch(self.runner)
             m.setText("Message: '%s'" % q)
             m.setText("Message: '%s'" % q)
    Line 62: Line 82:
              
              
         def run(self, context, match):
         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())
             KMessageBox.messageBox(None, KMessageBox.Information, match.data().toString())




    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>
    </syntaxhighlight>


    It is as simple as that. Note that the CreateRunner function must be present, and return an instance of your runner class.
    It is as simple as that. Note that the CreateRunner function must be present, and return an instance of your runner class.
    Line 75: 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 "msgbox_runner")


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


    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 msgbox_runner
      $ kquitapp krunner
      $ kquitapp krunner
      $ # wait a moment
      $ # wait a moment
    Line 92: Line 115:
    Should you want to distribute your plugin, it is practical to pack it in a zip file that users can download:
    Should you want to distribute your plugin, it is practical to pack it in a zip file that users can download:


      $ zip <directory>
      $ zip -r msgbox_runner msgbox_runner


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


      $ plasmapkg -t runner -i mypackage.zip
      $ plasmapkg -t runner -i msgbox_runner.zip


    That's all, happy coding :-)
    That's all, happy coding :-)

    Revision as of 02:48, 30 December 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.

    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 'msgbox_runner'. 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 so that it looks similar 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 necessary, but convenient. Note that ServiceTypes value is different 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 "msgbox_runner")

    $ plasmapkg --type runner --install msgbox_runner
    

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

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

    $ plasmapkg -t runner -i msgbox_runner.zip
    

    That's all, happy coding :-)