TweetFollow Us on Twitter

Winter 92 - THE TEXTBOX YOU'VE ALWAYS WANTED

THE TEXTBOX YOU'VE ALWAYS WANTED

BRYAN K. ("BEAKER") RESSLER

[IMAGE Ressler_article_rev1.GIF]

NeoTextBox is an alternative to the TextEdit utility routine TextBox. NeoTextBox provides full-justification capability and the option to use TrueType features while retaining all the advantages of TextBox. The three routines that comprise NeoTextBox compile to fewer than 900 bytes yet offer a 40% performance increase over TextBox in common cases.


In the deepest, darkest corner of the TextEdit chapter inInside Macintosh Volume I, there's an extremely useful routine called TextBox.

pascal void TextBox(void *text, long length, Rect *box, short just)

Given a rectangle and some text, TextBox word wraps the text inside the rectangle, drawing in the font, style, and size specified in the current grafPort.

Anyone who's tried to word wrap text knows that it's not as easy as it first appears. Perhaps that's why TextBox takes the approach it does: to perform its task, TextBox creates a new TERec with TENew, sets up the rectangles in the record, and calls TESetText to create a temporary handle to a copy of the text you provided to TextBox. TextBox then calls TEUpdate to wrap and draw the text, and finally TEDispose to dispose of the TERec. By calling TextEdit to do the text wrapping and drawing, TextBox avoids doing any hard work. Unfortunately, it also incurs quite a bit of overhead.

Despite its pass-the-buck implementation, TextBox's use of TextEdit has several advantages. Perhaps most important, TextBox works correctly with non-Roman script systems like Japanese and Arabic without the need for any extra programming. Another handy side effect is that updates in TextEdit degenerate into calls to DrawText, and can therefore be recorded into QuickDraw pictures. TextBox was designed specifically for drawing static text items in dialog boxes and performs this function well.

So TextBox is great--if you're drawing dialog boxes. But you want more. You want better performance. You want more flexibility. You want to control line height. You want full justification (instead of only left, center, and right alignment). You want to use whizzy TrueType calls when they're available. You want to control the text drawing mode. You can't stand the way TextBox always erases (and therefore isn't too useful when you're drawing to printers--it slows printing way down). Yeah, and you don't like that 32K text limitation either. You want to word wrapWar and Peace in a single call to TextBox. And you'd like some useful information back, too, like the line height it used, and where the last line of text was drawn, so that you can draw something below the text. And, of course, you want to retain the advantages of TextBox.

Well, this is your lucky day.

ENTER NEOTEXTBOX

NeoTextBox is the TextBox you've always wanted (and didn't even have to ask for). NeoTextBox is on the average 33% faster than an equivalent call to TextBox. Plus, it's considerably more flexible:
  • NeoTextBox allows a line height specification. You can ask for the default (same behavior as TextBox); use variable line height, which adjusts for characters that extend beyond the font's standard ascent or descent line; or specify a line height in points.
  • NeoTextBox provides left, center, and right alignment and full justification.
  • NeoTextBox never erases the rectangle it's drawing into. It lets you erase or, if you wish, draw a colored background.
  • NeoTextBox returns the total number of lines in the wrapped text.
  • NeoTextBox can return, via VAR parameters, the vertical pen position of the last line of text and the line height that was used to draw the text.

NeoTextBox gives you all this extra functionality, yet retains the advantages of TextBox. It is completely language independent and uses the Script Manager heavily (just like TextEdit). It's easy to call, and if you don't want all the spiffy new features, it's easy to get TextBox-like behavior with a free performance increase.

Let's take a look at the parameters for NeoTextBox.

short NeoTextBox(unsigned char *theText, unsigned long textLen, 
            Rect *wrapBox, short align, short lhCode, short *endY,
            short *lhUsed)

The first two parameters, theText and textLen, are analogous to TextBox's text and length parameters: they specify the text to be wrapped. Note that theText isn't a Pascal string--it's a pointer to the first printable character.

The third and fourth parameters, wrapBox (box in TextBox) and align, also hearken back to NeoTextBox's ancestor. Just as in TextBox, wrapBox specifies the rectangle within which you're wrapping text, and the align parameter specifies the alignment. In addition to the standard TextEdit alignments teFlushLeft, teCenter, and teFlushRight (see "Text Alignment Constants for System 7"), a new alignment is defined--ntbJustFull. It performs full justification in whatever manner is appropriate for the current script.

The fifth parameter, lhCode, specifies how the line height is derived. If lhCode is 0, the default line height is derived via a call to GetFontInfo. This gives the same behavior as TextBox. If lhCode is less than 0, the line height is derived by determining which characters in the text that's being drawn extend the most above and below the baseline (see "SetPreserveGlyph With TrueType Fonts"). Finally, if lhCode is greater than 0, the value of lhCode itself specifies the line height. For instance, you can draw 12-point text in 16-point lines.

The last two parameters, endY and lhUsed, are reference parameters that allow you to retrieve the vertical position of the last line of text and the line height that was used to draw the text, respectively. The endY parameter can be very useful if you intend to draw anything below the text, since it tells you exactly where the last line of text was drawn. To find out what the actual derived line height was if you used a negative lhCode, use the lhUsed parameter. Pass nil for either or both of these last two parameters if you don't want this extra information.


NeoTextBox returns thetotal  number of lines in the text. That includes lines clipped off because they were below the bottom of wrapBox. You can tell whether the text overflowed wrapBox by whether the value returned in endY is greater than wrapBox.bottom. If you want to know how many lines fit in wrapBox, simply divide the height of wrapBox by the value returned in lhUsed.

TEXT ALIGNMENT CONSTANTS FOR SYSTEM 7

Before System 7, there was a conflict between the names of the text alignment constants and their actual behavior. To help make applications compatible with non-Roman scripts, teJustLeft was interpreted as the default text alignment appropriate for the current script rather than forcing text to be aligned on the left as specified. For example, on a Hebrew system, a TextBox call with a just parameter of teJustLeft would actually use the default justification for Hebrew, which is teJustRight.

To overcome this conflict, new constants were introduced in System 7, as shown in Table 1.
Table 1 Text Alignment Constants

New ConstantOld ConstantValueMeaning
teFlushLeftteForceLeft-2Align text on the left for all scripts
teFlushRightteJustRight-1Align text on the right for all scripts
teFlushDefaultteJustLeft0Use conventional alignment for script
teCenterteJustCenter1Center text for all scripts

SETPRESERVEGLYPH WITH TRUETYPE FONTS

Before TrueType, all characters in all fonts fit beneath the font's ascent line and above the descent line, like the default characters shown in Figure 1. Bitmapped fonts were drawn so that diacriticals, like the angstrom over the A  in Ångström, would fit beneath the ascent line. To do this, the letterform had to be distorted. With the advent of TrueType, this "feature" can be controlled, because TrueType fonts carry outline data that's true to the original design (hence the name TrueType).

Since most applications expect characters to fit beneath the ascent line and above the descent line, QuickDraw transforms characters in TrueType fonts to force them within those bounds. To override this transformation and preserve the original glyph shape, use the Font Manager call SetPreserveGlyph(TRUE). After this call, TrueType fonts will be drawn as shown to the right in Figure 1. Preserving the glyph shape makes it possible to take advantage of NeoTextBox's variable line height feature.

[IMAGE Ressler_article_rev2.GIF]

Figure 1 How SetPreserveGlyph Affects Line Height

REQUIREMENTS

NeoTextBox uses some advanced Script Manager routines that are available only in System 6 or later. NeoTextBox assumes they're available, so make sure your main program checks that it's running on System 6 or later via a Gestalt or SysEnvirons call.

NeoTextBox requires one global variable, a Boolean named gHasTrueType. It should be set to TRUE if the TrueType trap ($A854) is available, or FALSE if not. If your development environment provides glue for Gestalt, you can use the following lines to set up gHasTrueType:

#define kTrueTypeTrap 0x54  /* The TrueType trap number */
#define kUnimplTrap 0x9f    /* The "unimplemented" trap number */
long gResponse;

if (Gestalt(gestaltFontMgrAttr,&gResponse) == noErr)
    gHasTrueType = BitTst(&gResponse,31-gestaltOutlineFonts);
else {
    gHasTrueType = (NGetTrapAddress(kTrueTypeTrap,ToolTrap) !=
        NGetTrapAddress(kUnimplTrap,ToolTrap));
}

THE BASIC ALGORITHM

NeoTextBox does a lot. But, in order to appease the programmer's natural desire to avoid work, we allow the Script Manager to do the hard parts. (Do you know how to do full justification in Arabic?) In short, here's how NeoTextBox gets its job done:
  1. It saves the current grafPort's clipping region and clips to the box we're drawing into.
  2. It calculates the appropriate line height with the function NTBLineHeight.
  3. It calls the Script Manager routine StyledLineBreak to find each line-break point in the input text.
  4. It draws each line with the function NTBDraw.
  5. It advances the pen down one line.
  6. When there's no more text, it restores the clipping region and returns the appropriate values.

It sounds simple, doesn't it? That's because StyledLineBreak does all the work. It knows how to find word breaks in whatever script we're using. StyledLineBreak is smart, too. For instance, in English, it knows that it's OK to break a hyphenated word if necessary. It uses rules that are provided by the installed script systems, so it always takes the appropriate actions. Let's take a closer look at the code.

THE NEOTEXTBOX FUNCTION

The source code for NeoTextBox that's shown here is written in MPW C 3.2. We'll start in the NeoTextBox function and break out to a couple of utility functions when we come upon them.

Here's the NeoTextBox declaration and local variables:

short NeoTextBox(unsigned char *theText, unsigned long textLen,
    Rect *wrapBox, short align, short lhCode, short *endY,
    short *lhUsed)
{
  RgnHandle           oldClip;        /* Saved clipping region */
  StyledLineBreakCode breakCode;      /* From StyledLineBreak */
  Fixed               fixedMax;       /* boxWidth in fixed point */
  Fixed               wrapWid;        /* Width to wrap within */
  short               boxWidth;       /* Width of box */
  long                lineBytes;    /* Number of bytes in one line */
  unsigned short      lineHeight;     /* Calculated line height */
  short               curY;           /* Current vert pen location */
  unsigned short      lineCount;    /* Number of lines we've drawn */
  long                textRemaining;  
                                   /* Number of bytes of text left */
  unsigned char       *lineStart;    /* Pointer to start of a line */
  unsigned char       *textEnd;    /* Pointer to end of input text */

Many of these variables are used in the call to StyledLineBreak, which is explained in detail later. The most important variables to know about here are breakCode, which contains the line break code returned by each call to StyledLineBreak; lineStart and lineBytes, which are returned by StyledLineBreak to specify a single line; and curY, the current vertical pen location.

GET READY
NeoTextBox, like TextBox, clips to wrapBox. Since this is a general-purpose routine, it's safest to save the clipping region, then restore it at the end. We calculate the width of wrapBox, because it's used a lot, and convert it to fixed point as fixedMax, which is used in calls to StyledLineBreak as a VAR parameter. Also, we retrieve the appropriate text alignment if the user has requested default alignment.

GetClip((oldClip = NewRgn()));
ClipRect(wrapBox);
boxWidth = wrapBox->right - wrapBox->left;
fixedMax = Long2Fix((long)boxWidth);
if (align == teFlushDefault)
    align = GetSysJust();

DETERMINE THE LINE HEIGHT
Now we need to determine the appropriate line height. NeoTextBox calls NTBLineHeight to perform this function, passing the text pointer, the text length, the wrap rectangle, the caller- specified line height code, and the address of curY, the current vertical pen location. NTBLineHeight calculates and returns the line height and calculates the correct starting pen location. Here's the NTBLineHeight function:

unsigned short NTBLineHeight(unsigned char *theText, 
   unsigned long textLen, Rect *wrapBox, short lhCode, short *startY)
{
    short                   asc, desc;
    FontInfo                fInfo;
    Point                   frac;
    unsigned short      lineHeight;

    GetFontInfo(&fInfo);
    if (lhCode < 0) {
       /* lhCode < 0 means "variable line height", so if it's a */
       /* TrueType font use OutlineMetrics, otherwise use default. */
        frac.h = frac.v = 1;
        if (gHasTrueType && IsOutline(frac, frac)) {
            OutlineMetrics((short)textLen, theText, frac, frac, &asc,
                &desc, nil, nil, nil);
            lineHeight = MAXOF(fInfo.ascent, asc) 
                + MAXOF(fInfo.descent, -desc) + fInfo.leading;
            *startY = wrapBox->top + MAXOF(fInfo.ascent, asc)
                + fInfo.leading;
        } else {
            /* Punt to "default" if we can't use TrueType. */
            lineHeight = fInfo.ascent + fInfo.descent + fInfo.leading;
            *startY = wrapBox->top + fInfo.ascent + fInfo.leading;
        }
    } else if (lhCode == 0) {
        /* lhCode == 0 means "default line height." */
        lineHeight = fInfo.ascent + fInfo.descent + fInfo.leading;
        *startY = wrapBox->top + fInfo.ascent + fInfo.leading;
    } else {
        /* lhCode > 0 means "use this line height" so we */
        /* trust 'em. */
        lineHeight = lhCode;
        *startY = wrapBox->top + lhCode + fInfo.leading;
    }
    return(lineHeight);
}

Remember, there are three possible line height codes:

  • Variable line height (specified by an lhCode less than 0) is handled first. If the TrueType trap is available and this particular font is a TrueType font, OutlineMetrics is called to determine the line height (see "Descent Into Hell"). OutlineMetrics can return a variety of information, but we really only want the highest ascent and the lowest descent, which are returned in the local variables asc and desc. Then we choose whichever is higher, the default ascent or asc, and whichever is lower, the default descent or desc. If TrueType isn't available or the particular font isn't a TrueType font, we punt to the default line height.
  • If lhCode is 0, the default line height is used. This is defined as the sum of the ascent, descent, and line gap (leading) derived by a GetFontInfo call.
  • Finally, if lhCode is greater than 0, the caller is providing a specific line height. In this case, NTBLineHeight returns lhCode as the line height.

Each of the three line height calculation methods also figures the correct startY based on the line height and wrapBox->top.

Back in NeoTextBox, we call NTBLineHeight to set up our local variables lineHeight and curY:

lineHeight = NTBLineHeight(theText, textLen, wrapBox, lhCode, &curY);
lineCount = 0;
lineStart = theText;
textEnd = theText + textLen;
textRemaining = textLen;

Here we also set up some other local variables. The variable lineCount records the number of lines we've drawn. The pointer lineStart points to the beginning of the current line, which initially is the beginning of the text. The variable textEnd is a pointer to just beyond the end of the input text and is used for testing when the text is all used up. Finally, the variable textRemaining keeps track of how many bytes of input text remain to be processed.

THE BREAK-DRAW LOOP
Now NeoTextBox is ready to break lines and draw the text. This task is performed by the following do-while loop:

do {
    lineBytes = 1;
    wrapWid = fixedMax;

    breakCode = StyledLineBreak(lineStart, textRemaining, 0,
        textRemaining, 0, &wrapWid, &lineBytes);

    NTBDraw(breakCode, lineStart, lineBytes, wrapBox, align, curY,
        boxWidth);

    curY += lineHeight;
    lineStart += lineBytes;
    textRemaining -= lineBytes;
    lineCount++;
} while (lineStart < textEnd);

If this looks simple, that's because it is. Anyone who's tried to write code to wrap text knows that it's a difficult task. Making the algorithm compatible with different script systems complicates the matter even more. Fortunately, we have the Script Manager, which in this case makes our lives alot  easier.

The workhorse: StyledLineBreak. First we set lineBytes to 1, signaling to StyledLineBreak that this is the first "script run" on this line. Since we have only one script run, we always reset lineBytes at the top of the loop. Also, we reset wrapWid to be fixedMax (which was previously initialized to the fixed- point width of the wrap rectangle). WrapWid tells StyledLineBreak the width within which to wrap the text and returns how much of the line is left (if any) after wrapping (that's why we have to reset it at the top of the loop each time).

Now we call StyledLineBreak. We provide a pointer to the beginning of the text for this line, the number of bytes of text remaining, the wrap width, and the address of a variable where StyledLineBreak puts the number of bytes in this line. StyledLineBreak does the hard work of finding word boundaries, adding up character widths, and handling special cases, all in an internationally compatible way.

After StyledLineBreak returns, lineBytes tells us the length of the current line beginning at lineStart, and breakCode has a line break code that tells us the circumstances of the line break, as shown in Figure 2.

[IMAGE Ressler_article_rev3.GIF]

Figure 2 Line Break Codes


Usually, StyledLineBreak returns smBreakWord, indicating that it broke the line on a word boundary. The break code smBreakChar says that it encountered a word that was too long to fit on a single line and was forced to break in the middle of a word. StyledLineBreak returns smBreakOverflow if you run out of text before filling the given width. These line break codes help determine how to draw the text.

Draw the text with NTBDraw. After StyledLineBreak figures the length of the line, NeoTextBox calls NTBDraw to draw the line. NeoTextBox passes a pointer to the line of text, the length of the line in bytes, the wrap rectangle, the alignment, the current vertical pen location, and the width of the wrap rectangle. Let's take a look at NTBDraw:

#define kReturnChar     0x0d

void NTBDraw(StyledLineBreakCode breakCode, unsigned char *lineStart,
    long lineBytes, Rect *wrapBox, short align, short curY, 
    short boxWidth)
{
    unsigned long   blackLen;    /* Length of non-white characters */
    short           slop;        /* Number of pixels of slop for */ 
                                 /* full justification */
    blackLen = VisibleLength(lineStart, lineBytes);
    
    if (align == ntbJustFull) {
        slop = boxWidth - TextWidth(lineStart, 0, blackLen);
        MoveTo(wrapBox->left, curY);
        if (breakCode == smBreakOverflow ||
                *(lineStart + (lineBytes - 1)) == kReturnChar)
            align = GetSysJust();
        else DrawJust(lineStart, blackLen, slop);
    }
    switch(align) {
        case teFlushLeft:
        case teFlushDefault:
            MoveTo(wrapBox->left, curY);
            break;
        case teFlushRight:
            MoveTo(wrapBox->right - TextWidth(lineStart, 0,
                blackLen), curY);
            break;
        case teCenter:
            MoveTo(wrapBox->left + (boxWidth - TextWidth(lineStart,
                0, blackLen)) / 2, curY);
            break;
    }
    if (align != ntbJustFull)
        DrawText(lineStart, 0, lineBytes);
}

NTBDraw's job is to move the pen and draw the text as indicated by the alignment parameter, align, and the line break code, breakCode. NTBDraw first calculates the visible length of the line with a call to the Script Manager routine VisibleLength. This excludes white-space characters at the end of the line. What exactly are white-space characters? Well, that depends on the script. VisibleLength knows which characters are visible and which are not for the current script, and returns an appropriate length in bytes, which is stored in the local variable blackLen.

When align is ntbJustFull, we need to determine whether the current line has a carriage return character ($0D) at the end, because a line with a carriage return (for example, the last line in a paragraph) should always be drawn with the default system alignment, rather than fully justified.

Looking back at the break codes for different types of lines shown in Figure 2, notice that the line that ends with the carriage return (denoted graphically in the illustration) returns a line break code of smBreakWord, where you might expect it to return smBreakOverflow. As you can see, StyledLineBreak expects the caller to know when a line is the last line of a paragraph. Therefore, every line whose break code is smBreakWord must be checked for a carriage return.

NTBDraw looks at the last byte in the line it's drawing to see if it's a carriage return. Since the carriage return character ($0D) falls into the control-code range, it's guaranteed never to occur as the low byte of a two-byte character. This frees us from having to test whether the last character in the line is two-byte and allows us to proceed directly to the last byte.

We now know whether the current line has a carriage return or not. If not, we calculate the amount of white-space slop remaining in the line, then call the Script Manager routine DrawJust to draw the text fully justified--whatever that means for this script. (In Arabic, for instance, full justification is performed completely differently than for Roman text.) If the current linedoes end in a carriage return, we override the align parameter with the default system alignment and fall through. For the left, right, and center alignments, the switch statement moves the pen appropriately, and a DrawText call is made to draw the text. The visible length (in blackLen) helps correctly calculate the pen position for right and center alignment and full justification.

Update the variables. After NTBDraw returns, we need to update a bunch of local variables and loop around again.

    curY += lineHeight;
    lineStart += lineBytes;
    textRemaining -= lineBytes;
    lineCount++;
} while (lineStart < textEnd);

First, we add lineHeight to curY, setting us up for the next line. LineStart, the pointer to the beginning of a line, gets updated to the character after the end of the current line. TextRemaining gets reduced by the number of bytes consumed by the current line, and lineCount gets incremented. If lineStart still hasn't run off the end of the text, the whole break-draw process is repeated.

RETURN SOME VALUES
Now that NeoTextBox has done such a fine job wrapping the text, it's time to return some useful values to the caller.

 if (endY)
    *endY = curY - lineHeight;
if (lhUsed)
    *lhUsed = lineHeight;

NeoTextBox returns these values only if the caller wants them. This makes it easy to get TextBox- like behavior from NeoTextBox without having to do any work: if you don't want a return value, just pass nil instead of providing the address of a variable.

CLEAN UP AND WE'RE DONE
The only thing left to do is a little cleanup, and we're outa here.

    SetClip(oldClip);
    DisposeRgn(oldClip);

    return(lineCount);
}

We restore the clipping region, dispose of our saved region, and return lineCount.

CALLS TO NEOTEXTBOX

One of the best features of NeoTextBox is that you can easily substitute it for calls you're currently making to TextBox. If that's all you want to do, replace every occurrence that looks like this

TextBox(textPtr, textLen, &wrapBox, justify);

with this

{
    EraseRect(&wrapBox);
    NeoTextBox(textPtr, textLen, &wrapBox, justify, 0, nil, nil);
}

To use NeoTextBox in place of TextBox, you pass 0 for lhCode (default line height) and nil for endY and lhUsed, and ignore the return value. If you add NeoTextBox to your program and just do thesubstitution above, every NeoTextBox call will be on the average 33% faster than the old TextBox call. If you use TextBox a lot, that can mean a real performance increase.

You can use NeoTextBox in more ways than just as direct substitution to improve performance. It does, after all, have whizzy new features that TextBox never had. Let's take a look at a more sophisticated call to NeoTextBox that uses some of its unique features:

short UseNTB(void)
{
    Rect            wrapBox;
    RGBColor        ltBlue;
    Handle          textHdl;
    long            textLen;
    short           numLines = 0;
    short           endY, lineHt;
    /* Set up our RGBColor and wrapBox. */
    SetRect(&wrapBox, 10, 10, 110, 110);
    ltBlue.red = 39321;
    ltBlue.green = 52428;
    ltBlue.blue = 65535;
    
    /* Paint the background, then set up the port text parameters. */
    PenNormal();
    RGBForeColor(&ltBlue);
    PaintRect(&wrapBox);
    ForeColor(blackColor);
    TextFont(helvetica); TextSize(12);
    TextFace(0); TextMode(srcOr);

    /* Retrieve some text for us to draw. */
    textHdl = GetResource('TEXT', 128);
    if (textHdl) {
        textLen = GetHandleSize(textHdl);
        /* Be sure to lock the handle. NeoTextBox can move memory! */
        HLock(textHdl);
        
        /* Wrap text and set numLines, endY, and lineHt. */
        numLines = NeoTextBox(*textHdl, textLen, &wrapBox,
            ntbJustFull, 18, &endY, &lineHt);
        HUnlock(textHdl);

        /* Beep if text overflows wrapBox. */
        if (endY > wrapBox.bottom)
            SysBeep(1);

        /* Prove we know where the text ended by drawing a line. */
        MoveTo(wrapBox.left, endY + lineHt);
        Line(20, 0);
    }
    return(numLines);
}

This sample function draws a 100-by-100-pixel box in light blue, then wraps text from a TEXT resource into the rectangle, ORing the text over the blue background. The text is fully justified 12- point Helvetica®, with 18-point line spacing. If the text overflows the box, a beep sounds. A small line is drawn at the baseline where subsequent text might be drawn.

Here's an example using NeoTextBox with variable line height and TrueType fonts:

void UseVariableLineHeight(Rect *wrapBox, short align)
{
    Boolean oldPreferred, oldPreserve;
    Handle      textHdl;
    long        textLen;

    if (gHasTrueType) {
        oldPreferred = GetOutlinePreferred();
        oldPreserve = GetPreserveGlyph();
        SetOutlinePreferred(TRUE);
        SetPreserveGlyph(TRUE);
    }

    textHdl = GetResource('TEXT', 128);
    textLen = GetHandleSize(textHdl);
    HLock(textHdl);
    NeoTextBox(*textHdl, textLen, wrapBox, align, -1, nil, nil);
    HUnlock(textHdl);

    if (gHasTrueType) {
        SetOutlinePreferred(oldPreferred);
        SetPreserveGlyph(oldPreserve);
    }
}

[IMAGE Ressler_article_rev4.GIF]

Figure 3 Using Variable Line Height

Notice that we save the current settings of the Font Manager's OutlinePreferred and PreserveGlyph flags. This allows us to be transparent to the caller. By setting OutlinePreferred to TRUE, we are ensured of using TrueType fonts, even if bitmapped fonts are available. By setting PreserveGlyph to TRUE, we get the accurate glyph shapes and measurements (see "SetPreserveGlyph With TrueType Fonts" on page 34). Calling NeoTextBox with -1 as its lhCode parameter causes it to use variable line height, which results in the difference shown in Figure 3.

LIMITATIONS AND POSSIBLE ENHANCEMENTS

NeoTextBox is a nice alternative to TextBox, but it has its limitations and areas that could benefit from improvement. Following are some suggestions for overcoming the limitations and adding useful features.

32K TEXT SIZE LIMIT
All you War and Peace fans out there need to do a little work. NeoTextBox shares the 32K text limitation that TextBox has, but not for the same reason. TextBox can wrap only 32K of text in one call because it uses TextEdit. In NeoTextBox, the limitation arises from the OutlineMetrics call, which is used in deriving variable line height and can only handle 32K of text. Heavy-duty Tolstoy types could remove the code that implements variable line height and subsequently word wrap most novels in a single NeoTextBox call (knock yourselves out).

DON'T FORGET TO ERASEPerhaps this isn't really a limitation, but you can't simply replace a TextBox call with a NeoTextBox call. You need to call EraseRect explicitly if you want TextBox behavior, as shown earlier in the section "Calls to NeoTextBox."

SCREEN-ONLY OPTIMIZATIONS
If you know you'll be using NeoTextBox only for screen applications (that is, you won't be using it to draw into a printer port), you can make a few optimizations. If you don't care about the return values, you can use RectInRgn to check whether the wrap rectangle intersects with the current port's visRgn; if it doesn't, you can simply return.

If you don't need the return value giving the number of total lines, you can make the break-draw loop terminate when curY exceeds wrapBox->bottom + lineHeight.

SPECIAL ONE-LINE CASE
In Macintosh computers with 256K ROMs, TextBox has a feature that might be a worthwhile addition to NeoTextBox. If the TextWidth of the input text is less than boxWidth, simply use DrawText to draw the text and don't bother with any of the wrapping code. TextBox has this feature because it's used for dialog box statText items, which are often one line.

DON'T DRAW OFF THE END OF WRAPBOX
It might make NeoTextBox faster if NTBDraw isn't called when curY is greater than wrapBox- >bottom + lineHeight. You'd still have to wrap all the text (to determine the total number of lines), but you wouldn't be drawing text that you know will be clipped.

MAKE SAVING/RESTORING THE CLIPPING REGION OPTIONAL
It might be useful to be able to set up some complex clipping region and have NeoTextBox wrap as usual but clip its text to whatever the clipping region is set to at invocation. You could add a Boolean swapClip parameter to control this.

STYLED NEOTEXTBOX
With considerable effort, NeoTextBox could be extended to handle styled and multiscript text. Since StyledLineBreak, the workhorse of NeoTextBox, is designed to be used with styled text, such an enhancement is possible.

CONCLUSION

Once you start using NeoTextBox, you'll find it ending up in all your applications. In tests on a Macintosh IIfx running System 7, NeoTextBox was between 25% and 50% faster than TextBox, 33% faster on the average. Performance varies depending on font, screen depth, and the ratio of wrapping to drawing. For left-aligned Geneva text on an 8-bit screen, NeoTextBox is 40% faster than TextBox. That alone is a good reason to use it. Plus, it has features you can't get out of TextBox at all.

Perhaps the moral of this article is if you don't like some feature of the Toolbox or OS go ahead and write your own. But you'll be doing yourself a favor--and you'll be a lot more compatible in the future--if you can find lower-level system, Toolbox, or OS facilities to aid you in your task, rather than recoding the entire feature yourself.

So go ahead and whip NeoTextBox into your application. Enjoy the improved performance and new features. And if there's something you don't like, go right in there and change it. Make NeoTextBox the TextBoxyou've always wanted!

DESCENT INTO HELL

Descent  is the amount of space that should be allocated for a font below the text baseline. When you call GetFontInfo, the value returned for descent is a positive number of points below the baseline. Although this is convenient, in the typographic industry it's more common to represent descent values as negative  numbers.

In an attempt to be more typographically useful, TrueType's OutlineMetrics call returns its descent values as negative numbers. So, to avoid a descent into hell, remember to note the sign of descent values when mixing calls to GetFontInfo and OutlineMetrics.

BRYAN K. RESSLER, or "Beaker" as he's known at Apple, is one of our twisted software engineers who seems to be convinced that anything is possible on a Macintosh, and if it's already been done, it can be done better. He got his BSCS from the University of California, Irvine, and wrote commercial MIDI applications before coming to Apple. Beaker wrote many of the programs used for testing TrueType fonts. When he's not on a coding frenzy, he writes noncommercial  MIDI applications, tries to have a life, and keeps a consistent blood-caffeine level so high you need scientific notation to express it.*

THANKS TO OUR TECHNICAL REVIEWERSSue Bartalo, John Harvey, Joe Ternasky*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Vienna 3.0.6 :5eaf312: - RSS and Atom ne...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
Kodi 15.1.rc1 - Powerful media center to...
Kodi (was XBMC) is an award-winning free and open-source (GPL) software media player and entertainment hub that can be installed on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user... Read more
Bookends 12.5.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Access the power of Bookends directly from Mellel, Nisus Writer Pro, or MS Word (... Read more
Chromium 44.0.2403.125 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 44.0.2403.125: This release contains a number... Read more
iMazing 1.2.2 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Audio Hijack 3.2.0 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
FontExplorer X Pro 5.0.1 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Calcbot 1.0.2 - Intelligent calculator a...
Calcbot is an intelligent calculator and unit converter for the rest of us. Featuring an easy-to-read history tape, expression view, intuitive conversion, and much more! Features History Tape -... Read more
MTR 5.0.0.1 - The Mac's oldest and...
MTR (was MacTheRipper)--the Mac's oldest and smartest DVD-backup app--is now updated to version 5.001 MTR -- the complete toolbox, not a one-trick, point-and-click extractor. MTR is intended for... Read more
LibreOffice 4.4.5.2 - Free, open-source...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more

Card King: Dragon Wars - Tips, Tricks an...
[Read more] | Read more »
Pac-Man Championship Edition DX has brou...
Bandai Namco has released Pac-Man Championship Edition DX on iOS and Android, which features the classic arcade gameplay that we've all grown to love. Pac-Man Championship Edition DX can be enjoyed in much shorter bursts than the arcade versions... | Read more »
Cosmonautica (Games)
Cosmonautica 1.1 Device: iOS Universal Category: Games Price: $6.99, Version: 1.1 (iTunes) Description: Cast off! Are you ready for some hilarious adventures in outer space? | Read more »
Rescue humanity from a Demon horde in An...
Angel Stone is Fincon's follow up to the massively successful Hello Hero and is out now on iOS and Android. You play as a member of The Resistance, a group of mighty human warriors who have risen up in defiance of the Demon horde threatening to... | Read more »
Gallery Doctor (Photography)
Gallery Doctor 1.0 Device: iOS iPhone Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Free up valuable iCloud and iPhone storage with Gallery Doctor, the only iPhone cleaner that automatically identifies the... | Read more »
You Against Me (Games)
You Against Me 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: A simple game… You. Me. Claim, steal, lock, score, win! | Read more »
Yep, it's True - Angry Birds 2 is O...
The not exactly rumors were true and the birds are back. Angry Birds 2 has come to the App Store and the world will... well I suppose it'll still be the same, but now we have more bird-flinging options! [Read more] | Read more »
You Could Design Your Own Card for Chain...
If you've ever wanted to create your own item, weapon, trap, or even monster for Chainsaw Warrior: Lords of the Night, this is your chance. Auroch Digital is currently holding a contest so that fans can fight to the death (not really) to see which... | Read more »
Bitcoin Billionaire is Going Back in Tim...
If you thought you managed to buy everything there is to buy in Bitcoin Billionaire and make all the money, well you though wrong. Those of you who made it far enough might remember investing in time travel - and it looks like that investment is... | Read more »
Domino Drop (Games)
Domino Drop 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Domino Drop is a delightful new puzzle game with dominos and gravity!Learn how to play it in a minute, master it day by day.Your... | Read more »

Price Scanner via MacPrices.net

11-inch MacBook Airs on sale for $100 off MSR...
Best Buy has 11-inch MacBook Airs on sale for $100 off MSRP. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - 11″ 1.6GHz... Read more
iPad Air 2 on sale for up to $100 off MSRP
Best Buy has iPad Air 2s on sale for up to $100 off MSRP on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale prices available for online... Read more
Sale! 13-inch MacBook Pros on sale for $100 o...
B&H Photo has 13″ MacBook Pros on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.5GHz/500GB MacBook Pro: $999.99 save $100 - 13″ 2.7GHz/128GB Retina... Read more
Sale! Save $100 on 13-inch MacBook Airs this...
B&H Photo has the 13″ 1.6GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model.... Read more
Worldwide Tablet Market Decline Continues, Ap...
The worldwide tablet market declined -7.0% year-over-year in the second quarter of 2015 (2Q15) with shipments totaling 44.7 million units according to preliminary data from the International Data... Read more
TP-LINK TL-PA8030P KIT Powerline Featuring Ho...
Consumer and business networking products provider TP-LINK is now shipping its TL-PA8030P KIT AV1200 3-Port Gigabit Passthrough Powerline Starter Kit that expands your home’s network over its... Read more
Apple refurbished iPad Air 2s available for u...
The Apple Store has Apple Certified Refurbished iPad Air 2s available for up to $140 off the price of new models. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB... Read more
Updated Apple iPad Price Trackers
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers. Read more
Apple refurbished 2014 13-inch 128GB MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ MacBook Airs available starting at $759. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.4GHz/128GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Infrastructure Engineer - *Apple* /Mac - Hil...
Infrastructure Engineer - Apple /Mac Job Code: 1608 # of openings: 1 Description Our fortune 500 client is looking to hire an experienced Infrastructure Engineer to join Read more
Executive Administrative Assistant, *Apple*...
…supporting presentation development for senior leadership. * User experience with Apple hardware and software is preferred. Additional Requirements The following list Read more
*Apple* Bus Company is now hirin - Apple Bus...
Apple Bus Company is now hiring school bus drivers in the Pettis County area. Class B CDL preferred. Free training provided. No nights or weekends required. Flexible Read more
*Apple* Certified Mac Technician - Updated 6...
…and friendly, hands-on technical support to customers troubleshooting and repairing Apple /Mac products with courtesy, speed and skill. Use your problem-solving skills Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.