56
\o \l{examples/addressbook-sdk/part1}{Designing the User Interface}
57
\o \l{examples/addressbook-sdk/part2}{Adding Addresses}
58
\o \l{examples/addressbook-sdk/part3}{Navigating between Entries}
59
\o \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses}
60
\o \l{examples/addressbook-sdk/part5}{Adding a Find Function}
61
\o \l{examples/addressbook-sdk/part6}{Loading and Saving}
62
\o \l{examples/addressbook-sdk/part7}{Additional Features}
56
\li \l{examples/addressbook-sdk/part1}{Designing the User Interface}
57
\li \l{examples/addressbook-sdk/part2}{Adding Addresses}
58
\li \l{examples/addressbook-sdk/part3}{Navigating between Entries}
59
\li \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses}
60
\li \l{examples/addressbook-sdk/part5}{Adding a Find Function}
61
\li \l{examples/addressbook-sdk/part6}{Loading and Saving}
62
\li \l{examples/addressbook-sdk/part7}{Additional Features}
65
65
Although this little application does not look much like a fully-fledged
93
93
Begin by launching Qt Creator and use it to generate a new project. To
94
94
do this, select \gui{File} > \gui{New File or Project...} >
95
95
\gui{Qt Application Project} > \gui{Qt Gui Application} and
96
click \gui OK. Set your project name to \bold part1 with the QtCore and
96
click \gui OK. Set your project name to \b part1 with the QtCore and
97
97
QtGui modules checked. Ensure that you select QWidget as your base class
98
98
and name it \c AddressBook.
104
\o \c{main.cpp} - the file containing a \c main() function, with an
105
instance of \c AddressBook,
106
\o \c{addressbook.cpp} - the implementation file for the
107
\c AddressBook class,
108
\o \c{addressbook.h} - the definition file for the \c AddressBook
110
\o \c{addressbook.ui} - the user interface file created with \QD,
112
\o \c{part1.pro} - the project file.
104
\li \c{main.cpp} - the file containing a \c main() function, with an
105
instance of \c AddressBook,
106
\li \c{addressbook.cpp} - the implementation file for the
107
\c AddressBook class,
108
\li \c{addressbook.h} - the definition file for the \c AddressBook
110
\li \c{addressbook.ui} - the user interface file created with \QD,
112
\li \c{part1.pro} - the project file.
115
115
Now that you have all the files you need, click \gui Finish so you can
132
132
QLineEdit and a QTextEdit for the input fields. To create this follow the
133
133
steps mentioned below:
135
\o Drag those widgets from the \gui{Widget Box} to your form.
136
\o In the \gui{Property Editor}, set their \gui{objectName} property to
137
\c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine
138
for the QLineEdit and finally, \c addressText for the QTextEdit.
139
\o Position the widgets properly, according to the screenshot above.
140
\o Use a QGridLayout to position our labels and input fields in a
141
structured manner. QGridLayout divides the available space into
142
a grid and places widgets in the cells you specify with row and
144
\o Place the caption of the \c addressLabel on the top, change the
135
\li Drag those widgets from the \gui{Widget Box} to your form.
136
\li In the \gui{Property Editor}, set their \gui{objectName} property to
137
\c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine
138
for the QLineEdit and finally, \c addressText for the QTextEdit.
139
\li Position the widgets properly, according to the screenshot above.
140
\li Use a QGridLayout to position our labels and input fields in a
141
structured manner. QGridLayout divides the available space into
142
a grid and places widgets in the cells you specify with row and
144
\li Place the caption of the \c addressLabel on the top, change the
145
145
vertical alignment property to \c AlignTop.
227
227
the behavior of a widget has the following advantages:
230
\o You can write implementations of virtual or pure virtual functions
231
to obtain exactly what you need, falling back on the base class's
232
implementation when necessary.
233
\o It allows you to encapsulate parts of the user interface within a
234
class, so that the other parts of the application do not need to
235
know about the individual widgets in the user interface.
236
\o The subclass can be used to create multiple custom widgets in the
237
same application or library, and the code for the subclass can be
238
reused in other projects.
230
\li You can write implementations of virtual or pure virtual functions
231
to obtain exactly what you need, falling back on the base class's
232
implementation when necessary.
233
\li It allows you to encapsulate parts of the user interface within a
234
class, so that the other parts of the application do not need to
235
know about the individual widgets in the user interface.
236
\li The subclass can be used to create multiple custom widgets in the
237
same application or library, and the code for the subclass can be
238
reused in other projects.
241
241
Since Qt does not provided a specific address book widget, you subclass a
272
272
complete the process of adding a contact. Break the existing layouts by
273
273
following the steps below:
275
\o Select, \gui{Break Layout} from the context menu. You might have to
276
do a \gui{Select All} with \key{Ctrl+A} first..
277
\o Add three push buttons and double-click on each of them to set
278
their text to "Add", "Submit", and "Cancel".
279
\o Set the \c objectName of the buttons to \c addButton,
280
\c submitButton and \c cancelButton respectively.
281
\o A \gui{Vertical Spacer} is required to ensure that the push buttons
282
will be laid out neatly; drag one from the \gui{Widget Box}.
283
\o Lay out these three push buttons and the spacer vertically, by
284
selecting all three of them using \key{Ctrl + click} and selecting
285
\gui{Lay out Vertically} from the context menu. Alternatively you
286
can use the \key{Ctrl+L} shortcut key.
275
\li Select, \gui{Break Layout} from the context menu. You might have to
276
do a \gui{Select All} with \key{Ctrl+A} first..
277
\li Add three push buttons and double-click on each of them to set
278
their text to "Add", "Submit", and "Cancel".
279
\li Set the \c objectName of the buttons to \c addButton,
280
\c submitButton and \c cancelButton respectively.
281
\li A \gui{Vertical Spacer} is required to ensure that the push buttons
282
will be laid out neatly; drag one from the \gui{Widget Box}.
283
\li Lay out these three push buttons and the spacer vertically, by
284
selecting all three of them using \key{Ctrl + click} and selecting
285
\gui{Lay out Vertically} from the context menu. Alternatively you
286
can use the \key{Ctrl+L} shortcut key.
288
\note Use the spacer as you do not want the buttons to be evenly
289
spaced, but arranged closer to the top of the widget.
290
\o The figure below shows the difference between using the spacer and
292
\image addressbook-tutorial-part2-stretch-effects.png
293
\o Select all the objects on the form using, \key{Ctrl+A} and lay them
295
\o Lastly, set the top level widget's layout by right-clicking anywhere
296
on the widget and selecting \gui{Lay out Horizontally} or
297
\gui{Lay out Vertically}.
288
\note Use the spacer as you do not want the buttons to be evenly
289
spaced, but arranged closer to the top of the widget.
290
\li The figure below shows the difference between using the spacer and
292
\image addressbook-tutorial-part2-stretch-effects.png
293
\li Select all the objects on the form using, \key{Ctrl+A} and lay them
295
\li Lastly, set the top level widget's layout by right-clicking anywhere
296
on the widget and selecting \gui{Lay out Horizontally} or
297
\gui{Lay out Vertically}.
300
300
The final design of the form is shown in the screenshot below:
376
376
This function can be divided into three parts:
379
\o Extract the contact's detail from \c nameLine and \c addressText
380
and store them in QString objects. Also validate to ensure that
381
you did not click \gui Submit with empty input fields;
382
otherwise, a QMessageBox is displayed to remind you for a name
385
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1
387
\o Then proceed to check if the contact already exists. If it does
388
not exist, add the contact to \c contacts and display a
389
QMessageBox to inform you about this, preventing you from
390
adding duplicate contacts. Our \c contacts object is based on
391
key-value pairs or name and address, hence, you want to ensure that
394
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2
396
\o Once you have handled both cases mentioned above, restore the
397
push buttons to their normal state with the following code:
399
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3
379
\li Extract the contact's detail from \c nameLine and \c addressText
380
and store them in QString objects. Also validate to ensure that
381
you did not click \gui Submit with empty input fields;
382
otherwise, a QMessageBox is displayed to remind you for a name
385
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1
387
\li Then proceed to check if the contact already exists. If it does
388
not exist, add the contact to \c contacts and display a
389
QMessageBox to inform you about this, preventing you from
390
adding duplicate contacts. Our \c contacts object is based on
391
key-value pairs or name and address, hence, you want to ensure that
394
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2
396
\li Once you have handled both cases mentioned above, restore the
397
push buttons to their normal state with the following code:
399
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3
402
402
The screenshot below shows the QMessageBox object used to display
457
457
need to traverse the existing contacts. To do so follow the steps
460
\o Add two push buttons at the bottom of your application and name
461
them: \gui Next and \gui Previous.
462
\o The buttons' \c objectName should be \c nextButton and
463
\c previousButton, respectively.
464
\o Break your top level layout by right-clicking on \c AddressBook in
465
the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}.
466
\o Place the \gui Next and \gui Previous buttons in a horizontal
468
\o Drag and drop the buttons together with their layout into the
469
existing grid layout.
470
\o Set a top level layout for the widget again.
460
\li Add two push buttons at the bottom of your application and name
461
them: \gui Next and \gui Previous.
462
\li The buttons' \c objectName should be \c nextButton and
463
\c previousButton, respectively.
464
\li Break your top level layout by right-clicking on \c AddressBook in
465
the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}.
466
\li Place the \gui Next and \gui Previous buttons in a horizontal
468
\li Drag and drop the buttons together with their layout into the
469
existing grid layout.
470
\li Set a top level layout for the widget again.
473
473
The screenshot below illustrates what you will see as the button layout
523
523
for \c contacts and then:
526
\o If the iterator is not at the end of \c contacts, increment it by
526
\li If the iterator is not at the end of \c contacts, increment it by
528
\o If the iterator is at the end of \c contacts, move it to the
529
beginning of \c contacts. This gives an illusion that our QMap
530
is working like a circularly-linked list.
528
\li If the iterator is at the end of \c contacts, move it to the
529
beginning of \c contacts. This gives an illusion that our QMap
530
is working like a circularly-linked list.
533
533
\snippet examples/addressbook-sdk/part3/addressbook.cpp next
539
539
\c contacts and then:
542
\o If the iterator is at the end of \c contacts, clear the display
544
\o If the iterator is at the beginning of \c contacts, move it to
546
\o Then decrement the iterator by one.
542
\li If the iterator is at the end of \c contacts, clear the display
544
\li If the iterator is at the beginning of \c contacts, move it to
546
\li Then decrement the iterator by one.
549
549
\snippet examples/addressbook-sdk/part3/addressbook.cpp previous
827
827
when you enter a contact name to look up. Once you click the
828
828
dialog's \c findButton, the dialog is hidden and the result code is set to
829
829
either QDialog::Accepted or QDialog::Rejected by the FindDialog's
830
\c findClicked() method. This ensures that you only search for a contact
830
\c findClicked() function. This ensures that you only search for a contact
831
831
if you have typed something in the FindDialog's line edit.
833
833
Then proceed to extract the search string, which in this case is
added
removed
doc/addressbook-sdk.qdoc
