Class: VisualUpdate

VisualUpdate

Contains all the information related to a row update that is about to be displayed on a grid. This may happen because of a call to the AbstractWidget#updateRow method, or, in case an AbstractGrid is used to listen to a Subscription, because of an update received from Lightstreamer Server.
Specifically, for each row it supplies:
  • The current values for the row fields in the grid and in the underlying model and a method to modify the value in the gris cells before updating them on the DOM.
  • Methods to set the stylesheets to be applied to the HTML cells.
  • Methods to configure the visual effect to be applied to the HTML cells in order to emphasize the changes in the cell values.
The provided visual effect consists of the following sequence:
  • A change in the cell colors, with a fading behaviour, to temporary "hot" colors.
  • The change of the values to the new values and the change of the stylesheets to the full "hot" stylesheet; after the change, the cell stays in this "hot" phase for a while.
  • A change in the cell colors, with a fading behaviour, to the final "cold" colors.
  • The change of the stylesheets to the full "cold" stylesheets.

The class constructor, its prototype and any other properties should never be used directly.

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.
See:

Method Summary

forEachChangedField
Receives an iterator function and invokes it once per each field of the underlying model changed with the current update.
getCellValue
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.
getChangedFieldValue
Inquiry method that gets the value that is going to update the underlying model of the grid for the associated field.
setAttribute
Setter method that configures the stylesheet changes to be applied to all the HTML cells of the involved row, while changing the field values.
setCellAttribute
Setter method that configures the stylesheet changes to be applied to the HTML cell related with a specified field, while changing its value.
setCellStyle
Setter method that configures the stylesheet to be applied to the HTML cell related with a specified field, while changing its value.
setCellValue
Setter method that assigns the value to be shown in a specified cell of the grid.
setColdToHotTime
Setter method that configures the length of the color fading phase before the "hot" phase.
setHotTime
Setter method that configures the length of the "hot" phase for the current row.
setHotToColdTime
Setter method that configures the length of the color fading phase after the "hot" phase.
setStyle
Setter method that configures the stylesheets to be applied to the HTML cells of the involved row, while changing the field values.

Method Detail

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.
See:

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 Argument 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.
See:
Throws:
if no cells were associated with the specified field.
Type
IllegalArgumentException
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 Argument 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.
See:
Throws:
if no cells were associated with the specified field.
Type
IllegalArgumentException

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 Argument 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.
See:
Throws:
if no cells were associated with the specified field.
Type
IllegalArgumentException

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 Argument 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.
Type
IllegalArgumentException

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.