-
Notifications
You must be signed in to change notification settings - Fork 841
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Feat: customizable character and space shortcut events (#2228)
* Added character shortcut events class * Feat: support for character and space shortcut events * Chore: added new gif video url * Chore: improve and fix some parts of the new section in the README.md * Merge from master * Fix: typo in comment into the Shortcut event section * chore: add a message for validating an assert in handleFormatByWrappingWithSingleCharacter() * chore: fix analysis warning * Chore: moved shortcut docs to its own file * Chore: changed editor without shortcut gif url * Chore: added description to asserts * Chore: removed unnecessary default cases in format functions * Fix: characterShortcutEvents param in raw configs is showing as it is deprecated * Chore: dart format * Chore: fixed some comments that references double chars instead single chars * Fix: typo * Chore: improved doc comments on format functions * Chore: dart format --------- Co-authored-by: CatHood0 <[email protected]> Co-authored-by: Ellet <[email protected]>
- Loading branch information
3 people
authored
Sep 15, 2024
1 parent
164c183
commit 289139b
Showing
19 changed files
with
807 additions
and
46 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| # Shortcut events | ||
|
|
||
| We will use a simple example to illustrate how to quickly add a `CharacterShortcutEvent` event. | ||
|
|
||
| In this example, text that starts and ends with an asterisk ( * ) character will be rendered in italics for emphasis. So typing `*xxx*` will automatically be converted into _`xxx`_. | ||
|
|
||
| Let's start with a empty document: | ||
|
|
||
| ```dart | ||
| import 'package:flutter_quill/flutter_quill.dart'; | ||
| import 'package:flutter/material.dart'; | ||
| class AsteriskToItalicStyle extends StatelessWidget { | ||
| const AsteriskToItalicStyle({super.key}); | ||
| @override | ||
| Widget build(BuildContext context) { | ||
| return QuillEditor( | ||
| scrollController: <your_scrollController>, | ||
| focusNode: <your_focusNode>, | ||
| controller: <your_controller>, | ||
| configurations: QuillEditorConfigurations( | ||
| characterShortcutEvents: [], | ||
| ), | ||
| ); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| At this point, nothing magic will happen after typing `*xxx*`. | ||
|
|
||
| <p align="center"> | ||
| <img src="https://github.com/user-attachments/assets/c9ab15ec-2ada-4a84-96e8-55e6145e7925" width="800px" alt="Editor without shortcuts gif"> | ||
| </p> | ||
|
|
||
| To implement our shortcut event we will create a `CharacterShortcutEvent` instance to handle an asterisk input. | ||
|
|
||
| We need to define key and character in a `CharacterShortcutEvent` object to customize hotkeys. We recommend using the description of your event as a key. For example, if the asterisk `*` is defined to make text italic, the key can be 'Asterisk to italic'. | ||
|
|
||
| ```dart | ||
| import 'package:flutter_quill/flutter_quill.dart'; | ||
| import 'package:flutter/material.dart'; | ||
| // [handleFormatByWrappingWithSingleCharacter] is a example function that contains | ||
| // the necessary logic to replace asterisk characters and apply correctly the | ||
| // style to the text around them | ||
| enum SingleCharacterFormatStyle { | ||
| code, | ||
| italic, | ||
| strikethrough, | ||
| } | ||
| CharacterShortcutEvent asteriskToItalicStyleEvent = CharacterShortcutEvent( | ||
| key: 'Asterisk to italic', | ||
| character: '*', | ||
| handler: (QuillController controller) => handleFormatByWrappingWithSingleCharacter( | ||
| controller: controller, | ||
| character: '*', | ||
| formatStyle: SingleCharacterFormatStyle.italic, | ||
| ), | ||
| ); | ||
| ``` | ||
|
|
||
| Now our 'asterisk handler' function is done and the only task left is to inject it into the `QuillEditorConfigurations`. | ||
|
|
||
| ```dart | ||
| import 'package:flutter_quill/flutter_quill.dart'; | ||
| import 'package:flutter/material.dart'; | ||
| class AsteriskToItalicStyle extends StatelessWidget { | ||
| const AsteriskToItalicStyle({super.key}); | ||
| @override | ||
| Widget build(BuildContext context) { | ||
| return QuillEditor( | ||
| scrollController: <your_scrollController>, | ||
| focusNode: <your_focusNode>, | ||
| controller: <your_controller>, | ||
| configurations: QuillEditorConfigurations( | ||
| characterShortcutEvents: [ | ||
| asteriskToItalicStyleEvent, | ||
| ], | ||
| ), | ||
| ); | ||
| } | ||
| } | ||
| CharacterShortcutEvent asteriskToItalicStyleEvent = CharacterShortcutEvent( | ||
| key: 'Asterisk to italic', | ||
| character: '*', | ||
| handler: (QuillController controller) => handleFormatByWrappingWithSingleCharacter( | ||
| controller: controller, | ||
| character: '*', | ||
| formatStyle: SingleCharacterFormatStyle.italic, | ||
| ), | ||
| ); | ||
| ``` | ||
| <p align="center"> | ||
| <img src="https://github.com/user-attachments/assets/35e74cbf-1bd8-462d-bb90-50d712012c90" width="800px" alt="Editor with shortcuts gif"> | ||
| </p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
45 changes: 45 additions & 0 deletions
45
lib/src/editor/raw_editor/config/events/character_shortcuts_events.dart
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| import 'package:equatable/equatable.dart'; | ||
| import 'package:meta/meta.dart'; | ||
|
|
||
| import '../../../../../flutter_quill.dart'; | ||
|
|
||
| typedef CharacterShortcutEventHandler = bool Function( | ||
| QuillController controller); | ||
|
|
||
| /// Defines the implementation of shortcut event based on character. | ||
| @immutable | ||
| class CharacterShortcutEvent extends Equatable { | ||
| const CharacterShortcutEvent({ | ||
| required this.key, | ||
| required this.character, | ||
| required this.handler, | ||
| }) : assert(character.length == 1 && character != '\n', | ||
| 'character cannot be major than one char, and it must not be a new line'); | ||
|
|
||
| final String key; | ||
| final String character; | ||
| final CharacterShortcutEventHandler handler; | ||
|
|
||
| bool execute(QuillController controller) { | ||
| return handler(controller); | ||
| } | ||
|
|
||
| CharacterShortcutEvent copyWith({ | ||
| String? key, | ||
| String? character, | ||
| CharacterShortcutEventHandler? handler, | ||
| }) { | ||
| return CharacterShortcutEvent( | ||
| key: key ?? this.key, | ||
| character: character ?? this.character, | ||
| handler: handler ?? this.handler, | ||
| ); | ||
| } | ||
|
|
||
| @override | ||
| String toString() => | ||
| 'CharacterShortcutEvent(key: $key, character: $character, handler: $handler)'; | ||
|
|
||
| @override | ||
| List<Object?> get props => [key, character, handler]; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| // event classes | ||
| export 'character_shortcuts_events.dart'; | ||
| export 'space_shortcut_events.dart'; | ||
| // default implementation of the shortcuts | ||
| export 'standard_char_shortcuts/block_shortcut_events_handlers.dart'; | ||
| export 'standard_char_shortcuts/double_character_shortcut_events.dart'; | ||
| export 'standard_char_shortcuts/single_character_shortcut_events.dart'; | ||
| // all available shortcuts | ||
| export 'standard_char_shortcuts/standard_shortcut_events.dart'; |
Oops, something went wrong.