Field layouts intro: What are they and how to use them?

TheHuff said:

What are field layouts?

They're the user-selectable data page layouts available for built-in activities on Garmin watches, such as Run or Bike. Connect IQ data fields can only be added to built-in activities, and any field [Connect IQ or built-in] that is added to a data page will be constrained to draw within the bounds of its own section of the data page layout.

Here's an example of a 6 field data page layout on a real Forerunner 955:

www.dcrainmaker.com/.../garmin-forerunner-solar-review.html

Each field in this picture has its own little section of the screen, and that's what meant/described by a "data page layout" or "field layout".

The field layouts in the device reference let devs know what data page layouts the user is able to select for a given device, so they can design their CIQ data field apps accordingly.

As a matter of fact, some Connect IQ data fields only work properly in a 1 field layout (where the data field is able to draw on the full screen), for various reasons:

- the data field is designed only to draw on the full screen because it draws logical fields of its own. This was especially true when most Garmin devices were only limited to a max of 4 fields per page, which opened the door for Connect IQ data field apps to draw many more fields/metrics of their own in a 1 field layout. One example is the CIQ app Dozen Run, which draws 12 metrics at once.

- the data field is designed only to draw on the full screen because it draws something else that requires all of that real estate, like graphs / charts.

[This pattern was so prevalent at one point that one of the Garmin support articles on CIQ data fields instructs users to select a 1-field layout, although not all CIQ data fields require this layout or even work best in this layout.]

Other CIQ data fields are able to dynamically adapt to the layout that the user chooses. For example, the Stryd Zones app displays several metrics when it's installed in a 1-field [full-screen] layout, but when it's a much smaller field in a multi-field layout, it only displays 1 metric.

And some CIQ data fields display very simple data which works ok in any layout (but which is probably not best suited for 1-field layout, due to the amount of wasted space.)

TheHuff said:

what the fields in the columns mean (Obscure left, right) etc. 

Logically speaking, every field in a given layout is rectangular, but on Garmin watches with a non-rectangular bezel, one or more field edges may be partially obscured by the physical bezel.

The obscure left/right/top/bottom flags refer to which edges of a given field in a specific layout are obscured by the bezel.

https://developer.garmin.com/connect-iq/api-docs/Toybox/WatchUi/DataField.html#getObscurityFlags-instance_function

Non-rectangular screens have certain portions of the screen obscured. For example, a round screen effectively cuts off the corners of a square screen

To be clear:

When a CIQ data field app runs, it doesn't have direct knowledge of its position in the layout.

- the dc's logical x/y coordinates and width/height only refer to its own section of the layout (you can tell if it's a 1-field layout by the fact that the dc width/height is the same as the screen width/height though.)

- getObscurityFlags() lets the app know which edges of the field are not fully visible (obscured by the physical bezel), and in *some* cases, can allow the app to guess which layout is active, and which part of the layout the field belongs to. (This is not a reliable method of doing so, though. It seems intentional that Garmin doesn't want data fields to rely on the knowledge of their exact position in the layout, as CIQ does not provide this information)