Application to examine and edit text styles

Products : VW5i.0
Platforms: ALL
Keywords : printing, font, FontDescription, FontPolicy, TextAttributes

Released:      Aug  4, 1998
Last Revised:  Sep 28, 1998

 Choosing a particular font or text style in a VisualWorks application
 can often be frustrating for the following reasons:

          1.  Since VisualWorks applications are intended to be cross platforn,
 an application may inevitably be installed on a platform that is missing
 one or more fonts for the platform it was developed for and uses. A choice
 trade-off exists between what stylized fonts the developer will choose
 to specify and what generic fonts are available to be substituted for them
 on all target platforms if these fonts are missing.

          2.  The path from creating the text and font specifications to
 seeing the outcome in the application involves some time consuming design
 steps.  A few iterations may be necessary in the specifications before
 the desired font and style is obtained.

          3.  Interpreting why text doesn't appear in a desired font or
 style requires the designer to probe through several inspectors on the text.

 Have you ever wished you could interactively choose and set font description
 and text attributes and see the result?  The application attached allows
 a developer to modify and view the result of FontDescription, TextAttributes,
 and FontPolicy specifications upon a ComposedText instance on the screen
 or printer.  For debugging, this application can be used to examine why
 a ComposedText instance appears the way it does based on its specifications
 and available platform fonts.
 

 Background

  A ComposedText instance embodies an instance of Text, a text style as
 an instance of either TextAttributes or VariableSizeTextAttributes, a FontPolicy,
 and other attributes that determine how its text is broken into lines or
 its composed height or width.  Aside from these remaining attributes the
 importance of each of these objects in text display will be discussed below.
 More information on each of these objects may be determined from their
 class comments.

 Text -- the Text instance possesses the string to be displayed plus an
 equally sized run array of any character style emphasis codes to be applied
 on a character by character basis in the text.  The position of a character
 code in the array matches the position in the string to which it is applied.
 Typical character style codes which require no parameter include #bold,
 #italic, #underline, #strikeout, #sansSerif,  #serif, #small, #normal,
 and #large.  Codes #family and #color take a single parameter and appear
 as an association, such as #color->ColorValue red or #family->'arial'.
 None, one, or more character codes may be defined for each character in
 the string.  The duty of interpreting these character codes belongs to
 a CharacterAttributes or VariableCharacterAttributes instance which uses
 a block defined for each emphasis code to appropriately refine a default
 FontDescription.  An example Text instance that emphasizes its entire string
 in italic and bold is created below

         'All this bold and in italic' asText emphasizeAllWith:#(#bold #italic).

 FontDescription -- a FontDescription is a specification for a font based
 on typeface family, encoding, name, size, etc.  A specification in a FontDescription
 may be left at or set to nil so that specification is ignored in the search
 for an appropriate font.  A CharacterAttributes or VariableCharacterAttributes
 uses a default query FontDescription instance to which it may further refine
 according to the character codes in a Text instance.  The FontDescription
 is ultimately used with a FontPolicy to search for the best platform font
 that matches its specification.  A FontDescription may be so loosely specified
 that a FontPolicy may choose any font or so tightly specified that it may
 find no font that satisfies its criteria.

 CharacterAttributes or VariableCharacterAttributes -- a CharacterAttributes
 instance is used to map character styles to fonts.  It holds one instance
 of FontDescription as a "default query" and a dictionary of styles that
 modify an interim FontDescription using a block defined for each character
 style.    A CharacterAttributes instance starts with the default query
 FontDescription, passes it to the first style block that applies, then
 takes the result of that block and applies it as the FontDescription for
 the next style block that applies, and so on for a FontDescription that
 combines all styles needed.   An instance of VariableCharacterAttributes
 is a subclass of CharacterAttributes that adds the behavior to change font
 size and encoding according the current Locale preferences.   It has a
 scale attribute that defines the ratio of  font size of  the  FontDescription
 it produces to the preferred font size of the current Locale.  An instance
 of VariableSizeTextAttributes uses an instance of VariableCharacterAttributes.

 TextAttributes or VariableSizeTextAttributes -- an instance of TextAttributes
 contains attributes describing text alignment and spacing with an instance
 of  CharacterAttributes that determines character font and styling.  A
 VariableSizeTextAttributes instance performs a parallel function but is
 paired with a VariableCharacterAttributes instance to scale text size independent
 of screen resolution.  A VariableSizeTextAttributes is a subclass of TextAttributes.

 FontPolicy -- an instance of FontPolicy is defined for each GraphicsDevice
 (i.e. screen or printer) that displays a font.  Based on a FontDescription
 it searches a list of platform fonts (i.e. ImplementationFont) available
 for the GraphicsDevice and ranks those fonts for the best match to the
 FontDescription.  It defines a number of weights for each attribute of
 a FontDescription.  The font that matches an attribute with the highest
 weight will take precedence over font attributes with a lesser weight.

 ComposedText -- a ComposedText instance possesses a Text instance, a TextAttributes
 (or VariableSizeTextAttributes), and an instance of  FontPolicy, or, if
 nil, will use a default FontPolicy instance.    A CharacterAttributes (or
 VariableCharacterAttributes) usually obtained from a TextAttributes (or
 VariableSizeTextAttributes) instance, its default FontDescription, and
 a FontPolicy are the minimum components needed to specify and obtain a
 font.  A ComposedText instance contains all these objects needed to specify
 how it may display itself.
 

 Font selection depends on the GraphicsDevice where it is used

  A different selection of fonts are often used for printing and screen
 display.  Unless the printer choice in VisualWorks is the Windows host
 printer, fonts for printing will usually originate from the set of default
 fonts internal to the printer.  On the other hand, Windows will usually
 display from its set of TrueType fonts installed on the platform hard disk.
 Since one can't expect the set of fonts available for the screen is the
 same as that printed it is important to examine text samples on the medium
 they are intended.  To be rendered on a printer, a ComposedText instance
 needs to be passed the message #newGraphicsDevice: with the printer instance
 as argument as in:

          | ps |
      printer := (Printer startPrintJobNamed:'temp') graphicsDevice.
      aComposedText graphicsDevice: printer.

 The TextOptionsEditor application may edit ComposedText instances for either
 media.  A ComposedText instance intended for printing should however be
 printed since its text shown in the editor viewer will likely be in only
 closest substitute to the font used by the printer.
 

  Opening the TextOptionsEditor

 To open the TextOptionsEditor on a default ComposedText instance file-in
 the attached code and evaluate the following:

          TextOptionsEditor open

 To open and view a particular ComposedText instance named aComposedText
 intended for screen viewing use the following:

          TextOptionsEditor new
          composedTextHolder: aComposedText asValue;
          open.

  If you wish to open on aComposedText instance and open an accessory window
 that prints a sample and reports its settings (e.g. for aComposedText instance
 whose graphics device is the printer) use

          TextOptionsEditor new
          composedTextHolder: aComposedText asValue;
          open;
          openPrintAccessory.

 Look to the TextOptionsEditor class side methods in category 'examples'
 for samples opening the editor under various conditions.

 When the editor is assigned a ComposedText instance to edit through the
 method #composedTextHolder: it creates and installs copies of the ComposedText
 instance's text style, FontPolicy, and FontDescription into the ComposedText
 instance.  This is a precaution to prevent the editor from altering any
 of the objects used in rendering system text.
 

 Description of classes

 The TextOptionsEditor uses three auxilary application classes to view and
 edit ComposedText properties.  This includes the FontDescriptionInterface
 class to edit a FontDescription, the TextAttributesInterface to edit either
 a TextAttributes or VariableSizeTextAttributes instance, and the FontPolicyInterface
 class to edit a FontPolicy.  The TextOptionsInterface is an abstract superclass
 of these three interface classes that provides common accessors and default
 behavior between them.  Either the FontDescriptionInterface, TextAttributesInterface,
 or FontPolicyInterface may be used by themselves to edit or display a FontDescription,
 TextAttributes, or FontPolicy respectfully or may be reused in other applications.
 Be aware that these applications can modify attributes in current use by
 VisualWorks to display text in its browsers, inspectors, or  widgets unless
 you open the editor applications on a copy of the instance.

Copyright © 1999 Cincom Systems, Inc.  All Rights Reserved.  Unauthorized use, copying or redistribution is prohibited. Code and other information are provided as-is, without warranty of any kind and Cincom Systems, Inc. disclaims all implied warranties of merchantability or fitness for a particular purpose. Code may only be used with Cincom Systems, Inc. products.