programming/hugo/library/contributions/boxdraw.h

!\===========================================================================
NOTE: This is version 5, dated 970818. It supercedes the previous version,
version 4. This version incorporates the following changes:

1. The display variables have been changed to conform with Hugo v2.4
   standards. Specifically, the variable "linelength" is now the property
   "display.linelength" and the variable pagelength is the property
   "display.windowlines".

NOTE: In what follows, the word "epigram" refers mainly not to a short,
      pithy quotation, but rather to the onscreen box such short, pithy
      quotations are typically displayed in in computer text adventure
      games.


                      THE TWO ROUTINES AND WHAT THEY DO:

Box(epiflag)

Box() is a box-drawing routine for Hugo v2.3. It takes one argument,
WHICH THE USER SHOULD NEVER SUPPLY. IOW, for all intents and purposes
as regards the user, Box() takes no arguments.

When Box() is called, an array of strings (box_array[]) is read and drawn
inside a colored box on the screen. The vertical position of the box
on the screen is determined by the position of the cursor at the time the
routine is called. IOW, the box begins drawing at the cursor's current
(vertical) position. All boxes, however, are centered horizontally, and
this is a behavior which cannot be overridden.

The color of the box and its text are determined by the two globals
BOX_TEXTCOLOR and BOX_BGCOLOR, which must be set up prior to the draw. If
these values are not set, the box will be drawn in reverse-video colors.

There is no provision for variable margins. All boxes are drawn "tight"
around the enclosed text. That is, every box will be number-of-lines-
plus-two high by length-of-longest-line-plus-four wide. Also, there is
no way to override the text-centering. Every line of text in a box will
be center-justified. If a user desires right- or left-justified text,
however, it can still be accomplished by supplying leading or trailing
spaces in the text strings themselves.

The number of lines of text a box can accommodate is controlled by the
constant MAX_BOX_LINES. MAX_BOX_LINES is set to 10 by default. 


Epigram(pauseflag)

Epigram() is a routine for Hugo v2.3 that uses Box() to display epigrams
on the screen. Epigram() takes one true-or-false argument (pauseflag). The
purpose of the argument is this: it is desirable at different times for
epigrams to behave in different ways. Most of the time, an epigram should
wait for all of a current turn's text to be printed before displaying itself
on the screen. This is the default mode, and no argument need be supplied
in order to get this kind of behavior. However, there are times as well
(such as during the opening sequence of a game) when the epigram should
display immediately, pausing to allow the player to read it before
continuing on with the next line of code. For situations like this,
Epigram() should be called with "true".

The only other difference between an epigram and a normal inline box is
the vertical position on the screen at which it displays. An epigram always
displays five rows down from the top of the screen, which means that any
existing text at that position will be overdrawn. For this reason (and
others as well), it is suggested that epigrams be used in moderation and
only in ways that are not likely to interfere with the playing of a game. 

Here's how to use Box():

First, store the strings you want boxed in box_array[]:

        box_array[0] = "This box drawn with Box()"
        box_array[1] = "by Cardinal Teulbachs (c) 1997"
        box_array[2] = " "
        box_array[3] = "All Rights, whatever those might be, Reserved"

Then, just call Box():

        Box()

That's all there is to it. All the contents of box_array[] will be centered
on the screen in a colored box. (Note, however, that a null string will be
interpreted as the end of the array, so that if a blank line is desired
inside the box, one should use a delimited space instead, as in case
box_array[2] above).

To display the same text as an epigram, call Epigram():

        Epigram()
or
        Epigram(true)

Now the box will display in the upper center of the screen, overwriting
whatever is beneath it. Remember that when Epigram() is called with a
non-zero argument, the screen pauses and waits for a keypress. Otherwise it
waits until a turn is completely finished before displaying itself.

IMPORTANT: IN ADDITION TO THE CODE SUPPLIED BELOW, THE FOLLOWING LINES
           MUST BE ADDED TO THE END OF THE main() ROUTINE:

           if epigram_on
           { "" : Box(true) }


Ok. That's it. Enjoy!
This file by Cardinal Teulbachs, (c) 1997

===========================================================================\!
! Either just #include this whole file before init() in your source, or
! declare these values before init() 

constant MAX_BOX_LINES 10                  ! max lines allowed in a box
global BOX_TEXTCOLOR = BGCOLOR             ! text color for boxes     
global BOX_BGCOLOR = TEXTCOLOR             ! background color for boxes
array box_array[MAX_BOX_LINES]             ! the string array
global EPIGRAM_ON                          ! switch for epigram display mode

!\
   NOTE: The BOX_TEXTCOLOR and BOX_BGCOLOR globals won't work properly
         unless they are re-initialized in the init() routine. So do that.
\!

! and put these routines anywhere after the above declarations.

routine Epigram(pauseflag)
{
  if pauseflag
  {
    Box(true)
    locate display.linelength, display.windowlines
    pause
  }
  else
    EPIGRAM_ON = true

  return true
}

routine Box(epiflag)   ! epiflag should never be supplied by user
{
  local a, b, l, old_lng, lng, startpos, endpos, row = 3

  Font(PROP_OFF)

  for (a=0; a <= MAX_BOX_LINES; a++)
  {
    old_lng = lng
    if box_array[a] = 0
      break

    l = string(_temp_string, box_array[a])
    lng = higher(old_lng,l)
  }

  if lng >= (display.linelength - 4)    ! if strings too long
  {                                     ! display them using normal
    print ""                            ! left-justifying engine routine
    for (b=0; b <= MAX_BOX_LINES; b++)              
    {
      if box_array[b] = 0
        break
      print box_array[b]
    }
    b = 0
    while(box_array[b] ~= 0)            ! then flush the array
    {
      box_array[b] = 0
      if b = MAX_BOX_LINES - 1
        break
      b++
    }
    return false                        ! and bail out
  }

  lng = lng + 4

  if not mod(display.linelength,2) and not mod(lng,2)   ! if screen width and string
    endpos = (display.linelength/2 + lng/2)             ! length evenly divide by 2
  else
    endpos = ((display.linelength/2 + lng/2) + 1)       ! if one or both lengths odd
  startpos = (display.linelength/2 - lng/2)

  if epiflag
    startpos += 1

  if epiflag                                    ! if this is epigram
    locate startpos, row
  else                                          ! elseif this is regular box
    print to startpos;

  color BOX_TEXTCOLOR, BOX_BGCOLOR
                                        !        Draw:
  print " ";                            ! top left corner of box

  for (b=0; b <= (lng - 3); b++)
    print " ";                          ! top of box

  print " ";                            ! top right corner of box

  if not epiflag
  { color TEXTCOLOR, BGCOLOR
    print to display.linelength                 !       End Line
  }

  for (b=0; b < a; b++)
  {
    l = string(_temp_string, box_array[b])

    if epiflag                          ! if this is epigram
      locate startpos, ++row   
    else                                ! elseif this is regular box
      print to startpos;

    color BOX_TEXTCOLOR, BOX_BGCOLOR

                                        !       Draw:
    print " ";                          ! left side of box

    print to (display.linelength/2 - l/2); box_array[b];     ! the string, centered
    print to (endpos-1);

    print " ";                          ! right side of box

    if not epiflag
    { color TEXTCOLOR, BGCOLOR
      print to display.linelength               !  End Line, Repeat
    }
  }
      
  if epiflag                            ! if this is epigram
    locate startpos, ++row
  else                                  ! elseif this is regular box
    print to startpos;

  color BOX_TEXTCOLOR, BOX_BGCOLOR

                                        !       Draw:
  print " ";                            ! bottom left corner of box

  for (b=0; b <= (lng - 3); b++)
    print " ";                          ! bottom of box

  print " ";                            ! bottom right corner of box

  if not epiflag
  { color TEXTCOLOR, BGCOLOR
    print to display.linelength                 !       End Line
  }

  a = 0
  while(box_array[a] ~= 0)              ! flush string array
  { box_array[a] = 0
    if a = MAX_BOX_LINES - 1
      break
    a++
  }

  color TEXTCOLOR, BGCOLOR
  Font(DEFAULT_FONT)

  EPIGRAM_ON = false                    ! turn off epigram switch and

  return true                           ! go home happy and contented
}