User manual

Automation Protocol Easytext Commands
Miranda Technologies Ltd Page 216
The Z0 command is the basis for all text updates.
All Easytext commands take a ‘layer’ parameter, defining whether the
midground (preview) or foreground (program) image is being modified.
In addition, many commands refer to a specific box on the template. Box
numbers can range from 0 to 254 (0xFE). Box 255 (0xFF) is treated as a
special case by some commands.
International Character Set Support
Easytext uses Unicode rather than ASCII to represent characters. Unlike
ASCII, which is limited in its scope to common western characters, Unicode
is a character-encoding standard that encapsulates all the major scripts used
throughout the world. Unicode characters are typically represented with
either 16 or 32-bit codes, rather than the 8 bits of ASCII.
To transfer Unicode data into Easytext, a format known as UTF-8 must be
used, which encodes each Unicode code into a sequence of one or more 8-bit
values. For common Latin characters there is a one-to-one mapping between
UTF-8 and standard ASCII. The UTF-8 code for these characters is a single
byte. Codes for other characters can vary in length between 2 and 4 bytes. In
the case of the Easytext automation command ‘Update Text Field’, it is
therefore valid to use:
remote_send("Z0%01x%02x%x%s", Layer, BoxNo,
Render, "Hello World");
However when characters outside the standard 7-bit set are required
(including special European and accented characters) the text must be
converted to the UTF-8 format. Routines to perform this conversion can be
found by searching on the Internet.
After the encoding to UTF-8, the byte-stream must be processed in the same
way as filenames and titles, to replace protocol-specific control codes with
alternative coding. See the section on loading and saving normal images by
filename for details of this conversion.