• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • kde-runtime API Reference
  • KDE Home
  • Contact Us
 

PlasmaComponents

  • sources
  • kde-4.14
  • kde-runtime
  • plasma
  • declarativeimports
  • plasmacomponents
  • qml
PageStack.qml
Go to the documentation of this file.
1 /****************************************************************************
2 **
3 ** Copyright (C) 2011 Marco Martin <mart@kde.org>
4 **
5 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
6 ** All rights reserved.
7 ** Contact: Nokia Corporation (qt-info@nokia.com)
8 **
9 ** This file is part of the Qt Components project.
10 **
11 ** $QT_BEGIN_LICENSE:BSD$
12 ** You may use this file under the terms of the BSD license as follows:
13 **
14 ** "Redistribution and use in source and binary forms, with or without
15 ** modification, are permitted provided that the following conditions are
16 ** met:
17 ** * Redistributions of source code must retain the above copyright
18 ** notice, this list of conditions and the following disclaimer.
19 ** * Redistributions in binary form must reproduce the above copyright
20 ** notice, this list of conditions and the following disclaimer in
21 ** the documentation and/or other materials provided with the
22 ** distribution.
23 ** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
24 ** the names of its contributors may be used to endorse or promote
25 ** products derived from this software without specific prior written
26 ** permission.
27 **
28 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
39 ** $QT_END_LICENSE$
40 **
41 ****************************************************************************/
42 
43 // The PageStack item defines a container for pages and a stack-based
44 // navigation model. Pages can be defined as QML items or components.
45 
46 import QtQuick 1.1
47 import "." 0.1
48 import "private/PageStack.js" as Engine
49 
58 Item {
59  id: root
60 
61  width: parent ? parent.width : 0
62  height: parent ? parent.height : 0
63 
65  property int depth: Engine.getDepth()
66 
68  property Item currentPage: null
69 
79  property ToolBar toolBar
80 
85  property variant initialPage
86 
88  property bool busy: internal.ongoingTransitionCount > 0
89 
117  function push(page, properties, immediate)
118  {
119  return Engine.push(page, properties, false, immediate);
120  }
121 
131  function pop(page, immediate)
132  {
133  return Engine.pop(page, immediate);
134  }
135 
151  function replace(page, properties, immediate)
152  {
153  return Engine.push(page, properties, true, immediate);
154  }
155 
157  function clear()
158  {
159  return Engine.clear();
160  }
161 
171  function find(func)
172  {
173  return Engine.find(func);
174  }
175 
176  implicitWidth: currentPage ? currentPage.implicitWidth : 0
177  implicitHeight: currentPage ? currentPage.implicitHeight : 0
178 
179  // Called when the page stack visibility changes.
180  onVisibleChanged: {
181  if (currentPage) {
182  internal.setPageStatus(currentPage, visible ? PageStatus.Active : PageStatus.Inactive);
183  if (visible)
184  currentPage.visible = currentPage.parent.visible = true;
185  }
186  }
187 
188  onInitialPageChanged: {
189  if (!internal.completed) {
190  return
191  }
192 
193  if (initialPage) {
194  if (depth == 0) {
195  push(initialPage, null, true)
196  } else if (depth == 1) {
197  replace(initialPage, null, true)
198  } else {
199  console.log("Cannot update PageStack.initialPage")
200  }
201  }
202  }
203 
204  Component.onCompleted: {
205  internal.completed = true
206  if (initialPage && depth == 0)
207  push(initialPage, null, true)
208  }
209 
210  QtObject {
211  id: internal
212 
213  // The number of ongoing transitions.
214  property int ongoingTransitionCount: 0
215 
216  //FIXME: there should be a way to access to theh without storing it in an ugly way
217  property bool completed: false
218 
219  // Sets the page status.
220  function setPageStatus(page, status)
221  {
222  if (page != null) {
223  if (page.status !== undefined) {
224  if (status == PageStatus.Active && page.status == PageStatus.Inactive)
225  page.status = PageStatus.Activating;
226  else if (status == PageStatus.Inactive && page.status == PageStatus.Active)
227  page.status = PageStatus.Deactivating;
228 
229  page.status = status;
230  }
231  }
232  }
233  }
234 
235  // Component for page containers.
236  Component {
237  id: containerComponent
238 
239  Item {
240  id: container
241 
242  width: parent ? parent.width : 0
243  height: parent ? parent.height : 0
244 
245  // The actual parent of page: page will anchor to that
246  // in this case is container itself, not the case for PageRow
247  property Item pageParent: container
248 
249  // The states correspond to the different possible positions of the container.
250  state: "Hidden"
251 
252  // The page held by this container.
253  property Item page: null
254 
255  // The owner of the page.
256  property Item owner: null
257 
258  // The width of the longer stack dimension
259  property int stackWidth: Math.max(root.width, root.height)
260 
261  // Duration of transition animation (in ms)
262  property int transitionDuration: 250
263 
264  // Flag that indicates the container should be cleaned up after the transition has ended.
265  property bool cleanupAfterTransition: false
266 
267  // Flag that indicates if page transition animation is running
268  property bool transitionAnimationRunning: false
269 
270  // State to be set after previous state change animation has finished
271  property string pendingState: "none"
272 
273  // Ensures that transition finish actions are executed
274  // in case the object is destroyed before reaching the
275  // end state of an ongoing transition
276  Component.onDestruction: {
277  if (transitionAnimationRunning)
278  transitionEnded();
279  }
280 
281  // Sets pending state as current if state change is delayed
282  onTransitionAnimationRunningChanged: {
283  if (!transitionAnimationRunning && pendingState != "none") {
284  state = pendingState;
285  pendingState = "none";
286  }
287  }
288 
289  // Handles state change depening on transition animation status
290  function setState(newState)
291  {
292  if (transitionAnimationRunning)
293  pendingState = newState;
294  else
295  state = newState;
296  }
297 
298  // Performs a push enter transition.
299  function pushEnter(immediate, orientationChanges)
300  {
301  if (!immediate) {
302  if (orientationChanges)
303  setState("LandscapeRight");
304  else
305  setState("Right");
306  }
307  setState("");
308  page.visible = true;
309  if (root.visible && immediate)
310  internal.setPageStatus(page, PageStatus.Active);
311  }
312 
313  // Performs a push exit transition.
314  function pushExit(replace, immediate, orientationChanges)
315  {
316  if (orientationChanges)
317  setState(immediate ? "Hidden" : "LandscapeLeft");
318  else
319  setState(immediate ? "Hidden" : "Left");
320  if (root.visible && immediate)
321  internal.setPageStatus(page, PageStatus.Inactive);
322  if (replace) {
323  if (immediate)
324  cleanup();
325  else
326  cleanupAfterTransition = true;
327  }
328  }
329 
330  // Performs a pop enter transition.
331  function popEnter(immediate, orientationChanges)
332  {
333  if (!immediate)
334  state = orientationChanges ? "LandscapeLeft" : "Left";
335  setState("");
336  page.visible = true;
337  if (root.visible && immediate)
338  internal.setPageStatus(page, PageStatus.Active);
339  }
340 
341  // Performs a pop exit transition.
342  function popExit(immediate, orientationChanges)
343  {
344  if (orientationChanges)
345  setState(immediate ? "Hidden" : "LandscapeRight");
346  else
347  setState(immediate ? "Hidden" : "Right");
348 
349  if (root.visible && immediate)
350  internal.setPageStatus(page, PageStatus.Inactive);
351  if (immediate)
352  cleanup();
353  else
354  cleanupAfterTransition = true;
355  }
356 
357  // Called when a transition has started.
358  function transitionStarted()
359  {
360  transitionAnimationRunning = true;
361  internal.ongoingTransitionCount++;
362  if (root.visible) {
363  internal.setPageStatus(page, (state == "") ? PageStatus.Activating : PageStatus.Deactivating);
364  }
365  }
366 
367  // Called when a transition has ended.
368  function transitionEnded()
369  {
370  if (state != "")
371  state = "Hidden";
372  if (root.visible)
373  internal.setPageStatus(page, (state == "") ? PageStatus.Active : PageStatus.Inactive);
374 
375  internal.ongoingTransitionCount--;
376  transitionAnimationRunning = false;
377  if (cleanupAfterTransition)
378  cleanup();
379  }
380 
381  states: [
382  // Explicit properties for default state.
383  State {
384  name: ""
385  PropertyChanges { target: container; visible: true; opacity: 1 }
386  },
387  // Start state for pop entry, end state for push exit.
388  State {
389  name: "Left"
390  PropertyChanges { target: container; x: -width / 2; opacity: 0 }
391  },
392  // Start state for pop entry, end state for push exit
393  // when exiting portrait and entering landscape.
394  State {
395  name: "LandscapeLeft"
396  PropertyChanges { target: container; x: -stackWidth / 2; opacity: 0 }
397  },
398  // Start state for push entry, end state for pop exit.
399  State {
400  name: "Right"
401  PropertyChanges { target: container; x: width / 2; opacity: 0 }
402  },
403  // Start state for push entry, end state for pop exit
404  // when exiting portrait and entering landscape.
405  State {
406  name: "LandscapeRight"
407  PropertyChanges { target: container; x: stackWidth / 2; opacity: 0 }
408  },
409  // Inactive state.
410  State {
411  name: "Hidden"
412  PropertyChanges { target: container; visible: false }
413  }
414  ]
415 
416  transitions: [
417  // Push exit transition
418  Transition {
419  from: ""; to: "Left"
420  SequentialAnimation {
421  ScriptAction { script: transitionStarted() }
422  ParallelAnimation {
423  PropertyAnimation { properties: "x"; easing.type: Easing.InQuad; duration: transitionDuration }
424  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
425  }
426  ScriptAction { script: transitionEnded() }
427  }
428  },
429  // Pop entry transition
430  Transition {
431  from: "Left"; to: ""
432  SequentialAnimation {
433  ScriptAction { script: transitionStarted() }
434  ParallelAnimation {
435  PropertyAnimation { properties: "x"; easing.type: Easing.OutQuad; duration: transitionDuration }
436  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
437  }
438  ScriptAction { script: transitionEnded() }
439  }
440  },
441  // Push exit transition landscape
442  Transition {
443  from: ""; to: "LandscapeLeft"
444  SequentialAnimation {
445  ScriptAction { script: transitionStarted() }
446  ParallelAnimation {
447  PropertyAnimation { properties: "x"; easing.type: Easing.InQuad; duration: transitionDuration }
448  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
449  }
450  ScriptAction { script: transitionEnded() }
451  }
452  },
453  // Pop entry transition landscape
454  Transition {
455  from: "LandscapeLeft"; to: ""
456  SequentialAnimation {
457  ScriptAction { script: transitionStarted() }
458  ParallelAnimation {
459  PropertyAnimation { properties: "x"; easing.type: Easing.OutQuad; duration: transitionDuration }
460  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
461  }
462  ScriptAction { script: transitionEnded() }
463  }
464  },
465  // Pop exit transition
466  Transition {
467  from: ""; to: "Right"
468  SequentialAnimation {
469  ScriptAction { script: transitionStarted() }
470  ParallelAnimation {
471  PropertyAnimation { properties: "x"; easing.type: Easing.InQuad; duration: transitionDuration }
472  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
473  }
474  // Workaround for transition animation bug causing ghost view with page pop transition animation
475  // TODO: Root cause still unknown
476  PropertyAnimation {}
477  ScriptAction { script: transitionEnded() }
478  }
479  },
480  // Push entry transition
481  Transition {
482  from: "Right"; to: ""
483  SequentialAnimation {
484  ScriptAction { script: transitionStarted() }
485  ParallelAnimation {
486  PropertyAnimation { properties: "x"; easing.type: Easing.OutQuad; duration: transitionDuration }
487  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
488  }
489  ScriptAction { script: transitionEnded() }
490  }
491  },
492  // Pop exit transition landscape
493  Transition {
494  from: ""; to: "LandscapeRight"
495  SequentialAnimation {
496  ScriptAction { script: transitionStarted() }
497  ParallelAnimation {
498  PropertyAnimation { properties: "x"; easing.type: Easing.InQuad; duration: transitionDuration }
499  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
500  }
501  // Workaround for transition animation bug causing ghost view with page pop transition animation
502  // TODO: Root cause still unknown
503  PropertyAnimation {}
504  ScriptAction { script: transitionEnded() }
505  }
506  },
507  // Push entry transition landscape
508  Transition {
509  from: "LandscapeRight"; to: ""
510  SequentialAnimation {
511  ScriptAction { script: transitionStarted() }
512  ParallelAnimation {
513  PropertyAnimation { properties: "x"; easing.type: Easing.OutQuad; duration: transitionDuration }
514  PropertyAnimation { properties: "opacity"; easing.type: Easing.Linear; duration: transitionDuration }
515  }
516  ScriptAction { script: transitionEnded() }
517  }
518  }
519  ]
520 
521  // Cleans up the container and then destroys it.
522  function cleanup()
523  {
524  if (page != null) {
525  if (page.status == PageStatus.Active) {
526  internal.setPageStatus(page, PageStatus.Inactive)
527  }
528  }
529 
530  container.destroy();
531  }
532  }
533  }
534 }
535 
PageStatus::Activating
Definition: enums.h:64
PageStatus::Active
Definition: enums.h:65
PageStatus
Definition: enums.h:56
ToolBar
A plasma theme based toolbar.
Definition: ToolBar.qml:25
Item
PageStatus::Deactivating
Definition: enums.h:66
PageStatus::Inactive
Definition: enums.h:63
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Jun 22 2020 13:08:40 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

PlasmaComponents

Skip menu "PlasmaComponents"
  • Main Page
  • Namespace List
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List

kde-runtime API Reference

Skip menu "kde-runtime API Reference"
  • KCMShell
  • KNotify
  • Plasma Runtime
  •     PlasmaCore
  •     DragAndDrop
  •     PlasmaComponents
  •     PlasmaExtraComponents
  •     QtExtraComponents

Search



Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal