MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Portal/Forma/Primitives/Prompt.hpp
Go to the documentation of this file.
1#pragma once
2
4
5class Surface;
6class FormaTarget;
7
8/**
9 * @brief Receives the accepted text, or nullopt when the prompt was cancelled or closed.
10 */
11using AskCallback = std::function<void(std::optional<std::string>)>;
12
13/**
14 * @brief Decides whether a text may be accepted.
15 */
16using AskValidator = std::function<bool(std::string_view)>;
17
18/**
19 * @brief Open a one line text prompt and report what the user typed.
20 *
21 * Requires Portal::Forma to be initialized and the engine running. The window
22 * holds one text field with the focus, started on @p initial with the cursor
23 * at its end. Enter accepts the text, Escape cancels, and closing the window
24 * cancels. The callback fires exactly once, on the event thread, so it must
25 * not block, and the window closes as it fires.
26 *
27 * When a @p validator is given it runs on every edit. Text it refuses is drawn
28 * in a warning colour and Enter does nothing until the text is accepted, so the
29 * callback only ever receives text the validator took.
30 *
31 * @param title Window title, with a note that Enter accepts and Escape cancels.
32 * @param initial Starting text.
33 * @param validator Accepts or refuses the text. Empty accepts everything.
34 * @param callback Invoked once with the text or nullopt.
35 */
36MAYAFLUX_API void ask(
37 std::string title,
38 std::string initial,
39 AskValidator validator,
40 AskCallback callback);
41
42/**
43 * @brief ask() with no validator.
44 */
45MAYAFLUX_API void ask(
46 std::string title,
47 std::string initial,
48 AskCallback callback);
49
50namespace internal {
51
52 /**
53 * @brief The prompt itself, placed on a surface that already exists.
54 *
55 * ask() builds a window and a surface and calls this. It places the field
56 * in the whole surface, gives it focus, and requests the surface's window
57 * to close when the prompt finishes. Separate so the behaviour can be
58 * driven against a scripted window.
59 *
60 * @param surface Surface to place the field on.
61 * @param target Where the field's text is drawn.
62 * @param row_px Height of the field in pixels, for the text layout.
63 * @param initial Starting text.
64 * @param validator Accepts or refuses the text. Empty accepts everything.
65 * @param callback Invoked once with the text or nullopt.
66 * @return Callable that finishes the prompt as cancelled, for a window
67 * that closes without the field's own Escape.
68 */
69 MAYAFLUX_API std::function<void()> ask_in(
70 Surface& surface,
71 FormaTarget target,
72 uint32_t row_px,
73 std::string initial,
74 AskValidator validator,
75 AskCallback callback);
76
77} // namespace internal
78
79} // namespace MayaFlux::Portal::Forma
Where an element's geometry and texture are written.
Definition Target.hpp:22
Named owner of a (Window, Layer, Context) triple: the Forma canvas.
Definition Surface.hpp:121
std::function< void()> ask_in(Surface &surface, FormaTarget target, uint32_t row_px, std::string initial, AskValidator validator, AskCallback callback)
The prompt itself, placed on a surface that already exists.
Definition Prompt.cpp:55
std::function< void(std::optional< std::string >)> AskCallback
Receives the accepted text, or nullopt when the prompt was cancelled or closed.
void ask(std::string title, std::string initial, AskValidator validator, AskCallback callback)
Open a one line text prompt and report what the user typed.
Definition Prompt.cpp:94
std::function< bool(std::string_view)> AskValidator
Decides whether a text may be accepted.