====== Mouse-Enable your Synchronet BBS ======
The Synchronet [[server:Terminal]] Server (v3.18a and later) supports XTerm-compatible and SyncTERM-compatible mouse reporting:
  * Protocol: X10 compatibility mode (''ESC[?9h'')
  * Encoding: SGR extended coordinates (''ESC[?1006h'')

Some modules (e.g. Deuce's Lightbar command shell, Synchronet Minesweeper) may manually enable and capture mouse events. However, for the most part, mouse-enablement is achieved by utilizing special codes/sequences to define mouse "hot-spots" in display strings and files. In Synchronet v3.20, mouse hot-spot support may be disabled by the sysop by setting [[util:SCFG]]->System->Toggles->Mouse Hot-spots in Menus/Prompts to "No".

===== Hot-spots =====

Hot-spots are rectangular areas (regions) of the terminal screen that when clicked with the left-mouse button will cause the terminal server to inject one or more characters into the keyboard input buffer. Typically, the text displayed in a hot-spot (e.g. an ASCII character representing a command key for a menu) will be the same text that is sent in response to a click of the hot-spot, but that does not always have to be the case. Hot-spot regions can be defined that occupy multiple screen columns but a single hot-spot region cannot occupy more than one screen row.

There are 2 types of hot-spots:
  * Hungry hot-spots
  * Strict hot-spots

Hungy and Strict hot-spots can be combined on the same terminal screen and even the same screen row.

Hot-spot regions may overlap. The most recently defined hot-spots (e.g. further to the right on a row or further down in a file) have priority over earlier defined hot-spots.

==== Hungry Hot-spots ====
Hungry hot-spots are hot-spots that can be triggered when clicking outside of the defined hot-spot dimensions. Hungry hot-spots enable the BBS user to click on a word or even a line rather than a single character to invoke a desired action. Hungry hot-spots are the default and preferred hot-spot type.

==== Strict Hot-spots ====
Strict hot-spots are hot-spots that will only be trigger when a BBS user clicks their mouse within the strictly-defined dimensions of the hot-spot.

==== Create ==== 

There are 4 ways to create mouse hot-spots:
  * [[custom:Mnemonics]]
  * [[custom:ctrl-A codes|Attribute (Ctrl-A) codes]]
  * [[custom:atcodes|Message Variables (@-codes)]]
  * [[custom:javascript|JavaScript]] methods: ''console.add_hotspot()'' and ''console.uselect()''

=== Mnemonics ===
Mnemonics are strings (e.g. from the ''[[custom:text.dat]]'' file) that may contain special characters to denote command-keys:
  * ''~'' precedes a command-key and creates a hungry hot-spot (if preceding a control character or end of line, the command key is a CR)
  * ''`'' precedes a command-key and creates a strict hot-spot that consists of the single command-key

Mnemonic strings are mainly interpreted and displayed by the SBBS C/C++ methods but may also be displayed with the JavaScript ''console.mnemonics()'' method or the [[util:Baja]] ''MNEMONICS'' function.

=== Attribute Codes ===
So-called [[custom:Ctrl-A Codes]] can be used to create single-character hot-spots in virtually all text strings and files:
  * ''^A~'' precedes a command-key and creates a hungry hot-spot (if preceding a control character or end of line, the command key is a CR)
  * ''^A`'' precedes a command-key and creates a strict hot-spot that consists of the single command-key

=== Message Variables ===
Message variables can be a convenient way to create hot-spots in display files (e.g. [[custom:menu files]]), especially when using [[resource:ANSI editors]].
  * ''@HOT@'' defines the implicit attribute (current color) that is used to identify mouse hot-spots
  * ''@HOT://attr//@'' define the explicit attribute (using attribute mnemonics) to identify mouse hot-spots
  * ''@HOT:HUNGRY@'' subsequently created hot-spots will be "hungry hot-spots" (the default)
  * ''@HOT:STRICT@'' subsequently created hot-spots will be "strict hot-spots"
  * ''@HOT:OFF@'' disable hot-spot by attribute definitions
  * ''@~//text//@'' create a hungry hot-spot
  * ''@~//text~cmd//@'' create a hungry hot-spot with an alternate command string (may use C-style character literal escaping)
  * ''@`//text//@'' create a strict hot-spot  * 
  * ''@`//text`cmd//@'' create a strict hot-spot with an alternate command string (may use C-style character literal escaping)

=== JavaScript ===
FIXME

==== Destroy ==== 

There are 2 ways to destroy mouse hot-spots:
  * Message Variable: ''[[custom:atcodes|@CLEAR_HOT@]]''
  * JavaScript method: ''[[custom:javascript|console.clear_hotspots()]]''

Any //clear-screen// operation will also clear any/all mouse hot-spots.


===== See Also =====
  * [[:howto:|howto index]]
  * [[https://www.youtube.com/watch?v=qjX-NbsKZ-0|Demonstration/tutorial video]]

{{tag>mouse terminal syncterm xterm}}