ConditionalFormat class (Gantt)

ConditionalFormat(oConditionalFormats, oOptions)

new ConditionalFormat(oConditionalFormats, oOptions)

The ConditionalFormat object defines a conditional format. The conditional formatting feature allows you to apply formats to a cell or range of cells, and have that formatting change depending on the value of the cell or the value of a formula. The ConditionalFormat(key) method gets the conditional format by index, key or reference. The Add, Remove and Clear methods of ConditionalFormats collection update the conditional formats collection automatically.

Every option of the ConditionalFormatOptions type has associated a property of the ConditionalFormat object. For instance, the option:

expression {string}, specifies the condition of the conditional format
is associated with the property:
Expression {string}, specifies the condition of the conditional format
which means that the following statements are equivalent:
oConditionalFormat.Options = {expression: "%0 >= 0"}
oConditionalFormat.SetOptions({expression: "%0 >= 0"})
oConditionalFormat.Expression = "%0 >= 0"
oConditionalFormat.Setexpression("%0 >= 0")
where oConditionalFormat is an object of ConditionalFormat type

The ConditionalFormat type defines additional properties and methods of the ConditionalFormat(extree) type. Use the ConditionalFormat(id) method to get the conditional-format based on its index or identifier/key.

Parameters:
Name Type Description
oConditionalFormats ConditionalFormats Indicates an object of ConditionalFormats type that's the owner collection of this conditional format.
oOptions object Specifies an object of ConditionalFormatOptions type that holds information about the conditional format, such as expression, shape and so on.

Members

ApplyTo :any

The ApplyTo property indicates whether the format is applied to items or columns. The ApplyTo property is equivalent with the GetApplyTo and SetApplyTo methods. The Shape property specifies the shape to apply on items or columns that verify the condition. The Expression property of the conditional format specifies the condition to verify for the shape to be applied on items or columns. By default, the ApplyTo property is set to -1, which means that the conditional format is applied to items. Setting the ApplyTo property to 0 or a list of columns separated by comma character, applies the conditional format to columns instead of items.
Type:
  • any
Example
null{null} or -1 {number}, the format is applied to items (negative-number)
0 {number}, the format is applied to all cells of the conditional format with the index 0 that verify the condition
"C1,C2" {string}, the format is applied to all cells of the columns "C1" and "C2" that verify the condition
ApplyTo

ApplyToBars :any

The ApplyToBars property indicates the list of bars the current format is applied to, separated by comma. By default, the conditional format applies to items. However, by using the ApplyToBars and BarShape properties, you can specify both the bars the conditional format applies to and the shape used for those bars. For example, if ApplyToBars is set to "Task,Milestone", the conditional format is applied only to bars of type "Task" or "Milestone", while BarShape defines the shape displayed for those bars.
Type:
  • any
Example
null{null}, undefined{undefined} or ""{string}, the format is not applied to a bar
"Task,Milestone" {string}, the format is applied to bars of "Task" or "Milestone" type
ApplyToBars

BarShape :any

The BarShape property gets or sets the shape to apply on bars. The ApplyToBars and BarShape properties allow you to specify both the bars the conditional format applies to and the shape used for those bars. For example, if ApplyToBars is set to "Task,Milestone", the conditional format is applied only to bars of type "Task" or "Milestone", while BarShape defines the shape displayed for those bars.

The BarShape property can be any of the following:

  • {null}, no custom-shape is applied
  • the shape's name within the exontrol.BarShape.Tree or exontrol.BarShape namespace
  • a CSS color
  • a JSON string-representation of an object of exontrol.Def.BarShape type, for the column itself
  • an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.BarShape type
Type:
  • any
Example
"" {string}, null {null}, no shape is applied
"red" {string}, fills the object's background in red (CSS color)
"Button" or exontrol.BarShape.Button {object}, applies the "Button" shape on the object as defined into exontrol.BarShape namespace
BarShape

Enabled :boolean

The Enabled property enables or disables the conditional format. If the conditional format is disabled no format or shape is applied even if the condition is valid. The Enabled property is equivalent with the GetEnabled and SetEnabled methods. The Valid property checks whether the expression of the conditional format is syntactically correct, while the Enabled property specifies whether the conditional format is enabled or disabled. This allows you to create conditional formats with invalid expressions, and enable them when the expression is valid. By default, the conditional format is enabled.
Type:
  • boolean
Example
false {boolean}, disables the condition (no format or shape is applied if the condition is invalid or disabled)
true {boolean}, enables the condition
Enabled

Expression :string

The Expression property gets or sets the conditional format's expression (no format or shape is applied if the condition is invalid or disabled). The Shape property specifies the shape to apply on items or columns that verify the condition. The Expression property of the conditional format specifies the condition to verify for the shape to be applied on items or columns. By default, the ApplyTo property is set to -1, which means that the conditional format is applied to items. Setting the ApplyTo property to 0 or a list of columns separated by comma character, applies the conditional format to columns instead of items.

The conditional format's expression supports the following:

value, gets the value of the cell being formatted/evaluated
The expression supports the following variables:
%0, %1, %2, ... specifies the value of the cell in the conditional format with the index 0, 1 2, ...
%C0, %C1, %C2, ... specifies the caption of the cell, or the string the cell displays in the conditional format with the index 0, 1 2, ...
%CD0, %CD1, %CD2, ... specifies the cell's user-date in the conditional format with the index 0, 1 2, ...
%CS0, %CS1, %CS2, ... specifies the cell's state in the conditional format with the index 0, 1 2, ...
The expression supports the following functions:
index, gets the index of the item
rindex, returns the recursive-index of the item
pos, returns the relative position of the item (the position within the parent's children collection)
rpos, returns the recursive relative-position of the item (the position within the parent's children collection)
opos, returns the relative old position of the item (the position within the parent's children collection)
ropos, returns the recursive relative-old-position of the item (the position within the parent's children collection)
apos, returns the absolute position of the item (the position from the first visible item)
rapos, returns the recursive absolute-position of the item (the position from the first visible item)
The Expression property is equivalent with the GetExpression and SetExpression methods.
Type:
  • string
Example
"1" {string}, highlights all cells or items.
"%0 >= 0" {string}, highlights the cells or items, when the cells in the first conditional format have the value greater or equal with zero
"%0 startwith 'A'" {string}, highlights the cells or items, when the cells in the first column starts with A
Expression

Key :string

The Key property gets or sets the key of the conditional format. The Key property is equivalent with the GetKey and SetKey methods. The key is used to identify the conditional format and to request it from the collection by key using the ConditionalFormats.Item(key) method. If the conditional format's key is missing or empty its expression is used instead.
Type:
  • string
Example
"cond" {string}, defines the conditional format with the giving key (cond). You can use the ConditionalFormats.Item("cond") method to request the conditional format giving its key.
Key

Options :ConditionalFormatOptions

The Options property gets or sets the conditional format's options (expression, shape, ...) at once. The Options property is equivalent with the GetOptions and SetOptions methods. Every option of the ConditionalFormatOptions type has associated a property of the ConditionalFormat object. The ConditionalFormats.Add() method accepts an object of ConditionalFormatOptions type to create a new conditional format based on the specified options. For instance, the expression option of the ConditionalFormatOptions type is associated with the Expression property of the ConditionalFormat object.
Type:
Example
The following statements are equivalents:

 oConditionalFormat.SetOptions({expression: "%0 > 10", shape: "red"}), sets the conditional format's expression and shape
 oConditionalFormat.Options = {expression: "%0 > 10", shape: "red"}, sets the conditional format's expression and shape
 oConditionalFormat.Expression = "%0 > 10"; oConditionalFormat.Shape = "red";, sets the conditional format's expression and shape

where oConditionalFormat is an object of ConditionalFormat type
Options

Shape :any

The Shape property defines the shape for the conditional format itself (conditional format's header), as one of the following:
  • {null}, no custom-shape is applied
  • the shape's name within the exontrol.Shapes.Gantt or exontrol.Shapes namespace
  • a CSS color
  • a JSON string-representation of an object of exontrol.Def.Shape type
  • an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.Shape type

The Shape property is equivalent with the GetShape and SetShape methods. The Expression property specifies the condition to verify for the shape to be applied on items or columns. The Shape property specifies the shape to apply on items or columns that verify the condition. By default, no shape is applied for the conditional format itself (conditional format's header).

Type:
  • any
Example
null {null}, no custom-shape is applied
"#FF0000" {string}, applies a red color as shape
"lime" {string}, applies a lime color as shape
"Button" {string}, applies the Button shape defined within the exontrol.Shapes namespace
Shape

(readonly) Valid :boolean

The Valid property determines whether the expression is syntactically correct. The Expression property specifies the condition to verify for the shape to be applied on items or columns. The Valid property checks whether the expression of the conditional format is syntactically correct, while the Enabled property specifies whether the conditional format is enabled or disabled. This allows you to create conditional formats with invalid expressions, and enable them when the expression is valid. The Valid property is equivalent with the GetValid method.
Type:
  • boolean
Example
The following statement:

 if ( oConditionalFormat.Valid ) { ... }, checks whether the expression is syntactically correct

where oConditionalFormat is an object of ConditionalFormat type
Valid

Methods

Remove()

The Remove() method removes the conditional format itself from its collection. The Remove() method is equivalent with ConditionalFormats.Remove(oConditionalFormat) method, where oConditionalFormat is the reference to the conditional format to remove. The Remove() method can be used to remove a single conditional format by index, key or reference, while the ConditionalFormats.Clear() method can be used to remove all conditional formats of the control.
Example
oConditionalFormat.Remove(), removes the conditional format itself from its collection
Remove