"

 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.

"

FontDescription subclass:#Font

	instanceVariableNames:'device fontId replacementFont ascent descent width isFixedWidth

		minWidth maxWidth maxAscent maxDescent'

	poolDictionaries:''

	category:'Graphics-Support'

!

!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.

    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'!

flushDeviceFontsFor:aDevice

    "unassign all fonts from their device if they are assigned

     to aDevice"

    "Modified: 5.7.1996 / 17:56:16 / cg"

!

initialize

    "initialize the font tracking array"

!

update:something with:aParameter from:changedObject

    "sent early during restart - flush any leftover device handles"

    (something == #earlyRestart) ifTrue:[

        "

         this is sent by ObjectMemory when restarting from

         an image. All device specific information (especially device

         handles) are now invalid and have to be flushed

        "

        self flushDeviceFontsFor:nil

    ]

    "Modified: 20.4.1996 / 23:22:23 / cg"

    "Created: 15.6.1996 / 15:21:30 / cg"

! !

!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

    ].

	(aFont family = family) ifTrue:[

	    (aFont face = faceString) ifTrue:[

		(aFont style = styleString) ifTrue:[

		     (aFont size == sizeNum) ifTrue:[

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

			    ^ aFont

			]

		    ]

		]

	    ]

	]

    ].

    ^ newFont

! !

!Font class methodsFor:'cleanup'!

releaseResourcesOnDevice:aDevice

    "this is sent when a display connection is closed,

     to release all cached Fonts from that device"

    "Created: 16.1.1997 / 16:44:46 / 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:'displaying'!

displayOpaqueString:aString from:index1 to:index2 x:x y:y in:aGC

    "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|

    replacementFont isNil ifTrue:[

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

        ^ self

    ].

    prevFont := aGC font.

    aGC basicFont:replacementFont.

    aGC displayOpaqueString:aString from:index1 to:index2 x:x y:y.

    aGC basicFont:prevFont

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

!

displayOpaqueString:aString x:x y:y in:aGC

    "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|

    replacementFont isNil ifTrue:[

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

        ^ self

    ].

    prevFont := aGC font.

    aGC basicFont:replacementFont.

    aGC displayOpaqueString:aString x:x y:y.

    aGC basicFont:prevFont.

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

!

displayString:aString from:index1 to:index2 x:x y:y in:aGC

    "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|

    replacementFont isNil ifTrue:[

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

        ^ self

    ].

    prevFont := aGC font.

    aGC basicFont:replacementFont.

    aGC displayString:aString from:index1 to:index2 x:x y:y.

    aGC basicFont:prevFont.

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

!

displayString:aString x:x y:y in:aGC

    "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|

    replacementFont isNil ifTrue:[

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

        ^ self

    ].

    prevFont := aGC font.

    aGC basicFont:replacementFont.

    aGC displayString:aString x:x y:y.

    aGC basicFont:prevFont.

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

! !

!Font methodsFor:'getting a device font'!

on: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].

    "first look if not already there"

                        ]

                    ]

                ]

            ]

        ]

    ].

    newFont := self on:aDevice ifAbsent:nil.

    newFont isNil ifTrue:[

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

        rep := self replacementFontOn:aDevice.

        device isNil ifTrue:[

            device := aDevice.

            replacementFont := rep.

            ^ self

        ].

        newFont := (self class basicNew)

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

        newFont setReplacementFont:rep.

        ^ newFont

    ].

    ^ newFont

    "

     Font family:'foo' size:17

    "

    "Modified: 5.7.1996 / 17:56:13 / cg"

!

on: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.

	^ 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.