### IGraphicText

  IGraphicText is an IMGraphic that displays an IText. The IGraphicText class, which is subclassed from IMGraphic, displays an IText object.

  By default, the text is created with its location at 0, 0. The location is the left baseline of the first line of text. Clients will typically get the looseFitbounds of the text and use this to position the graphic.

  Do not derive your own classes from this class.

### IGraphicText - Member Functions and Data by Group

### Constructors & Destructor

Use the constructors and destructors in this group to create and destroy objects of class IGraphicText.

~IGraphicText

      public:
      virtual ~IGraphicText()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IGraphicText

  Overload 1

      public:
      IGraphicText(const IGraphicText&)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IGraphicText(const IText& text, ELineBreak lb)

  Constructs an IGraphicText that draws its text according to the line-break policy specified by lb (see the explanation of ELineBreak). If lb is kMultipleLines, lines wrap only at line-termination characters. The origin of the graphic intersects the first line's baseline.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3

      public:
      IGraphicText(const IText& text, const IGRect2D& bounds)

  Constructs an IGraphicText whose line-break policy is kMultipleLines and which places its text within the specified bounds rectangle. The rectangle's width is used as the IGraphicText's wrap width, and the rectangle's upper left-hand corner is used to determine the initial location of the text. (The location will not be the upper left-hand corner, since the location is defined to always be the baseline position. The location will be calculated so that the upper left-hand corner is in the right place.)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 4

      public:
      IGraphicText(const IText& text, GCoordinate wrapWidth)

  Constructs an IGraphicText whose line-break policy is kMultipleLines and which has the specified wrap width. The origin of the graphic intersects the first line's baseline.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 5
  used by streaming only

      public:
      IGraphicText()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Assignment Operator

Use the function in this group to replace the current IGraphicText object with the given one.

operator =

      public:
      IGraphicText& operator =(const IGraphicText&)

  This function is the default assignment operator.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Getting and Setting the IGraphicText Object's Values and Attributes

Use these functions to get and set this objects attributes.

lineBreak

      public:
      ELineBreak lineBreak() const

  Returns the current line-break policy.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

location

      public:
      virtual IGPoint2D location() const

  Returns the current location.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setLineBreak

      public:
      void setLineBreak(ELineBreak lb)

  Sets the IGraphicText's line-break policy.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setLocation

      public:
      virtual void setLocation(const IGPoint2D&)

  Translates the graphic so the location is at the provided point.

  In the current implementation, the location x position is the left edge, and the y position is the baseline of the first line.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setText

      public:
      virtual void setText(const IText&)

  Sets the text displayed by the graphic.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setTransform

      public:
      virtual void setTransform(const IGrafMatrix&)

  Sets the transform on the text.

  An identity transform places the location at position 0, 0.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setWrapWidth

      public:
      void setWrapWidth(GCoordinate newWidth)

  Sets the IGraphicText's wrap width. If the line-break policy isn't kMultipleLines, this function has no effect, and we don't guarantee that a value provided to this function when the line-break policy isn't kMultipleLines will be "remembered" and put into effect if the line-break policy is later changesd to kMultipleLines. If the value provded to this function is negative, the wrap width it set to 0.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

text

      public:
      virtual IText text() const

  Returns the text displayed by the graphic.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

textBounds

      public:
      IGRect2D textBounds(const IGrafPort* port = 0) const

  Returns the bounding rectangle of the text in the IGraphicText's local (untransformed) coordinate system. The height of the rectangle is the actual untransformed height of the laid-out text. The width is the wrap width if the line-break policy is kMultipleLines (even if the longest line doesn't fill up the whole wrap width); if the line-break policy is kFirstLineOnly or kAllOnOneLine, the width of the rectangle is the actual untransformed width of the text. The origin (0, 0) is positioned at the intersection of the first line's baseline and the leading edge of the text's first character. This means the rectangle's left-hand coordinate is always 0, and the top coordinate is zero minus the first line's ascent.

  NOTE: This function takes into account any transforms applied to the text, as well as the port the text wil be drawn into because all of these things can affect the metrics on the text. Passing 0 for the port will cause this function to use a default port, but the bounding box might not be the same as the actual bounding box when the text is drawn.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

transform

      public:
      virtual IGrafMatrix transform() const

  Returns the transform on the text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

wrapWidth

      public:
      GCoordinate wrapWidth() const

  Returns the current wrap width. If the line-break policy isn't kMultipleLines, the value this function returns is undefined.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readFromStream

      protected:
      virtual void readFromStream(IDataStream&)

  Reads the object in from the specified stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeToStream

      protected:
      virtual void writeToStream(IDataStream&) const

  Writes the object out to the specified stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IMGraphic Override Functions

This group contains override functions.

draw

      public:
      virtual void draw(IGrafPort&) const

  Renders the text on a grafport.

  The bundle and transform are applied before rendering.

  The only text attribute the bundle currently affects is the text color. Runs of text without an explicit color style will use the pen color to draw the text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

geometricBounds

      public:
      virtual IGRect2D geometricBounds() const

  Returns looseFitBounds(0);

  Since the bounds depend on the host font support and the transforms that will be applied when rendering, this function cannot accurately determine a port-independent bounds, and so returns looseFitBounds(0) as an approximation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

looseFitBounds

      public:
      virtual IGRect2D
        looseFitBounds( const IGrafPort* port = 0 ) const

  Returns the bounds of the text as rendered in the provided port.

  This takes into account transforms and attributes set on the port, as well as font support available through the provided port.

  If no port is provided, the bounds will be computed as though rendering into an untransformed port corresponding to the screen device.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator ==

      public:
      virtual bool operator ==(const IMDrawable&) const

  Equality test.

  This is an IMDrawable override.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

transformBy

      public:
      virtual void transformBy(const IGrafMatrix&)

  Transforms the text.

  The passed-in transform is concatenated with any existing transform on the text. Clients can use transform() to get the resulting transform.

  Because text responds unpredictably to arbitrary transforms, after transforming the graphic clients should query the new bounds if they need this information.

  The entire text is transformed as a unit (no individual character rotations).

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Multiple Graph Port Support

These functions support the use of IGraphicText in multiple IGrafPort.

portHasChanged
  Call this function before drawing or measuring if you're using this IGraphicText in more than one IGrafPort.

      public:
      void portHasChanged()

  Whenever you draw or measure an IGraphicText, it caches its font metric information for performance. If you draw an IGraphicText into more than one IGrafPort (for example, to the screen and to a printer), they may have different font metrics, making the cached metrics invalid. IGraphicText can't tell whether it's being drawn into a different port than it was drawn into last time (checking the address of the IGrafPort object doesn't work, since you get a new one of those every time you draw, even if they're all drawing into the same physical port (e.g., the same window on the screen). Therefore, if you draw the same IGraphicText into more than one port, you have to call portHasChanged() to let it know when you're drawing into a different port and, thus, when it has to recalculate its font metric information.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IGraphicText - Enumerations

ELineBreak

      enum ELineBreak { kFirstLineOnly,
                        kAllOnOneLine,
                        kMultipleLines,
                        kSingleLine=kFirstLineOnly }

  Defines the formatting options for breaking lines.

  The following values are available:

  - kFirstLineOnly - Draws a single line of text, running from the first character of the specified text to the first line separator. Tabs are treated as spaces. Paragraph styles in the text are ignored.
  - kAllOnOneLine - Draws a single line of text, including all of the specified text. Tabs and line separators are both treated as spaces. Paragraph styles in the text are ignored.
  - kMultipleLines - Draws multiple lines, with word-wrap, with line separators and tabs treated peoperly, and with paragraph styles in the text treated properly. If no word-wrap width is specified, lines wrap only at line separators.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IGraphicText - Inherited Member Functions and Data

#### Inherited Public Functions

  IMDrawable

  -     virtual ~IMDrawable()

  -     bool operator !=(const IMDrawable&) const

  IMGraphic

  -     virtual ~IMGraphic()

  -     virtual void
          adoptAttributeState( IAttributeState* adoptedAttributeState )

  -     virtual void adoptBundle(IGrafBundle* adoptedBundle)

  -     virtual const IAttributeState* attributeState() const

  -     virtual const IGrafBundle* bundle() const

  -     virtual void draw(IGrafPort& port) const = 0

  -     virtual IGRect2D geometricBounds() const = 0

  -     IMGraphic()

  -     virtual IGRect2D looseFitBounds(const IGrafPort* = 0) const

  -     virtual IAttributeState* orphanAttributeState()

  -     virtual IGrafBundle* orphanBundle()

  -     virtual void
          rotateBy( GDegrees,
                    const IGPoint2D& centerOfRotation = IGPoint2D::origin ( ) )

  -     virtual void
          scaleBy( const IGPoint2D&,
                   const IGPoint2D& centerOfScale = IGPoint2D::origin ( ) )

  -     virtual void transformBy(const IGrafMatrix&) = 0

  -     virtual void translateBy(const IGPoint2D&)

  IMStreamable

  -     virtual ~IMStreamable()

  -     void externalizeToStream(IDataStream& towhere) const

  -     void internalizeFromStream(IDataStream& fromwhere)

  -     virtual const ITypeRepresentation&
          typeRepresentation() const = 0

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IMDrawable

  -     IMDrawable()

  -     IMDrawable(const IMDrawable&)

  -     IMDrawable& operator =(const IMDrawable& source)

  IMGraphic

  -     IMGraphic(IGrafBundle* adoptedBundle)

  -     IMGraphic(const IMGraphic&)

  -     IMGraphic& operator =(const IMGraphic& source)

  -     virtual void readFromStream(IDataStream& toWhere)

  -     virtual void resetTimeStamp()

  -     void setHit(bool flag)

  -     virtual void setTimeStamp(const unsigned long&)

  -     virtual unsigned long timeStamp() const

  -     virtual void updateTimeStamp()

  -     virtual void writeToStream(IDataStream& toWhere) const

  IMStreamable

  -     IMStreamable(const IMStreamable& other)

  -     IMStreamable()

  -     virtual void readFromStream(IDataStream& fromwhere) = 0

  -     virtual void writeToStream(IDataStream& towhere) const = 0

#### Inherited Protected Data

  - None