International Text (IText)(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook / Part - Appendixes: Appendix A - OpenDoc Utilities

International Text (IText)
This section describes the utilities defined in the files IText.h and IText.cpp. These utilities create, destroy, and manipulate international text (ODIText) structures, which contain a variable-size text buffer as well as Mac OS script and language codes.

Creation in Default Heap
The following functions create an ODIText structure using a C string. On the Mac OS, the ODScriptCode and the ODLangCode parameters correspond to the platform script code and language code. The CreateIText function is overloaded to use different types of input parameters, as shown throughout this section.
ODIText* CreateITextCString(ODScriptCode script, ODLangCode lang, 
                                          char* text);
ODIText* CreateIText(ODScriptCode script, ODLangCode lang, char* text);
The following functions create an ODIText structure using a Pascal string:
ODIText* CreateITextPString(ODScriptCode script, ODLangCode lang, 
                                       StringPtr text);
ODIText* CreateIText(ODScriptCode script, ODLangCode lang, 
                                       StringPtr text);
The following functions create an ODIText structure with an empty string of specified length:
ODIText* CreateITextClear(ODScriptCode script, ODLangCode lang, 
                                    ODSize stringLength );
ODIText* CreateIText(ODScriptCode script, ODLangCode lang, 
                                    ODSize stringLength );
The following functions create an ODIText structure with a buffer of characters of specified length:
ODIText* CreateITextWLen(ODScriptCode script, ODLangCode lang, 
                           ODUByte* text, ODSize textLength );
ODIText* CreateIText(ODScriptCode script, ODLangCode lang, 
                           ODUByte* text, ODSize textLength)
The following function sets the buffer size of the ODIText structure. If the input ODIText pointer is kODNULL, this function is equivalent to the CreateITextClear function.
ODIText* SetITextBufferSize(ODIText* text, ODSize bufferSize, 
                              ODBoolean preserveContents );
Destruction
The following function disposes of an ODIText structure and any memory associated with it:
void  DisposeIText(ODIText* text);
The following function is the same as the DisposeIText function except that it works on ODIText structure allocated on the stack:
void  DisposeITextStruct(ODIText text);
Duplication
The following function allocates and returns an exact copy of the ODIText structure passed in:
ODIText* CopyIText(ODIText* original);
The following function is the same as the CopyIText function except that the returned ODIText structure is allocated on the stack:
ODIText  CopyITextStruct(ODIText* original);
Accessing Attributes
The following functions set and get the script code of the ODIText structure passed in:
void  SetITextScriptCode(ODIText* text, ODScriptCode script);
ODScriptCode GetITextScriptCode(ODIText* text);
The following functions set and get the language code of the ODIText structure passed in:
void  SetITextLangCode(ODIText* text, ODLangCode lang);
ODLangCode GetITextLangCode(ODIText* text);
The following function sets the length of the ODIText structure's string length field. If kODNULL is passed in as the input ODIText, the function is equivalent to the CreateITextClear function.
ODIText* SetITextStringLength( ODIText* text, ODSize length, 
                                 ODBoolean preserveText);
ODIText* CreateIText(ODSize length);
The following function returns the string length of the ODIText structure passed in:
ODULong  GetITextStringLength(ODIText* text);
Accessing the String
The following function returns a pointer to the raw text without allocating any memory.

IMPORTANT
This function should be used with extreme caution because the pointer returned belongs to the ODIText structure.
char* GetITextPtr(ODIText* text);
The following functions set the string of the ODIText structure with a C string. Note that the SetITextString function is overloaded and can also take a Pascal string:
void SetITextCString(ODIText* iText, char* cString);
void SetITextString(ODIText* iText, char* cString);
The following functions set the string of the ODIText structure with a Pascal 
string.
void SetITextPString(ODIText* iText, StringPtr pString);
void SetITextString(ODIText* iText, StringPtr pString);
The following function sets the string of the ODIText structure with a buffer of 
the specified length:
void SetITextText(ODIText* text, ODUByte* text, ODSize textLength);
The following functions return to a C string a pointer that corresponds to the string in the ODIText structure. If a string is passed in, the same string is used to return the result. Otherwise, this function allocates memory for the returned string. Note that the GetITextString function is overloaded and can also take and return a Pascal string.
char*  GetITextCString(ODIText* iText, char* cString);
char* GetITextString(ODIText* iText, char* cString);
char* GetCStringFromIText(ODIText* iText);
The following functions work like the GetITextCString function except that they return a Pascal string:
StringPtr GetITextPString(ODIText*, Str255 pString);
StringPtr GetITextString(ODIText* i, StringPtr pString);
StringPtr GetPStringFromIText(ODIText* iText);