Ubuntu UI Toolkit

Merge lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs into lp:ubuntu-ui-toolkit/staging

  1. jsDocs
  2. Merge into staging
Proposed by Christian Dywan on 2015-07-07
Status: Merged
Approved by: Tim Peeters on 2015-07-27
Approved revision: 1559
Merged at revision: 1580
Proposed branch: lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs
Merge into: lp:ubuntu-ui-toolkit/staging
Diff against target: 793 lines (+615/-8)
16 files modified
components.api (+3/-3)
documentation/ubuntu-ui-toolkit-common.qdocconf (+2/-1)
src/Ubuntu/Components/1.2/mathUtils.js (+23/-4)
src/Ubuntu/Components/1.3/colorUtils.js (+37/-0)
src/Ubuntu/Components/1.3/dateUtils.js (+145/-0)
src/Ubuntu/Components/1.3/mathUtils.js (+61/-0)
src/Ubuntu/Components/1.3/pageUtils.js (+10/-0)
src/Ubuntu/Components/ComponentModule.pro (+2/-0)
src/Ubuntu/Components/Popups/1.3/popupUtils.js (+101/-0)
src/Ubuntu/Components/Popups/Popups.pro (+1/-0)
src/Ubuntu/Components/Popups/qmldir (+1/-0)
src/Ubuntu/Components/Themes/Ambiance/1.3/colorUtils.js (+36/-0)
src/Ubuntu/Components/Themes/Ambiance/1.3/scrollbarUtils.js (+139/-0)
src/Ubuntu/Components/Themes/Ambiance/1.3/sliderUtils.js (+48/-0)
src/Ubuntu/Components/Themes/Ambiance/qmldir (+3/-0)
src/Ubuntu/Components/qmldir (+3/-0)
To merge this branch: bzr merge lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs
Reviewer Review Type Date Requested Status
PS Jenkins bot continuous-integration 2015-07-07 Approve on 2015-07-27
Tim Peeters 2015-07-07 Approve on 2015-07-27
Review via email: mp+264050@code.launchpad.net

This proposal supersedes a proposal from 2015-07-05.

Commit Message

Include Javascript libraries in QML documentation

Description of the Change

Note: I duplicated all Javascript files because docs don't include older API folders.

To post a comment you must log in.
PS Jenkins bot (ps-jenkins) wrote : Posted in a previous version of this proposal
review: Needs Fixing (continuous-integration)
PS Jenkins bot (ps-jenkins) wrote :
review: Needs Fixing (continuous-integration)
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs updated on 2015-07-17
1551. By Christian Dywan on 2015-07-17

Fix annotations and include popupUtils

1552. By Christian Dywan on 2015-07-17

Tweak the wording of popupUtils::open

PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
Tim Peeters (tpeeters) wrote :

111 -// Linearly project a value x from [xmin, xmax] into [ymin, ymax]
112 +/*!
113 + \qmlmethod getFlickableChild(item)
114 + Linearly project a value x from [xmin, xmax] into [ymin, ymax]
115 + */
116 function projectValue(x, xmin, xmax, ymin, ymax) {
117 return ((x - xmin) * ymax - (x - xmax) * ymin) / (xmax - xmin)
118 }

wrong function name.

Tim Peeters (tpeeters) wrote :

370 +/*!
371 + \qmlmethod mathUtils::getFlickableChild(item)
372 + Linearly project a value x from [xmin, xmax] into [ymin, ymax]
373 + */
374 +function projectValue(x, xmin, xmax, ymin, ymax) {
375 + return ((x - xmin) * ymax - (x - xmax) * ymin) / (xmax - xmin)
376 +}

Tim Peeters (tpeeters) :
review: Needs Fixing
Tim Peeters (tpeeters) wrote :

I think we need to evaluate which of these libraries we need to expose. I know that they are in the qmldir now, but colorUtils, dateUtils, scrollbarUtils, sliderUtils have functions that are just meant to be used inside the components.

review: Needs Information
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs updated on 2015-07-23
1553. By Christian Dywan on 2015-07-23

Move Slider-/ Scrollbar-/ ColorUtils into Ambiance for 1.3

These are all internal components.

1554. By Christian Dywan on 2015-07-23

Fix types in qmldir of Ambiance theme

PS Jenkins bot (ps-jenkins) wrote :
review: Needs Fixing (continuous-integration)
PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
Tim Peeters (tpeeters) wrote :

sync with staging first to get the new directory structure.

review: Needs Fixing
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs updated on 2015-07-24
1555. By Christian Dywan on 2015-07-24

Merge lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/staging

1556. By Christian Dywan on 2015-07-24

Add js files to .pro files

PS Jenkins bot (ps-jenkins) wrote :
review: Needs Fixing (continuous-integration)
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs updated on 2015-07-24
1557. By Christian Dywan on 2015-07-24

Merge lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/staging

Tim Peeters (tpeeters) wrote :

17 -Ubuntu.Components.MathUtils 0.1 1.0
18 +Ubuntu.Components.MathUtils 0.1 1.0 1.3

Why is 1.3 added here, while you define it for 1.2?

47 === modified file 'src/Ubuntu/Components/1.2/mathUtils.js'
48 --- src/Ubuntu/Components/1.2/mathUtils.js 2015-04-30 08:32:44 +0000
49 +++ src/Ubuntu/Components/1.2/mathUtils.js 2015-07-24 17:23:20 +0000
50 @@ -14,9 +14,19 @@
51 * along with this program. If not, see <http://www.gnu.org/licenses/>.
52 */
53
54 +/*!
55 + \qmltype mathUtils
56 + \inqmlmodule Ubuntu.Components 1.2
57 + \ingroup ubuntu
58 + \brief Various mathematical utility functions.
59 + */
60 +

Tim Peeters (tpeeters) wrote :

122 +/*!
123 + \qmltype colorUtils
124 + \inqmlmodule Ubuntu.Components 1.3
125 + \ingroup ubuntu
126 + \brief Various chromatic utility functions.
127 + */
128

Didn't we agree to make colorUtils internal? If needed, with a second internal copy in Ambience?

Tim Peeters (tpeeters) wrote :

Ok, MathUtils was added in 1.3 as well.. any ideas why the components.api does not add 1.2?

> 17 -Ubuntu.Components.MathUtils 0.1 1.0
> 18 +Ubuntu.Components.MathUtils 0.1 1.0 1.3
>
> Why is 1.3 added here, while you define it for 1.2?
>
> 47 === modified file 'src/Ubuntu/Components/1.2/mathUtils.js'
> 48 --- src/Ubuntu/Components/1.2/mathUtils.js 2015-04-30 08:32:44
> +0000
> 49 +++ src/Ubuntu/Components/1.2/mathUtils.js 2015-07-24 17:23:20
> +0000
> 50 @@ -14,9 +14,19 @@
> 51 * along with this program. If not, see
> <http://www.gnu.org/licenses/>.
> 52 */
> 53
> 54 +/*!
> 55 + \qmltype mathUtils
> 56 + \inqmlmodule Ubuntu.Components 1.2
> 57 + \ingroup ubuntu
> 58 + \brief Various mathematical utility functions.
> 59 + */
> 60 +

Tim Peeters (tpeeters) wrote :

I'm having a failure with 'make docs':
http://pastebin.ubuntu.com/11931417/

PS Jenkins bot (ps-jenkins) wrote :
review: Needs Fixing (continuous-integration)
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/jsDocs updated on 2015-07-24
1558. By Christian Dywan on 2015-07-24

Change excluse dir in ubuntu-ui-toolkit-common.qdocconf

1559. By Christian Dywan on 2015-07-24

qdoc tweaks

PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
Tim Peeters (tpeeters) wrote :

good, thanks.

review: Approve
PS Jenkins bot (ps-jenkins) :
review: Approve (continuous-integration)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'components.api'
2--- components.api 2015-07-24 13:31:03 +0000
3+++ components.api 2015-07-24 18:25:45 +0000
4@@ -270,7 +270,7 @@
5 property url source
6 property QSizeF sourceSize
7 readonly property int status
8-Ubuntu.Components.DateUtils 0.1 1.0
9+Ubuntu.Components.DateUtils 0.1 1.0 1.3
10 Ubuntu.Components.Popups.DefaultSheet 1.0 0.1: SheetBase
11 property bool doneButton
12 signal closeClicked()
13@@ -494,7 +494,7 @@
14 Ubuntu.Components.MainView 1.3: MainViewBase
15 property bool automaticOrientation
16 default readonly property QtObject contentsItem
17-Ubuntu.Components.MathUtils 0.1 1.0
18+Ubuntu.Components.MathUtils 0.1 1.0 1.3
19 Ubuntu.Components.MimeData 1.0 0.1: QtObject
20 property color color
21 property var data
22@@ -740,7 +740,7 @@
23 property bool grabDismissAreaEvents
24 function var show()
25 function var hide()
26-Ubuntu.Components.Popups.PopupUtils 0.1 1.0
27+Ubuntu.Components.Popups.PopupUtils 0.1 1.0 1.3
28 Ubuntu.Components.ProgressBar 1.0 0.1: AnimatedItem
29 property bool indeterminate
30 property double maximumValue
31
32=== modified file 'documentation/ubuntu-ui-toolkit-common.qdocconf'
33--- documentation/ubuntu-ui-toolkit-common.qdocconf 2015-05-19 09:41:12 +0000
34+++ documentation/ubuntu-ui-toolkit-common.qdocconf 2015-07-24 18:25:45 +0000
35@@ -21,8 +21,9 @@
36 excludedirs += ../src/Ubuntu/Components/Popups/1.2
37 excludedirs += ../src/Ubuntu/Components/Themes/Ambiance
38 excludedirs += ../src/Ubuntu/Components/Themes/SuruDark
39+excludedirs += ../documentation/autopilot-helpers/_build/html/_static
40 imagedirs = images
41-sources.fileextensions = "*.qml *.qdoc *.cpp"
42+sources.fileextensions = "*.qml *.qdoc *.cpp *.js"
43 headers.fileextensions = "*.h"
44 # exclude qml files that have the component documented in a separate qdoc file
45 excludefiles = $BLD/../src/Ubuntu/Components/MainView.qml
46
47=== modified file 'src/Ubuntu/Components/1.2/mathUtils.js'
48--- src/Ubuntu/Components/1.2/mathUtils.js 2015-04-30 08:32:44 +0000
49+++ src/Ubuntu/Components/1.2/mathUtils.js 2015-07-24 18:25:45 +0000
50@@ -14,9 +14,19 @@
51 * along with this program. If not, see <http://www.gnu.org/licenses/>.
52 */
53
54+/*!
55+ \qmltype mathUtils
56+ \inqmlmodule Ubuntu.Components 1.2
57+ \ingroup ubuntu
58+ \brief Various mathematical utility functions.
59+ */
60+
61 .pragma library
62
63-// Ensure the value x is between min and max
64+/*!
65+ \qmlmethod clamp(x, min, max)
66+ Ensure the value x is between min and max
67+ */
68 function clamp(x, min, max) {
69 if (min <= max) {
70 return Math.max(min, Math.min(x, max));
71@@ -26,17 +36,26 @@
72 }
73 }
74
75-// Get the linear interpolation
76+/*!
77+ \qmlmethod lerp(delta, from, to)
78+ Get the linear interpolation
79+ */
80 function lerp(delta, from, to) {
81 return ((1.0 - delta) * from) + (delta * to);
82 }
83
84-// Linearly project a value x from [xmin, xmax] into [ymin, ymax]
85+/*!
86+ \qmlmethod getFlickableChild(item)
87+ Linearly project a value x from [xmin, xmax] into [ymin, ymax]
88+ */
89 function projectValue(x, xmin, xmax, ymin, ymax) {
90 return ((x - xmin) * ymax - (x - xmax) * ymin) / (xmax - xmin)
91 }
92
93-// Linearly project a value x, but in addition to projectValue it's clamped to xmin/xmax first
94+/*!
95+ \qmlmethod clampAndProject(x, xmin, xmax, ymin, ymax)
96+ Linearly project a value x, but in addition to projectValue it's clamped to xmin/xmax first
97+ */
98 function clampAndProject(x, xmin, xmax, ymin, ymax) {
99 return projectValue(clamp(x, xmin, xmax), xmin, xmax, ymin, ymax)
100 }
101
102=== added file 'src/Ubuntu/Components/1.3/colorUtils.js'
103--- src/Ubuntu/Components/1.3/colorUtils.js 1970-01-01 00:00:00 +0000
104+++ src/Ubuntu/Components/1.3/colorUtils.js 2015-07-24 18:25:45 +0000
105@@ -0,0 +1,37 @@
106+/*
107+ * Copyright (C) 2013-2015 Canonical, Ltd.
108+ *
109+ * This program is free software; you can redistribute it and/or modify
110+ * it under the terms of the GNU General Public License as published by
111+ * the Free Software Foundation; version 3.
112+ *
113+ * This program is distributed in the hope that it will be useful,
114+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
115+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
116+ * GNU General Public License for more details.
117+ *
118+ * You should have received a copy of the GNU General Public License
119+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
120+ */
121+
122+/*!
123+ \internal
124+ \qmltype colorUtils
125+ \inqmlmodule Ubuntu.Components 1.3
126+ \ingroup ubuntu
127+ \brief Various chromatic utility functions.
128+ */
129+
130+.pragma library
131+
132+/*!
133+ \qmlmethod colorUtils::luminance(hexcolor)
134+ Get the luminance for a color.
135+ */
136+function luminance(hexcolor){
137+ hexcolor = String(hexcolor)
138+ var r = parseInt(hexcolor.substr(1,2),16);
139+ var g = parseInt(hexcolor.substr(3,2),16);
140+ var b = parseInt(hexcolor.substr(5,2),16);
141+ return ((r*212)+(g*715)+(b*73))/1000/255;
142+}
143
144=== added file 'src/Ubuntu/Components/1.3/dateUtils.js'
145--- src/Ubuntu/Components/1.3/dateUtils.js 1970-01-01 00:00:00 +0000
146+++ src/Ubuntu/Components/1.3/dateUtils.js 2015-07-24 18:25:45 +0000
147@@ -0,0 +1,145 @@
148+/*
149+ * Copyright 2013-2015 Canonical Ltd.
150+ *
151+ * This program is free software; you can redistribute it and/or modify
152+ * it under the terms of the GNU Lesser General Public License as published by
153+ * the Free Software Foundation; version 3.
154+ *
155+ * This program is distributed in the hope that it will be useful,
156+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
157+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
158+ * GNU Lesser General Public License for more details.
159+ *
160+ * You should have received a copy of the GNU Lesser General Public License
161+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
162+ */
163+
164+/*!
165+ \qmltype dateUtils
166+ \inqmlmodule Ubuntu.Components 1.3
167+ \ingroup ubuntu
168+ \brief Various date utility functions.
169+ */
170+
171+.pragma library
172+
173+/*
174+ Extending Date with few prototypes
175+ */
176+Date.msPerDay = 86400e3
177+Date.msPerWeek = Date.msPerDay * 7
178+
179+/*!
180+ \qmlmethod Date::midnight()
181+ The function returns a Date object with the current date and hour set to
182+ midnight.
183+ */
184+Date.prototype.midnight = function() {
185+ this.setHours(0, 0, 0, 0);
186+ return this;
187+}
188+
189+/*!
190+ \qmlmethod Date::getInvalidDate()
191+ The function returns an invalid date object.
192+ Example of use:
193+ \code
194+ var invalidDate = Date.prototype.getInvalidDate.call();
195+ var otherInvalidDate = (new Date()).getInvalidDate();
196+ \endcode
197+ */
198+Date.prototype.getInvalidDate = function() {
199+ return new Date(-1, -1);
200+}
201+
202+/*!
203+ \qmlmethod Date::isValid()
204+ The function checks whether the date object is a valid one, meaning the year,
205+ month and date fields are positive numbers
206+ */
207+Date.prototype.isValid = function() {
208+ if (Object.prototype.toString.call(this) !== "[object Date]") {
209+ return false;
210+ }
211+ return (this.getFullYear() > 0) && (this.getMonth() >= 0) && (this.getDate() > 0);
212+}
213+
214+/*!
215+ \qmlmethod Date::daysInMonth()
216+ The function returns the number of days in the month set in the Date object.
217+ */
218+Date.prototype.daysInMonth = function() {
219+ return [
220+ 31/*an*/, 28/*Feb*/, 31/*Mar*/, 30/*Apr*/, 31/*May*/, 30/*Jun*/,
221+ 31/*Jul*/, 31/*Aug*/, 30/*Sep*/, 31/*Oct*/, 30/*Nov*/, 31/*Dec*/
222+ ][this.getMonth()] + (this.getMonth() === 1) * this.leapYear();
223+}
224+
225+/*!
226+ \qmlmethod Date::leapYear()
227+ The function checks whether the year in the Date object is a leap year or not.
228+ */
229+Date.prototype.leapYear = function() {
230+ var year = this.getFullYear();
231+ return year % 400 == 0 || (year % 100 !== 0 && year % 4 == 0);
232+}
233+
234+/*!
235+ \qmlmethod Date::monthsTo(date)
236+ The function returns the distance in months (not calendaristic months) between
237+ the Date object and the given one as parameter.
238+ */
239+Date.prototype.monthsTo = function(target) {
240+ return target.getMonth() - this.getMonth() + (12 * (target.getFullYear() - this.getFullYear()));
241+}
242+
243+/*!
244+ \qmlmethod Date::daysTo(date)
245+ Same as monthsTo, but returns the distance in days.
246+ */
247+Date.prototype.daysTo = function(target) {
248+ return !target.isValid() ? 0 : Math.ceil((target - this) / Date.msPerDay);
249+}
250+
251+/*!
252+ \qmlmethod Date::hoursTo(date)
253+ Same as monthsTo, but returns the distance in hours.
254+ */
255+Date.prototype.hoursTo = function(target) {
256+ return !target.isValid() ? 0 : Math.ceil((target.getTime() - this.getTime()) / (1000 * 60 * 60));
257+}
258+
259+/*!
260+ \qmlmethod Date::minutesTo(date)
261+ Same as monthsTo, but returns the distance in minutes.
262+ */
263+Date.prototype.minutesTo = function(target) {
264+ return !target.isValid() ? 0 : Math.ceil((target.getTime() - this.getTime()) / (1000 * 60));
265+}
266+
267+/*!
268+ \qmlmethod Date::secondsTo(date)
269+ Same as monthsTo, but returns the distance in seconds.
270+ */
271+Date.prototype.secondsTo = function(target) {
272+ return !target.isValid() ? 0 : Math.ceil((target.getTime() - this.getTime()) / 1000);
273+}
274+
275+/*!
276+ \qmlmethod Date::getWeek()
277+ The function returns the week number of the date stored in the object.
278+ */
279+Date.prototype.getWeek = function() {
280+ // Copy date so don't modify original
281+ var date = new Date(this);
282+ date.setHours(0, 0, 0, 0);
283+ // Set to nearest Thursday: current date + 4 - current day number
284+ // Make Sunday's day number 7
285+ date.setDate(date.getDate() + 4 - (date.getDay() || 7));
286+ // Get first day of year
287+ var yearStart = new Date(date.getFullYear(), 0, 1);
288+ // Calculate full weeks to nearest Thursday
289+ var weekNo = Math.ceil((((date - yearStart) / 86400000) + 1) / 7);
290+ // Return array of year and week number
291+ return weekNo;
292+}
293
294=== added file 'src/Ubuntu/Components/1.3/mathUtils.js'
295--- src/Ubuntu/Components/1.3/mathUtils.js 1970-01-01 00:00:00 +0000
296+++ src/Ubuntu/Components/1.3/mathUtils.js 2015-07-24 18:25:45 +0000
297@@ -0,0 +1,61 @@
298+/*
299+ * Copyright 2012-2015 Canonical Ltd.
300+ *
301+ * This program is free software; you can redistribute it and/or modify
302+ * it under the terms of the GNU Lesser General Public License as published by
303+ * the Free Software Foundation; version 3.
304+ *
305+ * This program is distributed in the hope that it will be useful,
306+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
307+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
308+ * GNU Lesser General Public License for more details.
309+ *
310+ * You should have received a copy of the GNU Lesser General Public License
311+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
312+ */
313+
314+/*!
315+ \qmltype mathUtils
316+ \inqmlmodule Ubuntu.Components 1.3
317+ \ingroup ubuntu
318+ \brief Various mathematical utility functions.
319+ */
320+
321+.pragma library
322+
323+/*!
324+ \qmlmethod mathUtils::clamp(x, min, max)
325+ Ensure the value x is between min and max
326+ */
327+function clamp(x, min, max) {
328+ if (min <= max) {
329+ return Math.max(min, Math.min(x, max));
330+ } else {
331+ // swap min/max if min > max
332+ return clamp(x, max, min);
333+ }
334+}
335+
336+/*!
337+ \qmlmethod mathUtils::lerp(delta, from, to)
338+ Get the linear interpolation
339+ */
340+function lerp(delta, from, to) {
341+ return ((1.0 - delta) * from) + (delta * to);
342+}
343+
344+/*!
345+ \qmlmethod mathUtils::projectValue(x, xmin, xmax, ymin, ymax)
346+ Linearly project a value x from [xmin, xmax] into [ymin, ymax]
347+ */
348+function projectValue(x, xmin, xmax, ymin, ymax) {
349+ return ((x - xmin) * ymax - (x - xmax) * ymin) / (xmax - xmin)
350+}
351+
352+/*!
353+ \qmlmethod mathUtils::clampAndProject(x, xmin, xmax, ymin, ymax)
354+ Linearly project a value x, but in addition to projectValue it's clamped to xmin/xmax first
355+ */
356+function clampAndProject(x, xmin, xmax, ymin, ymax) {
357+ return projectValue(clamp(x, xmin, xmax), xmin, xmax, ymin, ymax)
358+}
359
360=== modified file 'src/Ubuntu/Components/1.3/pageUtils.js'
361--- src/Ubuntu/Components/1.3/pageUtils.js 2015-04-25 08:54:58 +0000
362+++ src/Ubuntu/Components/1.3/pageUtils.js 2015-07-24 18:25:45 +0000
363@@ -15,6 +15,15 @@
364 */
365
366 /*!
367+ \qmltype pageUtils
368+ \inqmlmodule Ubuntu.Components 1.3
369+ \ingroup ubuntu
370+ \internal
371+ \brief Page-related utility functions.
372+ */
373+
374+/*!
375+ \qmlmethod pageUtils::isVerticalFlickable(object)
376 Return true if the object is a Flickable that can be flicked in vertical direction.
377 */
378 function isVerticalFlickable(object) {
379@@ -30,6 +39,7 @@
380 }
381
382 /*!
383+ \qmlmethod pageUtils::getFlickableChild(item)
384 Return the first child of the item that is flickable in the vertical direction.
385 */
386 function getFlickableChild(item) {
387
388=== modified file 'src/Ubuntu/Components/ComponentModule.pro'
389--- src/Ubuntu/Components/ComponentModule.pro 2015-07-24 13:32:17 +0000
390+++ src/Ubuntu/Components/ComponentModule.pro 2015-07-24 18:25:45 +0000
391@@ -93,12 +93,14 @@
392 1.3/CheckBox.qml \
393 1.3/ComboButton.qml \
394 1.3/CrossFadeImage.qml \
395+ 1.3/dateUtils.js \
396 1.3/DraggingArea.qml \
397 1.3/Header.qml \
398 1.3/InputHandler.qml \
399 1.3/Label.qml \
400 1.3/MainViewBase.qml \
401 1.3/MainView.qml \
402+ 1.3/mathUtils.js \
403 1.3/OptionSelectorDelegate.qml \
404 1.3/OptionSelector.qml \
405 1.3/OrientationHelper.qml \
406
407=== added file 'src/Ubuntu/Components/Popups/1.3/popupUtils.js'
408--- src/Ubuntu/Components/Popups/1.3/popupUtils.js 1970-01-01 00:00:00 +0000
409+++ src/Ubuntu/Components/Popups/1.3/popupUtils.js 2015-07-24 18:25:45 +0000
410@@ -0,0 +1,101 @@
411+/*
412+ * Copyright 2012 Canonical Ltd.
413+ *
414+ * This program is free software; you can redistribute it and/or modify
415+ * it under the terms of the GNU Lesser General Public License as published by
416+ * the Free Software Foundation; version 3.
417+ *
418+ * This program is distributed in the hope that it will be useful,
419+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
420+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
421+ * GNU Lesser General Public License for more details.
422+ *
423+ * You should have received a copy of the GNU Lesser General Public License
424+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
425+ */
426+
427+/*!
428+ \qmltype popupUtils
429+ \inqmlmodule Ubuntu.Components.Popups 1.0
430+ \ingroup ubuntu-popups
431+ \brief Popover utility functions.
432+*/
433+
434+/*!
435+ \qmlmethod popupUtils::open(popup, caller, params)
436+ The function creates and shows a popup object from either a \b Component or URL of a
437+ QML document. The caller drives the placement of the popup as well as the
438+ pointer's. The third parameter (param) can hold a series of properties configuring
439+ the popup to be opened. This can be any property defined by the popups and additional
440+ custom ones defined in derived popups.
441+
442+ \a caller should be given when a \l ComposerSheet or \l Dialog is specified using a URL
443+ and opened inside a \b Window. If not, the application's root item will be the dismiss area.
444+
445+ Returns a popop object, which can be closed using \l close.
446+
447+ \qml
448+ import Ubuntu.Components 1.3
449+ import Ubuntu.Components.Popups 1.3
450+
451+ Button {
452+ onClicked: PopupUtils.open(popoverComponent, popoverButton, { 'dummy': true } )
453+ }
454+ \endqml
455+
456+ See \l Popover, \l ComposerSheet and \l Dialog for their respective documentation and more examples.
457+ */
458+function open(popup, caller, params) {
459+ var popupComponent = null;
460+ var rootObject = null;
461+ if (popup.createObject) {
462+ // popup is a component and can create an object
463+ popupComponent = popup;
464+ rootObject = QuickUtils.rootItem(popup);
465+ } else if (typeof popup === "string") {
466+ popupComponent = Qt.createComponent(popup);
467+ rootObject = (caller !== undefined) ? QuickUtils.rootItem(caller) : QuickUtils.rootItem(null);
468+ } else {
469+ print("PopupUtils.open(): "+popup+" is not a component or a link");
470+ return null;
471+ }
472+
473+ var popupObject;
474+ if (params !== undefined) {
475+ popupObject = popupComponent.createObject(rootObject, params);
476+ } else {
477+ popupObject = popupComponent.createObject(rootObject);
478+ }
479+ if (!popupObject) {
480+ print(popupComponent.errorString().slice(0, -1));
481+ print("PopupUtils.open(): Failed to create the popup object.");
482+ return;
483+ } else if (popupObject.hasOwnProperty("caller") && caller)
484+ popupObject.caller = caller;
485+
486+ // if caller is specified, connect its cleanup to the popup's close
487+ // so popups will be removed together with the caller.
488+ if (caller)
489+ caller.Component.onDestruction.connect(popupObject.__closePopup);
490+
491+ popupObject.show();
492+ popupObject.onVisibleChanged.connect(popupObject.__closeIfHidden);
493+ return popupObject;
494+}
495+
496+/*!
497+ \qmlmethod popupUtils::close(popupObject)
498+ Closes (hides and destroys) the given popup.
499+
500+ \qml
501+ import Ubuntu.Components 1.3
502+ import Ubuntu.Components.Popups 1.3
503+
504+ Button {
505+ onClicked: PopupUtils.close(popup)
506+ }
507+ \endqml
508+ */
509+function close(popupObject) {
510+ popupObject.hide();
511+}
512
513=== modified file 'src/Ubuntu/Components/Popups/Popups.pro'
514--- src/Ubuntu/Components/Popups/Popups.pro 2015-05-19 09:23:01 +0000
515+++ src/Ubuntu/Components/Popups/Popups.pro 2015-07-24 18:25:45 +0000
516@@ -16,6 +16,7 @@
517 1.3/internalPopupUtils.js \
518 1.3/Popover.qml \
519 1.3/PopupBase.qml \
520+ 1.3/popupUtils.js \
521 1.3/SheetBase.qml
522
523 load(ubuntu_qml_module)
524
525=== modified file 'src/Ubuntu/Components/Popups/qmldir'
526--- src/Ubuntu/Components/Popups/qmldir 2015-05-02 13:27:39 +0000
527+++ src/Ubuntu/Components/Popups/qmldir 2015-07-24 18:25:45 +0000
528@@ -30,3 +30,4 @@
529 DefaultSheet 1.3 1.3/DefaultSheet.qml
530 ComposerSheet 1.3 1.3/ComposerSheet.qml
531 ActionSelectionPopover 1.3 1.3/ActionSelectionPopover.qml
532+PopupUtils 1.3 1.3/popupUtils.js
533
534=== added file 'src/Ubuntu/Components/Themes/Ambiance/1.3/colorUtils.js'
535--- src/Ubuntu/Components/Themes/Ambiance/1.3/colorUtils.js 1970-01-01 00:00:00 +0000
536+++ src/Ubuntu/Components/Themes/Ambiance/1.3/colorUtils.js 2015-07-24 18:25:45 +0000
537@@ -0,0 +1,36 @@
538+/*
539+ * Copyright (C) 2013-2015 Canonical, Ltd.
540+ *
541+ * This program is free software; you can redistribute it and/or modify
542+ * it under the terms of the GNU General Public License as published by
543+ * the Free Software Foundation; version 3.
544+ *
545+ * This program is distributed in the hope that it will be useful,
546+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
547+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
548+ * GNU General Public License for more details.
549+ *
550+ * You should have received a copy of the GNU General Public License
551+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
552+ */
553+
554+/*!
555+ \qmltype colorUtils
556+ \inqmlmodule Ubuntu.Components 1.3
557+ \ingroup ubuntu
558+ \brief Various chromatic utility functions.
559+ */
560+
561+.pragma library
562+
563+/*!
564+ \qmlmethod colorUtils::luminance(hexcolor)
565+ Get the luminance for a color.
566+ */
567+function luminance(hexcolor){
568+ hexcolor = String(hexcolor)
569+ var r = parseInt(hexcolor.substr(1,2),16);
570+ var g = parseInt(hexcolor.substr(3,2),16);
571+ var b = parseInt(hexcolor.substr(5,2),16);
572+ return ((r*212)+(g*715)+(b*73))/1000/255;
573+}
574
575=== added file 'src/Ubuntu/Components/Themes/Ambiance/1.3/scrollbarUtils.js'
576--- src/Ubuntu/Components/Themes/Ambiance/1.3/scrollbarUtils.js 1970-01-01 00:00:00 +0000
577+++ src/Ubuntu/Components/Themes/Ambiance/1.3/scrollbarUtils.js 2015-07-24 18:25:45 +0000
578@@ -0,0 +1,139 @@
579+/*
580+ * Copyright 2012-2015 Canonical Ltd.
581+ *
582+ * This program is free software; you can redistribute it and/or modify
583+ * it under the terms of the GNU Lesser General Public License as published by
584+ * the Free Software Foundation; version 3.
585+ *
586+ * This program is distributed in the hope that it will be useful,
587+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
588+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
589+ * GNU Lesser General Public License for more details.
590+ *
591+ * You should have received a copy of the GNU Lesser General Public License
592+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
593+ */
594+
595+/*!
596+ \qmltype scrollbarUtils
597+ \inqmlmodule Ubuntu.Components 1.3
598+ \ingroup ubuntu
599+ \brief Various scrolling utility functions.
600+ */
601+
602+.pragma library
603+
604+Qt.include("mathUtils.js")
605+
606+/*
607+ Object storing property names used in calculations.
608+ */
609+var _obj = {
610+ scrollbar: null,
611+ vertical: false,
612+ propOrigin: "",
613+ propContent: "",
614+ propPosRatio: "",
615+ propSizeRatio: "",
616+ propCoordinate: "",
617+ propSize: "",
618+ refresh: function () {
619+ _obj.vertical = (_obj.scrollbar.align === Qt.AlignLeading) || (_obj.scrollbar.align === Qt.AlignTrailing)
620+ _obj.propOrigin = (_obj.vertical) ? "originY" : "originX";
621+ _obj.propContent = (_obj.vertical) ? "contentY" : "contentX";
622+ _obj.propPosRatio = (_obj.vertical) ? "yPosition" : "xPosition";
623+ _obj.propSizeRatio = (_obj.vertical) ? "heightRatio" : "widthRatio";
624+ _obj.propCoordinate = (_obj.vertical) ? "y" : "x";
625+ _obj.propSize = (_obj.vertical) ? "height" : "width";
626+ }
627+}
628+
629+/*
630+ Checks whether the _obj is valid or not. Must be called in every function
631+ as those can be invoked prior to the host (style) component completion.
632+ */
633+function __check(sb) {
634+ if (sb !== null && (_obj.scrollbar !== sb)) {
635+ _obj.scrollbar = sb;
636+ sb.flickableItemChanged.connect(_obj.refresh);
637+ sb.alignChanged.connect(_obj.refresh);
638+ _obj.refresh();
639+ }
640+
641+ return _obj.scrollbar;
642+}
643+
644+/*!
645+ \qmlmethod scrollbarUtils::isVertical(scrollbar)
646+ Returns whether the scrollbar is vertical or horizontal.
647+ */
648+function isVertical(scrollbar) {
649+ if (!__check(scrollbar)) return 0;
650+ return _obj.vertical;
651+}
652+
653+/*!
654+ \qmlmethod scrollbarUtils::sliderPos(scrollbar, min, max)
655+ Calculates the slider position based on the visible area's ratios.
656+ */
657+function sliderPos(scrollbar, min, max) {
658+ if (!__check(scrollbar)) return 0;
659+ return clamp(scrollbar.flickableItem.visibleArea[_obj.propPosRatio] * scrollbar.flickableItem[_obj.propSize], min, max);
660+}
661+
662+/*!
663+ \qmlmethod scrollbarUtils::sliderSize(scrollbar, min, max)
664+ Calculates the slider size for ListViews based on the visible area's position
665+ and size ratios, clamping it between min and max.
666+
667+ The function can be used in Scrollbar styles to calculate the size of the slider.
668+ */
669+function sliderSize(scrollbar, min, max) {
670+ if (!__check(scrollbar)) return 0;
671+ var sizeRatio = scrollbar.flickableItem.visibleArea[_obj.propSizeRatio];
672+ var posRatio = scrollbar.flickableItem.visibleArea[_obj.propPosRatio];
673+ var sizeUnderflow = (sizeRatio * max) < min ? min - (sizeRatio * max) : 0
674+ var startPos = posRatio * (max - sizeUnderflow)
675+ var endPos = (posRatio + sizeRatio) * (max - sizeUnderflow) + sizeUnderflow
676+ var overshootStart = startPos < 0 ? -startPos : 0
677+ var overshootEnd = endPos > max ? endPos - max : 0
678+
679+ // overshoot adjusted start and end
680+ var adjustedStartPos = startPos + overshootStart
681+ var adjustedEndPos = endPos - overshootStart - overshootEnd
682+
683+ // final position and size of thumb
684+ var position = adjustedStartPos + min > max ? max - min : adjustedStartPos
685+ var result = (adjustedEndPos - position) < min ? min : (adjustedEndPos - position)
686+
687+ return result;
688+}
689+
690+/*!
691+ \qmlmethod scrollbarUtils::scrollAndClamp(scrollbar, amount, min, max)
692+ The function calculates and clamps the position to be scrolled to the minimum
693+ and maximum values.
694+
695+ The scroll and drag functions require a slider that does not have any minimum
696+ size set (meaning the minimum is set to 0.0). Implementations should consider
697+ using an invisible cursor to drag the slider and the ListView position.
698+ */
699+function scrollAndClamp(scrollbar, amount, min, max) {
700+ if (!__check(scrollbar)) return 0;
701+ return scrollbar.flickableItem[_obj.propOrigin] +
702+ clamp(scrollbar.flickableItem[_obj.propContent] - scrollbar.flickableItem[_obj.propOrigin] + amount,
703+ min, max);
704+}
705+
706+/*!
707+ \qmlmethod scrollbarUtils::dragAndClamp(scrollbar, cursor, contentSize, pageSize)
708+ The function calculates the new position of the dragged slider. The amount is
709+ relative to the contentSize, which is either the flickable's contentHeight or
710+ contentWidth or other calculated value, depending on its orientation. The pageSize
711+ specifies the visibleArea, and it is usually the heigtht/width of the scrolling area.
712+ */
713+function dragAndClamp(scrollbar, cursor, contentSize, pageSize) {
714+ if (!__check(scrollbar)) return 0;
715+ scrollbar.flickableItem[_obj.propContent] =
716+ scrollbar.flickableItem[_obj.propOrigin] + cursor[_obj.propCoordinate] * contentSize / pageSize;
717+}
718
719=== added file 'src/Ubuntu/Components/Themes/Ambiance/1.3/sliderUtils.js'
720--- src/Ubuntu/Components/Themes/Ambiance/1.3/sliderUtils.js 1970-01-01 00:00:00 +0000
721+++ src/Ubuntu/Components/Themes/Ambiance/1.3/sliderUtils.js 2015-07-24 18:25:45 +0000
722@@ -0,0 +1,48 @@
723+/*
724+ * Copyright 2013-2015 Canonical Ltd.
725+ *
726+ * This program is free software; you can redistribute it and/or modify
727+ * it under the terms of the GNU Lesser General Public License as published by
728+ * the Free Software Foundation; version 3.
729+ *
730+ * This program is distributed in the hope that it will be useful,
731+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
732+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
733+ * GNU Lesser General Public License for more details.
734+ *
735+ * You should have received a copy of the GNU Lesser General Public License
736+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
737+ */
738+
739+/*!
740+ \qmltype sliderUtils
741+ \inqmlmodule Ubuntu.Components 1.3
742+ \ingroup ubuntu
743+ \brief Various sliding utility functions.
744+ */
745+
746+.pragma library
747+
748+/*!
749+ \qmlmethod sliderUtils::liveValue(item)
750+ The function returns the live value of the slider.
751+ */
752+function liveValue(item) {
753+ return item.__internals.liveValue;
754+}
755+
756+/*!
757+ \qmlmethod sliderUtils::normalizedValue(item)
758+ The function returns the normalized live value of the slider.
759+ */
760+function normalizedValue(item) {
761+ return item.__internals.normalizedValue;
762+}
763+
764+/*!
765+ \qmlmethod sliderUtils::isPressed(item)
766+ The function returns whether the slider is being pressed or not.
767+ */
768+function isPressed(item) {
769+ return item.__internals.isPressed;
770+}
771
772=== modified file 'src/Ubuntu/Components/Themes/Ambiance/qmldir'
773--- src/Ubuntu/Components/Themes/Ambiance/qmldir 2015-05-12 13:41:39 +0000
774+++ src/Ubuntu/Components/Themes/Ambiance/qmldir 2015-07-24 18:25:45 +0000
775@@ -81,3 +81,6 @@
776 CheckBoxStyle 1.3 ./1.3/CheckBoxStyle.qml
777
778 ListItemStyle 1.3 ./1.3/ListItemStyle.qml
779+internal SliderUtils 1.3/sliderUtils.js
780+internal ScrollbarUtils 1.3/scrollbarUtils.js
781+internal ColorUtils 1.3/colorUtils.js
782
783=== modified file 'src/Ubuntu/Components/qmldir'
784--- src/Ubuntu/Components/qmldir 2015-07-24 13:31:03 +0000
785+++ src/Ubuntu/Components/qmldir 2015-07-24 18:25:45 +0000
786@@ -141,4 +141,7 @@
787 PullToRefresh 1.3 1.3/PullToRefresh.qml
788 UbuntuListView 1.3 1.3/UbuntuListView11.qml
789 Captions 1.3 1.3/Captions.qml
790+MathUtils 1.3 1.3/mathUtils.js
791+internal ColorUtils 1.3/colorUtils.js
792+DateUtils 1.3 1.3/dateUtils.js
793 BottomEdgeHint 1.3 1.3/BottomEdgeHint.qml

Subscribers

People subscribed via source and target branches