diff --git a/doc/addressbook-sdk.qdoc b/doc/addressbook-sdk.qdoc index 2ab021cdcde..a102eb665be 100644 --- a/doc/addressbook-sdk.qdoc +++ b/doc/addressbook-sdk.qdoc @@ -42,7 +42,7 @@ \image addressbook-tutorial-screenshot.png - In the process, we will learn about some basic technologies provided by + In the process, you will learn about some basic technologies provided by Qt, such as: \list @@ -88,21 +88,22 @@ \contentspage {Address Book Tutorial}{Contents} \nextpage {examples/addressbook-sdk/part2}{Chapter 2} \example examples/addressbook-sdk/part1 + \title Address Book 1 - Designing the User Interface The first part of this tutorial covers the design of the basic graphical - user interface (GUI) we use for the Address Book application. + user interface (GUI) you use for the Address Book application. The first step to creating a GUI program is to design the user interface. - In this chapter, our goal is to set up the labels and input fields needed + In this chapter, your goal is to set up the labels and input fields needed to implement a basic address book application. The figure below is a screenshot of our expected output. \image addressbook-tutorial-part1-screenshot.png - We begin by launching Qt Creator and use it to generate a new project. To - do this, select \gui{New File or Project...} from the \gui File menu. In - the \gui{New...} dialog, select \gui{Projects -> Qt4 Gui Application} and + Begin by launching Qt Creator and use it to generate a new project. To + do this, select \gui{File} > \gui{New File or Project...} > + \gui{Qt Application Project} > \gui{Qt Gui Application} and click \gui OK. Set your project name to \bold part1 with the QtCore and QtGui modules checked. Ensure that you select QWidget as your base class and name it \c AddressBook. @@ -122,12 +123,11 @@ \o \c{part1.pro} - the project file. \endlist - Now that we have all the files we need, click \gui Finish so can start - designing the user interface. - - \note For more information on how to create a \gui Project, see - \l {Creating a project}. + Now that you have all the files you need, click \gui Finish so you can + start designing the user interface. + \note For more details on how to create a \gui Project with Qt Creator, + refer to \l{Creating a Project}. \section1 Placing Widgets on The Form @@ -139,21 +139,26 @@ \image addressbook-tutorial-part1-designer-screenshot.png - We require two \l{QLabel}s to label the input fields as well as a QLineEdit - and a QTextEdit for the input fields. So, drag those widgets from the - \gui{Widget Box} to your form. In the \gui{Property Editor}, set their - \gui{objectName} property to \c nameLabel and \c addressLabel for the - \l{QLabel}s, \c nameLine for the QLineEdit and finally, \c addressText for - the QTextEdit. + You require two \l{QLabel}s to label the input fields as well as a + QLineEdit and a QTextEdit for the input fields. To create this follow the + steps mentioned below: + \list + \o Drag those widgets from the \gui{Widget Box} to your form. + \o In the \gui{Property Editor}, set their \gui{objectName} property to + \c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine + for the QLineEdit and finally, \c addressText for the QTextEdit. + \o Position the widgets properly, according to the screenshot above. + \o Use a QGridLayout to position our labels and input fields in a + structured manner. QGridLayout divides the available space into + a grid and places widgets in the cells you specify with row and + column numbers. + \o Place the caption of the \c addressLabel on the top, change the + vertical alignment property to \c AlignTop. + \endlist - Next, we have to position the widgets properly, according to the screenshot - earlier. We use a QGridLayout to position our labels and input fields in a - structured manner. QGridLayout divides the available space into a grid and - places widgets in the cells we specify with row and column numbers. To place - the caption of the \c addressLabel on the top, change the vertical alignment - property to \c AlignTop. The diagram below shows the layout cells and the - position of our widgets. Place your widgets accordingly and save the form by - choosing \gui{File -> Save} or using the \key{Ctrl+S} shortcut. + The figure below shows the layout cells and the position of our widgets. + Place your widgets accordingly and save the form by choosing + \gui{File} > \gui{Save} or use the shortcut key \key{Ctrl+S}. \image addressbook-tutorial-part1-labeled-screenshot.png @@ -162,19 +167,15 @@ red border, top level layouts have no graphical representation. Layouts are necessary for top level widgets, in this case QWidget, to ensure that when the window is resized, the widgets on the form will resize accordingly. You - can try this out by pressing \key{Ctrl+Alt+R} now. To correct it, simply click + can try this out by pressing \key{Ctrl+Alt+R} now. To correct it, click anywhere on the form and select \gui{Lay out Horizontally} or \gui{Lay out Vertically}. The output will be the same. Now your widgets will resize correctly. - \table - \row - \o \bold{Note:} Refer to the \l{Layout Classes} document for more - details on Qt's layout management classes. In addition, the - \l{Getting to Know Qt Designer} document explains how to use - layouts with \QD. - \endtable - + \note Refer to the \l{Layout Classes} document for more + details on Qt's layout management classes. In addition, the + \l{Getting to Know Qt Designer} document explains how to use + layouts with \QD. \section1 The AddressBook Class @@ -191,7 +192,7 @@ \snippet examples/addressbook-sdk/part1/addressbook.h class definition - Qt Creator's \gui{Project Wizard} provides us with the \c Ui object as a + Qt Creator's \gui{Project Wizard} provides you with the \c Ui object as a way to access the widgets on our form. The \l{examples/addressbook-sdk/part1/addressbook.cpp}{\c addressbook.cpp} @@ -223,23 +224,24 @@ \section1 Running the Application - To run your application with Qt Creator, simply click on the Play button - (image). A bare bones Address Book will be displayed. Click on the X button - to close it. + To run your application with Qt Creator, simply click, + \inlineimage qtcreator-run.png. + A bare bones Address Book will be displayed. + \section1 Qt Programming - Subclassing - When writing Qt programs, we usually subclass Qt objects to add + When writing Qt programs, you usually subclass Qt objects to add functionality. This is one of the essential concepts behind creating custom widgets or collections of standard widgets. Subclassing to extend or change the behavior of a widget has the following advantages: \list - \o We can write implementations of virtual or pure virtual functions - to obtain exactly what we need, falling back on the base class's + \o You can write implementations of virtual or pure virtual functions + to obtain exactly what you need, falling back on the base class's implementation when necessary. - \o It allows us to encapsulate parts of the user interface within a + \o It allows you to encapsulate parts of the user interface within a class, so that the other parts of the application do not need to know about the individual widgets in the user interface. \o The subclass can be used to create multiple custom widgets in the @@ -247,10 +249,12 @@ reused in other projects. \endlist - Since Qt does not provided a specific address book widget, we subclass a + Since Qt does not provided a specific address book widget, you subclass a standard Qt widget class and add features to it. The \c AddressBook class - we create in this tutorial can be reused in situations where a basic + you create in this tutorial can be reused in situations where a basic address book is needed. + + */ @@ -267,56 +271,58 @@ \image addressbook-tutorial-part2-add-contact.png - We will provide a push button that the user can click to add a new contact. - Also, some form of data structure is needed to store these contacts in an - organized way. + You will provide a push button that the user can click to add a new + contact. Also, some form of data structure is needed to store these + contacts in an organized way. \section1 Placing Widgets on The Form - We shall continue with the form we had from the last chapter; we have the - labels and input fields set up, but we need to add push buttons to complete - the process of adding a contact. So, we begin by breaking the existing - layouts: select \gui{Break Layout} from the context menu. You might have to - do a \gui{Select All} with \key{Ctrl+A} first.. Then, we add three push - buttons. Double-click on each of them to set their text to "Add", "Submit", - and "Cancel". Next, set the \c objectName of the buttons to \c addButton, - \c submitButton and \c cancelButton respectively. - We now require a vertical spacer to ensure that the push buttons will be laid - out neatly; drag one from the \gui{Widget Box}. + You can continue with the form from the last chapter; you have the + labels and input fields set up, but you need to add push buttons to + complete the process of adding a contact. Break the existing layouts by + following the steps below: + \list + \o Select, \gui{Break Layout} from the context menu. You might have to + do a \gui{Select All} with \key{Ctrl+A} first.. + \o Add three push buttons and double-click on each of them to set + their text to "Add", "Submit", and "Cancel". + \o Set the \c objectName of the buttons to \c addButton, + \c submitButton and \c cancelButton respectively. + \o A \gui{Vertical Spacer} is required to ensure that the push buttons + will be laid out neatly; drag one from the \gui{Widget Box}. + \o Lay out these three push buttons and the spacer vertically, by + selecting all three of them using \key{Ctrl + click} and selecting + \gui{Lay out Vertically} from the context menu. Alternatively you + can use the \key{Ctrl+L} shortcut key. - ## image for button missing - - Next, lay out these three push buttons and the spacer vertically, by - selecting all three of them (using the \key{Ctrl + click}) and choosing - \gui{Lay out Vertically} from the context menu. Alternatively you can click - on the ... button or use the \key{Ctrl+L} shortcut. We use the spacer as we - do not want the buttons to be evenly spaced, but arranged closer to the top - of the widget. The figure below shows the difference between using the - spacer and not using it. - - \image addressbook-tutorial-part2-stretch-effects.png - - Select all the objects on the form (use \key{Ctrl+A}) and lay them out in a - grid. Lastly, set the top level widget's layout by right-clicking anywhere - on the widget and selecting \gui{Lay out Horizontally} or - \gui{Lay out Vertically}. + \note Use the spacer as you do not want the buttons to be evenly + spaced, but arranged closer to the top of the widget. + \o The figure below shows the difference between using the spacer and + not using it. + \image addressbook-tutorial-part2-stretch-effects.png + \o Select all the objects on the form using, \key{Ctrl+A} and lay them + out in a grid. + \o Lastly, set the top level widget's layout by right-clicking anywhere + on the widget and selecting \gui{Lay out Horizontally} or + \gui{Lay out Vertically}. + \endlist The final design of the form is shown in the screenshot below: - ## image + \image addressbook-tutorial-part2-form-design.png \section1 The AddressBook Class - To ensure that the Address Book reacts to user interaction, we need to - write slots for each push button that we added earlier. A slot is a - function that responds to a particular signal. We will discuss this - concept in further detail below. However, for an overview of Qt's signals + To ensure that the Address Book reacts to user interaction, you need to + write slots for each push button that you added earlier. A slot is a + function that responds to a particular signal. This concept will be + discussed further in detail below. However, for an overview of Qt's signals and slots concept, you can refer to the \l{Signals and Slots} document. In the \l{examples/addressbook-sdk/part2/addressbook.h}{\c addressbook.h} - file, we add the following code: + file, add the following code: \snippet examples/addressbook-sdk/part2/addressbook.h slot definition @@ -325,53 +331,54 @@ \snippet examples/addressbook-sdk/part2/addressbook.h include - We need a container to store our address book contacts, so that we can + You need a container to store our address book contacts, so that you can traverse and display them. A QMap object, \c contacts, is used for this purpose as it holds a key-value pair: the contact's name as the \e key, and the contact's address as the \e value. \snippet examples/addressbook-sdk/part2/addressbook.h members - We also declare two private QString objects, \c oldName and \c oldAddress. + You also declare two private QString objects, \c oldName and \c oldAddress. These objects are needed to hold the name and address of the contact that - was last displayed, before the user clicked \gui Add. So, when the user - clicks \gui Cancel, we can revert to displaying the details of the last + was last displayed, before you click \gui Add. So, when you + click \gui Cancel, you can revert to displaying the details of the last contact. - ## this is a bit confusing, as the ctor was not defined by us nor is a slot - Let's move on to implementing the slots we defined earlier. Within the - constructor of \c AddressBook, we set up our fields by ensuring that - \c nameLine and \c addressText are read-only, so that we can only display - but not edit existing contact details. Note that in order to prevent - crashes, you need make sure that the autogenerated \c setupUi() call - is always first in the constructor. + + Let's move on to implementing the slots defined earlier. Within the + constructor of \c AddressBook, you set up our fields by ensuring that + \c nameLine and \c addressText are read-only, so that you can only display + but not edit existing contact details. + + \note In order to prevent crashes, you need make sure that the + autogenerated \c setupUi() call is always first in the constructor. \snippet examples/addressbook-sdk/part2/addressbook.cpp setup fields - We also hide both \c submitButton and \c cancelButton as they will only be - displayed when the user clicks \gui Add, and this is handled by the + You also hide both \c submitButton and \c cancelButton as they will only be + displayed when you click \gui Add, and this is handled by the \c addContact() function discussed below. \snippet examples/addressbook-sdk/part2/addressbook.cpp signal slot - We connect the push buttons' \l{QAbstractButton::}{clicked()} signal to + You connect the push buttons' \l{QAbstractButton::}{clicked()} signal to their respective slots. The figure below illustrates this. \image addressbook-tutorial-part2-signals-and-slots.png - Finally, we set the window title to "Simple Address Book" using the + Finally, set the window title to "Simple Address Book" using the \l{QWidget::}{setWindowTitle()} function. The tr() method allows us - to translate user interface strings. Refer to ###. + to translate user interface strings. \snippet examples/addressbook-sdk/part2/addressbook.cpp window title \section2 The \c addContact() Function - In this function, we begin by storing the last displayed contact details - in \c oldName and \c oldAddress. Then we clear these input fields and turn - off the read-only mode. The focus is set on \c nameLine and we display - \c submitButton and \c cancelButton; but we disable \c addButton. + In this function, begin by storing the last displayed contact details + in \c oldName and \c oldAddress. Then clear these input fields and turn + off the read-only mode. The focus is set on \c nameLine and display + \c submitButton and \c cancelButton; but disable \c addButton. \snippet examples/addressbook-sdk/part2/addressbook.cpp addContact @@ -380,30 +387,30 @@ This function can be divided into three parts: \list 1 - \o We extract the contact's detail from \c nameLine and \c addressText - and store them in QString objects. We also validate to ensure that - the user did not click \gui Submit with empty input fields; - otherwise, a QMessageBox is displayed to remind the user for a name + \o Extract the contact's detail from \c nameLine and \c addressText + and store them in QString objects. Also validate to ensure that + you did not click \gui Submit with empty input fields; + otherwise, a QMessageBox is displayed to remind you for a name and address. \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1 - \o We then proceed to check if the contact already exists. If it does - not exist, we add the contact to \c contacts and we display a - QMessageBox to inform the user about this, preventing the user from + \o Then proceed to check if the contact already exists. If it does + not exist, add the contact to \c contacts and display a + QMessageBox to inform you about this, preventing you from adding duplicate contacts. Our \c contacts object is based on - key-value pairs or name and address, hence, we want to ensure that + key-value pairs or name and address, hence, you want to ensure that \e key is unique. \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2 - \o Once we have handled both cases mentioned above, we restore the + \o Once you have handled both cases mentioned above, restore the push buttons to their normal state with the following code: \snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3 \endlist - The screenshot below shows the QMessageBox object we use to display + The screenshot below shows the QMessageBox object used to display information messages to the user. \image addressbook-tutorial-part2-add-successful.png @@ -415,7 +422,7 @@ \snippet examples/addressbook-sdk/part2/addressbook.cpp cancel - The general idea behind adding a contact is to give the user the + The general idea behind adding a contact is to give you the flexibility to click \gui Submit or \gui Cancel at any time. The flowchart below further explains this concept: @@ -438,115 +445,121 @@ \example examples/addressbook-sdk/part3 \title Address Book 3 - Navigating between Entries - The address book application is now half complete. We need to add some - functions to navigate between contacts. But first, we have to decide what - sort of a data structure we would like to use to hold these contacts. + The address book application is now half complete. You need to add some + functions to navigate between contacts. But first, you have to decide what + sort of a data structure you would like to use to hold these contacts. - In Chapter 2, we used a QMap of key-value pairs with the contact's name as + In Chapter 2, you used a QMap of key-value pairs with the contact's name as the \e key, and the contact's address as the \e value. This works well for - our case. However, in order to navigate and display each entry, a little + your case. However, in order to navigate and display each entry, a little bit of enhancement is needed. - We enhance the QMap by making it replicate a data structure similar to a + Enhance the QMap by making it replicate a data structure similar to a circularly-linked list, where all elements are connected, including the first element and the last element. The figure below illustrates this data - structure; + structure. \image addressbook-tutorial-part3-linkedlist.png \section1 Placing Widgets on The Form - So far, our application allows us to add new contacts. However, we also - need to traverse the existing contacts. To do so, we add two push buttons - at the bottom of our application and name them: \gui Next and - \gui Previous. The buttons' \c objectName should be \c nextButton and - \c previousButton, respectively. Then, we break our top level layout. - Simply right-click on \c AddressBook in the \gui{Object Inspector} and - then select \gui{Lay out|Break Layout}. Place the \gui Next and - \gui Previous buttons in a horizontal layout. Now drag and drop the buttons - together with their layout into the existing grid layout. The screenshot - below illustrates what you will see as the button layout approaches the - grid layout; drop it then. + So far, your application allows us to add new contacts. However, you also + need to traverse the existing contacts. To do so follow the steps + mentioned below: + \list + \o Add two push buttons at the bottom of your application and name + them: \gui Next and \gui Previous. + \o The buttons' \c objectName should be \c nextButton and + \c previousButton, respectively. + \o Break your top level layout by right-clicking on \c AddressBook in + the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}. + \o Place the \gui Next and \gui Previous buttons in a horizontal + layout. + \o Drag and drop the buttons together with their layout into the + existing grid layout. + \o Set a top level layout for the widget again. + \endlist + + The screenshot below illustrates what you will see as the button layout + approaches the grid layout; drop it then. \image addressbook-tutorial-part3-drop-in-gridlayout.png - Finally, set a top level layout for the widget again. - - \note We follow basic conventions for \c next() and \c previous() functions + \note Follow basic conventions for \c next() and \c previous() functions by placing the \c nextButton on the right and the \c previousButton on the left. \section1 The AddressBook Class - Let's move on to the code. In order to add navigation functions to the - address book application, we need to add two more slots to our - \c AddressBook class: \c next() and \c previous(). + In order to add navigation functions to the address book application, + you need to add two more slots to our \c AddressBook class: \c next() and + \c previous(). \snippet examples/addressbook-sdk/part3/addressbook.h slot definition - In the \c AddressBook constructor, we setup our fields and disable them by - default. This is because navigation is only enabled when there is more than - one contact in the address book. + In the \c AddressBook constructor, you setup your fields and disable them + by default. This is because navigation is only enabled when there is more + than one contact in the address book. \snippet examples/addressbook-sdk/part3/addressbook.cpp setup fields - Next, we connect the buttons to their respective slots: + Next, connect the buttons to their respective slots: \snippet examples/addressbook-sdk/part3/addressbook.cpp signal slot - The screenshot below is our expected graphical user interface. Notice that - it is getting closer to our final application. + The screenshot below is your expected graphical user interface. Notice that + it is getting closer to your final application. \image addressbook-tutorial-part3-screenshot.png - Within our \c addContact() function, we have to disable the \gui Next and - \gui Previous buttons so that the user does not attempt to navigate while + Within your \c addContact() function, you have to disable the \gui Next and + \gui Previous buttons so that you do not attempt to navigate while adding a contact. \snippet examples/addressbook-sdk/part3/addressbook.cpp disable navigation - Also, in our \c submitContact() function, we enable the navigation buttons, - depending on the size of \c contacts. Asmentioned earlier, navigation is + Also, in your \c submitContact() function, enable the navigation buttons, + depending on the size of \c contacts. As mentioned earlier, navigation is only enabled when there is more than one contact in the address book. The following lines of code demonstrates how to do this: \snippet examples/addressbook-sdk/part3/addressbook.cpp enable navigation - We also include these lines of code in the \c cancel() function. + Also include these lines of code in the \c cancel() function. - Recall that we intend to emulate a circularly-linked list with our QMap - object, \c contacts. So in the \c next() function, we obtain an iterator + Recall that you intend to emulate a circularly-linked list with your QMap + object, \c contacts. So in the \c next() function, obtain an iterator for \c contacts and then: \list - \o If the iterator is not at the end of \c contacts, we increment it by + \o If the iterator is not at the end of \c contacts, increment it by one. - \o If the iterator is at the end of \c contacts, we move it to the - beginning of \c contacts. This gives us the illusion that our QMap + \o If the iterator is at the end of \c contacts, move it to the + beginning of \c contacts. This gives an illusion that our QMap is working like a circularly-linked list. \endlist \snippet examples/addressbook-sdk/part3/addressbook.cpp next - Once we have iterated to the current object in \c contacts, we display its + Once you have iterated to the current object in \c contacts, display its contents on \c nameLine and \c addressText. - Similarly, for the \c previous() function,we obtain an iterator for + Similarly, for the \c previous() function, obtain an iterator for \c contacts and then: \list - \o If the iterator is at the end of \c contacts, we clear the display + \o If the iterator is at the end of \c contacts, clear the display and return. - \o If the iterator is at the beginning of \c contacts, we move it to + \o If the iterator is at the beginning of \c contacts, move it to the end. - \o We then decrement the iterator by one. + \o Then decrement the iterator by one. \endlist \snippet examples/addressbook-sdk/part3/addressbook.cpp previous - Again, we display the contents of the current object in \c contacts. + Again, display the contents of the current object in \c contacts. */ @@ -559,31 +572,31 @@ \example examples/addressbook-sdk/part4 \title Address Book 4 - Editing and Removing Addresses - In this chapter, we look at ways to modify the contents of contacts stored + This chapter looks at ways to modify the contents of contacts stored in the address book application. - #screenshot + \image addressbook-tutorial-part4-screenshot.png - We now have an address book that not only holds contacts in an organized + You now have an address book that not only holds contacts in an organized manner, but also allows navigation. It would be convenient to include edit and remove functions so that a contact's details can be changed when needed. However, this requires a little improvement, in the form of enums. - In our previous chapters, we had two modes: \c AddingMode and - \c NavigationMode - but they were not defined as enums. Instead, we enabled - and disabled the corresponding buttons manually, resulting in multiple - lines of repeated code. + In our previous chapters, you had two modes: \c AddingMode and + \c NavigationMode - but they were not defined as enums. Instead, you + enabled and disabled the corresponding buttons manually, resulting in + multiple lines of repeated code. - In this chapter, we define the \c Mode enum with three different values: + In this chapter, define the \c Mode enum with three different values: \list - \o \c{NavigationMode}, - \o \c{AddingMode}, and - \o \c{EditingMode}. + \o \c{NavigationMode} + \o \c{AddingMode} + \o \c{EditingMode} \endlist \section1 Placing Widgets on The Form - To edit and remove contacts, we need two push buttons. Drag them and name + To edit and remove contacts, you need two push buttons. Drag them and name them accordingly. Their \c objectName properties should be \c editButton and \c removeButton, respectively. The quickest way to place these two buttons into our existing layout, is to simply drag and drop them. Use the @@ -594,21 +607,21 @@ \section1 The AddressBook Class - We update the header file to contain the \c Mode enum: + Update the header file to contain the \c Mode enum: \snippet examples/addressbook-sdk/part4/addressbook.h enum - We also add two new slots, \c editContact() and \c removeContact(), to our + Also add two new slots, \c editContact() and \c removeContact(), to your current list of public slots. \snippet examples/addressbook-sdk/part4/addressbook.h slot definition - In order to switch between modes, we introduce the \c updateInterface() + In order to switch between modes, introduce the \c updateInterface() function to control the enabling and disabling of all push buttons. \snippet examples/addressbook-sdk/part4/addressbook.h updateInterface - Lastly, we declare \c currentMode to keep track of the enum's current mode. + Lastly, declare \c currentMode to keep track of the enum's current mode. \snippet examples/addressbook-sdk/part4/addressbook.h current mode @@ -623,10 +636,9 @@ \snippet examples/addressbook-sdk/part4/addressbook.cpp signal slot - Now we look at the \c editContact() and \c removeContact() functions in + Now look at the \c editContact() and \c removeContact() functions in detail. - \section2 The \c editContact() Function This function stores the contact's old details in \c oldName and @@ -636,58 +648,58 @@ \snippet examples/addressbook-sdk/part4/addressbook.cpp editContact - Since we will reuse the \c submitButton for both: adding a new contact and - editing an existing contact, we need to modify our existing - \c submitContact() function. So, we divide it in two with an \c{if-else} + Since you will reuse the \c submitButton for both: adding a new contact and + editing an existing contact, you need to modify our existing + \c submitContact() function. So, divide it in two with an \c{if-else} statement. - First, we check \c currentMode to see if it is in \c AddingMode. If it is, - we proceed with our adding process. + First, check \c currentMode to see if it is in \c AddingMode. If it is, + proceed with your adding process. \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part1 \dots \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part2 - Otherwise, we check to see if \c currentMode is in \c EditingMode. If it - is, we compare \c oldName with \c name. If the name has changed, we remove + Otherwise, check to see if \c currentMode is in \c EditingMode. If it + is, compare \c oldName with \c name. If the name has changed, remove the old contact from \c contacts and insert the newly updated contact. \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part3 - If only the contact's address changed, i.e., \c oldAddress is not the same - as \c address, we update the contact's address. Lastly, we set + If only the contact's address has changed, that is the \c oldAddress is + not the same as \c address, update the contact's address. Lastly, set \c currentMode to \c NavigationMode. This is an important step as it re-enables all the disabled push buttons. - To remove a contact from the address book, we implement the + To remove a contact from the address book, implement the \c removeContact() function. \snippet examples/addressbook-sdk/part4/addressbook.cpp removeContact This function first checks to see if the contact exists in \c contacts. If - it does, we display a QMessageBox, to confirm the removal with the user. - Once the user has confirmed, we call \c previous() to ensure that the - user interface shows another contact, and we remove the contact using - \l{QMap}'s \l{QMap::}{remove()} function. As a courtesy, we display a + it does, display a QMessageBox, to confirm the removal with the user. + Once the user has confirmed, call \c previous() to ensure that the + user interface shows another contact, and remove the contact using + \l{QMap}'s \l{QMap::}{remove()} function. As a courtesy, display a QMessageBox to inform the user. Both the message boxes used in this function are shown below: - # image - + \image addressbook-tutorial-part4-confirm.png + \image addressbook-tutorial-part4-remove.png \section2 The \c updateInterface() Function - We mentioned this function earlier as a means to enable and disable the + This function is mentioned earlier as a means to enable and disable the push buttons, depending on the current mode. The function updates the current mode according to the \c mode argument passed to it, assigning it - to \c currentMode, before checking its value.\ + to \c currentMode, before checking its value. Each of the push buttons is then enabled or disabled, depending on the current mode. The code for \c AddingMode and \c EditingMode is shown below: \snippet examples/addressbook-sdk/part4/addressbook.cpp updateInterface part1 - For \c NavigationMode, however, we include conditions within the parameters + For \c NavigationMode, however, include conditions within the parameters of the QPushButton::setEnabled() function. This is to ensure that \c editButton and \c removeButton are enabled when there is at least one contact in the address book; \c nextButton and \c previousButton are only @@ -696,10 +708,10 @@ \snippet examples/addressbook-sdk/part4/addressbook.cpp updateInterface part2 By performing the task of setting the mode and updating the user interface - in the same function, we avoid the possibility of the user interface + in the same function, you avoid the possibility of the user interface getting "out of sync" with the internal state of the application. - To maintain consistency, we need to modify our \c addContact() and + To maintain consistency, you need to modify our \c addContact() and \c cancel() functions respectively. Below is the code: \snippet examples/addressbook-sdk/part4/addressbook.cpp addContact @@ -717,34 +729,36 @@ \example examples/addressbook-sdk/part5 \title Address Book 5 - Adding a Find Function - In this chapter, we look at ways to locate contacts and addresses in the + This chapter looks at ways to locate contacts and addresses in the address book application. \image addressbook-tutorial-part5-screenshot.png - As we keep adding contacts to our address book, it becomes tedious to + As you keep adding contacts to your address book, it becomes tedious to navigate them with the \gui Next and \gui Previous buttons. In this case, a \gui Find function would be more efficient in looking up contacts. The screenshot above shows the \gui Find button and its position on the panel of buttons. - When the user clicks on the \gui Find button, it is useful to display a + When you click on the \gui Find button, it is useful to display a dialog prompting the user for a contact's name. Qt provides QDialog, which - we subclass in this chapter, to implement a FindDialog class. + you subclass in this chapter, to implement a FindDialog class. \section1 Designing The FindDialog \image addressbook-tutorial-part5-finddialog-in-designer.png - We begin by adding a new \c{.ui} file and a corresponding class to our project. Right click on your - project and select \gui{Add New...}. In the \gui{New File} dialog, select - \gui{Qt Designer Form Class}. In the \gui{Qt Designer Form Class} dialog, select - \e{Dialog without buttons}. Name the class \c{FindDialog} and add the files it to your - project. Open your new form in the \QD form editor within Qt Creator by - double-clicking on the \c{finddialog.ui} file in the \gui{Project Sidebar}. + Begin by adding a new \c{.ui} file and a corresponding class to our + project. Right click on your project and select + \gui{Add New...} > \gui{Qt} > \gui{Qt Designer Form Class}. + In the \gui{Qt Designer Form Class} dialog, select + \e{Dialog without buttons}. Name the class \c{FindDialog} and add the files + it to your project. Open your new form in the \QD form editor within + Qt Creator by double-clicking on the \c{finddialog.ui} file in + the \gui{Project Sidebar}. - To replicate the screenshot above, we need a label, a line edit, and a push + To replicate the screenshot above, you need a label, a line edit, and a push button. Drag these onto your form. Set their text accordingly and name them \c label, \c lineEdit, and \c findButton, respectively. Place these widgets in a horizontal layout. Then set a top level layout - either horizontal or @@ -753,11 +767,11 @@ \section1 Implementing The FindDialog Class - Let's look at \c{FindDialog}'s header file. We define a public function, + Let's look at \c{FindDialog}'s header file. Define a public function, \c findText(), to be used by classes that instantiate \c FindDialog. This - function allows the these classes to obtain the search string entered by - the user. A public slot, \c findClicked(), is also defined to handle the - search string when the user clicks the \gui Find button. + function allows the classes to obtain the search string entered by + you. A public slot, \c findClicked(), is also defined to handle the + search string when you click the \gui Find button. \snippet examples/addressbook-sdk/part5/finddialog.h findText \dots @@ -767,50 +781,51 @@ \snippet examples/addressbook-sdk/part5/finddialog.cpp constructor - In \c findClicked(), we validate to ensure that the user did not click the - \gui Find button without entering a contact's name. Then, we set + In \c findClicked(), validate to ensure that you did not click the + \gui Find button without entering a contact's name. Then, set \c findText to the search string, extracted from \c lineEdit. After that, - we clear the contents of \c lineEdit and hide the dialog. + clear the contents of \c lineEdit and hide the dialog. \snippet examples/addressbook-sdk/part5/finddialog.cpp findClicked \c findText() is public, which makes it easy for classes instantiating - and using \c FindDialog to access the search string that the user has entered + and using \c FindDialog to access the search string that you have entered and accepted. \snippet examples/addressbook-sdk/part5/finddialog.cpp findText - Finally, we connect our signals to their respective slots. Notice that + Finally, connect your signals to their respective slots. Notice that \c{findButton}'s \l{QPushButton::}{clicked()} signal is connected to - \c findClicked(), which calls \l{QDialog::}{accept()} or \l{QDialog::}{reject()}. - The \l{QDialog::}{accept()} slot provided by QDialog hides the dialog - and sets the result code to \l{QDialog::}{Accepted}, while \l{QDialog::}{reject()} - sets it to \l{QDialog::}{Rejected} accordingly. We use this function to help - \c{AddressBook}'s \c findContact() function know when the \c FindDialog object has been - closed. We will explain this logic in further detail when discussing the - \c findContact() function. + \c findClicked(), which calls \l{QDialog::}{accept()} or + \l{QDialog::}{reject()}. The \l{QDialog::}{accept()} slot provided by + QDialog hides the dialog and sets the result code to + \l{QDialog::}{Accepted}, while \l{QDialog::}{reject()} + sets it to \l{QDialog::}{Rejected} accordingly. Use this function to help + \c{AddressBook}'s \c findContact() function know when the \c FindDialog + object has been closed. This logic will be explained in further detail + when discussing the \c findContact() function. \image addressbook-tutorial-part5-signals-and-slots.png \section1 The AddressBook Class - To ensure that we can use \c FindDialog from within our \c AddressBook - class, we include \c finddialog.h in the \c addressbook.h file. + To ensure that you can use \c FindDialog from within your \c AddressBook + class, include \c finddialog.h in the \c addressbook.h file. \snippet examples/addressbook-sdk/part5/addressbook.h include - So far, all our address book features have a QPushButton and a - corresponding slot. Similarly, for the \gui Find feature, we have + So far, all your address book features have a QPushButton and a + corresponding slot. Similarly, the \gui Find feature, has \c{ui->findButton} and \c findContact(). \snippet examples/addressbook-sdk/part5/addressbook.h slot definition - Once we have instantiated a dialog, we might want to use it more than once; - using a private variable allows us to refer to it from more than one place - in the class. + Once you have instantiated a dialog, you might want to use it more than + once; using a private variable allows you to refer to it from more than one + place in the class. - Within the \c AddressBook class's constructor, we connect the + Within the \c AddressBook class's constructor, connect the \c{findButton}'s \l{QPushButton::}{clicked()} signal to \c findContact(). \snippet examples/addressbook-sdk/part5/addressbook.cpp signal slot @@ -819,26 +834,26 @@ \snippet examples/addressbook-sdk/part5/addressbook.cpp findContact - We start out by displaying the \c FindDialog instance, \c dialog. This is - when the user enters a contact name to look up. Once the user clicks the + Start out by displaying the \c FindDialog instance, \c dialog. This is + when you enter a contact name to look up. Once you click the dialog's \c findButton, the dialog is hidden and the result code is set to either QDialog::Accepted or QDialog::Rejected by the FindDialog's - \c findClicked() method. This ensures that we only search for a contact - if the user typed something in the FindDialog's line edit. + \c findClicked() method. This ensures that you only search for a contact + if you have typed something in the FindDialog's line edit. - We then proceed to extract the search string, which in this case is + Then proceed to extract the search string, which in this case is \c contactName, using \c{FindDialog}'s \c findText() function. If the - contact exists in our address book, we display it immediately. Otherwise, - we display the QMessageBox shown below to indicate that their search + contact exists in our address book, display it immediately. Otherwise, + display the QMessageBox shown below to indicate that their search failed. \image addressbook-tutorial-part5-dialogbox.png - The concept behind finding a contact only applies for cases where we have - more than two contacts in our address book. Hence, we implement this - behavior by modifying our \c{Navigation Mode} within our + The concept behind finding a contact only applies for cases where you have + more than two contacts in our address book. Hence, implement this + behavior by modifying our \c{Navigation Mode} within your \c updateInterface() function, by only enabling the \gui Find button when - we have more than two contacts. + you have more than two contacts. \snippet examples/addressbook-sdk/part5/addressbook.cpp enable @@ -853,20 +868,20 @@ \example examples/addressbook-sdk/part6 \title Address Book 6 - Loading and Saving - This chapter covers the file handling features of Qt that we used to write + This chapter covers the file handling features of Qt that is used to write loading and saving routines for the address book application. \image addressbook-tutorial-part6-screenshot.png - Although browsing and searching for contacts are useful features, our - address book is not really ready for use until we can save existing + Although browsing and searching for contacts are useful features, your + address book is not really ready for use until you can save existing contacts and load them again at a later time. Qt provides a number of - classes for \l{Input/Output and Networking}{input and output}, but we have + classes for \l{Input/Output and Networking}{input and output}, but you have chosen to use two which are simple to use in combination: QFile and QDataStream. A QFile object represents a file on disk that can be read from and written - to. QFile isa subclass of the more general QIODevice class which represents + to. QFile is a subclass of the more general QIODevice class which represents many different kinds of devices. A QDataStream object is used to serialize binary data so that it can be @@ -877,20 +892,20 @@ \section1 Placing Widgets on The Form - To load and save files containing contact details, we need two push + To load and save files containing contact details, you need two push buttons. Drag them and name them accordingly. Their \c objectName properties should be \c loadButton and \c saveButton, respectively. Then, - similar to \l{Address Book 5 - Adding a Find Function}{Chapter 5}, we place + similar to \l{Address Book 5 - Adding a Find Function}{Chapter 5}, place these buttons in our layout simply by dragging and dropping them. The \c text property of our push buttons are \gui{Load...} and \gui{Save...} respectively. Ideally, it would be more user-friendly to set the push buttons' labels to \gui{Load contacts from file} and \gui{Save contacts to file}. However, due to the size of our push buttons, - we set the labels to \gui{Load...} and \gui{Save...} instead. + set the labels to \gui{Load...} and \gui{Save...} instead. Fortunately, Qt Creator's \QD plugin provides a simple way to set tooltips - with the \c toolTip property. So, we set our buttons' tooltips to + with the \c toolTip property. So, set your buttons' tooltips to \gui{Load contacts from file} and \gui{Save contacts to file} respectively. To test your tooltip, use \key{Ctrl+Alt+R} and hover your mouse cursor on the push buttons. @@ -901,7 +916,7 @@ \section1 The AddressBook Class - We declare two public slots, \c saveToFile() and \c loadFromFile(). + Declare two public slots, \c saveToFile() and \c loadFromFile(). \snippet examples/addressbook-sdk/part6/addressbook.h slot definition @@ -911,11 +926,11 @@ \section2 The \c saveToFile() Function - To save a contact, we first obtain \c fileName using + To save a contact, first obtain \c fileName using QFileDialog::getSaveFileName(). This is a convenience function provided by - QFileDialog, which pops up a modal file dialog and allows the user to enter + QFileDialog, which pops up a modal file dialog and allows you to enter a file name or select any existing \c{.abk} file. The \c{.abk} file is our - Address Book extension that we create when we save contacts. + Address Book extension that you create when you save contacts. \snippet examples/addressbook-sdk/part6/addressbook.cpp saveToFile part1 @@ -923,18 +938,18 @@ \image addressbook-tutorial-part6-savedialog.png - If \c fileName is not empty, we create a QFile object, \c file, with + If \c fileName is not empty, create a QFile object, \c file, with \c fileName. The QFile object works with QDataStream as QFile is a QIODevice. - Next, we attempt to open the file in \l{QIODevice::}{WriteOnly} mode. If - this is unsuccessful, we display a QMessageBox to inform the user. + Next, attempt to open the file in \l{QIODevice::}{WriteOnly} mode. If + this is unsuccessful, display a QMessageBox to inform the user. \snippet examples/addressbook-sdk/part6/addressbook.cpp saveToFile part2 - Otherwise, we instantiate a QDataStream object, \c out, to write the open + Otherwise, instantiate a QDataStream object, \c out, to write the open file. QDataStream requires that the same version of the stream is used for - reading and writing. We ensure that this is the case by setting the version + reading and writing. Ensure that this is the case by setting the version used to the version introduced with Qt 4.5 before serializing the data into \c file. \snippet examples/addressbook-sdk/part6/addressbook.cpp saveToFile part3 @@ -942,10 +957,10 @@ \section2 The \c loadFromFile() Function - To load a contact, we also obtain \c fileName using + To load a contact, also obtain \c fileName using QFileDialog::getOpenFileName(). This function, the counterpart to QFileDialog::getSaveFileName(), also pops up the modal file dialog and - allows the user to enter a file name or select any existing \c{.abk} file + allows you to enter a file name or select any existing \c{.abk} file to load it into the address book. \snippet examples/addressbook-sdk/part6/addressbook.cpp loadFromFile part1 @@ -955,14 +970,14 @@ \image addressbook-tutorial-part6-opendialog.png - If \c fileName is not empty, again, we use a QFile object, \c file, and - attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our - implementation of \c saveToFile(), if this attempt is unsuccessful, we + If \c fileName is not empty, again, use a QFile object, \c file, and + attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to your + implementation of \c saveToFile(), if this attempt is unsuccessful, display a QMessageBox to inform the user. \snippet examples/addressbook-sdk/part6/addressbook.cpp loadFromFile part2 - Otherwise, we instantiate a QDataStream object, \c in, set its version as + Otherwise, instantiate a QDataStream object, \c in, set its version as above and read the serialized data into hte \c contacts data structure. The \c contacs object is emptied before data is read into it to simplify the file reading process. A more advanced method would be to read the contacts @@ -971,11 +986,11 @@ \snippet examples/addressbook-sdk/part6/addressbook.cpp loadFromFile part3 - To display the contacts that have been read from the file, we must first - validate the data obtained to ensure that the file we read from actually - contains address book contacts. If it does, we display the first contact; - otherwise, we display a QMessageBox to inform the user about the problem. - Lastly, we connect the \c clicked() signal of the push buttons + To display the contacts that have been read from the file, you must first + validate the data obtained to ensure that the file you read from actually + contains address book contacts. If it does, display the first contact; + otherwise, display a QMessageBox to inform you about the problem. + Lastly, connect the \c clicked() signal of the push buttons with the \c loadFromFile() and \c saveToFile(): \snippet examples/addressbook-sdk/part6/addressbook.cpp connectSlots @@ -990,15 +1005,15 @@ \example examples/addressbook-sdk/part7 \title Address Book 7 - Additional Features - Although our address book application is useful in its own right, it would - be useful it we could exchange contact data with other applications. The + Although your address book application is useful in its own right, it would + be useful if you could exchange contact data with other applications. The vCard format is a popular file format that can be used for this purpose. In - this chapter, we extend our address book client to allow contacts to be + this chapter, you extend our address book client to allow contacts to be exported to vCard \c{.vcf} files. \section1 Placing Widgets on The Form - We add a push button into our layout by dragging and dropping it in, with + Add a push button into our layout by dragging and dropping it in, with \c exportButton as its \c objectName. The \c toolTip property is set to \gui{Export as vCard}. @@ -1006,8 +1021,8 @@ \section1 The AddressBook Class - We declare a public slot, \c exportAsVCard(), in our header file. + Declare a public slot, \c exportAsVCard(), in your header file. - Within the \c AddressBook constructor, we connect \c{exportButton}'s + Within the \c AddressBook constructor, connect \c{exportButton}'s \l{QPushButton::}{clicked()} signal to \c exportAsVCard(). */ diff --git a/doc/images/addressbook-tutorial-part1-creator-screenshot.png b/doc/images/addressbook-tutorial-part1-creator-screenshot.png index 9c93a90dfa0..2e63048dab4 100644 Binary files a/doc/images/addressbook-tutorial-part1-creator-screenshot.png and b/doc/images/addressbook-tutorial-part1-creator-screenshot.png differ diff --git a/doc/images/addressbook-tutorial-part1-designer-screenshot.png b/doc/images/addressbook-tutorial-part1-designer-screenshot.png index 1429309f198..e6a79448e8f 100644 Binary files a/doc/images/addressbook-tutorial-part1-designer-screenshot.png and b/doc/images/addressbook-tutorial-part1-designer-screenshot.png differ diff --git a/doc/images/addressbook-tutorial-part2-form-design.png b/doc/images/addressbook-tutorial-part2-form-design.png new file mode 100644 index 00000000000..36c5e9a33c3 Binary files /dev/null and b/doc/images/addressbook-tutorial-part2-form-design.png differ diff --git a/doc/images/addressbook-tutorial-part4-confirm.png b/doc/images/addressbook-tutorial-part4-confirm.png new file mode 100644 index 00000000000..f763ad77188 Binary files /dev/null and b/doc/images/addressbook-tutorial-part4-confirm.png differ diff --git a/doc/images/addressbook-tutorial-part4-remove.png b/doc/images/addressbook-tutorial-part4-remove.png new file mode 100644 index 00000000000..f5e40054b4f Binary files /dev/null and b/doc/images/addressbook-tutorial-part4-remove.png differ diff --git a/doc/images/addressbook-tutorial-part4-screenshot.png b/doc/images/addressbook-tutorial-part4-screenshot.png new file mode 100644 index 00000000000..846a505082f Binary files /dev/null and b/doc/images/addressbook-tutorial-part4-screenshot.png differ diff --git a/doc/images/addressbook-tutorial-part5-finddialog-in-designer.png b/doc/images/addressbook-tutorial-part5-finddialog-in-designer.png index 2ffa61e36df..55927d87016 100644 Binary files a/doc/images/addressbook-tutorial-part5-finddialog-in-designer.png and b/doc/images/addressbook-tutorial-part5-finddialog-in-designer.png differ diff --git a/doc/images/qmldesigner-anchor-fill-screen.png b/doc/images/qmldesigner-anchor-fill-screen.png new file mode 100644 index 00000000000..b8a9587db2f Binary files /dev/null and b/doc/images/qmldesigner-anchor-fill-screen.png differ diff --git a/doc/images/qmldesigner-helloworld-base-state.png b/doc/images/qmldesigner-helloworld-base-state.png new file mode 100644 index 00000000000..91ce7bfaa9f Binary files /dev/null and b/doc/images/qmldesigner-helloworld-base-state.png differ diff --git a/doc/images/qmldesigner-helloworld-state1.png b/doc/images/qmldesigner-helloworld-state1.png new file mode 100644 index 00000000000..a3d85f3c7ee Binary files /dev/null and b/doc/images/qmldesigner-helloworld-state1.png differ diff --git a/doc/images/qmldesigner-helloworld-widget-add.png b/doc/images/qmldesigner-helloworld-widget-add.png new file mode 100644 index 00000000000..7016a9e37c5 Binary files /dev/null and b/doc/images/qmldesigner-helloworld-widget-add.png differ diff --git a/doc/images/qmldesigner-helloworld-widget-edit.png b/doc/images/qmldesigner-helloworld-widget-edit.png new file mode 100644 index 00000000000..03a91110575 Binary files /dev/null and b/doc/images/qmldesigner-helloworld-widget-edit.png differ diff --git a/doc/images/qmldesigner-helloworld.png b/doc/images/qmldesigner-helloworld.png new file mode 100644 index 00000000000..465d2959499 Binary files /dev/null and b/doc/images/qmldesigner-helloworld.png differ diff --git a/doc/images/qmldesigner-new-project-contents.png b/doc/images/qmldesigner-new-project-contents.png new file mode 100644 index 00000000000..d2bd3cc6f1c Binary files /dev/null and b/doc/images/qmldesigner-new-project-contents.png differ diff --git a/doc/images/qmldesigner-new-project-location.png b/doc/images/qmldesigner-new-project-location.png new file mode 100644 index 00000000000..9becf0fc550 Binary files /dev/null and b/doc/images/qmldesigner-new-project-location.png differ diff --git a/doc/images/qmldesigner-new-project-summary.png b/doc/images/qmldesigner-new-project-summary.png new file mode 100644 index 00000000000..046777d0a07 Binary files /dev/null and b/doc/images/qmldesigner-new-project-summary.png differ diff --git a/doc/images/qmldesigner-new-project.png b/doc/images/qmldesigner-new-project.png new file mode 100644 index 00000000000..4f60b77cdb4 Binary files /dev/null and b/doc/images/qmldesigner-new-project.png differ diff --git a/doc/images/qmldesigner-visual-editor.png b/doc/images/qmldesigner-visual-editor.png new file mode 100644 index 00000000000..f5d54b7ba85 Binary files /dev/null and b/doc/images/qmldesigner-visual-editor.png differ diff --git a/doc/images/qtcreator-add-resource-wizard.png b/doc/images/qtcreator-add-resource-wizard.png index 47dcaddf244..551a2e5858a 100644 Binary files a/doc/images/qtcreator-add-resource-wizard.png and b/doc/images/qtcreator-add-resource-wizard.png differ diff --git a/doc/images/qtcreator-add-resource-wizard2.png b/doc/images/qtcreator-add-resource-wizard2.png index 306fdb8a0ba..a4c78756c1c 100644 Binary files a/doc/images/qtcreator-add-resource-wizard2.png and b/doc/images/qtcreator-add-resource-wizard2.png differ diff --git a/doc/images/qtcreator-add-resource-wizard3.png b/doc/images/qtcreator-add-resource-wizard3.png new file mode 100644 index 00000000000..4c84bb43b9b Binary files /dev/null and b/doc/images/qtcreator-add-resource-wizard3.png differ diff --git a/doc/images/qtcreator-add-resource.png b/doc/images/qtcreator-add-resource.png index 036ff915484..728e7eeef59 100644 Binary files a/doc/images/qtcreator-add-resource.png and b/doc/images/qtcreator-add-resource.png differ diff --git a/doc/images/qtcreator-class-info.png b/doc/images/qtcreator-class-info.png index a0052397076..9791e6c0414 100644 Binary files a/doc/images/qtcreator-class-info.png and b/doc/images/qtcreator-class-info.png differ diff --git a/doc/images/qtcreator-cmake-import-wizard1.png b/doc/images/qtcreator-cmake-import-wizard1.png index 1d473d3e541..6c93ab9c98b 100644 Binary files a/doc/images/qtcreator-cmake-import-wizard1.png and b/doc/images/qtcreator-cmake-import-wizard1.png differ diff --git a/doc/images/qtcreator-cmake-import-wizard2.png b/doc/images/qtcreator-cmake-import-wizard2.png index c9b8d3703cb..c05fd3b8596 100644 Binary files a/doc/images/qtcreator-cmake-import-wizard2.png and b/doc/images/qtcreator-cmake-import-wizard2.png differ diff --git a/doc/images/qtcreator-cmakeexecutable.png b/doc/images/qtcreator-cmakeexecutable.png new file mode 100644 index 00000000000..08391df622c Binary files /dev/null and b/doc/images/qtcreator-cmakeexecutable.png differ diff --git a/doc/images/qtcreator-formedit.png b/doc/images/qtcreator-formedit.png index 18cd8c04de4..14401a668de 100644 Binary files a/doc/images/qtcreator-formedit.png and b/doc/images/qtcreator-formedit.png differ diff --git a/doc/images/qtcreator-intro-and-location.png b/doc/images/qtcreator-intro-and-location.png index f03e4fb6a47..e5118f7a830 100644 Binary files a/doc/images/qtcreator-intro-and-location.png and b/doc/images/qtcreator-intro-and-location.png differ diff --git a/doc/images/qtcreator-new-project-qt-versions.png b/doc/images/qtcreator-new-project-qt-versions.png new file mode 100644 index 00000000000..d6007f74fd7 Binary files /dev/null and b/doc/images/qtcreator-new-project-qt-versions.png differ diff --git a/doc/images/qtcreator-new-project-summary.png b/doc/images/qtcreator-new-project-summary.png index 05e1cf2e0d5..d8ace9f3c1c 100644 Binary files a/doc/images/qtcreator-new-project-summary.png and b/doc/images/qtcreator-new-project-summary.png differ diff --git a/doc/images/qtcreator-new-project.png b/doc/images/qtcreator-new-project.png index f6c186206e9..ca465974bd2 100644 Binary files a/doc/images/qtcreator-new-project.png and b/doc/images/qtcreator-new-project.png differ diff --git a/doc/images/qtcreator-run.png b/doc/images/qtcreator-run.png index 845bd48e2ed..ff8ff15b903 100644 Binary files a/doc/images/qtcreator-run.png and b/doc/images/qtcreator-run.png differ diff --git a/doc/images/qtcreator-search-allprojects.png b/doc/images/qtcreator-search-allprojects.png index 0a6400f5350..84693d1151d 100644 Binary files a/doc/images/qtcreator-search-allprojects.png and b/doc/images/qtcreator-search-allprojects.png differ diff --git a/doc/images/qtcreator-serverbutton.png b/doc/images/qtcreator-serverbutton.png new file mode 100644 index 00000000000..55ef8fd5a3f Binary files /dev/null and b/doc/images/qtcreator-serverbutton.png differ diff --git a/doc/images/qtcreator-texfinder-ui-horizontal-layout.png b/doc/images/qtcreator-texfinder-ui-horizontal-layout.png new file mode 100644 index 00000000000..482918fa480 Binary files /dev/null and b/doc/images/qtcreator-texfinder-ui-horizontal-layout.png differ diff --git a/doc/images/qtcreator-texteditor-behavior.png b/doc/images/qtcreator-texteditor-behavior.png index 8f7ef19c2f7..90bde3788b8 100644 Binary files a/doc/images/qtcreator-texteditor-behavior.png and b/doc/images/qtcreator-texteditor-behavior.png differ diff --git a/doc/images/qtcreator-texteditor-completion.png b/doc/images/qtcreator-texteditor-completion.png index 33cbda18598..4eb9aadfdf1 100644 Binary files a/doc/images/qtcreator-texteditor-completion.png and b/doc/images/qtcreator-texteditor-completion.png differ diff --git a/doc/images/qtcreator-texteditor-display.png b/doc/images/qtcreator-texteditor-display.png index 06558071e59..cfa8c965c77 100644 Binary files a/doc/images/qtcreator-texteditor-display.png and b/doc/images/qtcreator-texteditor-display.png differ diff --git a/doc/images/qtcreator-texteditor-fonts.png b/doc/images/qtcreator-texteditor-fonts.png index 0712fa1fb51..339dd28ac08 100644 Binary files a/doc/images/qtcreator-texteditor-fonts.png and b/doc/images/qtcreator-texteditor-fonts.png differ diff --git a/doc/images/qtcreator-textfinder-contents.png b/doc/images/qtcreator-textfinder-contents.png new file mode 100644 index 00000000000..84e8d17bc6b Binary files /dev/null and b/doc/images/qtcreator-textfinder-contents.png differ diff --git a/doc/images/qtcreator-textfinder-screenshot.png b/doc/images/qtcreator-textfinder-screenshot.png index 07f2c566eee..103e96cc6c7 100644 Binary files a/doc/images/qtcreator-textfinder-screenshot.png and b/doc/images/qtcreator-textfinder-screenshot.png differ diff --git a/doc/images/qtcreator-textfinder-ui-widgets.png b/doc/images/qtcreator-textfinder-ui-widgets.png new file mode 100644 index 00000000000..8b2b334d59e Binary files /dev/null and b/doc/images/qtcreator-textfinder-ui-widgets.png differ diff --git a/doc/images/qtcreator-textfinder-ui.png b/doc/images/qtcreator-textfinder-ui.png index 2d6be91296a..a5717a1f51a 100644 Binary files a/doc/images/qtcreator-textfinder-ui.png and b/doc/images/qtcreator-textfinder-ui.png differ diff --git a/doc/qtcreator.qdoc b/doc/qtcreator.qdoc index 0bd991b348d..b72a399ea81 100644 --- a/doc/qtcreator.qdoc +++ b/doc/qtcreator.qdoc @@ -14,11 +14,19 @@ \section1 Version 1.3.82 + Qt Creator provides integrated tools for both application designers + and developers to create applications for desktop and mobile device + platforms. + + For application designers, Qt Creator provides an integrated \QMLD + tool that you can use to design and develop application UIs for mobile + devices. + + For application developers, Qt Creator provides a cross-platform, complete integrated development - environment (IDE) for developing Qt projects. It is available for Linux, - Mac OS X and Windows operating systems. You can use Qt Creator to develop - applications for desktop and Symbian platforms. For more information, see - \l{Operating systems and supported platforms}. + environment (IDE) that is available for Linux, + Mac OS X and Windows operating systems. For more information, see + \l{Operating Systems and Supported Platforms}. \note Please report bugs and suggestions to the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}. @@ -36,7 +44,11 @@ \o \l{Introducing Qt Creator} \o \l{Operating Systems and Supported Platforms} \o \l{Quick Tour} - \o \l{Writing a Simple Program} + \o \l{Getting Started} + \list + \o \l{Writing a Simple Program} + \o \l{Creating an Animated Application} + \endlist \o \l{Using the Editor} \list \o \l{Finding and Replacing} @@ -51,13 +63,15 @@ \o \l{Setting Up a Generic Project} \o \l{Managing Sessions} \endlist - \o \l{Developing Applications} + \o \l{Developing Mobile Applications} \list + \o \l{Implementing Application UI} \o \l{Developing Maemo Applications} \o \l{Developing Symbian Applications} \endlist \o \l{Debugging} \o \l{Using Version Control Systems} + \o \l{Adding Qt Designer Plugins} \o \l{Tips and Tricks} \o \l{Keyboard Shortcuts} \o \l{Known Issues} @@ -75,18 +89,32 @@ \title Introducing Qt Creator + Qt Creator provides you with tools to design and develop animated applications for + mobile devices and to develop complex applications for multiple desktop + platforms. + + \section1 Developing for Mobile Devices + + \QMLD allows you to easily develop animations by using a declarative programming + language called QML. You use a visual editor to create widgets and define changes + in their state. \QMLD generates the necessary code for you. + You can edit the code in the code editor to add transitions and interaction. You + can write JavaScript to implement the application logic. + + \section1 Developing for Desktop Platforms + As an IDE, Qt Creator differs from a text editor in that it knows how to build and run applications. It understands the code as code, not just as plain text. This allows it to: \list - \o Enable you to write well formatted code. - \o Anticipate what you are going to write and complete the code. - \o Display inline error and warning messages. - \o Enable you to semantically navigate to classes, functions, and symbols. - \o Provide you with context-sensitive help on classes, functions, and symbols. + \o Enable you to write well formatted code + \o Anticipate what you are going to write and complete the code + \o Display inline error and warning messages + \o Enable you to semantically navigate to classes, functions, and symbols + \o Provide you with context-sensitive help on classes, functions, and symbols \o Rename symbols in an intelligent way, so that other symbols with the same name - that belong to other scopes are not renamed. - \o Show you the locations in code where a function is declared or called. + that belong to other scopes are not renamed + \o Show you the locations in code where a function is declared or called \endlist \section1 Why Do You Need Projects? @@ -97,17 +125,20 @@ Creating a project allows you to: \list - \o Group files together. - \o Add custom build steps. - \o Include forms and resource files. - \o Specify settings for running applications. + \o Group files together + \o Add custom build steps + \o Include forms and resource files + \o Specify settings for running applications \endlist You can either create a project from scratch or import an existing project. Qt Creator generates all the necessary files, depending on the type of project you create. For example, if you choose to create a graphical user - interface (GUI) application, Qt Creator generates an empty .ui file for you - that you can modify with the integrated Qt Designer. + interface (GUI) application, Qt Creator generates an empty .ui file + that you can modify with the integrated \QD. + + If you choose to create a QML application, Qt Creator generates a .qml file + that you can modify with the \QMLD visual editor and the code editor. */ /*! @@ -143,42 +174,61 @@ \o libxrandr-dev \o If you are using QtOpenGL, libgl-dev and libglu-dev \endlist - \o Mac OS 10.4 or later with the following: + \o Mac OS 10.5 or later with the following: \list \o Xcode tools for your Mac OS X version available from your Mac OS X installation DVDs or at \l http://developer.apple.com. \endlist \endlist - \section1 Building Qt Creator + \omit ## Are the Xcode tools still needed separately? \endomit + + \section1 Build Environment To build Qt Creator itself from the source, you need: \list - \o Qt 4.6.0 or later + \o Qt 4.7 or later \o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008 \endlist - \section1 Supported Platforms + \section1 Supported Mobile Device Platforms + You can develop applications for the following mobile device + platforms: + + \list + + \o Symbian + + \o Maemo and Maemo Application Development and Debugging Environment (MADDE) + + \endlist + + The following table summarizes operating system support for building + applications for mobile device platforms. \table \header - \o {1,2} Operating system - \o {2,1} Platform + \o {1,3} Operating system + \o {3,1} Platform \header \o Desktop \o Symbian + \o Maemo \row \o Windows \o Yes \o Yes + \o Yes \row \o Linux \o Yes \o No + \o Yes \row \o Mac OS X \o Yes \o No + \o No \endtable */ @@ -187,44 +237,41 @@ \contentspage index.html \previouspage creator-os-supported-platforms.html \page creator-quick-tour.html - \nextpage creator-writing-program.html + \nextpage creator-getting-started.html \title Quick Tour The figure below shows some of the components of Qt Creator in - \gui{Edit mode}. + \gui{Edit} mode. \image qtcreator-breakdown.png \section1 Qt Creator Modes The mode selector allows you to quickly switch between tasks such as - editing project and source files, configuring how projects are built and + editing project and source files, designing application UIs, + configuring how projects are built and executed, and debugging your applications. To change modes, click the icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}. \list - \o Use the \gui Welcome mode to open recent sessions and projects. - \o Use the \gui Edit mode to edit project and source files. - \l{The sidebar} in the Edit mode provides different views for - browsing files. - \o Use the \gui Debug mode to inspect the state of your program while - debugging. For more information, see \l Debugging. - \o Use the \gui Projects mode to configure project builing and - execution. For more information, see \l{Managing Projects}. - \o Use the \gui Help mode to view Qt documentation. For more - information, see \l{Qt Help Integration}. - \o Use the \gui Output mode to examine, for example, build issues - and compile and application output. This information is also - available in \l{The output panes}{the output panes}. + \o \gui Welcome mode for opening recent sessions and projects. + \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files. + \o \gui{\l{Implementing Application UI}{Design}} mode for designing and developing animated applications for + mobile devices. + \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while + debugging. + \o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and + execution. + \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation. \endlist Certain actions in Qt Creator trigger a mode change. For example, - \gui Debug > \gui{Start debugging} > \gui{Start debugging} - automatically switches to \gui Debug mode. + \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging} + automatically switches to \gui {Debug} mode. - \section1 The Sidebar + \section1 Browsing Project Contents Use the sidebar to browse files, projects and bookmarks. \image qtcreator-sidebar.png @@ -244,15 +291,14 @@ \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png or press \key Alt+0 (\key Cmd+0 on Mac OS X). \o To split the sidebar, click \inlineimage qtcreator-splitbar.png - . When you split the sidebar, the new view shows the same - contents as the view you are splitting. + . Select new content to view in the split view. \o To close a sidebar view, click \inlineimage qtcreator-closesidebar.png . \endlist - \section2 Project Tree + \section2 Viewing Project Files When the sidebar shows projects, they are displayed in a project tree. The project tree contains a list of all projects open in the current session. @@ -260,16 +306,17 @@ You can use the project tree in the following ways: \list - \o Right-clicking an item in the project tree brings up a + \o Double-click a file to open it in an editor. + \o Right-click an item in the project tree to bring up a context menu containing the actions most commonly needed. For example, through the menu of the project root directory you can, - among other actions, build, re-build, clean and run the project. + build, re-build, clean and run the project. \o To list all files in a project, click \inlineimage qtcreator-filter.png - and select \gui{Simplify tree}. + and select \gui{Simplify Tree}. \o During a build, the build system automatically generates source files. To hide these files, click \inlineimage qtcreator-filter.png - and select \gui{Hide generated files}. + and select \gui{Hide Generated Files}. \o To toggle the synchronization of your project tree with the file opened in the editor, click \inlineimage qtcreator-synchronizefocus.png @@ -279,12 +326,12 @@ \endlist - \section1 The Output Panes + \section1 Viewing Output The task pane in Qt Creator can display one of the following panes: \gui{Build Issues}, \gui{Search Results}, \gui{Application Output}, and \gui{Compile Output}. Output panes are available in all - \l{Qt Creator modes}{modes}. + \l{Qt Creator Modes}{modes}. \section2 Build Issues @@ -324,40 +371,44 @@ \image qtcreator-compile-pane.png - \section1 Qt Help Integration + \section1 Getting Help - Qt Creator comes fully integrated with all of Qt's documentation and - examples using the Qt Help plugin. + Qt Creator comes fully integrated with Qt documentation and + examples using the Qt Help plugin. You can get help in the following + ways: - To view documentation, switch to \gui Help mode. + \list - To obtain context sensitive help, move the text cursor to a Qt class or + \o To view documentation, switch to \gui Help mode. + + \o To get context sensitive help, move the text cursor to a Qt class or function and press \key F1. The documentation is displayed in a pane next to the code editor, or, if there is not enough vertical space, in the fullscreen \gui Help mode. + \endlist + \image qtcreator-context-sensitive-help.png To select and configure how the documentation is displayed in the - \gui Help mode, select \gui Tools > \gui Options... > \gui Help. + \gui Help mode, select \gui Tools > \gui Options > \gui Help. \section2 Adding External Documentation - You can display external documentation in Qt Creator's \gui Help mode. + You can display external documentation in the Qt Creator \gui Help mode. To augument or replace the documentation that ships with Qt Creator and Qt: \list 1 \o Create a .qch file from your documentation. For information on how to prepare your documentation and create a .qch file, see - \l{http://doc.qt.nokia.com/4.6/qthelp-framework.html} - {The Qt help framework}. + \l{http://doc.qt.nokia.com/4.6/qthelp-framework.html}{The Qt Help Framework}. \o Add the .qch file to Qt Creator by selecting \gui Tools > - \gui Options... > \gui Help > \gui Documentation > \gui Add. + \gui Options > \gui Help > \gui Documentation > \gui Add. \endlist - \section1 Keyboard Navigation + \section1 Navigating with Keyboard Qt Creator caters not only to developers who are used to using the mouse, but also to developers who are more comfortable with the keyboard. A wide @@ -365,21 +416,27 @@ \l{Searching With the Locator}{navigation} shortcuts are available to help speed up the process of developing your application. + \section1 Developing Application UI - \section1 Qt Designer Integration + To help you design the user interface of your application, two visual + editors are integrated into Qt Creator: - To help you design the user interface of your application, a complete - version of Qt Designer is integrated right into Qt Creator. Qt Creator - automatically opens all .ui files in Qt Designer. + \list + \o \QD + \o \QMLD + \endlist - The Qt Designer integration includes project management and code - completion. + The integration includes project management and code completion. + + \section1 Using Qt Designer + + Qt Creator automatically opens all .ui files in \QD. \image qtcreator-formedit.png - To change the layout of Qt Designer user interface elements: + To change the layout of \QD user interface elements: \list 1 - \o Select \gui Tools > \gui{Form editor} > \gui Views > + \o Select \gui Tools > \gui{Form Editor} > \gui Views > \gui Locked. When this option is unchecked, you can change the layout. @@ -387,7 +444,7 @@ position. \endlist - To change Qt Designer properties, select \gui Tools > \gui Options > + To change \QD properties, select \gui Tools > \gui Options > \gui Designer. \list \o Set the class properties and code generation preferences in \gui @@ -405,14 +462,48 @@ resolution, select \gui{Embedded Design}. \endlist - For more information on Qt Designer, see + For more information on \QD, see \l{http://doc.trolltech.com/designer-manual.html}{Qt Designer Manual}. + + \section1 Using QML Designer + + You can edit .qml files in either the visual \QMLD editor or in the + code editor. + + In \gui Projects, double-click a .gml file to open it in the code + editor. Then select the \gui {Design} mode to edit the file in the + visual editor. + + \image qmldesigner-visual-editor.png "Visual editor" + + Use the visual editor panes to manage your project: + + \list + + \o \gui {Navigator} pane displays the items in the scene. You can + show and hide items to focus on specific parts of the application. + + \o \gui {Library} pane displays lists of predefined \gui {Items} and + imported \gui {Resources} that you can use to design applications. The + images and other files that you copy to the project folder appear in the + \gui {Resources} pane. + + \o \gui {Properties} pane displays the properties of the selected item. + You can also change the properties in the code editor. + + \o \gui {State} pane displays the different states of the item. To add + states, click the empty slot. Then modify the new state in the editor. + In the code editor, you can see the changes recorded as changes to + the base state. + + \endlist + */ /*! \contentspage index.html - \previouspage creator-writing-program.html + \previouspage creator-qml-application.html \page creator-editor-using.html \nextpage creator-editor-finding.html @@ -435,11 +526,11 @@ \o Set tabs, indentation and the handling of whitespace in \gui Behavior. \o Set various display properties, such as - \l{Highlighting and folding blocks}{highlighting and folding blocks}, - text wrapping or \l{Moving to symbol definition or declaration} + \l{Highlighting and Folding Blocks}{highlighting and folding blocks}, + text wrapping or \l{Moving to Symbol Definition or Declaration} {moving to symbol definition or declaration} in \gui Display. - \o Configure \l{Code completion}{code completion} in \gui Completion. + \o Configure \l{Code Completion}{code completion} in \gui Completion. \endlist @@ -464,12 +555,12 @@ \endlist When you create or edit forms in an .ui file, the toolbar contains - Qt Designer specific tools. + \QD specific tools. If you are using a version control system, the toolbar enables you to compare the current file with the version in the repository. For more information on using Qt Creator with version control systems, see - \l{Using version control systems}. + \l{Using Version Control Systems}. \section1 Splitting the Editor View @@ -494,7 +585,7 @@ \endlist To move between split views, select \gui Window > - \gui{Go to Other Split} or press \key{Ctrl+E, 0}. + \gui{Go to Next Split} or press \key{Ctrl+E, 0}. To remove a split view, place the cursor within the view you want to remove and select \gui Window > \gui{Remove Current Split} or press @@ -693,12 +784,15 @@ \o To search using regular expressions, select \inlineimage qtcreator-editor-regularexpressions.png . - Regular expressions used in Qt Creator are modeled on Perl's regular + Regular expressions used in Qt Creator are modeled on Perl regular expressions. For more information on using regular expressions, see - \l http://doc.qt.nokia.com/4.6/qregexp.html#details - {Detailed description of QRegExp class reference}. + \l {http://doc.qt.nokia.com/4.6/qregexp.html#details} + {Detailed Description} in the QRegExp Class Reference. \endlist + \note If you have selected text before selecting \gui Find/Replace, the + search is conducted within the selection. + To replace occurrences of the existing text, enter the new text in the \gui{Replace with} text box. \list @@ -717,7 +811,8 @@ file: \list 1 \o Press \key Ctrl+Shift+F or select \gui Edit > - \gui Find/Replace > \gui Find.... + \gui Find/Replace > \gui{Advanced Find} > + \gui{Open Advanced Find...}. \o Select the scope of your search: \list \o \gui{All Projects} searches files matching the defined file @@ -826,8 +921,11 @@ all files listed in the \gui{Search Results} pane. You cannot undo this action. \endlist -*/ + \note Renaming local symbols does not open the \gui{Search Results} pane. + The instances of the symbol are highlighted in code and you can edit the + symbol. All instances of the local symbol are changed as you type. +*/ /*! \contentspage index.html @@ -884,26 +982,20 @@ To create a new project: \list 1 - \o Select \gui File > \gui{New Project} and select the type of your + \o Select \gui File > \gui{New File or Project} and select the type of your project. - This example uses \bold{Qt4 Gui Application}. + The contents of the following dialogs depend on the project type. + This example uses \gui {Qt Gui Application}. \image qtcreator-new-project.png \o Name the project and set its path. To select the path from a - directory tree, click \gui Choose.... + directory tree, click \gui Browse. Avoid using spaces and special characters in the project name and path. \image qtcreator-intro-and-location.png - \o Select the Qt modules you want to include in your project. - - Since this example shows creation of a Qt4 Gui Application project - type, QtCore and QtGui modules are selected by default. However, you - can select any other you need. - - \image qtcreator-select-modules.png \o Specify the name of the class you want to create and using the drop-down menu select its base class type. @@ -914,10 +1006,11 @@ \image qtcreator-class-info.png \o Review the project settings. - To create the project, click \gui Done. + To create the project, click \gui Finish. \image qtcreator-new-project-summary.png \endlist + */ @@ -1181,168 +1274,448 @@ /*! \contentspage index.html \previouspage creator-quick-tour.html - \page creator-writing-program.html + \page creator-getting-started.html + \nextpage creator-writing-program.html + + \title Getting Started + + This section contains examples that illustrate how to use Qt Creator and the + integrated design tools, \QD and \QMLD, to create simple applications: + + \list + \o \l{Writing a Simple Program} + \o \l{Creating an Animated Application} + \endlist + +*/ + + +/*! + \contentspage index.html + \previouspage creator-writing-program.html + \page creator-qml-application.html \nextpage creator-editor-using.html + \title Creating an Animated Application + + \note This tutorial assumes that you are familiar with the QML declarative + language. + + This tutorial describes how to use Qt Creator to create a small animated + Qt application, Hello World. + + \image qmldesigner-helloworld.png "Hello World" + + \section1 Creating the Hello World Project + + \note Create the project with the \gui{Help} mode active so that you can follow + these instructions while you work. + + \list 1 + + \o Select \gui{File > New File or Project > QML Project > QML Application > OK}. + + \image qmldesigner-new-project.png "New File or Project dialog" + + The \gui{Introduction and Project Location} dialog opens. + + \image qmldesigner-new-project-location.png "Introduction and Project Location dialog" + + \o In the \gui{Name} field, type \bold {Hello World}. + + \o In the \gui {Create in} field, enter the path for the project files. For example, + \c {C:\Qt\examples}, and then click \gui{Next}. + + The \gui{Project Management} dialog opens. + + \image qmldesigner-new-project-summary.png "Project Management dialog" + + \o Review the project settings, and click \gui{Finish} to create the project. + + \endlist + + The HelloWorld project now contains the following files: + + \list + \o HelloWorld.qmlproject + \o HelloWorld.qml + \endlist + + \image qmldesigner-new-project-contents.png "HelloWorld project contents" + + The .qmlproject file defines that all QML, JavaScript, and image files in + the project folder belong to the project. The .qml file contains some example + code that specifies the screen size (200x200) and a label that contains + the text \bold {Hello World}. + + \section1 Designing the User Interface + + \list + + \o In the \gui{Editor} mode, double-click the HelloWorld.qml file in + the \gui{Projects} pane to open it in the code editor. + + \o To set the screen size to that of some Symbian devices in portrait + mode, for example, change the \c height to \bold 240 and \c width to \bold 320. + + \o Click \gui{Design} to design the UI in the visual \QMLD editor. + + \o Drag and drop a \gui {Rectangle} from the \gui {Library} pane to the + scene. + + \image qmldesigner-helloworld-widget-add.png "Add widget to Hello World" + + \o Edit the \gui {Properties} of the item to turn it into a red ball: + + \list + + \o In the \gui {Advanced} tab, click the color picker to select a red + color. + + \o In the \gui {Radius} field, use the slider to set the radius value + to \bold 50. + + \image qmldesigner-helloworld-widget-edit.png "Edit the widget" + + \endlist + + \o To create a blue ball, press \key {Ctrl+C} and \key {Ctrl+V} to copy + and paste the red one, and then change its color to blue. + + \image qmldesigner-helloworld-base-state.png "Hello World first view" + + The first view of your application is now ready. + + \note You can use graphical design tools to create nice images and + copy them to the projects folder to display them in the \gui {Library} + pane in \gui {Resources}. + + \o In the \gui State pane, click the plus sign to add another view, or \e state + to the application. + + \o Modify the state by dragging and dropping the widgets to switch their + places. + + \image qmldesigner-helloworld-state1.png "Hello World second view" + + \endlist + + \section1 Animating the Scene + + Animate the scene so that the widgets appear to switch places + on the screen. + + \list 1 + + \o Click \gui {Edit} to open HelloWorld.qml in the code editor. + + \o Add the following code to create a transition: + + \code + transitions: [ + Transition { + NumberAnimation { properties: "x, y"; duration: 500 } + } + \endcode + + \note The code editor completes the code for you as you type. + + \o Click the \inlineimage qtcreator-run.png + button to check that the application can be built and run. + + \endlist + + \section1 Adding Interaction + + Add interaction to the scene to allow users to click on the screen to start + the animation. + + \list 1 + + \o Click \gui{Design} to open HelloWorld.qml in the visual editor. + + \o Drag and drop a \gui {Mouse Area} from the \gui {Library} to the scene. + + \o In the \gui {Properties} pane, \gui {Anchor} tab, click the + \inlineimage qmldesigner-anchor-fill-screen.png + button to make the mouse region cover the whole screen. + + \o In the code editor, use data binding to add a \c when statement to + the states sections, as illustrated by the following code: + + \code + + states: [ + State { + name: "State1" + when: mousearea1.pressed + \endcode + + \endlist + + \section1 Buiding and Running the Application + + \list 1 + + \o Press \key {Ctrl+R} to build and run the application. + + \o Click the screen and keep the mouse button pressed down to run the + animation. + + \endlist + +*/ + + +/*! + \contentspage index.html + \previouspage creator-getting-started.html + \page creator-writing-program.html + \nextpage creator-qml-application.html + \title Writing a Simple Program \note This tutorial assumes that you have experience in writing basic Qt - applications, using Qt Designer to design user interfaces and using the Qt + applications, using \QD to design user interfaces and using the Qt Resource System. - In this example, we describe the steps involved in using Qt Creator - to create a small Qt program, Text Finder. Inspired by the QtUiTools' - \l{http://doc.trolltech.com/uitools-textfinder.html}{Text Finder} - example, we write a similar but simplified version of it, as shown - below. + This tutorial describes how to use Qt Creator + to create a small Qt application, Text Finder. It is a simplified version of the + QtUiTools \l{http://doc.trolltech.com/uitools-textfinder.html}{Text Finder} + example. \image qtcreator-textfinder-screenshot.png \section1 Setting Up Your Environment - Once you have installed Qt Creator, it detects automatically if Qt's - location is in your \c PATH variable. If not, please follow the - instructions in \l{Selecting the Qt version}. + Qt Creator automatically detects whether the location of Qt is in your \c PATH variable. + If you have installed several Qt versions, follow the + instructions in \l{Selecting the Qt version} to set the Qt path. - \section1 Setting Up the Project + \section1 Creating the Text Finder Project - We begin with a Qt4 Gui Application project generated by Qt Creator. The - \l{Creating a project} document describes this process in - detail. Remember to select QWidget as the Text Finder's base class. If - your project is not yet loaded, load it by selecting \gui{File} > \gui{Open}. + \note Create the project with the \gui{Help} mode active so that you can follow + these instructions while you work. + + \list 1 + + \o Select \gui{File > New File or Project > Qt Application Project > Qt Gui + Application > OK}. + + \image qtcreator-new-project.png "New File or Project dialog" + + The \gui{Introduction and Project Location} dialog opens. + + \image qtcreator-intro-and-location.png "Introduction and Project Location dialog" + + \o In the \gui{Name} field, type \bold {TextFinder}. + + + \o In the \gui {Create in} field, enter the path for the project files. For example, + \c {C:\Qt\examples}, and then click \gui{Next}. + + The \gui{Select Required Qt Versions} dialog opens. + + \image qtcreator-new-project-qt-versions.png "Select Required Qt Versions dialog" + + \o Click \gui{Next} to use the Qt version set in the path in your project. + + The \gui{Class Information} dialog opens. + + \image qtcreator-class-info.png "Class Information dialog" + + \o In the \gui{Class Name} field, type \bold {TextFinder} as the class name. + + \o In the \gui{Base Class} list, select \bold {QWidget} as the base class type. + + \note The \gui{Header File}, \gui{Source File} and + \gui{Form File} fields are automatically updated to match the name of the + class. + + \o Click \gui{Next}. + + The \gui{Project Management} dialog opens. + + \image qtcreator-new-project-summary.png "Project Management dialog" + + \o Review the project settings, and click \gui{Finish} to create the project. - In your project, you have the following files: - \list - \o \c{textfinder.h} - \o \c{textfinder.cpp} - \o \c{main.cpp} - \o \c{textfinder.ui} - \o \c{textfinder.pro} \endlist - The \c{.h} and \c{.cpp} files come with the necessary boiler plate code. - The \c{.pro} file is also complete. + + + The TextFinder project now contains the following files: + + \list + \o textfinder.h + \o textfinder.cpp + \o main.cpp + \o textfinder.ui + \o textfinder.pro + \endlist + + \image qtcreator-textfinder-contents.png "TextFinder project contents" + + The .h and .cpp files come with the necessary boiler plate code. + The .pro file is complete. \section1 Filling in the Missing Pieces - We begin by designing the user interface and then move on to filling - in the missing code. Finally, we add the find functionality. + Begin by designing the user interface and then move on to filling + in the missing code. Finally, add the find functionality. - \section2 The User Interface + \section2 Designing the User Interface - To begin designing the user interface, double-click on the - \c{textfinder.ui} file in the \gui{Project Explorer}. This launches the - integrated Qt Designer. + \image qtcreator-textfinder-ui.png "Text Finder UI" + + \list 1 + + \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects} + view to launch the integrated \QD. + + \o Drag and drop the following widgets to the form: - Design the form below with: \list - \o \l{http://doc.trolltech.com/qlabel.html}{QLabel} - \o \l{http://doc.trolltech.com/qlinedit.html}{QLineEdit} (named lineEdit) - \o \l{http://doc.trolltech.com/qpushbutton.html}{QPushButton} (named findButton) - \o \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit} (named textEdit) + \o \gui{Label} (\l{http://doc.trolltech.com/qlabel.html}{QLabel}) + \o \gui{Line Edit} (\l{http://doc.trolltech.com/qlineedit.html}{QLineEdit}) + \o \gui{Push Button} (\l{http://doc.trolltech.com/qpushbutton.html}{QPushButton}) + \endlist - \image qtcreator-textfinder-ui.png + \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI" - We recommend that you use a \l{http://doc.trolltech.com/qgridlayout.html}{QGridLayout} - to lay out the label, the line edit and the push button. - The grid layout and the text edit can then be added to a - \l{http://doc.trolltech.com/qvboxlayout.html}{QVBoxLayout}. - If you are new to designing forms with \QD, see the + \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}. + + \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}. + + \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally} + (or press \gui{Ctrl+H}) to apply a horizontal layout + (\l{http://doc.trolltech.com/qhboxlayout.html}{QHBoxLayout}). + + \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout" + + \o Drag and drop a \gui{Text Edit} widget (\l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}) + to the form. + + \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctr+V}) + to apply a vertical layout (\l{http://doc.trolltech.com/qvboxlayout.html}{QVBoxLayout}). + + \image qtcreator-textfinder-ui.png "Text Finder UI" + + \o Press \gui{Ctrl+S} to save your changes. + + \endlist + + Applying the horizontal and vertical layouts ensures that the application UI scales to different + screen sizes. + + For more information about designing forms with \QD, see the \l{http://doc.trolltech.com/designer-manual.html}{Qt Designer Manual}. - \section2 The Header File + \section2 Completing the Header File - The \c{textfinder.h} file already has the necessary #includes, a - constructor, a destructor, and the \c{Ui} object. We need to add a private - slot, \c{on_findButton_clicked()}, to carry out our find operation. We + The textfinder.h file already has the necessary #includes, a + constructor, a destructor, and the \c{Ui} object. You need to add a private + slot, \c{on_findButton_clicked()}, to carry out the find operation. You also need a private function, \c{loadTextFile()}, to read and display the - contents of our input text file in the - \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. This is done with - the following code: + contents of the input text file in the + \l{http://doc.trolltech.com/qtextedit.html}{QTextEdit}. + + \list 1 + + \o In the \gui{Projects} view, double-click the \c{textfinder.h} file + to open it for editing. + + \o Add a private slot in a \c{private slots} section and a private function + in the \c{private} section, after the \c{Ui::TextFinder} function, as + illustrated by the following code snippet: \snippet examples/textfinder/textfinder.h 0 - \note The \c{Ui::TextFinder} object is already provided. + \endlist - \section2 The Source File + \section2 Completing the Source File - Now that our header file is complete we move on to our source file, - \c{textfinder.cpp}. We begin by filling in the functionality to load a - text file. This is described in the code snippet below: + Now that the header file is complete, move on to the source file, + textfinder.cpp. - \snippet examples/textfinder/textfinder.cpp 0 + \list 1 - Basically, we load a text file using + \o In the \gui{Projects} view, double-click the textfinder.cpp file + to open it for editing. + + \o Add code to load a text file using \l{http://doc.trolltech.com/qfile.html}{QFile}, read it with \l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and then display it on \c{textEdit} with \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()} - which requires adding the following additional #includes to textfinder.cpp: + This is illustrated by the following code snippet: + + \snippet examples/textfinder/textfinder.cpp 0 + + \o To use \l{http://doc.trolltech.com/qfile.html}{QFile} and + \l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, add the + following #includes to textfinder.cpp: \snippet examples/textfinder/textfinder.cpp 1 - For the \c{on_findButton_clicked()} slot, we extract the search string and + \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and use the \l{http://doc.trolltech.com/qtextedit.html#find}{find()} function - to look for the search string within the text file. This is described in - the code snippet below: + to look for the search string within the text file. This is illustrated by + the following code snippet: \snippet examples/textfinder/textfinder.cpp 2 - Once we have both of these functions complete, we call \c{loadTextFile()} in - our constructor. + \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in + the constructor, as illustrated by the following code snippet: \snippet examples/textfinder/textfinder.cpp 3 + \endlist + The \c{on_findButton_clicked()} slot is called automatically in - the uic generated \c{ui_textfinder.h} file by this line of code: + the uic generated ui_textfinder.h file by this line of code: \code QMetaObject::connectSlotsByName(TextFinder); \endcode - \section2 The Resource File + \section2 Creating a Resource File - We require a resource file (\c{.qrc}) within which we embed the input - text file. This can be any \c{.txt} file with a paragraph of text. + You need a resource file (.qrc) within which you embed the input + text file. The input file can be any .txt file with a paragraph of text. + Create a text file called input.txt and store it in the textfinder + folder. To add a resource file: \list 1 - \o Right-click on \gui{Resource Files} in the \gui{Project Explorer}. - \o Select \gui{Add New File...}. + \o Select \gui{File > New File or Project > Qt > Qt Resource File > OK}. + \image qtcreator-add-resource-wizard.png "New File or Project dialog" + + The \gui {Choose the Location} dialog opens. + + \image qtcreator-add-resource-wizard2.png "Choose the Location dialog" + + \o In the \gui{Name} field, enter \bold{textfinder}. + \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder}, + and click \gui{Next}. + + The \gui{Project Management} dialog opens. + + \image qtcreator-add-resource-wizard3.png "Project Management dialog" + + + \o In the \gui{Add to project} field, select \bold{TextFinder.pro} + and click \gui{Finish} to open the file in the code editor. + + \o Select \gui{Add > Add Prefix}. + \o In the \gui{Prefix} field, replace the default prefix with a slash (/). + \o Select \gui{Add > Add Files}, to locate and add input.txt. + + \image qtcreator-add-resource.png "Editing resource files" + \endlist - The wizard dialog below is displayed. - - \image qtcreator-add-resource-wizard.png - - \list 3 - \o Enter "textfinder" in the \gui{Name} field. Use the given \gui{Path}. - \o Click on \gui{Continue}. - \endlist - This page is displayed: - - \image qtcreator-add-resource-wizard2.png - - \list 5 - \o Choose to which project you want to add the new file. Select "TextFinder" - as the \gui{Project}. - \o Make sure that \gui{Add to Project} is checked. - \o Click on \gui{Done}. - \endlist - - Your resource file is now displayed in the resource editor. - - \list 8 - \o Select \gui{Add} > \gui{Add Prefix} from the drop-down list. The prefix we - require is a slash (\c{/}). - \o Select \gui{Add} > \gui{Add File} from the drop-down list. - \o Locate the text file you are going to use. We use \c{input.txt}. - \endlist - - Once the resource file has been successfully added, the following is displayed: - - \image qtcreator-add-resource.png \section1 Compiling and Running Your Program @@ -1356,7 +1729,7 @@ \contentspage index.html \previouspage creator-debugging.html \page creator-version-control.html - \nextpage creator-tips.html + \nextpage adding-plugins.html \title Using Version Control Systems @@ -1563,7 +1936,7 @@ To edit the currently open project's main.cpp file using the locator: \list 1 \o Activate the locator by pressing \key Ctrl+K. - \o Enter \tt \bold{main.cpp}. + \o Enter \c{main.cpp}. \image qtcreator-locator-open.png \o Press \key Return. @@ -1745,8 +2118,8 @@ \gui File > \gui Session. If you do not create or select a session, Qt Creator always uses the default session. - To create a new session or remove exisitng sessions, select \gui File > - \gui Sessions > \gui{Session Manager...}. + To create a new session or remove existing sessions, select \gui File > + \gui Sessions > \gui{Session Manager}. \image qtcreator-session-manager.png */ @@ -2051,6 +2424,97 @@ \note The set of watched items is saved in your session. + \section1 Walkthrough for the Debugger Frontend + + In our \l{Writing a Simple Program}{TextFinder} example, we + read a text file into QString and then display it with QTextEdit. + Suppose you want to look at this QString, \c{line}, and see what + data it actually stores. Follow the steps described below to place a + breakpoint and view the QString object's data. + + \table + \row + \i \inlineimage qtcreator-setting-breakpoint1.png + \i \bold{Setting a Breakpoint} + + \list 1 + \o Click in between the line number and the window border on the line + where we invoke \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()} + to set a breakpoint. + \o Select \gui{Start Debugging} from the \gui{Debug} menu or press \key{F5}. + \endlist + + \row + \i \inlineimage qtcreator-setting-breakpoint2.png + \i \bold{Viewing and removing breakpoints} + + Breakpoints are visible in the \gui{Breakpoints} view in + \gui{Debug} mode. To remove a breakpoint, right-click on + it and select \gui{Delete breakpoint} from the context menu. + + \row + \i \inlineimage qtcreator-watcher.png + \i \bold{Viewing Locals and Watchers} + + To view the contents of \c{line}, go to the \gui{Locals and + Watchers} view. + + \endtable + + Suppose we modify our \c{on_findButton_clicked()} function to move back to + the start of the document and continue searching once the cursor hits the + end of the document. Adding this functionality can be done with the code + snippet below: + + \code + void TextFinder::on_findButton_clicked() + { + QString searchString = ui->lineEdit->text(); + + QTextDocument *document = ui->textEdit->document(); + QTextCursor cursor = ui->textEdit->textCursor(); + cursor = document->find(searchString, cursor, + QTextDocument::FindWholeWords); + ui->textEdit->setTextCursor(cursor); + + bool found = cursor.isNull(); + + if (!found && previouslyFound) { + int ret = QMessageBox::question(this, tr("End of Document"), + tr("I have reached the end of the document. Would you like " + "me to start searching from the beginning of the document?"), + QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes); + + if (ret == QMessageBox::Yes) { + cursor = document->find(searchString, + QTextDocument::FindWholeWords); + ui->textEdit->setTextCursor(cursor); + } else + return; + } + previouslyFound = found; + } + \endcode + + However, if you compile and run this code, the application does not work + correctly due to a logic error. To locate this logic error, step + through the code using the following buttons: + + \image qtcreator-debugging-buttons.png + + \section1 Setting the Symbol Server + + To obtain operating system libraries for debugging Windows applications, + you have to add the Symbol Server: + \list 1 + \o Select \gui Tools > \gui Options > \gui Debugger > \gui Cdb + \o Click \inlineimage qtcreator-serverbutton.png + located next to the \gui{Insert...} button of the Symbol paths + field and select \gui{Symbol Server...} + \o Select a directory where you want to store the cached information + and click \gui OK. + \endlist + \section1 Debugging Helper Library with C++ While debugging, Qt Creator dynamically loads a helper library into your @@ -2313,84 +2777,6 @@ \endlist - \section1 Walkthrough for the Debugger Frontend - - In our \l{Writing a simple program}{TextFinder} example, we - read a text file into QString and then display it with QTextEdit. - Suppose you want to look at this QString, \c{line}, and see what - data it actually stores. Follow the steps described below to place a - breakpoint and view the QString object's data. - - \table - \row - \i \inlineimage qtcreator-setting-breakpoint1.png - \i \bold{Setting a Breakpoint} - - \list 1 - \o Click in between the line number and the window border on the line - where we invoke \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()} - to set a breakpoint. - \o Select \gui{Start Debugging} from the \gui{Debug} menu or press \key{F5}. - \endlist - - \row - \i \inlineimage qtcreator-setting-breakpoint2.png - \i \bold{Viewing and removing breakpoints} - - Breakpoints are visible in the \gui{Breakpoints} view in - \gui{Debug} mode. To remove a breakpoint, right-click on - it and select \gui{Delete breakpoint} from the context menu. - - \row - \i \inlineimage qtcreator-watcher.png - \i \bold{Viewing Locals and Watchers} - - To view the contents of \c{line}, go to the \gui{Locals and - Watchers} view. - - \endtable - - Suppose we modify our \c{on_findButton_clicked()} function to move back to - the start of the document and continue searching once the cursor hits the - end of the document. Adding this functionality can be done with the code - snippet below: - - \code - void TextFinder::on_findButton_clicked() - { - QString searchString = ui->lineEdit->text(); - - QTextDocument *document = ui->textEdit->document(); - QTextCursor cursor = ui->textEdit->textCursor(); - cursor = document->find(searchString, cursor, - QTextDocument::FindWholeWords); - ui->textEdit->setTextCursor(cursor); - - bool found = cursor.isNull(); - - if (!found && previouslyFound) { - int ret = QMessageBox::question(this, tr("End of Document"), - tr("I have reached the end of the document. Would you like " - "me to start searching from the beginning of the document?"), - QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes); - - if (ret == QMessageBox::Yes) { - cursor = document->find(searchString, - QTextDocument::FindWholeWords); - ui->textEdit->setTextCursor(cursor); - } else - return; - } - previouslyFound = found; - } - \endcode - - However, if you compile and run this code, the application does not work - correctly due to a logic error. To locate this logic error, step - through the code using the following buttons: - - \image qtcreator-debugging-buttons.png - */ @@ -2406,13 +2792,39 @@ Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version is at least 2.8. + You can set the path for the \c CMake executable in \gui{Tools} > + \gui{Options...} > \gui{CMake} > \gui{CMake}. + + \image qtcreator-cmakeexecutable.png + + \note Before you open a \c CMake project it is necessary to modify the + PATH environment variable to include the bin folders of \c mingw and + Qt Creator in the SDK. + + For instance, if you have the Qt Creator SDK installed in your C drive, + use the following command to set the environment variables in + the command line prompt: + \code + set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin; + \endcode + Then start Qt Creator by typing: + \code + C:\qtsdk\bin\qtcreator.exe + \endcode + \section1 Opening CMake Projects - To open a \c CMake project, select \gui Open from the \gui File menu and - select the \c{CMakeLists.txt} file from your \c CMake project. A wizard - guides you with the rest of the process. If the \c CMake project does - not have an in-place build, Qt Creator lets you specify the directory in - which the project is built (\l{glossary-shadow-build}{shadow build}). + To open a \c CMake project: + \list 1 + \o Select \gui Open from the \gui File menu. + \o Select the \c{CMakeLists.txt} file from your \c CMake project. + \endlist + + A wizard guides you with the rest of the process. + + \note If the \c CMake project does not have an in-place build, Qt Creator + lets you specify the directory in which the project is built + (\l{glossary-shadow-build}{shadow build}). \image qtcreator-cmake-import-wizard1.png @@ -2431,13 +2843,13 @@ \c nmake depending on your platform. The build errors and warnings are parsed and displayed in the \gui{Build Issues} output pane. - By default, Qt Creator builds the \e{all} target. You can specify which + By default, Qt Creator builds the \bold{all} target. You can specify which targets to build in \gui{Project} mode, under \gui{Build Settings}. \image qtcreator-cmake-build-settings.png - Qt Creator supports multiple build configurations. Also, the build - directory can be modified after the initial import. + Qt Creator supports multiple build configurations. The build + directory can also be modified after the initial import. \section1 Running CMake Projects Qt Creator automatically adds \gui{Run Configurations} for all targets @@ -2453,11 +2865,12 @@ syntax highlighting as if they were part of the current project or the Qt library. - External libraries are detected using the \c FIND_PACKAGE() macro. Some - libraries come with the CMake installation. You can find those in the - \b Modules directory of your CMake installation. If you provide your own - libraries, you also need to provide your own \c FindFoo.cmake file. - For more information, see + Qt Creator detects the external libraries using the \c FIND_PACKAGE() + macro. Some libraries come with the CMake installation. You can find those + in the \bold{Modules} directory of your CMake installation. + + \note If you provide your own libraries, you also need to provide your own + \c FindFoo.cmake file. For more information, see \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}. Syntax completion and highlighting work once your project successfully @@ -2491,7 +2904,7 @@ To import an existing generic project: \list 1 \o Select \gui File > \gui{New File or Project...} > \gui Projects > - \gui{Import of Makefile-based Project}. + \gui{Import Existing Project}. \o In \gui{Generic Project}, enter the project name and select the project file you want to import. @@ -2577,7 +2990,7 @@ syntax highlighting as if they were part of the current project or the Qt library. - If you import a project using the \gui{Import of Makefile-based Project} + If you import a project using the \gui{Import Existing Project} function, Qt Creator creates a file called .includes in your project directory. This file contains all project subdirectories for which Qt Creator found relevant headers. Add your include paths here. @@ -2594,15 +3007,89 @@ \contentspage index.html \previouspage creator-project-managing-sessions.html \page creator-developing-applications.html - \nextpage creator-developing-maemo.html + \nextpage creator-visual-editor.html + + \title Developing Mobile Applications + + Use \QMLD to design and implement application UI. + + Set up the development environment for your chosen mobile device + platform, Maemo or Symbian. Then specify build and run settings + for the environment in Qt Creator to build and run applications + from Qt Creator. - \title Developing Applications */ /*! \contentspage index.html \previouspage creator-developing-applications.html + \page creator-visual-editor.html + \nextpage creator-developing-maemo.html + + \title Implementing Application UI + + You can either create QML projects from scratch or import them to + Qt Creator. + + \section1 Creating QML Projects + + Select \gui {File > New File or Project > QML Project > QML Application}. + + \QMLD creates the following files: + + \list + + \o .qmlproject project file defines that all QML, JavaScript, and image + files in the project folder belong to the project. Therefore, you do not + need to individually list all the files in the project. + + \o .qml file defines an item, such as a widget, screen, or the whole + application UI. + + \endlist + + To use JavaScript and image files in the application, copy them to the + project folder. + + To import a QML project to Qt Creator, select + \gui {File > New File or Project > QML Project > Import Existing QML Directory}. + + \section1 Designing Application UI + + One .qml file can define a widget, screen, or the whole application. + + \section2 Creating Widgets + + You can use the \gui Library items to create your own widgets. Drag and drop + them to the editor and modify their properties in the \gui Properties pane. + You can use QML to add properties for a widget. The properties are automatically + displayed in the \gui Properties pane. + + Save the widgets as .qml files. You can import them to screens and applications. + + \section2 Creating Screens + + You can use the \gui Library items to create screens. Use states and transitions + to navigate between screens. + + To add interaction methods, drag and drop a \gui {Focus Scope} or \gui {Mouse Area} + to the screen. In the code editor, add functions to execute when users select + the scope or area. + + + \section1 Implementing Application Logic + + You can write JavaScript to implement the application logic. To include the script + files in the project, copy them to the project folder. + + */ + + +/*! + + \contentspage index.html + \previouspage creator-visual-editor.html \page creator-developing-maemo.html \nextpage creator-developing-symbian.html @@ -2610,12 +3097,12 @@ Maemo is a software platform developed by Nokia for smartphones and Internet Tablets. The platform is based on the Linux operating system - which itself is dervied from the Unix operating system. The platform + which itself is derived from the Unix operating system. The platform comprises of the Maemo operating system and Maemo SDK. The Maemo SDK provides an open development environment for different applications on top of the maemo platform. Maemo 5 is based on the Linux 2.6 operating - system. For more information refer, \l http://maemo.org/intro/platform/ - {Maemo platform}. + system. For more information refer, + \l{http://maemo.org/intro/platform/}{Maemo platform}. @@ -2632,7 +3119,7 @@ \o In order to setup the device IP address, you need to install PC Connectivity or implement using CLI. For information on PC Connectivity refer to the link, - \l http://pc-connectivity.garage.maemo.org/2nd_edition/node3.html#SECTION00032300000000000000 + \l{http://pc-connectivity.garage.maemo.org/2nd_edition/node3.html#SECTION00032300000000000000} {PC Connectivity}. \endlist @@ -2764,7 +3251,7 @@ Select \gui Tools > \gui Options > \gui Qt4 > \gui{Qt Versions}. Click \inlineimage qtcreator-windows-add.png, - to add a new Qt version. The \gui{QMake Location} is the qmake executable + to add a new Qt version. The \gui{qMake Location} is the qmake executable in \c{/targets//bin}. \image qtcreator-screenshot-toolchain.png @@ -3001,10 +3488,64 @@ */ - /*! \contentspage index.html \previouspage creator-version-control.html + \page adding-plugins.html + \nextpage creator-tips.html + + \title Adding Qt Designer Plugins + + You can use Qt APIs to create plugins that extend Qt applications. + This allows you to add your own widgets to \QD. + The most flexible way to include a plugin with an application is to compile it + into a dynamic library that is shipped separately, and detected and loaded at runtime. + + The applications can detect plugins that are stored in the standard plugin + subdirectories. For more information on how to create and locate plugins and to + change the default plugin path, see \l{How to Create Qt Plugins}. + + For more information about how to create plugins for \QD, see + \l{http://doc.trolltech.com/4.6/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}. + + \section1 Locating Qt Designer Plugins + + \QD fetches plugins from the standard locations and loads the plugins + that match its build key. \QD is delivered both as a standalone application + and as part of an SDK, where it is integrated into Qt Creator. + The correct folder to place the plugins depends on + which one you use. + + The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows + and Linux and \c {QtCreator.app/Contents/MacOS/designer} folder on Mac. To check which plugins + were loaded successfully and which failed, choose \gui{Tools > Form Editor > + About Qt Designer Plugins}. + + The standalone \QD is part of the Qt library used for building projects, + located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder: + \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which + failed, choose \gui{Help > About Plugins}. + + \section1 Matching Build Keys + + The Qt Creator that is included in pre-built SDK packages on Windows is built with the + Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications + is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of + Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be + used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check + the Qt version Qt Creator was built with. + + To use \QD plugins that were built for the shipped Qt version, make sure that + Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or + recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to + use for your applications. + +*/ + + +/*! + \contentspage index.html + \previouspage adding-plugins.html \page creator-tips.html \nextpage creator-keyboard-shortcuts.html @@ -3023,7 +3564,9 @@ \o \gui Help mode \key Ctrl+5 \endlist - For more information about Qt Creator modes, see \l{Qt Creator modes}. + + For more information about Qt Creator modes, see \l {Qt Creator Modes}. + \section1 Moving Between Open Files @@ -3043,10 +3586,15 @@ \o The second press closes secondary windows \endlist + \section1 Using the Filter in Options Dialog + + To find specific settings you require in \gui{Tools} > \gui{Options} + use the filter located at the top left of the Options dialog box. + \section1 Using Keyboard Shortcuts - Qt Creator provides \l{Keyboard shortcuts}{many useful keyboard shortcuts}. + Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}. To customize, import or export keyboard shortcuts, select \gui Tools > \gui Options... > \gui Environment > \gui Keyboard. @@ -3074,7 +3622,8 @@ \inlineimage qtcreator-togglebutton.png or press \key Alt+0 (\key Cmd+0 on Mac OS X). - For more information on using the sidebar, see \l{The sidebar}. + For more information on using the sidebar, see \l {Browsing Project Contents}. + \section1 Moving To Symbols @@ -3083,7 +3632,8 @@ \gui Editor toolbar drop-down menu. For more information on the editor toolbar, - see \l{Using the editor toolbar}. + see \l {Using the Editor Toolbar}. + \section1 Displaying Signals and Slots @@ -3507,8 +4057,8 @@ \table \header - \o 1,2 Action - \o 4,1 Version control system + \o {1,2} Action + \o {4,1} Version control system \header \o CVS \o Git diff --git a/doc/qtcreator.qdocconf b/doc/qtcreator.qdocconf index 08168daba88..c531f2aae0e 100644 --- a/doc/qtcreator.qdocconf +++ b/doc/qtcreator.qdocconf @@ -50,6 +50,8 @@ macro.ouml.HTML = "ö" macro.QA = "\\e{Qt Assistant}" macro.QD = "\\e{Qt Designer}" macro.QL = "\\e{Qt Linguist}" +macro.QC = "\\e{Qt Creator}" +macro.QMLD = "\\e{QML Designer}" macro.param = "\\e" macro.raisedaster.HTML = "*" macro.reg.HTML = "®"