Widget how-to guides

Use these guides when you know what you want to do but are not sure where the control lives. Each workflow starts from an open widget project in the editor unless it says otherwise.

Make a compact status widget

1. Open Editor and choose Widget.
2. Rename the project in the top bar.
3. Select Background in the Layers list and choose a Glance color in the inspector.
4. Keep the most important title, value, and status on the Glance.
5. Delete, hide, or resize anything that competes with the main value.
6. Choose Preview and check loading, stale, offline, empty, and error states.
7. Open design checks and fix blocking issues before building.

Start with one value and one short explanation. Add detail content only when the wearer needs more than the Glance can show.

Add a Detail page

1. Switch the surface control to Detail.
2. If the project does not have a Detail page yet, choose Add detail page.
3. Add rows, metrics, text, or charts for supporting information.
4. Keep actions near the related content.
5. Preview both Glance and Detail.

The Detail page is separate from the Glance after it is created. Changes to one surface do not automatically update the other.

Add an element

1. Choose Add element in the layer rail.
2. Browse or search the available categories.
3. Select text, icon, metric, row, chart, or an action.
4. Move and resize the layer on the canvas.
5. Use the inspector to edit content, binding, color, and position.

Action layers can only be used on the Detail page. A widget surface supports up to 12 layers.

Bind layers to shared values

1. Select a text, metric, or row layer.
2. In the inspector, choose a binding such as title, value, summary, or status.
3. Select Background and open Data.
4. Configure static, Garmin watch data, or web-service mappings for those shared values.
5. Switch scenarios to verify every bound layer updates together.

Bindings keep repeated content consistent. For example, the same status can appear as short Glance text and as a row on the Detail page.

Connect a web service

1. Select Background and open Data.
2. Set Source type to Web service.
3. Enter an HTTPS endpoint.
4. Choose GET or POST.
5. Add headers or parameters only when the widget can safely ship them.
6. Choose Test connection when the endpoint can be reached without OAuth.
7. Map response paths to title, value, summary, or status.
8. Replace all example URLs before building.

Never place passwords, private API keys, or other secrets in widget headers or parameters. They are packaged with the widget.

Configure OAuth account connection

1. Select Background and open Data.
2. Configure the web-service endpoint.
3. Open Advanced request settings.
4. Turn on Connect an account with OAuth.
5. Enter the authorization URL, redirect URL, client ID, scopes, and token result key.
6. Add an account connection action to the Detail page if the wearer needs a visible sign-in path.
7. Preview the unauthorized scenario.
8. Open design checks and resolve OAuth compatibility or placeholder URL errors.

Test connection is unavailable for OAuth endpoints because sign-in happens on the watch.

Add refresh behavior

1. Select Background and open Data.
2. Open Updates.
3. Turn on Update when opened for fresh-on-open behavior.
4. Turn on Allow manual refresh if the wearer should be able to refresh.
5. Add a visible refresh action to the Detail page when manual refresh needs a clear on-screen control.
6. For web-service widgets, enter a scheduled refresh interval from 5 to 1440 minutes if the watch supports background refresh.
7. Set saved data lifetime and request timeout.
8. Turn on offline fallback when stale data is better than an empty widget.

A non-static widget needs at least one refresh path. Studio blocks builds when data can never refresh.

Design empty and error states

1. Use the footer scenario selector or Preview controls.
2. Check Loading before data appears.
3. Check Stale and Offline for cached data.
4. Check Unauthorized for account connection copy and actions.
5. Check Empty when the service returns no useful value.
6. Check Error when the request fails.
7. Adjust bindings, fallback text, or detail content until each state explains what happened.

Short state copy is usually better than raw error language. The Glance should remain understandable even when it cannot show the desired value.

Move, resize, and align layers

1. Select a layer on the canvas or in Layers.
2. Drag it on the canvas to move it.
3. Use corner handles to resize supported layers.
4. Enter exact X, Y, width, or height values in the inspector when you need precision.
5. Turn on Grid, Snap, or Guides from the canvas controls.
6. Select multiple layers with Shift or Command/Ctrl, then move or arrange them together.
7. Lock finished layers so they do not move by accident.

Zoom changes only your working view. It does not change the final size on the watch.

Build and install a widget

1. Finish the design and fix blocking design checks.
2. Use DialStudio desktop for builds and installs.
3. Complete build setup until Studio reports Build environment ready.
4. Choose Build in the editor.
5. Review the target watch and start the build.
6. When the build finishes, choose Continue to Install, or open Projects → Builds later.
7. Connect the watch with a data-capable USB cable.
8. Choose Install on watch and keep the cable connected until Studio reports success.
9. Open the widget from the watch's widget loop or glance list.

Browser design is enough for editing and previewing. Building and USB transfer require the desktop app.