README.md

KRunner Dart

A user-friendly API for KDE's KRunner application.

With KRunner Dart you can create plugins for KDE's KRunner application in an easy and sane way. The API is designed to be type safe, null safe, and easy to use.

Unlike the C++ or Python APIs, KRunner Dart provides code completion and documentation in tooltips for a better development experience.

• KRunner Dart
  • Features
    • Documentation in tooltips
    • Code completion
  • Usage
    • Creating plugins
  • Documentation
  • Installing
  • Support
  • License
  • Contributing

Features

• Type safe
• Null safe
• Named parameters
• API Documentation

Documentation in tooltips

Code completion

Usage

Creating plugins

import 'package:krunner/krunner.dart';

Future<void> main() async {
  /// Create a runner instance.
  final runner = KRunnerPlugin(
    identifier: 'com.example.plugin_name',
    name: '/plugin_name',
    matchQuery: (String query) async {
      /// If the KRunner query matches exactly `hello` we return a match.
      if (query == 'hello') {
        return [
          QueryMatch(
            id: 'uniqueMatchId',
            title: 'This is presented to the user',
            icon: 'checkmark',
            rating: QueryMatchRating.exact,
            relevance: 1.0,
            properties: QueryMatchProperties(subtitle: 'Subtitle for match'),
          ),
        ];
      } else {
        return []; // Empty response (no matches).
      }
    },
    retrieveActions: () async => [
      SecondaryAction(
        id: 'uniqueActionId',
        text: 'hoverText',
        icon: 'addressbook-details',
      ),
    ],
    runAction: ({required String actionId, required String matchId}) async {
      if (actionId == 'uniqueActionId') {
        print('User clicked secondary action!');
      }
    },
  );

  /// Start the runner.
  await runner.init();
}

Refer to the example directory for a complete example, including instructions for debugging and installing plugins.

For a real-world example of a plugin made with this API see VSCode Runner.

Documentation

In addition to the documentation available in IDE code completion and hover popups, the API Documentation is available online.

Installing

Add to dependencies:

dart pub add krunner

Support

If you encounter any issues or have any questions, please file an issue on the GitHub repository.

License

You are free to copy, modify, and distribute KRunner Dart with attribution under the terms of the BSD 3-Clause License. See the LICENSE file for details.

Contributing

Contributions are welcome! Feel free to open an issue or a pull request on the GitHub repository.