Inherits from NSObject
Declared in ViMap.h

Overview

A map contains keys (or key sequences) mapped to editor actions, macros or Nu expressions.

A key sequence is a string of one or more keys. A key can be a regular character like ‘a’ or ‘€’. Key characters are case sensitive, so ‘a’ is different from ‘A’.

Special keys are specified as a string within angle brackets, like <f4>, <down> or <enter>. Modifiers are prepended with a separating dash, like <control-f4>, <command-down> or <alt-enter>. Multiple modifiers are also possible: <alt-command-tab>. The order of modifiers is not significant.

The following modifiers are recognized:

  • control, ctrl or c — Control modifier
  • option, alt, meta, a or m — Option modifier
  • command, cmd or d — Command modifier
  • shift or s — Shift modifier

For single character keys, the shift modifier should not be used. Use the corresponding upper case character instead. The same applies to the option modifier; if the generated character is a valid unicode character, use that character and drop the option modifier.

The following special keys are recognized:

  • delete or del — Delete function key
  • left — Left arrow key
  • right — Right arrow key
  • up — Up arrow key
  • down — Down arrow key
  • pageup or pgup — Page Up function key
  • pagedown or pgdn — Page Down function key
  • home — Home function key
  • end — End function key
  • insert or ins — Insert function key
  • help — Help function key
  • backspace or bs — Backspace key
  • tab — Tab key
  • escape or esc — Escape key
  • cr, enter or return — Enter key
  • bar| key
  • lt< key
  • backslash or bslash\ key
  • nl — Same as <control-j>
  • ff — Same as <control-l>
  • nul — Null key

Mappings that are limited by a scope selector will only be recognized if the current scope matches the selector. If multiple mappings match the current scope, the scope selector with the highest rank is used. Mappings with an empty scope selector has the lowest possible rank.

Tasks

Other Methods

  •   operatorMap

    Assign a map to be used by operator actions.

    property
  •   acceptsCounts

    If YES, leading digits acts as count to commands. If NO, digits are treated as normal commands.

    property
  •   defaultAction

    If no mapping matches a key sequence, this action is called.

    property

Creating custom maps

Predefined standard maps

Including other maps

Mapping macros

Mapping Nu expressions

Mapping keys to actions

Unmapping keys

Properties

acceptsCounts

If YES, leading digits acts as count to commands. If NO, digits are treated as normal commands.

@property (nonatomic, readwrite) BOOL acceptsCounts

Discussion

acceptsCounts should be disabled for maps in insert mode. Default is YES.

Declared In

ViMap.h

defaultAction

If no mapping matches a key sequence, this action is called.

@property (nonatomic, readwrite) SEL defaultAction

Declared In

ViMap.h

operatorMap

Assign a map to be used by operator actions.

@property (nonatomic, readwrite, assign) ViMap *operatorMap

Declared In

ViMap.h

Class Methods

completionMap

The map used in completion popups.

+ (ViMap *)completionMap

Return Value

The map used in completion popups.

Declared In

ViMap.h

explorerMap

The map used in the file explorer sidebar.

+ (ViMap *)explorerMap

Return Value

The map used in the file explorer sidebar.

Declared In

ViMap.h

insertMap

The map used in insert mode.

+ (ViMap *)insertMap

Return Value

The map used in insert mode.

Declared In

ViMap.h

mapWithName:

Create a new empty map.

+ (ViMap *)mapWithName:(NSString *)mapName

Parameters

mapName

The name of the map.

Return Value

The newly created map. It is initially empty.

Declared In

ViMap.h

normalMap

The map used in normal mode.

+ (ViMap *)normalMap

Return Value

The map used in normal mode.

Declared In

ViMap.h

operatorMap

The map used after an operator command.

+ (ViMap *)operatorMap

Return Value

The map used after an operator command.

Declared In

ViMap.h

symbolMap

The map used in the symbol list sidebar.

+ (ViMap *)symbolMap

Return Value

The map used in the symbol list sidebar.

Declared In

ViMap.h

visualMap

The map used in visual mode.

+ (ViMap *)visualMap

Return Value

The map used in visual mode.

Declared In

ViMap.h

Instance Methods

include:

Add a reference to another map.

- (void)include:(ViMap *)map

Parameters

map

The other map to include in this map.

Discussion

Mappings in an included map can be overridden by mappings in the parent map.

Declared In

ViMap.h

includesMap:

Check if a map is included by another map.

- (BOOL)includesMap:(ViMap *)aMap

Parameters

aMap

The map to check for inclusion.

Return Value

YES if the given map is included by this map.

Declared In

ViMap.h

map:to:

Globally map a key sequence to a macro non-recursively.

- (void)map:(NSString *)keySequence to:(NSString *)macro

Parameters

keySequence

The key sequence to map.

macro

The key sequence that make up the macro.

Declared In

ViMap.h

map:to:recursively:scope:

Map a key sequence to a macro.

- (void)map:(NSString *)keySequence to:(NSString *)macro recursively:(BOOL)recursiveFlag scope:(NSString *)scopeSelector

Parameters

keySequence

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

macro

The key sequence that make up the macro.

recursiveFlag

YES if the macro should be evaluated recursively.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

map:to:scope:

Map a key sequence to a macro non-recursively.

- (void)map:(NSString *)keySequence to:(NSString *)macro scope:(NSString *)scopeSelector

Parameters

keySequence

The key sequence to map.

macro

The key sequence that make up the macro.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

map:toExpression:

Map a key sequence to a Nu expression.

- (void)map:(NSString *)keySequence toExpression:(id)expr

Parameters

keySequence

The key sequence to map.

expr

A Nu anonymous function (do block) with zero arguments. See the Nu documentation.

Discussion

The mapping will be created with global scope, ie no limiting scope selector.

Declared In

ViMap.h

map:toExpression:scope:

Map a key sequence to a Nu expression.

- (void)map:(NSString *)keySequence toExpression:(id)expr scope:(NSString *)scopeSelector

Parameters

keySequence

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

expr

A Nu anonymous function (do block) with zero arguments. See the Nu documentation.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

setKey:toAction:

Map a key sequence to an action.

- (void)setKey:(NSString *)keyDescription toAction:(SEL)selector

Parameters

keyDescription

The key sequence to map.

selector

The selector of the action.

Discussion

This sets flags to 0, parameter to nil and empty scope selector.

Declared In

ViMap.h

setKey:toAction:flags:parameter:scope:

Map a key sequence to an action.

- (void)setKey:(NSString *)keyDescription toAction:(SEL)selector flags:(NSUInteger)flags parameter:(id)param scope:(NSString *)scopeSelector

Parameters

keyDescription

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

selector

The selector of the action.

flags

A combination of flags, or’d together.

param

Any parameter that should be passed to the command.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

setKey:toEditAction:

Map a key sequence to an edit action.

- (void)setKey:(NSString *)keyDescription toEditAction:(SEL)selector

Parameters

keyDescription

The key sequence to map.

selector

The selector of the action.

Discussion

This sets flags to ViMapSetsDot, parameter to nil and an empty scope selector.

Declared In

ViMap.h

setKey:toEditAction:flags:parameter:scope:

Map a key sequence to an edit action.

- (void)setKey:(NSString *)keyDescription toEditAction:(SEL)selector flags:(NSUInteger)flags parameter:(id)param scope:(NSString *)scopeSelector

Parameters

keyDescription

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

selector

The selector of the action.

flags

A combination of flags, or’d together. The ViMapSetsDot flag is always set.

param

Any parameter that should be passed to the command.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

setKey:toMotion:

Map a key sequence to a motion action.

- (void)setKey:(NSString *)keyDescription toMotion:(SEL)selector

Parameters

keyDescription

The key sequence to map.

selector

The selector of the action.

Discussion

This sets flags to ViMapIsMotion, parameter to nil and an empty scope selector.

Declared In

ViMap.h

setKey:toMotion:flags:parameter:scope:

Map a key sequence to a motion action.

- (void)setKey:(NSString *)keyDescription toMotion:(SEL)selector flags:(NSUInteger)flags parameter:(id)param scope:(NSString *)scopeSelector

Parameters

keyDescription

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

selector

The selector of the action.

flags

A combination of flags, or’d together. The ViMapIsMotion flag is always set.

param

Any parameter that should be passed to the command.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

setKey:toOperator:

Map a key sequence to an operator action.

- (void)setKey:(NSString *)keyDescription toOperator:(SEL)selector

Parameters

keyDescription

The key sequence to map.

selector

The selector of the action.

Discussion

This sets flags to ViMapNeedMotion, parameter to nil and an empty scope selector.

Declared In

ViMap.h

setKey:toOperator:flags:parameter:scope:

Map a key sequence to an operator action.

- (void)setKey:(NSString *)keyDescription toOperator:(SEL)selector flags:(NSUInteger)flags parameter:(id)param scope:(NSString *)scopeSelector

Parameters

keyDescription

The key sequence to map. Can include special keys within angle brackets, like <cmd-ctrl-up>.

selector

The selector of the action.

flags

A combination of flags, or’d together. The ViMapNeedMotion flag is always set.

param

Any parameter that should be passed to the command.

scopeSelector

A scope selector limiting where this key sequence is applicable, or nil for no limit.

Declared In

ViMap.h

unmap:

Unmap a key sequence without a limiting scope.

- (void)unmap:(NSString *)keySequence

Parameters

keySequence

The key sequence to unmap.

See Also

Declared In

ViMap.h

unmap:scope:

Unmap a key sequence in a specific scope.

- (void)unmap:(NSString *)keySequence scope:(NSString *)scopeSelector

Parameters

keySequence

The key sequence to unmap.

scopeSelector

A scope selector matching a previously mapped key sequence.

Declared In

ViMap.h