-- font.ref : version 5.20 -- jiri babor -- jbabor@paradise.net.nz -- 00-02-05 Introduction: The font package is a general purpose tool for the display of text in graphics modes, inspired by the Fastgraph/Fonts package from Ted Gruber Software. It is constructed from high level routines only, so it should work in any graphic mode supported by Euphoria. It lets you select a font suitable for the job and to put the text exactly where you want it, the way you want it. The latest version supports only transparent backgrounds, but you still have a great variety of options to your disposal: both solid color and textured (patterned) foregrounds, any mix of bold, shadow, italic and underline attributes, multi-line justification, etc, all with sensible defaults. Installation: No special installation is required. The best place for the include file, font.e, is obviously the default Euphoria include directory, and I suggest a separate font subdirectory in the main Euphoria directory for the font files. How to use it: More detailed instructions can be found below in the reference section of this document, but at the most basic level, remember, the system works only in *graphics* modes. Chose your fonts and load them. Each font is given a handle that allows you to selected it later at will. Decide on the starting point, text attributes, especially if you do not like the defaults, and display your text. The system maintains a text pointer, a pair of x, y coordinates, which is automatically updated after each operation. All text parameters are preserved, even as you switch from font to font. Patterns: foreground tiling is *local*, which simply means the pattern for each character always starts in the top left corner of the its space, at the current text pointer. Textured surfaces are also somewhat slower than their solid color counterparts. Line justification and multi-line support: Three basic justifications are available: left, right and centre, and each one is in respect of the initial horizontal position (x value) of the text pointer. Newline characters ('\n', ascii 10) imbedded within the printed string cause line feeds and automatic justification of the following segments of the string. ROM font: 8x16 ROM font is automatically loaded and is immediately available after invocation of the font system. 'On-the-fly' change of attributes: printable characters can have any (ascii) value between 1 and 255. Zero and absolute values of negative characters are interpreted as new font attributes. Since attributes are 'additive', a single negative value represents a total description of the font attributes from the given point on. So, for instance, in the string "this is my "&-9&"name"&0 the attributes are set to BOLD+UNDERLINE=1+8=9 just before 'name', and reset to NONE (=0) at the very end of the string. 'On-the-fly' change of foreground: character values greater than 255 indicate changes of the foreground color according to a very simple formula: new_color = char - 256. So, for example, the string 257&"this is your "&270&"name" starts with blue foreground (257 - 256 = 1 = BLUE), and 'name' will be printed in yellow (270 - 256 = 14 = YELLOW). Naming conventions: All global constants are in upper case, everything else is in lower case only! No global variables are *directly* accessible. Names of global functions are nouns, with the sole exception of getx & gety pair. Names of global procedures are usually verbs, or combinations starting with the word 'set'. Global constant: ROM = 1 -- ROM font 8x16, default Attributes are 'additive', e.g. BOLD+UNDERLINE = 1+8 = 9: NONE = 0 BOLD = 1 ITALIC = 2 SHADOW = 4 UNDERLINE = 8 Multi-line justification: LEFT = 0 CENTRE = 1 RIGHT = 2 BOXED = 4 Global routines: align -- align *current* font with some other font attributes -- return current text attributes char_pitch -- return character pitch, in pixels font_baseline -- return baseline height of specified font, in pixels font_height -- return nominal height of specified font, in pixels foreground -- return current foreground: plain color or 2-d pattern getx -- return current horizontal position of text pointer gety -- return current vertical position of text pointer justification -- return current line justification justify -- set text line justification lengths -- return sequence of lengths text lines, in pixels line_pitch -- return current line spacing, in pixels load_font -- load specified font and return its handle paper_color -- return background color for prompt prompt -- prompted screen input of string, with editing reset_font -- reset entire environment to current defaults restore_font -- restore entire environment to *initial* defaults select_font -- select font, make it current set_attributes -- set text attributes set_extra_char_pitch set_extra_line_pitch set_foreground -- set text foreground set_paper_color -- set background for prompt set_shadow_color -- set text shadow color set_shadow_offsets -- set horizontal & vertical shadow offsets setx -- set horizontal position of text pointer setxy -- set both coordinates of text pointer sety -- set vertical position of text pointer shadow_color -- return current text shadow color shadow_offsets -- return current shadow offsets write -- display text write_char -- print a single character Detailed alphabetical listing (prefix indicates variable type): ---------------------------------------------------------------------- syntax: align(ihandle) comment: Align, vertically, the *current* font with some other font: adjust the y-coordinate of the text pointer so that the baseline of the current font matches that of (previously used) font with the indicated handle. Useful when two or more fonts of different sizes are combined on the same line. It works properly only with *updated* font files, that have the correct baseline heights set! ---------------------------------------------------------------------- syntax: i = attributes() comment: return the current combined text attributes. see set_attributes() entry below. ---------------------------------------------------------------------- syntax: i = char_pitch(c) comment: return the pitch of the character c using the current font, attributes and kerning, in pixels. the returned value includes extra bold and kerning allowances, where applicable, but *not* shadow and/or italic offsets, because they do not contribute to the actual pitch. example: icp = char_pitch('m') ---------------------------------------------------------------------- syntax: i = font_baseline(ifont_handle) comment: Return the baseline height of the specified font, in pixels. Baseline height is the nominal font height *minus* the height of descenders. Baseline height is a relatively new feature, available only from version 3.xx. Older font files will return the *nominal* font height! A small utility named 'setbase' is available in this package to reset baseline height to a proper value. If the baseline height is not known, use a graphics mode with a coarser resolution (mode 19) or an old version of the font editor, fed, (with pre 3.xx version of font.e) to count the descender pixels... ---------------------------------------------------------------------- syntax: i = font_height(iFont_handle) comment: return the nominal height of the current font, in pixels ---------------------------------------------------------------------- syntax: o = foreground() comment: return the current foreground color. the foreground can be a plain color or any 2-d color pattern. ---------------------------------------------------------------------- syntax: i = getx() comment: return the horizontal coordinate of the text pointer - the left edge of the char to be printed next. ---------------------------------------------------------------------- syntax: i = gety() comment: return the vertical coordinate of the text pointer - the top edge of the char to be printed next. ---------------------------------------------------------------------- syntax: i = justification() comment: return current line justification. ---------------------------------------------------------------------- syntax: justify(i) comment: Set (multi-)line justification. Three horizontal and an extra vertical justification are available: LEFT, RIGHT, CENTRE and BOXED. One of the first three is used to arrange the text with respect to the initial horizontal coordinate. An 'additive' BOXED constant can be used to centre the text also vertically. Imbedded newline characters create multi-line blocks with the same justification. default: LEFT se also: lengths(), global constants above example: the following code will produce two lines, both centred about the given horizontal as well as vertical coordinates and separated by the current line pitch: setxy(320,80) justify(CENTRE+BOXED) write("Long Live\nEUPHORIA!") ---------------------------------------------------------------------- syntax: s = lengths(st) comment: return sequence of lengths, in pixels, of all lines contained in string st using current font and attributes. the current font with current attributes is assumed for the calculations. each imbedded newline char starts a new line length calculation, which is eventually appended to all previously obtained lengths. imbedded attribute changes are also taken into account. each length is the sum of all individual char pitches + 1! example: let's assume default conditions, ROM font (8x16): len = lengths("just a test...") -- len={113} (8*14+1) len = lengths("thanks\njiri") -- len={49,33} ---------------------------------------------------------------------- syntax: i = line_pitch() comment: return current line spacing invoked in response to embedded newline characters. it is font height plus extra line pitch plus 1! ---------------------------------------------------------------------- syntax: i = load_font(st) comment: Load software font st and make it available for selection, return font handle i. The name of the font file is *not* case sensitive. The resident system ROM font (8x16) is automatically loaded and available on start-up. It can be again recalled at any time using the pre-defined global constant ROM. Repeated loads of the same font will merely return the same handle! example: mo28 = load_font("modern28.f") ---------------------------------------------------------------------- syntax: icolor = paper() comments: Return background color for prompt. default: WHITE ---------------------------------------------------------------------- syntax: s = prompt(str, ifield_width) comment: Prompted screen input of a string with editing. Return two element sequence {key, str} when one of the following keys is pressed: tab, shift-tab, enter, esc, up or down arrow. key is the exit key, str is the edited string form. Edited string is displayed in a one-line window of requested length, in pixels, the top left corner indicated by the current text pointer. The length of the output string st is unlimited, the text is scrollable. Initially, the flashing xor cursor is placed just past the end of the prompt string. The current attributes, orientation and the line justification are all preserved, but temporally ignored. Any formatting characters in the prompt string are also ignored. example: s = prompt("Your name: ", 200) -- background strip -- 200 pixels long. ---------------------------------------------------------------------- syntax: reset_font() comment: reset the font environment to the *current* defaults. see also: restore_font(), set_default() ---------------------------------------------------------------------- syntax: restore_font() comment: restore the font environment to the *initial* defaults, set pointer to 0,0 do a reset_font(). Initial defaults: default_attributes = NONE default_extra_char_pitch = 0 default_extra_line_pitch = 1 default_font = ROM default_foreground = BRIGHT_WHITE default_horizontal_shadow_offset = 1 default_justification = LEFT default_paper_color = WHITE default_shadow_color = GRAY default_vertical_shadow_offset = 1 see also: reset_font(), set_default() ---------------------------------------------------------------------- syntax: select_font(ihandle) comment: select a font using its font handle and make it current. the procedure does *nothing* if the handle does not belong to a previously loaded font. the last loaded font is automatically selected. example: select_font(mo28) ---------------------------------------------------------------------- syntax: set_attributes(i) comment: set text attributes. four distinct attributes are currently recognized: BOLD, SHADOW, ITALIC and UNDERLINE (see global constants above). The attributes are 'additive', any combination of them is valid, but SHADOW is ignored in the fast, opaque background mode. An alternative method of setting attributes is direct insertion of *negative* value of combined attributes into the printed string, e.g.: write("What's your "&-9&"name"&0&"?") will cause the last word ('name') to be shown bold and underlined ( -(BOLD+UNDERLINE) = -(1+8) = -9. The zero character inserted just before the question mark will reset the attributes to NONE (=0). default: NONE ( = 0 ) example: set_attributes(BOLD+SHADOW) ---------------------------------------------------------------------- syntax: set_default(sString, oValue) comment: a routine to set *any* font default to a new value. It recognizes ten very descriptive strings: "attributes" "extra_char_pitch" "extra_line_pitch" "font" "foreground" "horizontal_shadow_offset" "justification" "paper_color" "shadow_color" "vertical_shadow_offset" example: set_default("foreground", YELLOW) see also: reset_font(), restore_font() ---------------------------------------------------------------------- syntax: set_extra_char_pitch() comment: additional character spacing default: 0 pixels ---------------------------------------------------------------------- syntax: set_extra_line_pitch() comment: extra pixel height over the font height default: 1 pixel ---------------------------------------------------------------------- syntax: set_foreground(o) comment: set foreground, tiled pattern or single color. tiled foregrounds can be significantly slower than their plain color counterparts. each pattern must be a 2-d sequence, and the tiling is always *local*: it will start at top left corner of the current char space space, the current text pointer location, {x,y}. alternatively, a plain color foreground can be specified 'on-the-fly', from within the printed string. any char value bigger than 255 will be interpreted as a new foreground color: new_foreground_color = char - 256 default: BRIGHT_WHITE ( = 15 ) examples: tile = {{4,4,1,1,},{4,4,1,1},{1,1,4,4},{1,1,4,4}} set_foreground(tile) -- 'on-the-fly' change: set_foreground(YELLOW) write("Euphoria "&271&"rules !") -- last part of string -- will be written in BRIGHT_WHITE ( 271 = 256 + 15 ) ---------------------------------------------------------------------- syntax: set_paper_color(iColor) comments: set prompt background default: WHITE (7) ---------------------------------------------------------------------- syntax: set_orientation(i) comment: set line orientation, HORIZONTAL or VERTICAL. vertical writes are also somewhat slower than their horizontal counterpart. only one vertical direction is supported, common in technical drawings: facing left and moving upwards! default: HORIZONTAL ---------------------------------------------------------------------- syntax: set_shadow_color(i) comment: set color of scharacter shadows. default: GRAY ( = 8 ) example: set_shadow_color(BLUE) ---------------------------------------------------------------------- syntax: set_shadow_offsets(ixoffset, iyoffset) comment: set horizontal and vertical offset of character shadows, positive right and down. default: 1, 1 example: set_shadow_offset(3,3) ---------------------------------------------------------------------- syntax: setx(ix) comment: set the horizontal coordinate of the text pointer - the left edge of the char to be printed next. default: zero ( 0 ) example: setx(35) ---------------------------------------------------------------------- syntax: setxy(ix,iy) comment: set both coordinates of the text pointer - top left corner of the char to be printed next. default: 0,0 example: setxy(35,65) ---------------------------------------------------------------------- syntax: sety(iy) comment: set the vertical coordinate of the text pointer - the top edge of the char to be printed next. default: zero ( 0 ) example: sety(25) ---------------------------------------------------------------------- syntax: i = shadow_color() comment: return the current shadow color. ---------------------------------------------------------------------- syntax: s = shadow_offsets() comment: return sequence of the current shadow offsets: {xoff,yoff} ---------------------------------------------------------------------- syntax: write(string) comment: Display the string starting at the current text pointer location using the current font, colors, attributes and justification. For longer strings, the opaque background mode is generally faster, sometimes much faster, than the CLEAR or tiled backgrounds, but relative speeds change quite dramatically from resolution to resolution. (Many of the graphic 'accelerators' are also pathetically slow in lower regions of the video screens in some SVGA modes. Pixel writes are often up to 20 times faster at the top than at the bottom of the screen!) example: write("this is just a test...") ---------------------------------------------------------------------- syntax: write_char(ichar) comment: Print a single character at the current text pointer location, using the current font, foreground and attributes. The ichar is an ASCII value between 1 and 255, inclusive.