Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/211.lha/Blk/bdoc

Text File | 1996-02-14 | 9.4 KB | 254 lines

          BLK - Automatic Requester Generator


BLK generates C code for declaring requesters.  It automatically formats
borders and text and generates the declarations for them.  The requester
can contain boolean, string and proportional gadgets.


Boxes:

BLK formats requesters as nested boxes.  The root box is the requester
itself.  Inner boxes can be formatted horizontally or vertically.  Borders
and text strings are thought of as boxes for the purpose of formatting.  The
box grammer, which is loosly based on lisp syntax, can be described by the
BNF description given below.  Non-terminal symbols are named and terminal
symbols are double quoted strings.

   box   :== fill | text | bord | block | seq
   fill  :== "f"
   text  :== "(t" onum str ")"
   str   :== [double quoted string]
   bord  :== rule | "(" rule num onum ")"
   rule  :== "|" | "-"
   block :== "(b" num num ")"
   seq   :== "(" ("h"|"v") blist ")"
   blist :== box | box blist
   onum  :== num | [nothing]
   num   :== [unsigned integer]

Some examples:

The following produces a 10 x 10 pixel square:

   (h | (v - (b 10 10) - ) | )

The central structure, "(b 10 10)," is a 10 x 10 block.  This is one of three
boxes in a vbox, or vertically oriented list of boxes.  The other two boxes
in the list are hrules, "-," which are horizontal "rules," or lines.  This
produces a box containing an empty area with lines above and below it.  This
box is further included with two vertical rules, "|," in an hbox - a
horizontally oriented list.  This puts horizontal lines on each side of the
box, closing the square.

      -----       |-----|
      xxxxx       |xxxxx|
      xxxxx       |xxxxx|
      xxxxx       |xxxxx|
      -----       |-----|

Rules are elastic, and while they have no intrinsic length they will expand
to fill any space available within their bounding box.  The vbox,
"(v - (b 10 10) - )," has dimensions 10 x 12, so each hrule expands to a
length of 10.

Fills are another type of elastic object.  For example, suppose you wanted
to format a set of strings, like:

      Line #1
      Blah Blah
      ETC

You could list the text boxes in a vbox, thus:

   (v (t"Line #1") (t"Blah Blah") (t"ETC"))

This would produce the formated lines as above.  But then suppose you wanted
each line centered within its box.  For this you use fills.  Each fill
expands to take up as much free space as it can within its bounding box, and
if a string is sandwiched between two fills horizontally, it will be
squeezed by competing fills into the center of its bounding box.

   (v
      (h f (t"Line #1")   f)
      (h f (t"Blah Blah") f)
      (h f (t"ETC")       f)
    )

Now the boxes within the vbox are not text boxes but hboxes containing text
boxes with fills to the left and right.  The width of the vbox is computed
as the maximum width of each box it contains.  Since fills have no intrinsic
size, the widest hbox is the one containing the text box (t"Blah Blah"),
which has a width of 9 characters, or 72 pixels.  (BLK always assumes an
8x8 font.)  So each of the other two shorter hboxes are contained
within a vbox of width 72, so each fill expands to make up the difference.
For example, the first hbox contains two fills and a 56 pixel wide text box.
To fill up a 72 pixel wide bounding box, each fill can expand 8 pixels
horizontally, thus centering the text box inbetween them.  The result is:

      Line #1
     Blah Blah
        ETC

This whole structure is just a box, and can be used within other box
structures.  For example, to put a border around the above box, you could
use the definition from the first example.  Specifically:

 (h | (v -
   (v
      (h f (t"Line #1")   f)
      (h f (t"Blah Blah") f)
      (h f (t"ETC")       f)
    )
  -) |)

The problem with this (you will see if you try it) is that the rules
surrounds the text too closely.  Since there is no space between the text and
the lines they lie almost right on top of each other.  Text boxes look ok
right next to each other, but rules need to be explicitly spaced away from
text.  This can be done with "struts," blocks used explicitly as spacers,
like so:

 (h | (v - (b 0 5) (h (b 5 0)
   (v
      (h f (t"Line #1")   f)
      (h f (t"Blah Blah") f)
      (h f (t"ETC")       f)
    )
  (b 5 0)) (b 0 5) -) |)

The 0 x 5 and 5 x 0 blocks have no volume but since they have width or
height, they affect the spacing of the other components in their h- or
vboxes.

Text and rules take on the default color (see "BLK files" below) unless the
color is explicitly stated.  For text boxes this is done with the optional
parameter in the text box description, as in (t 3 "hi there"), which
specifies that the text be color #3.  For rules, a different description
format is used.  Instead of simply | or -, a form such as (| 1 3) or (- 1 2)
is used.  The two examples create a vrule of color 3 and an hrule of color 2
respectively.  The first number is the width of the rule and should always
be 1.

This is about all there is to it.  With these simple tools, it is possible
to design a wide variety of nicely layed-out requesters without dealing with
a single number or C struct.  What is more, the strings in the above box
definition could be changed to anything, and the result would still be three
strings centered within a perfectly sized box.


Gadgets:

Any sub-box in a box definition can be defined to be a gadget hit box by
following it with the sequence:

   ":" num

From the above example, each text box could be defined as a hit box for a
gadget by restating it as:

      (h f (t"Line #1"):1   f)
      (h f (t"Blah Blah"):2 f)
      (h f (t"ETC"):3       f)

Given these box definitions, BLK will generate code for 3 BOOLEAN,
RELVERIFY, REQGADGET, GADGHCOMP gadgets with the GadgetID's 1,2 and 3.
Other types of gadgets can be defined using an extended gadget definition.
These are of the form:

   num {"s"|"p"} {":"id} flags

Stuff in {}'s is optional; "id" and "flags" are double-quoted strings.
"Num" is the id number for the gadget given after the ":" in the box
definition.  The optional "s" or "p" specify string or proportional gadgets,
the default being boolean.  The optional "id" string specifies a string to
be used for the GadgetID field in the gadget struct instead of just using
"0x<num>," where num is the id given in the box description.  "Flags" is a
set of characters used to specify flags available in defining a gadget.
Valid flags are (case is significant):

      B : GADGHBOX  (default is GADGHCOMP if this is ommited)
      t : TOGGLESELECT
      v : RELVERIFY
      e : ENDGADGET
      i : GADGIMMEDIATE
      c : STRINGCENTER  (string gadgets only)
      f : FOLLOWMOUSE

The default flags string is "v".  Here are some examples:

1p""              - proportional gadget with no flags
7:"OK_ID""ev"     - boolean gadget with id "OK_ID"
                     RELVERIFY and ENDGADGET flags set
5s"v"             - RELVERIFY string gadget
5s:"STR_ID""i"    - string gadget with id "STR_ID", GADGIMMEDIATE flag


BLK output:

The code that BLK outputs follows some simple conventions.  These were
implemented for my own convenience and can be changed by altering the source
code.  Structs are assigned in arrays, the name of each array being some
base name followed by the type of struct.  For example, if the base name
were xyz, some structs would be xyz_req, xyz_str, etc.  They are:

   struct Requester <base>_req      /* not an array */

   struct Gadget <base>_gad[]       /* always included */
   struct IntuiText <base>_txt[]
   struct Border <base>_brd[]
   short <base>_brd_XY[]

   UBYTE <base>_nbuf[][NUMCHR]      /* only if string gadgets defined */
   struct StringInfo <base>_sinfo[]

   struct Image <base>_pimg[]       /* only if prop gadgets defined */
   struct PropInfo <base>_pinfo[]

In user code, the symbol "ta" must be declared as struct TextAttr as in:

   struct TextAttr ta = { ... };  /* or */
   extern struct TextAttr ta;

To use string gadgets, the symbol "NUMCHR" must be #defined as the number of
characters in the string buffer.  The symbol "undo" must be declared as

   UBYTE undo[NUMCHR];

to be used as the undo buffer for string gadgets.  The string buffers will
be assigned in the order that they are encountered in reading the box
description, so the buffer for the first encountered will be <base>_nbuf[0],
the buffer for the second will be <base>_nbuf[1], and so on.


BLK files:

A blk input file contains all the information to describe a single
requester.  It starts with a string that is to be the base name for this set
of declarations.  There are then two optional numbers which are the default
border color and default text color.  Neither need to be specified and will
both default to 1.  Then comes the box definition followed by a set of
extended gadget descriptions.  Some examples are included in this release.


Using BLK:

The BLK commandline is:

   blk infile { "%" | outfile }

"Infile" is the input requester description.  The input file will be read
and the resulting requester will be displayed in a window.  If no output is
specified, BLK will wait for a few seconds and then exit.  (If you need more
time to view the results of you handiwork, just hold down the right mouse
button.)  If "%" is given as output, BLK will PRINT the box tree to standard
output.  This can be a huge ammout of output, but can be useful if you need
to know the exact coordinates or size of something.  If "outfile" is
specified, BLK will output the C declarations to this file.

Stuart Ferguson
            ([e-mail])    12/87
            ([e-mail])