Repository navigation
Expand file tree
/
Copy pathapp_tutorial.h
More file actions
257 lines (229 loc) · 9.17 KB
/
Copy pathapp_tutorial.h
File metadata and controls
257 lines (229 loc) · 9.17 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
// This file is part of the Diffractor photo and video organizer
// Copyright 2026 Zac Walker
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// Purpose: The Debug build's tutorial scripts (.dft), for tutorial videos made from the running application: a
// scene set before the recording starts, then beats - a line of narration each, and what is shown while it is
// spoken. The reader is here, with the player that acts a script out in app_frame through the application's own
// handlers - no real input - while the recorder (app_record.h) films the window and names where each beat starts,
// so its narration can be laid under the film. tutorial.py, beside the scripts, voices, records and assembles.
#pragma once
#ifdef _DEBUG
#include "app_commands.h"
// A script is one step a line; # starts a comment line. Text is 'single-quoted', reading \n, \' and \\ as .dfv
// does, or "double-quoted" and taken as it stands. The steps before the first say set the scene, before the
// recording starts; each say starts a beat, whose steps run while its narration is spoken. A beat ends once its
// steps are done and its narration has been spoken.
//
// say <id> '<narration>' starts a beat. narration\<script>\<id>.timing beside the script says how long its
// voice lasts, and where its cues fall; without it, both are guessed from the text.
// {name} in the narration marks a cue and is not spoken.
// cue <name> waits for the narration to reach {name}
// wait <seconds>
// settle waits for searching, indexing and loading to finish
// point <anchor> [<seconds>] the pointer glides to the anchor, over 0.8 seconds unless given
// hide hides the pointer
// click [ctrl] [shift] clicks what the pointer is on
// double-click double-clicks it
// type '<text>' types into the address box
// key <key> presses a key: ctrl+, shift+ or alt+ before a letter, a digit or enter, escape,
// space, tab, backspace, delete, left, right, up, down, home, end, page-up,
// page-down, or f1 to f12
// command <name> runs a command: one tutorial_command names
// open ['<folder or search>'] opens it, or with none the folder the window opened on
// select '<file name>' [ctrl] selects an item shown, or with ctrl adds it to the selection
// tooltips on|off shows the tooltip where the pointer rests; off until a script turns it on
// list writes what the window shows to the console, naming the items in view: an aid to
// writing a script, since the console is all a rehearsal shows of the window
//
// An anchor is where the pointer goes: address (the address box), sidebar, types, map, calendar (the sidebar's
// charts), month <yyyy>-<mm> (one of the calendar's, its year scrolled to), items, preview (the media pane), view
// (the whole view), button <command> (a toolbar's), tile '<file name>' [<x> <y>] (an item's, scrolled to: its
// middle, or x and y across it as fractions of it), or at <x> <y> (fractions of the window from its top left). A
// click on the address box takes the keyboard there, one on a month opens it, one on a button runs its command,
// and one anywhere in the view is a click there.
//
// A script cannot work a dialog or a menu. A step that opens one - a command that explains why it cannot run, a
// click on a link with a menu - stops the script, which says so and waits until the dialog or menu is closed.
enum class tutorial_step_kind
{
cue,
wait,
settle,
point,
hide,
click,
double_click,
type,
key,
command,
open,
select,
tooltips,
list,
};
enum class tutorial_anchor_kind
{
address,
sidebar,
types,
map,
calendar,
month,
items,
preview,
view,
button,
tile,
at,
};
struct tutorial_anchor
{
tutorial_anchor_kind kind = tutorial_anchor_kind::view;
// A tile's file name.
std::string name;
commands command = commands::none;
// A month's year, and its month from 1.
int year = 0;
int month = 0;
// at: from the window's top left, and tile: from the tile's, as fractions of its width and height.
double x = 0.0;
double y = 0.0;
};
struct tutorial_step
{
tutorial_step_kind kind = tutorial_step_kind::wait;
int line = 0;
// wait's length; point's glide.
double seconds = 0.0;
// cue's name; type's, open's and select's text.
std::string text;
tutorial_anchor anchor;
commands command = commands::none;
char32_t key = 0;
// The modifiers of a click, a key or a select.
platform::key_state keys;
// tooltips on.
bool on = false;
};
struct tutorial_beat
{
std::string id;
// As written, cues and all.
std::string narration;
int line = 0;
std::vector<tutorial_step> steps;
};
struct tutorial_script
{
std::vector<tutorial_step> scene;
std::vector<tutorial_beat> beats;
// "line <n>: <problem>", for each line that could not be read. A script with any is not played.
std::vector<std::string> problems;
};
tutorial_script parse_tutorial_script(std::string_view text);
// The commands a script names, and the name each has.
std::optional<commands> tutorial_command(std::string_view name);
// How long a beat's voice lasts, and when it reaches each of its cues, in seconds from its start.
struct tutorial_narration
{
double seconds = 0.0;
std::vector<std::pair<std::string, double>> cues;
// Measured from the voice; otherwise guessed from the text.
bool measured = false;
std::optional<double> cue(std::string_view name) const;
};
// The narration as it is spoken: its cues taken out.
std::string tutorial_spoken_text(std::string_view narration);
// Guessed from the text, at an even pace: before there is a voice, a rehearsal runs to this.
tutorial_narration estimate_tutorial_narration(std::string_view narration);
// A .timing file, as tutorial.py writes it: "length<TAB><seconds>", then "cue<TAB><name><TAB><seconds>" for each
// cue, one a line. Nothing for one that does not give a length.
std::optional<tutorial_narration> parse_tutorial_timing(std::string_view text);
class app_frame;
// Acts a script out in the window, a step at a time from the frame tick: sets its scene, waits for the window to
// settle, starts -record's recording if there is one, plays each beat, and closes the window once it has finished.
class tutorial_player
{
public:
tutorial_player(app_frame& app, core::file_path script);
~tutorial_player();
tutorial_player(const tutorial_player&) = delete;
tutorial_player& operator=(const tutorial_player&) = delete;
void tick();
bool shows_tooltips() const { return _tooltips; }
private:
enum class stage
{
loading,
waiting_for_window,
setting_scene,
starting_recording,
lead_in,
beats,
lead_out,
finished,
};
struct loaded
{
tutorial_script script;
std::vector<tutorial_narration> narration;
std::string failure;
};
void load();
void loaded_script(loaded result);
void enter(stage s);
// The step running now, if one is.
const tutorial_step* current_step() const;
// Runs the steps that are due; true once every one has finished.
bool run_steps(const std::vector<tutorial_step>& steps, double beat_time, const tutorial_narration* narration);
// Starts a step: false where it has nothing more to do.
void begin_step(const tutorial_step& step);
// Whether a started step has finished.
bool step_is_done(const tutorial_step& step, double beat_time, const tutorial_narration* narration);
bool is_settled();
std::optional<pointi> anchor_point(const tutorial_anchor& anchor);
void move_pointer(std::optional<pointi> to, double seconds);
pointi pointer_now() const;
void hover();
void click(bool twice, platform::key_state keys);
void key(char32_t key, platform::key_state keys);
void finish(std::string_view outcome);
void say(std::string_view text) const;
// What the window shows: the view, the search and how many items are selected, for the log of a run.
std::string shown() const;
double now() const;
app_frame& _app;
core::file_path _script_path;
std::shared_ptr<bool> _alive = std::make_shared<bool>(true);
stage _stage = stage::loading;
double _stage_started = 0.0;
tutorial_script _script;
std::vector<tutorial_narration> _narration;
size_t _beat = 0;
double _beat_started = 0.0;
size_t _step = 0;
bool _step_begun = false;
double _step_started = 0.0;
double _step_seconds = 0.0;
double _settled_since = -1.0;
size_t _typed = 0;
// The pointer, on the screen: shown, gliding from one point to another over a time.
bool _pointer_shown = false;
pointi _pointer_from;
pointi _pointer_to;
double _pointer_moved = 0.0;
double _pointer_seconds = 0.0;
std::optional<tutorial_anchor> _pointed;
std::optional<pointi> _hovered;
bool _tooltips = false;
double _started = 0.0;
// When the film starts: the recording's first frame, or for a rehearsal the moment one would have been.
double _film_started = 0.0;
// In a tick, which a dialog or menu a step opens ticks again from inside; and waiting for one to close.
bool _ticking = false;
bool _waiting = false;
};
#endif