4. First steps¶

The first thing to know about Keypirinha is that you can use almost all of its features by using your keyboard only. Keep that in mind!

4.1. Start Keypirinha¶

Keypirinha is a resident application, it directly goes to background when it is started.

You can check application is running by looking for its icon in the system tray’s notification area. It is located next to the system clock on your desktop, usually in the lower-right corner of your main monitor.

Tip

This k icon also indicates any activity from the plugins (e.g. cataloging, suggesting, executing, …) by turning green. Color is restored to normal as soon as plugins have finished their jobs.

4.2. Open the LaunchBox¶

Once Keypirinha is running, press Ctrl+Win+K (by default) to show the LaunchBox…

Tip

Many former Launchy users change the default hotkey to Alt+Space

4.3. First Search¶

You can now search for the task you wish to execute.

Say you want to launch the Firefox web browser for example. Start typing its name and it will soon show up in the results list as long as Firefox is installed on your machine.

To select the desired item if not done already, you can use the Down, Up, PgDown and PgUp keys.

Once the item is selected, press Enter to launch it.

Keypirinha will then automatically go back to background…

Note

Search is case-insensitive in Keypirinha, the search term FFOX is equivalent to ffox or FfoX

4.4. Second Search¶

Keypirinha remembers the tasks you execute, so if you want to launch a task you already executed, chances are high that you will only need to type the very first couple of letters of its name to get the task at the top of the results list.

To keep going with our example, we will just type the F letter since it is the one that naturally comes to our mind when thinking about the name Firefox.

Execute this item again. You will see why in the next section below.

Second search for an already executed item

4.5. Associate a Keyword to an Item¶

This is one of the coolest search feature of Keypirinha.

Still with our example, if you happen to launch your Firefox browser a lot, you probably want to keep the number of keystrokes that are required to search and launch it to a minimum.

Keypirinha implicitly associates a keyword with a particular item once this item is executed using any of the provided action .

In the last section, we typed the search term F (or f, search is case- insensitive), before executing Firefox. Keypirinha recorded that information so every time your search term will be f, the Firefox item will be pushed up to the top of the results list.

Tip

Association is done at execution time, that is, when you actually launch the item.

Note

You may want to associate f with an other item later. In that case, just type f and select this other item before executing it. Keypirinha will change the association implicitly.

4.6. Specify arguments¶

In Keypirinha, some items accept or require arguments.

Once you typed your search term and selected the desired item, hit the Tab key (see also the space_as_tab setting).

Back to our example, Firefox currently accepts the -preferences command line option so let’s try typing this one and execute our item.

4.7. Actions¶

Items may have several associated actions.

Search and select the Firefox item again.

By default, the number of actions available for the selected item are displayed at the right side: here 8 actions. Hit the Ctrl+Enter to visualize these actions (or the Tab key until you reach the actions list).

Because this particular Firefox item is a file, a *.lnk file in this example, the following actions are made available:

Select the one you want and press Enter to execute.

4.8. Maximize the LaunchBox¶

Alt+X (or Win+Up) toggles between normal and maximized state.

You may need to temporarily extend the size of the LaunchBox sometimes in order to see the full content of some items in the results list. You can do that by either pressing Alt+X or Win+Up (toggle).

Note

This feature does not impact the geometry you manually setup in case your geometry setting is persistent. Hit Alt+X again and your previous position and size will be restored. CAUTION: If you are in persistent geometry, do not reposition/resize the window while being in maximized mode or you will loose your previous geometry.

4.9. Leave a Search¶

May you wish to abort what you were doing on the LaunchBox, press the Esc key. Press it once, to clear your search, twice to close the dialog. Note that one time is enough if you didn’t type anything.

If you wish to close the window directly, press Shift+Esc or Alt+F4.

4.10. Drag and Drop¶

The LaunchBox allows drag-and-drop operations.

For example, a file from Windows Explorer can be dropped to the search box to insert its full path.

Also, items in the results list can be dragged out. The effect of the resulting drop depends on the type of item and the destination application:

The actual file pointed at by a FILE item will be copied to the drop destination.
The text content of the URL, CMDLINE, EXPRESSION and ERROR items will be copied to the drop destination. For example:
- a URL item dropped to your web browser’s window will usually open this URL
- a CMDLINE item dropped to a text editor will insert the CMDLINE itself

Tip

Like in Windows Explorer, you can drag out FILE items using either the left mouse button to have a regular behavior, or the right mouse button to invoke a contextual menu at drop destination that allows you to choose the desired drop effect.

4.11. Clear the history¶

It is possible to clear the history of every executed items by executing the Clear History item that can always be found in the Catalog. It can be done from application’s main contextual menu as well (right click on the LaunchBox).

If you just want to erase a single item from the history, just search for it, select it and press Ctrl+Del. A message dialog will ask you to confirm the operation.

It is also possible to delete every reference to a specific package from the history by selecting a result item from this package, then clicking the Remove parent package from History action from its contextual menu.
Note that no keyboard shortcut is provided here as it is assumed to be rarely used and to avoid any mistake.

Warning

By clearing the full history, the score subsystem is also reset and you will also loose the internal dictionary of the keywords you associated with items, that is described in the Associate a Keyword to an Item section.

4.12. Configuration¶

See the Configuration section for more info.

4.13. GUI Theming¶

It is possibe to tweak Keypirinha’s GUI, see Theming for more info.

4.14. Plugins¶

Some plugins, called packages in Keypirinha, are shipped with Keypirinha and are available out of the box. See Shipped Packages.

Also, some Keypirinha users kindly shared the packages they developed to the community. You may find them useful. See Third-Party Packages.

4.15. Customize your Catalog¶

Read the Customize your Catalog chapter to discover how you can gain full control over what will be referenced in Keypirinha’s database and consequently, in search results.

4.16. Extending Keypirinha¶

Despite its apparent simplicity, Keypirinha is a generic tool that is able to welcome a very wide range of features not offered yet by the official bundled plugins. An API allows to extend Keypirinha’s features to make them fit your needs.

See the Extending Keypirinha (API) section for more info.