This class can be used to create and update ILabels based on data items.
Remarks
These data items can be any business or arbitrary data which should be represented by labels.
LabelCreator<TDataItem> allows to conveniently bind properties of the data item to the properties of the created ILabel to control aspects like layout and styling.
In the context of the GraphBuilder, it is responsible to create the labels from the associated NodesSource<TDataItem>s and EdgesSource<TDataItem>s.
Type Parameters
- TDataItem
- The type of the data items in the source.
Type Details
- yfiles module
- view-component
- yfiles-umd modules
- All view modules
- Legacy UMD name
- yfiles.binding.LabelCreator
See Also
Constructors
Creates a new creator for labels.
Parameters
A map of options to pass to the method.
- defaults - ILabelDefaults
A set of ILabelDefaults that will be used for the labels. This option sets the defaults property on the created object.
- layoutParameter - function(TDataItem):ILabelModelParameter
An optional provider of a label model parameter that will be used as the label's layoutParameter for the source data item. This option sets the layoutParameterProvider property on the created object.
Signature Details
function(dataItem: TDataItem) : ILabelModelParameter
A callback that provides an instance of typeTValue
for the givendataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
- preferredSizeBindings - ObjectBindings<TDataItem>
An optional binding that will be applied to the label. This option sets the preferredSizeBindings property on the created object.
- preferredSize - function(TDataItem):Size
An optional provider of the size that will be used as the label's preferredSize for the source data item. This option sets the preferredSizeProvider property on the created object.
- styleBindings - ObjectBindings<TDataItem>
An optional set of bindings that will be applied to the label's style. This option sets the styleBindings property on the created object.
- style - function(TDataItem):ILabelStyle
An optional provider of an ILabelStyle instance that will be used as the label's style for the source data item. This option sets the styleProvider property on the created object.
Signature Details
function(dataItem: TDataItem) : ILabelStyle
A callback that provides an instance of typeTValue
for the givendataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
- tag - function(TDataItem):Object
An optional provider of an object that will be used as the label's tag for the source data item. This option sets the tagProvider property on the created object.
- text - function(TDataItem):string
An optional provider of the text that will be used as the label's text for the source data item. This option sets the textProvider property on the created object.
Signature Details
function(dataItem: TDataItem) : string
A callback that provides an instance of typeTValue
for the givendataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
- string
Properties
Gets or sets a set of ILabelDefaults that will be used for the labels.
Remarks
See Also
Gets or sets an optional provider of a label model parameter that will be used as the label's layoutParameter for the source data item.
Signature Details
function(dataItem: TDataItem) : ILabelModelParameter
TValue
for the given dataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
See Also
Gets or sets an optional binding that will be applied to the label.
Gets or sets an optional provider of the size that will be used as the label's preferredSize for the source data item.
Signature Details
function(dataItem: TDataItem) : Size
TValue
for the given dataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
See Also
Gets or sets an optional set of bindings that will be applied to the label's style.
Remarks
true
, the properties of the same instance are overwritten each time. To get fresh copies, set shareStyleInstance to false
.See Also
Gets or sets an optional provider of an ILabelStyle instance that will be used as the label's style for the source data item.
Remarks
Signature Details
function(dataItem: TDataItem) : ILabelStyle
TValue
for the given dataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
See Also
Gets or sets an optional provider of an object that will be used as the label's tag for the source data item.
Remarks
Signature Details
function(dataItem: TDataItem) : any
TValue
for the given dataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
- any
See Also
Gets or sets an optional provider of the text that will be used as the label's text for the source data item.
Remarks
null
or undefined
no label will be created. To force creation of an empty label the provider must return an empty string instead.Signature Details
function(dataItem: TDataItem) : string
TValue
for the given dataItem
.Parameters
- dataItem - TDataItem
- The data item for which a value shall be provided.
Returns
- string
See Also
Methods
Adds a label on the given ILabelOwner with the values of the bindings resolved against the dataItem
.
Remarks
This method will use the various helper methods in this class to determine the values for the label's properties.
If the dataItem
doesn't provide a label, this method returns null
.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The graph.
- owner - ILabelOwner
- The owner to which the label should be added.
- dataItem - TDataItem
- The data item for which to create the label.
Returns
- ↪ILabel
- The newly added label.
See Also
addLabelCore
(graph: IGraph, owner: ILabelOwner, text: string, layoutParameter: ILabelModelParameter, style: ILabelStyle, preferredSize: Size, tag: Object) : ILabelCalled from addLabel and performs the actual label creation in the graph.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The graph to create the node in.
- owner - ILabelOwner
- The owner to which the label should be added.
- text - string
- The label's text.
- layoutParameter - ILabelModelParameter
- The layout parameter of the label.
- style - ILabelStyle
- The style of the label.
- preferredSize - Size
- The preferred size of the label.
- tag - Object
- The tag of the node.
Returns
- ↪ILabel
- The newly added label.
Resolves the preferredSizeBindings against the given dataItem
and applies them to the given label
preferredSize.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label to update.
- dataItem - TDataItem
- The data item that is used.
See Also
Resolves the styleBindings against the given dataItem
and applies them to the given label
style.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label to update.
- dataItem - TDataItem
- The data item that is used.
See Also
Obtains a layoutParameter instance or null
by resolving layoutParameterProvider on the data item.
Parameters
A map of options to pass to the method.
- dataItem - TDataItem
- The data item on which the provider is resolved.
Returns
- ↪ILabelModelParameter
- The value to use or
null
in case the defaults should be used.
See Also
Obtains a preferredSize or null
by resolving the preferredSizeProvider on the data item.
Parameters
A map of options to pass to the method.
- dataItem - TDataItem
- The data item on which the provider is resolved.
Returns
- ↪Size
- The value to use or
null
in case the defaults should be used.
See Also
Obtains an ILabelStyle instance or null
by resolving the styleProvider.
Remarks
null
, the defaults are used.Parameters
A map of options to pass to the method.
- dataItem - TDataItem
- The data item on which the provider is resolved.
Returns
- ↪ILabelStyle
- The value to use or
null
in case the defaults should be used.
See Also
Obtains an object
to use as tag by resolving the tagProvider on the data item.
Remarks
Parameters
A map of options to pass to the method.
- dataItem - TDataItem
- The data item on which the provider is resolved.
Returns
- ↪any
- The value to use or
null
in case the defaults should be used.
See Also
Obtains a string
to use as text or null
by resolving the textProvider on the data item.
Parameters
A map of options to pass to the method.
- dataItem - TDataItem
- The data item on which the provider is resolved.
Returns
- ↪string
- The value to use or
null
in case no text should be added.
See Also
Resolves the layoutParameterProvider on the given data item.
Remarks
By default, it only delegates to getLayoutParameter.
This method is called by updateLayoutParameter.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label to update.
- dataItem - TDataItem
- The data item that is used.
Returns
- ↪ILabelModelParameter
- The new layout parameter instance. Either the value returned by getLayoutParameter, or the default layout parameter, if getLayoutParameter returns
null
.
Resolves the preferredSizeProvider and then applies the preferred size bindings.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label for which the size should be updated.
- dataItem - TDataItem
- The data item that is used.
Returns
- ↪Size
- Returns the label's new preferred size.
Resolves the styleProvider and then applies the style bindings.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label to update.
- dataItem - TDataItem
- The data item that is used.
Returns
- ↪ILabelStyle
- The updated style instance. Either the value returned by getStyle, or the default style, if getStyle returns
null
.
Resolves the tagProvider on the given data item.
Remarks
By default, it only delegates to getTag.
This method is called by updateLayoutParameter.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label for which the new tag should be obtained.
- dataItem - TDataItem
- The data item that is used.
Returns
- ↪any
- Returns the updated tag object.
Resolves the textProvider on the given data item.
Remarks
By default, it only delegates to getText.
This method is called by updateLayoutParameter.
Parameters
A map of options to pass to the method.
- graph - IGraph
- The managed graph.
- label - ILabel
- The label for which the new text should be obtained.
- dataItem - TDataItem
- The data item that is used.
Returns
- ↪string
- Returns the new text.
Triggers the LabelAdded event.
Triggers the LabelUpdated event.
Updates the label.
Remarks
By default, this method only fires the LabelUpdated event.
To update other aspects of the label instance, call the respective update methods when the label is updated or overwrite this method:
// configure the LabelCreators to update non-structural aspects
const labelCreator1 = nodeCreator.createLabelBinding((item) => item.name)
labelCreator1.addLabelUpdatedListener((sender, evt) => {
labelCreator1.updateText(evt.graph, evt.item, evt.dataItem)
labelCreator1.updateStyle(evt.graph, evt.item, evt.dataItem)
labelCreator1.updatePreferredSize(evt.graph, evt.item, evt.dataItem)
labelCreator1.updateLayoutParameter(evt.graph, evt.item, evt.dataItem)
labelCreator1.updateTag(evt.graph, evt.item, evt.dataItem)
})
// each LabelCreator has to be configured
const labelCreator2 = nodeCreator.createLabelBinding(
(item) => item.description
)
labelCreator2.addLabelUpdatedListener((sender, evt) => {
// only update properties which may change
labelCreator2.updateText(evt.graph, evt.item, evt.dataItem)
})
Parameters
A map of options to pass to the method.
- graph - IGraph
- The graph that contains the edge.
- label - ILabel
- The label to update.
- dataItem - TDataItem
- The data item with which the label should be updated.
Returns
- ↪boolean
true
if the label has been updated. Iffalse
the label information has been removed fromdataItem
and therefore the label will be removed, too.
See Also
Updates the layoutParameter of the label
with the given dataItem
by calling getUpdatedLayoutParameter and setting the new parameter on the label.
Updates the preferredSize of the label
with the given dataItem
by calling getUpdatedPreferredSize and setting the new size on the label.
Updates the style of the label
with the given dataItem
by calling getUpdatedStyle and applying the style to the node in the graph.
Updates the tag of the label
with the given dataItem
by calling getUpdatedTag and setting the new tag
on the label.
Updates the text of the label
with the given dataItem
by calling getUpdatedText and setting the new text on the label.
Events
Occurs when a label has been added.
See Also
Event Registration
addLabelAddedListener(function(this, GraphBuilderItemEventArgs<ILabel,TDataItem>):void)
Event Deregistration
removeLabelAddedListener(function(this, GraphBuilderItemEventArgs<ILabel,TDataItem>):void)
Signature Details
function(sender: this, evt: GraphBuilderItemEventArgs<ILabel,TDataItem>)
Parameters
- sender - this
- The source of the event.
- evt - GraphBuilderItemEventArgs<ILabel,TDataItem>
- An object that contains the event data.
Occurs when a label has been updated.
See Also
Event Registration
addLabelUpdatedListener(function(this, GraphBuilderItemEventArgs<ILabel,TDataItem>):void)
Event Deregistration
removeLabelUpdatedListener(function(this, GraphBuilderItemEventArgs<ILabel,TDataItem>):void)
Signature Details
function(sender: this, evt: GraphBuilderItemEventArgs<ILabel,TDataItem>)
Parameters
- sender - this
- The source of the event.
- evt - GraphBuilderItemEventArgs<ILabel,TDataItem>
- An object that contains the event data.