Legacy Document

Inside Macintosh: Text /

Chapter 2 - TextEdit / TextEdit Reference

Routines / Customizing TextEdit

TECustomHook

The TECustomHook procedure replaces a default TextEdit hook routine with a customized routine and returns the address of the replaced routine.

PROCEDURE TECustomHook (which: TEIntHook; VAR addr: ProcPtr; 
                        hTE: TEHandle);

which

The hook whose default routine is to be replaced.

addr

On input, the address of your customized procedure.

On output, the addr parameter contains the address of the routine that was previously installed in the field identified by the which parameter. This address is returned so that you can daisy-chain routines.

hTE

A handle to the edit record to be modified.

DESCRIPTION

The TECustomHook procedure lets you alter the behavior of TextEdit to better suit your application's requirements and those of the script systems installed. If you replace a default hook routine with a customized version that you write in a high-level language, such as Pascal or C, you need to provide assembly-language glue code that utilizes the registers for your high-level language routine. The register contents for each of the hook routines are described in this section under "Assembly-Language Information."

The end-of-line hook, width measurement hook, new width measurement hook, text width measurement hook, draw hook. and hit test hook fields are hook fields in the TextEdit dispatch record. The which parameter identifies the hook whose default routine is to be replaced; you use the following constants to specify a value for this parameter.

Constant	Value	Description
intEOLHook	0	End-of-line hook
intDrawHook	1	Draw hook
intWidthHook	2	Width measurement hook
intHitTestHook	3	Hit test hook
intNWidthHook	6	New width measurement hook
intTextWidthHook	7	Text width measurement hook (low-memory global width measurement hook)

ASSEMBLY-LANGUAGE INFORMATION

The end-of-line hook, width measurement hook, new width measurement hook, text width measurement hook, draw hook, and hit test hook fields are hook fields in the TextEdit dispatch record. When you use TECustomHook to replace the default routines installed in these hook fields with customized ones, remember that the replacement routine must preserve all registers except those specified as containing return values.

End-of-Line Hook Registers

You specify the intEOLHook constant as the value of the which parameter to identify the end-of-line hook routine as the one you want to replace. This hook routine determines whether an incoming character is an end-of-line character. It tests the character, sets the appropriate status flags in the status register, and returns. The default action is to compare the character with $0D (a carriage return).

Registers on entry
D0	Character to compare (byte)
A3	Pointer to the edit record
A4	Locked handle to the edit record

Registers on exit
Z	(Zero) flag in the status register clear if end-of-line character; set otherwise.

Draw Hook Registers

You specify the intDrawHook constant as the value of the which parameter to identify the drawing hook routine as the one you want to replace. The draw hook routine is called any time the components of a line are drawn. The appropriate font, style, and size characteristics have already been set into the current port by the time this routine is called. By default, the address of the QuickDraw DrawText procedure is stored in the draw hook field.

If your application is using outline (TrueType) fonts, TextEdit has also set the preserveGlyph parameter of the Font Manager's SetPreserveGlyph procedure to FALSE, so your customized hook procedure may need to reset this parameter if your application depends on it.

Registers on entry
D0	Offset into text (word)
D1	Length of text to draw (word)
A0	Pointer to text to draw
A3	Pointer to the edit record
A4	Locked handle to the edit record

Width Measurement Hook Registers

You specify the intWidthHook constant as the value of the which parameter to identify the width measurement hook routine as the one you want to replace. The width measurement hook routine measures portions of a line of text. It is used when only the Roman script system is installed and the field contains the address of a customized routine. It is supported for backward compatibility. In all other cases, when more than one script system is installed or when the width measurement hook field has not been customized, TextEdit calls the routine whose address is installed in the new width measurement hook field.

Registers on entry
D0	Length (in bytes) of text to measure (word)
D1	First byte of text to measure (word)
A0	Pointer to text buffer
A3	Pointer to the edit record
A4	Locked handle to the edit record

Registers on exit
D1	Pixel width of measured text (word)

Hit Test Hook Registers

You specify the intHitTestHook constant as the value of the which parameter to identify the hit test hook routine as the one you want to replace. The hit test hook routine determines the glyph position in a line given the pixel width from the left edge of the view rectangle. For system software before System 7, the default action is to call the QuickDraw TextWidth function to determine if the pixel width of the measured text is greater than the input width. If it is, then the hit test hook routine calls the QuickDraw PixelToChar function and returns. For System 7, the default action is to call the QuickDraw PixelToChar function.

Registers on entry
D0	Length of text block (style run) to measure (word)
D1	Pixel width from start of text block (word)
D2	Slop (should equal 0) (word)
A0	Pointer to start of text block
A3	Pointer to the edit record
A4	Locked handle to the edit record

Registers on exit
D0	Pixel width to character offset in text block (low word) A Boolean that is TRUE if a character offset corresponding to the given pixel width was found (high word). Otherwise, FALSE.
D1	Character offset (word)
D2	A Boolean that is TRUE if the pixel width falls within the leading edge of the character (low word). Otherwise, FALSE. TextEdit also uses the least significant bit of the high word. If the hit test hook routine calls PixelToChar, TextEdit sets this bit. If it uses TextWidth, TextEdit clears this bit. Your customized routine needs to do the same if you call either PixelToChar or TextWidth (high word). See the chapter "QuickDraw Text" in this book for more about these routines.

Note

In earlier versions of TextEdit, the value in register D2 on entry was not always used. If you daisy-chain in a routine and then call the hit test hook routine, D2 must be 0 (on entry).

New Width Measurement Hook Registers

You specify the intNWidthHook constant as the value of the which parameter to identify the new width measurement hook routine as the one you want to replace. The new width measurement hook routine measures portions of a line of text when a non-Roman script system is installed. It is also used when only a Roman script system is installed and the width hook field does not contain the address of a customized routine. The default procedure calls CharToPixel or TextWidth, depending on the primary line direction. The appropriate font, style, and size characteristics have already been set into the current graphics port by the time this routine is called.

The new width measurement hook routine is called to measure text for both Roman and non-Roman script systems, so make sure that your customized routine is script-aware.

Registers on entry
D0	Overall style run length, bounded by the line end (word)
D1	Offset position within style run on the current line (word)
D2	Slop (low word); direction flag (high word)
A0	Pointer to text buffer
A2	Pointer to current line start (from TextEdit's lineStarts array)
A3	Pointer to the edit record
A4	Locked handle to the edit record

Registers on exit
D1	Pixel width of measured text (word)

Text Width Measurement Hook Registers

You specify the intTextWidthHook constant as the value of the which parameter to identify the low-memory global text width measurement hook routine as the one you want to replace. By default, this hook field contains the address of the QuickDraw TextWidth function and provides a way to replace TextEdit's use of TextWidth. The new width measurement hook routine uses the routine whose address is installed in this field.

Registers on entry
D0	Length (in bytes) of text to be measured (word)
D1	Offset in text of first byte to measure (word)
A0	Pointer to text to measure
A3	Pointer to the edit record
A4	Locked handle to the edit record

Registers on exit
D1	Pixel width of measured text (word)

SEE ALSO

For more information about the SetPreserveGlyph procedure, see the chapter "Font Manager" in this book. For more information about DrawText, TextWidth, PixelToChar, and CharToPixel, see the chapter "QuickDraw Text" in this book.

SPECIAL CONSIDERATIONS

Take the following precautions if you replace a default routine:

• Before placing the address of your routine in the TextEdit dispatch record, strip the addresses, using the Operating System Utilities StripAddress function, to guarantee that your application is 32-bit clean. For more information, see Inside Macintosh: Operating System Utilities.
• Before replacing a TextEdit routine with a customized one, determine whether more than one script system is installed, and, if so, ensure that your customized routine accommodates all of the installed script systems. This avoids the problem of your customized routine producing results that are incompatible with the Script Manager.
• When you use assembly language, note that all registers must be preserved except those specified as containing return values. Registers A3 contains a pointer to the edit record and Register A4 contains a handle to it. You can obtain line start positions from the lineStarts array in the edit record. Register A5 is always valid. Refer to TECustomHook in the "TextEdit Reference" section for complete coverage of the register content requirements for all hook routines.