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.
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',
ExteriorNodeLabelModel.BOTTOM,
new LabelStyle(),
)
graph.addLabel(
node2,
'With borders',
ExteriorNodeLabelModel.BOTTOM,
new LabelStyle({
backgroundStroke: 'darkslategray',
backgroundFill: 'lightgray',
shape: 'rectangle',
padding: [0, 2],
}),
)
graph.addLabel(
node3,
'Longer texts can be wrapped automatically',
ExteriorNodeLabelModel.BOTTOM,
new LabelStyle({
backgroundStroke: 'darkgoldenrod',
backgroundFill: 'white',
shape: 'rectangle',
padding: [0, 2],
verticalTextAlignment: 'center',
horizontalTextAlignment: 'center',
}),
new Size(80, 80),
)Type Details
- yFiles module
- view
See Also
Constructors
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.
- 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.
- renderer - ILabelStyleRenderer
- 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.
- padding - Insets
- The padding for the label. This option sets the padding 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.
Remarks
true.Property Value
true if the label should be flipped automatically, otherwise false.See Also
Gets or sets the brush to use for the background box of the label.
Remarks
null.Property Value
null.See Also
Gets or sets the pen to use for the background box of the label.
Remarks
null.Property Value
null.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 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 StretchNodeLabelModel.
The default value is INFINITE.
Property Value
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 StretchNodeLabelModel.
The default value is ZERO.
Property Value
See Also
Gets or sets the padding for the label.
Remarks
The padding defines the distance between the label border and the label content.
The default value is EMPTY.
Property Value
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 padding 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 padding 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 padding or textWrappingPadding can result in less wide labels.
The default value is RECTANGLE.
See Also
Gets or sets the size of the text.
Remarks
This property delegates to the size of the font property.
The default value is 12.0d.
Property Value
See Also
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 LabelStyle({
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 padding determines areas that should not be rendered into. The padding has an influence on the size and positioning of the shape, whereas the margins are overlaid.
Note: For wrapping shapes other than RECTANGLE it is recommended to adjust the style's padding 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 padding 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 StretchNodeLabelModel 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 LabelStyle({
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.
Property Value
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 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 >=1d.
The default value is 1d.