Text Operations

You can use text media handlers to

• add plain or styled text samples to a movie

• indicate scrolling and highlighting properties for the text

• search for text

• highlight specified text

A particular text sample has a default font, size, typeface, and color as well as a location (text box) within the track bounds to be drawn. The data format allows you to include style run information for the text. You can set flags to clip the display to the text box, inhibit automatic scaling of text as the track bounds are scaled, scroll the text, and specify if text is to be displayed at all.

The Movie Toolbox provides functions to help you add text samples to a track. You can use the TextMediaAddTextSample function to add text to a media. The TextMediaAddTESample function allows you to specify a TextEdit handle (which may have multiple style runs) to be added to a media. The TextMediaAddHiliteSample function allows you to indicate highlighting for text that has just been added with the TextMediaAddTextSample or TextMediaAddTESample function.

The format of the text data that is added to the media is a 16-bit length word followed by the text. The length word specifies the number of bytes in the text. Optionally, one or more atoms of additional data may follow. An atom is structured as a 32-bit length word followed by a 32-bit type followed by some data. The length word includes the size of the data as well as the length and type fields (in other words, the size of the data plus 8).

Text atom types include the style atom ('styl'), the shrunken text box atom ('tbox'), the highlighting atom ('hlit'), the scroll delay atom ('dlay'), and the highlight color atom ('hclr').

The format of the style atom is the same as TextEdit’s StScrpRec data type. A StScrpRec data type is a short integer specifying the number of style runs followed by that number of ScrpSTElement data types, each specifying a different style run.

The shrunken text box atom is added when you set the dfShrinkTextBoxToFit display flag (in the TextMediaAddTextSample or TextMediaAddTESample function). Its format is simply the rectangle of the shrunken box (16 bytes total, including length and type).

The highlighting atom is added if the hiliteStart and hiliteEnd parameters are set appropriately in the TextMediaAddTextSample or TextMediaAddTESample function. When TextMediaAddHiliteSample is called, an empty text sample (the first 2 bytes are 0) with a highlighting atom is added to the media. The format is two long integers indicating the start and end of the highlighting (16 bytes total).

The scroll delay atom specifies the scroll delay for a sample. It is a long value that specifies the delay time. It consists of 12 bytes, including the length and type fields.

The highlight color atom specifies the highlight color for a sample. Its format is an RGBColor data type (that is, 2 bytes red, 2 bytes green, and 2 bytes blue). It consists of 14 bytes, including the length and type fields.

Text Media Handler Functions

The following functions can be used with text media handler components. They support such tasks as adding plain or styled text samples to a movie, setting scrolling and highlighting, and text searching.

• TextMediaSetTextSampleData

• TextMediaAddTextSample

• TextMediaAddTESample

• TextMediaAddHiliteSample

• TextMediaFindNextText

• TextMediaHiliteTextSample

• TextMediaSetTextProc

The TextMediaAddTextSample, TextMediaAddTESample, and TextMediaAddHiliteSample functions convert text into the text media format and add it to the media. To use these functions, you need to:

• create a text track and media

• call the BeginMediaEdits function

• call the TextMediaAddTextSample, TextMediaAddTESample, or TextMediaAddHiliteSample function, as appropriate

• call the EndMediaEdits function

• call the InsertMediaIntoTrack function

Movie import and export components help to get common data types (such as 'PICT' or 'snd ') into and out of movies easily. The text import component allows you to get text into a movie using the following principles:

• If you try to paste text, the text is inserted at the current position. The text import component tries to find an existing text track that fits the text.

• If no text tracks exist and there is an insertion operation, the newly created text track has the same position and size as the movie box.

• If there is an addition operation (using the Shift key), the new track is added below the movie at a height that fits the text.

• If a text track exists but the text does not fit, a new text track with sufficient height to accommodate the text is created in the same location as the existing one.

• If you hold down the Option key when you paste, the text is added in parallel at some default duration.

• If you hold down both the Option and Shift keys, the duration of the text is determined by the length of the current selection.

• If style information is on the Clipboard, it is used; otherwise, the text appears in the default 12-point application font, centered, in white on a black background.

If you want more control over how the text is added (for example, if you want to set some display flags or a new track position), your application must:

• intercept the text paste

• instantiate its own text import component using the component type 'eat ' and component subtype 'TEXT'

• use functions including MovieImportSetSampleDuration, MovieImportSetSampleDescription, MovieImportSetDimensions, and MovieImportSetAuxilliaryData (with 'styl' and a StScrpHandle data type)

• call the MovieImportHandle function with the text data

• adjust the location of the track, if desired (since the text import component may place it below the movie box)

The Movie Toolbox provides functions that allow you to search for and highlight text. You can use the TextMediaFindNextText function to search for text in a text track, and the TextMediaHiliteTextSample function to highlight specified text in a text track.

You can use the TextMediaSetTextProc function to specify a customized function whenever a new text sample is added to a movie.

You can use the MyTextProc callback to pass a handle to a specified sample containing formatted text, along with the movie in which the text is being displayed, a pointer to a flag variable, and your reference constant. You specify the desired operations on the text and return an indication of whether you want to display the text in the displayFlag parameter.