markup
markupBox( sheet, [genderAware] )
markupBox( ppi, [genderAware] )
MarkupBox
MarkupBox( ppi ) constructor
MarkupBox.draw( g, region )
MarkupBox Constants
MarkupBox.setStyleForTag( tagName, style )
MarkupBox.getStyleForTag( tagName )
MarkupBox.setParametricStyleForTag( tagName, factory )
MarkupBox.getParametricStyleForTag( tagName )
MarkupBox.setReplacementForTag( tagName, replacement )
MarkupBox.getReplacementForTag( tagName )
MarkupBox.removeTag( tagName )
MarkupBox.removeAllTags()
MarkupBox.setDefaultStyle( style )
MarkupBox.getDefaultStyle()
MarkupBox.setAlignment( alignment )
MarkupBox.getAlignment()
MarkupBox.setHeadlineAlignment( alignment )
MarkupBox.getHeadlineAlignment()
MarkupBox.setTabWidth( tabWidthInInches )
MarkupBox.getTabWidth()
MarkupBox.setTabWidths( tabWidthsInInches[] )
MarkupBox.getTabWidths()
MarkupBox.setTextFitting( fittingStyle )
MarkupBox.getTextFitting()
MarkupBox.setScalingLimit( factor )
MarkupBox.getScalingLimit()
MarkupBox.setLineTightness( tightness )
MarkupBox.getLineTightness()
MarkupBox.setTightnessLimit( minTightness )
MarkupBox.getTightnessLimit()
MarkupBox.setPageShape( shape )
MarkupBox.getPageShape()
MarkupBox.setMarkupText( markup )
MarkupBox.getMarkupText()
MarkupBox.parseLibrary( libraryString )
MarkupBox.draw( g, region )
MarkupBox.drawAsSingleLine( g, region )
MarkupBox.measure( g, region )
GenderMarkupBox : MarkupBox
GenderMarkupBox.setGender( useRightSideText )
GenderMarkupBox.getGender()
updateNameTags( markupbox, gameComponent )
TextStyle
TextStyle() constructor
TextStyle( key1, value1, [key2, value2, ...] ) constructor
TextStyle.add( key1, value1, [key2, value2, ...] )
TextStyle.add( textStyle )
TextStyle.get( key )
TextStyle.remove( key )
Style Attributes
FAMILY
WEIGHT
WIDTH
POSTURE
SIZE
SUPERSCRIPT
COLOUR (or COLOR)
BGCOLOUR (or BGCOLOR)
UNDERLINE
STRIKETHROUGH
SWAP_COLOURS (or SWAP_COLORS)
LIGATURES
TRACKING
PageShape class
PageShape.getLeftInset( y1, y2 )
PageShape.getRightInset( y1, y2 )
PageShape.debugDraw( g, rect )
PageShape.RECTANGLE_SHAPE
PageShape.InsetShape class
PageShape.InsetShape( leftInset, rightInset ) constructor
PageShape.CupShape class
PageShape.CupShape( i1, i2, y, i3, i4 ) constructor
PageShape.CompoundShape class
PageShape.CompoundShape( topShape, y, bottomShape ) constructor
PageShape.MergedShape class
PageShape.MergedShape( shape1, shape2 ) constructor
PageShape.GeometricShape( outline ) constructor
Creates a new markup renderer that can lay out text marked up with
Strange Eons tags. The renderer will be set up for use with
sheet, a DIY card face object.
| sheet | a character sheet object, such as that passed to DIY.createFrontPainter() |
| genderAware | if true a GenderMarkupBox is returned |
Creates a new markup renderer. The renderer will be set up for rendering
at a resolution of dpi pixels per inch.
| ppi | the rendering resolution in pixels per inch |
| genderAware | if true a GenderMarkupBox is returned |
An object capable of laying out styled text by parsing plain text that is
marked up with HTML-like tags.
To create an object of this class, it is normally recommended that you use
the markupBox( sheet ) function, which will set the correct
resolution and define standard tags.
Note: Because it is based on a Java class, you may use the JavaScript engine's
getter/setter syntax with a MarkupBox. For example, instead of
box.setDefaultStyle( style ); you can write
box.defaultStyle = style;
This constructor creates a default markup renderer which draws at the
specified resolution.
Rather than using a constructor, MarkupBoxes are usually created
indirectly with the markupBox( sheet ) helper function.
| ppi | the assumed resolution for drawing, in pixels per inch |
Lays out and draws the current markup text within the specified region.
Returns the y-coordinate where the next line of text would start.
| g | the graphics context to use for drawing |
| region | the area in which to draw text; this may be a Region or a java.awt.geom.Rectangle2D |
| FIT_NONE | do not try to fit text that is too long to fit in the given region |
| FIT_SCALE_TEXT | fit long text by shrinking it down |
| FIT_TIGHTEN_LINE_SPACING | fit long text by reducing line spacing |
| FIT_BOTH | fit text by shrinking it and reducing the space between lines |
| LAYOUT_LEFT | left-align lines of text |
| LAYOUT_CENTER | center lines of text |
| LAYOUT_RIGHT | right-align lines of text |
| LAYOUT_TOP | vertically align text to the top of the region |
| LAYOUT_MIDDLE | vertically center text within the region |
| LAYOUT_BOTTOM | vertically align text to the bottom of the region |
| LAYOUT_JUSTIFY | lines will be justified to fit the width of the region |
Sets the style associated with a non-parametric tag.
If a style was set previously for this tag, it will be replaced by the new
style. If a replacement was associated with this tag, the replacement will be removed.
Do not include the angle brackets in the tag name.
For example:
var style = new TextStyle( WEIGHT, WEIGHT_LIGHT );
box.setStyleForTag( "light", style );
| tagName | the name of the tag pair (<tagName> ... </tagName>) |
| style | the TextStyle to be applied for this pair |
Returns the TextStyle associated with the tag, or null if the tag does not
have a non-parametric style set (including if it has a replacement or
parametric style set).
| tagName | the name of the tag (without angle brackets) to fetch the style of |
Returns the style for the requested tag, or null if it has no,
or a different kind, of definition.
Sets a parameter-based style for the given tag. When this tag occurs in the
markup text, the factory will be used to create the actual style based on
the tag's parameters. This is an advanced feature.
The factory argument is an object that implements the interface
ca.cgjennings.layout.ParametricStyleFactory. This interface consists
of a single method:
TextStyle createStyle( java.lang.String[] parameters )
| tagName | the name of the tag (without angle brackets) to set the factory for |
| factory | a ParametricStyleFactory to be used to generate styles for this tag |
Returns the ParametricStyleFactory associated with the tag,
or null if the tag does not have a style set (including if it has
a replacement or style set).
| tagName | the name of the tag (without angle brackets) to get the factory for |
Returns the factory for the requested tag, or null if it has no,
or a different kind, of definition.
Sets a replacement string to be associated with a particular tag.
When this exact tag (not including angle brackets) occurs in the markup text,
it will be replaced by the replacement string.
For example:
box.setReplacementForTag( "copyright", "©" );
| tagName | the name of the replacement tag |
| replacement | the text to replace the tag with |
Returns the replacement String associated with the tag, or null
if the tag does not have a replacement set (including if it has a style
or parametric style set).
| tagName | the name of the tag to return the replacement string for |
Returns the replacement string for the tag, or null if it has no,
or a different kind, of definition.
Removes any style or replacement associated with this tag.
| tagName | the name of the tag to be undefined |
Removes all style and replacement definitions.
Sets the base style that is applied to text when no other tags affect it.
| style | the TextStyle that is applied to all text by default |
Returns the default style, which is the style that is applied to text when
no other tags are in effect. By modifying this style you can control what
"normal" text looks like.
For example:
box.defaultStyle = new TextStyle(
FAMILY, bodyFamily,
SIZE, 7,
WEIGHT, WEIGHT_BOLD
);
You can also modify the default style instead of replacing it. The following
changes just the size without affecting other attributes:
box.defaultStyle.add( SIZE, 10 );
| style | the TextStyle that is applied to all text by default |
Sets the horizontal and vertical alignment of text within a drawn rectangle.
This is the logical or of one of LAYOUT_LEFT, LAYOUT_RIGHT,
or LAYOUT_CENTER with one of LAYOUT_TOP, LAYOUT_BOTTOM,
or LAYOUT_MIDDLE. In addition, if the LAYOUT_JUSTIFY bit
is set, then paragraphs will be fully justified so that they fill the
entire region width.
For example:
box.alignment = LAYOUT_CENTER | LAYOUT_TOP | LAYOUT_JUSTIFY;
| alignment | a bitmask of alignment options |
Returns the alignment bitmask that describes how text is laid out within
a drawn rectangle.
For example:
if( (box.alignment & LAYOUT_LEFT) != 0 ) println( "left-aligned text" );
Returns the current alignment value.
Sets the horizontal alignment used for text in headline tags (<h1>,
<h2>, and so on). This is similar to setAlignment(),
but only the horizontal alignment value is used.
| alignment | a horizontal alignment option |
Returns the current horizontal alignment setting for heading tags.
Sets the distance, in inches, between tab stops.
| tabWidthInInches | the default gap between tab stops |
Returns the default distance, in inches, between tab stops.
If multiple stops have been set, this returns the first tab width.
It is equivalent to getTabWidths()[0].
Sets the distance, in inches, between tab stops.
This method accepts multiple tab positions as an array, which sets a
series of variable-width tab stops instead of a fixed tab size.
| tabWidthsInInches[] | the default gap between tab stops |
Returns an array of tab widths, in inches. If only one stop has been set,
perhaps using setTabWidth, then the length of the array is 1.
Sets the fitting methods that will be used to shrink text that is too long
to fit in the text region. One of FIT_NONE,
FIT_TIGHTEN_LINE_SPACING, FIT_SCALE_TEXT, or FIT_BOTH.
Returns the current text fitting method.
Sets the limit for shrinking text so that it can be scaled down to no more
than factor * 100% of original size.
Returns the current scaling limit for text shrinking.
Sets how tightly lines are grouped together. For normal line spacing, use
1.0; double-spaced lines would be 2.0. Values less than 1 reduce the standard
amount of space between lines; at 0 the bottom of one line will normally touch
or overlap the top of the next. The exact effect of this setting depends somewhat
on the font being used.
| tightness | the tightness of interline spacing (normally 1.0) |
Returns the current line tightness.
Sets the minimum line tightness that can be used when line spacing is reduced
to fit long text.
| minTightness | the smallest amount that line tightness can be reduced to when fitting text |
Returns the current line tightness limit.
Sets the PageShape that lines of text will conform to.
A PageShape is used to flow text around other elements of a component.
The default shape is PageShape.RECTANGLE_SHAPE, which simply uses the
sides of the region passed to the draw method.
| shape | the desired PageShape |
Returns the PageShape that will be used to shape lines of text.
Sets the markup text that will be used when laying out text.
Returns the current markup text that will be used when laying out text.
Processes a markup string, retaining only any definitions that are created
using <define> tags. Once some markup text (other than a library)
is parsed, all definitions will be cleared again.
Therefore, libraries must be parsed again before each call to
setMarkupText.
This method clears the current markup text.
| libraryString | a string containing markup definitions (like a case book library) |
Lays out and draws the current markup text within the specified region.
Returns the y-coordinate where the next line of text would be drawn.
| g | the graphics context to use for drawing |
| region | the area in which to draw text; this may be a Region or a java.awt.geom.Rectangle2D |
Lays out and draws the current markup text within the specified region.
The renderer will not insert line breaks into the text at the end of a line,
but will instead shrink the text as needed to fit the line within the width
of the given region. (If the source text contains hard line breaks then the
resulting layout will still consist of multiple lines, but only the width
of the last line will be used to determine the scale of the text.)
Returns the width of the last line.
| g | the graphics context to use for drawing |
| region | the area in which to draw text; this may be a Region or a java.awt.geom.Rectangle2D |
Lays out the current markup text without drawing it, returning the height
of the text.
| g | the graphics context to use for drawing |
| region | the area in which to lay out the ; this may be a Region or a java.awt.geom.Rectangle2D |
A GenderMarkupBox is a subclass of MarkupBox
that includes a boolean "gender" attribute. Tags that include a slash
in the middle (<like/this>) will be converted into the text before
the slash (if gender is false) or into the text after the slash (if gender
is true). This allows you to use markup that is sensitive to some binary
property, like a character's gender: <His/Her> monkey bit
<him/her>. Since tags are closed with tag names that start with
a slash, a dash is used to indicate an empty string (as in
prophet<-/ess>).
Sets the markup box's gender, which controls which text from slash
divided gender tags will be used.
| useRightSideText | if true, the text after the slash is used |
Returns the markup box's current gender. If true, the text
after the slash is used for tags that include a slash.
Updates a MarkupBox's <name> family of tags using
a component's current name. Call this at the start of your painting function
before drawing a box's text if you want name tags to work properly. This
function sets all of the name tags (<name>,
<lastname>, <fullname>) based simply on the
component's standard name. For more complete control, use
sheet.setNamesForRenderer( markupbox, firstName, lastName, fullName ).
| markupbox | the MarkupBox to update |
| gameComponent | the component (such as a DIY instance) to extract a name from |
A TextStyle consists of one or more style attributes that can be
applied to text. Style attributes consist of a style key and an appropriate
value. If an attribute is added to a text style and the style already contains
an attribute with the same key, the new attribute replaces the old one.
(For example, if you add a new font family attribute to a style, it replaces the old
family, although other attributes such as size and weight would remain the same.)
This constructor creates a new, empty style.
This constructor creates a text style that combines the listed style attributes.
| key1, value1, ... | pairs of text attribute keys and values |
Merges the listed style attributes into this text style.
| key1, value1, ... | pairs of text attribute keys and values |
Merges the style represented by textStyle into this text style.
| textStyle | a model TextStyle style whose settings will be copied into this style |
Returns the value for the given style attribute key that will be set by this
style, or null if it does not modify that attribute.
Removes the style attribute with this key from this text style.
Following are the style attribute keys (and the permitted values) that can
be set on a text style.
The value of this attribute is a string that names the font family to be used.
The following "standard family names" are defined for convenience:
| FAMILY_BODY | the standard Strange Eons body text font, if the core fonts library is installed (and otherwise a stand-in font) |
| FAMILY_SERIF | a default serif family |
| FAMILY_SANS_SERIF | a default sans-serif family |
| FAMILY_MONOSPACED | a default monospace family |
The value of this attribute controls the weight of text. Not all weights
may have visible effect. The following standard weights are defined
(medium is the "normal" weight):
WEIGHT_EXTRALIGHT
WEIGHT_LIGHT
WEIGHT_DEMILIGHT
WEIGHT_REGULAR
WEIGHT_SEMIBOLD
WEIGHT_MEDIUM
WEIGHT_DEMIBOLD
WEIGHT_BOLD
WEIGHT_HEAVY
WEIGHT_EXTRABOLD
WEIGHT_ULTRABOLD
Note: The correctness of this attribute relies
on underlying support from the platform and JRE. Some weights may have no
effect. (The regular and bold weights should always be available.)
The value of this attribute controls the width of text. The following
standard widths are defined (regular is the "normal" width):
WIDTH_CONDENSED
WIDTH_SEMICONDENSED
WIDTH_REGULAR
WIDTH_SEMIEXTENDED
WIDTH_EXTENDED
The value of this attribute controls the posture of text.
The following standard postures are defined
(regular is the "normal" posture, oblique is the standard
italic posture):
POSTURE_REGULAR
POSTURE_OBLIQUE
The value of this attribute is a number that controls the point size of text.
The absolute value of this attribute is a number that specifies the number of levels
of superscripting or subscripting that are in effect (normally 0, positive
values specify superscripting, negative values specify subscripting). The
following standard values are defined:
| SUPERSCRIPT_SUPER | one level of superscript |
| SUPERSCRIPT_SUB | one level of subscript |
A java.awt.Paint object that controls the text colour.
A java.awt.Paint object that controls the background colour
of text.
This attribute's value controls text underlining. The standard value
UNDERLINE_ON is defined.
This attribute's value controls text strikethrough. The standard value
STRIKETHROUGH_ON is defined.
This attribute's value controls whether the foreground and background colours
are swapped. The standard value
SWAP_COLOURS_ON is defined.
This attribute's value controls whether automatic ligature replacement is
enabled. The standard value LIGATURES_ON is defined.
The value of this attribute is a number that controls tracking (spacing between
letters). A value of 0 provides standard letter spacing. Positive values
increase the space between letters, while negative values move them closer
together. The following standard values are defined:
| TRACKING_TIGHT | provide tighter (i.e., closer together) than normal tracking |
| TRACKING_LOOSE | provide looser than normal tracking |
Shapes the left and right margins of drawn text.
A shape is defined in terms of insets relative to the original margins.
A MarkupBox will query the PageShape with a range of Y-positions
covered by a line of text, and the shape must return the narrowest (largest)
inset within that range.
Positive inset values always reduce the margins; negative values increase
them. A zero inset leaves the margin unchanged.
To create a new shape, subclass PageShape and override
getLeftInset and getRightInset. Optionally, you can
also override debugDraw to draw lines indicating how the margins
have changed. If you do not override this method, then no margin lines
(dashed blue lines) will be drawn when the Show Regions plug-in is
activated.
In addition to creating your own shapes, a number of predefined shapes
are also available to handle common cases.
Returns the narrowest (maximum) left edge inset between y1 and y2.
When calling this method, the condition y1 <= y2 must hold.
| y1 | the top Y-coordinate in the range |
| y2 | the bottom Y-coordinate in the range |
Returns the narrowest (maximum) right edge inset between y1 and y2.
When calling this method, the condition y1 <= y2 must hold.
| y1 | the top Y-coordinate in the range |
| y2 | the bottom Y-coordinate in the range |
Called when a markup box is drawn and Show Regions is activated.
This method should draw lines or curves to indicate the shape visually.
The passed-in graphics context will already have been initialized with
an appropriate stroke, paint, and transform.
| g | a Graphicsa2D instance that has been initialized with an appropriate scale and style |
| rect | the text drawing region to use to draw the margins for |
A shared immutable instance of a PageShape that defines the default
shape for text: insets are always 0, so text conforms to the region passed
to draw.
A PageShape that modifies that standard margin by a constant
amount for all Y-positions. This is often useful when creating a
CompoundShape.
Creates a new PageShape.InsetShape with constant margin insets
defined by leftMargin and rightMargin.
| leftMargin | the number of units to offset the left edge of the text region |
| rightMargin | the number of units to offset the right edge of the text region |
A PageShape that is optimized for the most common case:
a rectangle that becomes wider or narrower after a certain y-point
is reached, e.g.:
i1 i2 i1 i2
+--------+ +------+
| | | |
| | or | |
+--+ +--+ y +--+ | y
| | | |
+--+ +---------+
i3 i4 i3 i4 (same as i2)
Creates a new PageShape.CupShape that switches from insets
i1, i2 to i3, i4 at Y-position y.
| i1 | the left inset to use in the top part of the shape |
| i2 | the right inset to use in the top part of the shape |
| y | the Y-coordinate at which the insets switch from top to bottom |
| i3 | the left inset to use in the bottom part of the shape |
| i4 | the right inset to use in the bottom part of the shape |
A PageShape that switches between two PageShapes
at a specified Y-position. This may be used to build more complex shapes
from simpler ones. Either or both of the shapes may themselves
be CompoundShapes.
The following example uses a compound shape to create a "plus" or
"double cup" shape, that is, a cup shape that flows around decorations
in up to four corners (as opposed to PageShape.CupShape, which
handles no more than two:
new PageShape.CompoundShape(
new PageShape.CupShape( i1, i2, y1, 0, 0 ),
y2,
new PageShape.InsetShape( i3, i4 )
);
Creates a new PageShape.CompoundShape that uses topShape
until the Y-position y is reached, then switches to bottomShape.
| topShape | the shape to use until y is reached |
| y | the Y-position at which to switch shapes |
| bottomShape | the shape to use after y is reached |
A shape that merges two source shapes into a single shape.
The resulting shape always uses the narrowest margin
of the two source shapes at any given Y-position.
For example, to ensure that a shape never has a negative
inset (which lets text escape from the drawing region),
merge it with PageShape.RECTANGLE_SHAPE.
Creates a new PageShape.MergedShape that merges
shape1 and shape2 into a single shape.
| shape1 | a PageShape |
| shape2 | a second PageShape to be combined with shape1 |
A PageShape that redefines margins to match a shape used for
drawing (that is, a
java.awt.Shape).
This allows you to fit margins to an arbitrary polygon, an ellipse, etc. The
margins at a given Y point will be adjusted to touch the leftmost and
rightmost points on the shape at that Y position. If needed, the shape must
be transformed so that it intersects the text drawing region prior to
creating the PageShape. Creating a GeometricShape is a
fairly expensive operation, especially compared to other PageShapes.
It is recommended that you create them ahead of time and reuse them where
possible, instead of creating them on the fly in your painting code.
| outline | a Shape that defines an outline to create a PageShape from |
Contents