V6Lib Manual

                        Version 0.5
                     20 January, 1998
                      Jason C. Penney
                  [email protected]


Introduction
This document is not yet complete.  Only the Technical
Reference for V6Lib is near finished form.  This section
will contain enough information to get you started with
V6Lib, but will later be rewritten to be more useful.

The V6 Z-machine offers support for 8 text windows, images,
sounds, menus and user stacks.  Currently V6Lib doesn't
support V6 menus and user stacks, but it will in the future.
For a better understanding of the Z-Machine's V6 Screen
model, see section 8.6 of "The Z-Machine Standards
Document".

Both this manual and V6Lib are still under development.

Getting Started
The basic steps to getting started are simple.  Make sure
that the V6Lib files are in your include path.  Include
V6Defs before Parser, and include V6 after VerbLib.  There
are some constants that can be defined to change the
behavior of V6Lib (NOZPIC, NOZSND, MAXZPICS, MAXZSNDS).
They must be defined before including V6Defs.

Here is a commented shell file (based on the old shell.inf
by Graham Nelson [I think]).

    !!!! Start of file
    Switches v6;
    Release 0;

    Constant Story "V6Shell";
    Constant Headline "^An Interactive Emptiness^\
                 by Jason C. Penney.^";

    !Constant NOZPIC; !Uncomment if you don't want image
                      !support
    !Constant NOZSND; !Uncomment if you don't want sound
                      !support

    !Constant MAXZPICS x; !Uncomment if you want a dynamic
                          !image object pool.  Replace x with
                          !the size of the pool

    !Constant MAXZSNDS x; !Uncomment if you want a dynamic
                          !sound object pool.  Replace x with
                          !the size of the pool


    Include "V6Defs";
    Include "Parser";
    Include "VerbLib";
    Include "V6";

    Object V6Land "V6Land"
         with description "A gigantic void."
         has  light;

    [ Initialise;
         V6Init(); !you can pass a ZWinStyle object to
                   !V6Init to be used as the startup style.
         location = V6Land;
         print "^^^^^Welcome...^^";
    ];

    Include "Grammar";
    end;
    !!! end of file



Technical Reference

Class DocumentationZPic
The ZPic class provides an interface for displaying images.
To create an instance of a ZPic object, it is necessary to
provide with the private property picnum, which should be
equal to the image's number in the resource file.

    ZPic      TitlePic
     private
         picnum 1;

If the constant MAXZPICS is defined before the inclusion of
V6Defs.h a pool of dynamic ZPic objects will be created equal
to MAXZPICS.  This can be useful when an image is only going
to be needed for a short time. The images number should be
passed to the ZPic via create() (NOTE:  Inform does not (at
this time) handle the passing of arguments to create as one
might expect, to overcome this, call create again on the new
object with the intended parameters).

    DrawTitle[ TitlePic;
         TitlePic = ZPic.create();
         TitlePic.create(1);
         . . .
         TitlePic.Draw();
         ZPic.destroy(TitlePic);
         . . .
    ];


GetWidth(), GetHeight()
 Returns  the  images  width  or height  (respectively)  in
 units.
    height = TitlePic.GetHeight();

Draw([y, x])
 Draws   the  image  within  the  active  ZWindow.  If   no
 parameters  are  given the image displays at  the  current
 cursor position.
    TitlePic.Draw();
 The  optional y and x parameters give an offset within the
 window.
    TitlePic.Draw(1,1);

Erase([y, x])
 Paints  an area the size of the ZPic in the active ZWindow
 with  the  background colour.  If no parameters are  given
 the area is painted at the current cursor position.
    TitlePic.Erase();
 The  optional y and x parameters give an offset within the
 window.

TitlePic.Erase(1,1);ZSnd
The ZSnd class provides an interface for handling sound
effects (and possibly music).  To create an instance of a
ZSnd object, it is necessary to provide with the private
property sndnum, which should be equal to the sound's number
in the resource file.

    ZSnd      Creak
     private
         picnum 3;

If the constant MAXZSNDS is defined before the inclusion of
V6Defs.h a pool of dynamic ZSnd objects will be created
equal to MAXZSNDS.  This can be useful when an sound is only
going to be needed for a short time. The sound's number
should be passed to the ZSnd via create() (NOTE:  Inform
does not (at this time) handle the passing of arguments to
create as one might expect, to overcome this, call create
again on the new object with the intended parameters).

    PlayCreak[ Creak;
         Creak = ZSnd.create();
         Creak.create(3);
         . . .
         Creak.Play();
         ZSnd.destroy(Creak);
         . . .
    ];

V6Lib provides two ZSnd objects automatically,  HighBeep and
LowBeep.  They play a high or low pitched beep sound
respectively.

GetVolume()
 Returns the ZSnd's current volume setting.
    vol = Creak.GetVolume();

SetVolume(vol)
 Sets  the volume of the ZSnd to vol.  vol should  be  an
 integer  from  0  to 8 or V_MAX.  0 is the  softest  the
 sound can be played and V_MAX is the loudest.
    Creak.SetVolume(V_MAX);

Play([repeats, routine])
 Called with no arguments it will play the sound once.
    Creak.Play();
 If  repeats is greater than zero, the sound will  repeat
 that  many times.  To repeat forever (or until  stopped)
 pass in RP_FOREVER for repeats.
    Creak.Play(RP_FOREVER);
 routine should be the address of a routine that will  be
 called  with  no arguments once the sound  has  finished
 playing.
    Creak.Play(0,AfterCreak);

Stop()
 Stops  the  sound  if it is currently  playing.   (NOTE:
 Currently the Z-Machine only supports one sound  playing
 at  a  time.  Calling stop on any ZSnd objects will stop
 all  sound.  This may change in future).  Currently does
 not stop sounds that are Fading.
    Creak.Stop();

Prepare()
 Asks the interpreter to pre-load the sound into memory.
    Creak.Prepare();

Finish()
 If  the  sound  has been pre-loaded into memory,  it  is
 flushed out.
    Creak.Finish();

Fade(sv, fv, steps)
 Fades a sound in or out.  The starting volume, given  as
 sv,  is  faded  to the final volume, given  as  fv.   It
 repeats  the sound steps number of times to get from  sv
 to fv.

Creak.Fade(5,1,12);ZWindow
The ZWindow class provides an interface for controlling the
windowing features of the V6 Z-Machine's screen model.
V6Lib declares 8 ZWindow objects:   MainWin, StatusWin,
ZWin2, ZWin3, ZWin4, ZWin5, ZWin6, and ZWin7.

Activate()
 Sets the ZWindow as the Active ZWindow.  All output will
 go to the Active ZWindow.
    MainWin.Activate();

GetYLoc(), GetXLoc()
 Returns  the  current  Y  or X location  on  the  screen
 (respectively) of the ZWindow.
    xloc = MainWin.GetXLoc();

GetYSize(), GetXSize()
 Returns  the  height  or  width  (respectively)  of  the
 ZWindow in units.
    height = StatusWin.GetYSize();

GetYCursor(), GetXCursor()
 Returns   the   cursor's  current  Y   or   X   position
 (respectively) within the ZWindow.
    ycursor = StatusWin.GetYCursor();

GetLMargin(), GetRMargin()
 Returns  the Left or Right margin setting (respectively)
 of the ZWindow in units.
    left_margin = MainWin.GetLMargin();

GetNewLineIntRoutine()
 Returns  the address of the ZWindow's newline  interrupt
 routine.
    nlroutine = ZWin3.GetNewLineIntRoutine();

GetIntCount()
 Returns the ZWindow's interrupt count.
    int_count = ZWin3.GetIntCount();

GetFontStyle()
 Returns the ZWindow's current font style (NOTE:  On some
 interpreters a combination of styles is possible, so the
 value  may not directly equal a specific style.   It  is
 probably best to treat the value as a bitfield.)
    if (StatusWin.GetFontStyle() & ST_BOLD)
    {
         print "Bold is active^";
    }

GetBGColour(), GetFGColour()
 Returns  the  current  background or  foreground  colour
 (respectively) of the ZWindow.
    colour = MainWin.GetBGColour();

GetFont()
 Returns the current font of the ZWindow.
    font = MainWin.GetFont();

GetCharHeight(), GetCharWidth()
 Returns  the  height  or  width  (respectively)   of   a
 character in the ZWindow's current font, in units.   For
 proportional  fonts the interpreter  should  return  the
 width of the `0' (zero) character.
    cwidth = StatusWin.GetCharWidth();

GetLineCount
 Returns  the line count of the ZWindow.  (see section  8
 of      "The      Z-Machine     Standards      Document"
 Version 1.0 for more info about the line count)
    lc = MainWin.GetLineCount();

SetLoc(row, col)
 Set  the  ZWindow's new location on  the  screen  to  be
 (row,col).  If either argument is 0 then only the  other
 will  be  changed.   The screen's top  left  z-pixel  is
 (1,1).
    MainWin.SetLoc(1,(StatusWin.GetYSize()+1));

Move(rowoff, coloff)
 Move  the  ZWindow  rowoff units vertically  and  coloff
 units horizontally from it's current position.
    MainWin.Move(0,-3);

SetSize(height, width)
 Set the ZWindow's size to be height units tall and width
 units across.
    StatusWin.SetSize(20,640);

SetCursor(row, col)
 Set  the  ZWindow's cursor's location within the ZWindow
 to  be (row,col). If either argument is 0 then only  the
 other  will be changed.  The ZWindow's top left  z-pixel
 is (1,1).
    StatusWin.SetCursor(1,1);

MoveCursor(rowoff,coloff)
 Move  the  ZWindow's cursor rowoff units vertically  and
 coloff units horizontally from it's current position.
    MainWin.MoveCursor(-5,2);


HideCursor(), UnHideCursor()
 Makes   the   ZWindow's  cursor  invisible  or   visible
 (respectively).
    StatusWin.HideCursor();

SetMargins(lmar,rmar)
 Sets the ZWindow's left margin to be lmar units and it's
 right margin to be rmar units.
    MainWin.SetMargins(5,5);

SetColours(fg, bg), SetBGColour(bg), SetFGColour(fg)
 Controls the colour settings of the ZWindow.  The  first
 form  sets  the ZWindow's foreground colour to  fg,  and
 it's background colour to be bg.
    MainWin.SetColours(CL_WHITE, CL_BLACK);
 The  other  two  forms change either the  background  or
 foreground colour (respectively).
    StatusWin.SetBGColour(C_UNDERCUR);

SetFont(font)
 Sets the ZWindows current font to font.
    StatusWin.SetFont(FN_COURIER);

SetFontStyle(style)
 Sets  the ZWindow's current font style to style.  (NOTE:
 On   some  interpreters  a  combination  of  styles   is
 possible, so the value may not directly equal a specific
 style.   It  is probably best to treat the  value  as  a
 bitfield.)
    StatusWin.SetFontStyle(ST_BOLD | ST_ITALIC);

Scroll(num)
 Scrolls  the ZWindow num units.  num may be positive  or
 negative.   (NOTE:  This has no bearing on  the  windows
 scrolling attribute.  See WinStyleSet.)
    MainWin.Scroll(MainWin.GetCharHeight()*15);!Scroll 15
    lines.

SetNewlineIntRoutine(routine)
 Sets the ZWindow's newline interrupt routine to routine.
 This routine will be called when the ZWindow's interrupt
 is  about to be set to zero.  This may be used to  cause
 text to print around images.
    MainWin.SetNewlineIntRoutine(ResetMargins);

SetIntCount(num)
 Sets  the  ZWindow's  interrupt countdown  to  num.   By
 default  this  value is zero.  When set to  a  non  zero
 value, it is decremented each time the ZWindow newlines.
 Upon  reaching zero again, the newline interrupt routine
 will be called.
    !Set interrupt count for printing around SomePic
    MainWin.SetIntCount(SomePic.GetXSize()/MainWin.GetCharH
    eight());

SetLineCount(num)
 Set's the ZWindow's line count to num.  This can be used
 to manipulate when [MORE] is printed.
    MainWin.SetLineCount(25);

WinStyleSet(flags)
 Changes   the   ZWindow's  window  style   settings   by
 overwriting  the  ZWindows current style  settings  with
 flags.
    ZWin2.WinStyleSet(WS_TRANSCRIPT | WS_BUFFER);

WinStyleOn(flags)
 Changes  the ZWindow's window style settings by  turning
 on  the  styles  passed in by flags, leaving  all  other
 styles alone.
    ZWin2.WinStyleOn(WS_SCROLL);

WinStyleOff(flags)
 Changes   the   ZWindow's  window  style   settings   by
 WinStyleOff() turns off the styles passed in  by  flags,
 leaving all other styles alone.
    ZWin2.WinStyleOff(WS_WRAP);

WinStyleToggle(flags)
 Changes  the ZWindow's window style settings by flipping
 the  current settings of the styles passed in by  flags,
 leaving all other styles alone.
    ZWin2.WinStyleToggle(WS_TRANSCRIPT | WS_WRAP);

Erase()
 Clears  out  the  ZWindow  with its  current  background
 colour.
    StatusWin.Erase();

DrawPic(pic, y, x)
 Draws  ZPic  pic in the ZWindow.  The y and x parameters
 behave exactly like the ones for ZPic.Draw(y,x).
    StatusWin.DrawPic(StatusBanner,1,1);

ErasePic(pic, y, x)
 Erases  ZPic pic in the ZWindow.  The y and x parameters
 behave exactly like the ones for ZPic.Erase(y,x).
    StatusWin.ErasePic(CRose);


ResizeToPic(pic)
 Sets the size of the ZWindow to be that of the ZPic pic.
    ZWin3.ResizeToPic(Portrait);

ZWinStyle
The ZWinStyle class provides an interface for controlling
the layout of the screen.  The library provides on ZWinStyle
instance called DefaultZWinStyle, which emulates the Inform
Library status line behavior.  Each ZWinStyle should provide
it's own Finish(), Init() and Update().

Activate()
 Calls  the  active style's Finish(), then sets  the  the
 ZWinStyle  as the active style, and finally,  calls  the
 new active style's Init().
    CRoseStyle.Activate();

Init()
 This  should be provided by the programmer.   It  should
 set  up  the windows and margins used by the style.   It
 may  wish to draw any background image that will  reside
 on screen while this style is active.

Update()
 This  should be provided by the programmer.  It will  be
 called  each  turn when DrawStatusLine would  have  been
 called.

Finish()
 This  should be provided by the programmer.  It will  be
 called before this style is retired in favor of another.
 It  should  set  all  windows  back  to  their  previous
 positions,  undo any margin changes, and such  that  may
 get in the way of the new style.

Library Defined Information

Constants

Colours
 The  following colours are defined as constants  by  the
 library:  C_BLACK,  C_RED,  C_GREEN,  C_YELLOW,  C_BLUE,
 C_MAGENTA, C_CYAN, C_WHITE, C_GREY.  C_UNDERCUR is  also
 provided,  it  refers to the colour  under  the  cursor.
 (NOTE:   There  has been no consensus on whether  modern
 interpreters should use Infocom's Dos or Amiga  palette.
 Until this is decided upon, C_GREY is actually a Global,
 to make the library work similar on both platforms.  I'm
 pushing for the Amiga palette myself).

Fonts
 The  following  fonts are defined as  constants  by  the
 library:  FN_NORMAL, FN_PICTURE, FN_GRAPHIC, FN_COURIER.
 To  the  best of my knowledge most V6 interpreters  will
 only  display  FN_NORMAL and FN_COURIER.   FN_PREV  will
 switch to the previously used font.

Text Styles
 The  following text styles are defined as  constants  by
 the  library:  ST_ROMAN, ST_REVERSE, ST_BOLD, ST_ITALIC,
 ST_FIXED.  On some interpreters a combination of  styles
 may  be possible.  In these cases, setting the style  to
 ST_ROMAN should clear all other styles.

Window Styles
 The  following  constants are defined  by  the  library:
 WS_WRAP  (wrap  text), WS_SCROLL (scroll the  window  if
 text  doesn't fit),  WS_TRANSCRIPT (text in this  window
 should  be  included in the transcript, WS_BUFFER(buffer
 text before printing).


Appendix


Thanks!
I want to take this time/space to thank the following people
for there
help and support and such with V6Lib:

Matt Ackeret, Neil Brown, Charlie Cole, John Holder, Stefan
Jokisch, Patrick Kellum, Vincent Laviano, Howard Liu, Denise
Nedley, Graham Nelson, Gunther Schmidl, Miron Schmidt, and
Brian Waite.
(Sorry if I'm forgetting anybody, feel free to remind me...)

Internet Resources
There's a homepage for V6Lib at:
    http://www.chelmsford.com/home/jpenney/V6Lib/

V6Lib programming questions can be asked on rec.arts.int-
fiction.  I read posts there regularly, and post there semi-
regularly.  By posting your questions on the newsgroup
others may be able to offer assistance as well.

Bug reports, comments, questions or whatever can be sent
directly to me via email.  My address is
[email protected]

You are viewing proxied material from mercury.661.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.