caption: tm-edit-text-operation
created: 20160424211339792
modified: 20240909083525060
tags: Messages
title: WidgetMessage: tm-edit-text-operation
type: text/vnd.tiddlywiki

\define exciseDescription()
<div>

Excises the currently selected text into a new tiddler and replaces it with a link, a macro or a transclude of the new tiddler. Parameters include:

|!Name |!Description |
|title |Title of the new tiddler the selected content is excised to |
|type |Type of the replacement to be inserted: Can be one of <<.value "transclude">>, <<.value "link">> or <<.value "macro">> |
|macro |In case //type=<<.value "macro">>//, specifies the name of the macro to be inserted. The title of the new tiddler is provided as the first parameter to the macro. Defaults to the [[translink macro|translink Macro]] |
|tagnew |If '<<.value "yes">>', will tag the new tiddler with the title of the tiddler currently being edited |

</div>
\end

\define replaceAllDescription()
<div>

Replaces ''all'' contents of the editor with the provided text.

|!Name |!Description |
|text |Text to be inserted |

</div>
\end

\define replaceSelectionDescription()
<div>

Replaces the current selection with the provided text.

|!Name |!Description |
|text |Text to be inserted |

</div>
\end

\define prefixLinesDescription()
<div>

Prefixes the currently selected line//(s)// with the provided character. If a line is already prefixed by the provided prefix, the prefix is removed instead.

|!Name |!Description |
|character |Prefix character |
|count |Number of characters that make up the prefix |

''Example'' Setting //character="<<.value "!">>"// and //count="<<.value "3">>"// would insert the prefix "<<.value "!!!" >>", which will resolve to a subheading when parsed as WikiText.

</div>
\end

\define wrapLinesDescription()
<div>

Surrounds the selected //lines// with the provided <<.param "prefix">> and <<.param "suffix">>.

|!Name |!Description |
|prefix |String to be prefixed to the selected lines |
|suffix |Suffix to be inserted after the selected lines |


</div>
\end


\define wrapSelectionDescription()
<div>

Surrounds the current //selection// with the provided <<.param "prefix">> and <<.param "suffix">>.

|!Name |!Description |
|prefix |String to be prefixed to the selection |
|suffix |Suffix to be inserted after the selection |
|trimSelection |<<.from-version 5.3.6>> Trim leading and trailing white-space from the selection and move it to the surrounding text. Possible values are: `yes`, `no` (default), `start` and `end` |

</div>
\end

\define saveSelectionDescription()
<div>

Saves the text of the current //selection// into the provided <<.param "tiddler">> and <<.param "field">>.

|!Name |!Description |
|tiddler |Tiddler title to which the selection will be saved |
|field |Field name (defaults to "text") |

</div>
\end

\define makeLinkDescription()
<div>

Creates a wiki text link to the tiddler specified in <<.param "text">>. If there is a selection, it is used as the text of the link. 

|!Name |!Description |
|text |Tiddler title to which the link will be created |

</div>
\end

\define insertTextDescription()
<div>

Inserts the text specified in <<.param "text">> at the caret position. If there is a selection, it is replaced. 

|!Name |!Description |
|text |Text to be inserted |

</div>
\end

\define focusEditorDescription() Simply focuses the Text Editor

A `tm-edit-text-operation` invokes one of the available operations on a __surrounding__ text editor. Therefore the message has to be dispatched within the editor in order for it to catch it. The following properties on the `event` object are required:

|!Name |!Description |
|param |Name of the operation to be executed, see ''below'' for a list of possible operations |
|//{any other params}// |Any other parameters are made available as variables within the context of the widget message. |

The `tm-edit-text-operation` message is usually generated by a ButtonWidget or an [[ActionWidget|ActionWidgets]] and is handled by the surrounding text editor.

! Text Operations

At this point the following text operations have been implemented:

|!Name |!Description |
|<<.def "excise">>|<<exciseDescription>> |
|<<.def "replace-all">>|<<replaceAllDescription>> |
|<<.def "replace-selection">>|<<replaceSelectionDescription>> |
|<<.def "prefix-lines">>|<<prefixLinesDescription>> |
|<<.def "wrap-lines">>|<<wrapLinesDescription>> |
|<<.def "wrap-selection">>|<<wrapSelectionDescription>> |
|<<.def "save-selection">>|<<saveSelectionDescription>> |
|<<.def "make-link">>|<<makeLinkDescription>> |
|<<.def "insert-text">>|<<insertTextDescription>> |
|<<.def "focus-editor">>|<<.from-version 5.2.0>> <<focusEditorDescription>> |


! Example

An example can be seen in [[$:/core/ui/EditorToolbar/bold]]:

```
<$action-sendmessage
	$message="tm-edit-text-operation"
	$param="wrap-selection"
	prefix="''"
	suffix="''"
	trimSelection="yes"
/>
```