diff options
Diffstat (limited to 'doc/html/designer-manual-8.html')
| -rw-r--r-- | doc/html/designer-manual-8.html | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/doc/html/designer-manual-8.html b/doc/html/designer-manual-8.html index 9886c3846..5f2cd5537 100644 --- a/doc/html/designer-manual-8.html +++ b/doc/html/designer-manual-8.html @@ -113,7 +113,7 @@ bool createConnections() <!-- index TQSqlDatabase::database() --><p>You do not need to keep a reference to database connections. If you use a single database connection, this becomes the default connection and database functions will use this connection automatically. We can always get a pointer to any of our connections by calling <tt>TQSqlDatabase::database()</tt>.</p> <p>If you create a <tt>main.cpp</tt> file using <em>TQt Designer</em>, this file will <em>not</em> include <tt>createConnections()</tt>. We do not include this function because it needs the username and password for the database connection, and you may prefer to handle these differently from our simple example function. As a result, applications that preview correctly in <em>TQt Designer</em> will not run unless you implement your own database connections function.</p> <h3><a name="2"></a>Using <a href="qdatatable.html">TQDataTable</a></h3> -<p><a href="qdatatable.html">TQDataTable</a>s may be placed on any form to provide browsing of database tables and views. <a href="qdatatable.html">TQDataTable</a>s can also be used to update or delete records in-place, i.e. inside the cells themselves. Inserting records via a <a href="qdatatable.html">TQDataTable</a> usually retquires connecting to the<!-- index primeInsert() --> <tt>primeInsert()</tt> signal, so that we can generate primary keys for example, or provide default values. If we wish to present records using a form view (perhaps combining data from several tables and views) we might use several <a href="qdatabrowser.html">TQDataBrowser</a>s and <a href="qdataview.html">TQDataView</a>s.</p> +<p><a href="qdatatable.html">TQDataTable</a>s may be placed on any form to provide browsing of database tables and views. <a href="qdatatable.html">TQDataTable</a>s can also be used to update or delete records in-place, i.e. inside the cells themselves. Inserting records via a <a href="qdatatable.html">TQDataTable</a> usually requires connecting to the<!-- index primeInsert() --> <tt>primeInsert()</tt> signal, so that we can generate primary keys for example, or provide default values. If we wish to present records using a form view (perhaps combining data from several tables and views) we might use several <a href="qdatabrowser.html">TQDataBrowser</a>s and <a href="qdataview.html">TQDataView</a>s.</p> <h4><a name="2-1"></a>Quickly Viewing a Database Table</h4> <p>This example, along with all the other examples in this chapter, has the project name 'book' and uses the database created by the<!-- index book.sql --> <tt>book.sql</tt> script. As we work through the chapter we will build the 'book' application step by step. Create or copy the <tt>qt/tools/designer/examples/book/book1/main.cpp</tt> file shown earlier. The project file for this first example is <tt>qt/tools/designer/examples/book/book1/book.pro</tt>. Start a new project by clicking <b>File|New</b>, then click the 'C++ Project' icon to invoke the <em>Project Settings</em> dialog. Click the ellipsis button to invoke the <em>Save As</em> dialog; navigate to the project's directory (creating it if necessary). Make sure you're in the project's directory, then enter a project name of 'book.pro'. Click the <b>Save</b> button to return to the <em>Project Settings</em> dialog, then click <b>OK</b>. Now click <b>Project|Database Connections</b>. Fill in the connection information appropriate to your database then press <b>Connect</b>. The connection name should now appear in the left hand list box. (If this doesn't happen you'll need to contact your database systems administrator for help.) Close the dialog.</p> <p>We will now create a new form with a <a href="qdatatable.html">TQDataTable</a> that's connected to one of our database tables.</p> @@ -144,7 +144,7 @@ bool createConnections() <!-- index Foreign Keys --><!-- index Databases!Foreign Keys --><p>In most relational databases tables contain fields which are foreign keys into other tables. In our 'book' database example the authorid in the book table is a foreign key into the author table. When we present a form to the end user we do not usually want the foreign key itself to be visible but rather the text associated with it. Thus, we would want the author's name to appear rather than the author id when we show book information. In many databases, this can be achieved by using a view. See your database's documentation for details.</p> </blockquote> <h4><a name="2-2"></a>Inserting Records in <a href="qdatatable.html">TQDataTable</a>s</h4> -<!-- index Inserting Records --><!-- index Databases!Inserting Records --><p>Record insertion into a relational database usually retquires the generation of a primary key value which uniquely identifies the record in the table. Also we often want to create default values for some fields to minimize the user's work. We will create a slot to capture the <a href="qdatatable.html">TQDataTable</a>s<!-- index primeInsert() --> <tt>primeInsert()</tt> signal and populate the <a href="qsqlrecord.html">TQSqlRecord</a> insertion buffer with a unique primary key.</p> +<!-- index Inserting Records --><!-- index Databases!Inserting Records --><p>Record insertion into a relational database usually requires the generation of a primary key value which uniquely identifies the record in the table. Also we often want to create default values for some fields to minimize the user's work. We will create a slot to capture the <a href="qdatatable.html">TQDataTable</a>s<!-- index primeInsert() --> <tt>primeInsert()</tt> signal and populate the <a href="qsqlrecord.html">TQSqlRecord</a> insertion buffer with a unique primary key.</p> <ol type=1><li><p>Click <b>Edit|Slots</b> to invoke the <em>Edit Functions</em> dialog. Click <b>New Function</b>, then enter the slot name <tt>primeInsertAuthor(TQSqlRecord*)</tt> into the Function Properties' Function line edit box. Click <b>OK</b>.</p> <li><p>Click the <b>Connect Signals/Slots</b> toolbar button, then click the AuthorDataTable, drag to the form and release the mouse. The <em>Edit Connections</em> dialog will now appear. Click the<!-- index primeInsert() --> <tt>primeInsert()</tt> signal and then the <tt>primeInsertAuthor()</tt> slot to make the connection. Now click <b>OK</b>.</p> <li><p>Click the Members tab of the Object Explorer window (click <b>Window|Views|Object Explorer</b> to make the window visible if necessary). Click the <tt>primeInsertAuthor()</tt> slot and an editor window will appear.</p> @@ -161,15 +161,15 @@ bool createConnections() </pre> <p>A <a href="qsqlquery.html">TQSqlQuery</a> object is used to increment and retrieve a unique 'sequence' number for the author table. The signal passed us a pointer to the insertion buffer and we then put the value we've retrieved, i.e. the next sequence number, into the buffer's id field. (Again, note that SQL databases often support a native 'sequence' function. The method used here is inappropriate for production systems, and is for example purposes only. See your database's documentation for details on how to generate unique keys in code. In many cases, the database can generate them automatically, or the database may provide a special syntax for dealing with sequences.)</p> </ol><!-- index Deleting!Records!Databases --><!-- index Databases!Deleting Records --><!-- index Updating Records --><!-- index Databases!Updating Records --><p>If we rebuild the application it will now support <tt>INSERT</tt> as well as <tt>UPDATE</tt> and <tt>DELETE</tt>. We could easily have added additional code to insert default values, e.g. today's date into a date field, if necessary.</p> -<!-- index Databases!Browsing --><!-- index Databases!Confirmations --><!-- index Browsing Databases --><p>Browsing is supported by clicking records and by using the arrow keys. Once a record is active (highlighted) we can edit the it. Press the <b>Insert</b> key to <tt>INSERT</tt> a new record; press <b>F2</b> to <tt>UPDATE</tt> the current record; press the <b>Del</b> key to <tt>DELETE</tt> the current record. All these operations take place immediately. Users can be given the opportunity to confirm their edits by setting the <a href="qdatatable.html">TQDataTable</a>'s confirmEdits property to True. If the confirmEdits property is True then user confirmation will be retquired for all insertions, updates and deletes. For finer control you can set the confirmInsert, confirmUpdate and confirmDelete properties individually.</p> +<!-- index Databases!Browsing --><!-- index Databases!Confirmations --><!-- index Browsing Databases --><p>Browsing is supported by clicking records and by using the arrow keys. Once a record is active (highlighted) we can edit the it. Press the <b>Insert</b> key to <tt>INSERT</tt> a new record; press <b>F2</b> to <tt>UPDATE</tt> the current record; press the <b>Del</b> key to <tt>DELETE</tt> the current record. All these operations take place immediately. Users can be given the opportunity to confirm their edits by setting the <a href="qdatatable.html">TQDataTable</a>'s confirmEdits property to True. If the confirmEdits property is True then user confirmation will be required for all insertions, updates and deletes. For finer control you can set the confirmInsert, confirmUpdate and confirmDelete properties individually.</p> <blockquote> <p align="center"><b> <a href="qdatatable.html">TQDataTable</a> User Interface Interaction</b></p> <!-- index Databases!User Interface Interaction --><!-- index User Interface Interaction, Databases --><p>The default user-interface behavior for <a href="qdatatable.html">TQDataTable</a>s is as follows:</p> <ul><li><p>Users can move to records by clicking the scrollbar and clicking records with the mouse. They can also use the keyboard's navigation keys, e.g. <b>Left Arrow</b>, <b>Right Arrow</b>, <b>Up Arrow</b>, <b>Down Arrow</b>, <b>Page Up</b>, <b>Page Down</b>, <b>Home</b> and <b>End</b>.</p> -<li><p><tt>INSERT</tt> is initiated by right-clicking the record and clicking Insert or by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. The <tt>INSERT</tt> will take place if the user presses <b>Enter</b> or <b>Tab</b>s off the last field. If autoEdit is TRUE the insert will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing <b>Esc</b> (Escape). If autoEdit is FALSE navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will retquire the user to confirm each <tt>INSERT</tt>.</p> -<li><p><tt>UPDATE</tt> is initiated by right-clicking the record and clicking Update or by pressing <b>F2</b>. The update will take place if the user presses Enter or Tabs off the last field. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing <b>Esc</b>. If autoEdit is FALSE navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will retquire the user to confirm each <tt>UPDATE</tt>.</p> -<li><p><tt>DELETE</tt> is achieved by right-clicking the record and clicking Delete or by pressing the <b>Del</b> (Delete) key. Setting confirmDelete to TRUE will retquire the user to confirm each <tt>DELETE</tt>.</p> -</ul><p>You can change this default behavior programmatically if retquired.</p> +<li><p><tt>INSERT</tt> is initiated by right-clicking the record and clicking Insert or by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. The <tt>INSERT</tt> will take place if the user presses <b>Enter</b> or <b>Tab</b>s off the last field. If autoEdit is TRUE the insert will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing <b>Esc</b> (Escape). If autoEdit is FALSE navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will require the user to confirm each <tt>INSERT</tt>.</p> +<li><p><tt>UPDATE</tt> is initiated by right-clicking the record and clicking Update or by pressing <b>F2</b>. The update will take place if the user presses Enter or Tabs off the last field. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing <b>Esc</b>. If autoEdit is FALSE navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will require the user to confirm each <tt>UPDATE</tt>.</p> +<li><p><tt>DELETE</tt> is achieved by right-clicking the record and clicking Delete or by pressing the <b>Del</b> (Delete) key. Setting confirmDelete to TRUE will require the user to confirm each <tt>DELETE</tt>.</p> +</ul><p>You can change this default behavior programmatically if required.</p> </blockquote> <h4><a name="2-3"></a>Relating Two Tables Together (Master-Detail)</h4> <!-- index Databases!Master-Detail Relationships --><!-- index Master-Detail Relationships --><p>Databases often have pairs of tables that are related. For example, an invoice table might list the numbers, dates and customers for invoices, but not the actual invoice items, which an invoice item table might store. In the 'book' application we wish to have a <a href="qdatatable.html">TQDataTable</a> that we can use to browse through the authors table and a second <a href="qdatatable.html">TQDataTable</a> to show the books they've written.</p> @@ -210,7 +210,7 @@ bool createConnections() BookDataTable->refresh(); } </pre> - <p>All that's retquired now is to change the BookDataTable's filter and refresh the <a href="qdatatable.html">TQDataTable</a> to show the results of the filter.</p> + <p>All that's required now is to change the BookDataTable's filter and refresh the <a href="qdatatable.html">TQDataTable</a> to show the results of the filter.</p> </ol><h5><a name="2-3-2"></a>Preparing the Interface for Drilldown</h5> <!-- index Databases!Drilldown --><!-- index Drilldown --><p>We can now browse and edit authors and see their books in the BookDataTable. In the next section we explore <a href="qdatabrowser.html">TQDataBrowser</a>, which will allow us to drill down to a dialog through which we can edit books. For now we will add some buttons to the main BookForm which we will use to invoke the book editing dialog.</p> <ol type=1><li><p>Click the form, then click the <b>Break Layout</b> toolbar button. Resize the form to make room for some buttons at the bottom.</p> @@ -250,9 +250,9 @@ bool createConnections() <li><!-- index readFields() --><p><tt>readFields()</tt> to read data from the cursor's edit buffer and<!-- index writeFields() --> <tt>writeFields()</tt> to write the form's data to the cursor's edit buffer;</p> <li><!-- index clearValues() --><p><tt>clearValues()</tt> to clear the form's values.</p> </ul><p>If you use <em>TQt Designer</em>'s <a href="qdatabrowser.html">TQDataBrowser</a> wizard you will be given the option of creating a default set of buttons for navigation and editing. The behavior of these buttons is set up using the slots described above to provide the following functionality:</p> -<ul><li><p><tt>INSERT</tt> is initiated by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. If the user presses the Update button the <tt>INSERT</tt> will take place and the user will be taken to the record they have just inserted. If the user presses the Insert button (i.e. a second time) the <tt>INSERT</tt> will take place and a new insertion will be initiated. If autoEdit is TRUE the <tt>INSERT</tt> will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> (Delete) key. If autoEdit is FALSE then navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will retquire the user to confirm each <tt>INSERT</tt>.</p> -<li><p><tt>UPDATE</tt> is automatically initiated whenever the user navigates to a record. An update will take place if the user presses the Update button. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> button. If autoEdit is FALSE then navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will retquire the user to confirm each <tt>UPDATE</tt>.</p> -<li><p><tt>DELETE</tt> is achieved by pressing the <b>Del</b> key. Setting confirmDelete to TRUE will retquire the user to confirm each <tt>DELETE</tt>.</p> +<ul><li><p><tt>INSERT</tt> is initiated by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. If the user presses the Update button the <tt>INSERT</tt> will take place and the user will be taken to the record they have just inserted. If the user presses the Insert button (i.e. a second time) the <tt>INSERT</tt> will take place and a new insertion will be initiated. If autoEdit is TRUE the <tt>INSERT</tt> will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> (Delete) key. If autoEdit is FALSE then navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will require the user to confirm each <tt>INSERT</tt>.</p> +<li><p><tt>UPDATE</tt> is automatically initiated whenever the user navigates to a record. An update will take place if the user presses the Update button. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> button. If autoEdit is FALSE then navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will require the user to confirm each <tt>UPDATE</tt>.</p> +<li><p><tt>DELETE</tt> is achieved by pressing the <b>Del</b> key. Setting confirmDelete to TRUE will require the user to confirm each <tt>DELETE</tt>.</p> </ul></blockquote> <h5><a name="3-1-2"></a>Performing the Drilldown</h5> <!-- index Databases!Drilldown --><!-- index Drilldown --><p>We now have a working form for editing book records. We need to start the form when the user clicks our 'Edit Books' button, and to navigate to the record they have selected in the BookDataTable. We also need to provide a means of editing the foreign keys, e.g. authorid.</p> @@ -344,7 +344,7 @@ bool createConnections() } </pre> <p>Firstly we look up the book's author and secondly we iterate through the <em>ComboBox</em>'s items until we find the author and set the <em>ComboBox</em>'s current item to the matching author.</p> -</ul></ol><p>If the author name has changed or been deleted the query will fail and no author id will be inserted into the buffer causing the <tt>INSERT</tt> to fail. An alternative is to record the author id's as we populate the <em>ComboBox</em> and store them in a <a href="qmap.html">TQMap</a> which we can then look up as retquired. This approach retquires changes to the<!-- index init() --> <tt>init()</tt>, <tt>beforeUpdateBook()</tt> and <tt>primeInsertBook()</tt> functions and the addition of a new function, <tt>mapAuthor()</tt>. The relevant code from <tt>qt/tools/designer/examples/book/book8/editbook.ui</tt> is shown below.</p> +</ul></ol><p>If the author name has changed or been deleted the query will fail and no author id will be inserted into the buffer causing the <tt>INSERT</tt> to fail. An alternative is to record the author id's as we populate the <em>ComboBox</em> and store them in a <a href="qmap.html">TQMap</a> which we can then look up as required. This approach requires changes to the<!-- index init() --> <tt>init()</tt>, <tt>beforeUpdateBook()</tt> and <tt>primeInsertBook()</tt> functions and the addition of a new function, <tt>mapAuthor()</tt>. The relevant code from <tt>qt/tools/designer/examples/book/book8/editbook.ui</tt> is shown below.</p> <ol type=1><li><p>First we need to create a class variable to map author names to author id's. Click in the Members tab of the Object Explorer, then right click the Class Variables item and click <b>New</b>. Type in 'TQMap<TQString,int> authorMap;'.</p> <li><p>We now record the author id's in the<!-- index init() --> <tt>init()</tt> function.</p> <pre> void EditBookForm::init() @@ -389,7 +389,7 @@ bool createConnections() } } </pre> -</ol><!-- index Databases!Foreign Keys --><!-- index Foreign Keys --> <p>Another approach which is especially useful if the same foreign key lookups are retquired in different parts of the application is to subclass a cursor and use this for our lookups. This is described in the <a href="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>, particulary the section on subclassing <a href="qsqlcursor.html">TQSqlCursor</a>.</p> +</ol><!-- index Databases!Foreign Keys --><!-- index Foreign Keys --> <p>Another approach which is especially useful if the same foreign key lookups are required in different parts of the application is to subclass a cursor and use this for our lookups. This is described in the <a href="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>, particulary the section on subclassing <a href="qsqlcursor.html">TQSqlCursor</a>.</p> <p>The 'book' example demonstrates the basic techniques needed for SQL programming with TQt. Additional information on the TQt SQL classes, especially the <a href="qsqlquery.html">TQSqlQuery</a> and <a href="qsqlcursor.html">TQSqlCursor</a> classes is provided in the <a href="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>.</p> <!-- eof --> <p align="right">[<a href="designer-manual-7.html">Prev: Creating Custom Widgets</a>] [<a href="designer-manual.html">Home</a>] [<a href="designer-manual-9.html">Next: Customizing and Integrating TQt Designer</a>]</p> |