No Fragments Archive 10: Diskmags/nf_archive_10.iso/MAGS/ST_USER/1990/USERAU90.MSA/TEXT_GEM.DOC

Text File | 1990-06-24 | 8KB | 186 lines

                       TUNE IN TO THE TEST CARD


            In Part 2 of his introduction to GEM programming
           Roland Waddilove examines some common VDI functions


In the first part of this series of programming articles exploring GEM we
created our first program - a simple routine that displayed a message on the
screen and then waited for a mouse button to be clicked.

    We'll continue looking at the VDI (virtual device interface) functions and
try out some of the most common ones. To see what can be achieved using a few
simple VDI functions double click on either MONO_CRD.PRG in monochrome or
COLR_CRD.PRG in low res colour.

    Last month we used the v_gtext() function to print a message on the screen
and it appeared to be quite a simple process. However, we ignored a host of
related functions that directly effect the way in which v_gtext() works.

    Look at almost any page produced by a desktop publishing program and you'll
see a wide variety of type sizes, styles and even angles. All this can be
achieved with the humble v_gtext() VDI function so we'll look first at the
related functions that affect the way it displays text.

    A very simple and eay-to-use VDI function called vst_color() - note the
American way of spelling colour - sets the ink in which text is printed. Two
(short) integer parameters are required, the workstation handle and the ink:

short handle,ink;
vst_color(handle, ink);

    The ink number range and the colours displayed depend on the screen mode in
use and the palette (which may be set by the control panel or from within the
program). In low res the inks range from 0 to 15, in medium res it's 0 to 3 and
in monochrome you have a choice of either 0 or 1.

    If you don't set the text colour at the start of your program you'll
probably find that it defaults to something sensible like black text on a white
background. Also, the vst_color() returns the colour actually set, which may be
different than the one you wanted, for instance, if you supply an out of range
number.

    Another fairly simple VDI function is vst_effects(), which is used to set
the text style, such as bold, italic, underlined and so on. Like the previous
function, only two (short) integer parameters are required, the graphic
woorkstation handle and the bit-mapped effects byte:

short handle,effects;
vst_effects(handle, effects);

    Each bit in the effects byte turns on a particular text style and you can
set more than one bit to combine the effects:

BIT      EFFECT
--------------------
 0       Thickened
 1       Shaded
 2       Skewed
 3       Underlined
 4       Outlined
 5       Shadowed

    Text can be printed up the screen, down it, horizontally forwards or
backwards simply by setting the angle of rotation with vst_rotation(). Although
this function lets you set the angle at which text will be printed to a tenth
of a degree, normally only four orientations are possible - 0, 90, 180 and 270
degrees.

    Since vst_rotation() only accepts integer parameters, the angle must be in
tenths of a degree, that is 0, 900, 1800, 2700. The value returned by this call
is the angle actually set.

    So, to print some italic text vertically down the screen (you'll have to
turn your monitor on its side to read it), the following three lines of code
would be used:

vst_rotation(handle,2700);
vst_effects(handle,4);
v_gtext(handle,50,50,"This is a test...");

    If you try printing some text on top of a coloured background you'll see
that the characters are printed within a white box as the background colour is
always set to zero, which is normally white.

    To prevent this background from being shown, the VDI function vsw_mode()
enables you to set the text writing mode. It can be normal, transparent or
exclusively ORed. The function call looks like this:

short handle,mode;
vsw_mode(handle,mode);

    The value of mode ranges from one to four:

VALUE    EFFECT
--------------------------------------------------------------------
  1      Replace - background and foreground pixels overwrite screen
  2      Transparent - only foreground pixels written to screen
  3      XOR - all pixels are XORed with the screen
  4      Reverse transparent - only background pixels written

    We still aren't finished with the v_gtext() function as there are yet more
related functions that affect its output. We'll now move on to two very similar
functions which set the size of the text displayed on the screen - vst_height()
and vst_points().

    The size of text is set by specifying either the height in pixels or
points, where a point is 1/72 of an inch. The width is proportional to the
height so altering the latter will affect the former. The two calls look like
this:

short handle, h, p, wchar, hchar, wbox, hbox;
vst_height(handle, h, &wchar, &hchar, &wbox, &hbox);
vst_point(handle, p, &wchar, &hchar, &wbox, &hbox);

    If you use the first function then pass the height in pixels in 'h', or use
'p' in the second. The four extra parameters are used by the VDI to return the
width and height of the characters that will be used and the width and height
of the box in which they are printed.

    If a particular point or pixel size that you have asked for isn't available
then the figure may be rounded down to the nearest one. The actual values set
will be returned in wchar, hchar, wbox and hbox.

    Nearly finished this marathon run through the text manipulation commands
and just two more functions to look at - v_justified() and vst_alignment().
Word processors like 1st Word Plus and ST Writer are able to print text so that
both the right-hand and left-hand margins are straight.

    Many magazines and newspapers have a straight right edge, but some have
ragged ones. If it's straight then the text has been justified - extra tiny
spaces have been added between the words, the letters or both in order to nmake
all the lines of text exactly the same length.

    This effect is easily achieved by using v_justified() instead of v_gtext().
Extra parameters are tagged on to the end of the ones used in v_gtext() to tell
the VDI how long to make the line of text and whether it should add letter or
word spacing or both. Here's the VDI function call:

short handle, x, y, len, word, char;
char *string;
v_justified(handle, x, y, string, len, word, char);


    The first four parameters are the same as for v_gtext() so there shouldn't
be any problems setting these. The 'len' parameter tells the VDI how many
pixels long to make the text, while the 'word' and 'char' flags take values of
one or zero to indicate whether word or character spacing (or both) should be
used to pad out the text if necessary.

    At last we come to the end of the VDI text functions with the
vst_alignment() call. With this you can left or right justify text or centre
it, and use various points in the character cell as the coordinates to print
at. The function call is:

short handle, h, v, hset, vset);
vst_alignment(handle, h, v, &hset, &vset);

    The 'h' parameter is used to set the horizontal alignment and can be:

0   Left justified
1   Centre justified
2   Right justified

    The 'v' parameter is the vertical alignment and the following values can be
used:

0   Base line (default) - bottom of characters without descenders
1   Half line - top of lowercase characters
2   Ascent line - top of upper case characters
3   Bottom - bottom of character cell
4   Descent - bottom of characters with descenders
5   Top - top of the character cell

    That just about wraps up this month's GEM programming article. To see some
of these VDI functions used in practice take a look at the two Test Card
programs - MONO_CRD.PRG and COLR_CRD.PRG. This displays two lines of text in
two different sizes and colours. I'll also be documenting some of the other VDI
calls next month so you can see a sneak preview of the shape of things to
come.


HARDWARE: ALL STs, MONO AND COLOUR