Programming Guide: International Text

# Programming Guide

## International Text

This sections contains functions and macros used by part handlers for manipulating international text (IText) structures.

The following lists the IText functions and macros in alphabetic order.

- CopyIText
- CopyITextStruct
- CreateIText
- CreateITextClear
- CreateITextCString
- CreateITextFromCharPtr
- CreateITextPString
- DisposeIText
- DisposeITextStruct
- GetCStringFromIText
- GetPStringFromIText
- GetITextCString
- GetITextLangCode
- GetITextPString
- GetITextPStringFromIText
- GetITextPtr
- GetITextScriptCode
- GetITextStringLength
- SetITextBufferSize
- SetITextCString
- SetITextLangCode
- SetITextPString
- SetITextScriptCode
- SetITextStringLength
- SetITextText

### CopyIText

This function creates a copy of the specified IText structure.

Signature

    #include <IText.h>

    ODIText *CopyIText (ODIText *original)

Parameters

original (ODIText *) - input

  The IText structure to be copied.

Returns

rv (ODIText *) - returns

  A pointer to the copy of the specified IText structure.

### CopyITextStruct

This function creates a copy of the specified IText structure.

Signature

    #include <IText.h>

    ODIText *CopyITextStruct (ODIText *original)

Parameters

original (ODIText *) - input

  A pointer to the IText structure to be copied.

Returns

rv (ODIText *) - returns

  A copy of the specified IText structure.

### CreateIText

This function creates an IText structure from the specified buffer of characters.

Signature

    #include <IText.h>

    ODIText *CreateIText (ODScriptCode theScriptCode,
                          ODLangCode theLangCode,
                          ODUByte *text,
                          ODSize *textLength)

Parameters

theScriptCode (ODScriptCode) - input

  The script code; the code page.

theLangCode (ODLangCode) - input

  The language code; 0.

text (ODUByte *) - input

  A buffer of characters from which the IText is to be created.

textLength (ODSize *) - input

  The size, in bytes, of the buffer.

Returns

rv (ODIText *) - returns

  A pointer to the new IText structure.

Remarks

This function is used for text that is neither a C string or a Pascal string.

### CreateITextClear

This function creates an IText structure of a specified length.

Signature

    #include <IText.h>

    ODIText *CreateITextClear (ODScriptCode theScriptCode,
                               ODLangCode theLangCode,
                               ODSize stringLength)

Parameters

theScriptCode (ODScriptCode) - input

  The Script code; the code page.

theLangCode (ODLangCode) - input

  The language code; 0.

stringLength (ODSize) - input

  The size, in bytes, of the IText structure.

Returns

rv (ODIText *) - returns

  A pointer to the new IText structure.

Remarks

There is an overloaded C++ function call, CreateIText that performs the same function.

### CreateITextCString

This function creates an IText structure from the specified null-terminated string.

Signature

    #include <IText.h>

    ODIText *CreateITextCString (ODScriptCode theScriptCode,
                                 ODLangCode theLangCode,
                                 char *text)

Parameters

theScriptCode (ODScriptCode) - input

  The script code; the code page.

theLangCode (ODLangCode) - input

  The language code; 0.

text (char *) - input

  A null-terminated character string.

Returns

rv (ODIText *) - returns

  A pointer to the new IText structure.

Remarks

There is an overloaded C++ function call, CreateIText that performs the same function.

### CreateITextFromCharPtr

This function creates an IText structure from a C char pointer. The current code page becomes the script code.

Signature

    #include <IText.h>

    ODIText *CreateITextFromCharPtr (char *text&)

Parameters

text (char *) - input

  A null-terminated character string.

Returns

rv (ODIText *) - returns

  A pointer to the new IText structure.

### CreateITextPString

This function creates an IText structure from a specified array of 255 characters.

Signature

    #include <IText.h>

    ODIText *CreateITextPString (ODScriptCode theScriptCode,
                                 ODLangCode theLangCode,
                                 StringPtr text)

Parameters

theScriptCode (ODScriptCode) - input

  The script code; the code page.

theLangCode (ODLangCode) - input

  The language code; 0.

text (StringPtr) - input

  A pointer to an array of 255 characters. The first byte of this array contains its length.

Returns

rv (ODIText *) - returns

  A pointer to the new IText structure.

Remarks

These is an overloaded C++ function call, CreateIText that performs the same function.

### DisposeIText

This function frees memory of an IText structure.

Signature

    #include <IText.h>

    void DisposeIText (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be freed.

Returns

None.

### DisposeITextStruct

This macro frees the memory of an IText structure.

Signature

    #include <IText.h>

    void DisposeITextStruct (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be freed.

Returns

None.

### GetCStringFromIText

This function returns a pointer to a null-terminated character string in an IText structure.

Signature

    #include <IText.h>

    char *GetCStringFromIText (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

rv (char *) - returns

  The null-terminated string of the specified IText structure.

### GetITextScriptCode

This function returns the script code (the code page) for the specified IText structure.

Signature

    #include <IText.h>

    GetITextScriptCode (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

theScriptCode (ODScriptCode *) - returns

  The script code of the specified IText structure.

### GetPStringFromIText

This function returns an array of characters from the specified IText structure.

Signature

    #include <IText.h>

    StringPtr GetPStringFromIText (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

rv (StringPtr) - returns

  An array of characters from the specified IText structure. The first byte in this array contains the length of the string.

### GetITextCString

This function returns a pointer to the null-terminated character string of the specified IText structure.

Signature

    #include <IText.h>

    char *GetITextCString (ODIText *iText, char *cstring)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

cstring (char *) - input

  The null-terminated character string of the specified IText structure.

Returns

rv (char *) - returns

  The null-terminated character string of the specified IText structure.

Remarks

There are overloaded C++ function calls, GetITextString and GetCStringFromIText, that perform the same function.

### GetITextLangCode

This function returns the language code for the specified IText structure.

Signature

    #include <IText.h>

    ODLangCode GetITextLangCode (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

theLangCode (ODLangCode) - returns

  The language code of the specified IText structure.

### GetITextPString

This function returns the array of characters from the specified IText structure.

Signature

    #include <IText.h>

    char *GetITextPString (ODIText *iText,
                           Str255 pstring)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

pstring (Str255) - input

  If this parameter contains a valid string, the text from the iText parameter is copied into this character string, and a pointer to this string is returned. If this parameter is kODNULL, a new string is allocated, the text from the iText parameter is copied into this character string, and a pointer to this string is returned.

Returns

rv (char *) - returns

  An array of characters from the specified IText structure. The first byte in this array contains the length of the string.

Remarks

There are overloaded C++ function calls, GetITextString and GetCStringFromIText, that perform the same function.

### GetITextPStringFromIText

This function returns an array of characters from the specified IText structure.

Signature

    #include <IText.h>

    StringPtr GetITextPStringFromIText (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

pstring (StringPtr) - returns

  The character array of the specified IText structure. The first byte in the array contains the length of the string.

### GetITextPtr

This function returns a pointer to a byte array in the IText structure.

Signature

    #include <IText.h>

    char *GetITextPtr (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

ptr (char *) - returns

  A pointer to the byte array of the specified IText structure.

### GetITextStringLength

This function returns the length of the character string in the specified IText structure.

Signature

    #include <IText.h>

    ODULong GetITextStringLength (ODIText *iText)

Parameters

iText (ODIText *) - input

  The IText structure to be queried.

Returns

length (ODULong) - returns

  The length of the character string in the specified IText structure.

### SetITextBufferSize

This function sets the size of the byte-array buffer in the specified IText structure. If the input values are null, this function creates and returns a new ODIText structure.

Signature

    #include <IText.h>

    ODIText *SetITextBufferSize (ODIText *iText,
                                 ODSize bufferSize,
                                 ODBoolean preserveContents)

Parameters

iText (ODIText *) - input

  A pointer to the IText structure to be modified.

bufferSize (ODSize) - input

  The new size of the byte array.

preserveContents (ODBoolean) - input

  A flag indicating whether to preserve the content of the byte array, up to the length specified in the bufferSize parameter.

  kODTrue | The content of the byte array should be preserved.
  kODFalse | The content of the byte array should not be preserved.

Returns

rv (ODIText *) - returns

  A pointer to the IText structure with the new buffer size.

### SetITextCString

This function sets the value of the IText structure from the specified null-terminated character string. The byte array in the IText structure is automatically extended to fit the string.

Signature

    #include <IText.h>

    void SetITextCString (ODIText *iText, char *text)

Parameters

iText (ODIText *) - input

  The IText structure to be modified.

text (char *) - input

  The null-terminated character string to be copied into the specified IText structure.

Returns

None

Remarks

There is an overloaded C++ function call, SetITextString, that performs the same function.

### SetITextScriptCode

This function sets the script code for the specified IText structure.

Signature

    #include <IText.h>

    void SetITextScriptCode (ODIText *iText, ODScriptCode scriptCode)

Parameters

iText (ODIText *) - input

  The IText structure to be modified.

scriptCode (ODScriptCode) - input

  The script code to be set for the specified IText structure.

Returns

None.

### SetITextLangCode

This function sets the language code for the specified IText structure.

Signature

    #include <IText.h>

    void SetITextLangCode (ODIText *iText, ODLangCode theLangCode)

Parameters

iText (ODIText *) - input

  The IText structure to be modified.

theLangCode (ODLangCode) - input

  The language code to be set for the specified IText structure.

Returns

None.

### SetITextPString

This function sets the value of the IText structure to the specified array of 255 characters.

Signature

    #include <IText.h>

    void SetITextPString (ODIText *iText, StringPtr text)

Parameters

iText (ODIText *) - input

  The IText structure to be modified.

text (StringPtr) - input

  An array of 255 characters to be set in the specified IText structure.

Returns

None.

Remarks

There is an overloaded C++ function call, SetITextString, that performs the same function.

### SetITextStringLength

This function sets the length of the specified IText structure.

Signature

    #include <IText.h>

    ODIText *SetITextStringLength (ODIText *iText,
                                   ODSize length,
                                   ODBoolean preserveText)

Parameters

iText (ODIText *) - input

  The IText structure text to be modified. If this parameter is null, this function allocates and returns a new ODIText structure.

length (ODSize) - input

  The new length of the IText structure.

preserveText (ODBoolean) - input

  A flag indicating whether to preserve the content of the byte array up to the length specified in the length parameter.

  kODTrue | The content of the byte array should be preserved.
  kODFalse | The content of the byte array should not be preserved.

Returns

rv (ODIText *) - returns

  A pointer to the IText structure with the new buffer size.

Remarks

There is an overloaded C++ function call, CreateItext, that performs the same function.

### SetITextText

This function sets the value of the IText structure to the specified buffer. The byte array of the IText structure is automatically extended to fit the buffer.

Signature

    #include <IText.h>

    void SetITextText (ODIText *iText,
                       ODUByte *text,
                       ODSize textLength)

Parameters

iText (ODIText *) - input

  The IText structure to be modified.

text (ODUByte *) - input

  The buffer of characters to be set in the specified IText structure..

textLength (ODSize) - input

  The size of the buffer specified in the text parameter.

Returns

None.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]