Zones

Zones are marked areas of a line that has been output by Consoul. They are defined by inserting special zone beginning (ZONE_BEGIN) and ending (ZONE_END) escape sequences in the output flow, like any other supported escape sequences.

However, while setting a graphic rendition property like bold (BOLD_ON) may persist on the following lines until it is switched off (BOLD_OFF) or colors and attributes are reset (RESET), zones cannot span multiple lines. Consoul assumes that all non closed zones finish at the end of their output line. In other words, zones can begin anywhere in a line, they can overlap, but they end on the line they begin, even if there's no closing escape sequence for that zone.

Zones can overlap. For instance, zone 1 can be defined at the beginning of a line, followed by a text block of 10 characters. Zone 2 can begin after that, output a text block of 10 more characters, and the closing escape sequence for zone 1 can follow, leaving zone 2 open till the end of the line.

Consoul will not check the uniqueness of the zone id on a line. Using the same zone id multiple times on the same line will not confuse Consoul, but the related API functions (CSGetZoneText, CSGetZoneTag, CSReplaceZone) will be, and they will operate only on the first defined zone with the specified zone id.

Interactivity

By default, Consoul changes the mouse cursor to a pointing hand, when it enters a zone. Consoul also sends a message (or call the appropriate callback function) when the mouse cursor enters or leaves a zone, if the mouse tracking mode is ON (CSSetTrackZones). This can be used to either suppress the visual effect of the cursor entering a zone with a call like CSSetHoverCursor(hWnd, GetMouseCursor(hWnd)), or au contraire, to enhance it by changing the mouse cursor to a different one depending on the zone ID.

The CSReplaceZone can change a zone content on the fly. Coupling this function call with the mouse entering the zone event, can be used further used to enhance the user visual feedback, like replacing the zone content with the same content, wrapped with INVERSE_ON/INVERSE_OFF sequences, then stripping these escape sequences back off when the mouse cursor leaves the zone.