Drawing Text

FUNCTIONS

  int   drawstr(point p, char *str);
  char *drawtext(rect r, int alignment, char *text);
  int   gprintf(char *fmt, ...);

  int   strwidth(font f, char *s);
  point strsize(font f, char *s);
  rect  strrect(font f, char *s);

  int   textheight(int width, char *text);

CONSTANTS

  #define AlignTop      0x0000
  #define AlignBottom   0x0100
  #define VJustify      0x0200
  #define VCenter       0x0400
  #define VCentre       0x0400
  #define AlignLeft     0x0000
  #define AlignRight    0x1000
  #define Justify       0x2000
  #define Center        0x4000
  #define Centre        0x4000
  #define AlignCenter   0x4000
  #define AlignCentre   0x4000
  #define Underline     0x0800

NOTES

The drawstr function draws the text characters given by the string into the current drawing, using the current font and the current colour. The upper left corner of the first character (i.e., a point that is getascent(f) above the baseline) is placed at point p, and subsequent characters are placed on the same baseline, to the right of each previous character. The function returns the width of the string which was drawn.

The drawtext function draws text within a bounding box, using a given text-alignment. The possible text-alignments are: AlignTop, AlignBottom, VJustify, VCenter, AlignLeft, AlignRight, Justify and Center. The first four of these refer to the vertical alignment of text within the bounding box, the other four refer to the horizontal placement of text. A vertical and a horizontal alignment may be combined using the plus or bit-wise or operators. An alignment of zero is equivalent to AlignTop+AlignLeft.

Additionally, the value Underline can be combined with the above flags, and this has the effect of drawing a line one pixel below the baseline of the text, and using the current line width for the width of the line.

The drawtext function draws only as much text as will fit in the bounding box. It draws using the current colour and the current font. The function returns a pointer to the first character in the text string which could not be drawn within the bounding box; hence this pointer can be used to continue drawing the text string elsewhere. It will return NULL if the entire string was drawn.

The gprintf function is similar to the printf family, except that it draws to the current drawing. It uses the current font and current colour, and it also uses and modifies the currentpoint to record where drawing should occur. The gprintf function returns the number of characters successfully drawn.

The strwidth function reports the pixel width of the given string in the supplied font. The strsize function returns a point structure which reports the pixel width and height of the given string in the supplied font. The width will be reported as the x-coordinate, while the y-coordinate reports the height of the string. The strrect function returns the width and hight of the given string in the width and height fields in the returned rectangle, respectively. The x and y co-ordinates are zero.

The textheight function returns the pixel height of the given string using the current font and a supplied maximum pixel width for the text. The number of lines over which the text will be displayed can thus be determined: textheight(width,text) / fontheight(currentfont()).