# Escape sequences and clickable links

The KVIrc view widgets support clickable links.
The links can be created using special escape sequences in the text passed to the echo command.
KVIrc uses some escape sequences in the text "echoed" internally.
The simplest way to explain it is to use an example:

        echo This is a $cr![!dbl]echo You have clicked it!$cr\clickable link$cr !

The example above will show the following text line: "This is a clickable link". If you move the mouse over the words "clickable link", you will see the text highlighted.
Once you double-click one of that words, the command "echo You have clicked it!" will be executed.
The format looks complex ?... it is not...just read on.
<cr>!<link_type><cr><visible text><cr> <cr>!<escape_command><cr><visible text><cr>

Escape format

The whole escape sequence format is the following:
<cr>!<escape_command><cr><visible text><cr>
<cr> is the carriage return character. You can obtain it by using the [fnc]]$cr[/fnc] function.
<visible text> is the text that will appear as "link" when you move the mouse over it.
<escape_command> is the description of the actions to be taken when the user interacts with the link.
<escape_command> has the two following syntactic forms:
<escape_command> ::= <user_defined_commands>
<escape_command> ::= <builtin_link_description>

User defined links

The user defined links allow you to perform arbitrary commands when the user interacts with the link.
The commands are specified in the <escape_command> part by using the following syntax:
<escape_command> ::= <user_defined_commands>
<user_defined_commands> ::= <command_rule> [<user_defined_commands>]
<command_rule> ::= <action_tag><command>
<action_tag> ::= "[!" <action> "]"
<action> ::= "rbt" | "mbt" | "dbl" | "txt"
<command> ::= any kvirc command (see notes below)

Builtin links

The builtin links have builtin actions performed when the user interact with the link.
These links are used internally in KVIrc , but you can use them too.
The <escape_command> is a single letter this time: it defines the type of the link.
Currently KVIrc uses six types of builtin links : 'n' for nickname links, 'u' for url links, 'c' for channel links, 'h' for hostname links, 'm' for mask links and 's' for server links.
Theoretically you can also use your own link types: just use any other letter or digit (you can't use ']' and <cr>), but probably you will prefer a completely user defined link in that case anyway.
Once the user interacts with the link , kvirc executes the predefined events:
On right-click the event OnBuiltinLinkRightClicked is triggered: the first parameter is the link type, the second parameter is the <visible text> (as a single parameter!!!)
On middle-click the event OnBuiltinLinkMiddleClicked is triggered: the parameters are similar to the previous one.
In the same way you have OnBuiltinLinkDoubleClicked.

A shortcut
You may have a look at the $fmtlink function: it does automatically some of the job explained in this document.

Index, Miscellaneous

KVIrc 4.0.2.4740 Documentation
Generated by root at Tue Feb 1 06:16:04 2011