Package ca.cgjennings.apps.arkham.sheet

Class Sheet<G extends GameComponent>

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Sheet.DeckSnappingHint
      A deck snapping hint is used the describe the general behaviour of a sheet when it is placed in a deck and an attempt is made to snap it against another object.

    • Constructor Summary

      Constructors 
      Constructor Description
      Sheet​(G gameComponent)
      Creates a component face for a game component.
      Sheet​(G gameComponent, java.lang.String templateKey)
      Creates a component face for a game component that will use a template image defined by the value of the templateKey setting.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void allowTemplateUseInBleedSynthesis()
      Calling this method sets an internal flag allowing the template image to be used for bleed margin synthesis.
      protected void applyContextHints​(java.awt.Graphics2D g)
      Prepares a graphics context to render a sheet by setting up the context's rendering hints.
      protected void applyContextScale​(java.awt.Graphics2D g)
      Scales a graphics context to reflect the requested drawing resolution.
      protected java.awt.image.BufferedImage applyFinishingOptions​(java.awt.image.BufferedImage sheetImage, RenderTarget target, double resolution)
      Applies finishing options such as bleed margin adjustment and corner cuts to a painted sheet.
      void centerTitle​(java.awt.Graphics2D g, java.lang.String text, java.awt.Rectangle r, java.awt.Font font, float size, boolean embolden)
      Deprecated.
      Included for backwards compatibility with old plug-ins; use drawTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int) instead.
      java.awt.Graphics2D createGraphics()
      Creates a graphics context that can be used to draw this sheet.
      java.awt.Graphics2D createGraphics​(java.awt.image.BufferedImage bufferSource, boolean scaleForResolution, boolean applyHints)
      This method creates a graphics context for drawing sheet graphics.
      java.awt.image.BufferedImage createTemporaryImage​(int templateWidth, int templateHeight, boolean includeAlphaChannel)
      Creates a new temporary image to use while painting a sheet face.
      static void doStandardRendererInitialization​(MarkupRenderer r)  
      void drawOutlinedTitle​(java.awt.Graphics2D g, java.lang.String text, java.awt.Rectangle region, java.awt.Font font, float maxSize, float outlineSize, java.awt.Paint textColor, java.awt.Paint outlineColor, int alignment, boolean outlineUnderneath)
      Draws text within a region.
      static void drawPortraitBox​(java.awt.Graphics2D g, java.awt.geom.Rectangle2D region, Portrait portrait)
      A helper function that can be called from custom portrait painting code to draw the portrait debug box, if enabled.
      static void drawPortraitBox​(java.awt.Graphics2D g, java.awt.geom.Rectangle2D region, java.awt.image.BufferedImage portraitImage, double panX, double panY, double scale, double angle)
      A helper function that can be called from custom portrait painting code to draw the portrait debug box, if enabled.
      void drawRegionBox​(java.awt.Graphics2D g, java.awt.Rectangle region)
      Draws a magenta outline of the specified rectangle if layout debugging has been enabled.
      void drawRotatedTitle​(java.awt.Graphics2D g, java.lang.String text, java.awt.Rectangle region, java.awt.Font font, float maxSize, int alignment, int turns)
      Draws text within a region.
      void drawTitle​(java.awt.Graphics2D g, java.lang.String text, java.awt.Rectangle region, java.awt.Font font, float size, int alignment)
      Draws text within a region.
      void fitTitle​(java.awt.Graphics2D g, java.lang.String text, java.awt.Rectangle region, java.awt.Font font, float maxSize, int alignment)
      Draws text within a region; if the text is wider than the region, it will be scaled down to fit.
      void freeCachedResources()
      Releases cached resources used in sheet drawing, freeing up memory for other purposes.
      double getBleedMargin()
      Returns the size of the bleed margin around the component edge that should be cropped off, measured in points.
      double getCornerRadius()
      Returns the radius that should be used to round the corners of the component, measured in points.
      Sheet.DeckSnappingHint getDeckSnappingHint()
      Returns a hint describing how this sheet should behave when snapped in a deck.
      protected java.awt.image.BufferedImage getDestinationBuffer()
      Returns a view of the internal sheet image buffer as a BufferedImage object.
      static java.awt.image.BufferedImage getExpansionSymbol​(Expansion expansion, java.lang.String booleanOrIntegerVariant, int targetWidth)
      Returns the symbol to be painted on cards for an expansion.
      java.lang.String getExpansionSymbolKey()
      Returns the name of the settings key that will be used for the default expansion painting mechanism.
      double[] getFoldMarks()
      Returns an array that describes the extra fold marks that should appear on this face when it is placed in a deck.
      G getGameComponent()
      Returns the game component that this sheet was created for.
      MarkerStyle getMarkerStyle()
      If this sheet represents an embedded marker, returns the layout style of the marker.
      double getPaintingResolution()
      Returns the resolution that the sheet is being painted at, in pixels per inch.If called when the sheet is not being painted, returns the value that was active during the last paint request.
      PrintDimensions getPrintDimensions()
      Return the printed size of the sheet, measured in points.
      double getRenderedBleedMargin()
      Returns the actual bleed margin width that will be rendered for this sheet.
      double getScalingFactor()
      Returns the current scaling factor; this is the ratio of the resolution the sheet is being painted at to the template resolution.
      double getSuggestedUpsampleFactor()
      Returns a suggested scaling factor to use when previewing the image onscreen.
      int getTemplateHeight()
      Returns the height of the template image used by this sheet.
      java.awt.image.BufferedImage getTemplateImage()
      Returns the template image; this will be the image determined by the template key unless the image was changed by calling replaceTemplateImage(java.awt.image.BufferedImage).
      java.lang.String getTemplateKey()
      Returns the setting key that defines the template image for this face.
      double getTemplateResolution()
      Returns the base resolution of the template image, in pixels per inch (ppi).
      int getTemplateWidth()
      Returns the width of the template image used by this sheet.
      double getUserBleedMargin()
      Returns the ideal bleed margin for this sheet, in points.
      boolean hasChanged()
      Returns true if the sheet is currently marked as out of date.
      boolean hasCropMarks()
      Returns true if this sheet should have automatic crop and fold marks added when printed or placed in a deck.
      boolean hasFoldMarks()
      Returns true if this sheet should have special fold marks added when printed.When this returns true one or more fold marks will be shown at locations determined by getFoldMarks().
      protected void initializeTemplate​(java.lang.String templateKey)
      Initializes the template image, resolution, default expansion symbol location, and upsample rate from a base key name.
      protected void initializeTemplate​(java.lang.String pseudoKey, java.awt.image.BufferedImage template, java.lang.String expansionSymbolKey, double resolution, double upsampleFactor)
      Initializes the sheet from raw values instead of from settings.
      boolean isCachedTemporaryImageInvalid()
      Returns a hint value to help manage partial rendering caches.
      boolean isMarginSynthesisAllowed()
      Returns whether the sheet is allowed to synthesize a bleed margin when the designed margin is less than the user-requested margin.
      boolean isPrototypeRenderingModeEnabled()
      Returns whether prototype rendering mode is enabled.
      boolean isTransparent()
      Returns true if the sheets for this card are transparent.
      boolean isVariableSize()
      Returns true if the sheets created by this card can vary in size.
      void markChanged()
      Marks this face as out of date.
      java.awt.image.BufferedImage paint​(RenderTarget target, double resolution)
      Returns an image of the sheet content.
      java.awt.image.BufferedImage paint​(RenderTarget target, double resolution, boolean synthesizeBleedMargin)
      Deprecated.
      Use setUserBleedMargin(double) to set the desired bleed margin size, then call paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) to paint the image.
      protected abstract void paintSheet​(RenderTarget target)
      Paints the content of this sheet.
      static Expansion[] parseExpansionList​(java.lang.String settingValue)
      Given a list of expansion codes separated by commas (the format used to set expansion icons in a game component's private settings), return an array of the expansions represented by the codes.
      protected void replaceTemplateImage​(java.awt.image.BufferedImage newTemplate)
      Replaces the template image for the sheet.
      void setCornerRadius​(double radiusInPoints)
      Sets the corner radius used to round corners of the component, measured in points.
      protected void setExpansionSymbolKey​(java.lang.String expsymKey)
      Sets the name of the settings key that will be used by the default expansion symbol painting mechanism.
      static void setNamesForRenderer​(MarkupRenderer r, java.lang.String first, java.lang.String last, java.lang.String fullname)  
      void setPrototypeRenderingModeEnabled​(boolean prototype)
      Sets whether the sheet is rendered in prototype mode, with a white background and only text and shapes (no images).
      void setUserBleedMargin​(double marginInPoints)
      Sets the ideal bleed margin for this sheet, in points.
      protected java.awt.image.BufferedImage synthesizeBleedMargin​(java.awt.image.BufferedImage sheetImage, boolean synthesize, double resolution)
      Deprecated.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Sheet

        public Sheet​(G gameComponent)
        Creates a component face for a game component. Concrete subclasses must call initializeTemplate(java.lang.String) at some point in their constructor.
        Parameters:
        gameComponent - the component that this sheet draws for

      • Sheet

        public Sheet​(G gameComponent,
             java.lang.String templateKey)
        Creates a component face for a game component that will use a template image defined by the value of the templateKey setting. Note that the sheet is not required to actually use the template image. For example, the actual template image that gets drawn may be selected from one of several different images depending on settings in the associated game component.
        Parameters:
        gameComponent - the component that this sheet draws for
        templateKey - the key that defines the template image

    • Method Detail

      • initializeTemplate

        protected final void initializeTemplate​(java.lang.String templateKey)
        Initializes the template image, resolution, default expansion symbol location, and upsample rate from a base key name. If the constructor that takes a template key as a parameter was used to create this sheet, then this method will already have been called. Otherwise, you must call this method from within the subclass constructor.

        The initialization process consists of the following steps:

        1. The Settings of the game component associated with this sheet are fetched to look up the keys below.
        2. The template image is loaded using templateKey.
        3. If templateKey ends with -template, this is removed.
        4. The default region for drawing expansion symbols, if any, is read from templateKey-expsym-region.
        5. The template image resolution, in pixels per inch, is read from templateKey@code -ppi}; if undefined, the default is 150 ppi. (The suffix -dpi can also be used.)
        6. The preferred display upsample factor is read from templateKey-upsample; if undefined, the default is 1; this is multiplied by the template resolution to determine the default resolution for rendering. The default resolution is used by the preview window; components with extremely small text can be made more legible by increasing this value.
        7. The initial corner radius is set from templateKey-corner-radius; if undefined the default is 0. See also getBleedMargin().
        Parameters:
        templateKey - the base key name to use to initialize the template for this sheet
        Throws:
        java.lang.NullPointerException - if the template key is null

      • initializeTemplate

        protected final void initializeTemplate​(java.lang.String pseudoKey,
                                        java.awt.image.BufferedImage template,
                                        java.lang.String expansionSymbolKey,
                                        double resolution,
                                        double upsampleFactor)
        Initializes the sheet from raw values instead of from settings.
        Parameters:
        pseudoKey - the key value to report from getTemplateKey()
        template - the template image for the sheet
        expansionSymbolKey - the key to check for an expansion symbol region for default expansion symbol painting
        resolution - the resolution of the template image, in pixels per inch
        upsampleFactor - the upsample factor that determines the default resolution
        Throws:
        java.lang.NullPointerException - if the template or expansion symbol key is null
        java.lang.IllegalArgumentException - if the resolution or upsample factor is not positive

      • getMarkerStyle

        public MarkerStyle getMarkerStyle()
        If this sheet represents an embedded marker, returns the layout style of the marker. For regular sheets, this method returns null. (The base class returns null.)
        Returns:
        the token style of the embedded token, or null for standard sheets

      • setPrototypeRenderingModeEnabled

        public void setPrototypeRenderingModeEnabled​(boolean prototype)
        Sets whether the sheet is rendered in prototype mode, with a white background and only text and shapes (no images). This feature is called "ink saver" in the UI.
        Parameters:
        prototype - true if prototype mode should be enabled

      • isPrototypeRenderingModeEnabled

        public boolean isPrototypeRenderingModeEnabled()
        Returns whether prototype rendering mode is enabled. This feature is called "ink saver" in the UI.
        Returns:
        true if prototype rendering is enabled

      • paint

        public final java.awt.image.BufferedImage paint​(RenderTarget target,
                                                double resolution)
        Returns an image of the sheet content. The caller must not modify the contents of the returned image, as the image may be reused to speed up subsequent paint requests. (If you need to modify the returned image, use a copy.)

        If the sheet needs to be redrawn to satisfy the request, this method will call paintSheet(ca.cgjennings.apps.arkham.sheet.RenderTarget) to allow the subclass to paint the component-specific content. It will then execute the game component's on paint event handler (ScriptMonkey.ON_PAINT_EVENT_KEY), if any, and perform default expansion symbol drawing before returning the image.

        The resolution parameter determines the resolution of the result, in pixels per inch. If -1, the resolution will be the default resolution for the card, which is equal to getTemplateResolution() multiplied by getSuggestedUpsampleFactor().

        Parameters:
        target - the target hint to use for painting
        resolution - the resolution of the returned image, or -1 for the sheet's default resolution
        Returns:
        an image representing the content of the component face represented by this sheet
        Throws:
        java.lang.NullPointerException - if target is null
        java.lang.IllegalArgumentException - if the resolution is less than 1 but not the special default value (-1)
        java.util.ConcurrentModificationException - if the sheet is already being painted
        See Also:
        paintSheet(ca.cgjennings.apps.arkham.sheet.RenderTarget), applyContextHints(java.awt.Graphics2D)

      • applyFinishingOptions

        protected java.awt.image.BufferedImage applyFinishingOptions​(java.awt.image.BufferedImage sheetImage,
                                                             RenderTarget target,
                                                             double resolution)
        Applies finishing options such as bleed margin adjustment and corner cuts to a painted sheet.
        Parameters:
        sheetImage - a rendered sheet image
        target - a target describing the general quality and purpose
        resolution - the desired image resolution, in pixels per inch
        Returns:
        the original image, or a new image that has been modified to apply the selected finishing options

      • allowTemplateUseInBleedSynthesis

        public void allowTemplateUseInBleedSynthesis()
        Calling this method sets an internal flag allowing the template image to be used for bleed margin synthesis. This can improve the quality of the synthesized margin since the synthesized material will not include text and other painted content. However, some card designs modify the template on the fly: for example, with tinting or by substituting different graphics based on a user selection. Since this would result in a glaringly wrong bleed margin and Strange Eons cannot know if this may occur, it will not use the template unless explicitly told that this is safe by calling this method.

      • isMarginSynthesisAllowed

        public boolean isMarginSynthesisAllowed()
        Returns whether the sheet is allowed to synthesize a bleed margin when the designed margin is less than the user-requested margin. The base class returns true.
        Returns:
        true if the sheet can synthesize a missing bleed margin

      • setUserBleedMargin

        public void setUserBleedMargin​(double marginInPoints)
        Sets the ideal bleed margin for this sheet, in points. The possible values and their effects are:
        marginInPoints Effect
        >  0 Include a bleed margin of this width. If the designed bleed margin is too small, missing content will be synthesized using a simple algorithm. If the designed bleed margin is larger, the extra material will be cropped off.
        =  0 Do not include a bleed margin. If there is a designed bleed margin, it will be cropped off.
        = -1 Do not include a bleed margin. If the sheet has a positive corner radius, the final sheet image will "cut" the card corners.

        The sheet will attempt to honour the requested margin. Values of 0 and -1 are always rendered exactly. In some cases where the requested size is larger than the designed bleed margin, it is not possible to synthesize a reasonable bleed margin. In such cases, the actual bleed margin will be limited to the designed bleed margin width. The true margin width can be obtained by calling getRenderedBleedMargin().

        The recommended standard margin is 9 points, as this is compatible with virtually all commercial printers.

        Parameters:
        marginInPoints - the target bleed margin in points, or -1 to inset the card edges to the boundary described by the corner radius
        See Also:
        getRenderedBleedMargin(), getBleedMargin(), getCornerRadius(), getUserBleedMargin()

      • getUserBleedMargin

        public double getUserBleedMargin()
        Returns the ideal bleed margin for this sheet, in points. Refer to setUserBleedMargin(double) for a description of the possible return values and their implications.
        Returns:
        the ideal bleed margin, or -1 for a 0 bleed margin with cut corners
        See Also:
        setUserBleedMargin(double)

      • getRenderedBleedMargin

        public double getRenderedBleedMargin()
        Returns the actual bleed margin width that will be rendered for this sheet. This may be less than the user bleed margin. The returned value is always a physical width; if the user margin is negative, this will return zero.
        Returns:
        a non-negative width in points
        See Also:
        setUserBleedMargin(double)

      • paint

        @Deprecated
public final java.awt.image.BufferedImage paint​(RenderTarget target,
                                                double resolution,
                                                boolean synthesizeBleedMargin)
        Deprecated.
        Use setUserBleedMargin(double) to set the desired bleed margin size, then call paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) to paint the image.
        Renders the sheet image, including any designed bleed margin. If there is no designed bleed margin and synthesizeBleedMargin is true, a 9 point false margin will be synthesized (if the sheet image is compatible).
        Parameters:
        target - the target hint to use for painting
        resolution - the resolution of the returned image, or -1 for the sheet's default resolution
        synthesizeBleedMargin - true to synthesize a standard bleed margin if none is included
        Returns:
        a rendered image of the sheet
        Since:
        3.0.3680

      • markChanged

        public final void markChanged()
        Marks this face as out of date. When any part of a component that is drawn by this face changes, the component must call this method to indicate that the sheet needs to be redrawn to reflect the changes.

      • hasChanged

        public final boolean hasChanged()
        Returns true if the sheet is currently marked as out of date.
        Returns:
        true if the markChanged() has been called since the last time the card was drawn

      • getGameComponent

        public final G getGameComponent()
        Returns the game component that this sheet was created for.
        Returns:
        this sheet's game component

      • isTransparent

        public boolean isTransparent()
        Returns true if the sheets for this card are transparent. The base class returns false; subclasses that want to create non-rectangular card faces must override this method. When this method returns true, the framework guarantees the following:
        1. the image buffer used for drawing will have an alpha channel (that is, it will keep track of how opaque each pixel is)
        2. the image buffer used for drawing will be completely transparent (alpha = 0) at the start of each call to paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
        Returns:
        true if the card face may contain transparent or translucent areas

      • isVariableSize

        public boolean isVariableSize()
        Returns true if the sheets created by this card can vary in size. Subclasses that wish to create variably-sized sheets must override this method to return true.

        Typically a variably-sized sheet is also transparent. When this is the case, and the sheet image has one or more edges that are completely transparent after paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) returns, then the transparent edges will be trimmed from the outside of the sheet and the size adjusted accordingly. Alternatively (or additionally), the size can be altered by replacing the template image at the start of painting.

        Returns:
        true if this card can have different sizes
        See Also:
        isTransparent(), replaceTemplateImage(java.awt.image.BufferedImage)

      • getExpansionSymbolKey

        public final java.lang.String getExpansionSymbolKey()
        Returns the name of the settings key that will be used for the default expansion painting mechanism.
        Returns:
        the key used for expansion symbol painting

      • setExpansionSymbolKey

        protected final void setExpansionSymbolKey​(java.lang.String expsymKey)
        Sets the name of the settings key that will be used by the default expansion symbol painting mechanism. Subclasses can call this during paintSheet(ca.cgjennings.apps.arkham.sheet.RenderTarget) to modify the default expansion symbol painting algorithm in response to the component state.
        Parameters:
        expsymKey - the name of the key to use for default expansion symbol painting
        See Also:
        getExpansionSymbolKey()

      • getDeckSnappingHint

        public Sheet.DeckSnappingHint getDeckSnappingHint()
        Returns a hint describing how this sheet should behave when snapped in a deck. The default is CARD, meaning that the sheet behaves like one face of a playing card.
        Returns:
        a hint describing the default behaviour of this face when it is snapped against other objects in a deck

      • getBleedMargin

        public double getBleedMargin()
        Returns the size of the bleed margin around the component edge that should be cropped off, measured in points. This bleed margin allows for slight misalignment when cutting the component from a larger sheet of paper. The bleed margin will be the same on all sides. The height and width of the component after cutting will be less than the original by twice this margin. If hasCropMarks() returns true, then the automatic crop marks will be moved toward the inside of this component by an amount equal to the bleed margin.

        The base class looks up the setting templateKey-bleed-margin to determine the bleed margin, defaulting to 0 if none is defined.

        In the example below, the actual component to be cut and kept is indicated by the blank area, while the X'd area indicates the bleed margin. Component content covers the entire area, including the bleed margin, but nothing important should appear in the bleed margin or within a distance about the same size as the bleed margin on the component interior. 

         XXXXXXXXXXXXXXXXXX
 XX              XX
 X                X
 X                X
 X     Actual     X
 X    Component   X
 X     Content    X
 X       (tm)     X
 X                X
 X                X
 X                X
 XX              XX
 XXXXXXXXXXXXXXXXXX

        By default, this method returns 0, meaning that the design includes no bleed margin. If the bleed margin is 0, Strange Eons will attempt to synthesize bleed margin graphics, with varying results. Note that Strange Eons will not synthesize a bleed margin for transparent sheet images (i.e., if isTransparent() is true).

        Returns:
        the size of the bleed margin, in points (1 point = 1/72 inch)
        See Also:
        hasCropMarks()

      • getCornerRadius

        public double getCornerRadius()
        Returns the radius that should be used to round the corners of the component, measured in points. This allows you to specify how the corners of the component will be rounded when the trimmed edge style is selected. The default is a radius of 0, meaning there is no rounding. 
         XXXXXX------
 XX   |
 X    |
 X----• = radius
 |
        Returns:
        the size of the corner radius, in points (1 point = 1/72 inch)

      • setCornerRadius

        public void setCornerRadius​(double radiusInPoints)
        Sets the corner radius used to round corners of the component, measured in points. Subclasses can use this instead of overriding getCornerRadius() and design tools can use this to help developers find the right radius for their design.
        Parameters:
        radiusInPoints - the new, non-negative radius to set

      • hasCropMarks

        public boolean hasCropMarks()
        Returns true if this sheet should have automatic crop and fold marks added when printed or placed in a deck. If this method returns true, then crop marks will be created automatically around the edges of the face; the bleed margin of these marks is determined by getRenderedBleedMargin(). In certain circumstances, some of these crop marks will be converted automatically into fold marks. Typically, this happens when the front and back face of a card are snapped next to each other such that folding along the line indicated by the crop mark would produce a complete two-sided card.

        The base class implementation returns true.

        Returns:
        true if the deck should generate crop marks

      • hasFoldMarks

        public boolean hasFoldMarks()
        Returns true if this sheet should have special fold marks added when printed.When this returns true one or more fold marks will be shown at locations determined by getFoldMarks(). This can be used to produce complex 3D components that require assembly before use.

        Note that the fold marks produced by this method are completely independent of the marks that are sometimes generated automatically from crop marks (see hasCropMarks()).

        The base class returns false.

        Returns:
        true if getFoldMarks() should be consulted for the location of special fold marks

      • getFoldMarks

        public double[] getFoldMarks()
        Returns an array that describes the extra fold marks that should appear on this face when it is placed in a deck. This method is only called if hasFoldMarks() returns true. It should return an array of double values. Each fold mark to be added by the deck is described by a sequence of four doubles in the array. The first pair is the location of a start point for the fold mark (in x, y order). The location is relative to the width and height of the face, so for example the pair (0.5, 0) would start a fold mark in the center of the top edge. The second pair is a unit vector that describes the direction that the fold mark should extend from the start point. (Recall that a unit vector is a vector of length one, that is, sqrt(x2+y2) == 1.)

        Fold marks typically come in pairs, one on each side of the face. For example, the following fold mark array would indicate the face should be folded in half along the vertical axis by placing fold marks at the centers of the top and bottom edges: 

        [0.5, 0,  0, -1,     0.5, 1,  0, 1]

        The base class returns null.

        Returns:
        an array of quadruples that describe the location and angle of additional fold marks to be drawn around the component

      • getPrintDimensions

        public PrintDimensions getPrintDimensions()
        Return the printed size of the sheet, measured in points. The returned size will account for the current bleed margin settings.

        The base class implementation is only valid for fixed-size sheets. Variable-sized sheets must override this method to return the correct size.

        Returns:
        the dimensions of the bounding rectangle of this sheet when printed

      • getTemplateKey

        public final java.lang.String getTemplateKey()
        Returns the setting key that defines the template image for this face.
        Returns:
        the template key used to initialize this face

      • getTemplateImage

        public final java.awt.image.BufferedImage getTemplateImage()
        Returns the template image; this will be the image determined by the template key unless the image was changed by calling replaceTemplateImage(java.awt.image.BufferedImage).
        Returns:
        the current template image that

      • replaceTemplateImage

        protected final void replaceTemplateImage​(java.awt.image.BufferedImage newTemplate)
        Replaces the template image for the sheet. This can be used simply to substitute a different background graphic, or, for variably-sized faces, it can be used to make the sheet larger than its original size. Replacing the template image can only be safely done within paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) before calling createGraphics() because calling it may invalidate the internal sheet image buffer.
        Parameters:
        newTemplate - the new template image
        Throws:
        java.lang.NullPointerException - if the new template is null
        See Also:
        createGraphics(java.awt.image.BufferedImage, boolean, boolean)

      • getTemplateHeight

        public int getTemplateHeight()
        Returns the height of the template image used by this sheet.
        Returns:
        the height of the template image
        See Also:
        getTemplateWidth(), getTemplateResolution()

      • getTemplateResolution

        public final double getTemplateResolution()
        Returns the base resolution of the template image, in pixels per inch (ppi). The base resolution is determined from the value of the <i>templateKey</i>-dpi key. If this key is not defined, the resolution defaults to 150 ppi. The template resolution, together with the its width and height, determine the physical size of the template image. Unless the sheet is variably-sized, this is also the physical size of the sheet as a whole.
        Returns:
        the resolution of the template image, in pixels per inch

      • getScalingFactor

        public final double getScalingFactor()
        Returns the current scaling factor; this is the ratio of the resolution the sheet is being painted at to the template resolution. If called when the sheet is not being painted, it returns the value that was used during the last paint request.
        Returns:
        the scaling factor for the painting resolution

      • getPaintingResolution

        public final double getPaintingResolution()
        Returns the resolution that the sheet is being painted at, in pixels per inch.If called when the sheet is not being painted, returns the value that was active during the last paint request.
        Returns:
        the current or most recently used resolution, in pixels per inch

      • getSuggestedUpsampleFactor

        public double getSuggestedUpsampleFactor()
        Returns a suggested scaling factor to use when previewing the image onscreen. Typically, this is equal to 1, but some components with small text size and/or small to medium template resolution will set this to a higher value to make onscreen previews more legible.
        Returns:
        a suggested multiplier for the template resolution when previewing onscreen
        See Also:
        initializeTemplate(java.lang.String), getTemplateResolution()

      • createGraphics

        public java.awt.Graphics2D createGraphics()
        Creates a graphics context that can be used to draw this sheet. The context will be scaled for the current resolution and set up appropriately for the current rendering target. This is a convenience method equivalent to calling createGraphics( null, true, true ).

        Safe only when painting

        Returns:
        a context suitable for drawing the sheet

      • createGraphics

        public java.awt.Graphics2D createGraphics​(java.awt.image.BufferedImage bufferSource,
                                          boolean scaleForResolution,
                                          boolean applyHints)
        This method creates a graphics context for drawing sheet graphics. If the bufferSource is null, then the returned graphics context will draw to this sheet's internal sheet image buffer. Alternatively, passing in a BufferedImage of your choice will create a graphics context for that image as if by calling bufferSource.createGraphics(), and then apply scaling and hints as described below. This allows you to create intermediate images as part of the rendering process.

        If scaleForResolution is true, the graphics context will be scaled so that 1 unit in the context is equal to 1 pixel in the template image. This assumes that the passed-in image has been scaled according to the upsample factor. (The internal sheet image buffer is always correctly scaled, as will an image obtained by calling createTemporaryImage(int, int, boolean).) If the context is not scaled now, it can be scaled later by calling applyContextScale(java.awt.Graphics2D).

        If applyHints is true, then the graphics context's rendering settings will be initialized for the active target as if by calling applyContextHints(java.awt.Graphics2D).

        The caller is responsible for disposing of the returned graphics context. To ensure that the context is always disposed of properly, the drawing code should be placed in a try block, and dispose() called in the finally clause, e.g.: 

         Graphics2D g = sheet.createGraphics( null, true, true );
 try {
     // paint the sheet
 } finally {
     g.dispose();
 }

        Safe only when painting

        Parameters:
        bufferSource - the image to create a context for, or null to draw on the sheet image
        scaleForResolution - if true, the context is scaled to suit the current resolution
        applyHints - if true, rendering hints suited to the current target will be applied to the context
        Returns:
        a graphics context for the requested destination, optionally scaled and hinted
        See Also:
        applyContextScale(java.awt.Graphics2D), applyContextHints(java.awt.Graphics2D)

      • getDestinationBuffer

        protected final java.awt.image.BufferedImage getDestinationBuffer()
        Returns a view of the internal sheet image buffer as a BufferedImage object. To ensure that the sheet image remains consistent, do not manipulate the pixels in this image while there is also an active graphics context on the image buffer. (Dispose of the graphics context before using the image, and create a new graphics context afterward if you wish to continue drawing.)

        Note that the returned image buffer will vary in size depending on the current drawing resolution.

        If the internal image buffer is invalid, it will be validated before this method returns.

        Safe only when painting

        Returns:
        a view of the internal buffer as an image
        See Also:
        createGraphics()

      • createTemporaryImage

        public java.awt.image.BufferedImage createTemporaryImage​(int templateWidth,
                                                         int templateHeight,
                                                         boolean includeAlphaChannel)
        Creates a new temporary image to use while painting a sheet face. This can be used to hold intermediate results while processing or to cache results to speed up future drawing. The width and height are specified relative to the template image. The dimensions of the actual image will be scaled for the current drawing resolution. (To get a suitable graphics context for the image, use createGraphics( tempImage, true, true ).) Passing 0 for either the width or height is equivalent to using getTemplateWidth() or getTemplateHeight(), respectively.

        Safe only when painting

        Parameters:
        templateWidth - the width of the area of the template image to cover, or 0 to cover the entire width
        templateHeight - the height of the area of the template image to cover, or 0 to cover the entire height
        includeAlphaChannel - if true, the temporary image will have an alpha channel (pixels can be translucent or transparent)
        Returns:
        an image that can be used to render temporary results that cover a region that is templateWidth by templateHeight pixels on the template image
        Throws:
        java.lang.IllegalArgumentException - if the given width or height is less than one

      • isCachedTemporaryImageInvalid

        public final boolean isCachedTemporaryImageInvalid()
        Returns a hint value to help manage partial rendering caches. Sophisticated sheet implementations can speed up the rendering of complex areas by rendering once to a buffer and then using this buffer to paint results on subsequent calls. This buffer can become out of date in two ways: if the relevant game component attributes change, or if the requested target or resolution change. This method tests the second condition: during a call to paint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double), if this method returns true then the target or resolution have changed since the last call.

        Safe only when painting

        Returns:
        true if the target or resolution may have changed since the last time the sheet was rendered

      • synthesizeBleedMargin

        @Deprecated
protected java.awt.image.BufferedImage synthesizeBleedMargin​(java.awt.image.BufferedImage sheetImage,
                                                             boolean synthesize,
                                                             double resolution)
        Deprecated.

      • freeCachedResources

        public void freeCachedResources()
        Releases cached resources used in sheet drawing, freeing up memory for other purposes.

      • doStandardRendererInitialization

        public static void doStandardRendererInitialization​(MarkupRenderer r)

      • setNamesForRenderer

        public static void setNamesForRenderer​(MarkupRenderer r,
                                       java.lang.String first,
                                       java.lang.String last,
                                       java.lang.String fullname)

      • drawRegionBox

        public final void drawRegionBox​(java.awt.Graphics2D g,
                                java.awt.Rectangle region)
        Draws a magenta outline of the specified rectangle if layout debugging has been enabled. If the rectangle is null or has an area of zero, a warning will be logged and nothing will be drawn.
        Parameters:
        g - the sheet graphics context to draw on
        region - the rectangle to highlight

      • drawTitle

        public void drawTitle​(java.awt.Graphics2D g,
                      java.lang.String text,
                      java.awt.Rectangle region,
                      java.awt.Font font,
                      float size,
                      int alignment)
        Draws text within a region. The text will be centered vertically in the region. The horizontal alignment is determined by the alignment parameter, which can be any of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_LEADING, or ALIGN_TRAILING. The text is drawn as a single line and it does not interpret markup tags.
        Parameters:
        g - the graphics context to use for drawing
        text - the text to draw
        region - the region to draw the text within
        font - the font to use for the text
        size - the point size to use for the text
        alignment - the horizontal alignment of the text within the rectangle

      • drawPortraitBox

        public static void drawPortraitBox​(java.awt.Graphics2D g,
                                   java.awt.geom.Rectangle2D region,
                                   Portrait portrait)
        A helper function that can be called from custom portrait painting code to draw the portrait debug box, if enabled.
        Parameters:
        g - the sheet graphics context
        region - the portrait region rectangle
        portrait - the portrait instance
        Since:
        3.3

      • drawPortraitBox

        public static void drawPortraitBox​(java.awt.Graphics2D g,
                                   java.awt.geom.Rectangle2D region,
                                   java.awt.image.BufferedImage portraitImage,
                                   double panX,
                                   double panY,
                                   double scale,
                                   double angle)
        A helper function that can be called from custom portrait painting code to draw the portrait debug box, if enabled. This version can be used by any portrait painting code, even if it does not use a Portrait instance.
        Parameters:
        g - the sheet graphics context
        region - the portrait region rectangle
        portraitImage - the image being drawn as a portrait
        panX - the horizontal offset of the image from centre
        panY - the vertical offset of the image from centre
        scale - the scale factor of the image
        angle - the rotation angle of the image, in degrees
        Since:
        3.3

      • fitTitle

        public void fitTitle​(java.awt.Graphics2D g,
                     java.lang.String text,
                     java.awt.Rectangle region,
                     java.awt.Font font,
                     float maxSize,
                     int alignment)
        Draws text within a region; if the text is wider than the region, it will be scaled down to fit. The text will be centered vertically and the horizontal alignment is determined by the alignment parameter, which can be any of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_LEADING, or ALIGN_TRAILING. The text is drawn as a single line and it does not interpret markup tags.
        Parameters:
        g - the graphics context to use for drawing
        text - the text to draw
        region - the region to draw the text within
        font - the font to use for the text
        maxSize - the point size to use for the text
        alignment - the horizontal alignment of the text within the rectangle

      • drawOutlinedTitle

        public void drawOutlinedTitle​(java.awt.Graphics2D g,
                              java.lang.String text,
                              java.awt.Rectangle region,
                              java.awt.Font font,
                              float maxSize,
                              float outlineSize,
                              java.awt.Paint textColor,
                              java.awt.Paint outlineColor,
                              int alignment,
                              boolean outlineUnderneath)
        Draws text within a region. The text is drawn as if by fitTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int), but each glyph (drawn character) will be outlined. The text is drawn as a single line and it does not interpret markup tags.
        Parameters:
        g - the graphics context to use for drawing
        text - the text to draw
        region - the region to draw the text within
        font - the font to use for the text
        maxSize - the point size to use for the text
        outlineSize - the point size to use for the outline
        textColor - the colour of the text
        outlineColor - the colour of the outline
        alignment - the horizontal alignment of the text within the rectangle
        outlineUnderneath - if true, the outline is drawn underneath the text, otherwise overtop of it

      • drawRotatedTitle

        public void drawRotatedTitle​(java.awt.Graphics2D g,
                             java.lang.String text,
                             java.awt.Rectangle region,
                             java.awt.Font font,
                             float maxSize,
                             int alignment,
                             int turns)
        Draws text within a region. The text is drawn as if by fitTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int), but the text is rotated the specified number of 90 degree anticlockwise turns. The constants ROTATE_NONE, ROTATE_LEFT, ROTATE_RIGHT, and ROTATE_UPSIDE_DOWN may also be used to specify an orientation. The text is drawn as a single line and it does not interpret markup tags. The interpretation of alignment is rotated along with the text. For example, if the text is rotated left, then a left alignment will align the text to the bottom of the region.
        Parameters:
        g - the graphics context to use for drawing
        text - the text to draw
        region - the region to draw the text within
        font - the font to use for the text
        maxSize - the point size to use for the text
        alignment - the horizontal alignment of the text within the rectangle
        turns - the number of turns to make, or one of the ROTATE constants defined in this class

      • centerTitle

        @Deprecated
public void centerTitle​(java.awt.Graphics2D g,
                        java.lang.String text,
                        java.awt.Rectangle r,
                        java.awt.Font font,
                        float size,
                        boolean embolden)
        Deprecated.
        Included for backwards compatibility with old plug-ins; use drawTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int) instead.
        Draws a title string centered within the specified rectangle.
        Parameters:
        g - the sheet graphics context to render to
        text - the title string to draw
        r - the rectangle to center the text within
        font - the font to use to draw the title
        size - the point size to draw the title at
        embolden - if true, use a bolder version of the font

      • getExpansionSymbol

        public static java.awt.image.BufferedImage getExpansionSymbol​(Expansion expansion,
                                                              java.lang.String booleanOrIntegerVariant,
                                                              int targetWidth)
        Returns the symbol to be painted on cards for an expansion. If the expansion requested is null, then null is returned.

        If the variant string is null or indicates boolean false, then the expansion's 0th symbol is returned. If it indicates boolean true, then the expansion's 1st symbol is returned. Otherwise, the string is interpreted as an integer indicating the index of the symbol to return. If the string is invalid, the 0th symbol is used. Several versions of the image registered with the Expansion may be maintained. Each such version is optimized for drawing at a certain size (in effect, each version is best for a different sheet resolution). Which version is returned will be determined by the targetWidth parameter. If possible, the returned image's width will be between targetWidth and 2 * targetWidth. Typically, you should request a target width equal to the width of the region in which the symbol is painted, multiplied by getScalingFactor().

        Parameters:
        expansion - the expansion to obtain a symbol for
        booleanOrIntegerVariant - a string describing the desired variant
        targetWidth - the desired image width, in actual pixels (i.e., not scaled for the current drawing resolution)
        Returns:
        a variant of the expansion symbol image that is optimized for targetWidth, or null
        Throws:
        java.lang.IllegalArgumentException - if the target width is not positive

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object