MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
ActionTable.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "FactoryTable.hpp"
4
6
7/** @brief Attribute names of an on element that the document owns. */
8inline constexpr std::string_view action_event_attribute { "event" };
9inline constexpr std::string_view action_button_attribute { "button" };
10inline constexpr std::string_view action_key_attribute { "key" };
11inline constexpr std::string_view action_name_attribute { "action" };
12
13/**
14 * @struct ActionEvent
15 * @brief What an action is told when its event happens on an instance.
16 *
17 * The references are valid for the duration of the call. event is the window
18 * event as the window's event source reports it, so its data holds the button,
19 * key, codepoint or scroll delta. position is the pointer in NDC for pointer
20 * events and zero for the others.
21 */
25 uint32_t element;
26 std::string_view instance;
28 glm::vec2 position;
29};
30
31/** @brief Code a host registers by name to run when an instance's event happens. */
32using Action = std::function<void(const ActionEvent&)>;
33
34/**
35 * @class ActionTable
36 * @brief Actions by name, which a document attaches to events and never defines.
37 *
38 * A plain value like every table here. An instance of a document may hold on
39 * children, each naming a window event, the button or key it concerns and an action. The names
40 * are resolved when the document is checked, so an unknown action fails before
41 * anything is placed. An action may take parameters, written as further
42 * attributes of the on element and decoded strictly through a described type.
43 *
44 * Because an action is subscribed beside an element's own wiring, it never
45 * replaces a Form's built in interaction.
46 *
47 * Usage:
48 * @code
49 * ActionTable<IO::XmlElementView> actions;
50 * actions.expose_typed<PrintInputs>("print", {}, [](const PrintInputs& input) {
51 * return Action([message = input.message](const ActionEvent&) { std::cout << message << '\n'; });
52 * });
53 * @endcode
54 *
55 * @tparam Source Element type with a Reflect::RecordAccess specialization.
56 */
57template <typename Source, typename Access = Reflect::RecordAccess<Source>>
59public:
60 /** @brief Decodes an on element into the action to run, or nullopt with an error. */
61 using Maker = std::function<std::optional<Action>(const Source&, std::string&)>;
62
63 /**
64 * @brief Register an action that takes no parameters.
65 *
66 * The on element may carry only its event, button and action attributes.
67 */
68 void expose(std::string name, Action action)
69 {
70 m_makers.insert_or_assign(name,
71 [action = std::move(action)](const Source& on, std::string& error) -> std::optional<Action> {
72 std::optional<std::string> unexpected;
73 Access::for_each_attribute(on, [&](std::string_view attribute, std::string_view) {
74 if (attribute == action_event_attribute || attribute == action_button_attribute
75 || attribute == action_key_attribute || attribute == action_name_attribute) {
76 return true;
77 }
78 unexpected = std::string(attribute);
79 return false;
80 });
81 if (unexpected) {
82 error = Reflect::located_message(Access::location(on),
83 "<on> has an unsupported attribute " + *unexpected);
84 return std::nullopt;
85 }
86 return action;
87 });
88 }
89
90 /**
91 * @brief Register an action whose parameters are a described type.
92 *
93 * The attributes of the on element, other than event, button and action,
94 * are decoded strictly into Input, and make builds the action from it.
95 *
96 * @param binding Binding for Input, configured with any required names.
97 * @param make Callable taking the decoded Input and returning the Action.
98 */
99 template <Reflect::Described Input>
101 std::type_identity_t<std::function<Action(const Input&)>> make)
102 {
104 m_makers.insert_or_assign(name,
105 [binding = std::move(binding), make = std::move(make)](
106 const Source& on, std::string& error) -> std::optional<Action> {
107 uint64_t where {};
108 const auto input = binding.read(on, error, &where);
109 if (!input) {
110 error = Reflect::located_message(where, error);
111 return std::nullopt;
112 }
113 return make(*input);
114 });
115 }
116
117 /** @brief Add every action of another table under a name prefix. */
118 bool merge(const ActionTable& other, std::string_view prefix, std::string& error, bool replace = false)
119 {
120 return m_makers.merge_prefixed(other.m_makers, prefix, error, replace);
121 }
122
123 [[nodiscard]] bool contains(std::string_view name) const
124 {
125 return m_makers.find(name) != m_makers.end();
126 }
127
128 /** @brief Registered names in sorted order. */
129 [[nodiscard]] std::vector<std::string> names() const
130 {
131 std::vector<std::string> result;
132 for (const auto& entry : m_makers)
133 result.push_back(entry.first);
134 return result;
135 }
136
137 /** @brief The maker of this name, or nullptr. */
138 [[nodiscard]] const Maker* find(std::string_view name) const
139 {
140 const auto found = m_makers.find(name);
141 return found == m_makers.end() ? nullptr : &found->second;
142 }
143
144private:
146};
147
148}
Map kept as one sorted vector, cheap to copy.
Definition FlatMap.hpp:21
bool merge(const ActionTable &other, std::string_view prefix, std::string &error, bool replace=false)
Add every action of another table under a name prefix.
void expose(std::string name, Action action)
Register an action that takes no parameters.
std::vector< std::string > names() const
Registered names in sorted order.
Memory::FlatMap< std::string, Maker, std::less<> > m_makers
const Maker * find(std::string_view name) const
The maker of this name, or nullptr.
void expose_typed(std::string name, Reflect::RecordBinding< Input, Source, Access > binding, std::type_identity_t< std::function< Action(const Input &)> > make)
Register an action whose parameters are a described type.
bool contains(std::string_view name) const
std::function< std::optional< Action >(const Source &, std::string &)> Maker
Decodes an on element into the action to run, or nullopt with an error.
Actions by name, which a document attaches to events and never defines.
Event wiring between a Layer and a window surface.
Definition Context.hpp:42
Flat registry of Elements on a surface.
Definition Layer.hpp:28
RecordBinding & ignore(std::initializer_list< std::string_view > names)
Leave these attributes to other readers of the same element.
std::optional< Input > read(const Source &source, std::string &error, uint64_t *error_location=nullptr) const
Decode the source element into a new Input.
Bind described attributes and configured child collections of a source element.
constexpr std::string_view action_button_attribute
constexpr std::string_view action_event_attribute
Attribute names of an on element that the document owns.
constexpr std::string_view action_name_attribute
std::function< void(const ActionEvent &)> Action
Code a host registers by name to run when an instance's event happens.
constexpr std::string_view action_key_attribute
std::string located_message(uint64_t location, std::string_view message)
A diagnostic message prefixed with the location of the element it concerns.
Event data for window and input events.
const Core::WindowEvent & event
What an action is told when its event happens on an instance.