Multiple Actions for KRunner in KDE 4.2

I'd been meaning to blog in a quite a while but didn't quite have the time to do so. For much of December and January I had been exclusively using Ruby. It got to the point that when I finally got a little bored with Ruby and decided to resume work on KDE related projects again, it took several seconds for it to register in my brain that comments don't begin with a # in C++. Anyway, now that 4.2.0 is released I figured I could give a semi-technical discussion of what's new in 4.2.0 with regards to KRunner.

Multiple action support

As mentioned in some of my previous posts, KRunner now supports multiple actions. What does this mean for ordinary users? Well, prior to 4.2, runners (or the plugins that provide the matches for a search), could only provide a default action usually corresponding to "open". For example, given an html document match, KRunner would open it with the default viewer, in most cases the web browser. This isn't a problem if you wanted to view the file, however, if you wanted to edit it with a text editor, this behavior is not ideal. Multiple action support allows us to add another action such as "Edit" that would allow us to edit the file instead of opening it with the default browser. We could even add another action to open the file with a different browser.

Unfortunately, there are no runners included with 4.2.0 that support multiple actions. For this reason, I am bundling together two runners that support multiple actions and releasing it in kde-apps.org. The first runner is a modified desktop search runner that adds open with actions and service menu support. For those of you who were former Katapult users and grew fond of the Amarok plugin, the service menu support will allow you to play, append to your playlist, or queue any track nepomuk has found. There is a typo in the service menu desktop file though, replace amarok -e with amarok -a. You'll also need to create a script to call the correct DBus methods because the service menu contains an outdated command for the "append and play" action.


The second runner is a window management runner. It can perform any action that supported by the task manager of the panel, aside from moving a window. That means you can minimize/maximize, or shade a window, move it to a different desktop, keep it above other windows and many other actions.

For the developer seeking to take advantage of multiple action support, reimplementing the actionsForMatch method and modifying the run method are all that need to be done. For convenience, commonly used actions can be stored by the runner by calling the addAction method and the action can be retrieved by calling the action method. The run method of the runner needs to distinguish between actions and can determine the selected action by calling the selectedAction method of the match. Because it is possible that the user interface does not support multiple actions, the run method also needs to support a default action in case no action is selected.

For example given:

void FooRunner::run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
{
 foo(match);
}

adding multiple action support is as easy as:

QList FooRunner::actionsForMatch(const Plasma::QueryMatch &match)
{
    // In some cases we'd want to examine the match and choose appropriate actions based on it
    // but in this example we assume all matches have the same actions
    if (!action("foo")) {
        addAction("foo", QIcon(), "Foo");
    }
    if (!action("bar")) {
        addAction("bar", QIcon(), "Bar");
    }
    QList ret << action("foo") << action("bar");
    return ret;    
}

void FooRunner::run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
{
    // Check if an action was selected
    if (QAction *a = match.selectedAction()) {
        if (a == action("foo")) {
            break;
        }
        bar(match);
        return;
    }
    // Perform the default action
    foo(match);
}

QuickSand

Despite the fact that KRunner now comes with multiple-action support, the default interface does not expose this functionality. KRunner now comes with an alternative interface that allows you to make use of multiple actions. In order to enable it, open the configuration dialog by clicking on the wrench icon, click on the interface tab and select the "task-oriented" option.

If a match supports multiple actions, a second pane containing the actions will appear below the match pane. Press tab to switch to the action pane or click on the arrow icon on the top right portion of the action pane.

Note: Bugfixes for QuickSand didn't make it in time for 4.2.0 so the experience might not be as smooth as it could be. I missed the tagging by 28 hours. Oops. They should be in 4.2.1 though.