#include <IShortcutManager.h>

Inheritance diagram for IShortcutManager:

Public Types
enum	{ kDefaultIID = IID_ISHORTCUTMANAGER }

enum	ShortcutFileError { kKBSCFileNoError = 0, kKBSCFileNotFound, kKBSCFileWrongPlatform, kKBSCFileFormatWrongOrCorrupt, kKBSCFileFormatIncompatible, kKBSCFileWriteError }

Public Member Functions
virtual void	AddShortcut (ActionID actionToAddTo, const PMString &contextStr, const VirtualKey &key, int16 mods)=0

virtual void	RemoveAllShortcutsForAction (ActionID id)=0

virtual void	RemoveShortcut (const PMString &context, const VirtualKey &key, int16 mods)=0

virtual void	PerformShortcut (const IShortcutContext *context, const VirtualKey &key, int16 mods)=0

virtual bool16	IsEnabledShortcut (const IShortcutContext *context, const VirtualKey &key, int16 mods)=0

virtual ActionID	GetActionIDOfShortcut (const PMString &contextString, const VirtualKey &key, int16 mods) const =0

virtual ActionID	GetActionIDInContextChain (const IShortcutContext *context, const VirtualKey &key, int16 mods) const =0

virtual void	ClearShortcuts ()=0

virtual int32	GetNumShortcutsForAction (ActionID actionID) const =0

virtual void	GetNthShortcutForAction (ActionID actionID, int32 index, PMString contextStrOut, VirtualKey keyOut, int16 *modsOut) const =0

virtual int32	GetNumShortcutContexts () const =0

virtual IShortcutContext *	QueryNthShortcutContext (int32 index) const =0

virtual IShortcutContext *	QueryShortcutContextByName (const PMString &contextName) const =0

virtual PMString	GetShortcutSetFilename () const =0

virtual IKBSCSetsManager::KBSCArea	GetShortcutKBSCArea () const =0

virtual ShortcutFileError	ChangeShortcutSetFile (const PMString &filename, IKBSCSetsManager::KBSCArea area)=0

virtual ShortcutFileError	SaveCurrentShortcutSetFile ()=0

virtual ShortcutFileError	LoadDefaultShortcutSetFile (const PMLocaleId &locale)=0

virtual void	GetCurrentShortcut (PMString contextOut, VirtualKey keyOut, int16 *modsOut) const =0

virtual const PMString &	GetPersistedActionName (const ActionID &actionID) const =0

virtual bool16	Startup (const PMLocaleId &locale)=0

virtual void	Shutdown (const PMLocaleId &locale)=0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

This is the interface that manages the keyboard shortcuts for the application. It maintains a mapping of key combo(which is a key + 0 or more modifier keys) + shortcut context to ActionID. Whenever we get a key event that isn't handled by whatever eventhandler currently has the key focus, we check to see if it's a shortcut(by calling IsEnabledShortcut), and if it is, we execute the action by calling PerformShortcut. This interface also supports the functionality in the keyboard shortcut editor dialog, including adding & removing shortcuts, and reading and writing shortcut sets. In a Debug build, you can see some information about the shortcut matching that happens if you enable TRACE for the category "Shortcuts" from the test menu.

Member Enumeration Documentation

enum IShortcutManager::ShortcutFileError

Enumerator
kKBSCFileNoError	kKBSCFileNoError success
kKBSCFileNotFound	kKBSCFileNotFound File was not found
kKBSCFileWrongPlatform	kKBSCFileWrongPlatform File appears to be from wrong platform(i.e. trying to open windows shortcut set on mac)
kKBSCFileFormatWrongOrCorrupt	kKBSCFileFormatWrongOrCorrupt File isn't a known type of shortcut set
kKBSCFileFormatIncompatible	kKBSCFileFormatIncompatible File isn't a version that can be understood
kKBSCFileWriteError	kKBSCFileWriteError failed to write file

Member Function Documentation

virtual void IShortcutManager::AddShortcut	(	ActionID	actionToAddTo,
		const PMString &	contextStr,
		const VirtualKey &	key,
		int16	mods
	)

pure virtual

Add a shortcut

Parameters

actionToAddTo	The action that this new shortcut should invoke.
contextStr	The string for the context this shortcut should be assigned in.

See Also: IShortcutContext.

Parameters

key	The key for the new shortcut
mods	The modifier keys for the new shortcut.

See Also: KBSCModifierDefs.h

virtual ShortcutFileError IShortcutManager::ChangeShortcutSetFile	(	const PMString &	filename,
		IKBSCSetsManager::KBSCArea	area
	)

pure virtual

Update the current shortcuts to those in a file

Parameters

filename The name of the new shortcut file to use

Returns: kKBSCFileNoError if successful, else one of the errors.

virtual void IShortcutManager::ClearShortcuts ( )

pure virtual

Clear all shortcuts

virtual ActionID IShortcutManager::GetActionIDInContextChain	(	const IShortcutContext *	context,
		const VirtualKey &	key,
		int16	mods
	)		const

pure virtual

Retrieve the action associated with a shortcut. This one looks in the context passed in, as well as all the 'next' contexts.

Parameters

context The starting context. This method will also look in the rest of the context chain if the current context does not have an entry for this shortcut. Often retrieved from a call to IShortcutUtils::QueryCurrentContext()

See Also: IShortcutContext.

Parameters

key	The key for the shortcut
mods	The modifier keys for the shortcut.

See Also: KBSCModifierDefs.h

Returns: kInvalidActionID if no shortcut found in the context chain, else the ActionID of the assigned action.

virtual ActionID IShortcutManager::GetActionIDOfShortcut	(	const PMString &	contextString,
		const VirtualKey &	key,
		int16	mods
	)		const

pure virtual

Retrieve the action associated with a shortcut in a single context

Parameters

contextStr The string for the context to look for this shortcut.

See Also: IShortcutContext. Often retrieved from a call to IShortcutUtils::QueryCurrentContext()

Parameters

key	The key for the shortcut
mods	The modifier keys for the shortcut.

See Also: KBSCModifierDefs.h

Returns: kInvalidActionID if no shortcut found in this context, else the ActionID of the assigned action.

virtual void IShortcutManager::GetCurrentShortcut	(	PMString *	contextOut,
		VirtualKey *	keyOut,
		int16 *	modsOut
	)		const

pure virtual

Retrieve information about the shortcut that has been invoked. Only valid during a call to PerformShortcut. Pass nil for things you don't care about. It's quite rare for client code to need this information.

Parameters

contextStrOut	filled out with the context string for the current shortcut. Pass nil if you don't need this info.
keyOut	filled out with the key for the current shortcut. Pass nil if you don't need this info.
modsOut	filled out with the modifier keys for the current shortcut. Pass nil if you don't need this info.

virtual void IShortcutManager::GetNthShortcutForAction	(	ActionID	actionID,
		int32	index,
		PMString *	contextStrOut,
		VirtualKey *	keyOut,
		int16 *	modsOut
	)		const

pure virtual

Retrieve information about the nth shortcut associated with a particular action. Pass nil for things you don't care about.

Parameters

actionID	The action to get the shortcuts for.
index	Index of which shortcut for this action to return.
contextStrOut	filled out with the context string for the nth action. Pass nil if you don't need this info.
keyOut	filled out with the key for the nth action. Pass nil if you don't need this info.
modsOut	filled out with the modifier keys for the nth action. Pass nil if you don't need this info.

virtual int32 IShortcutManager::GetNumShortcutContexts ( ) const

pure virtual

Retrieve the number of shortcut contexts

Returns: count of known shortcut contexts

virtual int32 IShortcutManager::GetNumShortcutsForAction ( ActionID actionID ) const

pure virtual

Retrieve the number of shortcuts associated with a particular action

Parameters

actionID the action to investigate

Returns: count of how many shortcuts are assigned to this action.

virtual const PMString& IShortcutManager::GetPersistedActionName ( const ActionID & actionID ) const

pure virtual

Retrieve the action name that was persisted with shortcuts for a particular action id. Can be used to determine whether the shortcuts assigned to this action id are assigned to the wrong action by comparing with the name currently associated with the action (see IActionManager::GetActionName). This could happen if the id/name mapping for an action is dynamic and had been persisted in the preferences folder but then discarded. It's quite rare for client code to need this information.

Parameters

actionID the action to get the name of

Returns: string for the name of this action at the time of the last save.

virtual IKBSCSetsManager::KBSCArea IShortcutManager::GetShortcutKBSCArea ( ) const

pure virtual

Retrieve the area of the current shortcut set

Returns: area of current shortcut set.

virtual PMString IShortcutManager::GetShortcutSetFilename ( ) const

pure virtual

Retrieve the filename of the current shortcut set

Returns: filename of current shortcut set.

virtual bool16 IShortcutManager::IsEnabledShortcut	(	const IShortcutContext *	context,
		const VirtualKey &	key,
		int16	mods
	)

pure virtual

Check whether a shortcut is enabled

Parameters

context The starting context. This method will also look in the rest of the context chain if the current context does not have an entry for this shortcut.

See Also: IShortcutContext. Often retrieved from a call to IShortcutUtils::QueryCurrentContext()

Parameters

key	The key for the shortcut
mods	The modifier keys for the shortcut.

See Also: KBSCModifierDefs.h

Returns: kTrue if there is an enabled shortcut matching the passed in parameters.

virtual ShortcutFileError IShortcutManager::LoadDefaultShortcutSetFile ( const PMLocaleId & locale )

pure virtual

Load the default shortcut set file. For English, this is Default.indk, but in general is the file corresponding to the translation of the "#defaultKBSCSetName" string.

Returns: kKBSCFileNoError if successful, else one of the errors, most likely kKBSCFileWriteError.

virtual void IShortcutManager::PerformShortcut	(	const IShortcutContext *	context,
		const VirtualKey &	key,
		int16	mods
	)

pure virtual

Invoke the action associated with a shortcut. Should only be called if you know there is an enabled shortcut for this set of parameters.

Parameters

context The starting context. This method will also look in the rest of the context chain if the current context does not have an entry for this shortcut.

See Also: IShortcutContext. Often retrieved from a call to IShortcutUtils::QueryCurrentContext()

Parameters

key	The key for the shortcut
mods	The modifier keys for the shortcut.

See Also: KBSCModifierDefs.h

virtual IShortcutContext* IShortcutManager::QueryNthShortcutContext ( int32 index ) const

pure virtual

Query the nth shortcut context

Returns: the nth shortcut context known to the shortcut manager

virtual IShortcutContext* IShortcutManager::QueryShortcutContextByName ( const PMString & contextName ) const

pure virtual

Query a shortcut context by name

Parameters

contextName the name of the shortcut context

Returns: the IShortcutContext which matches that name, or nil if no match was found.

virtual void IShortcutManager::RemoveAllShortcutsForAction ( ActionID id )

pure virtual

Remove all shortcuts associated with a particular action

Parameters

id	The action to remove shortcuts for

virtual void IShortcutManager::RemoveShortcut	(	const PMString &	context,
		const VirtualKey &	key,
		int16	mods
	)

pure virtual

Remove a shortcut

Parameters

contextStr The string for the context this existing shortcut.

See Also: IShortcutContext.

Parameters

key	The key for the existing shortcut
mods	The modifier keys for the existing shortcut.

See Also: KBSCModifierDefs.h

virtual ShortcutFileError IShortcutManager::SaveCurrentShortcutSetFile ( )

pure virtual

Save the current shortcut set to the current shortcut file

Returns: kKBSCFileNoError if successful, else one of the errors, most likely kKBSCFileWriteError.

virtual void IShortcutManager::Shutdown ( const PMLocaleId & locale )

pure virtual

Shut down the shortcut manager. Internal use only.

virtual bool16 IShortcutManager::Startup ( const PMLocaleId & locale )

pure virtual

Start up the shortcut manager. Internal use only.

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation