Insert_Text

Functions

HC_KEY DInsert_Text (double x, double y, double z, const char *text)
 Similar to Insert_Text(), but accepts parameters of type double for increased precision. Unlike Insert_Text, the parameters are not truncated. More...
 
HC_KEY DInsert_Text_With_Encoding (double x, double y, double z, const char *encoding, const void *text)
 Similar to Insert_Text_With_Encoding() but accepts double-precision values. More...
 
HC_KEY Insert_Text (double x, double y, double z, const char *text)
 Puts lettering into the current segment, and thence into the picture. More...
 
HC_KEY Insert_Text_With_Encoding (double x, double y, double z, const char *encoding, const void *text)
 Similar to Insert_Text(), but operates with encoded text rather than Latin1 text. More...
 

Detailed Description

Function Documentation

◆ DInsert_Text()

HC_KEY DInsert_Text ( double  x,
double  y,
double  z,
const char *  text 
)

Similar to Insert_Text(), but accepts parameters of type double for increased precision. Unlike Insert_Text, the parameters are not truncated.

Parameters
x- x-position, in user coordinates, of the "reference point" of the text.
y- y-position, in user coordinates, of the "reference point" of the text.
z- z-position, in user coordinates, of the "reference point" of the text.
text- Characters to be rendered.
Returns
The key to the inserted geometry, or -1 if an error occurred.

DETAILS

No additional details. See Insert_Text().

◆ DInsert_Text_With_Encoding()

HC_KEY DInsert_Text_With_Encoding ( double  x,
double  y,
double  z,
const char *  encoding,
const void *  text 
)

Similar to Insert_Text_With_Encoding() but accepts double-precision values.

Parameters
x- x-position, in user coordinates, of the "reference point" of the text.
y- y-position, in user coordinates, of the "reference point" of the text.
z- z-position, in user coordinates, of the "reference point" of the text.
encoding- Constant indicating the encoding method used in text. See above.
text- Characters to be rendered.
Returns
The key to the inserted geometry, or -1 if an error occurred.

DETAILS

No additional details. See Insert_Text_With_Encoding()

◆ Insert_Text()

HC_KEY Insert_Text ( double  x,
double  y,
double  z,
const char *  text 
)

Puts lettering into the current segment, and thence into the picture.

Parameters
x- x-position, in user coordinates, of the "reference point" of the text.
y- y-position, in user coordinates, of the "reference point" of the text.
z- z-position, in user coordinates, of the "reference point" of the text.
text- Characters to be rendered.
Returns
The key to the inserted geometry, or -1 if an error occurred.

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 specifies.

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, Insert_Text() uses the "ISO Latin One" collating sequence for the characters, which is just the first 256 characters of the Latin character set defined by the International Standards Organization, encoded 8 bits per character. Characters 32 through 176 are identical to Ascii (the American Standard Code for Information Interchange); many of the higher numbered characters have been defined by the ISO.T hese 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.
For the "undefined" character values, using ISO Latin One, if a "specific" font was chosen (see Set_Text_Font() ) and the font has the character, HOOPS lets the value map through. If a generic font was chosen or if the font does not have the character, HOOPS "fills in" with the double-character such as DC for character "\220" as shown in Table 4.1. These fill-in characters are included only as a convenience. They might be changed in the future.
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:

  • utf8
    In this case the string should be a null terminated UTF8 encoded character string.
  • utf16
    In this case the string should be a null terminated UTF16 encoded character string.
  • utf32
    In this case the string should be a null terminated UTF32 encoded character string.
  • wcs
    In this case the string should be a null terminated WCS encoded character string. This is the encoding style that maps over to the wchar_t type.
  • mbs
    In this case the string should be a null terminated MBS encoded character string. This is a locale-dependent, narrow character string. When inserted into HOOPS this string will be turned into a locale independent WCS string.

The unicode option is now deprecated and has been replaced by utf16.

The following are examples of strings that could be passed for each encoding style respectively

    char utf8_string[] = "Hello World!";
    unsigned short utf16_string[] = {0x00ff, 0x05d0, 0x0000};
    unsigned int utf32_string[] = {0x00ff, 0x05d0, 0x0000};
    wchar_t wcs_string[] = L"Hello World!";
    char mbs_string[] = "Hello World!";
    
    HC_Insert_Text_With_Encoding(0,0,0, "wcs", wcs_string);
    HC_Insert_Text_With_Encoding(0,1,0, "mbs", mbs_string);
    HC_Insert_Text_With_Encoding(0,2,0, "utf8", utf8_string);
    HC_Insert_Text_With_Encoding(0,3,0, "utf16", utf16_string);
    HC_Insert_Text_With_Encoding(0,4,0, "utf32", utf32_string);

NOTES

If a text string encounters the edge of a Window, with some 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 might disappear when any part touches the edge.
This function's double parameters are internally truncated to float. If you require extra precision, use this function's double-precision variant, DInsert_Text.

Character Set - ISO Latin-1

RESTRICTIONS

See also
Edit_Text, Scroll_Text, Set_Text_Font, Set_Text_Alignment, Set_Text_Spacing, Set_Text_Path, Set_Visibility, Insert_String_Cursor, Enable_String_Events, Show_String, Show_String_With_Encoding, Compute_Text_From_Text16, Renumber_Key.

◆ Insert_Text_With_Encoding()

HC_KEY Insert_Text_With_Encoding ( double  x,
double  y,
double  z,
const char *  encoding,
const void *  text 
)

Similar to Insert_Text(), but operates with encoded text rather than Latin1 text.

Parameters
x- x-position, in user coordinates, of the "reference point" of the text.
y- y-position, in user coordinates, of the "reference point" of the text.
z- z-position, in user coordinates, of the "reference point" of the text.
encoding- Constant indicating the encoding method used in text. See above.
text- Characters to be rendered.
Returns
The key to the inserted geometry, or -1 if an error occurred.

DETAILS

No additional details. See Insert_Text()