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

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 ]