Class DrawString

  • All Implemented Interfaces:
    Computable, java.io.Serializable

    public class DrawString
    extends Drawable
    implements Computable
    A DrawString object displays a string, possibly multi-line, in a DisplayCanvas, inside the rectangular region of a CoordinateRect. The location of the string can be specified in two ways. First, by giving the coordinates of a reference point together with a constant that says how the string is positioned with respect to that reference point. The coordintes are given as Value objects and the values are interepreted in the coordinate system of the CoordinateRect. The positioning object is one of the constants TOP_LEFT, TOP_CENTER, ..., BOTTOM_RIGHT defined in this class. This says where the REFERENCE POINT is -- at the top left of the string, at the top center, etc.

    The second way to specify the position of the string is to set the reference point coordinates to null. In that case, the postioning constant gives the location of the STRING in the CorrdinateRect. A value of TOP_LEFT says that the string is in the top left corner of the rect, etc.

    An array of Value objects can be specified to be displayed in the string. Their values are substituted for #'s in the string. (A double # in the string, however, is displayed as a literal single #.)

    It is possible to set the color, font and justification of the string.

    A DisplayString implements the Computable interface, so it can be added to a Controller. The values of the Value objects used by the string are recomputed only when its compute() method is called.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.awt.Color backgroundColor
      If backgroundColor is non-null, then a rectangle of this color is filled as a background for the string;
      protected java.lang.String baseString
      String, possibly with \n and #'s.
      static int BOTTOM_CENTER
      Specify string location in rect
      static int BOTTOM_LEFT
      Specify string location in rect
      static int BOTTOM_RIGHT
      Specify string location in rect
      static int CENTER
      For specifying justification of lines in multiline strings.
      static int CENTER_CENTER
      Specify string location in rect
      static int CENTER_LEFT
      Specify string location in rect
      static int CENTER_RIGHT
      Specify string location in rect
      protected boolean clamp
      If true, the string is clamped to lie within the CoordinateRect.
      protected java.awt.Color color
      Color of string.
      protected java.awt.Font font
      Font for drawing string.
      protected java.awt.Color frameColor
      If frameWidth is greate than zero, then a frame is drawn around the string in this color.
      protected int frameWidth
      If frameWidth is greater than zero, then a frame of this width is drawn around the string in the color given by frameColor.
      protected int justification
      Left, right, or center justification of lines in the text.
      static int LEFT
      For specifying justification of lines in multiline strings.
      protected int numSize
      Maximum number of characters desired in numbers; actual number might actually be larger.
      protected int offset
      If absolute positioning is used, then this gives a gap between the string and edge of rect.
      protected int position
      one of the constants defined in this class for specifying position
      static int RIGHT
      For specifying justification of lines in multiline strings.
      protected java.lang.String[] strings
      The actual lines to draw, derived from baseString.
      static int TOP_CENTER
      Specify string location in rect
      static int TOP_LEFT
      Specify string location in rect
      static int TOP_RIGHT
      Specify string location in rect
      protected Value[] values
      Values to be substituted for #'s in the baseString.
      protected Value xPos
      xy-coords for drawing the string.
      protected Value yPos
      xy-coords for drawing the string.
    • Constructor Summary

      Constructors 
      Constructor Description
      DrawString()
      Create a DrawString object that initially has no string to draw.
      DrawString​(java.lang.String str)
      Create a DrawString for drawing a black string in the top left corner of the coordinate rect.
      DrawString​(java.lang.String str, int pos)
      Create a DrawString for drawing a black string in the position specified.
      DrawString​(java.lang.String str, int pos, Value[] values)
      Create a DrawString for drawing a black string in the specified position.
      DrawString​(java.lang.String str, int pos, Value xPos, Value yPos, Value[] values)
      Create a string that is displayed at the reference point (xPos,yPos); The positioning constant, pos, gives the positioning relative to this point, if xPos or yPos is non-null.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void compute()
      The compute method sets up the array of strings that is actually displayed.
      void draw​(java.awt.Graphics g, boolean coordsChanged)
      Draws the string.
      java.awt.Color getBackgroundColor()
      Get the color that is used to fill a rectangle on which the string is drawn.
      boolean getClamp()
      Returns true if the string is set to be clamped to lie within the CoordinateRect.
      java.awt.Color getColor()
      Get the non-null color that is used for drawing the string.
      java.awt.Font getFont()
      Return the font that is used for drawing the string.
      java.awt.Color getFrameColor()
      Get the color that is used to draw a frame around the string.
      int getFrameWidth()
      Get the width, in pixels, of the frame that is drawn around the string.
      int getJustification()
      Get the justification that is used for a multiple-line string.
      int getNumSize()
      Return the desired maximum number of characters in displayed numbers.
      int getOffset()
      Get the distance of the bounding box of the string from the reference point where it is drawn.
      int getPositioning()
      Return the positioning, as set by setPositioning().
      java.lang.String getString()
      Get a copy of the display string (with \n's #'s, not with substitued values.)
      Value[] getValues()
      Return the array of values that are substituted for #'s in the string.
      Value getXPos()
      Return the Value object that gives the x-coordinate of the reference point of this string.
      Value getYPos()
      Return the Value object that gives the y-coordinate of the reference point of this string.point of this string.
      void setBackgroundColor​(java.awt.Color color)
      Set the color that is used to fill a rectangle on which the string is drawn.
      void setClamp​(boolean clamp)
      Set the "clamp" property of the DrawString.
      void setColor​(java.awt.Color c)
      Set the color for the string.
      void setFont​(java.awt.Font f)
      Set the font that is used for drawing this string.
      void setFrameColor​(java.awt.Color color)
      Set the color that is used to draw a frame around the string.
      void setFrameWidth​(int width)
      Set the width, in pixels, of a frame to draw around the string.
      void setJustification​(int j)
      Set the justification to be used if there are multiple lins in the string.
      void setNumSize​(int size)
      Set the desired maximum number of characters in displayed numbers.
      void setOffset​(int b)
      Set the distance of the bounding box of the string from the reference point where it is drawn.
      void setPositioning​(int pos)
      Set the positioning of the string.
      void setReferencePoint​(Value x, Value y)
      Set the values of the (x,y) coordinates of the reference point for the stirng.
      void setString​(java.lang.String str)
      Set the string that is displayed.
      void setValues​(Value[] v)
      Set the Values that are substituted for (single) #'s in the string.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • TOP_LEFT

        public static final int TOP_LEFT
        Specify string location in rect
        See Also:
        Constant Field Values
      • TOP_CENTER

        public static final int TOP_CENTER
        Specify string location in rect
        See Also:
        Constant Field Values
      • TOP_RIGHT

        public static final int TOP_RIGHT
        Specify string location in rect
        See Also:
        Constant Field Values
      • CENTER_LEFT

        public static final int CENTER_LEFT
        Specify string location in rect
        See Also:
        Constant Field Values
      • CENTER_CENTER

        public static final int CENTER_CENTER
        Specify string location in rect
        See Also:
        Constant Field Values
      • CENTER_RIGHT

        public static final int CENTER_RIGHT
        Specify string location in rect
        See Also:
        Constant Field Values
      • BOTTOM_LEFT

        public static final int BOTTOM_LEFT
        Specify string location in rect
        See Also:
        Constant Field Values
      • BOTTOM_CENTER

        public static final int BOTTOM_CENTER
        Specify string location in rect
        See Also:
        Constant Field Values
      • BOTTOM_RIGHT

        public static final int BOTTOM_RIGHT
        Specify string location in rect
        See Also:
        Constant Field Values
      • CENTER

        public static final int CENTER
        For specifying justification of lines in multiline strings. (But can also be used as a synonym for CENTER_CENTER to specify the position of the string).
        See Also:
        Constant Field Values
      • LEFT

        public static final int LEFT
        For specifying justification of lines in multiline strings. (But can also be used as a synonym for TOP_LEFT to specify the position of the string).
        See Also:
        Constant Field Values
      • RIGHT

        public static final int RIGHT
        For specifying justification of lines in multiline strings. (But can also be used as a synonym for TOP_RIGHT to specify the position of the string).
        See Also:
        Constant Field Values
      • position

        protected int position
        one of the constants defined in this class for specifying position
      • baseString

        protected java.lang.String baseString
        String, possibly with \n and #'s. This is used as a base to get the actual string that is drawn.
      • strings

        protected java.lang.String[] strings
        The actual lines to draw, derived from baseString.
      • values

        protected Value[] values
        Values to be substituted for #'s in the baseString.
      • xPos

        protected Value xPos
        xy-coords for drawing the string. If non-null then relative positioning is used. If null, then positioning is absolute.
      • yPos

        protected Value yPos
        xy-coords for drawing the string. If non-null then relative positioning is used. If null, then positioning is absolute.
      • color

        protected java.awt.Color color
        Color of string. If null, black is used as the default.
      • font

        protected java.awt.Font font
        Font for drawing string. If null, get font from graphics context.
      • offset

        protected int offset
        If absolute positioning is used, then this gives a gap between the string and edge of rect. For relative positioning, this gives an offset from the value of xPos yPos.
      • clamp

        protected boolean clamp
        If true, the string is clamped to lie within the CoordinateRect.
      • justification

        protected int justification
        Left, right, or center justification of lines in the text.
      • numSize

        protected int numSize
        Maximum number of characters desired in numbers; actual number might actually be larger.
      • backgroundColor

        protected java.awt.Color backgroundColor
        If backgroundColor is non-null, then a rectangle of this color is filled as a background for the string;
      • frameWidth

        protected int frameWidth
        If frameWidth is greater than zero, then a frame of this width is drawn around the string in the color given by frameColor.
      • frameColor

        protected java.awt.Color frameColor
        If frameWidth is greate than zero, then a frame is drawn around the string in this color. If the value is null, then the color will be the same as the color of the string.
    • Constructor Detail

      • DrawString

        public DrawString()
        Create a DrawString object that initially has no string to draw.
      • DrawString

        public DrawString​(java.lang.String str)
        Create a DrawString for drawing a black string in the top left corner of the coordinate rect.
        Parameters:
        str - The string to draw, which can contain \n's to indicate line breaks.
      • DrawString

        public DrawString​(java.lang.String str,
                          int pos)
        Create a DrawString for drawing a black string in the position specified.
        Parameters:
        str - The string to draw, which can contain \n's to indicate line breaks.
        pos - The positioning of the string in the coordinate rect. One of the positioning constants such as TOP_LEFT or BOTTOM_RIGHT.
      • DrawString

        public DrawString​(java.lang.String str,
                          int pos,
                          Value[] values)
        Create a DrawString for drawing a black string in the specified position. The number of #'s in the string should match values.length. The values are computed and substituted for the #'s.
        Parameters:
        str - The string to draw, which can contain \n's to indicate line breaks and #'s to be replaced by numeric values.
        pos - The positioning of the string in the coordinate rect. One of the positioning constants such as TOP_LEFT or BOTTOM_RIGHT.
        values - Value objects associated with #'s in the string.
      • DrawString

        public DrawString​(java.lang.String str,
                          int pos,
                          Value xPos,
                          Value yPos,
                          Value[] values)
        Create a string that is displayed at the reference point (xPos,yPos); The positioning constant, pos, gives the positioning relative to this point, if xPos or yPos is non-null.
        Parameters:
        str - The string to draw, which can contain \n's to indicate line breaks and #'s to be replaced by numeric values.
        pos - The positioning of the string. One of the positioning constants such as TOP_LEFT or BOTTOM_RIGHT. If xPos or yPos is non-nul, this is interpreted relative to their values.
        xPos - x-coordinate relative to which the string is drawn (or null for absolute hoizontal positioning).
        yPos - y-coordinate relative to which the string is drawn (or null for absolute vertical positioning).
        values - Value objects associated with #'s in the string.
    • Method Detail

      • setColor

        public void setColor​(java.awt.Color c)
        Set the color for the string. If c is null, Color.black is used.
      • getColor

        public java.awt.Color getColor()
        Get the non-null color that is used for drawing the string.
      • setFont

        public void setFont​(java.awt.Font f)
        Set the font that is used for drawing this string. If f is null, then the font is obtained from the Graphics context in which the string is drawn.
      • getFont

        public java.awt.Font getFont()
        Return the font that is used for drawing the string. If the return value is null, then the font is taken from the Graphics context.
      • setValues

        public void setValues​(Value[] v)
        Set the Values that are substituted for (single) #'s in the string. If the array of Values is null, then no substitution is done. The length of the array should match the number of #'s, but it is not an error if they do not match. Extra values will be ignored; extra #'s will be shown as "undefined".
      • getValues

        public Value[] getValues()
        Return the array of values that are substituted for #'s in the string.
      • setPositioning

        public void setPositioning​(int pos)
        Set the positioning of the string. The parameter should be one of the positioning contstants defined in this class, such as TOP_LEFT. (If it is not, TOP_LEFT is used by default.)
      • getPositioning

        public int getPositioning()
        Return the positioning, as set by setPositioning().
      • setReferencePoint

        public void setReferencePoint​(Value x,
                                      Value y)
        Set the values of the (x,y) coordinates of the reference point for the stirng. If a value is null, absolute positioning is used. If a value is undefined, the string is not drawn.
      • getXPos

        public Value getXPos()
        Return the Value object that gives the x-coordinate of the reference point of this string.
      • getYPos

        public Value getYPos()
        Return the Value object that gives the y-coordinate of the reference point of this string.point of this string.
      • setString

        public void setString​(java.lang.String str)
        Set the string that is displayed. Note that it can include '\n' to represent a line break, and it can contain #'s which will be replaced by computed values.
      • getString

        public java.lang.String getString()
        Get a copy of the display string (with \n's #'s, not with substitued values.)
      • setOffset

        public void setOffset​(int b)
        Set the distance of the bounding box of the string from the reference point where it is drawn. The default value is 3.
      • getOffset

        public int getOffset()
        Get the distance of the bounding box of the string from the reference point where it is drawn.
      • setClamp

        public void setClamp​(boolean clamp)
        Set the "clamp" property of the DrawString. If set to true, the string will be clamped to lie entirely within the CoordinateRect (unless it doens't fit -- then it can stick out on the right and bottom). The default value is true.
      • getClamp

        public boolean getClamp()
        Returns true if the string is set to be clamped to lie within the CoordinateRect.
      • setJustification

        public void setJustification​(int j)
        Set the justification to be used if there are multiple lins in the string. Possible value are DrawString.LEFT, DrawString.RIGHT, and DrawString.CENTER.
      • getJustification

        public int getJustification()
        Get the justification that is used for a multiple-line string. The value is one of the constants DrawString.LEFT, DrawString.RIGHT, or DrawString.CENTER
      • setNumSize

        public void setNumSize​(int size)
        Set the desired maximum number of characters in displayed numbers. Actual size might be larger. Value is clamped to the range 6 to 25.
      • getNumSize

        public int getNumSize()
        Return the desired maximum number of characters in displayed numbers.
      • getBackgroundColor

        public java.awt.Color getBackgroundColor()
        Get the color that is used to fill a rectangle on which the string is drawn. Null indicates that no rectangle is filled so the stuff in back of the string shows though. The default value is null.
      • setBackgroundColor

        public void setBackgroundColor​(java.awt.Color color)
        Set the color that is used to fill a rectangle on which the string is drawn. If the value is null, no rectangle is filled and the string just overlays whatever is in back of it on the canvas.
      • getFrameColor

        public java.awt.Color getFrameColor()
        Get the color that is used to draw a frame around the string. This is only done if the frameWidth property is greater than zero. If the value is null, the frame is the same color as the string.
      • setFrameColor

        public void setFrameColor​(java.awt.Color color)
        Set the color that is used to draw a frame around the string. This is only done if the frameWidth property is greater than zero. If the value is null, the frame is the same color as the string.
      • getFrameWidth

        public int getFrameWidth()
        Get the width, in pixels, of the frame that is drawn around the string. The default width is zero. The largest possible value is 25.
      • setFrameWidth

        public void setFrameWidth​(int width)
        Set the width, in pixels, of a frame to draw around the string. If the value is zero, no frame is drawn. The default value is zero. The the value is clamped to the range 0 to 25.
      • compute

        public void compute()
        The compute method sets up the array of strings that is actually displayed. This is required by the Computable interface and is usually called by a Controller rather than directly.
        Specified by:
        compute in interface Computable
      • draw

        public void draw​(java.awt.Graphics g,
                         boolean coordsChanged)
        Draws the string.
        Specified by:
        draw in class Drawable
        Parameters:
        g - The graphics context in which the Drawble is to be drawn. (The drawing can change the color in g, but should not permanently change font, painting mode, etc. Thus, every drawable is responsible for setting the color it wants to use.)
        coordsChanged - Indicates whether the CoordinateRect has changed.