Doc: updating getting started docs - not finished

(cherry picked from commit b83f3a98fe5688872b4bd9a871e544951cb33e29)

Conflicts:

	doc/src/getting-started/gettingstarted.qdoc

3 files changed, 1604 insertions, 0 deletions

diff --git a/doc/src/getting-started/gettingstarted.qdoc b/doc/src/getting-started/gettingstarted.qdoc
new file mode 100644
index 0000000..145982b
--- /dev/null
+++ b/doc/src/getting-started/gettingstarted.qdoc
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Getting Started Guides
+
+	\group gettingStarted
+	
+	Following is a list.
+	 \generatelist{related}
+	
+*/
+
diff --git a/doc/src/getting-started/gettingstartedqml.qdoc b/doc/src/getting-started/gettingstartedqml.qdoc
new file mode 100644
index 0000000..2bfb71c
--- /dev/null
+++ b/doc/src/getting-started/gettingstartedqml.qdoc
@@ -0,0 +1,1050 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qml-textEditor.html
+
+    \title Getting Started programming with QML
+	\ingroup gettingStarted
+	
+	Welcome to the world of QML - the declarative UI language. In this Getting
+	Started guide, we will create a simple text editor application using QML.
+	After reading this guide, you should be ready to develop your own applications
+	using QML and Qt C++.
+
+	\section1 QML to Build User Interfaces
+
+	The application we are building is a simple text editor that will load, save,
+	and perform some text manipulation. This guide will consist of two parts. The
+	first part will involve designing the application layout and behaviors using
+	declarative language in QML. For the second part, file loading and saving will
+	be implemented using Qt C++. Using
+	\l {The Meta-Object System}{Qt's Meta-Object System}, we can expose C++ functions
+	as properties that QML elements can use. Utilizing QML and Qt C++, we can
+	efficiently decouple the interface logic from the application logic.
+	
+	\image qml-texteditor5_editmenu.png
+	
+	To run the QML example code, merely provide the included \l{QML Viewer}{qmlviewer}
+	tool with the QML file as the argument. The C++ portion of this tutorial assumes
+	that the reader possesses basic knowledge of Qt's compilation procedures.
+	
+	Tutorial chapters:
+	\list 1
+		\o \l {Defining a Button and a Menu}{Defining a Button and a Menu}
+		\o \l {Implementing a Menu Bar}{Implementing a Menu Bar}
+		\o \l {Building a Text Editor}{Building a Text Editor}
+		\o \l {Decorating the Text Editor}{Decorating the Text Editor}
+		\o \l {Extending QML using Qt C++}{Extending QML using Qt C++}
+	\endlist
+
+	\section1 Defining a Button and a Menu
+
+	\section2 Basic Component - a Button
+		
+	We start our text editor by building a button. Functionally, a button has a mouse
+	sensitive area and a label. Buttons perform actions when a user presses the button.
+	
+	In QML, the basic visual item is the \l {Rectangle}{Rectangle} element. The 
+	\c Rectangle element has properties to control the element's appearance and location. 
+	
+	\code
+		import Qt  4.7
+		Rectangle {
+			id: simplebutton
+			color: "grey"
+			width: 150; height: 75
+			
+			Text{
+				id: buttonLabel
+				anchors.centerIn: parent
+				text: "button label"	
+			}
+		}
+	\endcode
+	
+	First, the \c { import Qt 4.7 } allows the qmlviewer tool to import the QML elements
+	we will later use. This line must exist for every QML file. Notice that the version
+	of Qt modules is included in the import statement.
+	
+	This simple rectangle has a unique identifier, \c simplebutton, which is bound to the
+	id property. The \c Rectangle element's properties are bound to values by listing the
+	property, followed by a colon, then the value. In the code sample, the color \c grey
+	is bound to the the Rectangle's \c color property. Similarly, we bind the \c width
+	and \c height of the Rectangle.
+	
+	The \l {Text}{Text} element is a non-editable text field. We name this \c Text element
+	\c buttonLabel. To set the string content of the Text field, we bind a value to the
+	\c text property. The label is contained within the Rectangle and in order to center
+	it in the middle, we assign the \c anchors of the Text element to its parent, which
+	is called \c simplebutton. Anchors may bind to other items' anchors, allowing layout
+	assignments simpler. 
+	
+	We shall save this code as \c SimpleButton.qml. Running qmlviewer with the file as the
+	argument will display the grey rectangle with a text label.
+	
+	\image qml-texteditor1_simplebutton.png
+	
+	To implement the button click functionality, we can use QML's event handling. QML's event
+	handling is very similar to \l {Signals & Slots}{Qt's signal and slot} mechanism. Signals
+	are emitted and the connected slot is called.
+	
+	\code
+		Rectangle{
+			id:simplebutton
+			...
+
+			MouseArea{ 
+				id: buttonMouseArea
+				
+				anchors.fill: parent //anchor all sides of the mouse area to the rectangle's anchors
+						//onClicked handles valid mouse button clicks
+				onClicked: console.log(buttonLabel.text + " clicked" )
+			}
+		}
+	\endcode
+	
+	We include a \l{MouseArea} element in our simplebutton. \c MouseArea elements describe
+	the interactive area where mouse movements are detected. For our button, we anchor the
+	whole MouseArea to its parent, which is \c simplebutton. The \c anchors.fill syntax is
+	one way of accessing a specific property called \c fill inside a group of properties
+	called \c anchors. QML uses \l {Anchor-based Layout in QML}{anchor based layouts} where
+	items can anchor to another item, creating robust layouts.
+	
+	The \c MouseArea has many signal handlers that are called during mouse movements within
+	the specfied \c MouseArea boundaries. One of them is \c onClicked and it is called
+	whenever the acceptable mouse button is clicked, the left click being the default. We
+	can bind actions to the onClicked handler. In our example, \c console.log() outputs text
+	whenever the mouse area is clicked. The function \c console.log() is a useful tool for
+	debugging purposes and for outputting text. 
+	
+	The code in \c SimpleButton.qml is sufficient to display a button on the screen and
+	output text whenever it is clicked with a mouse.
+	
+	\code
+		Rectangle {
+			id:Button
+			...
+
+			property color buttonColor: "lightblue"	
+			property color onHoverColor: "gold"
+			property color borderColor: "white"
+			
+			signal buttonClick()
+			onButtonClick: {
+				console.log(buttonLabel.text + " clicked" )
+			}
+
+			MouseArea{ 
+				onClicked: buttonClick()	
+				hoverEnabled: true
+				onEntered: parent.border.color = onHoverColor
+				onExited:  parent.border.color = borderColor
+			}
+
+			//determines the color of the button by using the conditional operator
+			color: buttonMouseArea.pressed ? Qt.darker(buttonColor, 1.5) : buttonColor
+		}
+	\endcode
+	
+	A fully functioning button is in \c Button.qml. The code snippets in this article
+	have some code omitted, denoted by ellipses because they were either introduced
+	earlier in the previous sections or irrelevant to the current code discussion.
+	
+	Custom properties are declared using the \c {property type name} syntax. In the
+	code, the property \c buttonColor, of type \c color, is declared and bound to
+	the value \c{"lightblue"}. The \c buttonColor is later used in a conditional
+	operation to determine the buttons's fill color. Note that property value
+	assignment is possible using the \c= equals sign, in addition to value binding
+	using the \c : colon character. Custom properties allow internal items to be
+	accessible outside of the Rectangle's scope. There are basic
+	\l{QML Basic Types}{QML types} such as \c int, \c string, \c real, as well as
+	a type called \c variant.
+	
+	By binding the \c onEntered and \c onExited signal handlers to colors, the
+	button's border will turn yellow when the mouse hovers above the button and
+	reverts the color when the mouse exits the mouse area.
+	
+	A \c buttonClick() signal is declared in \c Button.qml by placing the \c signal
+	keyword in front of the signal name. All signals have their handlers automatically
+	created, their names starting with \c on. As a result, the \c onButtonClick is
+	\c buttonClick's handler. The \c onButtonClick is then assigned an action to
+	perform. In our button example, the \c onClicked mouse handler will simply call
+	\c onButtonClick, which displays a text. The \c onButtonClick enables outside
+	objects to access the \c {Button}'s mouse area easily. For example, items may
+	have more than one \c MouseArea declarations and a \c buttonClick signal can
+	make the distinction between the several \c MouseArea signal handlers better.
+	
+	We now have the basic knowledge to implement items in QML that can handle
+	basic mouse movements. We created a \c Text label inside a \c Rectangle,
+	customized its properties, and implemented behaviors that respond to mouse
+	movements. This idea of creating elements within elements is repeated
+	throughout the text editor application.
+	
+	This button is not useful unless used as a component to perform an action.
+	In the next section, we will soon create a menu containing several of these
+	buttons.
+	
+	\image qml-texteditor1_button.png
+	
+	\section2 Creating a Menu Page
+	
+	Up to this stage, we covered how to create elements and assign behaviors inside
+	a single QML file. In this section, we will cover how to import QML elements and how
+	to reuse some of the created components to build other components.
+	
+	Menus display the contents of a list, each item having the ability to perform an action.
+	In QML, we can create a menu in several ways. First, we will create a menu containing
+	buttons which will eventually perform different actions. The menu code is in
+	\c FileMenu.qml.
+
+	\code
+		import Qt 4.7				\\import the main Qt QML module
+		import “folderName”			\\import the contents of the folder	
+		import “Button.qml”			\\import a QML file
+		import “NewButton.qml” as ButtonModule	\\import a QML file and give it a name
+		import “script.js” as Script		\\import a Javascript file and name it as Script
+	\endcode
+
+	To use the \c Button element in \c FileMenu.qml, we need to import \c Button.qml.
+	The syntax shown above, shows how to use the \c import keyword. However, the
+	\c {import Button.qml} is not necessary; qmlviewer will import all the contents
+	of the current directory. We can directly create a \c Button element by declaring
+	\c Button{}, similar to a \c Rectangle{} declaration.
+
+	\code
+	In FileMenu.qml:
+
+		Row{
+			anchors.centerIn: parent
+			spacing: parent.width/6
+		
+			Button{
+				id: loadButton
+				buttonColor: "lightgrey"
+				label: "Load"
+			}
+			Button{
+				buttonColor: "grey"
+				id: saveButton
+				label: "Save"
+			}
+			Button{
+				id: exitButton
+				label: "Exit"
+				buttonColor: "darkgrey"
+
+				onButtonClick: Qt.quit() 
+			}
+		}
+	\endcode
+
+	In \c FileMenu.qml, we declare three \c Button elements. They are declared
+	inside a \l {Row}{Row} element, a positioner that will position its children
+	along a vertical row. The \c Button declaration resides in Button.qml,
+	which is the same as the \c Button.qml we used in the previous section.
+	New property bindings can be declared within the newly created buttons,
+	effectively overwriting the properties set in \c Button.qml. The button
+	called \c exitButton will quit and close the window when it is clicked.
+	Note that the signal handler \c onButtonClick in \c Button.qml will be
+	called in addition to the \c onButtonClick handler in \c exitButton.
+
+	\image qml-texteditor1_filemenu.png
+
+	The \c Row declaration is declared in a \c Rectangle, creating a rectangle
+	container for the row of buttons. This additional rectangle creates an indirect
+	way of organizing the row of buttons inside a menu.
+
+	The declaration of the edit menu is very similar at this stage. The menu has
+	buttons that have the labels: \c Copy, \c Paste, and \c {Select All}.
+
+	\image qml-texteditor1_editmenu.png      
+
+	Armed with our knowledge of importing and customizing previously made
+	components, we may now combine these menu pages to create a menu bar,
+	consisting of buttons to select the menu, and look at how we may structure
+	data using QML.
+
+	\section1 Implementing a Menu Bar
+
+	Our text editor application will need a way to display menus using a menu bar.
+	The menu bar will switch the different menus and the user can choose which menu
+	to display. Menu switching implies that the menus need more structure than
+	merely displaying them in a row. QML uses models and views to structure data
+	and display the structured data.
+
+	\section2  Using Data Models and Views
+
+	QML has different \l {Data Models}{data views} that display
+	\l {Data Models}{data models}. Our menu bar will display the menus in a list,
+	with a header that displays a row of menu names. The list of menus are declared
+	inside a \c VisualItemModel. The \l{VisualItemModel}{\c VisualItemModel}
+	element contains items that already have views such as \c Rectangle elements
+	and imported UI elements. Other model types such as the \l {ListModel}{\c ListModel}
+	element need a delegate to display their data.
+
+	We declare two visual items in the \c menuListModel, the \c FileMenu and the
+	\c EditMenu. We customize the two menus and display them using a
+	\l {ListView}{ListView}. The \c MenuBar.qml file contains the QML declarations
+	and a simple edit menu is defined in \c EditMenu.qml.
+
+	\code
+		VisualItemModel{
+			id: menuListModel
+			FileMenu{
+				width: menuListView.width
+				height: menuBar.height
+				color: fileColor
+			}
+			EditMenu{
+				color: editColor
+				width:  menuListView.width
+				height: menuBar.height
+			}
+		}
+	\endcode
+
+	The \l {ListView}{ListView} element will display a model according to a delegate.
+	The delegate may declare the model items to display in a \c Row element or display
+	the items in a grid. Our \c menuListModel already has visible items, therefore,
+	we do not need to declare a delegate.
+
+	\code
+		ListView{
+			id: menuListView
+			
+			//Anchors are set to react to window anchors
+			anchors.fill:parent
+			anchors.bottom: parent.bottom
+			width:parent.width
+			height: parent.height
+
+			//the model contains the data
+			model: menuListModel
+
+			//control the movement of the menu switching
+			snapMode: ListView.SnapOneItem
+			orientation: ListView.Horizontal
+			boundsBehavior: Flickable.StopAtBounds 
+			flickDeceleration: 5000
+			highlightFollowsCurrentItem: true
+			highlightMoveDuration:240
+			highlightRangeMode: ListView.StrictlyEnforceRange
+		}
+	\endcode
+
+	Additionally, \c ListView inherits from \l {Flickable}{\c Flickable}, making
+	the list respond to mouse drags and other gestures. The last portion of the
+	code above sets \c Flickable properties to create the desired flicking movement
+	to our view. In particular,the property \c highlightMoveDuration changes the
+	duration of the flick transition. A higher \c highlightMoveDuration value
+	results in slower menu switching. 
+
+	The \c ListView maintains the model items through an \c index and each visual
+	item in the model is accessible through the \c index, in the order of the
+	declaration. Changing the \c currentIndex effectively changes the highlighted
+	item in the \c ListView. The header of our menu bar exemplify this effect.
+	There are two buttons in a row, both changing the current menu when clicked.
+	The \c fileButton changes the current menu to the file menu when clicked,
+	the \c index being \c 0 because \c FileMenu is declared first in the
+	\c menuListModel. Similarly, the \c editButton will change the current
+	menu to the \c EditMenu when clicked.
+
+	The \c labelList rectangle has \c z value of \c 1, denoting that it is displayed
+	at the front of the menu bar. Items with higher \c z values are displayed in front
+	of items with lower \c z values. The default \c z value is \c 0.
+
+	\code
+		Rectangle{
+			id: labelList
+			...
+			z: 1
+			Row{
+				anchors.centerIn: parent
+				spacing:40
+				Button{
+					label: "File"
+					id: fileButton
+					...
+					onButtonClick: menuListView.currentIndex = 0
+				}
+				Button{
+					id: editButton
+					label: "Edit"
+					...
+					onButtonClick:	menuListView.currentIndex = 1	
+				}
+			}
+		}
+	\endcode
+
+	The menu bar we just created can be flicked to access the menus or by clicking
+	on the menu names at the top. Switching menu screens feel intuitive and responsive.
+
+	\image qml-texteditor2_menubar.png 
+
+	*/
+
+	/*!
+	\page qml-textEditor3.html
+	\title Building a Text Editor
+
+	\section1 Declaring a TextArea
+
+	Our text editor is not a text editor if it didn't contain an editable text area.
+	QML's \l {TextEdit}{TextEdit} element allows the declaration of a multi-line
+	editable text area. \l {TextEdit}{TextEdit} is different from a \l {Text}{Text}
+	element, which doesn't allow the user to directly edit the text.
+
+	\code
+		TextEdit{
+			id: textEditor 
+			anchors.fill:parent
+			width:parent.width; height:parent.height
+			color:"midnightblue"
+			focus: true
+
+			wrapMode: TextEdit.Wrap
+		
+			onCursorRectangleChanged: flickArea.ensureVisible(cursorRectangle)
+		}
+	\endcode
+
+	The editor has its font color property set and set to wrap the text. The
+	\c TextEdit area is inside a flickable area that will scroll the text if the
+	text cursor is outside the visible area. The function \c ensureVisible() will
+	check if the cursor rectangle is outside the visible boundaries and move the
+	text area accordingly. QML uses Javascript syntax for its scripts, and as previously
+	mentioned, Javascript files can be imported and used within a QML file.
+
+	\code
+		function ensureVisible(r){
+			if (contentX >= r.x)
+				contentX = r.x;
+			else if (contentX+width <= r.x+r.width)
+				contentX = r.x+r.width-width;
+			if (contentY >= r.y)
+				contentY = r.y;
+			else if (contentY+height <= r.y+r.height)
+				contentY = r.y+r.height-height;
+		}
+	\endcode
+		
+	\section1 Combining Components for the Text Editor
+
+	We are now ready to create the layout of our text editor using QML. The text
+	editor has two components, the menu bar we created and the text area. QML allows
+	us to reuse components, therefore making our code simpler, by importing components
+	and customizing when necessary. Our text editor splits the window into two;
+	one-third of the screen is dedicated to the menu bar and two-thirds of the screen
+	displays the text area. The menu bar is displayed in front of any other elements.
+
+	\code
+		Rectangle{
+
+			id: screen
+			width: 1000; height: 1000
+
+			//the screen is partitioned into the MenuBar and TextArea. 1/3 of the screen is assigned to the MenuBar
+			property int partition: height/3
+			
+			MenuBar{
+				id:menuBar
+				height: partition
+				width:parent.width
+				z: 1
+			}
+
+			TextArea{
+				id:textArea
+				anchors.bottom:parent.bottom
+				y: partition
+				color: "white"
+				height: partition*2
+				width:parent.width
+			}
+		}
+	\endcode
+
+	By importing reusable components, our \c TextEditor code looks much simpler.
+	We can then customize the main application, without worrying about properties
+	that already have defined behaviors. Using this approach, application layouts
+	and UI components can be created easily.
+
+	\image qml-texteditor3_texteditor.png 
+
+	*/
+
+	/*!
+	\page qml-textEditor4
+	\title Decorating the Text Editor
+	\section1 Implementing a Drawer Interface
+
+	Our text editor looks simple and we need to decorate it. Using QML, we can declare
+	transitions and animate our text editor. Our menu bar is occupying one-third of the
+	screen and it would be nice to have it only appear when we want it. 
+
+	We can add a drawer interface, that will contract or expand the menu bar when clicked.
+	In our implementation, we have a thin rectangle that responds to mouse clicks. The
+	\c drawer, as well as the application, has two sates: the "drawer is open" state and
+	the "drawer is closed" state. The \c drawer item is a strip of rectangle with a small
+	height. There is a nested \l {Image}{Image} element declaring that an arrow icon will
+	be centered inside the drawer. The drawer assigns a state to the whole application,
+	with the identifier \c screen, whenever a user clicks the mouse area.
+
+	\code
+		Rectangle{
+			id:drawer
+			height:15
+		
+			Image{
+				id: arrowIcon
+				source: "images/arrow.png"
+				anchors.horizontalCenter: parent.horizontalCenter
+			}
+			
+			MouseArea{
+				id: drawerMouseArea
+				anchors.fill:parent
+				onClicked:{
+					if (screen.state == "DRAWER_CLOSED"){
+						screen.state = "DRAWER_OPEN"
+					}
+					else if (screen.state == "DRAWER_OPEN"){
+						screen.state = "DRAWER_CLOSED"
+					}
+				}
+				...
+			}
+		}
+	\endcode
+
+	A state is simply a collection of configurations and it is declared in a
+	\l{State}{State} element. A list of states can be listed and bound to the
+	\c states property. In our application, the two states are called
+	\c DRAWER_CLOSED and \c DRAWER_OPEN. Item configurations are declared in
+	\l {PropertyChanges}{PropertyChanges} elements. In the \c DRAWER_OPEN state,
+	there are four items that will receive property changes. The first target,
+	\c menuBar, will change its \c y property to \c 0. Similarly, the \c textArea
+	will lower to a new position when the state is \c DRAWER_OPEN. The \c textArea,
+	the \c drawer, and the drawer's icon will undergo property changes to meet the
+	current state.
+
+	\code
+
+		states:[
+			State{
+				name: "DRAWER_OPEN"
+				PropertyChanges { target: menuBar; y:0}
+				PropertyChanges { target: textArea; y: partition + drawer.height}
+				PropertyChanges { target: drawer; y: partition}
+				PropertyChanges { target: arrowIcon; rotation: 180} 
+			},
+			State{
+				name: "DRAWER_CLOSED"
+				PropertyChanges { target: menuBar; y:-partition}
+				PropertyChanges { target: textArea; y: drawer.height; height: screen.height - drawer.height}
+				PropertyChanges { target: drawer; y: 0}
+				PropertyChanges { target: arrowIcon; rotation: 0} 
+			}
+
+		]
+
+	\endcode
+
+	State changes are abrupt and needs smoother transitions. Transitions between states
+	are defined using the \l {Transition}{Transition} element, which can then bind to
+	the item's \c transitions property. Our text editor has a state transition whenever
+	the state changes to either \c DRAWER_OPEN or \c DRAWER_CLOSED. Importantly, the
+	transition needs a \c from and a \c to state but for our transitions, we can use
+	the wild card \c * symbol to denote that the transition applies to all state changes. 
+
+	During transitions, we can assign animations to the property changes. Our
+	\c menuBar switches position from \c {y:0} to \c {y:-partition} and we can animate
+	this transition using the \l {NumberAnimation}{NumberAnimation} element. We declare
+	that the targets' properties will animate for a certain duration of time and using
+	a certain easing curve. An easing curve controls the animation rates and
+	interpolation behavior during state transitions. The easing curve we chose is
+	\l {PropertyAnimation::easing.type}{Easing.OutQuint}, which slows the movement near
+	the end of the animation. Pleae read \l {qdeclarativeanimation.html}{QML's Animation}
+	article.
+
+	\code
+		transitions: [
+			Transition{
+				to: "*"
+				NumberAnimation { target: textArea; properties: "y, height"; duration: 100; easing.type: Easing.OutQuint }
+				NumberAnimation { target: menuBar; properties: "y"; duration: 100;easing.type: Easing.OutQuint }
+				NumberAnimation { target: drawer; properties: "y"; duration: 100;easing.type: Easing.OutQuint }
+			}
+		]
+	\endcode
+
+	Another way of animating property changes is by declaring a \l {Behavior}{Behavior}
+	element. A transition only works during state changes and \c Behavior can set an
+	animation for a general property change. In the text editor, the arrow has a
+	\c NumberAnimation animating its \c rotation property whenever the property changes.
+
+	\code
+	In TextEditor.qml:
+
+		Behavior{
+			NumberAnimation{property: "rotation";easing.type: Easing.OutExpo }
+		}	
+	\endcode
+
+	Going back to our components with knowledge of states and animations, we can improve
+	the appearances of the components. In \c Button.qml, we can add \c color and \c scale
+	property changes when the button is clicked. Color types are animated using
+	\l {ColorAnimation}{ColorAnimation} and numbers are animated using
+	\l {NumberAnimation}{NumberAnimation}. The \c {on propertyName} syntax displayed below
+	is helpful when targeting a single property.
+
+	\code
+	In Button.qml:
+		...
+		
+		color: buttonMouseArea.pressed ? Qt.darker(buttonColor, 1.5) : buttonColor
+		Behavior on color { ColorAnimation{ duration: 55} }
+		
+		scale: buttonMouseArea.pressed ? 1.1 : 1.00
+		Behavior on scale { NumberAnimation{ duration: 55} }
+	\endcode
+
+	Additionally, we can enhance the appearances of our QML components by adding color
+	effects such as gradients and opacity effects. Declaring a \l {Gradient}{Gradient}
+	element will override the \c color property of the element. You may declare a color
+	in the gradient using the \l {GradientStop}{GradientStop} element. The gradient is
+	positioned using a scale, between \c 0.0 and \c 1.0.
+
+	\code
+	In MenuBar.qml
+		gradient: Gradient {
+			GradientStop { position: 0.0; color: "#8C8F8C" }
+			GradientStop { position: 0.17; color: "#6A6D6A" }
+			GradientStop { position: 0.98;color: "#3F3F3F" }
+			GradientStop { position: 1.0; color: "#0e1B20" }
+		}
+	\endcode
+
+	This gradient is used by the menu bar to display a gradient simulating depth.
+	The first color starts at \c 0.0 and the last color is at \c 1.0.
+
+
+	\section2 Where to Go from Here
+
+		We are finished building the user interface of a very simple text editor.
+		Going forward, the user interface is complete, and we can implement the
+		application logic using regular Qt and C++. QML works nicely as a prototyping
+		tool, separating the application logic away from the UI design. 
+
+	\image qml-texteditor4_texteditor.png  
+	
+	\section1 Extending QML using Qt C++
+
+	Now that we have our text editor layout, we may now implement the text editor
+	functionalities in C++. Using QML with C++ enables us to create our application
+	logic using Qt. We can create a QML context in a C++ application using the
+	\l {Using QML in C++ Applications}{Qt's Declarative} classes and display the QML
+	elements using a Graphics Scene. Alternatively, we can export our C++ code into
+	a plugin that the \l {QML Viewer}{qmlviewer} tool can read. For our application,
+	we shall implement the load and save functions in C++ and export it as a plugin.
+	This way, we only need to load the QML file directly instead of running an executable.
+
+	\section2 Exposing C++ Classes to QML 
+
+	We will be implementing file loading and saving using Qt and C++. C++ classes
+	and functions can be used in QML by registering them. The class also needs to be
+	compiled as a Qt plugin and the QML file will need to know where the plugin is located.
+
+	For our application, we need to create the following items:
+	\list 1
+	\o \c Directory class that will handle directory related operations
+	\o \c File class which is a QObject, simulating the list of files in a directory
+	\o plugin class that will register the class to the QML context
+	\o Qt project file that will compile the plugin
+	\o A \c qmldir file telling the qmlviewer tool where to find the plugin
+	\endlist
+
+	\section2 Building a Qt Plugin
+
+		To build a plugin, we need to set the following in a Qt project file. First,
+		the necessary sources, headers, and Qt modules need to be added into our
+		project file. All the C++ code and project files are in the \c filedialog
+		directory.
+
+	\code
+	In cppPlugins.pro:
+
+		TEMPLATE = lib
+		CONFIG += qt plugin
+		QT += declarative
+
+		DESTDIR +=  ../plugins
+		OBJECTS_DIR = tmp
+		MOC_DIR = tmp
+
+		TARGET = FileDialog
+			
+		HEADERS += 	directory.h \
+				file.h \
+				dialogPlugin.h
+		
+		SOURCES +=	directory.cpp \
+				file.cpp \
+				dialogPlugin.cpp
+	\endcode
+
+	In particular, we compile Qt with the \c declarative module and configure it as a
+	\c plugin, needing a \c lib template. We shall put the compiled plugin into the
+	parent's \c plugins directory.
+
+
+	\section2 Registering a Class into QML
+
+	\code
+	In dialogPlugin.h:
+
+		#include <QtDeclarative/QDeclarativeExtensionPlugin>
+
+		class DialogPlugin : public QDeclarativeExtensionPlugin
+		{
+			Q_OBJECT
+
+			public:
+			void registerTypes(const char *uri);
+		
+		};
+		
+	\endcode
+		Our plugin class, \c DialogPlugin is a subclass of \l {QDeclarativeExtensionPlugin}{QDeclarativeExtensionPlugin}. We need to implement the inherited function, \l {QDeclarativeExtensionPlugin::registerTypes}{registerTypes}. The \c dialogPlugin.cpp file looks like this:
+		
+	\code
+	DialogPlugin.cpp:
+
+		#include "dialogPlugin.h"
+		#include "directory.h"
+		#include "file.h"
+		#include <QtDeclarative/qdeclarative.h>
+		
+		void DialogPlugin::registerTypes(const char *uri){
+			
+			qmlRegisterType<Directory>(uri, 1, 0, "Directory");
+			qmlRegisterType<File>(uri, 1, 0,"File");
+		}
+
+		Q_EXPORT_PLUGIN2(FileDialog, DialogPlugin);
+	\endcode
+		
+	The \l {QDeclarativeExtensionPlugin::registerTypes}{registerTypes}
+	function registers our File and Directory classes into QML. This function
+	needs the class name for its template, a major version number, a minor version
+	number, and a name for our classes.
+
+	We need to export the plugin using the \l {Q_EXPORT_PLUGIN2}{Q_EXPORT_PLUGIN2}
+	macro. Note that in our \c dialogPlugin.h file, we have the \l {Q_OBJECT}{Q_OBJECT}
+	macro at the top of our class. As well, we need to run \c qmake on the project
+	file to generate the necessary meta-object code.
+
+
+	\section2 Creating QML Properties in a C++ class
+
+		We can create QML elements and properties using C++ and
+		\l {The Meta-Object System}{Qt's Meta-Object System}. We can implement
+		properties using slots and signals, making Qt aware of these properties.
+		These properties can then be used in QML.
+
+	For the text editor, we need to be able to load and save files. Typically,
+	these features are contained in a file dialog. Fortunately, we can use
+	\l {QDir}{QDir}, \l {QFile}{QFile}, and \l {QTextStream}{QTextStream} to
+	implement directory reading and input/output streams.
+		
+	\code
+		class Directory : public QObject{
+
+			Q_OBJECT
+			
+			Q_PROPERTY(int filesCount READ filesCount CONSTANT)
+			Q_PROPERTY(QString filename READ filename WRITE setFilename NOTIFY filenameChanged)
+			Q_PROPERTY(QString fileContent READ fileContent WRITE setFileContent NOTIFY fileContentChanged)
+			Q_PROPERTY(QDeclarativeListProperty<File> files READ files CONSTANT )
+
+			...
+	\endcode
+
+	The \c Directory class uses Qt's Meta-Object System to register properties it
+	needs to accomplish file handling. The \c Directory class is exported as a plugin
+	and is useable in QML as the \c Directory element. Each of the listed properties
+	using the \l {Q_PROPERTY()}{Q_PROPERTY} macro is a QML property.
+		
+	The \l {Q_PROPERTY()} {Q_PROPERTY} declares a property as well as its read and
+	write functions into Qt's Meta-Object System. For example, the \c filename
+	property, of type \l {QString}{QString}, is readable using the \c filename()
+	function and writable using the function \c setFilename(). Additionally, there
+	is a signal associated to the filename property called \c filenameChanged(),
+	which is emitted whenever the property changes. The read and write functions
+	are declared as \c public in the header file.
+
+	Similarly, we have the other properties declared according to their uses. The
+	\c filesCount property indicates the number of files in a directory. The filename
+	property is set to the currently selected file's name and the loaded/saved file
+	content is stored in \c fileContent property. 
+
+	\code
+		Q_PROPERTY(QDeclarativeListProperty<File> files READ files CONSTANT )
+	\endcode
+
+	The \c files list property is a list of all the filtered files in a directory.
+	The \c Directory class is implemented to filter out invalid text files; only
+	files with a \c .txt extension are valid. Further, \l {QLists}{QLists} can be
+	used in QML files by declaring them as a \c QDeclarativeListProperty in C++.
+	The templated object needs to inherit from a \l {QObject}{QObject}, therefore,
+	the \c File class must also inherit from \c QObject. In the \c Directory class,
+	the list of \c File objects is stored in a \c QList called \c m_fileList.
+
+	\code
+		class File : public QObject{
+		
+			Q_OBJECT
+			Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
+			
+			...
+		};
+	\endcode
+
+	The properties can then be used in QML as part of the \c Directory element's
+	properties. Note that we do not have to create an identifier \c id property
+	in our C++ code.
+
+	\code
+		Directory{
+			id: directory
+			
+			filesCount
+			filename
+			fileContent
+			files
+			
+			files[0].name
+		}
+
+	\endcode
+
+	Because QML uses Javascript's syntax and structure, we can iterate through
+	the list of files and retrieve its properties. To retrieve the first file's
+	name property, we can call \c { files[0].name }.
+
+	Regular C++ functions are also accessible from QML. The file loading and saving
+	functions are implemented in C++ and declared using the
+	\l {Q_INVOKABLE}{Q_INVOKABLE} macro. Alternatively, we can declare the functions
+	as a \c slot and the functions will be accessible from QML. 
+
+	\code
+	In Directory.h: 
+
+		Q_INVOKABLE void saveFile();
+		Q_INVOKABLE void loadFile();
+	\endcode
+
+	The \c Directory class also has to notify other objects whenever the directory
+	contents change. This feature is performed using a \c signal. As previously
+	mentioned, QML signals have a corresponding handler with their names prepended
+	with \c on. The signal is called \c directoryChanged and it is emitted whenever
+	there is a directory refresh. The refresh simply reloads the directory contents
+	and updates the list of valid files in the directory. QML items can then be
+	notified by attaching an action to the \c onDirectoryChanged signal handler.
+
+	The \c list properties need to be explored further. This is because list
+	properties use callbacks to access and modify the list contents. The list
+	property is of type \c QDeclarativeListProperty<File>. Whenever the list
+	is accessed, the accessor function needs to return a
+	\c QDeclarativeListProperty<File>. The template type, \c File, needs to be a
+	\c QObject derivative. Further, to create the
+	\l {QDeclarativeListProperty}{QDeclarativeListProperty}, the list's accessor
+	and modifiers need to be passed to the consructor as function pointers. The list,
+	a \c QList in our case,  also needs to be a list of \c File pointers.
+
+	The constructor of \l {QDeclarativeListProperty}{QDeclarativeListProperty}
+	constructor and the \c Directory implementation:
+	\code
+		QDeclarativeListProperty  ( QObject * object, void * data, AppendFunction append, CountFunction count = 0, AtFunction at = 0, ClearFunction clear = 0 )
+		QDeclarativeListProperty<File>( this, &m_fileList, &appendFiles, &filesSize, &fileAt,  &clearFilesPtr );
+	\endcode
+
+	The constructor passes pointers to functions that will append the list, count
+	the list, retrieve the item using an index, and empty the list. Only the append
+	function is mandatory. Note that the function pointers must match the definition
+	of \l {QDeclarativeListProperty::AppendFunction}{AppendFunction}, 
+	\l {QDeclarativeListProperty::CountFunction}{CountFunction}, 
+	\l {QDeclarativeListProperty::AtFunction}{AtFunction}, or 
+	\l {QDeclarativeListProperty::ClearFunction}{ClearFunction}.
+
+	\code
+		void appendFiles(QDeclarativeListProperty<File> * property, File * file)
+		File* fileAt(QDeclarativeListProperty<File> * property, int index)
+		int filesSize(QDeclarativeListProperty<File> * property)
+		void clearFilesPtr(QDeclarativeListProperty<File> *property)
+	\endcode
+
+	To simplify our file dialog, the \c Directory class filters out invalid text
+	files, which are files that do not have a \c .txt extension. If a file name
+	doesn't have the \c .txt extension, then it won't be seen in our file dialog.
+	Also, the implementation makes sure that saved files have a \c .txt extension in
+	the file name. \c Directory uses \l {QTextStream}{QTextStream} to read the file
+	and to output the file contents to a file.
+
+	With our \c Directory element, we can retrieve the files as a list, know how many
+	text files is in the application directory, get the file's name and content as a
+	string, and be notified whenever there are changes in the directory contents.
+
+	To build the plugin, run \c qmake on the \c cppPlugins.pro project file, then run
+	\c make to build and transfer the plugin to the \c plugins directory.
+
+
+	\section2 Importing a Plugin in QML
+		
+		The qmlviewer tool imports files that are in the same directory as the
+		application. We can also create a \c qmldir file containing the locations of
+		QML files we wish to import. The \c qmldir file can also store locations of
+		plugins and other resources.
+
+	\code
+	In qmldir: 
+
+		Button ./Button.qml
+		FileDialog ./FileDialog.qml
+		TextArea ./TextArea.qml
+		TextEditor ./TextEditor.qml
+		EditMenu ./EditMenu.qml
+
+		plugin FileDialog plugins
+	\endcode
+
+	The plugin we just created is called \c FileDialog, as indicated by the
+	\c TARGET field in the project file. The compiled plugin is in the \c plugins directory. 
+
+
+	\section2 Integrating a File Dialog into the File Menu
+
+		Our \c FileMenu needs to display the \c FileDialog element, containing a list of
+		the text files in a directory thus allowing the user to select the file by
+		clicking on the list. We also need to assign the save, load, and new buttons
+		to their respective actions. The FileMenu contains an editable text input to
+		allow the user to type a file name using the keyboard.
+
+	The \c Directory element is used in the \c FileMenu.qml file and it notifies the
+	\c FileDialog element that the directory refreshed its contents. This notification
+	is performed in the signal handler, \c onDirectoryChanged.
+
+	\code 
+	In FileMenu.qml:
+
+		Directory{
+			id:directory
+			filename: textInput.text
+			onDirectoryChanged: fileDialog.notifyRefresh()
+		}
+	\endcode
+
+	Keeping with the simplicity of our application, the file dialog will always be
+	visible and will not display invalid text files, which do not have a \c .txt
+	extension to their filenames. 
+
+	\code
+	In FileDialog.qml:
+		
+		signal notifyRefresh()
+		onNotifyRefresh: dirView.model = directory.files
+	\endcode
+
+	The \c FileDialog element will display the contents of a directory by reading its
+	list property called \c files. The files are used as the model of a
+	\l {GridView}{GridView} element, which displays data items in a grid according
+	to a delegate. The delegate handles the appearance of the model and our file
+	dialog will simply create a grid with text centered in the middle. Clicking on
+	the file name will result in the appearance of a rectangle to highlight the file
+	name. The \c FileDialog is notified whenever the \c notifyRefresh signal is emitted,
+	reloading the files in the directory.
+
+	\code
+	In FileMenu.qml:
+
+		Button{
+			id: newButton
+			label: "New"
+			onButtonClick:{
+				textArea.textContent = ""
+			}
+		}
+		Button{
+			id: loadButton
+			label: "Load"
+			onButtonClick:{
+				directory.filename = textInput.text
+				directory.loadFile()
+				textArea.textContent = directory.fileContent
+			}
+		}
+		Button{
+			id: saveButton
+			label: "Save"
+			onButtonClick:{
+				directory.fileContent = textArea.textContent
+				directory.filename = textInput.text
+				directory.saveFile()
+			}
+		}
+		Button{
+			id: exitButton
+			label: "Exit"
+			onButtonClick:{
+				Qt.quit()
+			}
+		}
+	\endcode
+
+	Our \c FileMenu can now connect to their respective actions. The \c saveButton
+	will transfer the text from the \c TextEdit onto the directory's \c fileContent
+	property, then copy its file name from the editable text input. Finally, the button
+	calls the \c saveFile() function, saving the file. The \c sloadButton has a similar
+	execution. Also, the \c New action will empty the contents of the \c TextEdit. 
+
+	Further, the \c EditMenu buttons are connected to the \c TextEdit functions to copy,
+	paste, and select all the text in the text editor. 
+
+	\image qml-texteditor5_filemenu.png
+
+	\section1 Text Editor Completion
+
+	\image qml-texteditor5_newfile.png
+
+		The application can function as a simple text editor, able to accept text
+		and save the text into a file. The text editor can also load from a file and
+		perform text manipulation. 
+		
+		
+*/
\ No newline at end of file
diff --git a/doc/src/getting-started/gettingstartedqt.qdoc b/doc/src/getting-started/gettingstartedqt.qdoc
new file mode 100644
index 0000000..1b3770f
--- /dev/null
+++ b/doc/src/getting-started/gettingstartedqt.qdoc
@@ -0,0 +1,517 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page gettingstartedqt.html
+
+    \title Getting Started programming with Qt
+	\ingroup gettingStarted
+
+    Welcome to the world of Qt--the cross-platform GUI toolkit. In
+    this getting started guide, we teach basic Qt knowledge by
+    implementing a simple Notepad application. After reading this
+    guide, you should be ready to delve into our overviews and API
+    documentation, and find the information you need for the
+    application you are developing.
+
+    \section1 Hello Notepad
+
+    In this first example, we simply create and show a text edit in a
+    window frame on the desktop. This represents the simplest possible
+    Qt program that has a GUI.
+
+    \image gs1.png
+
+    Here is the code:
+
+    \code
+ 1        #include <QApplication>
+ 2        #include <QTextEdit>
+ 3
+ 4        int main(int argv, char **args)
+ 5        {
+ 6            QApplication app(argv, args);
+ 7
+ 8            QTextEdit textEdit;
+ 9            textEdit.show();
+10
+11            return app.exec();
+12        }
+    \endcode
+
+    Let us go through the code line by line. In the first two lines, we
+    include the header files for QApplication and QTextEdit, which are
+    the two classes that we need for this example. All Qt classes have
+    a header file named after them.
+
+    Line 6 creates a QApplication object. This object manages
+    application-wide resources and is necessary to run any Qt program
+    that has a GUI. It needs \c argv and \c args because Qt accepts a
+    few command line arguments.
+
+    Line 8 creates a QTextEdit object. A text edit is a visual element
+    in the GUI. In Qt, we call such elements widgets. Examples of
+    other widgets are scroll bars, labels, and radio buttons. A widget
+    can also be a container for other widgets; a dialog or a main
+    application window, for example.  
+
+    Line 9 shows the text edit on the screen in its own window frame.
+    Since widgets also function as containers (for instance a
+    QMainWindow, which has toolbars, menus, a status bar, and a few
+    other widgets), it is possible to show a single widget in its own
+    window. Widgets are not visible by default; the function
+    \l{QWidget::}{show()} makes the widget visible.
+ 
+    Line 11 makes the QApplication enter its event loop. When a Qt
+    application is running, events are generated and sent to the
+    widgets of the application. Examples of events are mouse presses
+    and key strokes. When you type text in the text edit widget, it
+    receives key pressed events and responds by drawing the text
+    typed.
+
+    To run the application, open a command prompt, and enter the
+    directory in which you have the \c .cpp file of the program. The
+    following shell commands build the program.
+
+    \code
+        qmake -project
+        qmake
+        make
+    \endcode
+
+    This will leave an executable in the \c part1 directory (note that
+    on Windows, you may have to use \c nmake instead of \c make. Also,
+    the executable will be placed in part1/debug or part1/release). \c
+    qmake is Qt's build tool, which takes a configuration file. \c
+    qmake generates this for us when given the \c{-project} argument.
+    Given the configuration file (suffixed .pro), \c qmake produces a
+    \c make file that will build the program for you. We will look
+    into writing our own \c .pro files later.
+
+    \section2 Learn More
+
+    \table
+        \header
+            \o About
+            \o Here
+        \row
+            \o Widgets and Window Geometry
+            \o \l{Window and Dialog Widgets}
+        \row
+            \o Events and event handling
+            \o \l{The Event System}
+    \endtable
+
+    \section1 Adding a Quit Button
+
+    In a real application, you will normally need more than one
+    widget. We will now introduce a QPushButton beneath the text edit.
+    The button will exit the Notepad application when pushed (i.e.,
+    clicked on with the mouse).
+
+    \image gs2.png
+
+    Let us take a look at the code.
+
+    \code
+ 1        #include <QtGui>
+ 2
+ 3        int main(int argv, char **args)
+ 4        {
+ 5            QApplication app(argv, args);
+ 6
+ 7            QTextEdit textEdit;
+ 8            QPushButton quitButton("Quit");
+ 9
+10            QObject::connect(&quitButton, SIGNAL(clicked()), qApp, SLOT(quit()));
+11
+12            QVBoxLayout layout;
+13            layout.addWidget(&textEdit);
+14            layout.addWidget(&quitButton);
+15
+16            QWidget window;
+17            window.setLayout(&layout);
+18
+19            window.show();
+20
+21            return app.exec();
+22        }
+    \endcode
+
+    Line 1 includes QtGui, which contains all of Qt's GUI classes.
+
+    Line 10 uses Qt's Signals and Slots mechanism to make the
+    application exit when the \gui {Quit button} is pushed. A slot is
+    a function that can be invoked at runtime using its name (as a
+    literal string). A signal is a function that when called will
+    invoke slots registered with it; we call that to connect the slot
+    to the signal and to emit the signal.
+
+    \l{QApplication::}{quit()} is a slot of QApplication that exits
+    the application. \l{QPushButton::}{clicked()} is a signal that
+    QPushButton emits when it is pushed. The static
+    QObject::connect() function takes care of connecting the slot to
+    the signal. SIGNAL() and SLOT() are two macros that take the
+    function signatures of the signal and slot to connect. We also
+    need to give pointers to the objects that should send and receive
+    the signal.
+
+    Line 12 creates a QVBoxLayout. As mentioned, widgets can contain
+    other widgets. It is possible to set the bounds (the location and
+    size) of child widgets directly, but it is usually easier to use a
+    layout. A layout manages the bounds of a widget's children.
+    QVBoxLayout, for instance, places the children in a vertical row.
+
+    Line 13 and 14 adds the text edit and button to the layout. In
+    line 17, we set the layout on a widget. 
+
+    \section2 Learn More
+
+    \table
+        \header
+            \o About
+            \o Here
+         \row
+            \o Signals and slots
+            \o \l{Signals & Slots}
+        \row
+            \o Layouts
+            \o \l{Layout Management},
+               \l{Widgets and Layouts},
+               \l{Layout Examples}
+        \row 
+            \o The widgets that come with Qt
+            \o \l{Qt Widget Gallery},
+               \l{Widget Examples}
+    \endtable
+
+    \section1 Subclassing QWidget
+
+    When the user wants to quit an application, you might want to
+    pop-up a dialog that asks whether he/she really wants to quit. In
+    this example, we subclass QWidget, and add a slot that we connect
+    to the \gui {Quit button}.
+
+    \image gs3.png
+
+    Let us look at the code:
+
+    \code
+ 5        class Notepad : public QWidget
+ 6        {
+ 7            Q_OBJECT
+ 8
+ 9        public:
+10            Notepad();
+11
+12        private slots:
+13            void quit();
+14
+15        private:
+16            QTextEdit *textEdit;
+17            QPushButton *quitButton;
+18        };
+    \endcode
+
+    The \c Q_OBJECT macro must be first in the class definition, and
+    declares our class as a \c QObject (Naturally, it must also
+    inherit from QObject). A \l{QObject} adds several abilities to a
+    normal C++ class. Notably, the class name and slot names can be
+    queried at run-time. It is also possible to query a slot's
+    parameter types and invoke it.
+
+    Line 13 declares the slot \c quit(). This is easy using the \c
+    slots macro. The \c quit() slot can now be connected to signals
+    with a matching signature (any signal that takes no parameters).
+
+    Instead of setting up the GUI and connecting the slot in the \c
+    main() function, we now use \c{Notepad}'s constructor. 
+
+    \code
+        Notepad::Notepad()
+        {
+            textEdit = new QTextEdit;
+            quitButton = new QPushButton(tr("Quit"));
+
+            connect(quitButton, SIGNAL(clicked()), this, SLOT(quit()));
+
+            QVBoxLayout *layout = new QVBoxLayout;
+            layout->addWidget(textEdit);
+            layout->addWidget(quitButton);
+
+            setLayout(layout);
+
+            setWindowTitle(tr("Notepad"));
+        }
+    \endcode
+
+    As you saw in the class definition, we use pointers to our \l
+    {QObject}s (\c textEdit and \c quitButton). As a rule, you should
+    always allocate \l{QObject}s on the heap and never copy them.
+
+    We now use the function \l{QObject::}{tr()} around our user
+    visible strings. This function is necessary when you want to
+    provide your application in more than one language (e.g.  English
+    and Chinese). We will not go into details here, but you can follow
+    the \c {Qt Linguist} link from the learn more table.
+
+    \section2 Learn More
+
+    \table
+        \header
+            \o About
+            \o Here
+        \row
+            \o tr() and internationalization
+            \o \l{Qt Linguist Manual},
+               \l{Writing Source Code for Translation},
+               \l{Hello tr() Example},
+               \l{Internationalization with Qt}
+        \row
+            \o QObjects and the Qt Object model (This is essential to understand Qt)
+            \o \l{Object Model}
+        \row
+            \o qmake and the Qt build system
+            \o \l{qmake Manual}
+    \endtable
+
+    \section2 Creating a .pro file
+
+    For this example, we write our own \c .pro file instead of
+    using \c qmake's \c -project option.
+
+    \code
+        HEADERS =  notepad.h
+        SOURCES =  notepad.cpp \
+                   main.cpp
+    \endcode
+
+    The following shell commands build the example.
+
+    \code
+        qmake
+        make
+    \endcode
+
+    \section1 Using a QMainWindow
+
+    Many applications will benefit from using a QMainWindow, which has
+    its own layout to which you can add a menu bar, dock widgets, tool
+    bars, and a status bar. QMainWindow has a center area that can be
+    occupied by any kind of widget. In our case, we will place our
+    text edit there.
+
+    \image gs4.png
+
+    Let us look at the new \c Notepad class definition.
+
+    \code
+        #include <QtGui>
+
+        class Notepad : public QMainWindow
+        {
+            Q_OBJECT
+
+        public:
+            Notepad();
+
+        private slots:
+            void open();
+            void save();
+            void quit();
+
+        private:
+            QTextEdit *textEdit;
+
+            QAction *openAction;
+            QAction *saveAction;
+            QAction *exitAction;
+
+            QMenu *fileMenu;
+        };
+    \endcode
+
+    We include two more slots that can save and open a document. We
+    will implement these in the next section.
+
+    Often, in a main window, the same slot should be invoked by
+    several widgets. Examples are menu items and buttons on a tool
+    bar. To make this easier, Qt provides QAction, which can be given
+    to several widgets, and be connected to a slot. For instance, both
+    QMenu and QToolBar can create menu items and tool buttons from the
+    same \l{QAction}s. We will see how this works shortly.
+
+    As before, we use the \c {Notepad}s constructor to set up the
+    GUI.
+
+    \code
+        Notepad::Notepad()
+        {
+            saveAction = new QAction(tr("&Open"), this);
+            saveAction = new QAction(tr("&Save"), this);
+            exitAction = new QAction(tr("E&xit"), this);
+
+            connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
+            connect(saveAction, SIGNAL(triggered()), this, SLOT(save()));
+            connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit()));
+
+            fileMenu = menuBar()->addMenu(tr("&File"));
+            fileMenu->addAction(openAction);
+            fileMenu->addAction(saveAction);
+            fileMenu->addSeparator();
+            fileMenu->addAction(exitAction);
+
+            textEdit = new QTextEdit;
+            setCentralWidget(textEdit);
+
+            setWindowTitle(tr("Notepad"));
+        }
+    \endcode
+
+    \l{QAction}s are created with the text that should appear on the
+    widgets that we add them to (in our case, menu items). If we also
+    wanted to add them to a tool bar, we could have given
+    \l{QIcon}{icons} to the actions.
+
+    When a menu item is clicked now, the item will trigger the action,
+    and the respective slot will be invoked.
+
+    \section2 Learn More
+
+    \table
+        \header
+            \o About
+            \o Here
+        \row
+            \o Main windows and main window classes
+            \o \l{Application Main Window},
+               \l{Main Window Examples}
+        \row
+            \o MDI applications
+            \o QMdiArea,
+               \l{MDI Example}
+    \endtable
+
+    \section1 Saving and Loading
+
+    In this example, we will implement the functionality of the \c
+    open() and \c save() slots that we added in the previous example.
+
+    \image gs5.png
+
+    We will start with the \c open() slot:
+
+    \code
+        QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "",
+            tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
+
+        if (fileName != "") {
+            QFile file(fileName);
+            if (!file.open(QIODevice::ReadOnly)) {
+                QMessageBox::critical(this, tr("Error"),
+                    tr("Could not open file"));
+                return; 
+            }
+            QString contents = file.readAll().constData();
+            textEdit->setPlainText(contents);
+            file.close();
+        }
+    \endcode
+
+    The first step is asking the user for the name of the file to
+    open. Qt comes with QFileDialog, which is a dialog from which the
+    user can select a file. The image above shows the dialog on
+    Kubuntu. The static \l{QFileDialog::}{getOpenFileName()} function
+    displays a modal file dialog, and does not return until the user
+    has selected a file. It returns the file path of the file
+    selected, or an empty string if the user canceled the dialog. 
+
+    If we have a file name, we try to open the file with
+    \l{QIODevice::}{open()}, which returns true if the file could be
+    opened. We will not go into error handling here, but you can follow
+    the links from the learn more section. If the file could not be
+    opened, we use QMessageBox to display a dialog with an error
+    message (see the QMessageBox class description for further
+    details).
+
+    Actually reading in the data is trivial using the
+    \l{QIODevice::}{readAll()} function, which returns all data in the
+    file in a QByteArray. The \l{QByteArray::}{constData()} returns all
+    data in the array as a const char*, which QString has a
+    constructor for. The contents can then be displayed in the text
+    edit. We then \l{QIODevice::}{close()} the file to return the file
+    descriptor back to the operating system.
+
+    Now, let us move on to the the \c save() slot.
+
+    \code
+        QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "",
+            tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
+
+        if (fileName != "") {
+            QFile file(fileName);
+            if (!file.open(QIODevice::WriteOnly)) {
+                // error message
+            } else {
+                QTextStream stream(&file);
+                stream << textEdit->toPlainText();
+                stream.flush();
+                file.close();
+            }
+        }
+    \endcode
+
+    When we write the contents of the text edit to the file, we use
+    the QTextStream class, which wraps the QFile object. The text
+    stream can write QStrings directly to the file; QFile only accepts
+    raw data (char*) with the \l{QIODevice::}{write()} functions of
+    QIODevice.
+
+    \section2 Learn More
+
+    \table
+        \header
+            \o About
+            \o Here
+        \row
+            \o Files and I/O devices
+            \o QFile, QIODevice
+    \endtable
+
+    \omit
+    \section1 Moving On
+
+    This may not be true for the first release. 
+    The Qt documentation comes with three getting started guides. You
+    have come to the end of the first, which concerns itself with
+    basic Qt concepts. We also have guides covering intermediate and
+    advanced topics. They are found here: You may also have noticed that the learn more sections in
+    this guide frequently linked to them.
+    Basic Qt Architecture
+    \endomit
+*/
+