Merge lp:~nik90/component-store/add-welcome-wizard into lp:component-store

Proposed by Nekhelesh Ramananthan on 2015-03-03
Status: Merged
Merged at revision: 43
Proposed branch: lp:~nik90/component-store/add-welcome-wizard
Merge into: lp:component-store
Diff against target: 545 lines (+484/-1)
9 files modified
ComponentStore/WelcomeWizard/Walkthrough.qml (+116/-0)
ComponentStore/WelcomeWizard/ubuntu_component_store.json (+6/-0)
GallerySRC/Slide1.qml (+54/-0)
GallerySRC/Slide2.qml (+42/-0)
GallerySRC/WelcomeWizardWidget.qml (+41/-0)
GallerySRC/WidgetsModel.qml (+5/-0)
docs/_components/listitemwithactions.rst (+1/-1)
docs/_components/welcomewizard.rst (+218/-0)
docs/index.rst (+1/-0)
To merge this branch: bzr merge lp:~nik90/component-store/add-welcome-wizard
Reviewer Review Type Date Requested Status
Ubuntu Touch Community Dev 2015-03-03 Pending
Review via email: mp+251599@code.launchpad.net

Commit message

Added welcome wizard component

Description of the change

Adds welcome wizard component

To post a comment you must log in.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added directory 'ComponentStore/WelcomeWizard'
2=== added file 'ComponentStore/WelcomeWizard/Walkthrough.qml'
3--- ComponentStore/WelcomeWizard/Walkthrough.qml 1970-01-01 00:00:00 +0000
4+++ ComponentStore/WelcomeWizard/Walkthrough.qml 2015-03-03 14:08:25 +0000
5@@ -0,0 +1,116 @@
6+import QtQuick 2.3
7+import Ubuntu.Components 1.1
8+import Ubuntu.Components.ListItems 1.0 as ListItem
9+
10+Page {
11+ id: walkthrough
12+
13+ // Property to set the app name used in the walkthrough
14+ property string appName
15+
16+ // Property to check if this is the first run or not
17+ property bool isFirstRun: true
18+
19+ // Property to store the slides shown in the walkthrough (Each slide is a component defined in a separate file for simplicity)
20+ property list<Component> model
21+
22+ // Property to set the color of bottom cirle to indicate the user's progress
23+ property color completeColor: "green"
24+
25+ // Property to set the color of the bottom circle to indicate the slide still left to cover
26+ property color inCompleteColor: "grey"
27+
28+ // Property to set the color of the skip welcome wizard text
29+ property color skipTextColor: "grey"
30+
31+ // Property to signal walkthrough completion
32+ signal finished
33+
34+ // ListView to show the slides
35+ ListView {
36+ id: listView
37+ anchors {
38+ left: parent.left
39+ right: parent.right
40+ top: skipLabel.bottom
41+ bottom: separator.top
42+ }
43+
44+ model: walkthrough.model
45+ snapMode: ListView.SnapOneItem
46+ orientation: Qt.Horizontal
47+ highlightMoveDuration: UbuntuAnimation.FastDuration
48+ highlightRangeMode: ListView.StrictlyEnforceRange
49+ highlightFollowsCurrentItem: true
50+
51+ delegate: Item {
52+ width: listView.width
53+ height: listView.height
54+ clip: true
55+
56+ Loader {
57+ anchors {
58+ fill: parent
59+ margins: units.gu(2)
60+ }
61+
62+ sourceComponent: modelData
63+ }
64+ }
65+ }
66+
67+ // Label to skip the walkthrough. Only visible on the first slide
68+ Label {
69+ id: skipLabel
70+
71+ color: skipTextColor
72+ fontSize: "small"
73+ width: contentWidth
74+ text: listView.currentIndex === 0 ? i18n.tr("Already used %1? <b>Skip the tutorial</b>").arg(appName) : i18n.tr("Skip")
75+
76+ anchors {
77+ top: parent.top
78+ left: parent.left
79+ margins: units.gu(2)
80+ }
81+
82+ MouseArea {
83+ anchors.fill: parent
84+ onClicked: walkthrough.finished()
85+ }
86+ }
87+
88+ // Separator between walkthrough slides and slide indicator
89+ ListItem.ThinDivider {
90+ id: separator
91+ anchors.bottom: slideIndicator.top
92+ }
93+
94+ // Indicator element to represent the current slide of the walkthrough
95+ Row {
96+ id: slideIndicator
97+ height: units.gu(6)
98+ spacing: units.gu(2)
99+ anchors {
100+ bottom: parent.bottom
101+ horizontalCenter: parent.horizontalCenter
102+ }
103+
104+ Repeater {
105+ model: walkthrough.model.length
106+ delegate: Rectangle {
107+ height: width
108+ radius: width/2
109+ width: units.gu(2)
110+ antialiasing: true
111+ anchors.verticalCenter: parent.verticalCenter
112+ color: listView.currentIndex >= index ? completeColor : inCompleteColor
113+ Behavior on color {
114+ ColorAnimation {
115+ duration: UbuntuAnimation.FastDuration
116+ }
117+ }
118+ }
119+ }
120+ }
121+}
122
123=== added file 'ComponentStore/WelcomeWizard/ubuntu_component_store.json'
124--- ComponentStore/WelcomeWizard/ubuntu_component_store.json 1970-01-01 00:00:00 +0000
125+++ ComponentStore/WelcomeWizard/ubuntu_component_store.json 2015-03-03 14:08:25 +0000
126@@ -0,0 +1,6 @@
127+{
128+ "name": "WelcomeWizard",
129+ "description": "This widget adds a welcome wizard to help introduce the app to users.",
130+ "version": "1.0",
131+ "documentation_url": "http://ubuntu-component-store.readthedocs.org/en/latest/_components/circleimage.html"
132+}
133
134=== added file 'GallerySRC/Slide1.qml'
135--- GallerySRC/Slide1.qml 1970-01-01 00:00:00 +0000
136+++ GallerySRC/Slide1.qml 2015-03-03 14:08:25 +0000
137@@ -0,0 +1,54 @@
138+import QtQuick 2.3
139+import Ubuntu.Components 1.1
140+
141+// Slide 1
142+Component {
143+ id: slide1
144+ Item {
145+ id: slide1Container
146+
147+ UbuntuShape {
148+ anchors {
149+ bottom: textColumn.top
150+ bottomMargin: units.gu(4)
151+ horizontalCenter: parent.horizontalCenter
152+ }
153+
154+ image: Image {
155+ smooth: true
156+ antialiasing: true
157+ fillMode: Image.PreserveAspectFit
158+ source: Qt.resolvedUrl("assets/flashback.png")
159+ }
160+ }
161+
162+ Column {
163+ id: textColumn
164+
165+ anchors.centerIn: parent
166+
167+ Label {
168+ text: "Welcome to"
169+ fontSize: "x-large"
170+ height: contentHeight
171+ anchors.horizontalCenter: parent.horizontalCenter
172+ }
173+ Label {
174+ text: "Component Store Gallery"
175+ font.bold: true
176+ height: contentHeight
177+ font.pixelSize: units.dp(50)
178+ anchors.horizontalCenter: parent.horizontalCenter
179+ }
180+ }
181+
182+ Label {
183+ id: swipeText
184+ text: "Swipe left to continue"
185+ horizontalAlignment: Text.AlignHCenter
186+ anchors.bottom: parent.bottom
187+ anchors.bottomMargin: units.gu(2)
188+ anchors.horizontalCenter: parent.horizontalCenter
189+ }
190+ }
191+}
192
193=== added file 'GallerySRC/Slide2.qml'
194--- GallerySRC/Slide2.qml 1970-01-01 00:00:00 +0000
195+++ GallerySRC/Slide2.qml 2015-03-03 14:08:25 +0000
196@@ -0,0 +1,42 @@
197+import QtQuick 2.3
198+import Ubuntu.Components 1.1
199+
200+// Slide 2
201+Component {
202+ id: slide2
203+ Item {
204+ id: slide2Container
205+
206+ Column {
207+ id: mainColumn
208+ spacing: units.gu(4)
209+ anchors.fill: parent
210+
211+ Label {
212+ id: introductionText
213+ text: "Component Store Gallery"
214+ font.bold: true
215+ fontSize: "x-large"
216+ anchors.horizontalCenter: parent.horizontalCenter
217+ }
218+
219+ Image {
220+ id: centerImage
221+ height: parent.height - bodyText.contentHeight - introductionText.height - 4*mainColumn.spacing
222+ fillMode: Image.PreserveAspectFit
223+ anchors.horizontalCenter: parent.horizontalCenter
224+ source: Qt.resolvedUrl("assets/flashback.png")
225+ }
226+
227+ Label {
228+ id: bodyText
229+ anchors.left: parent.left
230+ anchors.right: parent.right
231+ wrapMode: Text.WordWrap
232+ font.pixelSize: units.dp(17)
233+ horizontalAlignment: Text.AlignHCenter
234+ text: "Component Store Gallery is a frontend app to the component store and provides a demo of all the components in the store. \n\nUbuntu Touch's first component store!"
235+ }
236+ }
237+ }
238+}
239
240=== added file 'GallerySRC/WelcomeWizardWidget.qml'
241--- GallerySRC/WelcomeWizardWidget.qml 1970-01-01 00:00:00 +0000
242+++ GallerySRC/WelcomeWizardWidget.qml 2015-03-03 14:08:25 +0000
243@@ -0,0 +1,41 @@
244+import QtQuick 2.0
245+import Ubuntu.Components 1.1
246+import "../ComponentStore/WelcomeWizard"
247+
248+TemplateWidgetPage {
249+ id: welcomeWizardWidget
250+
251+ title: "Welcome Wizard"
252+ author: "Nekhelesh Ramananthan, Michael Spencer"
253+ email: "nik90@ubuntu.com"
254+ license: "GNU General Public License v3.0"
255+ description: "This widget adds a welcome wizard which helps showcase the \
256+app features to the user."
257+
258+ Component {
259+ id: pageComponent
260+ Walkthrough {
261+ id: walkthrough
262+
263+ appName: "Component Store Gallery"
264+
265+ onFinished: {
266+ console.log("Welcome Wizard Complete!")
267+ stack.pop()
268+ }
269+
270+ model: [
271+ Slide1{},
272+ Slide2{}
273+ ]
274+ }
275+ }
276+
277+ content: Button {
278+ text: "Preview Welcome Wizard Component"
279+ color: "Green"
280+ height: units.gu(6)
281+ onClicked: stack.push(pageComponent)
282+ anchors.centerIn: parent
283+ }
284+}
285
286=== modified file 'GallerySRC/WidgetsModel.qml'
287--- GallerySRC/WidgetsModel.qml 2014-11-15 13:52:44 +0000
288+++ GallerySRC/WidgetsModel.qml 2015-03-03 14:08:25 +0000
289@@ -32,4 +32,9 @@
290 label: "Radial Bottom Edge"
291 source: "GallerySRC/RadialBottomEdgeWidget.qml"
292 }
293+
294+ ListElement {
295+ label: "Welcome Wizard"
296+ source: "GallerySRC/WelcomeWizardWidget.qml"
297+ }
298 }
299
300=== modified file 'docs/_components/listitemwithactions.rst'
301--- docs/_components/listitemwithactions.rst 2014-11-15 14:59:11 +0000
302+++ docs/_components/listitemwithactions.rst 2015-03-03 14:08:25 +0000
303@@ -116,7 +116,7 @@
304
305 Label {
306 id: subTitle
307- text: "SubTitle
308+ text: "SubTitle"
309 }
310 }
311
312
313=== added file 'docs/_components/welcomewizard.rst'
314--- docs/_components/welcomewizard.rst 1970-01-01 00:00:00 +0000
315+++ docs/_components/welcomewizard.rst 2015-03-03 14:08:25 +0000
316@@ -0,0 +1,218 @@
317+Welcome Wizard
318+==============
319+
320++----------+----------------------------------------+
321+| Author | Nekhelesh Ramananthan, Michael Spencer |
322++----------+-------------+--------------------------+
323+| License | BSD License |
324++----------+----------------------------------------+
325+| Contact | nik90@ubuntu.com |
326++----------+----------------------------------------+
327+| Framework| ubuntu-sdk-14.10 |
328++----------+----------------------------------------+
329+
330+This component shows users a welcome wizard which can be used to introduce
331+and showcase the features of the app to guide the user. The API of this
332+component is rather simple and provides a lot of freedom to the developer
333+to present his content.
334+
335+It is recommended to put the Walkthrough{} component inside a qml Component{}
336+since it is not run frequently. Walkthrough derives from a Page. So push it
337+into a pagestack to show the welcome wizard as shown below in the example.
338+
339+Example:
340+
341+MainView.qml
342+
343+.. code-block:: qml
344+
345+ MainView
346+ {
347+ Component {
348+ id: pageComponent
349+ Walkthrough {
350+ id: walkthrough
351+
352+ appName: "Component Store Gallery"
353+
354+ onFinished: {
355+ console.log("Welcome Wizard Complete!")
356+ // Here perhaps save isFirstRun variable to the disk
357+ stack.pop()
358+ }
359+
360+ model: [
361+ Slide1{},
362+ Slide2{}
363+ ]
364+ }
365+ }
366+
367+ component.onCompleted: pagestack.push(pageComponent)
368+ }
369+
370+Slide1.qml
371+
372+.. code-block:: qml
373+
374+ import QtQuick 2.3
375+ import Ubuntu.Components 1.1
376+
377+ // Slide 1
378+ Component {
379+ id: slide1
380+ Item {
381+ id: slide1Container
382+
383+ UbuntuShape {
384+ anchors {
385+ bottom: textColumn.top
386+ bottomMargin: units.gu(4)
387+ horizontalCenter: parent.horizontalCenter
388+ }
389+
390+ image: Image {
391+ smooth: true
392+ antialiasing: true
393+ fillMode: Image.PreserveAspectFit
394+ source: Qt.resolvedUrl("assets/flashback.png")
395+ }
396+ }
397+
398+ Column {
399+ id: textColumn
400+
401+ anchors.centerIn: parent
402+
403+ Label {
404+ text: "Welcome to"
405+ fontSize: "x-large"
406+ height: contentHeight
407+ anchors.horizontalCenter: parent.horizontalCenter
408+ }
409+ Label {
410+ text: "Component Store Gallery"
411+ font.bold: true
412+ height: contentHeight
413+ font.pixelSize: units.dp(50)
414+ anchors.horizontalCenter: parent.horizontalCenter
415+ }
416+ }
417+
418+ Label {
419+ id: swipeText
420+ text: "Swipe left to continue"
421+ horizontalAlignment: Text.AlignHCenter
422+ anchors.bottom: parent.bottom
423+ anchors.bottomMargin: units.gu(2)
424+ anchors.horizontalCenter: parent.horizontalCenter
425+ }
426+ }
427+ }
428+
429+.. image:: ../_images/welcomewizard.png
430+ :align: center
431+
432+Properties
433+----------
434+
435+- :ref:`appName`: string
436+- :ref:`isFirstRun`: boolean
437+- :ref:`model`: Item<list>
438+- :ref:`completeColor`: color
439+- :ref:`inCompleteColor`: color
440+- :ref:`skipTextColor`: color
441+
442+Signals
443+-------
444+
445+- :ref:`finished()`
446+
447+Property Documentation
448+----------------------
449+
450+.. _appName:
451+
452+appName
453+^^^^^^^
454+
455+Name of the application that is shown in some parts of the welcome wizard.
456+
457+.. _isFirstRun:
458+
459+isFirstRun
460+^^^^^^^^^^
461+
462+Boolean property to determine if the welcome wizard was run for the first time
463+or not. It is recommended to store this variable to the disk using U1dB or Qt.labs.settings
464+to remember the welcome wizard run state.
465+
466+.. _model:
467+
468+model
469+^^^^^
470+
471+This property stores the welcome wizards slides that are shown to the user.
472+Create your content and store them in separate files per slide. So if you
473+have 3 slides in your welcome wizard, you could define them as Slide1.qml,
474+Slide2.qml and Slide3.qml and then reference them as,
475+
476+.. code-block:: qml
477+
478+ model: [
479+ Slide1{},
480+ Slide2{},
481+ Slide3{}
482+ ]
483+
484+The slides should only contain the content you want to show. Everything else like the
485+dots, divider, title etc are handled by the welcome wizard component itself. Think of these
486+slides as delegates in a listview which only house the content itself.
487+
488+.. _completeColor:
489+
490+completeColor
491+^^^^^^^^^^^^^
492+
493+This property sets the color of the bottom circle to indicate the progress of the user. By
494+default it is green.
495+
496+.. _inCompleteColor:
497+
498+inCompleteColor
499+^^^^^^^^^^^^^^^
500+
501+This property sets the color of the bottom circle to indicate the slides left in the wizard.
502+By default it is grey.
503+
504+.. _skipTextColor:
505+
506+skipTextColor
507+^^^^^^^^^^^^^
508+
509+This property sets the color of the skip text shown at the top of the welcome wizard.
510+
511+Signal Documentation
512+--------------------
513+
514+.. _finished():
515+
516+finished()
517+^^^^^^^^^^
518+
519+This signal is fired automatically when the user press the skip button. It can also be made
520+to fire manually to exit the welcome wizard. You can perform exit tasks when this signal is fired
521+like updating the :ref:`isFirstRun` variable and storing to disk etc.
522+
523+.. code-block:: qml
524+
525+ Button {
526+ id: continueButton
527+ color: "Green"
528+ height: units.gu(5)
529+ width: units.gu(25)
530+ text: "Exit Welcome Wizard"
531+ anchors.horizontalCenter: parent.horizontalCenter
532+ onClicked: finished()
533+ }
534+
535
536=== added file 'docs/_images/welcomewizard.png'
537Binary files docs/_images/welcomewizard.png 1970-01-01 00:00:00 +0000 and docs/_images/welcomewizard.png 2015-03-03 14:08:25 +0000 differ
538=== modified file 'docs/index.rst'
539--- docs/index.rst 2014-11-15 14:50:47 +0000
540+++ docs/index.rst 2015-03-03 14:08:25 +0000
541@@ -54,3 +54,4 @@
542 _components/listitemwithactions
543 _components/pagewithbottomedge
544 _components/radialbottomedge
545+ _components/welcomewizard

Subscribers

People subscribed via source and target branches