Really the only time you use that is on MIP devices in onPartialUpdate.

When onUpdate is called, you always want to draw the entire screen.  On some devices, the entire dc is cleared before onUpdate is called.

Thank you for answering.

If I understand correctly, if my onUpdate is already every second, and I have a seconds hand, I don’t have any use for the setClip (and also for the onPartialUpdate)

onUpdate isn't called every second for a watch face on a real device.  Most of the time, it's only called every minute, but on many MIP devices, onPartialUpdate along with setting a clip region, you can update a small section of the screen to do things like showing seconds..

Here a tread I started years ago about doing is:

https://forums.garmin.com/developer/connect-iq/f/discussion/5156/1hz-watch-faces---q-a

thank you Jim, I'll read it thoroughly

To be explicit, setClip() is basically required for on onPartialUpdate() to work properly, as onPartialUpdate() has a strict limit on execution time. (By setting a clip region, you restrict which pixels the system needs to draw, which allows you to avoid exceeding the limit.)

https://developer.garmin.com/connect-iq/connect-iq-faq/how-do-i-get-my-watch-face-to-update-every-second/

How do I Make My Watch Face Update Every Second?

Since API level 2.3

Some devices support updating the watchface every second. These devices will run normal updates via the onUpdate() method at the top of each minute like other devices, but will also call the onPartialUpdate() method each second. The onPartialUpdate() method has very strict limits set on execution time, and must complete within these limits. If the execution limit is exceeded, the onPowerBudgetExceeded() method will be invoked in the WatchFaceDelegate, and partial updates will stop executing for the remainder of the app life-cycle.

Minimizing the number of pixels updated on the display during onPartialUpdate is important because refreshing the display is an expensive part of the update process. For this reason, the Connect IQ API provides a couple of useful tools: Dc.setClip()and BufferedBitmap.

The Dc.setClip() method is used to restrict the rendering window when drawing during an onPartialUpdate()callback. All pixels in the active clipping area are considered modified every time any pixel in the clip is modified.

For more complex graphics, resources can be rendered off-screen in one or more BufferedBitmap objects and copied as a single object to redraw background pixels during onPartialUpdate(). Rendering in a BufferedBitmapshould be completed during onUpdate() since it is not subject to the execution time limits as onPartialUpdate().

The Analog watch face, included in the SDK samples, is an example of a watchface that uses every second watchface updates.

module WatchUi
{
    class WatchFace extends Toybox.WatchUi.View
    {
        //! onPartialUpdate() is called each second as long as the device
        //! power budget is not exceeded.
        //! It is important to update as small of a portion of the display as possible
        //! in this method to avoid exceeding the allowed power budget. To do this, the
        //! application must set the clipping region for the Graphics.Dc object using
        //! the setClip method. Calls to Toybox.System.println() and Toybox.System.print()
        //! will not execute on devices when this function is being invoked, but can be
        //! used in the device simulator.
        //! @param [Graphics.Dc] dc The drawing context
        //! @since 2.3.0
        function onPartialUpdate(dc);
    }
}

We know you've never published a watch face, much less used this.  Why post a link and then post the text from that link at the same time?

jim_m_58 said:

We know you've never published a watch face, much less used this

That’s true but it doesn’t make the documentation any less relevant. You see through the magic of reading comprehension and critical thinking skills, people can discuss things they’ve never actually done in real life, especially fairly abstract things like software development.

If it turns out I’m wrong about something I post (which happens all the time), I’m happy to admit it.

jim_m_58 said:

Why post a link and then post the text from that link at the same time?

You see the link points the user at the source of the text (Garmin’s official CIQ documentation), and the text itself is here so the reader doesn’t have to actually click on the link. To be fair it is a lot of text.

To answer your implicit question of why I posted at all, you only implied or hinted at what the doc explicitly said about setClip() and onPartialUpdate(). I think the doc explains it fairly nicely though.

“but on many MIP devices, onPartialUpdate along with setting a clip region, you can update a small section of the screen to do things like showing seconds”

This only hints that setClip() is necessary for onPartialUpdate to work at all (i.e. it’s not just that you “can” update a small section of the screen in onPartialUpdate(), it’s that onPartialUpdate() only allows you to update a small section of the screen, due to the power budget.) For someone to be sure about that, they might have to pore through the entire thread that you linked, as useful as it is.

Even if they got the hint that onPartialUpdate() only allows you to update a small part of the screen, your comment didn’t exactly explain why (the power budget.)