Friday, January 30, 2009

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

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")) {
// Perform the default action


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.


Dread Knight said...

Nice stuff!

As i told you before, quicksand looks like ass with that actions list poping out on the right side from the middle of it, in that plain rectangle box heh....

Can you make it something more like this please?
(That's gnome do btw)

dilettante said...

@Dread Knight I placed the completion box on the right side of the dialog so it won't cover the actions when they appear. It just mimics the behavior of the Primer interface of Quicksilver.

I know most people prefer Bezel which most Quicksilver like applications such as gnome do emulate, but I can't really modify QuickSand now for the 4.2 branch. Any major changes will have to wait till 4.3.

I'll add a more detailed per-interface configuration that will allow you to disable the completion box (or maybe change the position) among other things for 4.3 :)

Mason Carten said...

Ultimately, an issue that I am fervent about. I have looked for information of this topic for the last several hours. Your site is greatly treasured. Mason, from web hosting coupons

alexjackson1976gmail said...

Hi! Your idea is good. I like the additional actions you are putting for the KRUNNER. It's really great. Congrats! Xtreme NO

Aloysius said...

I think there are mixed type of reviews regarding KRunner - do you think it really work ? Phen375

MâHâßuß ßHuiyân said...

I just found your blog and want to say thank you ! What an enjoyable time looking through so many sites. It is really nice post thanks for sharing and just keep up the good work !

Data Entry Jobs | Data Entry Training | Flash Photo Gallery | Medprax™ | Bangladeshi Exporters | Cars for Travelers | Search Engine Marketing | Live Stream Sports on HD

MâHâßuß ßHuiyân said...

I just found your blog and want to say thank you ! It is really nice post thanks for sharing and just keep up the good work !

Flash Photo Gallery ! Medprax™ ! Bangladeshi Exporters ! Cars for Travelers