The HOOPS Kanji package includes extra data files that represent Kanji characters. This data is accessed via calls to Insert_Text. Kanji functionality must be unlocked before Kanji characters are inserted using Insert_Text. The functionality is unlocked by supplying a key with the license option of Define_System_Options.
PURPOSE
Define_System_Options is part of the classic HOOPS product---HOOPS Kanji relies on being activated with the license option. It is also used to locate the Kanji font files.
CALLING SEQUENCE
Define_System_Options (list)
----------------------------------------------------------------------------- list string A quoted string or a string variable containing a list of the desired option settings. -----------------------------------------------------------------------------
DETAILS
"System options" are a group of status settings that don't have anything directly to do with graphics; They control how the system reacts to some error and debugging situations. "System options" are defined system-wide. They are not a part of the graphics segment tree.
license = (customer = customer, product = (Kanji [, AIR] [, IM]), key = key)
The license system option is used to enable one or more optional HOOPS products. The license option requires a numeric key obtained from Tech Soft 3D Sales. As one would expect, an application cannot activate an optional product for which it is not entitled. However, it is not required that an application activate ALL of the optional products for which it is entitled. In other words, using a supplied numeric key, only the products requested in the product list are activated. For programming convenience, the license option can be specified by the HOOPS_LICENSE environment variable; however, for shipping applications, a programmatic call to Define_System_Options is desirable.
[no] font directory = `pathlist'
This option specifies a comma separated list of directories where font information is stored. HOOPS will search each of the specified directories for font files that end with specific "known" suffixes. For Kanji fonts, the HSF (HOOPS Stroked Font) suffix is used.
Note that normally you will need to surround your directory list string with either single or double quotation marks to prevent HOOPS from interpreting any special characters within. The default is "no font directory".
NOTES
For HOOPS Kanji, there is a special system option to enable access to the Kanji character data. Enabling the optional HOOPS Kanji product requires a licensing agreement with Tech Soft 3D Sales. For example:
Define_System_Options("license = (customer = ABC, product = Kanji, key = 1E345), font directory = `/usr/include/myfonts'");
To obtain a company specific key to enable HOOPS Kanji functionality, please contact Tech Soft 3D Technical Support. Chapter 3 of the HOOPS Installation Guide identifies various methods of contact.
SEE ALSO
Define_Callback_Name, HIC_routines, Set_Callback.
PURPOSE
Puts lettering into the current segment, and thence into the picture.
CALLING SEQUENCE
Insert_Text (x, y, z, text)
-------------------------------------------------------------------------------------- x, y, z float Position, in user coordinates, of the "reference point" of the text. text string Characters to be rendered. --------------------------------------------------------------------------------------
VARIANTS
KInsert_Text (x, y, z, text), returns key
QInsert_Text (segment, x, y, z, text)
QKInsert_Text (segment, x, y, z, text), returns key
Insert_Text_With_Encoding (x, y, z, encoding, text)
KInsert_Text_With_Encoding (x, y, z, encoding, text), returns key
QInsert_Text_With_Encoding (segment, x, y, z, encoding, text)
QKInsert_Text_With_Encoding (segment, x, y, z, encoding, text), returns key
------------------------------------------------------------------------------- x, y, z float As above. text string As above. key HC_KEY Unique numeric identifier for this particular text string. Returned to caller. segment string Segment(s) to be inserted into, if other than the currently- open segment. encoding string Constant indicating the encoding method used in text. See below for details. -------------------------------------------------------------------------------
DETAILS
The specified string of characters, subject to the various text attributes, will be drawn at the specified location in your data space.
The "reference point" of the text works with Text Alignment, Text Spacing, Text Path, and text transformations to determine where the characters actually land. If the Text Alignment is set to Center-Center, for example, the system arranges your string so that the middle of the group of characters will land where your x-y-z has specified.
When text is transformed (Scale_Object, Roll_Camera ...;), the characters may or may not react completely, depending on the font in use. In the default case the reference point is always transformed properly but the characters will continue to "face front" no matter what. If you want your text to react fully to geometrical transformations, you need to turn on "text transforms"---see Set_Text_Font for details.
By default, HOOPS uses the "ISO Latin One" collating sequence for the characters, (except in Japan---see below). These characters as they occur in the built-in stroked font are shown in Table 4.1. Character values above 127 can be embedded in your source C character strings with "compose-key" sequences from your keyboard or with the standard C backslash-octal-number notation. From Fortran you can use the compose key or the CHAR function.
You can use Insert_Text_With_Encoding to gain access to character sets other than "ISO Latin One". The following choices are recognized for encoding:
ISO Latin
See the description of Insert_Text in Classic Routines.
ISO Latin One
See the description of Insert_Text in Classic Routines.
JEC
The Japanese Electronic Code for the JIS (Japanese Industry Standards) X0208 (formerly C6226) character set that includes characters for Kanji, Katakana, and Hiragana, plus various European characters. Also known as "Shift-JIS". JEC in HOOPS is encoded in a way similar to ISO Latin as a mixture of 8-bit and 16-bit characters.
Text is expected to be an array of bytes. Walking through the array, if a byte has the value of decimal 129 through 159 or 224 through 239 then a 16-bit JEC value is assumed and another byte must follow: the first byte becomes the high-order part of the number and the second byte is the low-order part. Otherwise the byte is taken as its ISO Latin One equivalent and no second byte will be expected.
Thus the four characters 65-66-33089-36769 (two ISO characters and two JIS characters, hex 41-42-8141-8FA1) could be written in C as "AB\x81A\x8F\xA1", although stylistically it would probably be safer to say "AB\201\101\217\241".
In Fortran, the same example would be
'AB'//char(129)//char(65)//char(143)//char(161).
EUC
The "Extended Unix Code". Characters with a "0" in the high bit are mapped to U.S. Ascii (which is the first half of ISO Latin One). Characters with a "1" in the high bit (except SS2 (hex 8E) and SS3 (hex 8F)) assume that another byte with the high bit on follows. The high bits are turned off to give the same characters as "Old JIS", "New JIS", and "NEC code" encoding: the two bytes together give a 16-bit value. The 16-bit value is mapped through to a 16-bit Shift-JIS character.
In EUC, an SS2 character introduces a "half-size Katakana" (JIS X0201, formerly C6220) character; SS3 introduces a general Gaija or user-defined character. Neither SS2 or SS3 character sequences are supported in HOOPS; if they appear in the input a warning will be given.
16
See the description of Insert_Text in Classic Routines.
In real life encoded characters will often be conveniently handled as arrays of 16-bit integers, rather than in the above packed-byte format. You can use Compute_Text_From_Text16 and Compute_Text16_From_Text to make the necessary conversions.
NOTES
For compatibility with previous versions of HOOPS, copies of HOOPS sold in Japan have the default character encoding used by Insert_Text, Show_Text, etc., set to "JEC" rather than "ISO Latin One". For compatibility with international versions of HOOPS you may wish to specify the encoding you expect.
If a text string encounters the edge of a Window, with certain fonts on some displays whole characters will be snipped off as they touch the edge. On most fonts and displays the characters will go "over the edge" gradually. And in a few fonts or on a few displays the whole string may disappear when any part touches the edge.
If there is an error the KInsert routine will return a -1.
Any reference in your program to Insert_Text_With_Encoding will cause the Kanji font data to be linked in. This may noticeably increase the size of your executable image.
RESTRICTIONS
The set of provided Kanji characters in HOOPS is known to be a subset of the Kanji characters that comprise the language.
SEE ALSO
Edit_Text, Scroll_Text, Set_Text_Font, Set_Text_Alignment, Set_Text_Spacing, Set_Text_Path, Set_Visibility, KInsert_String_Cursor, Enable_String_Events, Show_String, Show_String_With_Encoding, Compute_Text_From_Text16, Renumber_Key.