Merge branch 'skia_2024' into docs_2024

Author: djowel

examples/buttons/CMakeLists.txt

@@ -25,8 +25,8 @@ set(ELEMENTS_APP_VERSION "1.0")
 set(ELEMENTS_APP_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
 set(ELEMENTS_APP_RESOURCES
    ${CMAKE_CURRENT_SOURCE_DIR}/resources/power_180x632.png
-   ${CMAKE_CURRENT_SOURCE_DIR}/resources/phase_180x632.png
-   ${CMAKE_CURRENT_SOURCE_DIR}/resources/mail_180x632.png
+   ${CMAKE_CURRENT_SOURCE_DIR}/resources/phase_180x790.png
+   ${CMAKE_CURRENT_SOURCE_DIR}/resources/mail_180x790.png
    ${CMAKE_CURRENT_SOURCE_DIR}/resources/transpo_180x632.png
 )
 

examples/buttons/main.cpp

@@ -50,9 +50,12 @@ void my_custom_button::draw(context const& ctx)
    // necessary. For this simple example, we wiill deal only with `value` and
    // `hilite`.
 
-   auto state = value();
-   bool value = state.value;     // button is on or off
-   bool hilite = state.hilite;   // cursor is hovering over the button
+   auto btn = find_parent<basic_button*>(ctx);
+   if (!btn)
+      return;
+
+   bool value = btn->value();    // button is on or off
+   bool hilite = btn->hilite();  // cursor is hovering over the button
    bool enabled = ctx.enabled;   // button is enabled or disabled
 
    bounds = bounds.inset(1, 1);
@@ -272,18 +275,24 @@ auto make_controls(view& view_)
 
    float const button_scale = 1.0/4;
    sprite power_button = sprite{"power_180x632.png", 158*button_scale, button_scale};
-   sprite phase_button = sprite{"phase_180x632.png", 158*button_scale, button_scale};
-   sprite mail_button = sprite{"mail_180x632.png", 158*button_scale, button_scale};
+   sprite phase_button = sprite{"phase_180x790.png", 158*button_scale, button_scale};
+   sprite mail_button = sprite{"mail_180x790.png", 158*button_scale, button_scale};
    sprite transpo_button = sprite{"transpo_180x632.png", 158*button_scale, button_scale};
 
+   // Note: When disabling a sprite button, the sprite must have a fifth
+   //       frame specifically for the disabled state.
+   auto phase_disabled = toggle_button(phase_button);
+   phase_disabled.enable(false);
+
    auto  sprite_buttons =
          group("Sprite Buttons",
             margin({10, 45, 20, 10},
                htile(
                   align_center(toggle_button(power_button)),
                   align_center(toggle_button(phase_button)),
                   align_center(momentary_button(mail_button)),
-                  align_center(toggle_button(transpo_button))
+                  align_center(toggle_button(transpo_button)),
+                  align_center(phase_disabled)
                )
             )
          );

examples/buttons/resources/mail_180x632.png

@@ -37,11 +37,11 @@ namespace cycfi::elements
     *    A struct for maintaining and managing the state of a button.
     *
     *    This structure captures the various states that a button can have:
-    *    - `value`: The button's value; 0(off) or 1(on).
-    *    - `hilite`: True if the button is highlighted (when the mouse is
-    *                hovering over the button).
-    *    - `tracking`: True if the mouse button being pressed.
-    *    - `enabled`: True if the button is enabled.
+    *    - `value`:     The button's value; 0(off) or 1(on).
+    *    - `hilite`:    True if the button is highlighted (when the mouse is
+    *                   hovering over the button).
+    *    - `tracking`:  True if the mouse button being pressed.
+    *    - `enabled` :  True if the button is enabled.
     */
    struct button_state
    {
@@ -60,37 +60,13 @@ namespace cycfi::elements
     *
     *    The `basic_button` class is a foundational class for creating a GUI
     *    button. This class is a proxy which delegates the rendering of the
-    *    actual button to a button styler subject. This separation of
-    *    responsibilities provides greater flexibility in defining the
-    *    button's appearance and behavior. The `basic_button` class handles
-    *    user interactions, while the button styler manages the button's
-    *    visual presentation. With this pattern, different stylers can be
-    *    implemented for various visual representations, for instance, plain
-    *    buttons, radio buttons, slide switches, checkboxes, and more.
-    *
-    *    The communication with the button styler is done via the
-    *    `receiver<button_state>` or a `receiver<int>` APIs. These APIs
-    *    provide a means for the `basic_button` to update the button styler
-    *    about changes in button's state to allow the styler to adjust the
-    *    visual representation accordingly.
-    *
-    *    If the button styler follows a `receiver<int>` API, it will receive
-    *    in integer with these possible values:
-    *
-    *       0: value=`false`, hilite=`false`
-    *       1: value=`false`, hilite=`true`
-    *       2: value=`true`,  hilite=`false`
-    *       3: value=`true`,  hilite=`true`
-    *
-    *    If the button styler follows a `receiver<button_state>` API, it will
-    *    receive a `button_state` when the button's state changes. This has a
-    *    richer API compared to the former, allowing more nuanced button
-    *    rendering. See `button_state`.
-    *
-    *    Take note that the button styler is just an element and does not
-    *    have to follow the `receiver` API. If that's the case, then the
-    *    button rendering will be static, and not adjust to state changes.
-    *    This may still be useful in certain cases.
+    *    actual button to a button styler subject. This division of
+    *    responsibilities allows for more flexibility in dictating the
+    *    button's appearance and interaction. The `basic_button` class
+    *    handles user interactions, while the button styler manages the
+    *    button's visual presentation. With this pattern, different stylers
+    *    can be implemented for various visual representations, for instance,
+    *    plain buttons, radio buttons, slide switches, checkboxes, and more.
     */
    class basic_button : public proxy_base, public receiver<bool>
    {
@@ -118,14 +94,12 @@ namespace cycfi::elements
 
    protected:
 
-      bool              state(bool val);
+      bool              set_value(bool val);
       void              tracking(bool val);
       void              hilite(bool val);
 
    private:
 
-      bool              update_receiver();
-
       button_state      _state;
    };
 

examples/buttons/resources/mail_180x790.png

@@ -67,9 +67,7 @@ namespace cycfi::elements
 
                            basic_dial(double init_value = 0.0);
 
-      void                 prepare_subject(context& ctx) override;
       element*             hit_test(context const& ctx, point p, bool leaf, bool control) override;
-
       bool                 scroll(context const& ctx, point dir, point p) override;
       void                 keep_tracking(context const& ctx, tracker_info& track_info) override;
 

examples/buttons/resources/phase_180x632.png

@@ -7,6 +7,7 @@
 #define ELEMENTS_IMAGE_APRIL_24_2016
 
 #include <elements/element/element.hpp>
+#include <elements/element/proxy.hpp>
 #include <elements/support/receiver.hpp>
 #include <artist/image.hpp>
 #include <artist/canvas.hpp>
@@ -59,47 +60,6 @@ namespace cycfi::elements
       float                   _scale;
    };
 
-   /**
-    * \class sprite_as_int
-    *
-    * \brief
-    *    A template structure to handle sprite images used as 'int' receivers.
-    *
-    *    Receives an 'int' value which indicates which frame of sprite image
-    *    should be displayed.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    */
-   template <typename Derived>
-   struct sprite_as_int : receiver<int>
-   {
-      void                    value(int val) override;
-      int                     value() const override;
-   };
-
-   /**
-    * \class sprite_as_double
-    *
-    * \brief
-    *    A template structure to handle sprite images used as 'double'
-    *    receivers.
-    *
-    *    Receives a 'double' value in the range of 0.0 to 1.0, which
-    *    indicates which frame of the sprite image should be displayed. The
-    *    double value essentially represents the frame number, scaled down to
-    *    fit within the 0.0 to 1.0 range.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    */
-   template <typename Derived>
-   struct sprite_as_double : receiver<double>
-   {
-      void                    value(double val) override;
-      double                  value() const override;
-   };
-
    /**
     * \class basic_sprite
     *
@@ -130,35 +90,33 @@ namespace cycfi::elements
       float                   _height;
    };
 
-   /**
-    * \class sprite
-    *
-    * \brief
-    *    A class representing a sprite image that can be used as controls.
-    *
-    *    `sprite` extends `basic_sprite` to utilize both `sprite_as_int` and
-    *    `sprite_as_double`, making it usable as both an 'int' and a 'double'
-    *    receiver.
-    *
-    *    Sprites are images used as controls. Various frames are laid out in
-    *    a single (big) image but only one frame is drawn at any single time.
-    *    Useful for switches, knobs and basic (sprite) animation.
-    *
-    *    Note on sprite_as_int and sprite_as_double: The tricky thing about
-    *    sprites is that they can act as both receiver<int> or
-    *    receiver<double> depending on usage. For example, buttons use it as
-    *    a receiver<int> where the int value reflects the current frame
-    *    displayed. On the other hand, dials regard it as a receiver<double>,
-    *    where the value 0.0 to 1.0 reflects its state from 0 to
-    *    num_frames()-1. Alas, we cannot directly inherit from both because
-    *    the overridden value() member function will have an ambiguous return
-    *    type (double or int?). The sprite_as_int and sprite_as_double TMP
-    *    trick solves this dilemma.
-    */
-   struct sprite : basic_sprite, sprite_as_int<sprite>, sprite_as_double<sprite>
+   using sprite = basic_sprite;
+
+   namespace detail
    {
-      using basic_sprite::basic_sprite;
-   };
+      template <typename T>
+      constexpr auto is_sprite()
+      {
+         if constexpr (std::is_base_of_v<proxy_base, T>)
+            return is_sprite<typename T::subject_type>();
+         else
+            return std::false_type{};
+      }
+
+      template <>
+      constexpr auto is_sprite<sprite>()
+      {
+         return std::true_type{};
+      }
+   }
+
+   namespace concepts
+   {
+      template <typename T>
+      concept SpriteSubject
+         = concepts::Element<T> &&
+         decltype(detail::is_sprite<std::decay_t<T>>())::value;
+   }
 
    //--------------------------------------------------------------------------
    // Inlines
@@ -175,77 +133,6 @@ namespace cycfi::elements
    {
       return _index;
    }
-
-   /**
-    * \brief
-    *    Returns the index of the currently displayed frame in sprite_as_int.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    *
-    * \returns
-    *    The index of the currently displayed frame as an integer.
-    */
-   template <typename Derived>
-   int sprite_as_int<Derived>::value() const
-   {
-      auto this_ = static_cast<Derived const*>(this);
-      return this_->index();
-   }
-
-   /**
-    * \brief
-    *    Sets the index of the sprite_as_int to the provided value.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    *
-    * \param val
-    *    The value to set the index to (index of the frame to be displayed).
-    */
-   template <typename Derived>
-   void sprite_as_int<Derived>::value(int val)
-   {
-      auto this_ = static_cast<Derived*>(this);
-      this_->index(val);
-   }
-
-   /**
-    * \brief
-    *    Returns the index of the currently displayed frame in
-    *    sprite_as_double as a fraction of the total frames.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    *
-    * \returns
-    *    The index of the currently displayed frame as a fraction of the
-    *    total frames (between 0.0 to 1.0).
-    */
-   template <typename Derived>
-   double sprite_as_double<Derived>::value() const
-   {
-      auto this_ = static_cast<Derived const*>(this);
-      return this_->index() / this_->num_frames()-1;
-   }
-
-   /**
-    * \brief
-    *    Sets the index of the sprite_as_double to the provided value.
-    *
-    * \tparam Derived
-    *    The derived class type.
-    *
-    * \param val
-    *    The value to set the index to. It's a value between 0.0 and 1.0
-    *    representing the relative position in the sequence of frames.
-    */
-   template <typename Derived>
-   void sprite_as_double<Derived>::value(double val)
-   {
-      auto this_ = static_cast<Derived*>(this);
-      this_->index(val * (this_->num_frames()-1));
-   }
 }
 
 #endif

examples/buttons/resources/phase_180x790.png

@@ -129,6 +129,9 @@ namespace cycfi::elements
    class proxy : public Base
    {
    public:
+
+      using subject_type = Subject;
+
                               template <typename... T>
                               proxy(Subject subject_, T&&... args);
 

lib/include/elements/element/button.hpp

@@ -23,6 +23,8 @@
 #include <elements/element/style/radio_button.hpp>
 #include <elements/element/style/slide_switch.hpp>
 #include <elements/element/style/slider.hpp>
+#include <elements/element/style/sprite_button.hpp>
+#include <elements/element/style/sprite_dial.hpp>
 #include <elements/element/style/tab.hpp>
 #include <elements/element/style/text_entry.hpp>
 #include <elements/element/style/thumbwheel.hpp>

lib/include/elements/element/dial.hpp

@@ -22,14 +22,12 @@ namespace cycfi::elements
     * \brief Base class for button styling.
     *
     * The `button_styler_base` class is responsible for providing the basic
-    * styling and behavior for buttons. It inherits from `element` and
-    * `basic_receiver<button_state>`, allowing it to handle button states
-    * and interact with the user interface.
+    * styling and behavior for buttons.
     *
     * This class provides the foundational functionality for button styling,
     * including cursor handling and control requirements.
     */
-   struct button_styler_base : element, basic_receiver<button_state>
+   struct button_styler_base : element
    {
       bool                    cursor(context const& ctx, point p, cursor_tracking status) override;
       bool                    wants_control() const override;

lib/include/elements/element/image.hpp

@@ -14,7 +14,7 @@ namespace cycfi::elements
    ////////////////////////////////////////////////////////////////////////////
    // Check Box
    ////////////////////////////////////////////////////////////////////////////
-   struct check_box_styler : toggle_selector, basic_receiver<button_state>
+   struct check_box_styler : toggle_selector
    {
       using toggle_selector::toggle_selector;