"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libview' }"

FontDescription subclass:#Font

	instanceVariableNames:'device fontId replacementFont ascent descent width isFixedWidth

		minWidth maxWidth maxAscent maxDescent'

	classVariableNames:'Replacements'

	poolDictionaries:''

	category:'Graphics-Support'

!

Object subclass:#DeviceFontHandle

	instanceVariableNames:'device fontId'

	classVariableNames:''

	poolDictionaries:''

	privateIn:Font

!

!Font class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    Font represents fonts in a device independent manner; after being

    created using 'Font family:family face:face style:style size:size',

    the returned font is not associated to a specific device.

    (therefore, those fonts can be used to draw on any GC)

    To get a device font, any font can be sent the message

    'aFont on:aDevice' which returns an instance of Font which is

    associated to a device (it returns the receiver, if that is already

    associated to that device).

    For proper operation, each graphics operation working with fonts

    must get a device font before doing the draw.

    Most draw methods in DeviceDrawable do that automatically for you, 

    before doing the draw; so you do not have to care.

    However, some operations require explicit conversion to a device font

    before being allowed. For example, a query for a fonts height (in device

    units) can only be done if the font being asked is associated to

    a device (which should be clear, since a 'courier-roman-12' font may

    have a different number of pixels on a 75dpi vs. a 120dpi display. And

    a totally different number of device units on a 600dpi laser printer.

    Thus, to query a font for its height (or ascent, or descent, or width),

    use something like:

        myFont := Font family:'courier' ... size:12.

            ...

        'want to know its height on the Display'

        h := (myFont on:Display) height.

        'want to know its height on a printer'

        h := (myFont on:aPrinter) height.

    there are alternative shortcuts for these operations:

        h := myFont heightOn:Display.

        h := myFont heightOn:Printer.

        or:

        a := myFont ascentOn:Display.

    Keep in mind, that each device is free to think in whatever units it

    likes - a display may return units of pixels, a postscript printer may

    think in (fractions of) inches, a dot matrix printer may think in dots.

    Also, notice that currently only graphic displays are really supported;

    printer devices are being developped and may or may not be in the current

    system.

    If a font cannot be represented on a device, a replacement

    font is chosen and kept in the replacementFont instance variable. 

    This is done to preserve the original font information, in case the image

    is restarted later on another display which has that font available.

    [Instance variables:]

      family          <String>        the fonts family ('courier', 'helvetica' etc)

      face            <String>        the fonts face ('bold', 'medium' etc)

      style           <String>        the fonts style ('roman', 'italic', 'oblique')

      size            <String>        the fonts size (not in pixels) 

      encoding        <Symbol>        the fonts encoding (usually #iso8859)

      device          <Object>        the device the font is associated to, or nil

      fontId          <Object>        the id of the font on that device, or nil

      replacement     <Font>          the replacement font or nil

      ascent          <Integer>       the fonts ascent in device units on device

      descent         <Integer>       the fonts descent in device units on device

      width           <Integer>       the character width in device units on device

                                      (for variable fonts, its the width of a space)

      isFixedWidth    <Boolean>       true if font is a fixed width font

      minWidth        <Integer>       width of the smallest-width character in

                                      in device units on device

      maxWidth        <Integer>       width of the largest-width character in

                                      in device units on device

    [class variables:]

      Replacements    <Dictionary>    replacement fonts

    [see also:]

        DeviceWorkstation 

        DeviceDrawable GraphicsContext

        Cursor Color

        ( introduction to view programming :html: programming/viewintro.html#FONTS )

    [author:]

        Claus Gittinger

"

!

examples

"

    standard fonts:

        aFont := Font family:'courier' size:12

        aFont := Font 

                     family:'helvetica' 

                     face:'roman' 

                     style:'bold' 

                     size:16

    special (non-portable displayType specific) fonts:

        aFont := Font name:'6x10'

        aFont := Font name:'k14'

    setting the font of a button:

                                                                        [exBegin]

        |b|

        b := Button new.

        b label:'hello'.

        b font:(Font family:'helvetica' 

                     face:'medium' 

                     style:'roman' 

                     size:16).

        b open

                                                                        [exEnd]

    asking a font about a strings size in pixels, 

    if it was used on some device:

        aFont widthOf:'hello' on:Display

    asking about the ascent, if used on some device:

        aFont ascentOn:Display

    if the font has been associated to a device, the following are 

    a bit faster:

        |aFont|

        ...

        aFont := aFont on:aDevice.

        ...

        aFont widthOf:'hello'

        ...

        aFont ascent

        ...

"

! !

!Font class methodsFor:'initialization'!

initialize

    "initialize the font tracking array"

    "

     replacement handling is not yet finished

    "

    Replacements isNil ifTrue:[

        Replacements := Dictionary new.

        Replacements at:'clean'                  put:'courier'.

        Replacements at:'fixed'                  put:'courier'.

        Replacements at:'new century schoolbook' put:'times'.

        Replacements at:'lucida'                 put:'helvetica'.

        Replacements at:'lucidabright'           put:'helvetica'.

        Replacements at:'lucidatypewriter'       put:'courier'.

        Replacements at:'charter'                put:'times'.

        Replacements at:'terminal'               put:'courier'.

    ]

! !

!Font class methodsFor:'instance creation'!

family:familyString face:faceString style:styleString size:sizeNum encoding:encodingSym

    "returns a font for given family, face, style, size and encoding. 

     The returned font is not associated to a specific device"

    |family newFont|

    (familyString at:1) isUppercase ifTrue:[

        family := familyString asLowercase

    ] ifFalse:[

        family := familyString

    ].

    "look if this font is already known on the default device

     (the most common case)"

    Display notNil ifTrue:[

        Display deviceFonts do:[:aFont |

            (aFont family = family) ifTrue:[

                (aFont face = faceString) ifTrue:[

                    (aFont style = styleString

                    or:[styleString = 'italic' and:[aFont style = 'oblique']]) ifTrue:[

                         (aFont size == sizeNum) ifTrue:[

                            (encodingSym isNil or:[aFont encoding == encodingSym]) ifTrue:[

                                ^ aFont

                            ]

                        ]

                    ]

                ]

            ]

        ]

    ].

    newFont := self basicNew 

                    setFamily:familyString

                    face:faceString

                    style:styleString

                    size:sizeNum

                    encoding:encodingSym

                    device:nil.

    ^ newFont

    "Modified: / 26.9.1999 / 13:49:45 / cg"

! !

!Font methodsFor:'accessing'!

device

    "return the device I am on"

    ^ device

!

fontId

    "return the device-dependent font-id"

    ^ fontId

!

graphicsDevice

    "same as #device, for ST-80 compatibility naming.

     Return the device I am associated with."

    ^ device

    "Created: 28.5.1996 / 18:39:53 / cg"

! !

!Font methodsFor:'binary storage'!

readBinaryContentsFrom: stream manager: manager

    "tell the newly restored Font about restoration"

    super readBinaryContentsFrom: stream manager: manager.

    self restored

! !

!Font methodsFor:'copying'!

deepCopyUsing:aDictionary

    ^ self

! !

!Font methodsFor:'displaying'!

    "this is only called for fonts which have a nil fontId,

     and therefore use the replacementFont. Should never be called

     for non-replacement fonts."

    |prevFont|

    prevFont := aGC font.

    replacementFont isNil ifTrue:[

        fontId notNil ifTrue:[

            aGC basicFont:self.

        ] ifFalse:[

            'Font: [warning]: no replacementFont. should not happen' errorPrintCR.

        ].

    ] ifFalse:[

        aGC basicFont:replacementFont.

    ].

    aGC basicFont:prevFont.

    "Modified: 10.1.1997 / 17:51:17 / cg"

! !

!Font methodsFor:'getting a device font'!

onDevice:aDevice

    "create a new Font representing the same font as

     myself on aDevice; if one already exists, return the one."

    |newFont rep|

    "if I am already assigned to that device ..."

    (device == aDevice) ifTrue:[^ self].

    aDevice isNil ifTrue:[^ self].

    "first look if not already there"

    aDevice deviceFonts do:[:aFont |

        (size == aFont size) ifTrue:[

            (family = aFont family) ifTrue:[

                (face = aFont face) ifTrue:[

                    (style = aFont style) ifTrue:[

                        (encoding isNil or:[encoding == aFont encoding]) ifTrue:[

                            ^ aFont

                        ]

                    ]

                ]

            ]

        ]

    ].

    newFont := self onDevice:aDevice ifAbsent:nil.

    newFont isNil ifTrue:[

        "oops did not work - (device has no such font)"

        aDevice isOpen ifFalse:[

            "/ the display device is not connected

            "/ (or has a broken connection).

            self error:'trying to get font from closed display:', aDevice printString.

            ^ self.

        ].

        rep := self replacementFontOnDevice:aDevice.

        device isNil ifTrue:[

            device := aDevice.

            replacementFont := rep.

            aDevice registerFont:self.

            ^ self

        ].

        newFont := (self class basicNew)

                     setFamily:family face:face style:style size:size encoding:encoding device:aDevice.

        newFont setReplacementFont:rep.

        aDevice registerFont:newFont.

        ^ newFont

    ].

    ^ newFont

    "

     Font family:'foo' size:17

    "

    "Modified: 14.4.1997 / 18:22:31 / cg"

!

onDevice:aDevice ifAbsent:exceptionBlock 

    "create a new Font representing the same font as

     myself on aDevice. This does NOT try to look for existing

     or replacement fonts (i.e. can be used to get physical fonts)."

    |newFont id|

    "ask that device for the font"

    id := aDevice getFontWithFamily:family face:face style:style size:size encoding:encoding.

    id isNil ifTrue:[

        "oops did not work - (device has no such font)"

        ^ exceptionBlock value

    ].

    "receiver was not associated - do it now"

    device isNil ifTrue:[

        device := aDevice.

        fontId := id.

        self getFontInfos.

        aDevice registerFont:self.

        ^ self

    ].

    "receiver was already associated to another device - need a new font"

    newFont := (self class basicNew) 

                        setFamily:family 

                        face:face

                        style:style

                        size:size

                        encoding:encoding

                        device:aDevice.

    newFont setFontId:id.

    newFont getFontInfos.

    aDevice registerFont:newFont.

    ^ newFont

!

replacementFontOnDevice:aDevice

    "return a replacement font for the receiver - this is needed, if

     an image is restored on another type of display, or one which has

     a different set of fonts."

    |id f alternative|

    alternative := Replacements at:family ifAbsent:nil.

    alternative notNil ifTrue:[

        id := aDevice getFontWithFamily:alternative

                                   face:face

                                  style:style 

                                   size:size

                               encoding:encoding.

    ].

    id notNil ifTrue:[

        ('Font [info]: use alternative for ' , (self userFriendlyName)) infoPrintCR.

    ] ifFalse:[

        id := aDevice getDefaultFont.

        ('Font [info]: use default for ' , (self userFriendlyName)) infoPrintCR.

    ].

    id isNil ifTrue:[

        "oops did not work - this is a serious an error"

        self error:'cannot get default font'.

        ^ nil

    ].

    f := self class basicNew.

    f setDevice:aDevice fontId:id.

    f getFontInfos.

    aDevice registerFont:f.

    ^ f

    "Modified: 10.1.1997 / 15:40:21 / cg"

! !

!Font methodsFor:'instance release'!

executor

    "redefined to return a lightweight copy 

     - all we need is the device handle"

    ^ DeviceFontHandle basicNew setDevice:device fontId:fontId.

    "Modified: / 20.4.1996 / 23:23:04 / cg"

    "Modified: / 3.2.1999 / 16:13:10 / stefan"

! !

!Font methodsFor:'printing & storing'!

printOn:aStream

    "append a user printed representation of the receiver to aStream.

     The format is suitable for a human - not meant to be read back.

     Redefined to print more about the fonts name"