@PublicApi public interface

KeyboardShortcutManager

com.atlassian.jira.plugin.keyboardshortcut.KeyboardShortcutManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

Provides a registry of keyboard shortcuts currently available in JIRA. Keyboard shortcuts can be provided via the KeyboardShortcut plugin point. In order for keyboard shortcuts to remain consistent across a cluster, they should be added or removed simultaneously across the cluster, e.g. upon startup, not at arbitrary times such as in response to user input.

Summary

Nested Classes
enum KeyboardShortcutManager.Context Defines the context under which a keyboard shortcut is valid. 
enum KeyboardShortcutManager.Operation Defines the different operations that can be taken using a KeyboardShortcut. 
Public Methods
@Deprecated List<KeyboardShortcut> getActiveShortcuts()
This method is deprecated. uses listActiveShortcutsUniquePerContext(Map) under the hood
List<KeyboardShortcut> getAllShortcuts()
Returns an ordered list of all KeyboardShortcuts available using the plugin descriptor's 'order' attribute for sorting.
String includeShortcuts()
Returns a URL to be used to include the currently registered keyboard shortcuts in a page.
boolean isKeyboardShortcutsEnabled()
Returns if the user has keyboard shortcuts enabled.
List<KeyboardShortcut> listActiveShortcutsUniquePerContext(Map<String, Object> userContext)
Returns an ordered list of active KeyboardShortcuts, sorted using the plugin descriptor's order attribute.
void registerShortcut(String pluginModuleKey, KeyboardShortcut shortcut)
Given a complete plugin module key, this method registers a keyboard shortcut with the manager, which will make it available in the UI to end-users.
void requireShortcutsForContext(KeyboardShortcutManager.Context context)
Register that the keyboard shortcuts for the context should be included by includeShortcuts() (in addition to the global shortcuts, which are always included).
void unregisterShortcut(String pluginModuleKey)
Removes a keyboard shortcut by its complete plugin module key.

Public Methods

@Deprecated public List<KeyboardShortcut> getActiveShortcuts ()

This method is deprecated.
uses listActiveShortcutsUniquePerContext(Map) under the hood

Returns an ordered list of active KeyboardShortcuts, sorted using the plugin descriptor's order attribute.

A shortcut is active if it has not been overriden by another shortcut that uses the same key combination and has a greater value in its order attribute (see the keyboard shortcut plugin module documentation).

Returns
  • ordered list of all active keyboard shortcuts

public List<KeyboardShortcut> getAllShortcuts ()

Returns an ordered list of all KeyboardShortcuts available using the plugin descriptor's 'order' attribute for sorting. Implementations should take care to implement this method as quickly as possible since it will be called very often.

Note this method returns all registered shortcuts, even if they are not in effect (e.g. they have been overridden). This means that this method may return duplicate shortcuts.

Returns
  • ordered list of all registered keyboard shortcuts
See Also

public String includeShortcuts ()

Returns a URL to be used to include the currently registered keyboard shortcuts in a page. The URL should point to the Keyboard Shortcut REST resource. Generally this URL will look something like: /rest/api/1.0/shortcuts/500/f1e3b05a6e6db41e5b77fb8afd7ddde9/shortcuts.js

It has been suggested that webresources (with say the systemcounter) would be a good fit for this, however the problem is that the systemcounter would have to be updated everytime a plugin is enabled/disabled (so everytime JIRA is started up), which would have some adverse side effects:

  • The system counter would get really large eventually
  • All webresources would no longer be cached after a restart of JIRA and would have to be downloaded again.
That's why this uses a md5 checksum of the shortcuts in the URL instead of the web-resources approach.

It does not contain the applications context path. Also, the hash included at the end of the URL should be a hash of all keyboard shortcuts currently available such that the resource can be cached indefinitely. If a new shortcut is registered (or an old shortcut unregistered), then the hash should obviously change.

Returns
  • URL pointing to a REST resource to included keyboard shortcuts. The URL will be correctly URL-escaped, but it is not HTML escaped.
See Also

public boolean isKeyboardShortcutsEnabled ()

Returns if the user has keyboard shortcuts enabled. If the user is not logged in this will default to true

Returns
  • boolean indicating if the user has keyboard shortcuts enabled. Defaults to true if the user is not logged in.

public List<KeyboardShortcut> listActiveShortcutsUniquePerContext (Map<String, Object> userContext)

Returns an ordered list of active KeyboardShortcuts, sorted using the plugin descriptor's order attribute.

A shortcut is considered active if

  1. All conditions attached to the keyboard shortcut are fulfilled, so that the current user is allowed to use it.
  2. It has not been overriden by another shortcut of the same KeyboardShortcutManager.Context that uses the same key combination and has a greater value in its order attribute (see the keyboard shortcut plugin module documentation). Thus this list can contain multiple shortcuts with the same key combination, which all belong to a different context.

Be aware, that this operation is potentially expensive, depending on the number and type of conditions attached to the keyboard shortcuts. So store the result in favour of recalculating it.

Parameters
userContext the context to be used when evaluating, whether the user is allowed to use the shortcut; not null
Returns

public void registerShortcut (String pluginModuleKey, KeyboardShortcut shortcut)

Given a complete plugin module key, this method registers a keyboard shortcut with the manager, which will make it available in the UI to end-users.

Parameters
pluginModuleKey the complete plugin module key for this keyboard shortcut
shortcut the shortcut to register

public void requireShortcutsForContext (KeyboardShortcutManager.Context context)

Register that the keyboard shortcuts for the context should be included by includeShortcuts() (in addition to the global shortcuts, which are always included).

Parameters
context the context whose keyboard shorcuts should be included (in addition to global).

public void unregisterShortcut (String pluginModuleKey)

Removes a keyboard shortcut by its complete plugin module key.

Parameters
pluginModuleKey the key to remove