Package ca.cgjennings.apps.arkham.component

Interface Portrait

  • All Known Implementing Classes:
    AbstractPortrait, DefaultPortrait
    public interface Portrait
    A portrait is a user-supplied image that is part of a game component, such as a character portrait on a character card. Portraits are obtained using the PortraitProvider interface implemented by components that support them. Note that a component may implement that interface yet not actually have any portraits (by returning 0 from PortraitProvider.getPortraitCount()).
    Since:
    3.0
    Author:
    Chris Jennings

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  Portrait.Feature
      Identifies features that this portrait supports.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.awt.Dimension getClipDimensions()
      Returns the size of the bounding rectangle of the area that the portrait is drawn within on the component sheet, in the coordinate system of the sheet's template image.
      java.awt.image.BufferedImage getClipStencil()
      Optionally returns an image that describes how the portrait will "show through" surrounding card features.
      java.util.EnumSet<Portrait.Feature> getFeatures()
      Returns a set of the features supported by this portrait.
      java.awt.image.BufferedImage getImage()
      Returns the image being used by this portrait.
      java.awt.geom.Point2D getPan​(java.awt.geom.Point2D dest)
      Returns the pan value as a Point2D.
      double getPanX()
      Returns the horizontal pan value.
      double getPanY()
      Returns the vertical pan value.
      double getRotation()
      Returns the rotation angle for the portrait image.
      double getScale()
      Returns the scale of the portrait.
      java.lang.String getSource()
      Returns the identifier for the image being used by this portrait.
      void installDefault()
      Requests that this portrait be set to use a default portrait image.
      void setImage​(java.lang.String reportedSource, java.awt.image.BufferedImage image)
      Explicitly sets the image used by this portrait.
      void setPan​(java.awt.geom.Point2D pan)
      Sets the pan value from a reference point.
      void setPanX​(double x)
      Sets the horizontal pan value.
      void setPanY​(double y)
      Sets the vertical pan value.
      void setRotation​(double angleInDegrees)
      Sets the rotation angle for the portrait image.
      void setScale​(double scale)
      Sets the scale factor applied to the default size chosen by the component.
      void setSource​(java.lang.String resource)
      Sets the image used by the portrait.The value of resource is an identifier such as a local path to an image file or a URL.

    • Field Detail

      • STANDARD_PORTRAIT_FEATURES

        static final java.util.EnumSet<Portrait.Feature> STANDARD_PORTRAIT_FEATURES
        A predefined feature set that includes all of the features except rotation.

      • ROTATABLE_PORTRAIT_FEATURES

        static final java.util.EnumSet<Portrait.Feature> ROTATABLE_PORTRAIT_FEATURES
        A predefined feature set that includes all of the features except rotation.

    • Method Detail

      • setSource

        void setSource​(java.lang.String resource)
        Sets the image used by the portrait.The value of resource is an identifier such as a local path to an image file or a URL. Either null or an empty string is a special identifier that requests a default image that depends on the component and portrait number.

        When a new portrait is set, the scale, pan, and rotation values will be changed to suit the new image. If you wish to keep these fixed, you must store these values in temporary variables before setting them image, and then restore them once this method returns.

        If an image cannot be obtained from resource (for example, if the file it names does not exist or is invalid), then a special error image is substituted.

        Parameters:
        resource - an identifier user to locate the image (a file or URL)
        Throws:
        java.lang.NullPointerException - if resource is null

      • getSource

        java.lang.String getSource()
        Returns the identifier for the image being used by this portrait. See the description of setSource(java.lang.String) for details.
        Returns:
        a resource identifier, such as a file path or URL

      • getImage

        java.awt.image.BufferedImage getImage()
        Returns the image being used by this portrait. The original image is returned, rather than a copy, in order to conserve resources. However, it is important that this image not be modified in any way as it may be shared between several objects.
        Returns:
        a shared copy of the image used by the component

      • setImage

        void setImage​(java.lang.String reportedSource,
              java.awt.image.BufferedImage image)
        Explicitly sets the image used by this portrait. The source for the portrait will be set to reported source, but no attempt will be made to load the portrait from this source. Instead, the given image will be used as if it was the image loaded from the reported source. This is sometimes useful when you want to copy an image to a new component but you do not know if the source location is actually available on this system.
        Parameters:
        reportedSource - the apparent source of the image
        image - the image to use

      • getScale

        double getScale()
        Returns the scale of the portrait. A scale of 1 means that the portrait is being used at the default size chosen by the component.
        Returns:
        the scale multiplier for the portrait

      • setScale

        void setScale​(double scale)
        Sets the scale factor applied to the default size chosen by the component. Note that for many component types, the default size just fits in the available space, so that a value less than 1 will show blank space at one or more edges of the portrait area.
        Parameters:
        scale - the scale multiplier to apply to the image's default size

      • getPanX

        double getPanX()
        Returns the horizontal pan value. A value of 0 places the image at its default location within the portrait area. The units are pixels in the component's template image.
        Returns:
        the shift from the default X position of the portrait

      • setPanX

        void setPanX​(double x)
        Sets the horizontal pan value.
        Parameters:
        x - the shift from the default X position of the portrait

      • getPanY

        double getPanY()
        Returns the vertical pan value. A value of 0 places the image at its default location within the portrait area. The units are pixels in the component's template image.
        Returns:
        the shift from the default Y position of the portrait

      • setPanY

        void setPanY​(double y)
        Sets the vertical pan value.
        Parameters:
        y - the shift from the default Y position of the portrait

      • setPan

        void setPan​(java.awt.geom.Point2D pan)
        Sets the pan value from a reference point.
        Parameters:
        pan - a point set to the new X and Y pan values

      • getPan

        java.awt.geom.Point2D getPan​(java.awt.geom.Point2D dest)
        Returns the pan value as a Point2D. The pan values will be stored in dest; if null, a new point object will be allocated and returned.
        Parameters:
        dest - a point object to store the pan value in
        Returns:
        the point object that contains the pan value

      • getRotation

        double getRotation()
        Returns the rotation angle for the portrait image. The default rotation is usually 0, but it differs by component. Positive angles turn in the anti-clockwise direction, while negative angles turn in the clockwise direction.
        Returns:
        the rotation angle, in degrees

      • setRotation

        void setRotation​(double angleInDegrees)
        Sets the rotation angle for the portrait image.
        Parameters:
        angleInDegrees - the rotation angle, in degrees

      • installDefault

        void installDefault()
        Requests that this portrait be set to use a default portrait image.

      • getClipDimensions

        java.awt.Dimension getClipDimensions()
        Returns the size of the bounding rectangle of the area that the portrait is drawn within on the component sheet, in the coordinate system of the sheet's template image.

        Note: The value returned by this method is intended for use in creating sample composites for the user to manipulate when adjusting the portrait. It usually, but may not, reflect the dimensions used internally by the portrait when drawing or calculating a default portrait scale.

        Returns:
        the dimensions of the portrait's clipping rectangle

      • getClipStencil

        java.awt.image.BufferedImage getClipStencil()
        Optionally returns an image that describes how the portrait will "show through" surrounding card features. The image's alpha channel is taken to represent a mask for the features that appear over the portrait area. For example, pixels with an alpha of 0 will show the portrait image only, and pixels with an alpha of 255 will show part of a sheet feature that obscures the underlying portrait. In other words, the alpha channel describes the shape of the portrait. If the portrait is simply an unobscured rectangle (that is, nothing is drawn overtop of it), this method can simply return null.

        Note: The value returned by this method is not guaranteed to be accurate and should not be relied on.

        Returns:
        an image whose alpha channel describes the obscured areas of the portrait, or null

      • getFeatures

        java.util.EnumSet<Portrait.Feature> getFeatures()
        Returns a set of the features supported by this portrait.