Detailed Description

The Toggle Button is an on/off button that can send and receive values from remote or local cdp communication objects like signals and parameters. It can also be used to send messages and toggle based on remote state values.

The following two examples shows the main usage of the button. Note that toggling is not only done by the values 0 and 1. The user can add any values/text by using the properties, cdpValueOn and cdpValueOff.

How to toggle a remote CDP object value

• All you need is the routing to the property value of the object.
• Use cdpValueOff and cdpValueOn to choose different values than 0 and 1.
• Make sure that cdpTextMsgOn and cdpTextMsgOff is not set.

How to toggle component states

• This requires that the component has at least two states and messages handlers to control it.
• Configure routing to the component CurrentState, cdpRouting = Application.FilterComponent.CurrentState
• Configure the states that are to toggle the button, cdpValueOn = On (all other states will toggle the button off).
• Configure the messages that will trigger the component to switch state, cdpTextMsgOn = TurnOn and cdpTextMsgOff = TurnOff

In CDP version 4.7, a third option was introduced. Now, the user can configure, cdpTextMsgRouting, to specify a different destination for cdpTextMsgOn and cdpTextMsgOff than the parent of the object routed in cdpRouting.

Styling by SVG

Use the svgFile property to style the widget using a svg file. Styling by svg enables switching between different themes in runtime (as long as the files are placed at identical locations within theme directories).

Main element structure

The following tree shows the svg structure that can be used on the CDPBaseToggleButton.

svg
└─── Layer1
      ├─── cdpTextOn                  (text)
      ├─── cdpTextOff                 (text)
      ├─── cdpBorderMarginTopLeft     (transparent rect/path)
      ├─── cdpBorderMarginBottomRight (transparent rect/path)
      ├─── cdpButton                  (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpButtonOff               (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpButtonDisabled          (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpButtonOffDisabled       (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpBackground              (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpBackgroundOff           (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      ├─── cdpBackgroundDisabled      (element group)
      │     ├─── < Path >             (transparent rect/path)
      │     └─── < Group >            (actual graphics)
      └─── cdpBackgroundOffDisabled   (element group)
            ├─── < Path >             (transparent rect/path)
            └─── < Group >            (actual graphics)

The following table explains the named elements in more detail.

Note: Elements that are written with pointy brackets, like < Path >, can be given any name. Avoid cdp prefix as these are special to the parser.

Note: Skipping both cdpButtonDisabled and cdpBackgroundDisabled will trigger opacity in the disabled state. It is also possible to force the opacity to any level using the property named disabledStateOpacity.

Style element structure

The toggle button also supports styles that can be changed by the widgetStyle property or by cdp signal/object. Styles makes it possible to change colors and shape of button, background and texts.

svg
├─── Layer1
│      └─── ...                  (see previous section)
└─── Styles
        ├─── cdpTextOnStyleX     (text)
        ├─── cdpTextOffStyleX    (text)
        ├─── cdpButtonStyleX     (element group)
        │       ├─── < Path >    (transparent rect/path)
        │       └─── < Group >   (button graphics)
        └─── cdpBackgroundStyleX (element group)
                ├─── < Path >    (transparent rect/path)
                └─── < Group >   (actual graphics)

How to handle round designs

The toggle button allows border margins by default as this will make the widget scalable to any size while maintaining its corner radius. On rounded designs, however, this is not always what we want. To enable buttons to be circular with a round knob, we might need to turn off border margins by setting the property named, allowBorderMargins to false. This is often used in combination with the minimumSize and maximumSize properties to tweak the button into looking good.