FacNavBar Methods

Scripting > CxHmiFac > FacNavBar Object > FacNavBar Methods

FacNavBar Methods

The FacNavBar object contains the following methods:

AboutBox
CanNavNext
CanNavPrev
CanSelNext
CanSelPrev
EnableAllInitialFilterRules
EnableInitialFilterRule
GetAllTargetFacTags

GetFacNavBarCustomAttribute
GetInitialFilterRuleNames
GetSelectedTargetFacTag
GetTargetFacilityAttrValues
NavNext
NavPrev
PersistRunTimeConfig
Restart

RestoreDesignTimeConfig
RestoreRunTimeConfig
SelNext
SelPrev
SelTargetFacility
SetFacNavBarCustomAttribute
Start
Stop

AboutBox

The AboutBox method displays an About dialog box for the control.

Syntax

AboutBox()

Example

The following example launches an About dialog box.

Sub

FacNavBar.X.AboutBox

End Sub

CanNavNext

The CanNavNext method specifies whether the next target item (facility or node) can be selected.

Syntax

CanNavNext(Wrap As Boolean) As Boolean

Parameters

Parameter	Required	Description
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example enables the Nav >> and << buttons if the next and previous target facilities, respectively, can be selected. This example is taken from the FacNavBar Example.

Sub UpdateUI()

eboLevels.Text = FacNavBar.X.Levels - 1

eboInitialFilter.Text = FacNavBar.X.InitialFilter

If FacNavBar.X.RuntimeCfgAutoPersist Then

ckbRTimeCfgAutoPersist.Check = 1

Else

ckbRTimeCfgAutoPersist.Check = 0

End If

btnNext.Enable = FacNavBar.X.CanSelNext(eboLevel.Text, ckbWrap.Value)

btnPrev.Enable = FacNavBar.X.CanSelPrev(eboLevel.Text, ckbWrap.Value)

btnNavNext.Enable = FacNavBar.X.CanNavNext(ckbNavWrap.Value)

btnNavPrev.Enable = FacNavBar.X.CanNavPrev(ckbNavWrap.Value)

End Sub

CanNavPrev

The CanNavPrev method specifies whether the previous target item (facility or node) can be selected.

Syntax

CanNavPrev(Wrap As Boolean) As Boolean

Parameters

Parameter	Required	Description
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example enables the Nav >> and << buttons if the next and previous target facilities, respectively, can be selected. This example is taken from the FacNavBar Example.

Sub UpdateUI()

eboLevels.Text = FacNavBar.X.Levels - 1

eboInitialFilter.Text = FacNavBar.X.InitialFilter

If FacNavBar.X.RuntimeCfgAutoPersist Then

ckbRTimeCfgAutoPersist.Check = 1

Else

ckbRTimeCfgAutoPersist.Check = 0

End If

btnNext.Enable = FacNavBar.X.CanSelNext(eboLevel.Text, ckbWrap.Value)

btnPrev.Enable = FacNavBar.X.CanSelPrev(eboLevel.Text, ckbWrap.Value)

btnNavNext.Enable = FacNavBar.X.CanNavNext(ckbNavWrap.Value)

btnNavPrev.Enable = FacNavBar.X.CanNavPrev(ckbNavWrap.Value)

End Sub

CanSelNext

The CanSelNext method returns True if the next item (facility attribute value or node) for the specified level can be selected. Otherwise returns False.

Syntax

CanSelNext(Level As Integer, Wrap As Boolean) As Boolean

Parameters

Parameter	Required	Description
Level	Yes	Specifies the level for the filter.
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example enables the Sel >> and << buttons if the next and previous facility attributes at the given level, respectively, can be selected. This example is taken from the FacNavBar Example.

Sub UpdateUI()

eboLevels.Text = FacNavBar.X.Levels - 1

eboInitialFilter.Text = FacNavBar.X.InitialFilter

If FacNavBar.X.RuntimeCfgAutoPersist Then

ckbRTimeCfgAutoPersist.Check = 1

Else

ckbRTimeCfgAutoPersist.Check = 0

End If

btnNext.Enable = FacNavBar.X.CanSelNext(eboLevel.Text, ckbWrap.Value)

btnPrev.Enable = FacNavBar.X.CanSelPrev(eboLevel.Text, ckbWrap.Value)

btnNavNext.Enable = FacNavBar.X.CanNavNext(ckbNavWrap.Value)

btnNavPrev.Enable = FacNavBar.X.CanNavPrev(ckbNavWrap.Value)

End Sub

CanSelPrev

The CanSelPrev method returns True if the previous item (facility attribute value or node) for the specified level can be selected. Otherwise returns False.

Syntax

CanSelPrev(Level As Integer, Wrap As Boolean) ) As Boolean

Parameters

Parameter	Required	Description
Level	Yes	Specifies the level for the filter.
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

Sub UpdateUI()

eboLevels.Text = FacNavBar.X.Levels - 1

eboInitialFilter.Text = FacNavBar.X.InitialFilter

If FacNavBar.X.RuntimeCfgAutoPersist Then

ckbRTimeCfgAutoPersist.Check = 1

Else

ckbRTimeCfgAutoPersist.Check = 0

End If

btnNext.Enable = FacNavBar.X.CanSelNext(eboLevel.Text, ckbWrap.Value)

btnPrev.Enable = FacNavBar.X.CanSelPrev(eboLevel.Text, ckbWrap.Value)

btnNavNext.Enable = FacNavBar.X.CanNavNext(ckbNavWrap.Value)

btnNavPrev.Enable = FacNavBar.X.CanNavPrev(ckbNavWrap.Value)

End Sub

EnableAllInitialFilterRules

The EnableAllInitialFilterRules method enables or disables all rules and vectors for the initial filter.

Syntax

EnableAllInitialFilterRules(Enable As Boolean) As Boolean

Parameters

Parameter	Required	Description
Enable	Yes	Specifies whether all rules and vectors are disabled in the initial filter.

Example

The following example enables all initial filter rules if the "Enable Initial Filter Rules" check box is checked. This example is taken from the FacNavBar Example.

Sub ckbEnableAllInitialFilterRules_EventChange()

Dim This : Set This = ckbEnableAllInitialFilterRules

If ckbEnableAllInitialFilterRules.Check <> 2 Then

FacNavBar.X.EnableAllInitialFilterRules ckbEnableAllInitialFilterRules.Check()

ListInitialFilterRules()

End If

End Sub

EnableInitialFilterRule

The EnableInitialFilterRule method enables or disables a rule or vector of rules by name for the initial filter.

Syntax

EnableInitialFilterRule(Name As String, Enable As Boolean) As Boolean

Parameters

Parameter	Required	Description
Name	Yes	Specifies the name of the rule or vector to enable or disable.
Enable	Yes	Specifies whether the rule or vector is disabled in the initial filter.

Example

The following example disables an initial filter rule when that rule is moved from the "Enabled" rules list to the "Disabled" rules list. This example is taken from the FacNavBar Example.

Sub btnDisableRule_EventClick()

Dim This : Set This = btnDisableRule

If lboEnabledRules.GetCurSel() < 0 Then

Exit Sub

End If

FacNavBar.X.EnableInitialFilterRule lboEnabledRules.GetText(lboEnabledRules.GetCurSel()), False

ListInitialFilterRules()

ckbEnableAllInitialFilterRules.Check = 2

End Sub

GetAllTargetFacTags

The GetAllTargetFacTags method returns an array of all target facility tags.

Syntax

GetAllTargetFacTags() As Variant

Example

The following example retrieves the list of target facility tags and presents each in a message box.

Sub

Dim aryTargetFacTags

aryTargetFacTags = FacNavBar.X.GetAllTargetFacTags()

Dim i

For i = 0 To UBound(aryTargetFacTags)

MsgBox aryTargetFacTags(i)

End Sub

GetFacNavBarCustomAttribute

The GetFacNavBarCustomAttribute method returns the value of a facility navigation bar custom attribute.

Syntax

GetFacNavBarCustomAttribute(AttributeNameOrDesc As String) As String

Parameters

Parameter	Required	Description
AttributeNameOrDesc	Yes	Specifies the name or description of the attribute.

Example

The following example retrieves the value for "Custom Attribute 0" and displays it in a message box.

Sub

Dim val

val = FacNavBar.X.GetFacNavBarCustomAttribute("Custom Attribute 0")

MsgBox val

End Sub

GetInitialFilterRuleNames

The GetInitialFilterRuleNames method returns the names of enabled and disabled rules for the initial filter.

Syntax

GetInitialFilterRuleNames(EnabledNames As Variant, DisabledNames As Variant)

Parameters

Parameter	Required	Description
EnabledNames	Yes	Specifies the list of enabled rule names being returned.
DisabledNames	Yes	Specifies the list of disabled rule names being returned.

Remark

This method only returns rules that have been assigned names.

Example

The following example retrieves the lists of enabled and disabled rules, and fills the list boxes accordingly. This example is taken from the FacNavBar Example.

Sub ListInitialFilterRules()

lboEnabledRules.ResetContent

lboDisabledRules.ResetContent

Dim aryEnabledRules, aryDisabledRules

FacNavBar.X.GetInitialFilterRuleNames aryEnabledRules, aryDisabledRules

Dim i

For i = 0 To UBound(aryEnabledRules)

lboEnabledRules.AddString(aryEnabledRules(i))

For i = 0 To UBound(aryDisabledRules)

lboDisabledRules.AddString(aryDisabledRules(i))

End Sub

GetSelectedTargetFacTag

The GetSelecedTargetFacTag method returns the facility tag corresponding to the target level combo box selection.

Syntax

GetSelectedTargetFacTag() As String

Example

The following example retrieves the target facility tag from the FacNavBar object and loads the Group Grid Control with UDC information. This example is taken from the FacNavBar Example.

Sub LoadGrid()

Dim arrUdcList

Dim iLowerBound

Dim iUpperBound

Dim strFacTag

Dim strUis

strUis = FacNavBar.X.SiteService

strFacTag = FacNavBar.X.GetSelectedTargetFacTag()

If strUis = "" Then

msgbox "Set the Site.Service"

Exit Sub

End If

If strFacTag = "" Then

msgbox "Invalid FacilityTag (" + strFacTag + ")"

Exit Sub

End If

Dim aryFacTag, strFacility

aryFacTag = Split(strFacTag, "::")

strFacility = aryFacTag(1)

' Get the udc list for this facility.

GetUdcList strFacTag, arrUdcList

iLowerBound = 0

iUpperBound = ubound(arrUdcList)

' Load up the grid rows/columns

Dim i, j, itemid

CxGrpGrid.x.Stop

CxGrpGrid.x.ClearRows

CxGrpGrid.x.Columns = 4

For j=0 To 3

CxGrpGrid.x.ColSiteService(j) = strUis

CxGrpGrid.x.ColFacility(j) = strFacility

CxGrpGrid.x.ColLabelText(0) = "Description"

CxGrpGrid.x.ColDisplayItem(0) = 10007

CxGrpGrid.x.ColLabelText(1) = "Value"

CxGrpGrid.x.ColDisplayItem(1) = 10001

CxGrpGrid.x.ColLabelText(2) = "Units"

CxGrpGrid.x.ColDisplayItem(2) = 10008

CxGrpGrid.x.ColLabelText(3) = "Time"

CxGrpGrid.x.ColDisplayItem(3) = 10002

For i=iLowerBound To iUpperBound

CxGrpGrid.x.RowUdc(i) = arrUdcList(i)

CxGrpGrid.x.RowLabelText(i) = CxGrpGrid.x.RowUdc(i)

CxGrpGrid.x.Start

End Sub

GetTargetFacilityAttrValues

The GetTargetFacilityAttrValues method returns the specified attribute value for all target facilities.

Syntax

GetTargetFacilityAttrValues(AttributeId As Variant) As Variant

Parameters

Parameter	Required	Description
AttributeId	Yes	Specifies the ID of the attribute.

Example

The following example retrieves the "facility_desc" attribute for all target facilities and displays the values in message boxes:

Sub

Dim aryAttrs

aryAttrs = FacNavBar.X.GetTargetFacilityAttrValues("facility_desc")

Dim i

For i = 0 To UBound(aryAttrs)

MsgBox aryAttrs(i)

End Sub

NavNext

The NavNext method navigates to the next target facility or node. Returns the number of the lowest-level combo box whose selection changed. The EventOnSelChangeLevel event is triggered when NavNext is called.

Syntax

NavNext(Wrap As Boolean) As Integer

Parameters

Parameter	Required	Description
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example navigates to the next target facility when the Nav >> button is clicked. This example is taken from the FacNavBar Example.

Sub btnNavNext_EventClick()

Dim This : Set This = btnNavNext

Dim iLevel

iLevel = FacNavBar.X.NavNext(ckbNavWrap.Value)

UpdateUI()

LoadGrid()

End Sub

NavPrev

The NavPrev method navigates to the previous target facility or node. Returns the number of the lowest-level combo box whose selection changed. The EventOnSelChangeLevel event is triggered when NavPrev is called.

Syntax

NavPrev(Wrap As Boolean) As Integer

Parameters

Parameter	Required	Description
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example navigates to the previous target facility when the Nav << button is clicked. This example is taken from the FacNavBar Example.

Sub btnNavPrev_EventClick()

Dim This : Set This = btnNavPrev

Dim iLevel

iLevel = FacNavBar.X.NavPrev(ckbNavWrap.Value)

UpdateUI

LoadGrid()

End Sub

PersistRunTimeConfig

The PersistRunTimeConfig method saves the current control configuration snapshot to the run-time registry key.

Syntax

PersistRunTimeConfig() As Boolean

Example

The following example persists the run-time configuration when the Persist Run-Time Cfg button is clicked. This example is taken from the FacNavBar Example.

Sub btnPersistRTimeCfg_EventClick()

Dim This : Set This = btnPersistRTimeCfg

FacNavBar.X.PersistRunTimeCfg

End Sub

Restart

For objects, the Restart method stops and restarts Run mode. For TheFrame/TheView, the Restart method restarts TheView with new site, service, and facility information, if applicable.

Syntax

Restart()

Example

The following example restarts Run mode.

Sub

Restart()

End Sub

RestoreDesignTimeConfig

The RestoreDesignTimeConfig method reverts the control to its design-time configuration.

Syntax

RestoreDesignTimeConfig() As Boolean

Example

The following example restores the design-time configuration when the Restore Design-Time Cfg button is clicked. This example is taken from the FacNavBar Example.

Sub btnRestoreDTimeCfg_EventClick()

Dim This : Set This = btnRestoreDTimeCfg

FacNavBar.X.RestoreDesignTimeCfg

UpdateUI()

ListInitialFilterRules()

LoadGrid()

End Sub

RestoreRunTimeConfig

The RestoreRunTimeConfig method reverts the control back to the last run-time configuration.

Syntax

RestoreRunTimeConfig() As Boolean

Example

The following example restores the run-time configuration when the Restore Run-Time Cfg button is clicked. This example is taken from the FacNavBar Example.

Sub btnRestoreRTimeCfg_EventClick()

Dim This : Set This = btnRestoreRTimeCfg

FacNavBar.X.RestoreRunTimeCfg()

UpdateUI()

ListInitialFilterRules()

LoadGrid()

End Sub

SelNext

The SelNext method selects the next item (facility attribute value or node) for the specified level. If Wrap is True, the selection wraps to the first item, if necessary. The EventOnSelChangeLevel event is triggered when SelNext is called.

Syntax

SelNext(Level As Short, Wrap As Boolean) As Boolean

Parameters

Parameter	Required	Description
Level	Yes	The level at which to select the next facility attribute value.
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example selects the next facility attribute value at the specified level when the Sel >> button is clicked. This example is taken from the FacNavBar Example.

Sub btnNext_EventClick()

Dim This : Set This = btnNext

Dim iRet

iRet = FacNavBar.X.SelNext(eboLevel.Text, ckbWrap.Value)

UpdateUI()

LoadGrid()

End Sub

SelPrev

The SelPrev method selects the previous item (facility attribute value or node) for the specified level. If Wrap is True, the selection wraps to the last item, if necessary. The EventOnSelChangeLevel event is triggered when SelPrev is called.

Syntax

SelPrev(Level As Short, Wrap As Boolean) As Boolean

Parameters

Parameter	Required	Description
Level	Yes	The level at which to select the previous facility attribute value.
Wrap	Yes	Specifies whether the control considers the list of target facilities to be wrapped (in other words, is the last item in the list considered to be the "previous" item of the first item in the list, and vice versa).

Example

The following example selects the previous facility attribute value at the specified level when the Sel << button is clicked. This example is taken from the FacNavBar Example.

Sub btnPrev_EventClick()

Dim This : Set This = btnPrev

Dim iRet

iRet = FacNavBar.X.SelPrev(eboLevel.Text, True)

UpdateUI()

LoadGrid()

End Sub

SelTargetFacility

The SelectTargetFacility method selects the item in the target combo box that corresponds to the specified facility tag.

Syntax

SelTargetFacility(FacilityTag As String) As Boolean

Parameters

Parameter	Required	Description
FacilityTag	Yes	The facility tag that corresponds to the item being selected in the target combo box.

Example

The following example selects the facility with the tag "CYGDEMO.UIS::MYFACILITY":

Sub

FacNavBar.X.SelTargetFacility("CYGDEMO.UIS::MYFACILITY")

End Sub

SetFacNavBarCustomAttribute

The SelFacNavBarCustomAttribute method sets the value of a facility navigation bar custom attribute.

Syntax

SetFacNavBarCustomAttribute(AttributeNameOrDesc As String, Value As String)

Parameters

Parameter	Required	Description
AttributeNameOrDesc	Yes	Specifies the name or description of the attribute.
Value	Yes	Specifies the value to set.

Example

The following example sets the value of custom attribute "Custom Attribute 0" to "100":

Sub

FacNavBar.X.SetFacNavBarCustomAttribute "Custom Attribute 0", "100"

End Sub

Start

The Start method configures the control and starts Run mode.

Syntax

Start()

Example

The following example starts Run mode:

Sub

Start()

End Sub

Stop

The Stop method stops Run mode.

Syntax

Stop()

Example

The following example stops Run mode:

Sub

Stop()

End Sub