doc: note that calling methods before component completion may have no effect

So use Component.onCompleted:

3 files changed, 36 insertions, 0 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp
index 8e53237..14980a8 100644
--- a/src/declarative/graphicsitems/qdeclarativegridview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp
@@ -1919,6 +1919,8 @@ void QDeclarativeGridView::keyPressEvent(QKeyEvent *event)
     Move the currentIndex up one item in the view.
     The current index will wrap if keyNavigationWraps is true and it
     is currently at the end.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexUp()
 {
@@ -1942,6 +1944,8 @@ void QDeclarativeGridView::moveCurrentIndexUp()
     Move the currentIndex down one item in the view.
     The current index will wrap if keyNavigationWraps is true and it
     is currently at the end.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexDown()
 {
@@ -1965,6 +1969,8 @@ void QDeclarativeGridView::moveCurrentIndexDown()
     Move the currentIndex left one item in the view.
     The current index will wrap if keyNavigationWraps is true and it
     is currently at the end.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexLeft()
 {
@@ -1988,6 +1994,8 @@ void QDeclarativeGridView::moveCurrentIndexLeft()
     Move the currentIndex right one item in the view.
     The current index will wrap if keyNavigationWraps is true and it
     is currently at the end.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexRight()
 {
@@ -2028,6 +2036,14 @@ void QDeclarativeGridView::moveCurrentIndexRight()
     at a particular index.  This is unreliable since removing items from the start
     of the view does not cause all other items to be repositioned.
     The correct way to bring an item into view is with \c positionViewAtIndex.
+
+    \bold Note: methods should only be called after the Component has completed.  To position
+    the view at startup, this method should be called by Component.onCompleted.  For
+    example, to position the view at the end:
+
+    \code
+    Component.onCompleted: positionViewAtIndex(count - 1, GridView.Beginning)
+    \endcode
 */
 void QDeclarativeGridView::positionViewAtIndex(int index, int mode)
 {
@@ -2097,6 +2113,8 @@ void QDeclarativeGridView::positionViewAtIndex(int index, int mode)
 
     If the item is outside the visible area, -1 is returned, regardless of
     whether an item will exist at that point when scrolled into view.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 int QDeclarativeGridView::indexAt(int x, int y) const
 {
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index 35e6bab..35794c2 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -2386,6 +2386,8 @@ void QDeclarativeListView::keyPressEvent(QKeyEvent *event)
 
     Increments the current index.  The current index will wrap
     if keyNavigationWraps is true and it is currently at the end.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeListView::incrementCurrentIndex()
 {
@@ -2403,6 +2405,8 @@ void QDeclarativeListView::incrementCurrentIndex()
 
     Decrements the current index.  The current index will wrap
     if keyNavigationWraps is true and it is currently at the beginning.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeListView::decrementCurrentIndex()
 {
@@ -2439,6 +2443,14 @@ void QDeclarativeListView::decrementCurrentIndex()
     of the list does not cause all other items to be repositioned, and because
     the actual start of the view can vary based on the size of the delegates.
     The correct way to bring an item into view is with \c positionViewAtIndex.
+
+    \bold Note: methods should only be called after the Component has completed.  To position
+    the view at startup, this method should be called by Component.onCompleted.  For
+    example, to position the view at the end:
+
+    \code
+    Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning)
+    \endcode
 */
 void QDeclarativeListView::positionViewAtIndex(int index, int mode)
 {
@@ -2509,6 +2521,8 @@ void QDeclarativeListView::positionViewAtIndex(int index, int mode)
 
     If the item is outside the visible area, -1 is returned, regardless of
     whether an item will exist at that point when scrolled into view.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 int QDeclarativeListView::indexAt(int x, int y) const
 {
diff --git a/src/declarative/graphicsitems/qdeclarativepathview.cpp b/src/declarative/graphicsitems/qdeclarativepathview.cpp
index 0c2d249..0e980b3 100644
--- a/src/declarative/graphicsitems/qdeclarativepathview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativepathview.cpp
@@ -552,6 +552,8 @@ void QDeclarativePathView::setCurrentIndex(int idx)
     \qmlmethod PathView::incrementCurrentIndex()
 
     Increments the current index.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativePathView::incrementCurrentIndex()
 {
@@ -563,6 +565,8 @@ void QDeclarativePathView::incrementCurrentIndex()
     \qmlmethod PathView::decrementCurrentIndex()
 
     Decrements the current index.
+
+    \bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativePathView::decrementCurrentIndex()
 {