Class Sheet<G extends GameComponent>
- java.lang.Object
-
- ca.cgjennings.apps.arkham.sheet.Sheet<G>
-
- Type Parameters:
G
- the type of component for which this is a sheet
- Direct Known Subclasses:
DIYSheet
,MarkerSheet
,UndecoratedCardBack
public abstract class Sheet<G extends GameComponent> extends java.lang.Object
An abstract base class for objects that paint one face (side) of aGameComponent
.Subclasses must provide a template key before the sheet can be used. This is normally provided during construction, but sheets with more complex initialization may delay this step and callinitializeTemplate
later to set the key.Sheets maintain an internal image buffer that is used when painting. This buffer is only guaranteed to be valid while the face is being painted, and then only after you call either
createGraphics
to get a graphics context for the image buffer, orgetDestinationBuffer
to access it as aBufferedImage
.This class provides a number of helper methods for drawing tasks that are commonly needed when drawing components, such as drawing text within rectangular regions of the face null (
drawTitle
,fitTitle
drawOutlinedTitle
,drawRotatedTitle
), performing custom handling of expansion symbols (getExpansionSymbol
,parseExpansionList
), and setting up markup text boxes null (doStandardRendererInitialization
,setNamesForRenderer
).- Author:
- Chris Jennings
-
-
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.
-
Field Summary
Fields Modifier and Type Field Description static int
ALIGN_CENTER
Constant for center alignment of text when using the drawing helper methods.static int
ALIGN_LEADING
Constant for alignment of text to normal reading order: left if the game language is written left-to-right, and right otherwise.static int
ALIGN_LEFT
Constant for left alignment of text when using the drawing helper methods.static int
ALIGN_RIGHT
Constant for right alignment of text when using the drawing helper methods.static int
ALIGN_TRAILING
Constant for alignment of text to reverse reading order: right if the game language is written left-to-right, and left otherwise.static boolean
DEBUG_BLEED_MARGIN
static boolean
DEBUG_PORTRAIT_REGION
static boolean
DEBUG_UNSAFE_AREA
static java.lang.String
ON_PAINT_EVENT_METHOD
The name of the function called in an on-paint script.static int
ROTATE_LEFT
Constant to rotate text 90 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.static int
ROTATE_NONE
Constant to rotate text 0 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.static int
ROTATE_RIGHT
Constant to rotate text 270 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.static int
ROTATE_UPSIDE_DOWN
Constant to rotate text 180 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.
-
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 thetemplateKey
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; usedrawTitle(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 aBufferedImage
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 callingreplaceTemplateImage(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()
Returnstrue
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()
Returnstrue
if this sheet should have special fold marks added when printed.When this returnstrue
one or more fold marks will be shown at locations determined bygetFoldMarks()
.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()
Returnstrue
if the sheets for this card are transparent.boolean
isVariableSize()
Returnstrue
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.UsesetUserBleedMargin(double)
to set the desired bleed margin size, then callpaint(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()
-
-
-
Field Detail
-
ON_PAINT_EVENT_METHOD
public static final java.lang.String ON_PAINT_EVENT_METHOD
The name of the function called in an on-paint script. If the game component associated with this sheet has a setting key whose name equals the value ofScriptMonkey.ON_PAINT_EVENT_KEY
, then the value of that key will be executed as script code and then the function with this name ("onPaint") will be called. The function is passed a graphics context for the sheet image buffer, a reference to the game component, and a reference to this sheet.- See Also:
- Constant Field Values
-
DEBUG_BLEED_MARGIN
public static boolean DEBUG_BLEED_MARGIN
-
DEBUG_UNSAFE_AREA
public static boolean DEBUG_UNSAFE_AREA
-
DEBUG_PORTRAIT_REGION
public static boolean DEBUG_PORTRAIT_REGION
-
ALIGN_LEFT
public static final int ALIGN_LEFT
Constant for left alignment of text when using the drawing helper methods.- See Also:
- Constant Field Values
-
ALIGN_CENTER
public static final int ALIGN_CENTER
Constant for center alignment of text when using the drawing helper methods.- See Also:
- Constant Field Values
-
ALIGN_RIGHT
public static final int ALIGN_RIGHT
Constant for right alignment of text when using the drawing helper methods.- See Also:
- Constant Field Values
-
ALIGN_LEADING
public static final int ALIGN_LEADING
Constant for alignment of text to normal reading order: left if the game language is written left-to-right, and right otherwise.
-
ALIGN_TRAILING
public static final int ALIGN_TRAILING
Constant for alignment of text to reverse reading order: right if the game language is written left-to-right, and left otherwise.
-
ROTATE_NONE
public static final int ROTATE_NONE
Constant to rotate text 0 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.- See Also:
- Constant Field Values
-
ROTATE_LEFT
public static final int ROTATE_LEFT
Constant to rotate text 90 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.- See Also:
- Constant Field Values
-
ROTATE_UPSIDE_DOWN
public static final int ROTATE_UPSIDE_DOWN
Constant to rotate text 180 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.- See Also:
- Constant Field Values
-
ROTATE_RIGHT
public static final int ROTATE_RIGHT
Constant to rotate text 270 degrees when drawn withdrawRotatedTitle(java.awt.Graphics2D, java.lang.String, java.awt.Rectangle, java.awt.Font, float, int, int)
.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Sheet
public Sheet(G gameComponent)
Creates a component face for a game component. Concrete subclasses must callinitializeTemplate(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 thetemplateKey
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 fortemplateKey
- 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:
- The
Settings
of the game component associated with this sheet are fetched to look up the keys below. - The template image is loaded using templateKey.
- If templateKey ends with
-template
, this is removed. - The default region for drawing expansion symbols, if any, is read
from templateKey
-expsym-region
. - 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.) - 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. - The initial corner radius is set from
templateKey
-corner-radius
; if undefined the default is 0. See alsogetBleedMargin()
.
- Parameters:
templateKey
- the base key name to use to initialize the template for this sheet- Throws:
java.lang.NullPointerException
- if the template key isnull
- The
-
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 fromgetTemplateKey()
template
- the template image for the sheetexpansionSymbolKey
- the key to check for an expansion symbol region for default expansion symbol paintingresolution
- the resolution of the template image, in pixels per inchupsampleFactor
- the upsample factor that determines the default resolution- Throws:
java.lang.NullPointerException
- if the template or expansion symbol key is nulljava.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 returnsnull
. (The base class returnsnull
.)- 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 bygetSuggestedUpsampleFactor()
.- Parameters:
target
- the target hint to use for paintingresolution
- 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 isnull
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 imagetarget
- a target describing the general quality and purposeresolution
- 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 tosetUserBleedMargin(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.UsesetUserBleedMargin(double)
to set the desired bleed margin size, then callpaint(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 andsynthesizeBleedMargin
is true, a 9 point false margin will be synthesized (if the sheet image is compatible).- Parameters:
target
- the target hint to use for paintingresolution
- the resolution of the returned image, or -1 for the sheet's default resolutionsynthesizeBleedMargin
- 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()
Returnstrue
if the sheet is currently marked as out of date.- Returns:
true
if themarkChanged()
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()
Returnstrue
if the sheets for this card are transparent. The base class returnsfalse
; subclasses that want to create non-rectangular card faces must override this method. When this method returnstrue
, the framework guarantees the following:- the image buffer used for drawing will have an alpha channel (that is, it will keep track of how opaque each pixel is)
- 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()
Returnstrue
if the sheets created by this card can vary in size. Subclasses that wish to create variably-sized sheets must override this method to returntrue
.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 duringpaintSheet(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 isCARD
, 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. IfhasCropMarks()
returnstrue
, 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 overridinggetCornerRadius()
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 returnstrue
, then crop marks will be created automatically around the edges of the face; the bleed margin of these marks is determined bygetRenderedBleedMargin()
. 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()
Returnstrue
if this sheet should have special fold marks added when printed.When this returnstrue
one or more fold marks will be shown at locations determined bygetFoldMarks()
. 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 ifhasFoldMarks()
returnstrue
. 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 callingreplaceTemplateImage(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 withinpaint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
before callingcreateGraphics()
because calling it may invalidate the internal sheet image buffer.- Parameters:
newTemplate
- the new template image- Throws:
java.lang.NullPointerException
- if the new template isnull
- See Also:
createGraphics(java.awt.image.BufferedImage, boolean, boolean)
-
getTemplateWidth
public int getTemplateWidth()
Returns the width of the template image used by this sheet.- Returns:
- the width of the template image
- See Also:
getTemplateHeight()
,getTemplateResolution()
-
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 callingcreateGraphics( 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 thebufferSource
isnull
, then the returned graphics context will draw to this sheet's internal sheet image buffer. Alternatively, passing in aBufferedImage
of your choice will create a graphics context for that image as if by callingbufferSource.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
istrue
, 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 callingcreateTemporaryImage(int, int, boolean)
.) If the context is not scaled now, it can be scaled later by callingapplyContextScale(java.awt.Graphics2D)
.If
applyHints
istrue
, then the graphics context's rendering settings will be initialized for the active target as if by callingapplyContextHints(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, anddispose()
called in thefinally
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, ornull
to draw on the sheet imagescaleForResolution
- iftrue
, the context is scaled to suit the current resolutionapplyHints
- iftrue
, 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)
-
applyContextHints
protected void applyContextHints(java.awt.Graphics2D g)
Prepares a graphics context to render a sheet by setting up the context's rendering hints. The specific hints set depend on the current rendering target.When implementing
paintSheet(ca.cgjennings.apps.arkham.sheet.RenderTarget)
, subclasses may wish to perform some setup operations with different rendering settings before the main drawing process begins. In such cases, perform the initial drawing steps before calling this method. Otherwise, call this method at the start of drawing. Subclasses may also wish to override this method to customize hinting; the base class simply callsRenderTarget.applyTo(java.awt.Graphics2D)
.Safe only when painting
- Parameters:
g
- the graphics context to modify- See Also:
createGraphics(java.awt.image.BufferedImage, boolean, boolean)
,createTemporaryImage(int, int, boolean)
-
applyContextScale
protected void applyContextScale(java.awt.Graphics2D g)
Scales a graphics context to reflect the requested drawing resolution.Safe only when painting
- Parameters:
g
- the context to scale- See Also:
createGraphics(java.awt.image.BufferedImage, boolean, boolean)
-
getDestinationBuffer
protected final java.awt.image.BufferedImage getDestinationBuffer()
Returns a view of the internal sheet image buffer as aBufferedImage
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, usecreateGraphics( tempImage, true, true )
.) Passing 0 for either the width or height is equivalent to usinggetTemplateWidth()
orgetTemplateHeight()
, respectively.Safe only when painting
- Parameters:
templateWidth
- the width of the area of the template image to cover, or 0 to cover the entire widthtemplateHeight
- the height of the area of the template image to cover, or 0 to cover the entire heightincludeAlphaChannel
- iftrue
, 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
bytemplateHeight
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 topaint(ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
, if this method returnstrue
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
-
paintSheet
protected abstract void paintSheet(RenderTarget target)
Paints the content of this sheet. This method will be called by the framework whenever the sheet needs to be redrawn.A typical procedure to set up for painting is to call
createGraphics()
to get a graphics context for the sheet's internal image buffer. The returned context will be scaled so that 1 unit in the graphics context is equal to 1 pixel in the template image, and the context will be configured appropriately for the current rendering target. In some cases you may wish to perform these steps in stages, in which case you can usecreateGraphics(java.awt.image.BufferedImage, boolean, boolean)
,applyContextHints(java.awt.Graphics2D)
andapplyContextScale(java.awt.Graphics2D)
.- Parameters:
target
- the rendering target
-
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 isnull
or has an area of zero, a warning will be logged and nothing will be drawn.- Parameters:
g
- the sheet graphics context to draw onregion
- 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 ofALIGN_LEFT
,ALIGN_CENTER
,ALIGN_RIGHT
,ALIGN_LEADING
, orALIGN_TRAILING
. The text is drawn as a single line and it does not interpret markup tags.- Parameters:
g
- the graphics context to use for drawingtext
- the text to drawregion
- the region to draw the text withinfont
- the font to use for the textsize
- the point size to use for the textalignment
- 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 contextregion
- the portrait region rectangleportrait
- 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 aPortrait
instance.- Parameters:
g
- the sheet graphics contextregion
- the portrait region rectangleportraitImage
- the image being drawn as a portraitpanX
- the horizontal offset of the image from centrepanY
- the vertical offset of the image from centrescale
- the scale factor of the imageangle
- 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 ofALIGN_LEFT
,ALIGN_CENTER
,ALIGN_RIGHT
,ALIGN_LEADING
, orALIGN_TRAILING
. The text is drawn as a single line and it does not interpret markup tags.- Parameters:
g
- the graphics context to use for drawingtext
- the text to drawregion
- the region to draw the text withinfont
- the font to use for the textmaxSize
- the point size to use for the textalignment
- 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 byfitTitle(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 drawingtext
- the text to drawregion
- the region to draw the text withinfont
- the font to use for the textmaxSize
- the point size to use for the textoutlineSize
- the point size to use for the outlinetextColor
- the colour of the textoutlineColor
- the colour of the outlinealignment
- the horizontal alignment of the text within the rectangleoutlineUnderneath
- iftrue
, 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 byfitTitle(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 constantsROTATE_NONE
,ROTATE_LEFT
,ROTATE_RIGHT
, andROTATE_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 drawingtext
- the text to drawregion
- the region to draw the text withinfont
- the font to use for the textmaxSize
- the point size to use for the textalignment
- the horizontal alignment of the text within the rectangleturns
- the number of turns to make, or one of theROTATE
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; usedrawTitle(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 totext
- the title string to drawr
- the rectangle to center the text withinfont
- the font to use to draw the titlesize
- the point size to draw the title atembolden
- iftrue
, 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 isnull
, thennull
is returned.If the variant string is
null
or indicates booleanfalse
, then the expansion's 0th symbol is returned. If it indicates booleantrue
, 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 theExpansion
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 thetargetWidth
parameter. If possible, the returned image's width will be betweentargetWidth
and2 * targetWidth
. Typically, you should request a target width equal to the width of the region in which the symbol is painted, multiplied bygetScalingFactor()
.- Parameters:
expansion
- the expansion to obtain a symbol forbooleanOrIntegerVariant
- a string describing the desired varianttargetWidth
- 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
, ornull
- Throws:
java.lang.IllegalArgumentException
- if the target width is not positive
-
parseExpansionList
public 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. Any undefined expansions will appear asnull
values in the array. If settingValue is null or empty, this method returns null.- Parameters:
settingValue
- the setting value to parse- Returns:
- an array of the expansions listed by settingValue
- See Also:
Expansion.getComponentExpansionSymbols(ca.cgjennings.apps.arkham.component.GameComponent)
,Settings.getExpansionCode()
,Settings.getExpansionVariant(ca.cgjennings.apps.arkham.sheet.Sheet)
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-