Constructor
new VisualUpdate()
Used by Lightstreamer to provide a value object to each call of the StaticGridListener#onVisualUpdate and DynaGridListener#onVisualUpdate events. This constructor is not supposed to be used by custom code.
Methods
forEachChangedField(iterator)
Receives an iterator function and invokes it once per each field
of the underlying model changed with the current update.
Note that in case of an event generated by the creation of a new row
all the field will be iterated.
Note that the iterator is executed before this method returns.
Note that the iterator will iterate through all of the changed fields
including fields not having associated cells. Also, even if a field is
associated with more cells it will be passed to the iterator only once.
Parameters:
| Name | Type | Description |
|---|---|---|
iterator |
ChangedFieldCallback |
Function instance that will be called once per each field changed on the current update on the internal model. |
getCellValue(field, replicaIdopt) → {String}
Inquiry method that gets the value that is going to be shown in the grid
in a specified cell or the current value if the value is not going to be
changed.
Note that if the value is not changing then no effects or styles are
going to be applied on the cell itself. If the effect is desired even if
the value in the cell is unchanged, then a call to VisualUpdate#setCellValue can
be performed using the value from this getter.
In order to inquiry the values for the row cells on the underlying
model, the VisualUpdate#getChangedFieldValue method is available.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
field |
String |
The field name associated with one of the cells in the grid (the "data-field" attribute). |
|
replicaId |
String |
<optional> |
A custom identifier that can be used in case two or more cells were defined for the same field (the "data-replica" attribute). If more cells have been defined but this parameter is not specified, then a random cell will be selected. |
Throws:
-
if no cells were associated with the specified field.
Returns:
A text or null; if the value for the specified field has never been assigned in the model, the method also returns null.
- Type
- String
getChangedFieldValue(field) → {String}
Inquiry method that gets the value that is going to update the underlying model of the grid for the associated field. It can be null if no change for the specified field is going to be applied.
Parameters:
| Name | Type | Description |
|---|---|---|
field |
String |
The name of a field from the model. |
Returns:
The new value of the specified field (possibly null), or null if the field is not changing. If the value for the specified field has never been assigned in the model, the method also returns null.
- Type
- String
setAttribute(hotValue, coldValue, attrName)
Setter method that configures the stylesheet changes to be applied
to all the HTML cells of the involved row, while changing the field values.
A temporary "hot" style can
be specified as different than the final "cold" style. This allows
Lightstreamer to perform a visual effect, in which a temporary "hot"
phase is visible. By using this method, stylesheet attributes can be
specified one at a time.
If nonzero fading times are specified, through
VisualUpdate#setColdToHotTime and/or VisualUpdate#setHotToColdTime,
then the "color" and "backgroundColor" attributes, if set, will be
changed with a fading behaviour.
Note that if color attributes are not set and nonzero fading times are
specified in VisualUpdate#setColdToHotTime and/or VisualUpdate#setHotToColdTime,
this will cause a delay of the "hot" and "cold" phase switches;
however, as fading times refer to the whole row, you may need to set
them as nonzero in order to allow fading on some specific fields only.
If a row stylesheet is set through the VisualUpdate#setStyle method,
then this method should be used only to set stylesheet properties
not set by the row stylesheet. This condition applies throughout the
whole lifecycle of the cell (i.e. manipulating the same style property
through both methods, even at different times, does not guarantee
the result).
By default for each stylesheet attribute that is not
specified neither with this method nor with VisualUpdate#setStyle, the
current value is left unchanged.
Parameters:
| Name | Type | Description |
|---|---|---|
hotValue |
String |
the temporary "hot" value for the involved attribute, or null if the attribute should not change while entering "hot" phase; an empty string causes the current attribute value to be cleared. |
coldValue |
String |
the final "cold" value for the involved attribute, or null if the attribute should not change while exiting "hot" phase; an empty string causes the "hot" phase attribute value to be cleared. |
attrName |
String |
the name of an HTML stylesheet attribute. The DOM attribute name should be used, not the CSS name (e.g. "backgroundColor" is accepted, while "background-color" is not). Note that if the "color" or "backgroundColor" attribute is being set, then several color name conventions are supported by the underlying DOM manipulation functions; however, in order to take advantage of the color fading support, only the "#RRGGBB" syntax is fully supported. |
setCellAttribute(field, hotValue, coldValue, attrName, replicaIdopt)
Setter method that configures the stylesheet changes to be applied
to the HTML cell related with a specified field, while changing its
value.
The method can be used to override, for a specific field, the settings
made through VisualUpdate#setAttribute.
If a specific stylesheet is assigned to the field through the
VisualUpdate#setStyle or VisualUpdate#setCellStyle method,
then this method can be used only in order to set stylesheet properties
not set by the assigned specific stylesheet. This condition applies
throughout the whole lifecycle of the cell (i.e. it is discouraged
to manipulate the same style property through both methods,
even at different times).
By default the settings possibly made by VisualUpdate#setAttribute
are used.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
field |
String |
The field name associated with one of the cells in the grid (the "data-field" attribute). |
|
hotValue |
String |
the temporary "hot" value for the involved attribute, or null if the attribute should not change while entering "hot" phase; an empty string causes the current attribute value to be cleared. |
|
coldValue |
String |
the final "cold" value for the involved attribute, or null if the attribute should not change while exiting "hot" phase; an empty string causes the "hot" phase attribute value to be cleared. |
|
attrName |
String |
the name of an HTML stylesheet attribute. The DOM attribute name should be used, not the CSS name (e.g. "backgroundColor" is accepted, while "background-color" is not). |
|
replicaId |
String |
<optional> |
A custom identifier that can be used in case two or more cells were defined for the same field (the "data-replica" attribute). If more cells were defined but this parameter is not specified, then a random cell will be selected. |
Throws:
-
if no cells were associated with the specified field.
setCellStyle(field, hotStyle, coldStyle, replicaIdopt)
Setter method that configures the stylesheet to be applied to the
HTML cell related with a specified field, while changing its value.
This method can be used to override, for a specific field, the settings
made through VisualUpdate#setStyle.
By default the stylesheet possibly set through VisualUpdate#setStyle
is used.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
field |
String |
The field name associated with one of the cells in the grid (the "data-field" attribute). |
|
hotStyle |
String |
the name of the temporary "hot" stylesheet, or null if the cell style should not change while entering "hot" phase (regardless of the settings made through VisualUpdate#setStyle and VisualUpdate#setAttribute). |
|
coldStyle |
String |
the name of the final "cold" stylesheet, or null if the cell style should not change while exiting "hot" phase (regardless of the settings made through VisualUpdate#setStyle and VisualUpdate#setAttribute). |
|
replicaId |
String |
<optional> |
A custom identifier that can be used in case two or more cells were defined for the same field (the "data-replica" attribute). If more cells were defined but this parameter is not specified, then a random cell will be selected. |
Throws:
-
if no cells were associated with the specified field.
setCellValue(field, value, replicaIdopt)
Setter method that assigns the value to be shown in a specified cell of
the grid.
The specified value is the text that will be actually written in the cell
(for instance, it may be a formatted version of the original value),
unless it is null, in which case the value currently shown will be kept.
The latter may still be the initial cell value (or the cell value
specified on the template) if no formatted value hasn't been supplied
for the field yet.
Note that this method does not update the internal model of the AbstractGrid
so that if a value is set through this method it can't be used
for features working on such model (e.g. it can't be used to sort the grid).
If a change to the model is required use the AbstractWidget#updateRow method.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
field |
String |
The field name associated with one of the cells in the grid (the "data-field" attribute). |
|
value |
String |
the value to be written in the cell, or null. |
|
replicaId |
String |
<optional> |
A custom identifier that can be used in case two or more cells were defined for the same field (the "data-replica" attribute). If more cells were defined but this parameter is not specified, then a random cell will be selected. |
Throws:
-
if no cells were associated with the specified field.
setColdToHotTime(val)
Setter method that configures the length of the color fading phase
before the "hot" phase. This fading phase is one of the phases of
the visual effect supplied by Lightstreamer to emphasize the change
of the row values. A 0 length means that the color switch to "hot"
colors should be instantaneous and should happen together with value
and stylesheet switch.
Warning: The fading effect, if enabled, may be computation
intensive for some client environments, when high-frequency updates
are involved.
By default 0 ms (no fading at all) is set.
Parameters:
| Name | Type | Description |
|---|---|---|
val |
Number |
Duration in milliseconds of the fading phase before the "hot" phase. |
setHotTime(val)
Setter method that configures the length of the "hot" phase for the
current row. The "hot" phase is one of the phases of the visual effect
supplied by Lightstreamer to emphasize the change of the row values.
By default 1200 ms is set.
Parameters:
| Name | Type | Description |
|---|---|---|
val |
Number |
Duration in milliseconds of the "hot" phase. |
setHotToColdTime(val)
Setter method that configures the length of the color fading phase
after the "hot" phase. This fading phase is one of the phases of
the visual effect supplied by Lightstreamer to emphasize the change
of the row values. A 0 length means that the color switch from "hot"
to final "cold" colors should be instantaneous and should happen
together with the stylesheet switch.
Warning: The fading effect, if enabled, may be very computation
intensive for some client environments, when high-frequency updates
are involved.
By default 0 ms (no fading at all) is set.
Parameters:
| Name | Type | Description |
|---|---|---|
val |
Number |
Duration in milliseconds of the fading phase after the "hot" phase. |
setStyle(hotStyle, coldStyle)
Setter method that configures the stylesheets to be applied to the
HTML cells of the involved row, while changing the field values.
A temporary "hot" style can
be specified as different than the final "cold" style. This allows
Lightstreamer to perform a visual effect, in which a temporary "hot"
phase is visible. By using this method, the names of existing
stylesheets are supplied.
Note that in order to specify cell colors that can change with
a fading behavior, the VisualUpdate#setAttribute method should be used instead,
as fading is not supported when colors are specified in the stylesheets
with this method. So, if nonzero fading times are specified in
VisualUpdate#setColdToHotTime and/or VisualUpdate#setHotToColdTime,
this will just cause a delay of the "hot" and "cold" phase switches;
however, as fading times refer to the whole row, you may need to set
them as nonzero in order to allow fading on some specific fields only.
for each stylesheet attribute that is not
specified neither with this method nor with VisualUpdate#setStyle, the
current value is left unchanged.
By default no stylesheet is applied to the cell.
Parameters:
| Name | Type | Description |
|---|---|---|
hotStyle |
String |
the name of the temporary "hot" stylesheet, or null if the cells style should not change while entering "hot" phase. |
coldStyle |
String |
the name of the final "cold" stylesheet, or null if the cells style should not change while exiting "hot" phase. |