Clippets - User Guide

Version 2.0

1. Overview
2. What's New
3. Installation
4. The Clippets View
5. Editing Clippet Collections
6. Editing Clippets
7. Recalling Clippets
8. Storing Clippets
9. Tags
10. Live Tags
11. Preferences
12. Live Tag Extensions
13. Developing Live Tags
14. Contact
15. Licence

Programmers typically rely heavily on the clipboard - frequently, a single clipboard isn't enough. Some desktop systems, like KDE, provide tools to support multiple clipboards, allowing the user to switch between different content previously stored in the clipboard as required.

Clippets provides a similar feature integrated into the Eclipse IDE. Among other things, this means that switching clipboards works in the same way on all platforms supported by Eclipse, which can be useful for developers frequently working on different systems.

One clipboard content item stored by the plug-in is called a "clippet". Clippets can be labelled and arranged in multiple lists called "clippet collections". Individual collections can be marked as persistent, which causes them to be stored permanently so that they are still available when Eclipse is restarted.

The following features have been added to Clippets since the initial release:

Reordering Clippets (2.0)

Clippet collections can be configured to automatically move a clippet to the top of the collection whenever it is recalled.

Tags (2.0)

Curly brace tags can be used in clippets to include custom content whenever the clippet is recalled. When recalling a clippet containing such tags, the user will be prompted with a dialogue for entering the content for the tags.

Certain predefined live tags can be replaced automatically without user intervention, e.g. by the name or path of the current file.

Styles (1.1)

Clippets can be assigned styles to change the foreground and background colours shown in clippet lists.

Clippet collection memory (1.1)

The clippet selection popup by default opens with the last clippet collection that was selected. Changing the collection also updates the Clippet View.

Popup notifications (1.1)

To provide feedback with some of the "blind" actions (e.g. recalling clippets via keyboard shorcuts), certain actions trigger notification popup notifications.

Inserting clippets (1.1)

Double clicking a clippet directly inserts the selected clippet into the current editor without changing the clipboard content.

Store to selection in popup (1.1)

Pressing Shift+Enter in the clippet storing popup dialogue stores the clipboard content into the selected clippet.

Clippets requires Java 6 and Eclipse 4.2 (Juno) or higher.

To install Clippets from the Update Site, select Help/Software Updates/Available Software from your Eclipse menu and click Add Site to add the following URL:

http://eclipse.schedenig.name

You can now open the site in the list of available software, check Clippets and click Install to begin the installation process. Clippets depends on the Popup Notifications plug-in, which will be automatically installed from the same location.

The Clippets View allows you to view and manage your clippets. You can open it from Eclipse's Window/Show View/Other... menu.

Clippets are organised in clippet collections. Each collection has a name and a few additional settings. The clippet view always shows the contents of one collection at a time; you can switch between the collections via the tabs at the top of the view. By default, Clippets starts with two collections named "Temporary" and "Persistent".

All modifications you make to clippets and clippet collections, via the Clippet View or global keyboard shortcuts, can be revoked via Eclipse's standard undo/redo actions.

To add a new collection, you can use the "Add collection" action from the view's dropdown menu. Right clicking on of the tabs at the top of the view allows you to edit or delete that specific collection. You can rearrange collections by dragging them to a new position.

The list in the view shows all the clippets in the currently selected collection. The actions in the view's action bar allow you to edit these clippets. A popup menu which appears when you right click on the selected clippets offers more options. You can also rearrange the selected clippets by dragging them to a new position within the list.

The following actions are available:

Recall

Recalls the selected clippet by copying its content to the system clipboard.

Store

Stores the current clipboard to a new clippet. The clippet will be added at the top of the clippet collection.

Store to Selection

Stores the current clipboard to the selected clippet. The clippet's previous content will be overwritten.

Delete

Deletes the selected clipptes.

Edit

Opens the Clippet Dialogue for the selected clippet.

Paste

Pastes the selected clippet into the current editor. This action can also be triggered by double clicking a clippet.

Move (clippet context menu)

Allows you to move the selected clippets to a different collection.

Add Collection (view menu)

Opens the Clippet Collection Dialogue allowing you to create a new clippet collection.

Edit Collection (collection context menu)

Opens the Clippet Collection Dialogue allowing you to edit the selected collection.

Delete Collection (collection context menu)

Deletes the selected collection.

Clippet collections are added and edited using the clippet collection dialogue:

The following properties can be configured for a clippet collection:

Name

The name for the clippet collection, as displayed in the clippets view and clippet selection dialogues.

Persistent

Whether the collection retains its clippets after you exit Eclipse. Non persistent collections will be empty when you start Eclipse.

Maximum length

If this is set, the clippet collection will not grow longer than the specified maximum length. If adding new clippets results in the collection containing more clippets than specified here, clippets will be dropped from the end of the list until the collection no longer exceeds the maximum length.

Move used clippets to top

If this option is enabled, clippets in this collection will be moved to the top of the collection automatically whenever they are recalled.

Clippets are edited using the clippet dialogue:

The following properties can be configured for a clippet:

Name

An optional name for the clippet. If this is specified, the name will be used to represent the clippet in lists. Otherwise, the clippet's content will be displayed instead.

Content

The clippet's text content as a multi line string. When hovering over this edit field, a tooltip will show a list of all available live tags, along with descriptions.

Shortcut

Allows you to select a keyboard shortcut to quickly access the clippet in the clippet dialogue..

Style

This allows you to select a style for the clippet, which affects how the clippet is shown in the clippet list. To select a style, you first have to define it in the preferences.

In addition to recalling clippets by selecting them in the clippet view, a keyboard shortcut also provides a quicker way to directly recall a clippet. By default, the shortcut to recall a clippet is CTRL+ALT+V (or COMMAND+ALT+V on Mac OS), but this can be configured in Eclipse's key preferences.

Pressing the recall clippet shortcut opens the clippet selection dialogue:

You can use the cursor keys to navigate between clippets (up/down) and clippet collections (left/right). Home can be used to jump to the clippet collection currently selected in the Clippets View, while End jumps to the default collection (the first collection in the list).

Enter will recall the selected clippet and close the dialogue, while Escape will cancel the operation. Holding the Shift key while pressing Enter will also close the dialogue, but simply insert the selected clippet into the current editor instead of recalling it to the clipboard.

You can use the Delete key to delete the selected clippet. The standard shortcuts for Undo and Redo are also available.

The dialogue also shows the configured keyboard shortcuts for the listed clippets, plus numbered shortcuts for the first ten clippets. Pressing one of these shortcuts will directly recall the corresponding clippet and close the dialogue.

There are shortcuts for storing clippets as well. By default, CTRL+ALT+C (or COMMAND+ALT+C on Mac OS) opens the clippet collection selection dialogue, which works in a similar way to the clippet selection dialogue described above. Selecting a clippet collection and pressing Enter will store the current clipboard content in a new clippet in the selected collection. Holding Shift while pressing Enter will replace the content of the selected clippet with the clipboard content.

To directly store the clipboard content to a new clippet in the clippet collection currently selected in the clippet view, another shortcut can be used. This shortcut defaults to CTRL+ALT+SHIFT+C (or COMMAND+ALT+SHIFT+C on Mac OS).

When storing clipboard text containing curly braces, each curly brace character will be duplicated to escape it and avoid it being treated as a tag.

Parts of a clippet's text surrounded by single curly braces ('{' and '}'), are called tags. Any tags in a clippet are filled in with custom content whenever the clippet is recalled.

When recalling a clippet containing tags, you will be prompted to provide the content for each tag:

Live tags are special, predefined tags that do not need to be filled out when recalling a clippet, but rather provide their content autonomously.

Some live tags support parameters to control how they are replaced. Parameters are simply appeneded to the live tag with a colon. For example, the live tag tag with the parameter param1 would look like this: tag:param1.

The following built in live tags are always available:

{file}

The name of the editor file. The parameter path will use the full file path instead of just the name. uri will use the file's URI.

{selection}

The text currently selected in the editor.

{clipboard}

The current clipboard's text content.

Additional live tags may be provided through extensions. See Live Tag Extensions for an overview of the officially provided extensions and Developing Live Tags to learn how to implement your own live tags.

Certain operations can display popup notifications, which can be useful as a confirmation for otherwise "silent" actions like recalling a clippet to the clipboard. This page allows you to disable this feature (it is enabled by default) and to change the look up of the displayed popups.

As explained earlier, each clippet can be assigned a style to highlight it in the clippets list. Before you can assign a style, you have to define it in this preference page. Each style has a name and can have a foreground or background colour.

The official Clippets update site also offers extensions providing additional live tags. These live tags depend on specific versions or extensions of the Eclipse platform that may not be available on all installations and must therefore be installed seperately.

The following live tag extensions are available:

Clippets - C/C++ Support

Provides live tags for Eclipse's CDT framework. The following tags are supported if the current editor is a C/C++ editor:

{type}

The name of the current struct or class.

{method}

The name of the current method or function.

Clippets - Java Support

Provides live tags for Eclipse's JDT framework. The following tags are supported if the current editor is a Java editor:

{type}

The name of the current type. Use the parameter full to get the fully qualified name.

{method}

The name of the current method.

{package}

The name of the current package.

This section describes how to implement custom live tags. It is targeted at Java developers who are familiar with Eclipse's concept of plug-ins and features.

Clippets offers an extension point through which plug-ins can provide their own live tags:

name.schedenig.eclipse.clippets.livetags

A plug-in can provide one or more tags in an extension of this type. Each tag has a name (the text used, in curly braces, to insert the live tag in a clippet), a description (displayed to the user in the clippet editor dialogue) and a class

The class must implement the interface name.schedenig.eclipse.clippets.java.tags.ILiveTag and override the method resolveTag(). In this method, it must return the content for the tag or null if no content is available.

Multiple extensions may provide tags with identical names. In this case, Clippets will call one extension's ILiveTag implementation and use its tag content, if it is provided. If the tag implementation provided null, the next extension is tried, until one implementation provides content. If none of the available implementations provide content, the tag is considered a non-live tag in the current context and the user will be prompted to enter its content.

To distinguish a tag with a standard name from other implementations of the same tag, the clippet editor's tool tip which shows a list of all tags, will show the name of the extension along with each tag. It is therefore recommended to provide a name for the extension if it contains tags that are only available in a specific context (e.g. an editor of a specific type), but may have alternative implementations for different contexts.

Clippets websites:

• Official Clippets website
• Facebook page
• Google+ page

Clippets was written by Marian Schedenig. You can find my website here.

Clippets is licensed under the terms of the Eclipse Public License v1.0.

Copyright © 2014 Marian Schedenig.