Debian Codegraph @

documentation/qml/pages/preview-actions.qdoc

raw
1 /*!
2 \page preview-actions.html Preview Actions
3 \title Preview Actions
4 \contentspage {Lomiri Action API}
5
6 The preview action is an action that allows the application to generate a preview of the action before
7 the action is applied. The preview is controlled by the HUD UI.
8
9 PreviewActions contain one or more parameters which form the preview parameters of the action.
10
11 The PreviewAction has additional extra requirements compared to other Actions:
12 \list
13 \li - It can have multiple parameters whose values can be seen and changed over the bus
14 \li - The parameters' ordering can be specified by client code
15 \li - It adds new signals to control the preview mode: started, cancelled, resetted
16 \endlist
17
18 The ordering of the parameters is specified by the order in which the actions are defined in the parameters list.
19
20 PreviewAction does not have a value of it's own. Instead the values of the parameters provide the information
21 on which the preview is generated.
22
23 \image hud_parameters.jpg
24 \caption HUD UI showing Color Balance action with four slider parameters
25
26
27 \part Control Signals
28 Diagram describing when the different signals are emitted:
29 \image preview_action_signals.png
30
31 \e {started} signal informs the application that it must set up a preview view and start updating the
32 preview based on the values of the defined preview parameters.
33
34 \e {resetted} signal informs the application that it has to reset the parameter values to their original values.
35
36 \e {cancelled} signal informs the application that the user cancelled the PreviewAction. At this point the application
37 must return the the state it was in at the time the \e {started()} signal was triggered without applying any changes.
38
39 \e {triggered} signal informs the application the user wants the changes to be applied.
40
41 \part Example
42
43
44 \code
45 import QtQuick 2.0
46 import Lomiri.Action 1.0
47
48 Item {
49 ActionManager {
50
51 PreviewAction {
52 text: "Exposure"
53
54 PreviewRangeParameter {
55 id: exposureParameter
56 text: "Exposure Amount"
57 minimumValue: -50
58 maximumValue: 50
59 value: 25
60
61 onValueChanged: {
62 // gets the values from the HUD UI when user interacts with the slider
63 // Application then updates the preview based on this value
64 console.debug("range value: " + value);
65 }
66 }
67
68 onStarted: {
69 // action was activated in the HUD UI.
70 // do the necessary initialization and start providing preview
71 // based on the values of the parameters.
72 }
73
74 onResetted: {
75 // reset the parameter values
76 }
77
78 onCancelled: {
79 // action was cancelled
80 }
81
82 onTriggered: {
83 // action was completed.
84 // apply the action with the values of the parameters
85 }
86 }
87
88 }
89 }
90 \endcode
91 */