1QDataBrowser(3qt) QDataBrowser(3qt)
2
6 QDataBrowser - Data manipulation and navigation for data entry forms
7
9 #include <qdatabrowser.h>
10 Inherits QWidget.
12 Public Members
14 QDataBrowser ( QWidget * parent = 0, const char * name = 0, WFlags fl =
15 0 )
16 ~QDataBrowser ()
17 enum Boundary { Unknown, None, BeforeBeginning, Beginning, End,
18 AfterEnd }
19 Boundary boundary ()
20 void setBoundaryChecking ( bool active )
21 bool boundaryChecking () const
22 void setSort ( const QSqlIndex & sort )
23 void setSort ( const QStringList & sort )
24 QStringList sort () const
25 void setFilter ( const QString & filter )
26 QString filter () const
27 virtual void setSqlCursor ( QSqlCursor * cursor, bool autoDelete =
28 FALSE )
29 QSqlCursor * sqlCursor () const
30 virtual void setForm ( QSqlForm * form )
31 QSqlForm * form ()
32 virtual void setConfirmEdits ( bool confirm )
33 virtual void setConfirmInsert ( bool confirm )
34 virtual void setConfirmUpdate ( bool confirm )
35 virtual void setConfirmDelete ( bool confirm )
36 virtual void setConfirmCancels ( bool confirm )
37 bool confirmEdits () const
38 bool confirmInsert () const
39 bool confirmUpdate () const
40 bool confirmDelete () const
41 bool confirmCancels () const
42 virtual void setReadOnly ( bool active )
43 bool isReadOnly () const
44 virtual void setAutoEdit ( bool autoEdit )
45 bool autoEdit () const
46 virtual bool seek ( int i, bool relative = FALSE )
47 Public Slots
49 virtual void refresh ()
50 virtual void insert ()
51 virtual void update ()
52 virtual void del ()
53 virtual void first ()
54 virtual void last ()
55 virtual void next ()
56 virtual void prev ()
57 virtual void readFields ()
58 virtual void writeFields ()
59 virtual void clearValues ()
60 void updateBoundary ()
61 Signals
63 void firstRecordAvailable ( bool available )
64 void lastRecordAvailable ( bool available )
65 void nextRecordAvailable ( bool available )
66 void prevRecordAvailable ( bool available )
67 void currentChanged ( const QSqlRecord * record )
68 void primeInsert ( QSqlRecord * buf )
69 void primeUpdate ( QSqlRecord * buf )
70 void primeDelete ( QSqlRecord * buf )
71 void beforeInsert ( QSqlRecord * buf )
72 void beforeUpdate ( QSqlRecord * buf )
73 void beforeDelete ( QSqlRecord * buf )
74 void cursorChanged ( QSqlCursor::Mode mode )
75 Properties
77 bool autoEdit - whether the browser automatically applies edits
78 bool boundaryChecking - whether boundary checking is active
79 bool confirmCancels - whether the browser confirms cancel operations
80 bool confirmDelete - whether the browser confirms deletions
81 bool confirmEdits - whether the browser confirms edits
82 bool confirmInsert - whether the data browser confirms insertions
83 bool confirmUpdate - whether the browser confirms updates
84 QString filter - the data browser's filter
85 bool readOnly - whether the browser is read-only
86 QStringList sort - the data browser's sort
87 Protected Members
89 virtual bool insertCurrent ()
90 virtual bool updateCurrent ()
91 virtual bool deleteCurrent ()
92 virtual bool currentEdited ()
93 virtual QSql::Confirm confirmEdit ( QSql::Op m )
94 virtual QSql::Confirm confirmCancel ( QSql::Op m )
95 virtual void handleError ( const QSqlError & error )
96
98 The QDataBrowser class provides data manipulation and navigation for
99 data entry forms.
100 A high-level API is provided for navigating through data records in a
102 cursor, for inserting, updating and deleting records, and for
103 refreshing data in the display.
104 If you want a read-only form to present database data use QDataView; if
106 you want a table-based presentation of your data use QDataTable.
107 A QDataBrowser is used to associate a dataset with a form in much the
109 same way as a QDataTable associates a dataset with a table. Once the
110 data browser has been constructed it can be associated with a dataset
111 with setSqlCursor(), and with a form with setForm(). Boundary checking,
112 sorting and filtering can be set with setBoundaryChecking(), setSort()
113 and setFilter(), respectively.
114 The insertCurrent() function reads the fields from the default form
116 into the default cursor and performs the insert. The updateCurrent()
117 and deleteCurrent() functions perform similarly to update and delete
118 the current record respectively.
119 The user can be asked to confirm all edits with setConfirmEdits(). For
121 more precise control use setConfirmInsert(), setConfirmUpdate(),
122 setConfirmDelete() and setConfirmCancels(). Use setAutoEdit() to
123 control the behaviour of the form when the user edits a record and then
124 navigates.
125 The record set is navigated using first(), next(), prev(), last() and
127 seek(). The form's display is updated with refresh(). When navigation
128 takes place the firstRecordAvailable(), lastRecordAvailable(),
129 nextRecordAvailable() and prevRecordAvailable() signals are emitted.
130 When the cursor record is changed due to navigation the cursorChanged()
131 signal is emitted.
132 If you want finer control of the insert, update and delete processes
134 then you can use the lower level functions to perform these operations
135 as described below.
136 The form is populated with data from the database with readFields(). If
138 the user is allowed to edit, (see setReadOnly()), write the form's data
139 back to the cursor's edit buffer with writeFields(). You can clear the
140 values in the form with clearValues(). Editing is performed as follows:
141 insert When the data browser enters insertion mode it emits the
143 primeInsert() signal which you can connect to, for example to pre-
144 populate fields. Call writeFields() to write the user's edits to the
145 cursor's edit buffer then call insert() to insert the record into the
146 database. The beforeInsert() signal is emitted just before the cursor's
147 edit buffer is inserted into the database; connect to this for example,
148 to populate fields such as an auto-generated primary key.
149 update For updates the primeUpdate() signal is emitted when the data
151 browser enters update mode. After calling writeFields() call update()
152 to update the record and connect to the beforeUpdate() signal to
153 manipulate the user's data before the update takes place.
154 delete For deletion the primeDelete() signal is emitted when the data
156 browser enters deletion mode. After calling writeFields() call del() to
157 delete the record and connect to the beforeDelete() signal, for example
158 to record an audit of the deleted record.
159 See also Database Classes.
161 Member Type Documentation
164 This enum describes where the data browser is positioned.
165 QDataBrowser::Unknown - the boundary cannot be determined (usually
167 because there is no default cursor, or the default cursor is not
168 active).
169 QDataBrowser::None - the browser is not positioned on a boundary, but
171 it is positioned on a record somewhere in the middle.
172 QDataBrowser::BeforeBeginning - the browser is positioned before the
174 first available record.
175 QDataBrowser::Beginning - the browser is positioned at the first
177 record.
178 QDataBrowser::End - the browser is positioned at the last record.
180 QDataBrowser::AfterEnd - the browser is positioned after the last
182 available record.
183
186 WFlags fl = 0 )
187 Constructs a data browser which is a child of parent, with the name
188 name and widget flags set to fl.
189
191 Destroys the object and frees any allocated resources.
192
194 Returns TRUE if the browser automatically applies edits; otherwise
195 returns FALSE. See the "autoEdit" property for details.
196
198 This signal is emitted just before the cursor's edit buffer is deleted
199 from the database. The buf parameter points to the edit buffer being
200 deleted. You might connect to this signal to capture some auditing
201 information about the deletion.
202
204 This signal is emitted just before the cursor's edit buffer is inserted
205 into the database. The buf parameter points to the edit buffer being
206 inserted. You might connect to this signal to populate a generated
207 primary key for example.
208
210 This signal is emitted just before the cursor's edit buffer is updated
211 in the database. The buf parameter points to the edit buffer being
212 updated. You might connect to this signal to capture some auditing
213 information about the update.
214
216 Returns an enum indicating the boundary status of the browser.
217 This is achieved by moving the default cursor and checking the
219 position, however the current default form values will not be altered.
220 After checking for the boundary, the cursor is moved back to its former
221 position. See QDataBrowser::Boundary.
222 See also Boundary.
224
226 Returns TRUE if boundary checking is active; otherwise returns FALSE.
227 See the "boundaryChecking" property for details.
228
230 Clears all the values in the form.
231 All the edit buffer field values are set to their 'zero state', e.g. 0
233 for numeric fields and "" for string fields. Then the widgets are
234 updated using the property map. For example, a combobox that is
235 property-mapped to integers would scroll to the first item. See the
236 QSqlPropertyMap constructor for the default mappings of widgets to
237 properties.
238
240 Protected virtual function which returns a confirmation for cancelling
241 an edit mode m. Derived classes can reimplement this function and
242 provide their own confirmation dialog. The default implementation uses
243 a message box which prompts the user to confirm the edit action.
244
246 Returns TRUE if the browser confirms cancel operations; otherwise
247 returns FALSE. See the "confirmCancels" property for details.
248
250 Returns TRUE if the browser confirms deletions; otherwise returns
251 FALSE. See the "confirmDelete" property for details.
252
254 Protected virtual function which returns a confirmation for an edit of
255 mode m. Derived classes can reimplement this function and provide their
256 own confirmation dialog. The default implementation uses a message box
257 which prompts the user to confirm the edit action.
258
260 Returns TRUE if the browser confirms edits; otherwise returns FALSE.
261 See the "confirmEdits" property for details.
262
264 Returns TRUE if the data browser confirms insertions; otherwise returns
265 FALSE. See the "confirmInsert" property for details.
266
268 Returns TRUE if the browser confirms updates; otherwise returns FALSE.
269 See the "confirmUpdate" property for details.
270
272 This signal is emitted whenever the current cursor position changes.
273 The record parameter points to the contents of the current cursor's
274 record.
275
277 Returns TRUE if the form's edit buffer differs from the current cursor
278 buffer; otherwise returns FALSE.
279
281 This signal is emitted whenever the cursor record was changed due to
282 navigation. The mode parameter is the edit that just took place, e.g.
283 Insert, Update or Delete. See QSqlCursor::Mode.
284
286 Performs a delete operation on the data browser's cursor. If there is
287 no default cursor or no default form, nothing happens.
288 Otherwise, the following happens:
290 The current form's record is deleted from the database, providing that
292 the data browser is not in insert mode. If the data browser is actively
293 inserting a record (see insert()), the insert action is canceled, and
294 the browser navigates to the last valid record that was current. If
295 there is an error, handleError() is called.
296
298 Performs a delete on the default cursor using the values from the
299 default form and updates the default form. If there is no default form
300 or no default cursor, nothing happens. If the deletion was successful,
301 the cursor is repositioned to the nearest record and TRUE is returned.
302 The nearest record is the next record if there is one otherwise the
303 previous record if there is one. If an error occurred during the
304 deletion from the database, handleError() is called and FALSE is
305 returned.
306 See also cursor, form(), and handleError().
308
310 Returns the data browser's filter. See the "filter" property for
311 details.
312
314 Moves the default cursor to the first record and refreshes the default
315 form to display this record. If there is no default form or no default
316 cursor, nothing happens. If the data browser successfully navigated to
317 the first record, the default cursor is primed for update and the
318 primeUpdate() signal is emitted.
319 If the browser is already positioned on the first record nothing
321 happens.
322
324 This signal is emitted whenever the position of the cursor changes. The
325 available parameter indicates whether or not the first record in the
326 default cursor is available.
327
329 Returns the data browser's default form or 0 if no form has been set.
330
332 Virtual function which handles the error error. The default
334 implementation warns the user with a message box.
335
337 Performs an insert operation on the data browser's cursor. If there is
338 no default cursor or no default form, nothing happens.
339 If auto-editing is on (see setAutoEdit()), the following happens:
341 If the browser is already actively inserting a record, the current
343 form's data is inserted into the database.
344 If the browser is not inserting a record, but the current record was
346 changed by the user, the record is updated in the database with the
347 current form's data (i.e. with the changes).
348 If there is an error handling any of the above auto-edit actions,
350 handleError() is called and no insert or update is performed.
351 If no error occurred, or auto-editing is not enabled, the data browser
353 begins actively inserting a record into the database by performing the
354 following actions:
355 The default cursor is primed for insert using
357 QSqlCursor::primeInsert().
358 The primeInsert() signal is emitted.
360 The form is updated with the values in the default cursor's. edit
362 buffer so that the user can fill in the values to be inserted.
363
365 Reads the fields from the default form into the default cursor and
366 performs an insert on the default cursor. If there is no default form
367 or no default cursor, nothing happens. If an error occurred during the
368 insert into the database, handleError() is called and FALSE is
369 returned. If the insert was successfull, the cursor is refreshed and
370 relocated to the newly inserted record, the cursorChanged() signal is
371 emitted, and TRUE is returned.
372 See also cursorChanged(), sqlCursor(), form(), and handleError().
374
376 Returns TRUE if the browser is read-only; otherwise returns FALSE. See
377 the "readOnly" property for details.
378
380 Moves the default cursor to the last record and refreshes the default
381 form to display this record. If there is no default form or no default
382 cursor, nothing happens. If the data browser successfully navigated to
383 the last record, the default cursor is primed for update and the
384 primeUpdate() signal is emitted.
385 If the browser is already positioned on the last record nothing
387 happens.
388
390 This signal is emitted whenever the position of the cursor changes. The
391 available parameter indicates whether or not the last record in the
392 default cursor is available.
393
395 Moves the default cursor to the next record and refreshes the default
396 form to display this record. If there is no default form or no default
397 cursor, nothing happens. If the data browser successfully navigated to
398 the next record, the default cursor is primed for update and the
399 primeUpdate() signal is emitted.
400 If the browser is positioned on the last record nothing happens.
402
404 This signal is emitted whenever the position of the cursor changes. The
405 available parameter indicates whether or not the next record in the
406 default cursor is available.
407
409 Moves the default cursor to the previous record and refreshes the
410 default form to display this record. If there is no default form or no
411 default cursor, nothing happens. If the data browser successfully
412 navigated to the previous record, the default cursor is primed for
413 update and the primeUpdate() signal is emitted.
414 If the browser is positioned on the first record nothing happens.
416
418 This signal is emitted whenever the position of the cursor changes. The
419 available parameter indicates whether or not the previous record in the
420 default cursor is available.
421
423 This signal is emitted when the data browser enters deletion mode. The
424 buf parameter points to the record buffer being deleted. (Note that
425 QSqlCursor::primeDelete() is not called on the default cursor, as this
426 would corrupt values in the form.) Connect to this signal in order to,
427 for example, save a copy of the deleted record for auditing purposes.
428 See also del().
430
432 This signal is emitted when the data browser enters insertion mode. The
433 buf parameter points to the record buffer that is to be inserted.
434 Connect to this signal to, for example, prime the record buffer with
435 default data values, auto-numbered fields etc. (Note that
436 QSqlCursor::primeInsert() is not called on the default cursor, as this
437 would corrupt values in the form.)
438 See also insert().
440
442 This signal is emitted when the data browser enters update mode. Note
443 that during navigation (first(), last(), next(), prev()), each record
444 that is shown in the default form is primed for update. The buf
445 parameter points to the record buffer being updated. (Note that
446 QSqlCursor::primeUpdate() is not called on the default cursor, as this
447 would corrupt values in the form.) Connect to this signal in order to,
448 for example, keep track of which records have been updated, perhaps for
449 auditing purposes.
450 See also update().
452
454 Reads the fields from the default cursor's edit buffer and displays
455 them in the form. If there is no default cursor or no default form,
456 nothing happens.
457
459 Refreshes the data browser's data using the default cursor. The
460 browser's current filter and sort are applied if they have been set.
461 See also filter and sort.
463
465 Moves the default cursor to the record specified by the index i and
466 refreshes the default form to display this record. If there is no
467 default form or no default cursor, nothing happens. If relative is TRUE
468 (the default is FALSE), the cursor is moved relative to its current
469 position. If the data browser successfully navigated to the desired
470 record, the default cursor is primed for update and the primeUpdate()
471 signal is emitted.
472 If the browser is already positioned on the desired record nothing
474 happens.
475
477 Sets whether the browser automatically applies edits to autoEdit. See
478 the "autoEdit" property for details.
479
481 Sets whether boundary checking is active to active. See the
482 "boundaryChecking" property for details.
483
485 Sets whether the browser confirms cancel operations to confirm. See the
486 "confirmCancels" property for details.
487
489 Sets whether the browser confirms deletions to confirm. See the
490 "confirmDelete" property for details.
491
493 Sets whether the browser confirms edits to confirm. See the
494 "confirmEdits" property for details.
495
497 Sets whether the data browser confirms insertions to confirm. See the
498 "confirmInsert" property for details.
499
501 Sets whether the browser confirms updates to confirm. See the
502 "confirmUpdate" property for details.
503
505 Sets the data browser's filter to filter. See the "filter" property for
506 details.
507
509 Sets the browser's default form to form. The cursor and all navigation
510 and data manipulation functions that the browser provides become
511 available to the form.
512
514 Sets whether the browser is read-only to active. See the "readOnly"
515 property for details.
516
518 Sets the data browser's sort to sort. See the "sort" property for
519 details.
520
522 This is an overloaded member function, provided for convenience. It
523 behaves essentially like the above function.
524 Sets the data browser's sort to the QSqlIndex sort. To apply the new
526 sort, use refresh().
527
529 ) [virtual]
530 Sets the default cursor used by the data browser to cursor. If
531 autoDelete is TRUE (the default is FALSE), the data browser takes
532 ownership of the cursor pointer, which will be deleted when the browser
533 is destroyed, or when setSqlCursor() is called again. To activate the
534 cursor use refresh(). The cursor's edit buffer is used in the default
535 form to browse and edit records.
536 See also sqlCursor(), form(), and setForm().
538
540 Returns the data browser's sort. See the "sort" property for details.
541
543 Returns the default cursor used for navigation, or 0 if there is no
544 default cursor.
545 See also setSqlCursor().
547
549 Performs an update operation on the data browser's cursor.
550 If there is no default cursor or no default form, nothing happens.
552 Otherwise, the following happens:
553 If the data browser is actively inserting a record (see insert()), that
555 record is inserted into the database using insertCurrent(). Otherwise,
556 the database is updated with the current form's data using
557 updateCurrent(). If there is an error handling either action,
558 handleError() is called.
559
561 If boundaryChecking() is TRUE, checks the boundary of the current
562 default cursor and emits signals which indicate the position of the
563 cursor.
564
566 Reads the fields from the default form into the default cursor and
567 performs an update on the default cursor. If there is no default form
568 or no default cursor, nothing happens. If an error occurred during the
569 update on the database, handleError() is called and FALSE is returned.
570 If the update was successfull, the cursor is refreshed and relocated to
571 the updated record, the cursorChanged() signal is emitted, and TRUE is
572 returned.
573 See also cursor, form(), and handleError().
575
577 Writes the form's data to the default cursor's edit buffer. If there is
578 no default cursor or no default form, nothing happens.
579 Property Documentation
582 This property holds whether the browser automatically applies edits.
583 The default value for this property is TRUE. When the user begins an
585 insertion or an update on a form there are two possible outcomes when
586 they navigate to another record:
587 the insert or update is is performed -- this occurs if autoEdit is TRUE
589 the insert or update is discarded -- this occurs if autoEdit is FALSE
591 Set this property's value with setAutoEdit() and get this property's
593 value with autoEdit().
594
596 This property holds whether boundary checking is active.
597 When boundary checking is active (the default), signals are emitted
599 indicating the current position of the default cursor.
600 See also boundary().
602 Set this property's value with setBoundaryChecking() and get this
604 property's value with boundaryChecking().
605
607 This property holds whether the browser confirms cancel operations.
608 If this property is TRUE, all cancels must be confirmed by the user
610 through a message box (this behavior can be changed by overriding the
611 confirmCancel() function), otherwise all cancels occur immediately. The
612 default is FALSE.
613 See also confirmEdits and confirmCancel().
615 Set this property's value with setConfirmCancels() and get this
617 property's value with confirmCancels().
618
620 This property holds whether the browser confirms deletions.
621 If this property is TRUE, the browser confirms deletions, otherwise
623 deletions happen immediately.
624 See also confirmCancels, confirmEdits, confirmUpdate, confirmInsert,
626 and confirmEdit().
627 Set this property's value with setConfirmDelete() and get this
629 property's value with confirmDelete().
630
632 This property holds whether the browser confirms edits.
633 If this property is TRUE, the browser confirms all edit operations
635 (insertions, updates and deletions), otherwise all edit operations
636 happen immediately. Confirmation is achieved by presenting the user
637 with a message box -- this behavior can be changed by reimplementing
638 the confirmEdit() function,
639 See also confirmEdit(), confirmCancels, confirmInsert, confirmUpdate,
641 and confirmDelete.
642 Set this property's value with setConfirmEdits() and get this
644 property's value with confirmEdits().
645
647 This property holds whether the data browser confirms insertions.
648 If this property is TRUE, the browser confirms insertions, otherwise
650 insertions happen immediately.
651 See also confirmCancels, confirmEdits, confirmUpdate, confirmDelete,
653 and confirmEdit().
654 Set this property's value with setConfirmInsert() and get this
656 property's value with confirmInsert().
657
659 This property holds whether the browser confirms updates.
660 If this property is TRUE, the browser confirms updates, otherwise
662 updates happen immediately.
663 See also confirmCancels, confirmEdits, confirmInsert, confirmDelete,
665 and confirmEdit().
666 Set this property's value with setConfirmUpdate() and get this
668 property's value with confirmUpdate().
669
671 This property holds the data browser's filter.
672 The filter applies to the data shown in the browser. Call refresh() to
674 apply the new filter. A filter is a string containing a SQL WHERE
675 clause without the WHERE keyword, e.g. "id>1000"," name LIKE 'A%'",
676 etc.
677 There is no default filter.
679 See also sort.
681 Set this property's value with setFilter() and get this property's
683 value with filter().
684
686 This property holds whether the browser is read-only.
687 The default is FALSE, i.e. data can be edited. If the data browser is
689 read-only, no database edits will be allowed.
690 Set this property's value with setReadOnly() and get this property's
692 value with isReadOnly().
693
695 This property holds the data browser's sort.
696 The data browser's sort affects the order in which records are viewed
698 in the browser. Call refresh() to apply the new sort.
699 When retrieving the sort property, a string list is returned in the
701 form 'fieldname order', e.g. 'id ASC', 'surname DESC'.
702 There is no default sort.
704 Note that if you want to iterate over the list, you should iterate over
706 a copy, e.g.
707 QStringList list = myDataBrowser.sort();
709 QStringList::Iterator it = list.begin();
710 while( it != list.end() ) {
711 myProcessing( *it );
712 ++it;
713 }
714 Set this property's value with setSort() and get this property's value
716 with sort().
717
720 http://doc.trolltech.com/qdatabrowser.html
721 http://www.trolltech.com/faq/tech.html
722
724 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
725 license file included in the distribution for a complete license
726 statement.
727
729 Generated automatically from the source code.
730
732 If you find a bug in Qt, please report it as described in
733 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
734 help you. Thank you.
735 The definitive Qt documentation is provided in HTML format; it is
737 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
738 web browser. This man page is provided as a convenience for those users
739 who prefer man pages, although this format is not officially supported
740 by Trolltech.
741 If you find errors in this manual page, please report them to qt-
743 bugs@trolltech.com. Please include the name of the manual page
744 (qdatabrowser.3qt) and the Qt version (3.3.8).
745Trolltech AS 2 February 2007 QDataBrowser(3qt)