Controls - Advanced Topics

In Controls Overview, you learned the basics of each type of Content Control, and you've seen some of the settings you can change for each one to make them look just the way you want. In this chapter, we'll do a deep dive into each of the Content Controls, explaining every aspect of each one that can be customized. Nothing in this chapter is absolutely necessary - you can create a perfectly usable instance of SKipper without any of it. However, if you're going to get the most from SKipper, this chapter is required reading.

Zones

In Signal K, Zones can be defined for each Path that conveys a numeric value. Zones are part of the metadata for the Path, and look like this:

"zones": [ {"upper": 30, "state": "alarm", "message": "Critically low - shut down!"}, {"lower": 30, "upper": 50, "state": "warn", "message": "Low - investigate}, {"lower": 50, "upper": 75, "state": "normal"}, {"lower": 75, "state": "warn", "message": "High - investigate"} ]

This example is for a path like propulsion.mainEngine.oilPressure. It defines any oil pressure reading less than 30 as being an "alarm" state, with the message "Critically low - shut down!"; oil pressure between 30 and 50 as a "warn" state, with the message "Low - investigate"; between 50 and 75 as "normal", and above 75 as "warn", with the message "High - investigate".

NOTE: Setting up Zones in Signal K is beyond the scope of this SKipper documentation. Refer to the Signal K documentation, or ask about Zones in the Signal K Discord channel. When you have Zones defined for a particular path, you can then use those Zones in SKipper.

NOTE: Currently (SKipper ver. 1.0.21), each Zone must have both its upper and lower limit defined. In the above example of Zones, the first and last lines will work in Signal K, but not in SKipper. They would need to be modified like this:

Instead of:

{"upper": 30, "state": "alarm", "message": "Critically low - shut down!"}

it would need to be:

{"lower": 0, "upper": 30, "state": "alarm", "message": "Critically low - shut down!"}

where the "lower" limit is explicitly stated. So when setting up your Zones in Signal K, be sure to do this for any path you for which you want to use Zones in SKipper.

Control Details

Below, each of the types of Controls will be described in detail, including any properties about the Control that aren't obvious.

Button

A Button can be used to: - Send a PUT to a Signal K path (e.g., to turn the anchor light on or off) - Start some other program on your computer - Open any other Page in SKipper (although you would typically do that with that Page's icon on the Icon Bar) - Open any URL in a browser

The colors of a Button (text and background) can change depending on the value of a Signal K path - details below.

Here are all the Properties of a Button that are not self-explanatory:

Text

This will typically be static text that describes the purpose of the Button, such as "Anchor Light", or "Open SailorWx.com". You could, however, display the value of any Signal K path. (@Jan - need an example here.)

Icon

If you select an icon, it will appear to the left of whatever is in the Text field.

Foreground and Background Colors

By default, the colors are the same as the "Close" button that's at the bottom of the Button properties screen - white text on a blue background. You can change either one to a specific color, or you can use the value of a Signal K binding to set the color of either or both of these. For example, you could bind the background color to the path for the status of the anchor light. If the light is currently on, the color would be red, and if it's off, it would be green. (This will work only if you have Zones defined for that path, where 0 to 0 is defined as "Normal", and 1 to 1 is defined as "Alert".)

Interactivity (Click action)

Select one of the following Action Types, then complete the details:

• "exec" - provide the complete path to the executable program, and provide any commmand line arguments in the separate field.
• "put" - select the Signal K path to send the PUT to, and select what you want to send. The "Add" option will send an integer and add it to the current value of the path.
• "page" - select the SKipper Page that you want to go to.
• "openurl" - enter the url of the web page you want to open in your default browser, including the "https://" at the beginning.

ToggleButton

A ToggleButton is used to display the current value of any Signal K path that displays any form of boolean (true/false, 0/1, on/off), and toggles the value when clicked. The specific settings - many of which determine how the button will look - are detailed below (except the ones that are self-explanatory):

Value

This is the binding to the Signal K path that you want to display / control. It must be one of the boolean types (true/false, 0/1, on/off).

Style

• Button
• Switch (WARNING: don't use this in a Stack Layout - it looks horrible!)
• ToggleWithText

Each of these three styles is illustrated above. The top two buttons are the Button style, the middle two are the Switch style, and the bottom two are the ToggleWithText style. In addition, they illustrate some of the other properties of this type of Control:

Foreground and Background Colors

The middle pair of buttons above illustrates how these are used. See details in the Button section above.

Text-to-Icon Orientation

The icon can be beside the text (first and last pairs in the image above) or above it (middle pair).

Text Size

The top pair shows 40 pt. text vs. the default 25 pt. text on the other two pairs.

Active / Inactive Appearance

These are the text and icons that will be used when the button is in the Active (true / 1 / on) state, and the Inactive (false / 0 / off) state. Each of the pairs of buttons in the image above illustrates this.

Horizontal / Vertical Alignment

The default is for the button to completely fill the area allocated to it, as illustrated with the bottom two pairs in the image above. You can also have the buttons go to any corner of the area, or the center, as illustrated with the top pair.

Label

There is a good description of the Label Control here. Specific properties of the Label Control are either self-explanatory, or have been covered in the previous sections about Buttons and ToggleButtons.

TitleValue

There is a good description of the TitleValue Control here. Specific properties that are not self-explanatory or covered in the previous sections about Buttons and ToggleButtons are detailed below:

Title Alignment (Default appearance only)

If you choose the Default appearance of the TitleValue, you can determine where along the top of the Control the title will go. By default, it starts at the left side, but you can put it in the center, or send it to the right side.

Font Sizing

You can choose Auto-size, and SKipper will do its best to display the title, value, and units in appropriate sizes, with the emphasis always on the value. Or you can customize the size of all three of these fonts. The three examples in the image below illustrate (from left to right) the default sizes, Auto-sizing, and custom sizing.

The examples below also illustrate using a color for the text or the background, and using something other than the default "Stretch" for horizontal alignment.

HorizontalBar and VerticalBar

Everything you need to know about these two Controls is explained in the Controls Overview chapter.

Modern Compass

Refer to the image below to know how each bit of data is displayed on this Control:

• Course Over Ground is the blue/white "199".
• Heading is the red line at the bow of the boat, mostly obscured by the blue/white "199".
• Next Waypoint Heading is the green square partially obscured by the blue/white "199".
• Wind Speed and Heading are indicated by the dark blue/white "8.6".

Note that you can hide the Next Waypoint Heading, and the Wind information, if you don't want to see them.

Digital Gauge and Analog Gauge

The only property of these two Controls that's not obvious is "Show Zones". If you have set up Zones for the Signal K path that you're displaying, they will show on the gauge, all the time, regardless of the current value of the path. So you will always see, for example, the Normal, Alert, and Alarm ranges on the gauge, as in the image below.

Wind Gauge and Compass

Everything about these two Controls should be self-explanatory.