Class PaperProperties

  • All Implemented Interfaces:
    IconProvider, java.io.Serializable, java.lang.Comparable<PaperProperties>

    public final class PaperProperties
    extends java.lang.Object
    implements java.lang.Comparable<PaperProperties>, IconProvider, java.io.Serializable
    PaperProperties are immutable objects that describe the properties of the paper used in a deck.
    Author:
    Chris Jennings
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static boolean LANDSCAPE
      A constant that indicates the landscape orientation (in which the width is the longest dimension).
      static double MAX_PAPER_SIZE
      The maximum size for a paper dimension, in points.
      static boolean PORTRAIT
      A constant that indicates the portrait orientation (in which the width is the shortest dimension).
    • Constructor Summary

      Constructors 
      Constructor Description
      PaperProperties()
      Create a new paper properties object using default dimensions that match the "North American Letter" paper size.
      PaperProperties​(java.lang.String name, double width, double height, boolean orientation)
      Create a new paper property description.
      PaperProperties​(java.lang.String name, double width, double height, boolean orientation, double margin, double gridSeparation)
      Create a new paper property description.
      PaperProperties​(java.lang.String name, double width, double height, boolean orientation, double margin, double gridSeparation, boolean isPhysical, Game game)
      Create a new paper property description.
      PaperProperties​(javax.print.attribute.standard.MediaSize media, boolean orientation)
      Creates a paper properties object from a print media description.
      PaperProperties​(javax.print.attribute.standard.MediaSize media, boolean orientation, double margin, double gridSeparation)
      Creates a paper properties object from a print media description.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(PaperProperties that)
      The natural ordering of paper properties instances sorts them by their string representation using the interface language's collator.
      java.awt.image.BufferedImage createCompatibleImage​(double ppi)
      Create an image compatible with the dimensions of this PaperProperties.
      java.awt.print.PageFormat createCompatiblePageFormat​(boolean applyMargins)
      Create a PageFormat object that is compatible with this PaperProperties.
      PaperProperties deriveOrientation​(boolean orientation)
      Returns a PaperProperties with the same dimensions as this paper but with the requested orientation.
      boolean equals​(java.lang.Object that)
      Returns true if another properties instance has the same dimensions, orientation, grid size, margin, and name as this instance.
      java.lang.String getGameCode()
      Returns the game code for the Game that this paper type is associated with.
      double getGridSeparation()
      Returns the distance between grid lines, in points (1/72 inch).
      javax.swing.Icon getIcon()  
      java.lang.String getInternalName()
      Returns the internal name for this paper type.
      double getMargin()
      Returns the margin around page edges, in points (1/72 inch).
      java.lang.String getName()
      Returns the name for this paper type.
      boolean getOrientation()
      Returns PORTRAIT or LANDSCAPE depending on the orientation.
      double getPageHeight()
      Returns the page height in points (1/72 inch).
      double getPageWidth()
      Returns the page width in points (1/72 inch).
      PrintDimensions getPrintDimensions()
      Returns the page dimensions as an immutable PrintDimensions instance.
      int hashCode()  
      boolean isPhysical()
      Returns true if this describes a physical paper type; that is, if it matches real-world paper sizes that might fit in a particular printer model.
      boolean isPortraitOrientation()
      Returns true if this page uses portrait orientation.
      java.lang.String toString()
      Returns a localized description of the paper type.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • PORTRAIT

        public static final boolean PORTRAIT
        A constant that indicates the portrait orientation (in which the width is the shortest dimension).
        See Also:
        Constant Field Values
      • LANDSCAPE

        public static final boolean LANDSCAPE
        A constant that indicates the landscape orientation (in which the width is the longest dimension).
        See Also:
        Constant Field Values
    • Constructor Detail

      • PaperProperties

        public PaperProperties()
        Create a new paper properties object using default dimensions that match the "North American Letter" paper size.
      • PaperProperties

        public PaperProperties​(java.lang.String name,
                               double width,
                               double height,
                               boolean orientation)
        Create a new paper property description. Note that the width and height can be given in any order. The actual width and height dimensions will be determined automatically from the orientation. The paper name is localized automatically if the name begins with '@'. The localized name is determined as if by Language.string( name.substring(1) ).
        Parameters:
        name - the name to use for the paper type
        width - paper width in points
        height - paper height in points
        orientation - one of LANDSCAPE or PORTRAIT
        Throws:
        java.lang.NullPointerException - if the name is null
      • PaperProperties

        public PaperProperties​(java.lang.String name,
                               double width,
                               double height,
                               boolean orientation,
                               double margin,
                               double gridSeparation)
        Create a new paper property description. Note that the width and height can be given in any order. The actual width and height dimensions will be determined automatically from the orientation.
        Parameters:
        name - the name to use for the paper type
        width - paper width in points
        height - paper height in points
        orientation - one of LANDSCAPE or PORTRAIT
        margin - the size of the print edge margin, in points
        gridSeparation - the size of the snapping grid, in points
      • PaperProperties

        public PaperProperties​(java.lang.String name,
                               double width,
                               double height,
                               boolean orientation,
                               double margin,
                               double gridSeparation,
                               boolean isPhysical,
                               Game game)
        Create a new paper property description. Note that the width and height can be given in any order. The actual width and height dimensions will be determined automatically from the orientation.
        Parameters:
        name - the name to use for the paper type
        width - paper width in points
        height - paper height in points
        orientation - one of LANDSCAPE or PORTRAIT
        margin - the size of the print edge margin, in points
        gridSeparation - the size of the snapping grid, in points
        isPhysical - true if this paper represents physical media, or false if it represents a virtual paper size such as the size of an expansion board
        game - the game that this paper applies to, or null for all games
      • PaperProperties

        public PaperProperties​(javax.print.attribute.standard.MediaSize media,
                               boolean orientation)
        Creates a paper properties object from a print media description.
        Parameters:
        media - the media description to
        orientation - one of LANDSCAPE or PORTRAIT
      • PaperProperties

        public PaperProperties​(javax.print.attribute.standard.MediaSize media,
                               boolean orientation,
                               double margin,
                               double gridSeparation)
        Creates a paper properties object from a print media description.
        Parameters:
        media - the media description to
        orientation - one of LANDSCAPE or PORTRAIT
        margin - the size of the print edge margin, in points
        gridSeparation - the size of the snapping grid, in points
    • Method Detail

      • getName

        public java.lang.String getName()
        Returns the name for this paper type.
        Returns:
        the paper's base name
        See Also:
        toString()
      • getInternalName

        public java.lang.String getInternalName()
        Returns the internal name for this paper type. The internal name is the name that the paper was created with. This will be the same value as getName() unless the paper was created with a localizable @-name.
        Returns:
        the name that the paper was created with
        Since:
        3.0
      • getPageWidth

        public double getPageWidth()
        Returns the page width in points (1/72 inch).
        Returns:
        the page width, corrected for orientation
      • getPageHeight

        public double getPageHeight()
        Returns the page height in points (1/72 inch).
        Returns:
        the page height, corrected for orientation
      • getPrintDimensions

        public PrintDimensions getPrintDimensions()
        Returns the page dimensions as an immutable PrintDimensions instance. The dimensions will reflect the page's orientation.
        Returns:
        the page dimensions, corrected for orientation
      • getGridSeparation

        public double getGridSeparation()
        Returns the distance between grid lines, in points (1/72 inch).
        Returns:
        the snapping grid size
      • getMargin

        public double getMargin()
        Returns the margin around page edges, in points (1/72 inch).
        Returns:
        the edge margin
      • isPortraitOrientation

        public boolean isPortraitOrientation()
        Returns true if this page uses portrait orientation. (The definition of PORTRAIT is such that the value returned from this method and the value returned from getOrientation() are identical.)
        Returns:
        true if orientation is PORTRAIT, otherwise false
        See Also:
        getOrientation()
      • isPhysical

        public boolean isPhysical()
        Returns true if this describes a physical paper type; that is, if it matches real-world paper sizes that might fit in a particular printer model.
        Returns:
        true if this is a physical paper type
      • getGameCode

        public java.lang.String getGameCode()
        Returns the game code for the Game that this paper type is associated with. If the paper type is not associated with a game, this will be Game.ALL_GAMES_CODE.
        Returns:
        the non-null game code for the game this paper type is associated with
      • deriveOrientation

        public PaperProperties deriveOrientation​(boolean orientation)
        Returns a PaperProperties with the same dimensions as this paper but with the requested orientation. If the orientation matches this paper's orientation, this instance is returned. Otherwise, a new instance is returned with the requested orientation.
        Parameters:
        orientation - one of LANDSCAPE or PORTRAIT
        Returns:
        a paper properties with these dimensions and the requested orientation
      • createCompatiblePageFormat

        public java.awt.print.PageFormat createCompatiblePageFormat​(boolean applyMargins)
        Create a PageFormat object that is compatible with this PaperProperties. PageFormats are used by the printing system to describe physical pages. If applyMargins is true, then the imageable area of the resulting PageFormat will be reduced to account for the margin. Otherwise, the imageable area will be set to the entire page.
        Parameters:
        applyMargins - if true, use the margin to set the imageable area
        Returns:
        a page format that represents the same physical paper size and orientation as this instance
      • createCompatibleImage

        public java.awt.image.BufferedImage createCompatibleImage​(double ppi)
        Create an image compatible with the dimensions of this PaperProperties. The size of the image will be determined by the page size and the resolution, specified in pixels per inch. The new image will be filled with solid white.
        Parameters:
        ppi - the resolution of resulting image, in pixels per inch
        Returns:
        an image the same size as this paper size at the given resolution
        Throws:
        java.lang.IllegalArgumentException - if ppi is not a positive number
      • toString

        public java.lang.String toString()
        Returns a localized description of the paper type.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a human-friendly description of the paper type
      • equals

        public boolean equals​(java.lang.Object that)
        Returns true if another properties instance has the same dimensions, orientation, grid size, margin, and name as this instance.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        that - the paper properties to compare this with
        Returns:
        true if the paper properties are equal to this
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • compareTo

        public int compareTo​(PaperProperties that)
        The natural ordering of paper properties instances sorts them by their string representation using the interface language's collator.

        Note: This ordering is incompatible with the definition of equals(java.lang.Object).

        Specified by:
        compareTo in interface java.lang.Comparable<PaperProperties>
        Parameters:
        that - the properties to compare this to
        Returns:
        for the toString() value of this and that object:
        the value 0 if the values are equal;
        a value less than 0 if this is "less" than that;
        and a value greater than 0 if this is "greater" than that
      • getIcon

        public javax.swing.Icon getIcon()
        Specified by:
        getIcon in interface IconProvider