MarkdownComposer

Represents a control where you can write and edit a markdown text, with the formatting applied while you type:

To create a markdown composer use MarkdownComposer::new method (with 2 parameters: a layout and initialization flags) or MarkdownComposer::from method (with 3 parameters: a text, a layout and initialization flags).

let mc1 = MarkdownComposer::new(layout!("x:1,y:1,w:40,h:10"), markdown_composer::Flags::None);
let mc2 = MarkdownComposer::from("**Hello** world", layout!("d:f"), markdown_composer::Flags::ShowMarkers);

or the macro markdown_composer!

let mc1 = markdown_composer!("x:1,y:1,w:40,h:10");
let mc2 = markdown_composer!("'**Hello** world',d:f,flags:ShowMarkers");

A markdown composer supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A markdown composer supports the following initialization flags:

• markdown_composer::Flags::ShowMarkers or ShowMarkers (for macro initialization) - by default the markdown markers (**, _, `, ```) are hidden and only their effect is visible. If this flag is being used, the raw text is displayed instead, markers included.
• markdown_composer::Flags::Emoticons or Emoticons (for macro initialization) - if set, a text emoticon or an emoji name written between colons is replaced with the corresponding emoji while typing (:B): becomes 😎, :smile: becomes 😀), as described in the Emoticons section.
• markdown_composer::Flags::ReadOnly or ReadOnly (for macro initialization) - this will allow you to view, select and copy the text but not to modify it.

Some examples that uses these paramateres:

1. A markdown composer that shows the raw markers and can not be modified.

   let mc = markdown_composer!("'A **bold** word',x:1,y:1,w:40,h:6,flags:ShowMarkers+ReadOnly");
   

2. A markdown composer that replaces emoticons while typing and has an emoji list opened by :.

   let mc = markdown_composer!("d:f,flags:Emoticons,emoji:':'");
   

3. A markdown composer with a list of names opened by @ and a list of labels opened by #.

   let mc = markdown_composer!("
       d:f,
       lists:[
           {'@',items:['Ana','Bogdan','Cristina'],flags:RemoveTrigger},
           {trigger:'#',values:[{bug,'🐛'},{todo,'📝'}]}
       ]");
   

Events

To intercept events from a markdown composer, the following trait has to be implemented to the Window that processes the event loop:

pub trait MarkdownComposerEvents {
    fn on_validate(&mut self, handle: Handle<MarkdownComposer>, text: &str) -> EventProcessStatus {...}
    fn on_text_changed(&mut self, handle: Handle<MarkdownComposer>) -> EventProcessStatus {...}
}

The on_validate(...) method is called when Ctrl+Enter is pressed and it receives the entire markdown text. The on_text_changed(...) method is called after every modification made by the user. Changes made from code (such as set_text(...)) do not raise this event.

Methods

Besides the Common methods for all Controls a markdown composer also has the following additional methods:

Key association

The following keys are processed by a markdown composer control if it has focus:

Additionally, all printable characters can be used to insert / modify or edit the current text.

Deleting a selection keeps the markdown valid: a marker that remains without its pair is removed as well, so a text such as a **bold** b can never become a **bold b.

When a suggestion list is opened, the following keys are processed by that list:

All the other keys are processed by the control itself, so Home, End, Left and Right move the cursor and close the list. The list is also closed when no item matches the typed text, or when the trigger character is deleted.

Mouse actions

Markdown syntax

The following elements are parsed and displayed:

When the ShowMarkers flag is not present, the markers themselves have no width: the cursor moves over them in one step and a selection can never start or end in the middle of a marker. Copying such a selection rebuilds a valid markdown text, so selecting only bold from **bold** puts **bold** in the clipboard.

Suggestion lists

A suggestion list is opened by a trigger character typed at the begining of a word. While the list is opened, the text written after the trigger filters the items, ignoring the case. Choosing an item replaces the trigger and the typed text with the value of that item.

A list can be added from code with add_list(...), add_list_with_values(...) and add_emoji_list(...), or from the macro with the lists and emoji parameters. Every entry of the lists parameter accepts the following parameters:

A suggestion list supports the following flags:

• markdown_composer::ListFlags::RemoveTrigger or RemoveTrigger (for macro initialization) - the trigger character is removed when an item is inserted. Without this flag, @ followed by Ana becomes @Ana; with it, the result is just Ana.

The items of a list can also be changed while the application runs, through list_mut(...):

if let Some(list) = mc.list_mut('@') {
    list.add("Bogdan");
    list.add_value("me", "@covita");
    list.remove(0);
    list.set_flags(markdown_composer::ListFlags::RemoveTrigger);
}

Emoticons

If the Emoticons flag is present, a code written between two colons is replaced with an emoji as soon as the second colon is typed. Both text emoticons and emoji names are accepted:

The replacement is not applied inside a code block or an inline code, and the first colon has to be preceded by a space or by the begining of a line, so a text such as 10:30: is left untouched.

Example

The following code creates a small message editor: the names are suggested by @, the emoji by :, and Ctrl+Enter sends the message and empties the composer.

use appcui::prelude::*;

#[Window(events = MarkdownComposerEvents)]
struct MyWin {
    composer: Handle<MarkdownComposer>,
    sent: Handle<Label>,
}

impl MyWin {
    fn new() -> Self {
        let mut w = Self {
            base: window!("'Message editor',a:c,w:60,h:14,flags:Sizeable"),
            composer: Handle::None,
            sent: Handle::None,
        };
        w.sent = w.add(label!("'Nothing was sent yet',x:1,y:1,w:56,h:1"));
        w.composer = w.add(markdown_composer!("
            'Write **here** and press Ctrl+Enter',
            x:1,y:3,w:56,h:8,
            flags:Emoticons,
            emoji:':',
            lists:[{'@',items:['Ana','Bogdan','Cristina'],flags:RemoveTrigger}]"));
        w
    }
}

impl MarkdownComposerEvents for MyWin {
    fn on_validate(&mut self, handle: Handle<MarkdownComposer>, text: &str) -> EventProcessStatus {
        let message = format!("Sent: {} characters", text.len());
        let label = self.sent;
        if let Some(label) = self.control_mut(label) {
            label.set_caption(&message);
        }
        if let Some(composer) = self.control_mut(handle) {
            composer.set_text("");
        }
        EventProcessStatus::Processed
    }
}

fn main() -> Result<(), appcui::system::Error> {
    App::new().window(MyWin::new).run()
}