runners.improve()

krunner is a launcher application of sorts, among other things (it also does screen locking, provides a tasks lists via ksysguard, etc...). think of it as a "run command" dialog on steroids.

the aim is to provide something that not only gives us the ability to run commands as we always have been able to, but also as a one stop shop to do, well ... anything. type in some text and you get results relevant to what you typed in. it's kind of like google for your desktop, and with the search plugin ... it pretty much is.

krunner is plugin based (though it has a few built ins too; i'll probably end up moving most/all of them out to plugins, however) so you can extend it with new functionality. each plugin gets asked what it knows about what you are typing in and those answers are returned to you in a cute little interface.

these plugins, known as runners, are based on a class in libplasma called Plasma::AbastractRunner. this means that any app that links against libplasma can get the same functionality. neat.

not so neat: Plasma::AbstractRunner was a first-draft API. while i've told everyone that libplasma will be changing between 4.0 and 4.1, i want to keep the changes as minimal as possible, especially when it comes to things that affect plugins. why? because i hate rewriting code and i really hate making others do the same. changes that affect plugins affect every programmer who has written a plugin. not good.

so i spent the day today reviewing the API for Plasma::AbstractRunner. i posted revisions on pastebin.ca for #plasma to review. Richard Moore in particular was really helpful and provided some excellent feedback and thoughts that helped make the resulting API better than i could've made it on my own.

essentially instead of only getting a search term, runners now get a full blown SearchContext object. this object handles all the results as well, sorting them into Informational, Exact and Possible categories. the results can be ranked for relevancy from 0.0 to 1.0 as well as have an associated mimetype.

the end result is a much nicer design and one that should be able to survive as is from 4.0 onwards. (having said that, i'm probably going to get hit by the "famous last words" principle ;).

the improvements include:

• future proofing. we should be able to add features and capabilities without breaking plugins.


• informational answers, such as the value of a numerical calculation, can now be selected. this means that if you enter "=14*.5" you'll see "14*.5 = 7" and if you press enter, the text area will get replace with "= 7". this was a request in a comment from my last blog as well as from Maksim-of-khtml on irc. hugs.


• runners will be able to 'mutate' the search as well as respond to it. this means we could have filtering runners, for instance, or runners that change the state of the SearchContext based on their own returned results. this should help runners keep out of each other's way better in the future.


• expensive analysis of the search term (e.g. "is this a local directory or file? what is its mimetype? is it a network protocol?") can now be centralized and done just once in the SearchContext versus in every runner that needs this information


• it's possible to have multiple searches operating in parallel if so desired


• runners can now provide a configuration for the runner itself


• handling of the options widgets for both matches and the runners is more sensible


• it will be possible to add actions (verbs) to results (nouns). this means that searching for "pizza" might result not only in a match for pizza, but the associated verb "order from pizza hut"


• we'll probably end up supporting non-C++ runners, as the new design should make it trivial to use kross for this: essentially just export the SearchContext and SearchAction objects into the Kross object


• writing a Runner is much simpler and, i think, more obvious


• probably other stuff that i've already forgotten or haven't yet realized

some regressions have been introduced, however. these include:

• the results are refreshed on every search, even if they remain the same. performance still seems to be better than the previous design, however.


• there is no asynchronous interface anymore. no runners were using the old one, anyways, and we can add a better one on top of the new design. i'm actually curious if, with a bit of work, we couldn't put the runners in their own thread(s) and thereby obviate the need for an async interface in the API (at the cost of making some of the key bits of API thread safe).

future avenues of exploration may include:

• multi-threading the searching (as noted above)


• adding a completion API so that as the user types they can get possible completions in real time


• custom visualizations of actions, so a weather response might actually provide a live weather report visualization


• researching what sorts of additional metadata would be interesting for the SearchContext


• adding action verbs to individual search returns and a user interface to make using them feel natural

as for the "writing a runner is simpler" claim, this is because there is really only one method you are required to override now: void match(Plasma::SearchContext *search) and for most runners that need to do something when a match is selected there is the void exec(Plasma::SearchAction *action) method.

to see what this all means, here is the code for the calculator runner:

CalculatorRunner::CalculatorRunner( QObject* parent, const QVariantList &args )
    : Plasma::AbstractRunner(parent)
{
    Q_UNUSED(args)
    setObjectName(i18n("Calculator"));
}

CalculatorRunner::~CalculatorRunner()
{
}

void CalculatorRunner::match(Plasma::SearchContext *search)
{
    QString cmd = search->term();

    if (cmd[0] != '=') {
        return;
    }

    cmd.remove(0, 1);
    if (QRegExp("[a-zA-Z\\]\\[]").indexIn(cmd) == -1) {
        QString result = calculate(cmd);

        if (!result.isEmpty()) {
            Plasma::SearchAction *action = search->addInformationalMatch(this);
            action->setIcon(KIcon("accessories-calculator"));
            action->setText(QString("%1 = %2").arg(cmd, result));
            action->setData("= " + result);
        }
    }
}

QString CalculatorRunner::calculate( const QString& term )
{
    QScriptEngine eng;
    QScriptValue result = eng.evaluate(term);

    if (result.isError()) {
        return QString();
    }

    return result.toString();
}

and here are the two relevant methods from the much more complex location runner, which handles opening paths, urls and web shortcuts like "gg:kde" for google, "wp:kde" for wikipedia (and unlike in kde3, it uses your default browser properly =):

void WebshortcutRunner::match(Plasma::SearchContext *search)
{
    QString term = search->term().trimmed().toLower();
    m_type = search->type();

    foreach (KService::Ptr service, m_offers) {
        foreach (QString key, service->property("Keys").toStringList()) {
            key = key.toLower() + ":";
            if (term.size() > key.size() &&
                term.startsWith(key, Qt::CaseInsensitive)) {
                QString actionText = QString("Search %1 for %2");
                actionText = actionText.arg(service->name(),
                                            term.right(term.length() - term.indexOf(':') - 1));

                QAction *action = search->addExactMatch(this);
                action->setText(actionText);
                QString url = getSearchQuery(service->property("Query").toString(), term);
                action->setData(url);

                // let's try if we can get a proper icon from the favicon cache
                QIcon icon = getFavicon(url);
                if (icon.isNull()){
                    action->setIcon(m_icon);
                } else {
                    action->setIcon(icon);
                }

                return;
            }
        }
    }

    if (m_type == Plasma::SearchContext::Directory ||
        m_type == Plasma::SearchContext::Help) {
        //kDebug() << "Locations matching because of" << m_type;
        QAction *action = search->addExactMatch(this);
        action->setText(i18n("Open %1", term));
        action->setIcon(m_icon);
        return;
    }

    if (m_type == Plasma::SearchContext::NetworkLocation) {
        QAction *action = search->addPossibleMatch(this);
        KUrl url(term);

        if (url.protocol().isEmpty()) {
            url.clear();
            url.setHost(term);
            url.setProtocol("http");
        }

        action->setText(i18n("Go to %1", url.prettyUrl()));
        action->setIcon(m_icon);
        action->setData(url.url());
        return;
    }
}

void WebshortcutRunner::exec(Plasma::SearchAction *action)
{
    QString location = action->data().toString();

    if (location.isEmpty()) {
        location = action->term();
    }

    if (m_type == Plasma::SearchContext::UnknownType ||
        (m_type == Plasma::SearchContext::NetworkLocation &&
         location.left(4) == "http")) {
        KToolInvocation::invokeBrowser(location);
    } else {
        new KRun(location, 0);
    }
}

now i'm off to techbase to write a tutorial on AbstractRunner so that people can start implementing all those great ideas in the comments on my my last blog entry. ;)

tomorrow i'll start working on the gui of krunner to make it non-fugly. if all goes well, i won't have to look much more at krunner before 4.0 is out.