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-2016 by Bob Frazier (aka 'Big Bad Bombastic Bob')
                             all rights reserved

  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.

  BSD-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
  BSD-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"



// function prototypes


static int InternalCalcIdealBounds(Display *pDisplay, XFontSet fontSet, 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); 




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

int DTGetTextWidth0(XFontStruct *pFont, const char *szUTF8, int nLength)
{
//XRectangle rctInk, rctLog;
XFontSet fSet;
int iRval;//, iLen;

  if(nLength <= 0)
  {
    return 0;
  }

  fSet = WBFontSetFromFont(WBGetDefaultDisplay(), pFont);

  if(!fSet)
  {
    WB_ERROR_PRINT("Unable to get font set!\n");

    return XTextWidth(pFont, szUTF8, nLength);
  }

  iRval = DTGetTextWidth(fSet, szUTF8, nLength); // WB_TEXT_ESCAPEMENT(fSet, szUTF8, nLength);

  XFreeFontSet(WBGetDefaultDisplay(), fSet);

  return iRval;
}

int DTGetTextWidth(XFontSet fontSet, const char *szUTF8, int nLength)
{
int iRval;

  if(nLength <= 0)
  {
    return 0;
  }

  if(fontSet == None)
  {
    fontSet = WBGetDefaultFontSet(WBGetDefaultDisplay());

    if(fontSet == None)
    {
      WB_ERROR_PRINT("ERROR:  %s - fSet is None\n", __FUNCTION__);

      return 0;
    }
  }

  iRval = WBTextWidth(fontSet, szUTF8, nLength); // WB_TEXT_ESCAPEMENT(fSet, szUTF8, nLength);

  // TODO:  any debug output

  return iRval;
}



// determine ideal font size from desired text and geometry

XFontStruct *DTCalcIdealFont(XFontStruct *pRefFont, const char *szText, WB_GEOM *geomBounds)
{
  if(!pRefFont)
  {
    pRefFont = WBGetDefaultFont();
  }




  return NULL; // for now
}


XFontSet DTCalcIdealFontSet(Display *pDisplay, XFontSet fontSet, const char *szText, WB_GEOM *geomBounds)
{
  if(fontSet == None)
  {
    fontSet = WBGetDefaultFontSet(pDisplay);
  }


  return None; // 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(struct __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(struct __DT_WORD__)
                + 1; // because DT_WORDS contains one struct __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 * DTGetWordsFromText0(XFontStruct *pFont, const char *szText, int iAlignment)
{
XFontSet fSet;
DT_WORDS *pRval = NULL;


  fSet = WBFontSetFromFont(WBGetDefaultDisplay(), pFont);

  if(!fSet)
  {
    WB_ERROR_PRINT("ERROR:  %s - Unable to get font set!\n", __FUNCTION__);

    return NULL;
  }

  pRval = DTGetWordsFromText(WBGetDefaultDisplay(), fSet, szText, iAlignment);

  XFreeFontSet(WBGetDefaultDisplay(), fSet);

  return pRval;
}


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

  DT_WORDS *pRval = WBAlloc(sizeof(DT_WORDS) + sizeof(struct __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(struct __DT_WORD__)
              + 1; // because DT_WORDS contains one struct __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 = DTGetTextWidth(fontSet, p2, pRval->aWords[pRval->nCount].nLength);
        pRval->aWords[pRval->nCount].iHeight = WBFontSetHeight(pDisplay, fontSet); // 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 = DTGetTextWidth(fontSet, 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 = DTGetTextWidth(fontSet, p2, p1 - p2)
                                              - iUnderscoreFlag * DTGetTextWidth(fontSet, "_", 1);
        }
      }
      else
      {
        pRval->aWords[pRval->nCount].iWidth = 0;
      }

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

      pRval->nCount++;
    }
  }

  return pRval;
}

int DTCalcIdealBounds(Display *pDisplay, XFontSet fontSet, 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, fontSet, szText, iAlignment);

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

    return -1; // error
  }

//  InternalDebugDumpWords(pWords);

  iRval = InternalCalcIdealBounds(pDisplay, fontSet, 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, XFontSet fontSet, 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(fontSet == None)
  {
    fontSet = WBGetDefaultFontSet(pDisplay);
    if(fontSet == None)
    {
      WB_ERROR_PRINT("%s - returns ERROR (WBGetDefaultFontSet returns None)\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 = WBFontSetAvgCharWidth(WBGetDefaultDisplay(), fontSet);

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

  iFontAscent = WBFontSetAscent(pDisplay, fontSet);
  iFontDescent = WBFontSetDescent(pDisplay, fontSet);
  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_ERROR_PRINT("TEMPORARY:  %s - iHPos=%d, iMaxLen=%d, iLines=%d, iFontHeight=%d, *=%d\n", __FUNCTION__,
//                 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_ERROR_PRINT("TEMPORARY:  %s - rctSource %d,%d,%d,%d  rctBounds: %d,%d,%d,%d\n", __FUNCTION__,
//                 rctSource.left, rctSource.top, rctSource.right, rctSource.bottom,
//                 rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom);

  if(iLines > 1)
  {
    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 - source rectangle too small, alignment flags may not work\n", __FUNCTION__);
  }

#endif // NO_DEBUG

  if(rctBounds.right <= rctSource.right &&
     rctBounds.bottom <= rctSource.bottom)
  {
it_fits:

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

    // 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
    {
//      WB_ERROR_PRINT("%s - TEMPORARY:  'it fits' bounds rectangle is %d,%d,%d,%d  iAlignment=%d (%08xH)\n",
//                     __FUNCTION__, rctBounds.left, rctBounds.top, rctBounds.right, rctBounds.bottom, iAlignment, iAlignment);

      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_ERROR_PRINT("TEMPORARY:  %s - here I am, %d, %d, %d, %d\n", __FUNCTION__,
//                           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:

//  // TEMPORARY
//  WB_ERROR_PRINT("%s - TEMPORARY:  '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)
}



void DTDrawSingleLineText0(XFontStruct *pFont, const char *szText, Display *pDisplay, GC gc, Drawable dw,
                           int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
{
#if 0
XGCValues xgc;
int iAvgChar

  iAvgChar = WBFontAvgCharWidth(pDisplay, pFont); // was DTGetTextWidth(pFont, " ", 1);  // width of 1 space for text border (TODO:  RTL text)

  // height pFont->max_bounds.ascent + pFont->max_bounds.descent + 2;


            iU1 = DTGetTextWidth(pFont, tbuf, p1 - tbuf);

      WB_DRAW_STRING(pDisplay, wID, fSet, gc, iHPos, iVPos, szText, strlen(szText));

  xgc.font = pOldFont->fid;
  BEGIN_XCALL_DEBUG_WRAPPER
  XChangeGC(pDisplay, gc, GCFont, &xgc);
  END_XCALL_DEBUG_WRAPPER
#endif // 0
  // TODO:  implement

  DTDrawMultiLineText0(pFont, szText, pDisplay, gc, dw, iTabWidth, iTabOrigin, prcBounds,
                       iAlignment | DTAlignment_SINGLELINE | DTAlignment_NO_WORD_WRAP);
}

void DTDrawSingleLineText(XFontSet fontSet, const char *szText, Display *pDisplay, GC gc, Drawable dw,
                          int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
{
#if 0
XGCValues xgc;
int iAvgChar

  iAvgChar = WBFontAvgCharWidth(pDisplay, pFont); // was DTGetTextWidth(pFont, " ", 1);  // width of 1 space for text border (TODO:  RTL text)

  // height pFont->max_bounds.ascent + pFont->max_bounds.descent + 2;


            iU1 = DTGetTextWidth(pFont, tbuf, p1 - tbuf);

      WB_DRAW_STRING(pDisplay, wID, fSet, gc, iHPos, iVPos, szText, strlen(szText));

  xgc.font = pOldFont->fid;
  BEGIN_XCALL_DEBUG_WRAPPER
  XChangeGC(pDisplay, gc, GCFont, &xgc);
  END_XCALL_DEBUG_WRAPPER
#endif // 0
  // TODO:  implement

  DTDrawMultiLineText(fontSet, szText, pDisplay, gc, dw, iTabWidth, iTabOrigin, prcBounds,
                      iAlignment | DTAlignment_SINGLELINE | DTAlignment_NO_WORD_WRAP);
}

void DTDrawMultiLineText0(XFontStruct *pFont, const char *szText, Display *pDisplay, GC gc, Drawable dw,
                          int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
{
XFontSet fSet;

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

      return; // bad
    }
  }

  fSet = WBFontSetFromFont(pDisplay, pFont);

  if(fSet == None)
  {
    WB_ERROR_PRINT("Unable to get font set!\n");

    return;
  }

  DTDrawMultiLineText(fSet, szText, pDisplay, gc, dw, iTabWidth, iTabOrigin, prcBounds, iAlignment);
}

void DTDrawMultiLineText(XFontSet fSet, const char *szText, Display *pDisplay, GC 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(fSet == None)
  {
    fSet = WBGetDefaultFontSet(pDisplay);
    if(fSet == None)
    {
      WB_ERROR_PRINT("%s - ERROR:  WBGetDefaultFontSet returns None\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 DTGetTextWidth(pFont, " ", 1);  // width of a single space
//  iFontHeight = pFont->ascent + pFont->descent;

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

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

    return; // error
  }

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

  if(InternalCalcIdealBounds(pDisplay, fSet, 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 = WBFontSetDescent(pDisplay, fSet);
  xMaxBounds = WBFontSetMaxBounds(pDisplay, fSet); // font's 'max_bounds' structure member, maximized for all of them

//  InternalDebugDumpWords(pWords);

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

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

  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_ERROR_PRINT("%s - TEMPORARY (a), WB_DRAW_STRING at %d,%d  %d chars of %s\n",
//                       __FUNCTION__, rcDest.left + pW->iX, rcDest.top + pW->iY, pW->nLength, pW->pText);

        // draw the entire string. 'pW->iY' is the BASE of the font
        WB_DRAW_STRING(pDisplay, dw, fSet, gc, rcDest.left + pW->iX, rcDest.top + pW->iY,
                       pW->pText, pW->nLength);
      }
      else
      {
        iH = rcDest.left + pW->iX;
        iH2 = -1; // horizontal position of NEXT underscore to display (corresponds to character index 'i3')

        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_ERROR_PRINT("%s - TEMPORARY (b), WB_DRAW_STRING at %d,%d  %d chars of %s\n",
//                           __FUNCTION__, 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
            WB_DRAW_STRING(pDisplay, dw, fSet, gc, iH, rcDest.top + pW->iY,
                           (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 + DTGetTextWidth(fSet, (char *)(pW->pText) + i3, 1); // width of character
              xpt[1].y=xpt[0].y;

              XDrawLines(pDisplay, dw, gc, xpt, 2, CoordModeOrigin);
            }

            // advance the pointer
            iH += DTGetTextWidth(fSet, (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
          WB_DRAW_STRING(pDisplay, dw, fSet, gc, iH, rcDest.top + pW->iY,
                         (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 + DTGetTextWidth(fSet, (char *)(pW->pText) + i3, 1); // width of character
            xpt[1].y=xpt[0].y;

            XDrawLines(pDisplay, dw, gc, xpt, 2, CoordModeOrigin);
          }
        }
      }
    }
  }

  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, XFontSet fontSet, DT_WORDS *pWords, int iTabWidth, int iTabOrigin,
                 WB_RECT *prcBounds, int iAlignment, int iStartLine, int iEndLine)
{
WB_RECT rcDest;


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

  if(fontSet == None)
  {
    fontSet = WBGetDefaultFontSet(pDisplay);
    if(fontSet)
    {
      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, fontSet, 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, XFontSet fontSet, const DT_WORDS *pWords, GC 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");
}