draw_text.c

Go to the documentation of this file.

//                  _                          _               _                        //
//               __| | _ __  __ _ __      __  | |_  ___ __  __| |_     ___              //
//              / _` || '__|/ _` |\ \ /\ / /  | __|/ _ \\ \/ /| __|   / __|             //
//             | (_| || |  | (_| | \ V  V /   | |_|  __/ >  < | |_  _| (__              //
//              \__,_||_|   \__,_|  \_/\_/_____\__|\___|/_/\_\ \__|(_)\___|             //
//                                       |_____|                                        //
//                                                                                      //
//                        text draw, multi-line and tabbed text                         //
//                                                                                      //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')


  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <memory.h>
#include <string.h>
#include <strings.h>

#include "window_helper.h"  // this also includes 'font_helper.h'

#include "draw_text.h"
#include "pixmap_helper.h" // for anti-alias functions, etc.


// function prototypes


static int InternalCalcIdealBounds(Display *pDisplay, WB_FONTC pFont, DT_WORDS *pWords, int iTabWidth, unsigned int iTabOrigin,
                                   const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment, int iStartLine, int iEndLine);


static void InternalDebugDumpWords(DT_WORDS *pWords); 


static void __internalDoAntiAlias(Display *pDisplay, Drawable dw, WBGC gc, int iX, int iY, int iWidth, int iHeight);


// *******************
// DRAW TEXT UTILITIES
// *******************

// abstracting the 'draw text' process
// NOTE:  this is like WBDrawString but you specify a font without assigning it to the WBGC

void DTDrawString(Display *pDisplay, Drawable drawable, WB_FONTC pFont,
                  WBGC gc, int x, int y, const char *pString, int nLength)
{
char tbuf[1024];
char *pS;
WB_EXTENT ext;
XImage *pImage;

//#if defined(X_HAVE_UTF8_STRING)
//#define DO_DRAW_STRING Xutf8DrawString
//#else // use 'multi-byte char' equivalent
//#define DO_DRAW_STRING XmbDrawString
//#endif // UTF8 vs multi-byte


  // NOTE:  invokes WB_DRAW_STRING macro, which (for X11) is either Xutf8DrawString() or XmbDrawString()
  //        depending on your system's configuration (more likely the first one)

  if(!pDisplay || !pString || drawable == None || !pFont || !gc || nLength <= 0)
  {
    if(pString && nLength > 0)
    {
      WB_ERROR_PRINT("ERROR: %s.%d returning error for \"%-.*s\"\n", __FUNCTION__, __LINE__, nLength, pString);
    }
    else
    {
      WB_ERROR_PRINT("ERROR: %s.%d returning error for %d,%p\n", __FUNCTION__, __LINE__, nLength, pString);
    }

    return; // don't allow this.  just don't.
  }

// TODO:  do I allow this??
//  if(nLength < 0) // negative length - use strlen
//  {
//    nLength = strlen(pString);
//  }

  pImage = WBGetWindowImage(pDisplay, drawable);

  if(pImage) // cached image - use WBXDrawString to do the work
  {
    WBXDrawString(pImage, pFont, gc, x, y, pString, nLength);
    // NOTE:  does not update immediately, but after you 'end paint'

    return;
  }


  // do THIS part because 'pString' is 'const char *' and X*DrawString wants 'char *'
  // and so 'pS' becomes a copy of the string, in writeable memory.

  if(WB_LIKELY(nLength <= sizeof(tbuf)))
  {
use_the_stack_buffer:

    // use my temporary buffer for small strings [the most common thing]

    if(WB_LIKELY(nLength > 0))
    {
      memcpy(tbuf, pString, nLength);
    }

    pS = &(tbuf[0]);
  }
  else
  {
    pS = WBAlloc(nLength);
    if(!pS)
    {
      nLength = sizeof(tbuf); // shorten the string and do it anyway, but not all of it.  desperate, yeah.
      goto use_the_stack_buffer;
    }

    memcpy(pS, pString, nLength);
  }


  // TODO:  An alternate method of anti-aliasing
  //        make a font that is twice as big, render it on large-enough pixmap, and then
  //        shrink it down onto the display surface with a raster operation that combines
  //        pixels and (effectively) gives it an anti-aliasing effect.


#ifdef X11WORKBENCH_TOOLKIT_HAVE_XFT
  if(pFont && pFont->pxftFont)
  {
#warning TODO: IMPLEMENT THIS PART for Xft FONTS
  }
  else
#endif // X11WORKBENCH_TOOLKIT_HAVE_XFT
  {
    if(pFont->fsFont)
    {
      WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                     "%s.%d using WB_DRAW_STRING for \"%-.*s\" color=#%08lxH bkgnd=#%08lxH\n",
                     __FUNCTION__, __LINE__, nLength, pString,
                     WBGetForeground(gc), WBGetBackground(gc));

      BEGIN_XCALL_DEBUG_WRAPPER
      WB_DRAW_STRING(pDisplay, drawable, pFont->fsFont, gc->gc, x, y, pS, nLength); // for now, just do this
      END_XCALL_DEBUG_WRAPPER

      if(WBFontEnableAntiAlias())
      {
        WBTextExtent(pFont, pS, nLength, &ext);

        // NOTE:  the x and y are for bottom left when the function was called, not top left (as with specifying a rect or geom)
        __internalDoAntiAlias(pDisplay, drawable, gc, x, y - ext.height, ext.width, ext.height);
      }
    }
    else
    {
      XGCValues gcv, gcv2;

      WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                     "%s.%d using XDrawString for \"%-.*s\" color=#%08lxH bkgnd=#%08lxH\n",
                     __FUNCTION__, __LINE__, nLength, pString,
                     WBGetForeground(gc), WBGetBackground(gc));

      if(pFont->pFontStruct) // legacy font?  switch gc to use this
      {
        memset(&gcv, 0, sizeof(gcv));
        memset(&gcv2, 0, sizeof(gcv2));

        BEGIN_XCALL_DEBUG_WRAPPER
        XGetGCValues(gc->display, gc->gc, GCFont, &gcv);
        END_XCALL_DEBUG_WRAPPER

        memcpy(&gcv2, &gcv, sizeof(gcv));

        // if GC font is not this one, assign it to this one
        if(gcv2.font != pFont->pFontStruct->fid)
        {
          gcv2.font = pFont->pFontStruct->fid; // new font ID

          BEGIN_XCALL_DEBUG_WRAPPER
          XChangeGC(gc->display, gc->gc, GCFont, &gcv2);
          END_XCALL_DEBUG_WRAPPER
        }
      }

      BEGIN_XCALL_DEBUG_WRAPPER
      XDrawString(pDisplay, drawable, gc->gc, x, y, pS, nLength); // for now, just do this
      END_XCALL_DEBUG_WRAPPER

      if(pFont->pFontStruct)
      {
        // put the font back

        BEGIN_XCALL_DEBUG_WRAPPER
        XChangeGC(gc->display, gc->gc, GCFont, &gcv);
        END_XCALL_DEBUG_WRAPPER
      }
    }
  }

  // free up buffer if I allocated it
  if(pS && pS != &(tbuf[0]) && pS != (char *)pString)
  {
    WBFree(pS);
  }
}

// determine ideal font size from desired text and geometry

WB_FONT DTCalcIdealFont(Display *pDisplay, WB_FONTC pRefFont, const char *szText, WB_GEOM *geomBounds)
{
  if(!pRefFont)
  {
    pRefFont = WBGetDefaultFont();
  }




  return NULL; // for now
}


#define INITIAL_DT_WORDS_COUNT 256

static int CheckReAllocWords(DT_WORDS **ppWords)
{
DT_WORDS *pRval = *ppWords;

  if(pRval->nCount + 1 >= pRval->nMax)
  {
    int iNewLen = sizeof(*pRval)
                + ((pRval->nMax & 0xffffff80) + 127) * sizeof(DT_WORD);

    void *p3 = WBReAlloc(pRval, iNewLen);

    if(!p3)
    {
      WB_ERROR_PRINT("%s - ERROR:  not enough memory to allocate new struct (%d required)\n",
                     __FUNCTION__, iNewLen);

      return 0;
    }

    pRval = (DT_WORDS *)p3;
//#ifdef HAVE_MALLOC_USABLE_SIZE
    pRval->nMax = (WBAllocUsableSize(pRval) - sizeof(DT_WORDS))
                / sizeof(DT_WORD)
                + 1; // because DT_WORDS contains one DT_WORD
//#else // HAVE_MALLOC_USABLE_SIZE
    pRval->nMax = (pRval->nMax & 0xffffff80) + 128;
//#endif // HAVE_MALLOC_USABLE_SIZE
  }

  *ppWords = pRval;
  return 1; // OK
}

// NOTES ON UTF-8 AND INTERNATIONAL CHARACTERS
// notes from http://en.wikipedia.org/wiki/UTF-8
//
// # of bits  highest      Byte 1   Byte 2   Byte 3   Byte 4   Byte 5   Byte 6
// -----------------------------------------------------------------------------
//  7 bits    U+007F      0xxxxxxx
// 11 bits    U+07FF      110xxxxx 10xxxxxx
// 16 bits    U+FFFF      1110xxxx 10xxxxxx 10xxxxxx
// 21 bits    U+1FFFFF    11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
// 26 bits    U+3FFFFFF   111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
// 31 bits    U+7FFFFFFF  1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
//
// Because of THIS, it is STILL SAFE to look for <= ' ' for white space, and make some assumptions
// about 0-byte, \n, \r, \t, and other control characters (for now, anyway).
//
// RFC 3629 states "Implementations of the decoding algorithm MUST protect against decoding invalid sequences."
// invalid sequences could (in theory) cause burping to the point of security risk.

// There are also some "print direction" override characters 202C 202D and 202E .
//   http://www.unicodemap.org/details/0x202C/index.html  (POP Directional Formatting)
//   http://www.unicodemap.org/details/0x202D/index.html  (LTR Override)
//   http://www.unicodemap.org/details/0x202E/index.html  (RTL Override)
//
//  also http://www.unicodemap.org/details/0x200E/index.html  (LTR mark)
//       http://www.unicodemap.org/details/0x200E/index.html  (RTL mark)
//       http://www.unicodemap.org/details/0x202A/index.html  (LTR embedding)
//       http://www.unicodemap.org/details/0x202B/index.html  (RTL embedding)
//
//  and these:
//       http://www.unicodemap.org/details/0x2028/index.html  (line separator - alternate LF?)
//       http://www.unicodemap.org/details/0x202A/index.html  (paragraph separator - alternate to CTRL+L ?)
//
//  There are also a handful of various width 'spacing' including NO WIDTH SPACE
//  206A through 206F apparently affect "shaping".  205F through 2069 apparently do nothing
//
// If I pay attention to these, it could put some serious strain on everything.  If I don't, it's not really UTF-8
// However the focus of THIS project is "only implement what is necessary" (and forget the rest).


DT_WORDS * DTGetWordsFromText(Display *pDisplay, WB_FONTC pFont, const char *szText, int iAlignment)
{
  const char *p1, *p2;

  DT_WORDS *pRval = WBAlloc(sizeof(DT_WORDS) + sizeof(DT_WORD) * (INITIAL_DT_WORDS_COUNT - 1));

  if(!pRval)
  {
    return NULL;
  }

  pRval->nCount = 0;
  pRval->szText = szText;
//#ifdef HAVE_MALLOC_USABLE_SIZE
  pRval->nMax = (WBAllocUsableSize(pRval) - sizeof(DT_WORDS)) // calculate actual # of structs it contains
              / sizeof(DT_WORD)
              + 1; // because DT_WORDS contains one DT_WORD
//#else // HAVE_MALLOC_USABLE_SIZE
  pRval->nMax = INITIAL_DT_WORDS_COUNT;
//#endif // HAVE_MALLOC_USABLE_SIZE

  if(!szText || !*szText)
  {
    return pRval;
  }

  p1 = szText;
  while(*p1)
  {
    // find non-white-space and keep 'tabs' on the count/type of white space as well
    // adding entries to 'words' as needed

    while(*p1 && (unsigned char)*p1 <= ' ')
    {
      // TODO:  check for high bit set aka UTF-8 multi-byte chars

      if(*p1 == '\t')  // tab character
      {
        if(!CheckReAllocWords(&pRval))
        {
          WBFree(pRval);
          return NULL; // ERROR
        }

        pRval->aWords[pRval->nCount].pText = NULL;
        pRval->aWords[pRval->nCount].nLength = 1;
        pRval->aWords[pRval->nCount].iIsWhiteSpace = 0;
        pRval->aWords[pRval->nCount].iIsLineFeed = 0;
        pRval->aWords[pRval->nCount].iIsTab = 1;
        pRval->aWords[pRval->nCount].iX = -1;
        pRval->aWords[pRval->nCount].iY = -1;

        while(*(p1 + 1) == '\t')
        {
          p1++;
          pRval->aWords[pRval->nCount].nLength++;
        }

        // use white space string for width
        pRval->aWords[pRval->nCount].iWidth = 0; // NA (calc on the fly)
        pRval->aWords[pRval->nCount].iHeight = 0; // NA (calc on the fly)

        pRval->nCount++;
      }
      else if(*p1 == '\n' || *p1 == '\r')
      {
        if(!CheckReAllocWords(&pRval))
        {
          WBFree(pRval);
          return NULL; // ERROR
        }

        pRval->aWords[pRval->nCount].pText = NULL;
        pRval->aWords[pRval->nCount].nLength = 1;

        if(iAlignment & DTAlignment_SINGLELINE) // treat line feed as white space
        {
          pRval->aWords[pRval->nCount].iIsWhiteSpace = 1;
          pRval->aWords[pRval->nCount].iIsLineFeed = 0;
        }
        else
        {
          pRval->aWords[pRval->nCount].iIsWhiteSpace = 0;
          pRval->aWords[pRval->nCount].iIsLineFeed = 1;
        }

        pRval->aWords[pRval->nCount].iIsTab = 0;
        pRval->aWords[pRval->nCount].iX = -1;
        pRval->aWords[pRval->nCount].iY = -1;

        while(1)
        {
          if(*p1 == '\n' && p1[1] == '\r')
          {
            p1++;
          }
          else if(*p1 == '\r' && p1[1] == '\n')
          {
            p1++;
          }

//          pRval->aWords[pRval->nCount].nLength++;

          if(p1[1] != '\r' && p1[1] != '\n')
          {
            break;
          }

          p1++; // loop consecutive CR,LF
          pRval->aWords[pRval->nCount].nLength++;
        }

        // use white space string for width
        pRval->aWords[pRval->nCount].iWidth = 0; // NA
        pRval->aWords[pRval->nCount].iHeight = 0; // NA

        pRval->nCount++;
      }
      else if((unsigned char)*p1 <= ' ')
      {
        if(!CheckReAllocWords(&pRval))
        {
          WBFree(pRval);
          return NULL; // ERROR
        }

        pRval->aWords[pRval->nCount].pText = NULL;
        pRval->aWords[pRval->nCount].nLength = 1;
        pRval->aWords[pRval->nCount].iIsWhiteSpace = 1;
        pRval->aWords[pRval->nCount].iIsLineFeed = 0;
        pRval->aWords[pRval->nCount].iIsTab = 0;
        pRval->aWords[pRval->nCount].iX = -1;
        pRval->aWords[pRval->nCount].iY = -1;

        p2 = p1;

        while(*(p1 + 1) && (unsigned char)*(p1 + 1) <= ' ' && *(p1 + 1) != '\t' && *(p1 + 1) != '\r' && *(p1 + 1) != '\n')
        {
          p1++;
          pRval->aWords[pRval->nCount].nLength++;
        }

        // use white space string for width
        pRval->aWords[pRval->nCount].iWidth = WBTextWidth(pFont, p2, pRval->aWords[pRval->nCount].nLength);
        pRval->aWords[pRval->nCount].iHeight = WBFontHeight(pFont); // total height of font

        pRval->nCount++;
      }

      p1++;
    }

    if(*p1)
    {
      int iUnderscoreFlag = 0;

      // get length of word

      p2 = p1;
      while(/* *p1 && */ (unsigned char)*p1 > ' ')
      {
        if(*p1 == '_')
        {
          iUnderscoreFlag++;
        }

        p1++;
      }

      if(!CheckReAllocWords(&pRval))
      {
        WBFree(pRval);
        return NULL; // ERROR
      }

      pRval->aWords[pRval->nCount].pText = p2;
      pRval->aWords[pRval->nCount].nLength = p1 - p2;
      pRval->aWords[pRval->nCount].iIsWhiteSpace = 0;
      pRval->aWords[pRval->nCount].iIsTab = 0;
      pRval->aWords[pRval->nCount].iIsLineFeed = 0;
      pRval->aWords[pRval->nCount].iX = -1;
      pRval->aWords[pRval->nCount].iY = -1;

      if(p1 > p2)
      {
        if(!(iAlignment & DTAlignment_UNDERSCORE) || !iUnderscoreFlag)
        {
          pRval->aWords[pRval->nCount].iWidth = WBTextWidth(pFont, p2, p1 - p2);
        }
        else
        {
          // fast and dirty, subtract "length of underscores" from text length
          // assume kerning doesn't alter this at all

          // TODO:  the hard way?

          pRval->aWords[pRval->nCount].iWidth = WBTextWidth(pFont, p2, p1 - p2)
                                              - iUnderscoreFlag * WBTextWidth(pFont, "_", 1);
        }
      }
      else
      {
        pRval->aWords[pRval->nCount].iWidth = 0;
      }

      pRval->aWords[pRval->nCount].iHeight = WBFontHeight(pFont);//pFont->ascent + pFont->descent;  // for now just do this

      pRval->nCount++;
    }
  }

  return pRval;
}

int DTCalcIdealBounds(Display *pDisplay, WB_FONTC pFont, const char *szText, int iTabWidth, unsigned int iTabOrigin,
                      const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment)
{
int iRval;
DT_WORDS *pWords;


  pWords = DTGetWordsFromText(pDisplay, pFont, szText, iAlignment);

  if(!pWords)
  {
    if(prcDest)
      prcDest->left = prcDest->right = prcDest->top = prcDest->bottom = 0;

    return -1; // error
  }

//  InternalDebugDumpWords(pWords);

  iRval = InternalCalcIdealBounds(pDisplay, pFont, pWords, iTabWidth, iTabOrigin, prcSource, prcDest, iAlignment, 0, -1);

  WBFree(pWords);

  return iRval;
}


static void DoHCenterWrappedLines(DT_WORDS *pWords, int iWidth)
{
int i1, i2, i3, iMax;
DT_WORD *pW;


  // For a multi-line string, I need to make sure each line centers
  // correctly.  If the lines break, I allow them to break and wrap
  // but each line that is COMPLETELY within the centered rectangle
  // without wrapping MUST BE RE-CENTERED!!!

  i1 = 0; // this will be my 'word counter'

  do
  {
    i2 = i1; // start of line
    iMax = 0;

    // step 1:  find the end of the current line and calculate
    //          the max width of the line (including 'wrap')

    while(i1 < pWords->nCount)
    {
      pW = &(pWords->aWords[i1]);
      i1++;

      if(pW->iIsLineFeed)
      {
        break; // i1 already incremented, so it will skip Mr. Line Feed on the next iteration
      }

      if(!pW->iIsTab && !pW->iIsWhiteSpace)
      {
        i3 = pW->iX + pW->iWidth; // max extent

        if(i3 > iMax)
        {
          iMax = i3;
        }
      }
    }

    // if 'iMax' is less than 'iWidth', add half the delta
    // to all of the 'iX' values

    i3 = (iWidth - iMax) / 2;

    if(i3 > 0)
    {
      for(; i2 < i1; i2++)
      {
        pW = &(pWords->aWords[i2]);

        if(pW->iX >= 0) // only for the 'assigned' ones
        {
          pW->iX += i3;
        }
      }
    }

  } while(i1 < pWords->nCount);


//  InternalDebugDumpWords(pWords);
}



//  * parameters to this function
//  *
//  * pFont A pointer to an XFontStruct (NULL implies system default font)
//  * pWords The DT_WORDS structure for the text
//  * iTabWidth A positive integer in 'characters', or negative integer in pixels, indicating tab width
//  * iTabOrgin An unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character.
//  * prcSource A pointer to the 'source' bounding rectangle in which the text is intended to fit
//  * prcDest A pointer to the 'destination' bounding rectangle, based on the actual text size
//  * iAlignment The desired text alignment, one or more of the DTAlignment bit flags
//  * iStartLine A zero-based index for the first line on which to start calculating things
//  * iEndLine A zero-based index for the last line on which to start calculating things (-1 for 'all')
//  * zero if the text will fit within prcSource, -1 error, or 1 to indicate that prcDest is larger than prcSource

static int InternalCalcIdealBounds(Display *pDisplay, WB_FONTC pFont, DT_WORDS *pWords, int iTabWidth, unsigned int iTabOrigin,
                                   const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment, int iStartLine, int iEndLine)
{
int iFontWidth, iFontHeight, iFontAscent, iFontDescent, iLineSpacing;  // average font width/height and line spacing
int iHPos, iHPos0, iMaxLen, iLines;
int i1, i2, i3;
//const char *p1;
WB_RECT rctBounds, rctSource;
DT_WORD *pW, *pW2;


  if(!pWords || (!prcSource && !prcDest))
  {
    WB_ERROR_PRINT("%s - returns ERROR (bad values pWords=%p, prcSource=%p, prcDest=%p)\n",
                   __FUNCTION__, pWords, prcSource, prcDest);
    return -1;
  }
  else if(prcSource)
  {
    rctSource.left = prcSource->left;
    rctSource.top = prcSource->top;
    rctSource.right = prcSource->right;
    rctSource.bottom = prcSource->bottom;
  }
  else
  {
    bzero(&rctSource, sizeof(rctSource));
  }

  memcpy(&rctBounds, &rctSource, sizeof(rctBounds)); // make copy of it as 'rctSource' (for now)

  if(!pFont)
  {
    pFont = WBGetDefaultFont();
    if(!pFont)
    {
      WB_ERROR_PRINT("%s - returns ERROR (no font)\n", __FUNCTION__);
      return -1;
    }
  }

//  // TEMPORARY
//  WB_ERROR_PRINT("%s - TEMPORARY:  bounds rectangle is INITIALLY %d,%d,%d,%d\n",
//                 __FUNCTION__, rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);

  // TODO:  make use of iStartLine and iEndLine - for now "do all" every time so I can avoid a re-write

  // get a few things straight 'round here

  iFontWidth = WBFontAvgCharWidth(pFont);

  if(!iFontWidth)
  {
    iFontWidth = WBTextWidth(pFont, " ", 1);  // width of a single space
  }

  iFontAscent = WBFontAscent(pFont);
  iFontDescent = WBFontDescent(pFont);
  iFontHeight = iFontAscent + iFontDescent; // cache for performance

  // for now, line spacing equals 1/2 descent or 2 pixels
  iLineSpacing = iFontDescent / 2;
  if(iLineSpacing < 2)
  {
    iLineSpacing = 2;
  }

  if(iTabWidth < 0)
  {
    iTabWidth = -iTabWidth;  // in pixels
  }
  else
  {
    iTabOrigin *= iFontWidth;
    iTabWidth *= iFontWidth;  // convert chars to pixels
  }

  // step 1:  trial fit within the current rectangle

  iHPos0 = iHPos = rctSource.left;

  iMaxLen = 0;
  iLines = 0;

  // initial text width and # of lines calculation.

  for(i1=0; i1 < pWords->nCount; i1++)
  {
    pW = &(pWords->aWords[i1]);

    if(pW->iIsWhiteSpace)
    {
      pW->iY = pW->iX = -1; // NA

      // before I start adding white space, see if there is
      // any NON-WHITE SPACE following this entry...

      if(iAlignment & DTAlignment_ALLOW_TRAILING)
      {
        iHPos += pW->iWidth; // it's ok to use the TOTAL width of this white space
      }
      else
      {
        for(i2=i1 + 1; i2 < pWords->nCount; i2++)
        {
          pW2 = &(pWords->aWords[i2]);

          if(!pW2->iIsWhiteSpace && !pW2->iIsTab && !pW2->iIsLineFeed)
          {
            iHPos += pW->iWidth; // it's ok to use the width of this white space
            break;
          }
          else if(pW2->iIsLineFeed)
          {
            break; // end of line (trailing white space will be ignored)
          }
        }
      }
    }
    else if(pW->iIsTab)
    {
      pW->iY = pW->iX = -1; // NA

      // before I start adding white space for tabs, see if there is
      // any NON-WHITE SPACE following this entry...

      if(iAlignment & DTAlignment_ALLOW_TRAILING)
      {
do_the_tab:
        if(iAlignment & (DTAlignment_HCENTER | DTAlignment_HJUSTIFY)) // no tabbing for center/justify
        {
          iHPos += pW->nLength * iFontWidth;  // treat it as regular white space
        }
        else
        {
          i3 = (iHPos - iHPos0 + iTabOrigin) % iTabWidth; // remaining space to tab over

          if(!i3)
          {
            iHPos += iTabWidth; // tab out the entire distance
          }
          else
          {
            iHPos += i3; // tab out "the remainder"
          }

          if(pW->nLength > 1) // check for multiple tabs
          {
            iHPos += iTabWidth * (pW->nLength - 1); // additional tabs
          }
        }
      }
      else
      {
        for(i2=i1 + 1; i2 < pWords->nCount; i2++)
        {
          pW2 = &(pWords->aWords[i2]);
          pW2->iX = pW2->iY = -1; // because I'm skipping them

          if(!pW2->iIsWhiteSpace && !pW2->iIsTab && !pW2->iIsLineFeed)
          {
            goto do_the_tab; // cleaner code with label
          }
          else if(pW2->iIsLineFeed)
          {
            break; // end of line (trailing tabs will be ignored)
          }
        }

        // if I get here, only white space remains at the end of the DT_WORD array.  Ignore it.
        break;
      }
    }
    else if(pW->iIsLineFeed)
    {
      pW->iY = pW->iX = -1; // NA

      if(iMaxLen < iHPos - iHPos0)
      {
        iMaxLen = iHPos - iHPos0;
      }

      if(iHPos > iHPos0 &&           // there is actual text present on this line
         (i1 + 1) == pWords->nCount) // the last entry?  The text ends in one or more line feeds
      {
        // TODO:  see if it's just a bunch of blank lines following the text
        //        and consider ignoring them ALL if it makes sense to do so

        iLines += pW->nLength - 1; // at the end, the final line feed doesn't "count" unless it's by itself
      }
      else
      {
        iLines += pW->nLength;    // add ALL of the line feeds to the line count (more to come)
      }

      iHPos = iHPos0;
    }
    else
    {
      if(!iLines) // this handles blank text, which will show up with "zero lines"
      {
        iLines++;  // indicate at least one line of printable stuff
      }

      pW->iX = iHPos - iHPos0;             // relative X position
      pW->iY = (iLines - 1) * iFontHeight + iFontAscent;  // relative Y position for 'base of text'

      iHPos += pW->iWidth;
    }

    if(iHPos > iMaxLen)
    {
      iMaxLen = iHPos;
    }
  }

  // Now I know the current (unmodified) text extents.  Let's see what they SHOULD be

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d - iHPos=%d, iMaxLen=%d, iLines=%d, iFontHeight=%d, *=%d\n", __FUNCTION__, __LINE__,
                 iHPos, iMaxLen, iLines, iFontHeight, (iLines * iFontHeight));

  rctBounds.left = rctSource.left;
  rctBounds.top  = rctSource.top;
  rctBounds.right = /*rctBounds.left +*/ iMaxLen;
  rctBounds.bottom = rctBounds.top + (iLines * iFontHeight);

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d - rctSource %d,%d,%d,%d  rctBounds: %d,%d,%d,%d\n", __FUNCTION__, __LINE__,
                 rctSource.left, rctSource.top, rctSource.right, rctSource.bottom,
                 rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);

  if(iLines > 1)
  {
    WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                   "%s.%d - %d lines - font height %d, line spacing %d\n",
                   __FUNCTION__, __LINE__, iLines, iFontHeight, iLineSpacing);
    rctBounds.bottom += (iLines - 1) * iLineSpacing; // inter-line spacing
  }

#ifndef NO_DEBUG

  if(rctBounds.top < rctSource.top || rctBounds.bottom > rctSource.bottom)
  {
    WB_ERROR_PRINT("WARNING:  %s.%d - source rectangle too small, alignment flags may not work\n", __FUNCTION__, __LINE__);
    WB_ERROR_PRINT("          %d,%d,%d,%d bounds  vs  source %d,%d,%d,%d\n",
                   rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom,
                   rctSource.left, rctSource.top, rctSource.right, rctSource.bottom);
    WB_ERROR_PRINT("          Lines: %d  Font ascent=%d, descent=%d, height=%d, line spacing %d\n",
                   iLines, iFontAscent, iFontDescent, iFontHeight, iLineSpacing);
  }
  else
  {
    WB_DEBUG_PRINT(DebugLevel_Heavy | DebugSubSystem_DrawText,
                   "INFO:  %s - source rectangle seems to fit\n", __FUNCTION__);
    WB_DEBUG_PRINT(DebugLevel_Heavy | DebugSubSystem_DrawText,
                   "          %d,%d,%d,%d bounds  vs  source %d,%d,%d,%d\n",
                   rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom,
                   rctSource.left, rctSource.top, rctSource.right, rctSource.bottom);
    WB_DEBUG_PRINT(DebugLevel_Heavy | DebugSubSystem_DrawText,
                   "          Lines: %d  Font ascent=%d, descent=%d, height=%d, line spacing %d\n",
                   iLines, iFontAscent, iFontDescent, iFontHeight, iLineSpacing);
  }

#endif // NO_DEBUG

  if(rctBounds.right <= rctSource.right &&
     rctBounds.bottom <= rctSource.bottom)
  {
it_fits:
    WB_DEBUG_PRINT(DebugLevel_Heavy | DebugSubSystem_DrawText,
                   "%s.%d - 'it fits' bounds rectangle is %d,%d,%d,%d  iAlighment=%d (%08xH)\n",
                   __FUNCTION__, __LINE__,
                   rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom,
                   iAlignment, iAlignment);

    // it looks like it can fit properly without any additional effort.
    // based on the alignment flags, I will return now with the results.

    // TODO:  check if any alignment flags might prevent me from returning now...

    if(prcDest) // caller wants the actual rectangle
    {
      if(iAlignment & DTAlignment_NO_SHRINK)
      {
        rctBounds.right = rctSource.right;
        rctBounds.bottom = rctSource.bottom;
      }
      else
      {
        switch(iAlignment & DTAlignment_HMASK)
        {
          case DTAlignment_HJUSTIFY: // treat like 'center' for now
          case DTAlignment_HCENTER:
            WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                           "%s.%d - here I am, %d, %d, %d, %d\n", __FUNCTION__, __LINE__,
                           rctSource.left, rctSource.right, rctBounds.left, rctBounds.right);

            i1 = rctSource.right - rctBounds.right;
            i1 -= (i1 >> 1); // so that it's balanced properly, do it THIS way
            rctBounds.left += i1;
            rctBounds.right += i1;

            // For a multi-line string, I need to make sure each line centers
            // correctly.  If the lines break, I allow them to break and wrap
            // but each line that is COMPLETELY within the centered rectangle
            // without wrapping MUST BE RE-CENTERED!!!

            DoHCenterWrappedLines(pWords, rctBounds.right - rctBounds.left);

            break;

          case DTAlignment_HLEFT:
            break; // no changes
          case DTAlignment_HRIGHT:
            rctBounds.left += rctSource.right - rctBounds.right;
            rctBounds.right = rctSource.right;
            break;
        }
      }

      switch(iAlignment & DTAlignment_VMASK)
      {
        case DTAlignment_VTOP:
          break;
        case DTAlignment_VBOTTOM:
          rctBounds.top += rctSource.bottom - rctBounds.bottom;
          rctBounds.bottom = rctSource.bottom;
          break;
        case DTAlignment_VCENTER:
          i1 = ((rctSource.bottom - rctBounds.bottom + 1) >> 1) - 1; // favors being slightly closer to top
          rctBounds.top += i1;
          rctBounds.bottom += i1;
          break;

        case DTAlignment_VCENTERASCENT:  // only works properly with single line
          i2 = iFontDescent >> 1; // 1/2 ascent is top + a / 2; 1/2 font is top + (a + d) / 2; diff is d / 2
          i1 = ((rctSource.bottom - rctBounds.bottom + 1) >> 1) - 1; // favors being slightly closer to top
          i1 -= i2;
          if(i1 > 0) // subtracting i2 from i1 didn't make it negative
          {
            rctBounds.top += i1;
            rctBounds.bottom += i1;
          }
          break;

        case DTAlignment_VCENTERBASELINE:
          i2 = (iFontAscent - iFontDescent) >> 1; //  ascent is top + a; 1/2 font is top + (a + d) / 2; diff is (a - d) / 2
          i1 = ((rctSource.bottom - rctBounds.bottom + 1) >> 1) - 1; // favors being slightly closer to top
          i1 += i2;
          if(i1 < rctSource.bottom) // adding i2 won't exceed 'bottom'
          {
            rctBounds.top += i1;
            rctBounds.bottom += i1;
          }
          else // adding i2 exceeds bottom, so just use bottom
          {
            rctBounds.top += rctSource.bottom - rctBounds.bottom;
            rctBounds.bottom = rctSource.bottom;
          }
          break;

        case DTAlignment_VTOPHALF:
        case DTAlignment_VTBOTTOMHALF:
          break; // reserved
      }

//      WB_ERROR_PRINT("%s - TEMPORARY:  'aligned' bounds rectangle is %d,%d,%d,%d\n",
//                     __FUNCTION__, rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);

      memcpy(prcDest, &rctBounds, sizeof(*prcDest));
    }

    return 0;
  }

  // the simplest solutions are usually the best.  If the text extends past the horizontal
  // border but does not extend past the vertical border, attempt to wrap it to make it fit.
  // This is probably the most common solution.

  if(rctSource.right > 0 && // if prcSource is NULL, rctSource.right will be zero
     rctBounds.right > rctSource.right &&
     rctBounds.bottom <= rctSource.bottom &&
     !(iAlignment & DTAlignment_NO_WORD_WRAP)) // disable this if I'm bit allowing word wrap
  {
    iMaxLen = 0;
    iHPos0 = iHPos = rctSource.left;

    // TEMPORARY
//    WB_ERROR_PRINT("%s - TEMPORARY:  'needs text wrap' bounds rectangle is %d,%d,%d,%d\n",
//                   __FUNCTION__, rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);



    for(i1=0; i1 < pWords->nCount; i1++)
    {
      pW = &(pWords->aWords[i1]);

      if(pW->iIsWhiteSpace)
      {
        pW->iY = pW->iX = -1; // NA

        // before I start adding white space, see if there is
        // any NON-WHITE SPACE following this entry...

        if(iAlignment & DTAlignment_ALLOW_TRAILING)
        {
          iHPos += pW->iWidth; // it's ok to use the width of this white space
        }
        else
        {
          for(i2=i1 + 1; i2 < pWords->nCount; i2++)
          {
            pW2 = &(pWords->aWords[i2]);

            if(!pW2->iIsWhiteSpace && !pW2->iIsTab && !pW2->iIsLineFeed)
            {
              iHPos += pW->iWidth; // it's ok to use the width of this white space
              break;
            }
            else if(pW2->iIsLineFeed)
            {
              break; // end of line (trailing white space will be ignored)
            }
          }
        }
      }
      else if(pW->iIsTab)
      {
        pW->iY = pW->iX = -1; // NA

        // before I start adding white space for tabs, see if there is
        // any NON-WHITE SPACE following this entry...

        if(iAlignment & DTAlignment_ALLOW_TRAILING) // all bets are off when line-wrap happens
        {
do_the_tab2:
          if(iAlignment & (DTAlignment_HCENTER | DTAlignment_HJUSTIFY)) // no tabbing for center/justify
          {
            iHPos += pW->nLength * iFontWidth;  // treat it as regular white space
          }
          else
          {
            i3 = (iHPos - iHPos0 + iTabOrigin) % iTabWidth;

            if(!i3)
            {
              iHPos += iTabWidth; // tab out the entire distance
            }
            else
            {
              iHPos += i3; // tab out "the remainder"
            }

            if(pW->nLength > 1) // check for multiple tabs
            {
              iHPos += iTabWidth * (pW->nLength - 1); // additional tabs
            }
          }

          if(iHPos > rctSource.right) // tab goes past the end
          {
            // treat it like a line feed, but 'trim off' any additional white space first

            while((i1 + 1) < pWords->nCount)
            {
              pW2 = &(pWords->aWords[i1]);
              pW2->iX = pW2->iY = -1; // because I'm probably skipping them

              if(!pW2->iIsWhiteSpace && !pW2->iIsTab)
              {
                break; // if next item isn't white space, bust out of the loop
              }
              else if(pW2->iIsLineFeed)
              {
                i1++; // absorb THIS line feed since I'm doing one now
                break;
              }

              i1++; // keep skipping white space
            }

            // Do a line feed first (nearly the same as 'line feed' code, below)
//do_a_line_feed2:
            if(iMaxLen < iHPos - iHPos0)
            {
              iMaxLen = iHPos - iHPos0;
            }

            if(iHPos > iHPos0 &&           // there is actual text present on this line
               (i1 + 1) == pWords->nCount) // the last entry?  The text ends in one or more line feeds
            {
              // TODO:  see if it's just a bunch of blank lines following the text
              //        and consider ignoring them ALL if it makes sense to do so

              // at the end, the final line feed doesn't "count" unless it's by itself
            }
            else
            {
              iLines++;  // only ONE line feed here...
            }

            iHPos = iHPos0;
          }
        }
        else
        {
          for(i2=i1 + 1; i2 < pWords->nCount; i2++)
          {
            pW2 = &(pWords->aWords[i2]);
            pW2->iX = pW2->iY = -1; // because I'm going to skip them

            if(!pW2->iIsWhiteSpace && !pW2->iIsTab && !pW2->iIsLineFeed)
            {
              goto do_the_tab2; // cleaner code with label
            }
            else if(pW2->iIsLineFeed)
            {
              i1 = i2 - 1; // skip all of the white space
              break; // this will cause the line feed to become "the next thing" and I'll end the line
            }
          }

          // if I get here, only white space remains at the end of the current 'line' (so ignore it)
          break;
        }
      }
      else if(pW->iIsLineFeed)
      {
        pW->iY = pW->iX = -1; // NA

        if(iMaxLen < iHPos - iHPos0)
        {
          iMaxLen = iHPos - iHPos0;
        }

        if(iHPos > iHPos0 &&           // there is actual text present on this line
           (i1 + 1) == pWords->nCount) // the last entry?  The text ends in one or more line feeds
        {
          // TODO:  see if it's just a bunch of blank lines following the text
          //        and consider ignoring them ALL if it makes sense to do so

          iLines += pW->nLength - 1; // at the end, the final line feed doesn't "count" unless it's by itself
        }
        else
        {
          iLines += pW->nLength;    // add ALL of the line feeds to the line count (more to come)
        }

        iHPos = iHPos0;
      }
      else
      {
        if(!iLines) // this handles blank text, which will show up with "zero lines"
        {
          iLines++;  // indicate at least one line of printable stuff

          if(iHPos + pW->iWidth > rctSource.right) // word is "too wide"
          {
            goto will_not_fit;  // generic bailout point, doesn't attempt to gerrymander the boundary rectangle
          }
        }

        pW->iX = iHPos - iHPos0;        // relative X position
        pW->iY = (iLines - 1) * iFontHeight + iFontAscent;  // relative Y position for 'base of text'

        if(iHPos + pW->iWidth > rctSource.right) // word is "too wide"
        {
          // Do a line feed first (nearly the same as 'line feed' code, above)

          if(iMaxLen < iHPos - iHPos0)
          {
            iMaxLen = iHPos - iHPos0;
          }

          if(iHPos > iHPos0 &&           // there is actual text present on this line
             (i1 + 1) == pWords->nCount) // the last entry?  The text ends in one or more line feeds
          {
            // TODO:  see if it's just a bunch of blank lines following the text
            //        and consider ignoring them ALL if it makes sense to do so

            // at the end, the final line feed doesn't "count" unless it's by itself
          }
          else
          {
            iLines++;  // only ONE line feed here...
          }

          iHPos = iHPos0;
          i1--; // "repeat this word"
          continue;
        }

        iHPos += pW->iWidth;
      }
    }

    if(iHPos > iMaxLen)
    {
      iMaxLen = iHPos;
    }
  }

  // re-calc boundary, see if it fits NOW

  rctBounds.left = rctSource.left;
  rctBounds.top  = rctSource.top;
  rctBounds.right = rctBounds.left + iMaxLen;
  rctBounds.bottom = rctBounds.top + (iLines * iFontHeight);

  if(iLines > 1)
  {
    rctBounds.bottom += (iLines - 1) * iLineSpacing; // inter-line spacing
  }

  if(rctBounds.right <= rctSource.right &&
     rctBounds.bottom <= rctSource.bottom)
  {
    goto it_fits;
  }

will_not_fit:

  WB_DEBUG_PRINT(DebugLevel_Heavy,
                 "%s - 'it does not fit' bounds rectangle is %d,%d,%d,%d\n",
                 __FUNCTION__, rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);

  if(!(iAlignment & DTAlignment_PRINTING))
  {
    // At this point we know it's not going to fit in the specified rectangle.  It will be
    // necessary to ESTIMATE the "ideal" rectangle for the text.

    //            re-sizing the rectangle, ideal dimensions vs actual dimensions

    // since wrapped text looks SO much better when it maintains a reasonable height/width ratio,
    // try squeezing the text around to make this happen.  The most reasonable first trial will
    // be to wrap the text at 3/4 iMaxLen, then 2/3 iMaxLen, then 1/2 iMaxLen, etc. until I end
    // up with a decent height/width ratio.  To facilitate this I should throw out anything that
    // has a font pixel ratio of more than 16:1 (this would be appx 20 characters x 1 line) or
    // less than 4 : 1 (this would be appx 5 characters x 1 line).  If I can't achieve either of
    // these goals, leave 'prcDest' as it is right now.

    // if rctSource is an empty rectangle, I'll need to create a set of dimensions that makes
    // good visual sense, based on the contents of the string.

    // First step:  'ideal' dimensions


    // Since the above didn't work, try half-split convergence

    // TODO:  implement these things
  }

  if(prcDest)
  {
    memcpy(prcDest, &rctBounds, sizeof(*prcDest));
  }

  return 1; // for now (until I complete writing this)
}


//WB_DEFINE_PROFILE(anti_alias);
//WB_DEFINE_PROFILE(anti_alias2);
//WB_DEFINE_PROFILE(anti_alias3);
//WB_DEFINE_PROFILE(anti_alias4);
//WB_DEFINE_PROFILE(anti_alias5);

static void __internalDoAntiAlias(Display *pDisplay, Drawable dw, WBGC gc, int iX, int iY, int iWidth, int iHeight)
{
XStandardColormap map;
XImage *pImage;
unsigned long lPixel;
WB_GEOM geom;
Window winRoot; // unused, but I still need it
int iX0=0, iY0=0;
unsigned int iWidth0=0, iHeight0=0, iBorder;
unsigned int uiDepth = 0;
Pixmap pxTemp;
WBGC gc2;
Region rgnClip;


//  WB_ENABLE_PROFILE(anti_alias, "overall");
//  WB_ENABLE_PROFILE(anti_alias2, "performing XCopyArea");
//  WB_ENABLE_PROFILE(anti_alias3, "performing WBSimpleAntiAliasImage");
//  WB_ENABLE_PROFILE(anti_alias4, "performing WBXGetImage");
//  WB_ENABLE_PROFILE(anti_alias5, "performing WBXPutImage");

  lPixel = WBGetGCFGColor(gc); // current foreground color

  pxTemp = None;
  rgnClip = None;
  gc2 = None;

  WBDefaultStandardColormap(pDisplay, &map);

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d - geom %d,%d,%d,%d\n", __FUNCTION__, __LINE__, iX, iY, iWidth, iHeight);

  // use XGetGeometry to obtain the characteristics of the pixmap or window.  iX and iY SHOULD be zero...
  BEGIN_XCALL_DEBUG_WRAPPER
  XGetGeometry(pDisplay, dw, &winRoot, &iX0, &iY0, &iWidth0, &iHeight0, &iBorder, &uiDepth);
  END_XCALL_DEBUG_WRAPPER

  geom.x = 0;
  geom.y = 0;

  if(iX >= iWidth0 + iX0 || iY >= iHeight0 + iY0)
  {
    WB_ERROR_PRINT("ERROR: %s.%d - drawable smaller than requested geom:  %d,%d,%d,%d  %d,%d,%d,%d\n",
                 __FUNCTION__, __LINE__, iX0, iY0, iWidth0, iHeight0,
                 iX, iY, iWidth, iHeight);
    return;
  }

//  WB_START_PROFILE(anti_alias);

  iWidth0 = (iWidth0 + iX0) - iX; // right - 'new left' = 'new width'
  iHeight0 = (iHeight0 + iY0) - iY; // adjust so that it matches the 'remaining space' from X,Y

  // to avoid errors from WBXGetImage, if the requested geometry is too big, reduce
  // the width/height to the actual width/height of the Drawable

  if(iWidth0 < iWidth)
  {
    geom.width = iWidth0;
  }
  else
  {
    geom.width = iWidth;
  }

  if(iHeight0 < iHeight)
  {
    geom.height = iHeight0;
  }
  else
  {
    geom.height = iHeight;
  }

  geom.x = 0;
  geom.y = 0;

  BEGIN_XCALL_DEBUG_WRAPPER
  pxTemp = XCreatePixmap(pDisplay, dw, geom.width, geom.height,
                         DefaultDepth(pDisplay, DefaultScreen(pDisplay)));
  END_XCALL_DEBUG_WRAPPER

  if(pxTemp == None)
  {
    WB_ERROR_PRINT("ERROR: %s - unable to create temporary pixmap via XCreatePixmap()\n", __FUNCTION__);
    goto the_end;
  }

  rgnClip = WBGeomToRegion(&geom);
  if(rgnClip == None)
  {
    WB_ERROR_PRINT("ERROR: %s - unable to create temporary clipping region\n", __FUNCTION__);
    goto the_end;
  }

  gc2 = WBCopyDrawableGC(pDisplay, dw, gc); // everything the same except the clip region
  if(gc2 == None)
  {
    WB_ERROR_PRINT("ERROR: %s - unable to create temporary WBGC copy\n", __FUNCTION__);

    goto the_end;
  }

  WBSetRegion(gc2, rgnClip); // new clipping region

//  WB_START_PROFILE(anti_alias2);

  BEGIN_XCALL_DEBUG_WRAPPER
  XCopyArea(pDisplay, dw, pxTemp, gc2->gc,
            iX, iY, geom.width, geom.height, 0, 0);
  END_XCALL_DEBUG_WRAPPER

//  WB_STOP_PROFILE(anti_alias2);

//  WB_ERROR_PRINT("TEMPORARY: %s - geom %d,%d,%d,%d  (%d,%d)\n",
//                 __FUNCTION__, geom.x, geom.y, geom.width, geom.height, iWidth0, iHeight0);


  // create an XImage, and perform the operation on that

//  WB_START_PROFILE(anti_alias4);
  pImage = WBXGetImage(pDisplay, pxTemp, 0, 0, geom.width, geom.height, 0xffffffff, ZPixmap);
//  WB_STOP_PROFILE(anti_alias4);

  if(!pImage)
  {
    WB_ERROR_PRINT("ERROR: %s - unable to create image via WBXGetImage()\n", __FUNCTION__);
  }
  else
  {
//    WB_START_PROFILE(anti_alias3);

    WBSimpleAntiAliasImage(&map, pImage, lPixel, &geom);

//    WB_STOP_PROFILE(anti_alias3);

//    WB_START_PROFILE(anti_alias5);

    WBXPutImage(pDisplay, pxTemp, gc2, pImage, 0, 0, 0, 0, geom.width, geom.height);

//    WB_STOP_PROFILE(anti_alias5);

    BEGIN_XCALL_DEBUG_WRAPPER
//    WB_START_PROFILE(anti_alias2);
    XCopyArea(pDisplay, pxTemp, dw, gc->gc, // this one uses 'gc' when copying BACK to 'dw'
              0, 0, geom.width, geom.height, iX, iY);
//    WB_STOP_PROFILE(anti_alias2);
    END_XCALL_DEBUG_WRAPPER

    // I can destroy the image now
    WBXDestroyImage(pImage);
  }

the_end:

//  WB_STOP_PROFILE(anti_alias);

  BEGIN_XCALL_DEBUG_WRAPPER
  if(gc2 != NULL)
  {
    WBFreeGC(gc2);
  }
  if(pxTemp != None)
  {
    XFreePixmap(pDisplay, pxTemp);
  }
  if(rgnClip != None)
  {
    XDestroyRegion(rgnClip);
  }
  END_XCALL_DEBUG_WRAPPER

}


void DTDrawSingleLineText(WB_FONTC pFont, const char *szText, Display *pDisplay, WBGC gc, Drawable dw,
                          int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
{
  DTDrawMultiLineText(pFont, szText, pDisplay, gc, dw, iTabWidth, iTabOrigin, prcBounds,
                      iAlignment | DTAlignment_SINGLELINE | DTAlignment_NO_WORD_WRAP);
}

void DTDrawMultiLineText(WB_FONTC pFont, const char *szText, Display *pDisplay, WBGC gc, Drawable dw,
                         int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
{
int i1, i2, i3, iH, iH2, iFontDescent; //, iW2, iFontWidth, iFontHeight;
DT_WORDS *pWords;
DT_WORD *pW;
WB_RECT rcDest;
XPoint xpt[3];
XCharStruct xMaxBounds;


  if(!pFont)
  {
    pFont = WBGetDefaultFont();
    if(!pFont)
    {
      WB_ERROR_PRINT("%s - ERROR:  WBGetDefaultFont returns NULL\n",
                     __FUNCTION__);

      return; // bad
    }
  }

  if(iAlignment & DTAlignment_SINGLELINE)
  {
    iAlignment |= DTAlignment_NO_WORD_WRAP; // make sure
  }


  // get a few things straight 'round here

// NOTE:  iFontWidth and iFontHeight not being used; commented out because of linux gcc warnings
//  iFontWidth = WBFontSetAvgCharWidth(pDisplay, pFont); // was WBTextWidth(pFont, " ", 1);  // width of a single space
//  iFontHeight = pFont->ascent + pFont->descent;

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d call to DTGetWordsFromText\n", __FUNCTION__, __LINE__);
  pWords = DTGetWordsFromText(pDisplay, pFont, szText, iAlignment);

  if(!pWords)
  {
    WB_ERROR_PRINT("%s - ERROR:  DTGetWordsFromText returns NULL\n",
                   __FUNCTION__);

    return; // error
  }

  memcpy(&rcDest, prcBounds, sizeof(rcDest));

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d bounds rectangle is INITIALLY %d,%d,%d,%d\n",
                 __FUNCTION__, __LINE__, rcDest.left, rcDest.top, rcDest.right, rcDest.bottom);

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d call to InternalCalcIdealBounds\n", __FUNCTION__, __LINE__);
  if(InternalCalcIdealBounds(pDisplay, pFont, pWords, iTabWidth, iTabOrigin, prcBounds, &rcDest,
                             iAlignment | DTAlignment_PRINTING, 0, -1)
    < 0)
  {
    InternalDebugDumpWords(pWords);

    WBFree(pWords);

    WB_ERROR_PRINT("%s - ERROR:  InternalCalcIdealBounds returns error\n",
                   __FUNCTION__);

    return; // bad (error)
  }

  iFontDescent = WBFontDescent(pFont);
  xMaxBounds = WBFontMaxBounds(pFont); // font's 'max_bounds' structure member, maximized for all of them

//  InternalDebugDumpWords(pWords);

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d bounds rectangle is NOW %d,%d,%d,%d\n",
                 __FUNCTION__, __LINE__, rcDest.left, rcDest.top, rcDest.right, rcDest.bottom);

  // this function assumes I do not erase the background.  TODO:  flag for that?

  WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                 "%s.%d loop to display 'words'\n", __FUNCTION__, __LINE__);
  for(i1=0; i1 < pWords->nCount; i1++)
  {
    pW = &(pWords->aWords[i1]);

    if(pW->iX >= 0 && pW->iY >= 0 && pW->iWidth > 0)
    {
      if(!(iAlignment & DTAlignment_UNDERSCORE) ||
         !memchr(pW->pText, '_', pW->nLength))
      {
        // normal string drawing - no underscores to deal with

      WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                     "%s.%d DTDrawString at %d,%d  %d chars of %s\n",
                     __FUNCTION__, __LINE__, rcDest.left + pW->iX, rcDest.top + pW->iY, pW->nLength, pW->pText);

        // draw the entire string. 'pW->iY' is the BASE of the font
        DTDrawString(pDisplay, dw, pFont, gc, rcDest.left + pW->iX, rcDest.top + pW->iY,
                     pW->pText, pW->nLength);

        WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                       "%s.%d normal display of \"%-.*s\"\n", __FUNCTION__, __LINE__, pW->nLength, pW->pText);
      }
      else
      {
        iH = rcDest.left + pW->iX;
        iH2 = -1; // horizontal position of NEXT underscore to display (corresponds to character index 'i3')

        WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                       "%s.%d loop to handle underscores\n", __FUNCTION__, __LINE__);
        for(i2=0, i3=0; i2 < pW->nLength; )
        {
          if(pW->pText[i2] == '_')
          {
            if((i2 + 1) >= pW->nLength)
            {
              break;  // this will print the '_' normally
            }
            else if(i3 && i3 == i2) // a double-underscore
            {
              i2++;
              continue; // i'm going to print this as-is
            }

            WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                           "%s.%d DTDrawString at %d,%d  %d chars of %s\n",
                           __FUNCTION__, __LINE__, iH, rcDest.top + pW->iY, pW->nLength - i3, (char *)(pW->pText) + i3);

            // print i3 through i2 - 1.  'pW->iY' is the BASE of the font
            DTDrawString(pDisplay, dw, pFont, gc, iH, rcDest.top + pW->iY,
                         (const char *)(pW->pText) + i3, i2 - i3);

            // draw the preceding underscore
            if(iH2 >= 0)
            {
              xpt[0].x=iH2;
              xpt[0].y=rcDest.top + pW->iY + iFontDescent + 1;// + pFont->max_bounds.ascent;
              xpt[1].x=iH + WBTextWidth(pFont, (char *)(pW->pText) + i3, 1); // width of character
              xpt[1].y=xpt[0].y;

              //BEGIN_XCALL_DEBUG_WRAPPER
              WBDrawLines(pDisplay, dw, gc, xpt, 2, CoordModeOrigin);
              //END_XCALL_DEBUG_WRAPPER
            }

            // advance the pointer
            iH += WBTextWidth(pFont, (char *)(pW->pText) + i3, i2 - i3);

            iH2 = iH; // next underscore's position

            i2++;
            i3 = i2; // the next text character
          }
          else
          {
            i2++;
          }
        }

        if(i3 < pW->nLength)
        {
          // draw the last part of the string.  'pW->iY' is the BASE of the font
          DTDrawString(pDisplay, dw, pFont, gc, iH, rcDest.top + pW->iY,
                       (const char *)(pW->pText) + i3, pW->nLength - i3);

          // draw the preceding underscore
          if(iH >= 0)
          {
            xpt[0].x=iH;
            xpt[0].y=rcDest.top + pW->iY + xMaxBounds.descent + 1;// + pFont->max_bounds.ascent;
            xpt[1].x=iH + WBTextWidth(pFont, (char *)(pW->pText) + i3, 1); // width of character
            xpt[1].y=xpt[0].y;

            //BEGIN_XCALL_DEBUG_WRAPPER
            WBDrawLines(pDisplay, dw, gc, xpt, 2, CoordModeOrigin);
            //END_XCALL_DEBUG_WRAPPER
          }
        }
      }

    }
  }

  // now that I have drawn the text, anti-alias it if I set the anti-alias flag

  if(WBFontEnableAntiAlias() &&
     (iAlignment & DTAlignment_ANTIALIAS))
  {
    WB_DEBUG_PRINT(DebugLevel_Verbose | DebugSubSystem_DrawText,
                   "%s.%d call to __internalDoAntiAlias\n", __FUNCTION__, __LINE__);
    __internalDoAntiAlias(pDisplay, dw, gc,
                          rcDest.left, rcDest.top,
                          rcDest.right - rcDest.left,
                          rcDest.bottom - rcDest.top);
  }

  WBFree(pWords);
}


// TODO:  consider whether either of these is really necessary.  each line could stand on its own,
//        and it would be more efficient.  where it MIGHT help is a simple 'edit window' with limited
//        text length, which could be stored as a 'DT_WORDS'. Probably NOT practical.
//        (so perhaps these should be deprecated?)


void DTPreRender(Display *pDisplay, WB_FONTC pFont, DT_WORDS *pWords, int iTabWidth, int iTabOrigin,
                 WB_RECT *prcBounds, int iAlignment, int iStartLine, int iEndLine)
{
WB_RECT rcDest;


  if(!pDisplay)
  {
    pDisplay = WBGetDefaultDisplay();
  }

  if(!pFont)
  {
    pFont = WBGetDefaultFont();
    if(!pFont)
    {
      WB_ERROR_PRINT("%s - ERROR:  WBGetDefaultFont returns NULL\n",
                     __FUNCTION__);

      return; // bad
    }
  }

  if(iAlignment & DTAlignment_SINGLELINE)
  {
    iAlignment |= DTAlignment_NO_WORD_WRAP; // make sure
  }

  memcpy(&rcDest, prcBounds, sizeof(rcDest));

  if(InternalCalcIdealBounds(pDisplay, pFont, pWords, iTabWidth, iTabOrigin, prcBounds, &rcDest,
                             iAlignment | DTAlignment_PRINTING, iStartLine, iEndLine)
    < 0)
  {
    InternalDebugDumpWords(pWords);

    WB_ERROR_PRINT("%s - ERROR:  InternalCalcIdealBounds returns error\n",
                   __FUNCTION__);

    return; // bad (error)
  }


  // TODO:  implement
}

void DTRender(Display *pDisplay, WB_FONTC pFont, const DT_WORDS *pWords, WBGC gc, Drawable dw,
              int iHScrollBy, int iVScrollBy, const WB_RECT *prcBounds, const WB_RECT *prcViewport, int iAlignment)
{
  // TODO:  implement
}





static void InternalDebugDumpWords(DT_WORDS *pWords)
{
  char tbuf[1024]; // for now max size of 'word'
  int i1, i2;

  WBDebugPrint("===================================================\n"
               "%s - DUMPING pWords array\n    ", __FUNCTION__);

  for(i1=0; i1 < pWords->nCount; i1++)
  {
    DT_WORD *pW = &(pWords->aWords[i1]);

    if(pW->iIsLineFeed)
    {
      for(i2=0; i2 < pW->nLength; i2++)
      {
        WBDebugPrint("<LF>\n    ");
      }
    }
    else if(pW->iIsTab)
    {
      for(i2=0; i2 < pW->nLength; i2++)
      {
        WBDebugPrint("<TAB>");
      }
    }
    else if(pW->iIsWhiteSpace)
    {
      for(i2=0; i2 < pW->nLength; i2++)
      {
        WBDebugPrint("<W>");
      }
    }
    else
    {
      i2 = pW->nLength > sizeof(tbuf) - 1 ? sizeof(tbuf) - 1: pW->nLength;
      memcpy(tbuf, pW->pText, i2);
      tbuf[i2] = 0;
      WBDebugPrint("%s", tbuf);
    }
  }

  WBDebugPrint("\n\n");

  // now do it again and indicate the length/width/height for each

  for(i1=0; i1 < pWords->nCount; i1++)
  {
    DT_WORD *pW = &(pWords->aWords[i1]);

    if(pW->iIsLineFeed)
    {
      WBDebugPrint("    LF:  length=%d,width=%d,height=%d  X=%d,Y=%d\n",
                   pW->nLength, pW->iWidth, pW->iHeight, pW->iX, pW->iY);
    }
    else if(pW->iIsTab)
    {
      WBDebugPrint("    TAB: length=%d,width=%d,height=%d  X=%d,Y=%d\n",
                   pW->nLength, pW->iWidth, pW->iHeight, pW->iX, pW->iY);
    }
    else if(pW->iIsWhiteSpace)
    {
      WBDebugPrint("    WS:  length=%d,width=%d,height=%d  X=%d,Y=%d\n",
                   pW->nLength, pW->iWidth, pW->iHeight, pW->iX, pW->iY);
    }
    else
    {
      i2 = pW->nLength > sizeof(tbuf) - 1 ? sizeof(tbuf) - 1: pW->nLength;
      memcpy(tbuf, pW->pText, i2);
      tbuf[i2] = 0;
      WBDebugPrint("    STR: length=%d,width=%d,height=%d  X=%d,Y=%d  \"%s\"\n",
                   pW->nLength, pW->iWidth, pW->iHeight, pW->iX, pW->iY, tbuf);
    }
  }

  WBDebugPrint("\n===================================================\n");
}