A basic label style which renders the label's text and optionally a background and border.
Remarks
The style allows for setting text color, font, font size and font style. It also provides various text alignments and wrapping options.
This style uses a DefaultLabelStyleRenderer to create its visualization.
An optional background can be rendered. Different shapes, colors, and borders are supported.
Examples
const node1 = graph.createNode(new Rect(0, 0, 40, 40))
const node2 = graph.createNode(new Rect(100, 0, 40, 40))
const node3 = graph.createNode(new Rect(200, 0, 40, 40))
graph.addLabel(
node1,
'Text only',
ExteriorLabelModel.SOUTH,
new DefaultLabelStyle()
)
graph.addLabel(
node2,
'With borders',
ExteriorLabelModel.SOUTH,
new DefaultLabelStyle({
backgroundStroke: 'darkslategray',
backgroundFill: 'lightgray',
shape: 'rectangle',
insets: [0, 2]
})
)
graph.addLabel(
node3,
'Longer texts can be wrapped automatically',
ExteriorLabelModel.SOUTH,
new DefaultLabelStyle({
backgroundStroke: 'darkgoldenrod',
backgroundFill: 'white',
shape: 'rectangle',
insets: [0, 2],
verticalTextAlignment: 'center',
horizontalTextAlignment: 'center'
}),
new Size(80, 80)
)Type Details
- yfiles module
- view-component
- yfiles-umd modules
- All view modules
- Legacy UMD name
- yfiles.styles.DefaultLabelStyle
See Also
Constructors
Creates a new instance using DefaultLabelStyleRenderer as renderer.
Parameters
A map of options to pass to the method.
- backgroundFill - Fill
The brush to use for the background box of the label. This option sets the backgroundFill property on the created object.
- verticalTextAlignment - VerticalTextAlignment
The vertical text alignment to use if the label is assigned more space than needed. This option sets the verticalTextAlignment property on the created object.
- horizontalTextAlignment - HorizontalTextAlignment
The text alignment. This option sets the horizontalTextAlignment property on the created object.
- wrapping - TextWrapping
The text wrapping and trimming behavior. This option sets the wrapping property on the created object.
- clipText - boolean
A value that determines whether text should be clipped. This option sets the clipText property on the created object.
- backgroundStroke - Stroke
The pen to use for the background box of the label. This option sets the backgroundStroke property on the created object.
- shape - LabelShape
The shape of the label's background. This option sets the shape property on the created object.
- textWrappingShape - TextWrappingShape
The shape the label text shall be wrapped in when rendered. This option sets the textWrappingShape property on the created object.
- textWrappingPadding - number
The padding between the wrapped text and the textWrappingShape. This option sets the textWrappingPadding property on the created object.
- cssClass - string
A CSS class that will be applied to the visualization. This option sets the cssClass property on the created object.
- font - Font
The typeface to use for the label. This option sets the font property on the created object.
- autoFlip - boolean
A value indicating whether the label should be flipped 180 degrees automatically, if it would be oriented downwards, otherwise. This option sets the autoFlip property on the created object.
- textFill - Fill
The brush to use for the label's text. This option sets the textFill property on the created object.
- textSize - number
The size of the text. This option sets the textSize property on the created object.
- insets - Insets
The insets for the label. This option sets the insets property on the created object.
- minimumSize - Size
The minimum preferred size allowed for the label. This option sets the minimumSize property on the created object.
- maximumSize - Size
The maximum preferred size allowed for the label. This option sets the maximumSize property on the created object.
Creates a new instance using the provided renderer.
Parameters
A map of options to pass to the method.
- renderer - ILabelStyleRenderer
- The custom renderer for this style instance.
- backgroundFill - Fill
The brush to use for the background box of the label. This option sets the backgroundFill property on the created object.
- verticalTextAlignment - VerticalTextAlignment
The vertical text alignment to use if the label is assigned more space than needed. This option sets the verticalTextAlignment property on the created object.
- horizontalTextAlignment - HorizontalTextAlignment
The text alignment. This option sets the horizontalTextAlignment property on the created object.
- wrapping - TextWrapping
The text wrapping and trimming behavior. This option sets the wrapping property on the created object.
- clipText - boolean
A value that determines whether text should be clipped. This option sets the clipText property on the created object.
- backgroundStroke - Stroke
The pen to use for the background box of the label. This option sets the backgroundStroke property on the created object.
- shape - LabelShape
The shape of the label's background. This option sets the shape property on the created object.
- textWrappingShape - TextWrappingShape
The shape the label text shall be wrapped in when rendered. This option sets the textWrappingShape property on the created object.
- textWrappingPadding - number
The padding between the wrapped text and the textWrappingShape. This option sets the textWrappingPadding property on the created object.
- cssClass - string
A CSS class that will be applied to the visualization. This option sets the cssClass property on the created object.
- font - Font
The typeface to use for the label. This option sets the font property on the created object.
- autoFlip - boolean
A value indicating whether the label should be flipped 180 degrees automatically, if it would be oriented downwards, otherwise. This option sets the autoFlip property on the created object.
- textFill - Fill
The brush to use for the label's text. This option sets the textFill property on the created object.
- textSize - number
The size of the text. This option sets the textSize property on the created object.
- insets - Insets
The insets for the label. This option sets the insets property on the created object.
- minimumSize - Size
The minimum preferred size allowed for the label. This option sets the minimumSize property on the created object.
- maximumSize - Size
The maximum preferred size allowed for the label. This option sets the maximumSize property on the created object.
Properties
Gets or sets a value indicating whether the label should be flipped 180 degrees automatically, if it would be oriented downwards, otherwise.
Gets or sets the brush to use for the background box of the label.
Gets or sets the pen to use for the background box of the label.
Gets or sets a value that determines whether text should be clipped.
Remarks
If set to true, the label text will be clipped at the label's bounds.
Clipping is be done after trimming and wrapping the text. Disabling this feature will not prevent trimming or wrapping from removing text.
The default value is true.
See Also
Gets or sets a CSS class that will be applied to the visualization.
Remarks
The default value is an empty string, in which case no class is set for the visualization.
Multiple classes can be set by separating them with spaces, just like with the SVG class attribute.
Note that adjusting the visualization of graph items with CSS works purely on a DOM level. Therefore, CSS properties that affect the text size of labels should be avoided, since they are not considered for text measuring and therefore might result in wrong text placement. Only CSS properties that affect `visual` aspects of the label's style should be used.
See Also
Gets or sets the text alignment.
Gets or sets the insets for the label.
Remarks
The insets define the distance between the label border and the label content.
The default value is EMPTY.
See Also
Gets or sets the maximum preferred size allowed for the label.
Remarks
If wrapping is enabled and the text exceeds the maximum width allowed, then the text is wrapped.
This property only changes the preferred size calculated by getPreferredSize and thus has no effect for ILabelModels that ignore the preferred size, such as InteriorStretchLabelModel.
The default value is INFINITE.
See Also
Gets or sets the minimum preferred size allowed for the label.
Remarks
This property only changes the preferred size calculated by getPreferredSize and thus has no effect for ILabelModels that ignore the preferred size, such as InteriorStretchLabelModel.
The default value is ZERO.
See Also
Gets the renderer implementation that can be queried for implementations that provide details about the visual appearance and visual behavior for a given label and this style instance.
Remarks
const creator = style.renderer.getVisualCreator(label, style)
const visual = creator.createVisual(context)Implements
Gets or sets the shape of the label's background.
Remarks
Since ROUND_RECTANGLE uses a fixed corner radius, setting a constant value for insets works well for different label text sizes. Because the size of the end caps of PILL and HEXAGON depend on the height of the text, the preferred size of a label that uses these shapes is automatically increased to produce labels that can contain the complete text and where the text does not intersect with the shape of the label when a backgroundStroke is used to render the background. Using non-zero insets for the longer side of the label allows the style to place the text rendering inside the end caps, so increasing the top and bottom insets or textWrappingPadding can result in less wide labels.
The default value is RECTANGLE.
See Also
Gets or sets the size of the text.
Gets or sets the padding between the wrapped text and the textWrappingShape.
Remarks
Examples
// Wrap text in an elliptic shape with a small padding
const labelStyle = new DefaultLabelStyle({
textWrappingShape: 'ellipse',
textWrappingPadding: 5
})See Also
Gets or sets the shape the label text shall be wrapped in when rendered.
Remarks
The shape is fitted inside the label layout and text is wrapped to stay inside the shape. If a padding is set, this padding is kept between the shape and the text.
Also insets determine areas that should not be rendered into. The padding has an influence on the size and positioning of the shape, whereas the insets are overlaid.
Note: For wrapping shapes other than RECTANGLE it is recommended to adjust the style's insets and textWrappingPadding, too. Also, the preferredSize needs to be set to a suitable value to get the desired effect or a respective ILabelModel needs to be used that provides a suitable label layout.
If the value is set to RECTANGLE or wrapping is set to NONE, the preferred size calculation will take into account the extra space that is required by a label shape of PILL or HEXAGON to completely render the text contents within the outline of the shape. In the case of ROUND_RECTANGLE suitable constant insets value can be configure to prevent the text from intersecting with the rounded corners.
For the cases where the value is set to other values, the calculation of the preferred size will be unaffected by the shape. This will typically lead to preferred sizes that cannot ensure that the text content is rendered within the outline. Since these values are typically used for rendering larger amounts of text that needs to wrap within a shape, a preferred size is either not required or not feasible to determine unambiguously. So developers need to either come up with and manually set an adjusted preferred size that suits the users or let the users determine the size of the label rendering, interactively. The latter can be done by letting the user interactively change the preferred size or by using a label model that does not even consider the preferred size, like the InteriorStretchLabelModel with CENTER parameter which derives the size of the label from the size of the owning node.
For the majority of use-cases where label texts are only a few lines or likely a single line of text or even word, you probably want to be using the RECTANGLE which has good support for accurate preferred size calculations that lead to compact labels even with the non-rectangular label background shapes. More sophisticated label wrapping shapes are mostly meant to be used without a label background and shape but are rendered on top of another node or graph element that has its own corresponding shape and where the label is stretched across the element.
Note that values other than RECTANGLE are only considered if wrapping is not NONE.
The default value is RECTANGLE.
Examples
// Wrap text in an elliptic shape with a small padding
const labelStyle = new DefaultLabelStyle({
textWrappingShape: 'ellipse',
textWrappingPadding: 5
})See Also
Gets or sets the vertical text alignment to use if the label is assigned more space than needed.
Gets or sets the text wrapping and trimming behavior.
Methods
Create a clone of this object.
Default Properties
Gets or sets a value that is added to the preferred width and height of the label.
Remarks
When storing a graph on one platform and loading it on another one with a slightly different font rendering implementation or font, it often happens that text gets truncated because the preferred size is just one or two pixels too small on that platform. This can be avoided by slightly enlarging the labels on the platform where the graph is stored.
Values should be >=0d.
The default value is 0d.
Gets or sets a value that multiplies the preferred width and height of the label.
Remarks
When storing a graph on one platform and loading it on another one with a slightly different font rendering implementation or font, it often happens that text gets truncated because the preferredSize is just one or two pixels too small on that platform. This can be avoided by slightly enlarging the labels on the platform where the graph is stored.
Values should be >=1d.
The default value is 1d.