The Text Objects: 4.1 Text Object Chunks: The Text

The most important data associated with a text object is the text itself. The text of all non-large Text Objects is stored within a single chunk; this chunk is located in the same resource as the object itself. Text objects contain an instance field with a ChunkHandle to this text chunk. (In GenText objects, this is the instance field GTXI_text ; in VisText objects, this is VTI_text .)

Unless your text object uses the complex large model, it stores all of its text within this chunk. You may set initial text for your text object to appear within its instance data. The text object library automatically handles keyboard input from the user and translates that into characters displayed within the text object, altering the contents of the text chunk at the same time.

The text within the chunk is represented by a null-terminated character string. Each character of the text occupies a zero-based position within the text field. (The first character in the text field is at position zero.) These character positions are useful for setting character and paragraph attributes, marking the current selection, and marking the insertion point for new text.

The text object library provides a number of operations that you can perform to alter the display of text. These messages may take text from a variety of sources and include it within your text object; alternatively, you may retrieve text from your object and send it to other objects or processes.

Though the text within a non-large text object will always reside in a chunk (and may therefore be referenced with an optr) text may come from (and go to) several different sources. If you intend to retrieve text from or send text to a text object, you must know what type of source (or destination) you are dealing with.

Typically, text outside of a text object will reside in one of the following six forms. The first two cases are the most common.

A pointer to null terminated text string.
An optr to a chunk. (This is the same format the text object itself stores its text.)
A handle of a global memory block.
A handle of a VM block.
A database item.
A huge array.

For each operation on a text object, the text object library provides specific messages tailored to the format you are retrieving text from or transferring text to.

Text Ranges

VisTextRange, MSG_VIS_TEXT_GET_RANGE, VisTextRangeContext, MSG_VIS_TEXT_GET_TEXT_SIZE

Frequently, your application may wish to specify a range of text to act on. This range specifies the starting and ending points within the text for the relevant operation. Each of these starting and ending points is a zero-based character position.

typedef struct {
    dword		VTR_start;
			/* starting character position */
    dword		VTR_end;
			/* ending character position */
} VisTextRange;

To select a starting point at the first character, set VTR_start to zero. To select an ending point at the last character, set VTR_end to the special constant TEXT_ADDRESS_PAST_END.

If you want to pass the current selection as a range in any message that demands a VisTextRange , pass VIS_TEXT_RANGE_SELECTION to indicate that the currently selected area should be used to specify the range. Note that for some operations (such as paragraph attribute changes) the affected area may be larger than the text selection. Pass VIS_TEXT_RANGE_PARAGRAPH_SELECTION if you want the currently selected area to be used after it has been adjusted to reflect its paragraph boundaries.

You can use MSG_VIS_TEXT_GET_RANGE to return an actual VisTextRange of the selection (or paragraph selection). Pass this message a VisTextRangeContext , which specifies whether the range will include just the selection or kick out the range to its paragraph boundaries.The VisTextRange buffer that you also pass must be initially filled in (with VTR_start as 0 and VTR_end as TEXT_ADDRESS_PAST_END).

typedef WordFlags VisTextRangeContext;
#define VTRC_PARAGRAPH_CHANGE							0x8000
#define VTRC_CHAR_ATTR_CHANGE							0x4000
#define VTRC_PARA_ATTR_BORDER_CHANGE							0x2000

MSG_VIS_TEXT_GET_TEXT_SIZE returns the total size of the text within the text object.

MSG_VIS_TEXT_GET_RANGE

void	MSG_VIS_TEXT_GET_RANGE(
        VisTextRange		*range,
        word		context);

This message fills in a VisTextRange buffer based on the selection criteria passed in the context argument. The context information specifies whether the range will be used for a character attribute change (in which case the normal selection positions will be used) or whether the range will be used for a paragraph attribute change (in which case the boundaries of the selection will be kicked out to paragraph boundaries).

Source: Unrestricted.

Destination: Any text object.

Parameters: range VisTextRange buffer to hold the range text positions returned from the message handler. This buffer must be initially filled inwith VTR_start as 0 and VTR_end as TEXT_ADDRESS_PAST_END.

context: VisTextRangeContext .

Return: The VisTextRange buffer filled in.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_TEXT_SIZE

dword	MSG_VIS_TEXT_GET_TEXT_SIZE();

This message returns the current size of text.

Source: Unrestricted.

Destination: Any text object.

Return: The size of the text within the text object.

Interception: Generally not intercepted.

Replacing Text

MSG_VIS_TEXT_REPLACE_TEXT

There are many messages provided in VisTextClass to replace text within your Text Object. The most generic (and therefore versatile) of these messages is MSG_VIS_TEXT_REPLACE_TEXT. Simpler messages that you can use in special cases are documented in the following section (e.g. if you need to replace all of the text--or all of the text within a selection).

You may replace any range of text displayed within a Text Object by sending MSG_VIS_TEXT_REPLACE_TEXT, passing a pointer to a VisTextReplaceParameters structure. This structure must contain a range of text to replace and a TextReference that defines how the replacement text is referenced and stored. The structure is shown below.

typedef struct {
    VisTextRange         VTRP_range;
    dword                VTRP_insCount;
    TextReference        VTRP_textReference;
    VisTextReplaceFlags  VTRP_flags;
} VisTextReplaceParameters;

VTRP_range defines the range of text being replaced.

VTRP_insCount contains the number of characters in the replacement string buffer that is passed in VTRP_textReference . If you wish to have the Text object calculate this value itself dynamically, you may pass INSERT_COMPUTE_TEXT_LENGTH in the high word of this field (and zero in the low word).

VTRP_textReference contains a TextReference structure. This structure is explained in more detail below.

VTRP_flags contains a bitfield of VisTextReplaceFlags . Valid flags are:

VTRF_FILTER: This flag indicates that the passed replacement string should be passed through the Text object's VTI_filters , if any, before it is inserted into the Text object.
VTRF_KEYBOARD_INPUT: This flag indicates that the text being inserted is coming from the keyboard rather than from some other source.
VTRF_USER_MODIFICATION: This flag indicates that the text being inserted is due to a user modification. (User modifications will mark the Text object dirty; text inserted due to an application-initiated action may not mark the Text object dirty.)
VTRF_UNDO: This flag indicates that the text being inserted is due to an UNDO operation.
VTRF_DO_NOT_SEND_CONTEXT_UPDATE: This flag is internally set. It speeds up context notifications during global replaces, ensuring that the context is only updated after the entire operation has finished. Do not set this flag yourself.

The TextReference structure is shown below:

typedef struct {
    TextReferenceType     TR_type;
    TextReferenceUnion    TR_ref;
} TextReference

The TextReferenceType indicates what structure is referenced within the TextReferenceUnion . For each case, the reference is a structure of different arguments and size. These types are listed below, and correspond to teh indicated matching structure:

TRT_POINTER /* TextReferencePointer */: TRT_SEGMENT_CHUNK /* TextReferenceSegmentChunk */
TRT_OPTR /* TextReferenceBlockChunk */
TRT_BLOCK /* TextReferenceBlock */
TRT_VM_BLOCK /* TextReferenceVMBlock */
TRT_DB_ITEM /* TextReferenceDBItem */
TRT_HUGE_ARRAY /* TextReferenceHugeArray */

The TextReferenceUnion may be any of the following:

typedef union {
    TextReferencePointer       TRU_pointer;
    TextReferenceSegmentChunk  TRU_segChunk;
    TextReferenceBlockChunk    TRU_blockChunk;
    TextReferenceBlock         TRU_block;
    TextReferenceVMBlock       TRU_vmBlock;
    TextReferenceDBItem        TRU_dbItem;
    TextReferenceHugeArray     TRU_hugeArray;
} TextReferenceUnion;

The formats of these individual reference structures are contained within the Structures Reference book.

MSG_VIS_TEXT_REPLACE_TEXT

Boolean	MSG_VIS_TEXT_REPLACE_TEXT(
        VisTextReplaceParameters				*params);

This message replaces the text string within a text object (either a VisText or a GenText object) with the text referenced within the passed structure.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: *params A pointer to a VisTextReplaceParameters structure.

Return: true if an error occurred; false if the Text object's text is replaced.

Interception: Generally not intercepted.

Replacing Text All At Once

MSG_VIS_TEXT_REPLACE_ALL_PTR, MSG_VIS_TEXT_REPLACE_ALL_OPTR, MSG_VIS_TEXT_REPLACE_ALL_BLOCK, MSG_VIS_TEXT_REPLACE_ALL_VM_BLOCK, MSG_VIS_TEXT_REPLACE_ALL_DB_ITEM, MSG_VIS_TEXT_REPLACE_ALL_HUGE_ARRAY

You may replace the text displayed within a Text Object all at once with the following messages. Any previous text within the text object will be replaced with new text. The new text may come from any of the formats previously described. The format of this source determines which message you should use to replace the text.

MSG_VIS_TEXT_REPLACE_ALL_PTR replaces the text with text referenced by a simple pointer to a text string.

MSG_VIS_TEXT_REPLACE_ALL_OPTR replaces the text with text referenced by an optr. (This is the format that non-large text objects store their text.)

MSG_VIS_TEXT_REPLACE_ALL_BLOCK replaces the text with text residing in a global memory block.

MSG_VIS_TEXT_REPLACE_ALL_VM_BLOCK replaces the text with text residing in a VM block. Text objects that use the large model usually store their text within a VM block, so this message is useful for transferring text from one VisText object to another, for example.

MSG_VIS_TEXT_REPLACE_ALL_DB_ITEM replaces the text with text from a database item.

MSG_VIS_TEXT_REPLACE_ALL_HUGE_ARRAY replaces the text with text from a huge array.

MSG_VIS_TEXT_REPLACE_ALL_PTR

void	MSG_VIS_TEXT_REPLACE_ALL_PTR(
        const char 		*text, 
        word 		textLen);

This message replaces the text string within a text object (either a VisText or a GenText object) with the text referenced by the passed pointer.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: text A pointer to a text string.

textLen: The text length (in characters) or zero if null-terminated.

Return: Nothing. The Text object's text is replaced.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_ALL_OPTR

void	MSG_VIS_TEXT_REPLACE_ALL_OPTR(
        optr o,
        word textLen);

This message replaces the text string within a text object (either a VisText or a GenText) with the text referenced by the passed optr.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: o The optr of the chunk containing the text.

textLen: Length of the text string or zero if null-terminated.

Return: Nothing. The text object's text is replaced.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_ALL_BLOCK

void	MSG_VIS_TEXT_REPLACE_ALL_BLOCK(
        word block,
        word textLen);

This message replaces the text string within a text object (either a VisText or a GenText) with the text within the passed data block.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: block The handle of the data block containing the text to use in the replacement operation.

textLen: The length of the text or zero if null-terminated.

Return: Nothing. The text object's text is replaced.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_ALL_VM_BLOCK

void	MSG_VIS_TEXT_REPLACE_ALL_VM_BLOCK(
        VMFileHandle		file,
        VMBlockHandle		block,
        word 		textLen);

This message replaces the text string within a text object (either a VisText or a GenText) with the text within the passed data block.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file The handle of the VM file containing the text.

block: The VM block handle of the block within the VM file.
textLen: The length of the text or zero if null-terminated.

Return: Nothing. The text object's text is replaced.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_ALL_DB_ITEM

void	MSG_VIS_TEXT_REPLACE_ALL_DB_ITEM(
        VMFileHandle 		file,
        DBGroup 		group,
        DBItem		item);

This message replaces the text string within a text object (either a VisText or a GenText) with the text within the passed database item. The text is assumed to be null-terminated.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file The handle of the database item's associated VM file.

group: The database group containing the text.
item: The DB item containing the text.

Return: Nothing. The text object's text is replaced.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_ALL_HUGE_ARRAY

void	MSG_VIS_TEXT_REPLACE_ALL_HUGE_ARRAY(
        VMFileHandle		file,
        VMBlockHandle		hugeArrayBlock,
        word		textLen);

This message replaces the text string within a text object (either a VisText or a GenText) with the text within the passed HugeArray.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file The handle of the huge array's associated VM file.

hugeArrayBlock: The VM block handle of the huge array directory block.
textLen: The length of the text or zero if null-terminated.

Return: Nothing. The text object's text is replaced.

Interception: Generally not intercepted.

Replacing the Text Within a Selection

MSG_VIS_TEXT_REPLACE_SELECTION_PTR, MSG_VIS_TEXT_REPLACE_SELECTION_OPTR, MSG_VIS_TEXT_REPLACE_SELECTION_BLOCK, MSG_VIS_TEXT_REPLACE_SELECTION_VM_BLOCK, MSG_VIS_TEXT_REPLACE_SELECTION_DB_ITEM, MSG_VIS_TEXT_REPLACE_SELECTION_HUGE_ARRAY

The text object library automatically allows text selection. By using the mouse (or other device, depending on the specific UI), a user may select any section of text and perform operations on this selected text. The following messages replace any selected text with text from one of the described sources. What message you use depends on what type of source your text comes from.

Note that if no text is selected, these messages will enter text at the current cursor position. This allows these messages either to replace selected text or to "insert" text if none is selected. You may override this insertion behavior by setting paragraph attributes. In those cases, text entered at the current position will overstrike current text.

MSG_VIS_TEXT_REPLACE_SELECTION_PTR

void	MSG_VIS_TEXT_REPLACE_SELECTION_PTR(
        const char		*text,
        word		textLen);

This message replaces the current selection within a text object with the text contained in the passed string pointer. If no text is currently selected, the text will be inserted at the current cursor position.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: text The pointer to the character string.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_SELECTION_OPTR

void	MSG_VIS_TEXT_REPLACE_SELECTION_OPTR(
        optr	o,
        word	textLen);

This message replaces the current selection within a text object with the text in the chunk specified by o . If no text is currently selected, the text will be inserted at the current cursor position.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: o The optr of the text chunk.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_SELECTION_BLOCK

void	MSG_VIS_TEXT_REPLACE_SELECTION_BLOCK(
        word	block,
        word	textLen);

This message replaces the current selection within a text object with the text contained in the passed block. If no text is currently selected, the text will be inserted at the current cursor position.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: block Handle of the text block.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_SELECTION_VM_BLOCK

void	MSG_VIS_TEXT_REPLACE_SELECTION_VM_BLOCK(
        VMFileHandle		file,
        VMBlockHandle		block,
        word		textLen);

This message replaces the current selection within a text object by the text contained in the passed VM block. If no text is currently selected, the text will be inserted at the current cursor position.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file Handle of the VM file containing the text.

block: Handle of the block within the VM file.
textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_SELECTION_DB_ITEM

void	MSG_VIS_TEXT_REPLACE_SELECTION_DB_ITEM(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This message replaces the current selection within a text object with the text contained in the passed database item. If no text is currently selected, the text will be inserted at the current cursor position. The text is assumed to be null-terminated.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file The handle of the VM file containing the text.

group: The database group containing the text.
item: The database item.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_REPLACE_SELECTION_HUGE_ARRAY

void	MSG_VIS_TEXT_REPLACE_SELECTION_HUGE_ARRAY(
        VMFileHandle		file,
        VMBlockHandle		hugeArrayBlock,
        word		textLen);

This message replaces the current selection within a text object with the text contained in the passed huge array. If no text is currently selected, the text will be inserted at the current cursor position.

Source: Unrestricted.

Destination: Any GenText or VisText object.

Parameters: file The VM file containing the huge array.

hugeArrayBlock: The VM block handle of the huge array directory block.
textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

Appending the Text

MSG_VIS_TEXT_APPEND_PTR, MSG_VIS_TEXT_APPEND_OPTR, MSG_VIS_TEXT_APPEND_BLOCK, MSG_VIS_TEXT_APPEND_VM_BLOCK, MSG_VIS_TEXT_APPEND_DB_ITEM, MSG_VIS_TEXT_APPEND_HUGE_ARRAY

In many cases, you may not want to replace text but instead add it to the end of the current text. You may use any of the following messages to append text to your text object. Again, the new text may come from any of the formats previously described. The format of this source determines which message you should use to add the text.

MSG_VIS_TEXT_APPEND_PTR

void	MSG_VIS_TEXT_APPEND_PTR(
        const char		*text,
        word		textLen);

This message appends text to a text object; the text is added at the end of the current text. None of the previous text is changed.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: text The pointer to the character string.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_APPEND_OPTR

void	MSG_VIS_TEXT_APPEND_OPTR(
        optr	o,
        word	textLen);

This message adds text to a text object; the text is added at the end of the current text. None of the previous text is changed.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: o The optr of the text chunk.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_APPEND_BLOCK

void	MSG_VIS_TEXT_APPEND_BLOCK(
        word	block,
        word	textLen);

This message appends text to a text object; the text is added at the end of the current text. None of the previous text is changed.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: block Handle of the text block.

textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_APPEND_VM_BLOCK

void	MSG_VIS_TEXT_APPEND_VM_BLOCK(
        VMFileHandle		file,
        VMBlockHandle		block,
        word		textLen);

This message appends text to a text object; the text is added at the end of the current text. None of the previous text is changed.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file Handle of the VM file containing the text.

block: Handle of the block within the VM file.
textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_APPEND_DB_ITEM

void	MSG_VIS_TEXT_APPEND_DB_ITEM(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This message appends text to a text object; the text is added at the end of the current text. None of the previous text is changed. The text is assumed to be null-terminated.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The handle of the VM file containing the text.

group: The database group containing the text.
item: The database item.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_APPEND_HUGE_ARRAY

void	MSG_VIS_TEXT_APPEND_HUGE_ARRAY(
        VMFileHandle		file,
        VMBlockHandle		hugeArrayBlock,
        word		textLen);

This message appends text to a text object; the text is added at the end of the current text. None of the previous text is changed.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file containing the huge array.

hugeArrayBlock: The block handle of the huge array.
textLen: The length of the text in characters or zero, if null-terminated.

Return: Nothing.

Interception: Generally not intercepted.

Retrieving the Text

MSG_VIS_TEXT_GET_ALL_PTR, MSG_VIS_TEXT_GET_ALL_OPTR, MSG_VIS_TEXT_GET_ALL_BLOCK, MSG_VIS_TEXT_GET_ALL_VM_BLOCK, MSG_VIS_TEXT_GET_ALL_DB_ITEM, MSG_VIS_TEXT_GET_ALL_HUGE_ARRAY

You may also retrieve the text from your text object and place its text into any of the previously mentioned formats. The format of your destination determines which message you should use.

MSG_VIS_TEXT_GET_ALL_PTR

word	MSG_VIS_TEXT_GET_ALL_PTR(
        const char		*text);

This message retrieves the entire text of a text object and copies it to the buffer passed. The text within the text object is unchanged.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: text The pointer to a locked or fixed buffer. The buffer must be large enough to accommodate all the text.

Return: The length of the null-terminated string not counting the null character.

text: The buffer pointed to by text will contain the null-terminated text of the text object.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_ALL_OPTR

word	MSG_VIS_TEXT_GET_ALL_OPTR(
        optr	o);

This message retrieves the entire text of a text object and copies it into the chunk specified by o . The text within the text object is unchanged.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: o The optr of the chunk into which the text will be copied. Pass a valid memory handle with a null chunk handle to have the message allocate a new chunk.

Return: The chunk handle of the resized (or new) chunk. The chunk will always exist upon return and will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_ALL_BLOCK

word	MSG_VIS_TEXT_GET_ALL_BLOCK(
        word	block);

This message retrieves the entire text of a text object and copies it into the passed data block.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: block Handle of the memory block into which the text will be copied. Pass a null handle to have the message allocate a new block.

Return: The handle of the resized (or new) block. The block will always exist upon return and will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_ALL_VM_BLOCK

word	MSG_VIS_TEXT_GET_ALL_VM_BLOCK(
        VMFileHandle		file,
        VMBlockHandle		block);

This message retrieves the entire text of a text object and copies it into the passed VM block.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file.

block: The VM block handle of the VM block into which the text will be copied. Pass a null handle to have the message allocate a new VM block in the file.

Return: The VM block handle of the resized (or new) VM block. The VM block will always exist (assuming a valid VM file was passed), and it will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_ALL_DB_ITEM

DBGroupAndItem MSG_VIS_TEXT_GET_ALL_DB_ITEM(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This message retrieves the entire text of a text object and copies it into the passed database item.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file.

group: The database group number (may be DB_UNGROUPED--if so, a new group will be returned as part of the return value).
item: The item number of the database item into which the text will be copied. Pass zero to allocate a new database item in the specified group .

Return: The DBGroupAndItem representing the resized (or new) DB item into which the text was copied. The item will always exist (assuming a valid VM file was specified) upon return, and it will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_ALL_HUGE_ARRAY

word	MSG_VIS_TEXT_GET_ALL_HUGE_ARRAY(
        VMFileHandle		file,
        VMBlockHandle		hugeArrayBlock);

This message retrieves the entire text of a text object and copies it into the passed huge array block.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file containing the huge array.

hugeArrayBlock: The VM block handle of the huge array. Pass a null handle to have the message allocate a new huge array.

Return: The VM block handle of the first block of the resized (or new) huge array. The huge array will always exist upon return (assuming a valid VM file was specified), and it will contain at least the terminating null character.

Interception: Generally not intercepted.

Retrieving the Text Within a Selection

MSG_VIS_TEXT_GET_SELECTION_PTR, MSG_VIS_TEXT_GET_SELECTION_OPTR, MSG_VIS_TEXT_GET_SELECTION_BLOCK, MSG_VIS_TEXT_GET_SELECTION_VM_BLOCK, MSG_VIS_TEXT_GET_SELECTION_DB_ITEM, MSG_VIS_TEXT_GET_SELECTION_HUGE_ARRAY

To retrieve the text within the current selection, you may send any of the following messages to your text object. If no text is currently selected no text will be retrieved.

MSG_VIS_TEXT_GET_SELECTION_PTR

word	MSG_VIS_TEXT_GET_SELECTION_PTR(
        const char		*text);

This message retrieves the currently selected text and stores it in the character string referenced by the passed pointer. The text remains selected and intact in the original text object. The passed buffer must be large enough to accommodate the text.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: text The pointer to the character string.

Return: The length of the string not including the terminating null character.

text: The buffer pointed to by text will contain the null-terminated character string.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_SELECTION_OPTR

word	MSG_VIS_TEXT_GET_SELECTION_OPTR(
        optr	o);

This message retrieves the currently selected text and copies it into the passed chunk. The text remains selected and intact in the original text object.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: o The optr of the text chunk into which the text will be copied. Pass a valid memory handle and a null chunk handle to have the message allocate a new chunk in the give block.

Return: The chunk handle of the resized (or new) chunk containing the text. The chunk will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_SELECTION_BLOCK

word	MSG_VIS_TEXT_GET_SELECTION_BLOCK(
        word	block);

This message retrieves the currently selected text and copies it into the passed data block. The text remains selected and intact in the original text object.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: block Handle of the text block to place the text into. Pass a null handle to have the message allocate a new memory block.

Return: The memory handle of the resized (or new) block containing the selected text. The block will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_SELECTION_VM_BLOCK

word	MSG_VIS_TEXT_GET_SELECTION_VM_BLOCK(
        VMFileHandle		file,
        VMBlockHandle		block);

This message retrieves the currently selected text and copies it into the passed VM block. The text remains selected and intact in the original text object.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file.

block: The VM block handle of the VM block into which the text will be copied. Pass a null block handle to have the message allocate a new VM block in the file.

Return: The VM block handle of the resized (or new) VM block. The VM block will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_SELECTION_DB_ITEM

DBGroupAndItem MSG_VIS_TEXT_GET_SELECTION_DB_ITEM(
        VMFileHandle		file,
        DBGroup		group,
        DBItem		item);

This message retrieves the currently selected text and copies it into the given database item. The text remains selected and intact in the original text object.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file.

group: The group number of the passed item (if DB_UNGROUPED, a group will be determined).
item: The item number of the database item into which the text will be copied. Pass zero to have the message allocate a new database item in the specified group and file.

Return: The DBGroupAndItem representing the resized (or new) database item. The item will contain at least the terminating null character.

Interception: Generally not intercepted.

MSG_VIS_TEXT_GET_SELECTION_HUGE_ARRAY

word	MSG_VIS_TEXT_GET_SELECTION_HUGE_ARRAY(
        VMFileHandle		file,
        VMBlockHandle		hugeArrayBlock);

This message retrieves the currently selected text and copies it into the passed huge array. The text remains selected and intact in the original text object.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: file The VM file handle of the VM file.

hugeArrayBlock: The VM block handle of the huge array into which the text will be copied. Pass a null handle to have the message allocate a new huge array in the passed VM file.

Return: The VM block handle of the resized (or new) huge array block. The huge array will contain at least the terminating null character.

Interception: Generally not intercepted.

Other Operations on the Text

MSG_VIS_TEXT_DELETE_ALL, MSG_VIS_TEXT_DELETE_SELECTION

To delete the entire contents of a text object, send it MSG_VIS_TEXT_DELETE_ALL . This message will also resize the text's chunk to its minimum size. To delete only the current selection, send the text object MSG_VIS_TEXT_DELETE_SELECTION . No text will be selected after this message is sent.

MSG_VIS_TEXT_DELETE_ALL

void	MSG_VIS_TEXT_DELETE_ALL();

This message deletes the entire contents of a text object's text chunk. The chunk will be resized to zero.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: None.

Return: Nothing

Interception: Generally not intercepted.

MSG_VIS_TEXT_DELETE_SELECTION

void	MSG_VIS_TEXT_DELETE_SELECTION();

This message deletes the currently selected text. The text after the deletion will be automatically repositioned, and the text chunk will be resized.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: None.

Return: Nothing.

Interception: Generally not intercepted.

Marking the Text Selection

MSG_VIS_TEXT_GET_SELECTION_RANGE, MAG_VIS_TEXT_SELECT_RANGE, MSG_VIS_TEXT_SELECT_RANGE_SMALL, MSG_VIS_TEXT_SELECT_ALL, MSG_VIS_TEXT_SELECT_START, MSG_VIS_TEXT_SELECT_END, MSG_VIS_TEXT_SELECT_RELATIVE

MSG_VIS_TEXT_GET_SELECTION_RANGE returns the VisTextRange of the current selection.

MSG_VIS_TEXT_SELECT_RANGE selects the selected area of text to the passed range. This message can be used with both large and small model text objects.

MSG_VIS_TEXT_SELECT_RANGE_SMALL selects a range of text. The message must pass the VisTextRange to "select." This message only works with non-large text objects. Any previous selection will be deselected.

MSG_VIS_TEXT_SELECT_ALL selects the recipient's entire text.

MSG_VIS_TEXT_SELECT_START selects the start of the text with a VisTextRange of zero length. This places the cursor at the beginning of the text object and deselects any previous selection.

MSG_VIS_TEXT_SELECT_END selects the end of the text with a VisTextRange of zero length. This places the cursor at the end of the text object and deselects any previous selection.

MSG_VIS_TEXT_SELECT_RELATIVE moves the cursor from its current position to a new location relative to the old position. You may pass this message a relative selection range to move the cursor and select text at the new position.

MSG_VIS_TEXT_GET_SELECTION_RANGE

void	MSG_VIS_TEXT_GET_SELECTION_RANGE(
        VisTextRange		*vtr);

This message returns the range of the text object's current selection. You must pass this message a VisTextRange buffer for the message to fill in with the selection range.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: vtr A pointer to a VisTextRange structure to fill in with the selection range.

Return: The VisTextRange buffer will be filled in.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_RANGE

void	MSG_VIS_TEXT_SELECT_RANGE(@stack
        dword	end
        dword	start);

This message creates a selection for a text object. The message must pass the starting and ending character positions to mark as the text object's selection. Any previous selection will be deselected. Note that this message uses dword offsets into the text, and can therefore be used with LARGE model text objects.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: start The zero-based character position of the start of the selection.

end: The zero-based character position of the end of the selection. This must be equal to or larger than the start position.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_RANGE_SMALL

void	MSG_VIS_TEXT_SELECT_RANGE_SMALL(
        word	start,
        word	end);

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: start The zero-based character position of the start of the selection.

end: The zero-based character position of the end of the selection. This must be equal to or larger than the start position.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_ALL

void	MSG_VIS_TEXT_SELECT_ALL();

This message selects the entire text of a text object as its selection.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: None.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_START

void	MSG_VIS_TEXT_SELECT_START();

This message places the cursor at the start of the text. Any current selection will be deselected.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: None.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_END

void	MSG_VIS_TEXT_SELECT_END();

This message places the cursor at the end of the text. Any current selection will be deselected.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: None.

Return: Nothing.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SELECT_RELATIVE

void	MSG_VIS_TEXT_SELECT_RELATIVE(
        word	newStart,
        word	newEnd);

This message moves a selection from the current cursor position to a position relative to that position.

Source: Unrestricted.

Destination: Any VisText or GenText object.

Parameters: newStart The number of character positions from the current cursor position to start the new selection.

newEnd: number of character positions from the current cursor position to end the new selection. This value must be equal to or greater than newStart .

Return: Nothing.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

4 Text Object Chunks | Next:

4.2 Lines and Fields