Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

XG.3D-INSERT-HERSHEY-STRING

source files: xhsy.[ch] xgrl.[ch]

SYNTAX

(XG.3D-INSERT-HERSHEY-STRING
    :THING <thing>
    :TEXT "some text"
  [ :FONT <fix:font-index> ]
  [ :X    <fix:x> ]
  [ :Y    <fix:y> ]
  [ :Z    <fix:z> ]
  [ :LEFT-MARGIN      <fix:margin> ]
  [ :VERTICAL-SPACING <fix:vspacing> ]
  [ :JUSTIFY { :LEFT | :CENTER | :RIGHT } ]
  [ :TRANSFORM <xtfm> ]
  [ :SCALE   <flo:scale> ]
  [ :SCALE-X <flo:scalex> ]
  [ :SCALE-Y <flo:scaley> ]
  [ :SCALE-Z <flo:scalez> ]
  [ :UPDATE-CURSOR NIL ]
)

DESCRIPTION

This call accepts an ascii string and converts it into a set of vectors in a line-segment thing. If a thing of triangles or rectangles is supplied, the text is drawn as rods capped with spheres rather than as simple line segments; In this case, all the additional parameters accepted by the INSERT-BALL and INSERT-ROD functions may be supplied -- in particular, you will likely need to provide a :RADIUS value of about 0.05 to produce reasonable results.

The <thing> must be a 'thing' in the :DRAW <xcmr> sense, containing a <point-grl> and a <facet-grl>.

<point-grl> contains the :point-x/y/z float-arrays to hold the points of the string.

<facet-grl> contains :facet-0, and :facet-1 arrays defining line segments.

"some text" is a regular xlisp string, which is to be converted into a set of grl line-segments using the Hershey font definitions.

<font-index> An integer in the range [1..11], identifying which font should be used. (Font 0 is also allowed, but is a nonalphabetic set of special symbols.) Font 1 (the default) one is the workaday choice, the others get successively fancier. Be warned, the special characters in the fonts aren't very ASCII-compatible ... a little work here wouldn't hurt.

<facet-grl> may have fixnum :CURSOR-X, :CURSOR-Y, :CURSOR-Z and :LEFT-MARGIN properties, initialized to the x/y/zcoord at which you wish the string to start, and the x-coordinate to which you wish the cursor to return after each newline. If not provided, they will default to zero. They will be updated to reflect the end of the string after each message, so that successive xg.3d-insert-hershey-string calls with the same <thing> will append to the existing string in sensible fashion.

If :X, :Y or :Z are provided, they override the currently set :CURSOR-X/Y/Z.

Similarly, if :LEFT-MARGIN is provided, it replaces the currently set :LEFT-MARGIN property, and if :VERTICAL-SPACING is provided, it replaces the currently set :VERTICAL-SPACING property.

If :SCALE is provided, the text is scaled by it before being stored. The :SCALE-X and :SCALE-Y option allow independent scaling on X and Y if desired.

The :JUSTIFY parameter defaults to :LEFT, meaning that the cursor specifies the position of the left end of the inserted string. If it is set to :RIGHT, the cursor specifies the position of the right end of the inserted string; if it is set to :CENTER, the string will be centered on the given cursor coordinates. Note: :CENTER and :RIGHT justify options are only intended for single lines of text, :RIGHT justify in particular probably won't do what you want for a paragraph.

If :TRANSFORM is supplied, it must be an instance of CLASS-MATRIX44, and will be used to transform the text exactly as if by XG.3D-TRANSFORM-THING.

If :UPDATE-CURSOR is supplied, it controls whether an internal cursor position should be updated. Letting it default to t results in successive calls appending text in visually sensible fashion. Setting it to NIL results in successive calls writing text at the same address -- which may be what you want if you clearing the relation between each call and inserting updated text.

Currently, nonprinting characters other than newline ("\n") (and blank, of course) are not supported.


Go to the first, previous, next, last section, table of contents.