Skip to main content

​
Overview

CharacterShortcutEvent defines the implementation of shortcut events based on character input. These events are triggered when users type specific characters, enabling features like markdown shortcuts and formatting.

​
Constructor

CharacterShortcutEvent({
  required String key,
  required String character,
  required CharacterShortcutEventHandler handler,
  CharacterShortcutEventHandlerWithCharacter? handlerWithCharacter,
  RegExp? regExp,
})

​
Parameters

​
key
String
required
The unique key for the shortcut event. Usually uses the description as the key.Example: 'format sign to heading list'
​
character
String
required
The character to trigger the shortcut event. Must be a single character when regExp is null, or empty string when regExp is provided.Example: ' ' (space), '*', '/'
​
handler
CharacterShortcutEventHandler
required
The handler function to execute when the shortcut is triggered.Type signature:
typedef CharacterShortcutEventHandler = Future<bool> Function(
  EditorState editorState,
);
Returns true if the event was handled, false otherwise.
​
handlerWithCharacter
CharacterShortcutEventHandlerWithCharacter
Optional handler that receives the character as a parameter.Type signature:
typedef CharacterShortcutEventHandlerWithCharacter = Future<bool> Function(
  EditorState editorState,
  String character,
);
​
regExp
RegExp
Optional regular expression to match characters. When provided, character must be empty. Only matches a single character.

​
Properties

​
key

final String key
The unique identifier for this shortcut event.

​
character

String character
The trigger character. Can be updated using updateCharacter().

​
regExp

RegExp? regExp
Optional regex pattern for matching characters.

​
handler

final CharacterShortcutEventHandler handler
The function that handles the shortcut event.

​
handlerWithCharacter

final CharacterShortcutEventHandlerWithCharacter? handlerWithCharacter
Optional handler that receives the character.

​
Methods

​
execute()

Future<bool> execute(EditorState editorState)
Executes the shortcut event handler. Returns: true if handled, false otherwise.

​
executeWithCharacter()

Future<bool> executeWithCharacter(
  EditorState editorState,
  String character,
)
Executes the handler with the character parameter if available, otherwise falls back to the standard handler. Parameters:
  • editorState - The current editor state
  • character - The character that triggered the event
Returns: true if handled, false otherwise.

​
updateCharacter()

void updateCharacter(String newCharacter)
Updates the trigger character. The new character must be a single character. Parameters:
  • newCharacter - The new trigger character (must be length 1)

​
copyWith()

CharacterShortcutEvent copyWith({
  String? key,
  String? character,
  CharacterShortcutEventHandler? handler,
  RegExp? regExp,
})
Creates a copy of this event with updated properties.

​
Examples

​
Format to Heading

Convert # characters followed by space to heading blocks: 
CharacterShortcutEvent formatSignToHeading = CharacterShortcutEvent(
  key: 'format sign to heading list',
  character: ' ',
  handler: (editorState) async => await formatMarkdownSymbol(
    editorState,
    (node) => true,
    (_, text, selection) {
      final characters = text.split('');
      // only supports heading1 to heading6 levels
      return characters.isNotEmpty &&
          characters.every((element) => element == '#') &&
          characters.length < 7;
    },
    (text, node, delta) {
      final numberOfSign = text.split('').length;
      return [
        headingNode(
          level: numberOfSign,
          delta: delta.compose(Delta()..delete(numberOfSign)),
        ),
        if (node.children.isNotEmpty) ...node.children,
      ];
    },
  ),
);

​
Format to Bold

Format text surrounded by double asterisks to bold: 
final CharacterShortcutEvent formatDoubleAsterisksToBold =
    CharacterShortcutEvent(
  key: 'format the text surrounded by double asterisks to bold',
  character: '*',
  handler: (editorState) async => handleFormatByWrappingWithDoubleCharacter(
    editorState: editorState,
    character: '*',
    formatStyle: DoubleCharacterFormatStyle.bold,
  ),
);

​
Slash Command

Show the slash menu when / is typed: 
final CharacterShortcutEvent slashCommand = CharacterShortcutEvent(
  key: 'show the slash menu',
  character: '/',
  handler: (editorState) async => await _showSlashMenu(
    editorState,
    standardSelectionMenuItems,
  ),
);

​
Insert New Line

Insert a new block after a heading: 
CharacterShortcutEvent insertNewLineAfterHeading = CharacterShortcutEvent(
  key: 'insert new block after heading',
  character: '\n',
  handler: (editorState) async {
    final selection = editorState.selection;
    if (selection == null ||
        !selection.isCollapsed ||
        selection.startIndex != 0) {
      return false;
    }
    final node = editorState.getNodeAtPath(selection.end.path);
    if (node == null || node.type != HeadingBlockKeys.type) {
      return false;
    }
    final transaction = editorState.transaction;
    transaction.insertNode(selection.start.path, paragraphNode());
    transaction.afterSelection = Selection.collapsed(
      Position(path: selection.start.path.next, offset: 0),
    );
    await editorState.apply(transaction);
    return true;
  },
);

​
Usage

To use character shortcut events in your editor: 
import 'package:appflowy_editor/appflowy_editor.dart';

final editor = AppFlowyEditor(
  editorState: editorState,
  characterShortcutEvents: [
    formatSignToHeading,
    formatDoubleAsterisksToBold,
    slashCommand,
    insertNewLineAfterHeading,
    // Add more character shortcuts...
  ],
);

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us