{comment this file contains the first part of the display chapter, with sections on:
POSITION
REGION
BITMAP
BITBLT
TEXTURE
Saving BITMAPs
Screen Operation
Characters and Fonts
}


{Begin SubSec POSITION}
{Title POSITION}
{Text

A position denotes a point in an X,Y coordinate system.  A
{lisp POSITION} is an instance of a record with fields {lisp XCOORD}
and {lisp YCOORD} and is manipulated with the standard record
package facilities.  For example, {lisp (create POSITION XCOORD _ 10 YCOORD _ 20)} creates a position representing the point (10,20).


{FnDef {Name POSITIONP} {Args X}
{Text
Returns {arg X} if {arg X} is a {lisp POSITION}; {lisp NIL} otherwise.
}}

}{End SubSec POSITION}


{Begin SubSec REGION}
{Title REGION}
{Text

A Region denotes a rectangular area in a coordinate system.  Regions
are characterized by the coordinates of their bottom left corner and
their width and height.  A {lisp REGION} is a record with fields
{lisp LEFT}, {lisp BOTTOM}, {lisp WIDTH}, and {lisp HEIGHT}.  It can be
manipulated with the standard record package facilities.  There are
access functions for the {lisp REGION} record that returns the {lisp
TOP} and {lisp RIGHT} of the region.

The following functions are provided for manipulating regions:
  
{FnDef {Name CREATEREGION} {Args LEFT BOTTOM WIDTH HEIGHT}
{Text
Returns an instance of the {lisp REGION} record which has {arg LEFT}, {arg BOTTOM}, {arg WIDTH} and {arg HEIGHT} as respectively its {lisp LEFT}, {lisp BOTTOM}, {lisp WIDTH}, and {lisp HEIGHT}.

Example:
{lisp (CREATEREGION 10 -20 100 200)}
will create a region that denotes a rectangle whose width is 100, whose height is 200, and whose lower left corner is (10,-20).
}}

{FnDef {Name INTERSECTREGIONS}
{Args REGION{sub 1} REGION{sub 2} {ellipsis} REGION{sub n}}
{Type nospread}
{Text
Returns a region which is the intersection of a number of regions.
Returns {lisp NIL} if the intersection is empty.  If there are no
regions given, it returns a very large region.
}}


{FnDef {Name UNIONREGIONS}
{Args REGION{sub 1} REGION{sub 2} {ellipsis} REGION{sub n}}
{Type nospread}
{Text
Returns a region which is the union of a number of regions, i.e. the
smallest region that contains all of them.  Returns {lisp NIL} if
there are no regions given.
}}


{FnDef {Name REGIONSINTERSECTP} {Args REGION1 REGION2}
{Text
Returns {lisp T} if {arg REGION1} intersects {arg REGION2}.
Returns {lisp NIL} if they do not intersect.
}}


{FnDef {Name SUBREGIONP} {Args LARGEREGION SMALLREGION}
{Text
Returns {lisp T} if {arg SMALLREGION} is a subregion (is equal to or entirely contained in) {arg LARGEREGION}; otherwise 
returns {lisp NIL}.
}}


{FnDef {Name EXTENDREGION} {Args REGION INCLUDEREGION}
{Text
Changes (destructively modifies) the region {arg
REGION} so that it includes the region {arg INCLUDEREGION}.
It returns {arg REGION}.
}}

{FnDef {Name MAKEWITHINREGION} {Args REGION LIMITREGION}
{Text
Changes (destructively modifies) the left and bottom of region {arg
REGION} so that it is within the region {arg LIMITREGION}, if possible. If the dimension of {arg REGION} are larger than {arg LIMITREGION}, {arg REGION} is moved to the lower left of {arg LIMITREGION}.  If {arg LIMITREGION} is {LISP NIL}, {var WHOLEDISPLAY} (the screen region) is used.
It returns {arg REGION}.
}}


{FnDef {Name INSIDEP} {Args REGION X Y}
{Text
If {arg X} and {arg Y} are numbers, it returns {lisp T} if the point
({arg X},{arg Y}) is inside of {arg REGION}.  If {arg X} is a {lisp
POSITION}, it returns {lisp T} if {arg X} is inside of {arg REGION}.  If {ARG REGION} is a {LISP WINDOW}, the window's interior region in window coordinates is used.
Otherwise, it returns {lisp NIL}.
}}

}{End SubSec REGION}



{Begin SubSec BITMAP}
{Title BITMAP}
{Text

The display primitives manipulate graphical images in the form of {term bitmaps}.  A bitmap is a rectangular array of "pixels," each of which is an integer representing the color of one point in the bitmap image.  A bitmap is created with a specific number of bits allocated for each pixel.  Most bitmaps used for the display screen use one bit per pixel, so that at most two colors can be represented.  If a pixel is 0, the corresponding location on the image is white.  If a pixel is 1, its location is black.  (This interpretation can be changed with the function {fn VIDEOCOLOR}; see {PageRef Fn VIDEOCOLOR}.)  Bitmaps with more than one bit per pixel are used to represent color or grey scale images.

Bitmaps use a positive integer coordinate system with the lower left corner pixel at coordinate (0,0).  Bitmaps are represented as instances of the datatype {lisp BITMAP} with fields {lisp BITMAPWIDTH}, {lisp BITMAPHEIGHT}, {lisp BITMAPBITSPERPIXEL}, {lisp BITMAPRASTERWIDTH}, and {lisp BITMAPBASE}.  Only the width, height, and bits per pixel fields are of interest to the user, and can be accessed with the following functions:

{note do we need to tell about what fields are in bitmaps??}

{FnDef {Name BITMAPWIDTH} {Args BITMAP}
{Text
Returns the width of {arg BITMAP} in pixels.
}}

{FnDef {Name BITMAPHEIGHT} {Args BITMAP}
{Text
Returns the height of {arg BITMAP} in pixels.
}}

{FnDef {Name BITSPERPIXEL} {Args BITMAP}
{Text
Returns the number of bits per pixel of {arg BITMAP}.
}}


The functions used to manipulate bitmaps are:

{FnDef {Name BITMAPCREATE} {Args WIDTH HEIGHT BITSPERPIXEL}
{Text
Creates and returns a new bitmap which is {arg WIDTH} pixels wide by {arg HEIGHT} pixels high, with {arg BITSPERPIXEL} pits per pixel.  If {arg BITSPERPIXEL} is {lisp NIL}, the default is 1.
}}


{FnDef {Name BITMAPBIT} {Args BITMAP X Y NEWVALUE}
{Text
If {arg NEWVALUE} is between 0 and the maximum value for a pixel in {arg BITMAP}, the pixel ({arg X,Y}) is changed to {arg NEWVALUE} and the old value is returned.  If {arg NEWVALUE} is {lisp NIL}, {arg BITMAP} is not changed but the value of the pixel is returned.  If {arg NEWVALUE} is anything else, an error is generated. If ({arg X,Y}) is outside the limits of {arg BITMAP}, 0 is returned and no pixels are changed.  {arg BITMAP} can also be a window.
}}


{FnDef {Name BITMAPCOPY} {Args BITMAP}
{Text
Returns a new bitmap which is a copy of {arg BITMAP} (same dimensions and contents).
}}

{FnDef {Name EXPANDBITMAP} {Args BITMAP WIDTHFACTOR HEIGHTFACTOR}
{Text
Returns a new bitmap that is {arg WIDTHFACTOR} times as wide as {arg BITMAP} and {arg HEIGHTFACTOR} times as high.  Each pixel of {arg BITMAP} is copied into a {arg WIDTHFACTOR} times {arg HEIGHTFACTOR} block of pixels.  If {lisp NIL}, {arg WIDTHFACTOR} defaults to 4, {arg HEIGHTFACTOR} to 1.

{note WIDTHFACTOR defaults to 4, HEIGHTFACTOR to 1.
this is because so that this could be used to translate 1 bitperpixel bitmaps to 4 bitperpixel color bitmaps.  However, we don't want to do this, because this relies on knowing that bitmaps are stored width-first.  For now, perhaps this should be done by allocating a new array, and doing a BITBLT.}

{note Q: I assume that the new bitmap returned by expand macro has the same bitsperpixel??}
}}


There are two distinguished bitmaps that are read by the hardware to become visible as the screen and the cursor.  The screen is a bitmap {lisp SCREENWIDTH} (=1024) wide by {lisp SCREENHEIGHT} (=808) high.  The cursor is a bitmap {lisp CURSORWIDTH} (=16) wide by {lisp CURSORHEIGHT} (=16) high.  They are accessed by:


{FnDef {Name SCREENBITMAP}
{Text
Returns the screen bitmap.
}}


{FnDef {Name CURSORBITMAP}
{Text
Returns the cursor bitmap.

Note:  The cursor bitmap can be changed with the function {fn CURSOR} ({PageRef Fn CURSOR}).
}}


}{End SubSec BITMAP}


{Begin SubSec BITBLT}
{Title BITBLT}
{Text

{fn BITBLT} is the primitive function for moving bits from one bitmap to another.  It is similar to the function {lisp RASTEROP}{index RASTEROP Fn} that is used in other systems.


{FnDef {Name BITBLT} {Args SOURCEBITMAP SOURCELEFT SOURCEBOTTOM
DESTINATIONBITMAP DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT SOURCETYPE OPERATION TEXTURE CLIPPINGREGION}
{Text}}

{arg WIDTH} and {arg HEIGHT} define a pair of rectangles, one in each of the {arg SOURCEBITMAP} and {arg DESTINATIONBITMAP} whose left, bottom corners are at, respectively, ({arg SOURCELEFT}, {arg SOURCEBOTTOM}) and ({arg DESTINATIONLEFT}, {arg DESTINATIONBOTTOM}).  If these rectangles overlap the boundaries of either bitmap they are both reduced in size (without translation) so that they fit within their respective boundaries.  If {arg CLIPPINGREGION} is non-{lisp NIL} it should be a {lisp REGION} and is interpreted as a clipping region within {arg DESTINATIONBITMAP}; clipping to this region may further reduce the defining rectangles.  These (possibly reduced) rectangles define the source and destination rectangles for {fn BITBLT}.  {arg SOURCEBITMAP} and {arg DESTINATIONBITMAP} can also be display streams or windows, in which case their associated bitmaps are used.

The mode of transferring bits is defined by {arg SOURCETYPE} and {arg OPERATION}.  {arg SOURCETYPE} and {arg OPERATION} specify boolean functions that are used to determine, respectively, the method of combining {arg SOURCEBITMAP} bits with the {arg TEXTURE} and the operation between these resultant bits and {arg DESTINATIONBITMAP}.  {arg TEXTURE} is a gray pattern, as described on {PageRef Tag Textures}.  (Note:  The alignment of the texture pattern with {fn BITBLT} is such that the origin of the destination bitmap is at an intersection of the "tiles.")

{arg SOURCETYPE} specifies how to combine the bits from {arg SOURCEBITMAP} with the bits from {arg TEXTURE} (a background pattern) to produce a "Source".  This is designed to allow characters and figures to be placed on a background.


{index SOURCETYPE (BITBLT argument)}

{Begin Table Sourcetype specifies}

{COLUMN 25percent}	{COLUMN}

{First {arg SOURCETYPE}}		{Next Source}
{First {lisp INPUT}}	{Next {arg SOURCEBITMAP}}
{First {lisp INVERT}}	{Next {lisp (NOT {arg SOURCEBITMAP})}}
{First {lisp TEXTURE}}	{Next {arg TEXTURE}}

{End Table Sourcetype specifies}

{note TEXTURE being deimplemented.  Flushed here? ??? How can Texture be deimplemented?? rrb}

For the {lisp INPUT} and {lisp INVERT} case, the {arg TEXTURE}
argument to {fn BITBLT} is ignored.  For the {lisp TEXTURE} case,
the {arg SOURCEBITMAP}, {arg SOURCELEFT}, and {arg SOURCEBOTTOM}
arguments are ignored.

{arg OPERATION} specifies how this source is combined with the bits in {arg DESTINATIONBITMAP} and stored back into {arg DESTINATIONBITMAP}.


{index OPERATION (BITBLT argument)}

{Begin Table Operation specifies}

{COLUMN 25percent}	{COLUMN}

{First {arg OPERATION}}		{Next {arg DESTINATIONBITMAP} becomes}
{First {lisp REPLACE}}	{Next Source}
{First {lisp PAINT}}	{Next {lisp (OR {arg DESTINATIONBITMAP}} Source{lisp )}}
{First {lisp INVERT}}	{Next {lisp (XOR {arg DESTINATIONBITMAP}} Source{lisp )}}
{First {lisp ERASE}}	{Next {lisp (AND {arg DESTINATIONBITMAP} (NOT} Source{lisp ))}}

{End Table Operation specifies}


{arg SOURCELEFT}, {arg SOURCEBOTTOM}, {arg DESTINATIONLEFT}, and {arg DESTINATIONBOTTOM} default to 0.  {arg WIDTH} and {arg HEIGHT} default to the width and height of the {arg SOURCEBITMAP}.
{arg TEXTURE} defaults to white.  {arg SOURCETYPE} defaults to {lisp INPUT}. {arg OPERATION} defaults to {lisp REPLACE}.
If {arg CLIPPINGREGION} is not provided, no additional clipping is done.
{fn BITBLT} returns {lisp T} if any bits were moved;{note ???}
{lisp NIL} otherwise.


Note:  {fn BITBLT} and {fn BITMAPBIT} accept windows and display streams as their bitmap arguments.  In these cases, the remaining arguments are interpreted as values in the coordinate system of the window or display stream and the operation of the functions are translated and clipped accordingly.  If a window or display stream is used as the destination to {fn BITBLT}, its clipping region limits the operation involved.

{note no longer true ==>
However, if a display stream is used as the source to {fn BITBLT}, its clipping region does not limit the bits transferred.}


{note EXAMPLES, WITH PICTURES!!  -- lmm}

}{End SubSec BITBLT}



{Begin SubSec TEXTURE}
{Title TEXTURE}
{Text

{index Textures}

{Tag Textures}



A Texture denotes a pattern of gray which can be used by {fn BITBLT} to (conceptually) tessellate the plane to form an infinite sheet of gray.  It is currently either a 4 by 4 pattern or a 16 by n (n <= 16) pattern.  Textures are created interactively using the function {fn EDITSHADE} or from bitmaps using the following function.


{FnDef {Name CREATETEXTUREFROMBITMAP} {Args BITMAP}
{Text
Returns a texture object that will produce the texture of {arg BITMAP}.  If {arg BITMAP} is too large, its lower left portion is used.  If {arg BITMAP} is too small, it is repeated to fill out the texture.
}}


{FnDef {Name TEXTUREP} {Args OBJECT}
{Text
Returns {arg OBJECT} if it is a texture, i.e. a legal texture argument to {fn BITBLT}.
}}


The common textures white and black are available as system constants {var WHITESHADE}{index WHITESHADE Var} and {var BLACKSHADE}.{index BLACKSHADE Var}  The global variable {var GRAYSHADE}{index GRAYSHADE Var} is used by many system facilities as a background gray shade and can be set by the user.  The original background shade of the window system is kept in {var WINDOWBACKGROUNDSHADE}.{index WINDOWBACKGROUNDSHADE Var}{index background shade}  The background shade can be changed by the following function:



{FnDef {Name CHANGEBACKGROUND} {Args SHADE}
{Text
Changes the background shade of the window system.  {arg SHADE} determines the pattern of the background.  If {arg SHADE} is a texture, then the background is simply painted with it.  If {arg SHADE} is a {lisp BITMAP}, the background is tesselated (tiled) with it to cover the screen.  If {arg SHADE} is {lisp T}, it changes to the original shade, the value of {var WINDOWBACKGROUNDSHADE}.  It returns the previous value of the background.
}}


{Begin Note}
Textures can be (and TEXTUREP is true of) BITMAPs of 16 bits wide by up to 16 bits high. 4x4 textures can still be represented as integers.
{End Note}



}{End SubSec TEXTURE}



{Begin SubSec Saving BITMAPs}
{Title Saving BITMAPs}
{Text



Bitmaps can be saved on files with the {filecom VARS} file package command ({PageRef FileCom VARS}).  The following two functions translate bitmaps into and out of a representation which may be used to transfer bitmaps between Interlisp and other computer systems' representations.


{FnDef {Name READBITMAP} {Args FILE}
{Text
Creates a bitmap by reading an expression (written by {fn PRINTBITMAP}) from the file {arg FILE}.
}}


{FnDef {Name PRINTBITMAP} {Args BITMAP FILE}
{Text
Prints the bitmap {arg BITMAP} on the file {arg FILE} in a format that can be read back in by {fn READBITMAP}.

{note (If {arg BITMAP} is an atom whose value is a bitmap, its value will be used.)  -- crock, sez Larry}
}}


{Begin Note}
previous version of READBITMAP description was:

(READBITMAP {arg WIDTH} {arg HEIGHT} {arg BITSPERINTEGER})	[function]
Creates a bitmap which is {arg WIDTH} by {arg HEIGHT} bits in size and gets values for its bits by {lisp READING} an expression that should be a list of integers from the primary input channel. (This convention is adopted from the method of saving arrays on files.)  {arg BITSPERINTEGER} is the number of low order bits that should be taken from each integer in the read list.  Each line of the bitmap begins on a new integer.  Thus, the list of integers should be ((({arg WIDTH}-1)/{arg BITSPERINTEGER})+1)*{arg HEIGHT} elements long.  If {arg WIDTH} is not a multiple of {arg BITSPERINTEGER}, the most significant of the {arg BITSPERINTEGER} bits from the last integer of each line will be used.

This design allows bitmaps to be written on the files in an implementation independent way.  {arg BITSPERINTEGER} should be kept small (less than 20) so that the integers can be read by the {fn READ} function on machines of smaller word size without overflow.  For Interlisp-D, {arg BITSPERINTEGER} is 16.

---  there is a backward compatibility crock allowing READBITMAP to be used in this way, by supplying the arguments WIDTH, HEIGHT, and BITSPERINTEGER, but it is felt that the old way should be de-documented.
{End Note}


}{End SubSec Saving BITMAPs}




{Begin SubSec Screen Operation}
{Title Screen Operation}
{Text

The following functions control the display screen.


{FnDef {Name VIDEOCOLOR} {Args BLACKFLG}
{Type NOSPREAD}
{Text
Sets the interpretation of the bits in the screen bitmap.  If {arg BLACKFLG} is {lisp NIL}, a 0 bit will be displayed as white, otherwise a 0 bit will be displayed as black.  {fn VIDEOCOLOR} returns the previous setting.  If {arg BLACKFLG} is not given, {fn VIDEOCOLOR} will return the current setting without changing anything.

Note:  This function only works on the Xerox 1100 and Xerox 1108.
}}


{FnDef {Name VIDEORATE} {Args TYPE}
{Text
Sets the rate at which the screen is refreshed.  {arg TYPE} is one of {lisp NORMAL} or {lisp TAPE}.  If {arg TYPE} is {lisp TAPE}, the screen will be refreshed at the same rate as TV (60 cycles per second).  This makes the picture look better when video taping the screen.    Note: Changing the rate may change the dimensions of the display on the picture tube.  
}}



Several functions are provided for turning off the display (partially or completely).  See {PageRef Fn SETDISPLAYHEIGHT}.



}{End SubSec Screen Operation}


{Begin SubSec Characters and Fonts}
{Title Characters and Fonts}
{Text

{note how does this font stuff interact with Interlisp-10 font profiles (pages 14.49-52 in the ref. man.)?  Have font profiles been extended in Interlisp-D?  What is the magic for turning off fonts (for sites that don't have font-y printers)?}


Fonts control the way characters look when printed on the screen or a graphics printer.  Fonts are defined by a distinctive style or {lisp FAMILY} (such as Gacha or TimesRoman), a {lisp SIZE} (such as 10 points), and {lisp FACE} (such as bold or italic).  Fonts also have a {lisp ROTATION} that indicates the orientation of characters on the screen or page.  A normal horizontal font (also called a portrait font) has a rotation of 0; the rotation of a vertical (landscape) font is 90 degrees.  While the specification allows any combination, in practice the user will find that only certain combinations of
families, sizes, faces, and rotations are available.

In specifying a font to the functions described below, a {lisp FAMILY} is represented by a literal atom, a {lisp SIZE} by a positive integer, and a {lisp FACE} by a three-element list of the form {lisp (WEIGHT SLOPE EXPANSION)}.  {lisp WEIGHT}, which indicates the thickness of the characters, can be {lisp BOLD}, {lisp MEDIUM}, or {lisp LIGHT}; {lisp SLOPE} can be {lisp ITALIC} or {lisp REGULAR}; and {lisp EXPANSION} can be {lisp REGULAR}, {lisp COMPRESSED}, or {lisp EXPANDED}, indicating how spread out the characters are.  For convenience, faces may also be specified by three-character atoms, where each character is the first letter of the corresponding field.  Thus, {lisp MRR} is a synonym for {lisp (MEDIUM REGULAR REGULAR)}.  In addition, certain common face combinations may be indicated by special literal atoms:


{lisp STANDARD} = {lisp (MEDIUM REGULAR REGULAR)} = {lisp MRR}

{lisp ITALIC} = {lisp (MEDIUM ITALIC REGULAR)} = {lisp MIR}

{lisp BOLD} = {lisp (BOLD REGULAR REGULAR)} = {lisp BRR}

{lisp BOLDITALIC} = {lisp (BOLD ITALIC REGULAR)} = {lisp BIR}


A font also has the properties {lisp ASCENT}, {lisp DESCENT}, and {lisp HEIGHT} (= {lisp ASCENT} + {lisp DESCENT}), and, for each character, a width and bit pattern.  The {lisp ASCENT} is the maximum height of any character in the font from its base line (the printing position).  The {lisp DESCENT} is the maximum extent of any character below the base line, such as the lower part of a "p."  Therefore the top line of a character will be at Base+{lisp ASCENT}-1, while the bottom line will be at Base-{lisp DESCENT}.  The width of each character specifies how a stream's position will change when the character is printed.  This may have both an X and a Y component (e.g., for landscape fonts), and it varies from character to character in variable pitch fonts.

The information about a particular font is represented in a font
descriptor.  The following functions manipulate font descriptors:


{FnDef {Name FONTCREATE} {Args FAMILY SIZE FACE ROTATION DEVICE NOERRORFLG}
{Text
Returns a font descriptor for the specified font.  {arg SIZE} is an integer indicating the size of the font in points.  {arg FACE} specifies the face characteristics in one of the formats listed above; if {arg FACE} is {lisp NIL}, {lisp STANDARD} is used.  {arg ROTATION}, which specifies the orientation of the font, is 0 (or {lisp NIL}) for a portrait font and 90 for a landscape font.
{arg DEVICE} indicates the output device for the font.  For Interlisp-D, the possible values for {arg DEVICE} are {lisp DISPLAY} for the display screen, {lisp PRESS} for Press printers, AND {lisp INTERPRESS} for Interpress printers.  {arg DEVICE} defaults to {lisp DISPLAY}.

For display fonts, {fn FONTCREATE} looks for a {lisp STRIKE} file with the appropriate name (such as {lisp TIMESROMAN8BI.STRIKE} for a {lisp TIMESROMAN 8 BOLDITALIC} font), searching through directories on the list {var FONTDIRECTORIES}.{index FONTDIRECTORIES Var}  If the file is found, it is read into a font descriptor.  If the file is not found, {fn FONTCREATE} looks for fonts with less face information (in this example, {lisp TIMESROMAN8I.STRIKE}) and fakes the remaining faces (such as by doubling the bit pattern of each character or slanting it).  Failing that, {fn FONTCREATE} searches through directories on the list {var NSFONTDIRECTORIES} for an NS display font.{index NSFONTDIRECTORIES Var}  If no appropriately sized font is found, the action of the function is determined by {arg NOERRORFLG}.  If {arg NOERRORFLG} is {lisp NIL}, it generates a {lisp FILE NOT FOUND} error with the name of the most specific file tried (in the example {lisp TIMESROMAN8BI.STRIKE}); otherwise, {fn FONTCREATE} returns {lisp NIL}.

For Press and Interpress fonts, {fn FONTCREATE} accesses the widths information for the font from a font-dictionary file whose name is in the list {var FONTWIDTHSFILES}{index FONTWIDTHSFILES Var} (usually initialized in the site-greeting file to contain at least {lisp {bracket DSK}FONTS.WIDTHS)}.
That dictionary must contain information for the face as specified; there is no acceptable faking algorithm for hard-copy fonts.  The width and height information for press fonts is expressed in micas (= 10 microns = 1/2540 inch), not in screen-point units.

Failing that, {fn FONTCREATE} searches the directories in the list {var NSFONTWIDTHSDIRECTORIES}{index NSFONTWIDTHSDIRECTORIES Var} for a file named something like {lisp MODERN10-C0.WD} for the font {lisp (MODERN 10 (MEDIUM REGULAR REGULAR))}.
Width and height information for Interpress fonts is expressed in micas (= 10 microns = 1/2540 inch), not in screen-point units.


{note seems like FONTWIDTHSFILES should be named FONTSWIDTHSFILES}
{note FONTWIDTHSFILES is also mentioned in hardcopy output section}


The {arg FAMILY} argument to {fn FONTCREATE} may also be a list, in which case it is interpreted as a {arg FAMILY}-{arg SIZE}-{arg FACE}-{arg ROTATION} quadruple.  Thus, {lisp (FONTCREATE '(GACHA 10 BOLD))} is equivalent to {lisp (FONTCREATE 'GACHA 10 'BOLD)}.  {arg FAMILY} may also be a font descriptor, in which case that descriptor is simply returned.
}}

{FnDef {Name FONTSAVAILABLE} {Args FAMILY SIZE FACE ROTATION DEVICE CHECKFILESTOO?}
{Text
Returns a list of fonts that match the given specification.  {arg FAMILY}, {arg SIZE}, {arg FACE} and {arg DEVICE} are the same as for {fn FONTCREATE}.  Additionally, any of them can be {lisp *} in which case, all values of that field are matched.  If {arg CHECKFILESTOO?} is {lisp NIL}, only fonts already loaded into virtual memory will be considered.  If {arg CHECKFILESTOO?} is non-{lisp NIL}, the font directories for the specified device will be searched. When checking font files, the {arg ROTATION} is ignored.  Note: In systems with several font directories, wildcard searches may take a while.  Note: The search is conditional on the status of the server which holds the font.  Thus a file server crash may prevent {fn FONTCREATE} from finding a file that an earlier {fn FONTSAVAILABLE} returned. 

Each element of the list returned will be of the form (Family Size Face Rotation Device).

CAVEAT for PRESS device:  For PRESS devices, there is no way of obtaining exactly what fonts are on a given printer.  {fn FONTSAVAILABLE} uses the fonts widths files to obtain its information.  For many common fonts such as GACHA, TIMESROMAN and HELVETICA, this information does not include font sizes.  In these cases, if the {arg SIZE} is a number, it will be assumed to exist.  If the {arg SIZE} is '{lisp *}, the size field in the returned list will be 0.  

Examples:

{lisp
(FONTSAVAILABLE 'MODERN 10 NIL NIL 'DISPLAY)

will return {lisp (MODERN 10 (MEDIUM REGULAR REGULAR) 0 DISPLAY)} if Modern10 for the display is in virtual memory; {lisp NIL} otherwise.

{lisp
(FONTSAVAILABLE '* 14 NIL NIL 'INTERPRESS)

will return a list of all the size 14 interpress fonts. 
 
}}




{FnDef {Name FONTP} {Args X}
{Text
Returns {arg X} if {arg X} is a font descriptor; {lisp NIL}
otherwise.
}}

The following functions take a font as one argument.  This argument must either be a particular font descriptor or coerceable to a font descriptor.  A display stream is coerced to its current font, a window is coerced to the current font of its display stream, and anything else is coerced by applying {fn FONTCREATE} to it.{note what if x=NIL?  --lmm}

{FnDef {Name FONTPROP} {Args FONT PROP}
{Text
Returns the value of the {arg PROP} property of font {arg FONT}.  {arg PROP} may be one of {lisp FAMILY}, {lisp SIZE}, {lisp FACE}, {lisp WEIGHT}, {lisp SLOPE}, {lisp EXPANSION}, {lisp DEVICE}, {lisp ASCENT}, {lisp DESCENT}, {lisp HEIGHT}, or {lisp ROTATION}.
}}


{FnDef {Name FONTCOPY}
{Args OLDFONT PROP{sub 1} VAL{sub 1} PROP{sub 2} VAL{sub 2} {ellipsis}}
{Type nospread}
{Text
Returns a font descriptor that is a copy of the font {arg OLDFONT}, but which differs from {arg OLDFONT} in that {arg OLDFONT}'s properties are replaced by the specified properties and values.  Thus, {lisp (FONTCOPY {arg FONT} 'WEIGHT 'BOLD 'DEVICE 'PRESS)} will return a bold press font with all other properties the same as those of {arg FONT}.  {fn FONTCOPY} accepts all the properties that {fn FONTPROP} interrogates except for {lisp ASCENT}, {lisp DESCENT}, and {lisp HEIGHT}.  If the first property is a list, it is taken to be the {arg PROP{sub 1}} {arg VAL{sub 1}} {arg PROP{sub 2}} {arg VAL{sub 2}} {ellipsis} sequence.  Thus, {lisp (FONTCOPY {arg FONT} '(WEIGHT BOLD DEVICE PRESS))} is equivalent to the example above.
}}



{FnDef {Name CHARWIDTH} {Args CHARCODE FONT}
{Text
{arg CHARCODE} is an integer that represents a valid character (as returned by {fn CHCON1}).  Returns the amount by which a stream's X-position will be incremented when the character is printed.

{note Example?}
}}


{FnDef {Name CHARWIDTHY} {Args CHARCODE FONT}
{Text
Like {fn CHARWIDTH}, but returns the Y component of the
character's width, the amount by which a stream's Y-position will
be incremented when the character is printed.  This will be zero
for most characters in normal portrait fonts, but may be non-zero for
landscape fonts or for vector-drawing fonts.{note do we have any?}

{note currently, the printing operations do not look at the char Y-width, for performance reasons.  Doc??}
}}


{FnDef {Name STRINGWIDTH} {Args STR FONT PRIN2FLG RDTBL}
{Text
Returns the amount by which a stream's X-position will be incremented if the printname for the Interlisp-D object {arg STR} is printed in font {arg FONT}.  If {arg FONT} is a display stream, its font is used.  If {arg PRIN2FLG} is non-{lisp NIL}, the {lisp PRIN2}-pname of {arg STR} with respect to the readtable {arg RDTBL} is used.
}}


{FnDef {Name STRINGREGION} {Args STR WINDOW PRIN2FLG RDTBL}
{Text
Returns the region occupied by {arg STR} if it were printed at the current location in {arg WINDOW}.  This is useful for determining where text is in a window to allow the user to select it.  The arguments {arg PRIN2FLG} and {arg RDTBL} are passed to {fn STRINGWIDTH}.
}}


It is sometimes useful to simulate an unavailable font or to use a
font with characteristics different from the interpretations
provided by the system.  The following function allows the user to
tell the system what font descriptor to use for given
characteristics.


{FnDef {Name SETFONTDESCRIPTOR} {Args FAMILY SIZE FACE ROTATION DEVICE FONT}
{Text
Indicates to the system that {arg FONT} is the font with the
{arg FAMILY} {arg SIZE} {arg FACE} {arg ROTATION} {arg DEVICE}
characteristics.  If {arg FONT} is {lisp NIL}, the font associated
with these characteristics is cleared and will be recreated the
next time it is needed.  As with {fn FONTPROP} and {fn
FONTCOPY}, {arg FONT} is coerced to a font descriptor if it is not
one already.
}}


{FnDef {Name DEFAULTFONT} {Args DEVICE FONT {anonarg}}
{Text
Returns the font that would be used as the default (if {lisp NIL} were specified as a font argument) for device {arg DEVICE}.  If {arg FONT} is a font descriptor, it is set to be the default font for {arg DEVICE}.
}}



The following functions allow the user to access and change the bitmaps for individual characters in a display font.


{FnDef {Name GETCHARBITMAP} {Args CHARCODE FONT}
{Text
Returns a bitmap containing a copy of the image of the
character {arg CHARCODE} in the font {arg FONT}.
}}


{FnDef {Name PUTCHARBITMAP} {Args CHARCODE FONT NEWCHARBITMAP}
{Text
Changes the bitmap image of the character {arg CHARCODE} in
the font {arg FONT} to the bitmap {arg NEWCHARBITMAP}.  Currently,
{arg NEWCHARBITMAP} must be the same width and height as the
current image for {arg CHARCODE} in the font {arg FONT}.
}}

Users can interactively edit characters using the {fn EDITCHAR} function ({PageRef Fn EDITCHAR}).


}{End SubSec Characters and Fonts}


GACHA

GACHA

EDITMARK.STYLEFNGACHA
GACHA

EDITMARK.STYLEFNGACHA
GACHA

EDITMARK.STYLEFN3GACHA
GACHA

EDITMARK.STYLEFNGACHA
	GACHA

EDITMARK.STYLEFNGACHA
GACHA

EDITMARK.STYLEFNGACHA

GACHA

EDITMARK.STYLEFN
GACHA
×GACHA

EDITMARK.STYLEFNiHGACHA
vz¸