Class VisualUpdateInfo

Object
   |
   +--VisualUpdateInfo

class VisualUpdateInfo

Contains all the information related to a data row that is about to be displayed in a screen table. This may happen because of a new update received or a call to VisualTable.showValues(). In these cases, a call to one of the various "onChangingValues" event handler is issued and a VisualUpdateInfo instance is supplied. Specifically, for each row it supplies:

• The current values for the row fields
• The related formatted values to be shown in the cells, that can be changed from predefined defaults
• 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

• 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

- OverwriteTable.onChangingValues()
- ScrollTable.onChangingValues()
- DynaScrollTable.onChangingValues()
- MetapushTable.onChangingValues()
- DynaMetapushTable.onChangingValues()

Constructor Detail

VisualUpdateInfo

VisualUpdateInfo()

Used by Lightstreamer to provide a value object to each call of the various "onChangingValues" event handlers.

See:
- OverwriteTable.onChangingValues()
- ScrollTable.onChangingValues()
- DynaScrollTable.onChangingValues()
- MetapushTable.onChangingValues()
- DynaMetapushTable.onChangingValues()

getFormattedValue

String getFormattedValue(<FieldDescriptor> field)

Inquiry method that gets the formatted value for a specified field. The formatted value is the text that is actually written in the cell. A null value states that the formatted value has to remain unchanged. A null value also states that the cell stylesheet has to remain unchanged and no effect should be performed at all.

Parameters:
field - a field descriptor object for the requested field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.

Returns:
A formatted text or null

See:
- setFormattedValue()

getServerValue

String getServerValue(<FieldDescriptor> field)

Inquiry method that gets the value for a specified field. If the involved row is coming from a Server update, then it is the value as received from the Server in case of a subscribed field or set in Table.onItemUpdate() in case of an extra field. If the incoming row has been supplied through a call to VisualTable.showValues(), then it is the value as supplied in that call.

Parameters:
field - a field descriptor object for the requested field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.

Returns:
A value. Null is an allowed value for a field, too; a null value is also returned for an extra field that has not been assigned.

setAttribute

void setAttribute(<FieldDescriptor> field, <String> hotValue, <String> coldValue, <String> attrName)

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 setRowAttribute().
If a specific stylesheet is assigned to the field through the setStyle() method (causing all the settings made through setRowStyle() and setRowAttribute() to be ignored), 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).

Invocation: optional.

Default value: the setting possibly made by setRowAttribute() is used, unless cancelled by calling setStyle() for the field.

Parameters:
field - a field descriptor object for the involved field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
hotValue - 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 - 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 - 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).

See:
- setRowAttribute()

setColdToHotTime

void setColdToHotTime(<Number> 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.
The fading effect is not supported by ScrollTable and MetapushTable data tables. In these cases, this setting is ignored and the switch to "hot" phase is always instantaneous.
Warning: The fading effect, if enabled, may be very computation intensive for some client environments, when high-frequency updates are involved.
Note: The fading effect requires that the client browser supports DOM level 1 functions. For other browsers, the fading phase is skipped and the value set is ignored.

Invocation: optional.

Default value: 0 ms (no fading at all).

Parameters:
val - Duration in milliseconds of the fading phase before the "hot" phase.

setFormattedValue

void setFormattedValue(<FieldDescriptor> field, <String> value)

Setter method that assigns the formatted value for a specified field. The formatted value is the text that is really written in the cell. If the formatted value is not set for a field, a default value is supplied by Lightstreamer.

Invocation: optional.

Default value:
• The field value, if the row was supplied through a call to VisualTable.showValues().
• Otherwise, the field value, if the involved item is being processed by a SCROLL or DYNASCROLL table
• Otherwise, the field value, if such value has changed with the current update (as stated by UpdateItemInfo.isValueChanged()); however, if the field value is null or unassigned (for extra fields), then a blank string is used
• Otherwise, a null value, to state that the cell content and stylesheet have to remain unchanged and no effect should be performed at all for this field.

Parameters:
field - a field descriptor object for the involved field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
value - the formatted value for the field, or null.

setHotTime

void setHotTime(<Number> 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.

Invocation: optional.

Default value: 1200 ms.

Parameters:
val - Duration in milliseconds of the "hot" phase.

setHotToColdTime

void setHotToColdTime(<Number> 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.
The fading effect is not supported by ScrollTable and MetapushTable data tables. In these cases, this setting is ignored and the switch from "hot" to "cold" phase is always instantaneous.
Warning: The fading effect, if enabled, may be very computation intensive for some client environments, when high-frequency updates are involved.
Note: The fading effect requires that the client browser supports DOM level 1 functions. For other browsers, the fading phase is skipped and the value set is ignored.

Invocation: optional.

Default value: 0 ms (no fading at all).

Parameters:
val - Duration in milliseconds of the fading phase after the "hot" phase.

setRowAttribute

void setRowAttribute(<String> hotValue, <String> coldValue, <String> attrName)

Setter method that configures the stylesheet changes 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, stylesheet attributes can be specified one at a time.
If nonzero fading times are specified, through setColdToHotTime() and/or setHotToColdTime(), then the "color" and "backgroundColor" attributes, if set, will be changed with a fading behaviour. Note: if color attributes are not set and nonzero fading times are specified in setColdToHotTime() and/or setHotToColdTime(), this will cause a delay of the "hot" and "cold" phase switches; however, as fading times refer to the whole line, 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 setRowStyle() 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).

Invocation: optional.

Default value: for each stylesheet attribute that is not specified neither with this method nor with setRowStyle(), the current value is left unchanged.

Parameters:
hotValue - 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 - 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 - 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: 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.

setRowStyle

void setRowStyle(<String> hotStyle, <String> 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.
This method can be used as an alternative to setRowAttribute(), though, if cell colors are specified in the stylesheets with this method, they are not changed with a fading behaviour. So, if nonzero fading times are specified in setColdToHotTime() and/or setHotToColdTime(), this will just cause a delay of the "hot" and "cold" phase switches; however, as fading times refer to the whole line, you may need to set them as nonzero in order to allow fading on some specific fields only.

Invocation: optional.

Default value: for each stylesheet attribute that is not specified neither with this method nor with setRowAttribute(), the current value is left unchanged.

Parameters:
hotStyle - the name of the temporary "hot" stylesheet, or null if the cells style should not change while entering "hot" phase.
coldStyle - the name of the final "cold" stylesheet, or null if the cells style should not change while exiting "hot" phase.

setStyle

void setStyle(<FieldDescriptor> field, <String> hotStyle, <String> coldStyle)

Setter method that configures the stylesheets 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 setRowStyle().
If this method is used for a field, it also cancels any settings made through setRowAttribute().

Invocation: optional.

Default value: the settings possibly made by setRowStyle() and setRowAttribute() are used.

Parameters:
field - a field descriptor object for the involved field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
hotStyle - 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 setRowStyle() and setRowAttribute()).
coldStyle - 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 setRowStyle() and setRowAttribute()).

See:
- setRowStyle()