Import the pebble dev site into devsite/

devsite/source/_guides/events-and-services/buttons.md

@@ -0,0 +1,214 @@
+---
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+title: Buttons
+description: |
+  How to react to button presses in your app.
+guide_group: events-and-services
+order: 2
+related_docs:
+  - Clicks
+  - ClickHandler
+related_examples:
+  - title: App Font Browser
+    url: https://github.com/pebble-examples/app-font-browser/blob/master/src/app_font_browser.c#L168
+---
+
+Button [`Clicks`](``Clicks``) are the primary input method on Pebble. All Pebble
+watches come with the same buttons available, shown in the diagram below for
+Pebble Time:
+
+![button-layout](/images/guides/sensors-and-input/button-layout.png)
+
+These buttons are used in a logical fashion throughout the system:
+
+* Back - Navigates back one ``Window`` until the watchface is reached.
+
+* Up - Navigates to the previous item in a list, or opens the past timeline when
+  pressed from the watchface.
+
+* Select - Opens the app launcher from the watchface, accepts a selected option
+  or list item, or launches the next ``Window``.
+
+* Down - Navigates to the next item in a list, or opens the future timeline when
+  pressed from the watchface.
+
+Developers are highly encouraged to follow these patterns when using button
+clicks in their watchapps, since users will already have an idea of what each
+button will do to a reasonable degree, thus avoiding the need for lengthy usage
+instructions for each app. Watchapps that wish to use each button for a specific
+action should use the ``ActionBarLayer`` or ``ActionMenu`` to give hints about
+what each button will do.
+
+
+## Listening for Button Clicks
+
+Button clicks are received via a subscription to one of the types of button
+click events listed below. Each ``Window`` that wishes to receive button click
+events must provide a ``ClickConfigProvider`` that performs these subscriptions.
+
+The first step is to create the ``ClickConfigProvider`` function:
+
+```c
+static void click_config_provider(void *context) {
+  // Subcribe to button click events here
+
+}
+```
+
+The second step is to register the ``ClickConfigProvider`` with the current
+``Window``, typically after ``window_create()``:
+
+```c
+// Use this provider to add button click subscriptions
+window_set_click_config_provider(window, click_config_provider);
+```
+
+The final step is to write a ``ClickHandler`` function for each different type
+of event subscription required by the watchapp. An example for a single click
+event is shown below:
+
+```c
+static void select_click_handler(ClickRecognizerRef recognizer, void *context) {
+  // A single click has just occured
+
+}
+```
+
+
+## Types of Click Events
+
+There are five types of button click events that apps subscribe to, enabling
+virtually any combination of up/down/click events to be utilized in a watchapp.
+The usage of each of these is explained below:
+
+
+### Single Clicks
+
+Most apps will use this type of click event, which occurs whenever the button
+specified is pressed and then immediately released. Use
+``window_single_click_subscribe()`` from a ``ClickConfigProvider`` function,
+supplying the ``ButtonId`` value for the chosen button and the name of the
+``ClickHandler`` that will receive the events:
+
+```c
+static void click_config_provider(void *context) {
+  ButtonId id = BUTTON_ID_SELECT;  // The Select button
+
+  window_single_click_subscribe(id, select_click_handler);
+}
+```
+
+
+### Single Repeating Clicks
+
+Similar to the single click event, the single repeating click event allows
+repeating events to be received at a specific interval if the chosen button
+is held down for a longer period of time. This makes the task of scrolling
+through many list items or incrementing a value significantly easier for the
+user, and uses fewer button clicks.
+
+```c
+static void click_config_provider(void *context) {
+  ButtonId id = BUTTON_ID_DOWN;       // The Down button
+  uint16_t repeat_interval_ms = 200;  // Fire every 200 ms while held down
+
+  window_single_repeating_click_subscribe(id, repeat_interval_ms,
+                                                down_repeating_click_handler);
+}
+```
+
+After an initial press (but not release) of the button `id` subscribed to, the
+callback will be called repeatedly with an interval of `repeat_interval_ms`
+until it is then released.
+
+Developers can determine if the button is still held down after the first
+callback by using ``click_recognizer_is_repeating()``, as well as get the number
+of callbacks counted so far with ``click_number_of_clicks_counted()``:
+
+```c
+static void down_repeating_click_handler(ClickRecognizerRef recognizer,
+                                                              void *context) {
+  // Is the button still held down?
+  bool is_repeating = click_recognizer_is_repeating(recognizer);
+
+  // How many callbacks have been recorded so far?
+  uint8_t click_count = click_number_of_clicks_counted(recognizer);
+}
+```
+
+> Single click and single repeating click subscriptions conflict, and cannot be
+> registered for the same button.
+
+
+### Multiple Clicks
+
+A multi click event will call the ``ClickHandler`` after a specified number of
+single clicks has been recorded. A good example of usage is to detect a double
+or triple click gesture:
+
+```c
+static void click_config_provider(void *context) {
+  ButtonId id = BUTTON_ID_SELECT;  // The Select button
+  uint8_t min_clicks = 2;          // Fire after at least two clicks
+  uint8_t max_clicks = 3;          // Don't fire after three clicks
+  uint16_t timeout = 300;          // Wait 300ms before firing
+  bool last_click_only = true;     // Fire only after the last click
+
+  window_multi_click_subscribe(id, min_clicks, max_clicks, timeout,
+                                 last_click_only, multi_select_click_handler);
+}
+```
+
+Similar to the single repeating click event, the ``ClickRecognizerRef`` can be
+used to determine how many clicks triggered this multi click event using
+``click_number_of_clicks_counted()``.
+
+
+### Long Clicks
+
+A long click event is fired after a button is held down for the specified amount
+of time. The event also allows two ``ClickHandler``s to be registered - one for
+when the button is pressed, and another for when the button is released. Only
+one of these is required.
+
+```c
+static void click_config_provider(void *context) {
+  ButtonId id = BUTTON_ID_SELECT;  // The select button
+  uint16_t delay_ms = 500;         // Minimum time pressed to fire
+
+  window_long_click_subscribe(id, delay_ms, long_down_click_handler,
+                                                       long_up_click_handler);
+}
+```
+
+
+### Raw Clicks
+
+The last type of button click subcsription is used to track raw button click
+events. Like the long click event, two ``ClickHandler``s may be supplied to
+receive each of the pressed and depressed events.
+
+```c
+static void click_config_provider(void *context) {
+  ButtonId id = BUTTON_ID_SELECT;  // The select button
+
+  window_raw_click_subscribe(id, raw_down_click_handler, raw_up_click_handler,
+                                                                        NULL);
+}
+```
+
+> The last parameter is an optional pointer to a context object to be passed to
+> the callback, and is set to `NULL` if not used.