diff options
Diffstat (limited to 'doc/sql.doc')
| -rw-r--r-- | doc/sql.doc | 348 |
1 files changed, 174 insertions, 174 deletions
diff --git a/doc/sql.doc b/doc/sql.doc index 9754cf178..9542f4aff 100644 --- a/doc/sql.doc +++ b/doc/sql.doc @@ -80,26 +80,26 @@ This module is part of the \link commercialeditions.html TQt Enterprise Edition \table \row -\i \l QSql -\i \l QSqlCursor -\i \l QSqlDatabase -\i \l QSqlDriver -\i \l QSqlDriverPlugin +\i \l TQSql +\i \l TQSqlCursor +\i \l TQSqlDatabase +\i \l TQSqlDriver +\i \l TQSqlDriverPlugin \row -\i \l QSqlEditorFactory -\i \l QSqlError -\i \l QSqlField -\i \l QSqlFieldInfo -\i \l QSqlForm +\i \l TQSqlEditorFactory +\i \l TQSqlError +\i \l TQSqlField +\i \l TQSqlFieldInfo +\i \l TQSqlForm \row -\i \l QSqlIndex -\i \l QSqlPropertyMap -\i \l QSqlQuery -\i \l QSqlRecord -\i \l QSqlRecordInfo +\i \l TQSqlIndex +\i \l TQSqlPropertyMap +\i \l TQSqlQuery +\i \l TQSqlRecord +\i \l TQSqlRecordInfo \row -\i \l QSqlResult -\i \l QSqlSelectCursor +\i \l TQSqlResult +\i \l TQSqlSelectCursor \i31 See also: \link sql-driver.html Supported Drivers\endlink \endtable @@ -114,7 +114,7 @@ your TQt applications. <blockquote> This overview assumes that you have at least a basic knowledge of SQL. You should be able to understand simple \c SELECT, \c INSERT, \c UPDATE -and \c DELETE commands. Although the \l QSqlCursor class provides an +and \c DELETE commands. Although the \l TQSqlCursor class provides an interface to database browsing and editing that does not \e require a knowledge of SQL, a basic understanding of SQL is highly recommended. A standard text covering SQL databases is \e {An Introduction to Database @@ -135,30 +135,30 @@ how the classes fit together. \link #Connecting_to_Databases Connecting to Databases \endlink. This section explains how to set up database connections using the \l -QSqlDatabase class. +TQSqlDatabase class. \link #Executing_SQL_commands Executing SQL Commands \endlink. This section demonstrates how to issue the standard data manipulation commands, \c SELECT, \c INSERT, \c UPDATE and \c DELETE on tables in the database (although any valid SQL statement can be sent to the database). The focus is purely on database interaction using \l -QSqlQuery. +TQSqlQuery. \link #Using_QSqlCursor Using Cursors \endlink. This section explains -how to use the QSqlCursor class which provides a simpler API than the -raw SQL used with \l QSqlQuery. +how to use the TQSqlCursor class which provides a simpler API than the +raw SQL used with \l TQSqlQuery. \link #Data-Aware_Widgets Data-Aware Widgets \endlink. This section shows how to programmatically link your database to the user interface. In -this section we introduce the \l QDataTable, \l QSqlForm, \l -QSqlPropertyMap and QSqlEditorFactory classes and demonstrate how to +this section we introduce the \l TQDataTable, \l TQSqlForm, \l +TQSqlPropertyMap and TQSqlEditorFactory classes and demonstrate how to use custom data-aware widgets. \link designer-manual.book Qt Designer\endlink provides an easy visual way of achieving the same thing. See the \link designer-manual.book TQt Designer\endlink manual, -\l QDataBrowser and \l QDataView for more information. +\l TQDataBrowser and \l TQDataView for more information. -\link #Subclassing_QSqlCursor Subclassing QSqlCursor \endlink. This -section gives examples of subclassing QSqlCursor. Subclassing can be +\link #Subclassing_QSqlCursor Subclassing TQSqlCursor \endlink. This +section gives examples of subclassing TQSqlCursor. Subclassing can be used to provide default and calculated values for fields (such as auto-numbered primary index fields), and to display calculated data, e.g. showing names rather than ids of foreign keys. @@ -173,25 +173,25 @@ The SQL classes are divided into three layers: \e {User Interface Layer.} These classes provide data-aware widgets that can be connected to tables or views in the database (by using a -QSqlCursor as a data source). End users can interact directly with +TQSqlCursor as a data source). End users can interact directly with these widgets to browse or edit data. \link designer-manual.book Qt Designer\endlink is fully integrated with the SQL classes and can be used to create data-aware forms. The data-aware widgets can also be programmed directly with your own C++ code. The classes that support -this layer include \l QSqlEditorFactory, \l QSqlForm, \l -QSqlPropertyMap, \l QDataTable, \l QDataBrowser and \l QDataView. +this layer include \l TQSqlEditorFactory, \l TQSqlForm, \l +TQSqlPropertyMap, \l TQDataTable, \l TQDataBrowser and \l TQDataView. \e {SQL API Layer.} These classes provide access to databases. -Connections are made using the \l QSqlDatabase class. Database -interaction is achieved either by using the QSqlQuery class and +Connections are made using the \l TQSqlDatabase class. Database +interaction is achieved either by using the TQSqlQuery class and executing SQL commands directly or by using the higher level \l -QSqlCursor class which composes SQL commands automatically. In -addition to \l QSqlDatabase, \l QSqlCursor and \l QSqlQuery, the SQL -API layer is supported by QSqlError, QSqlField, QSqlFieldInfo, -QSqlIndex, QSqlRecord and QSqlRecordInfo. +TQSqlCursor class which composes SQL commands automatically. In +addition to \l TQSqlDatabase, \l TQSqlCursor and \l TQSqlQuery, the SQL +API layer is supported by TQSqlError, TQSqlField, TQSqlFieldInfo, +TQSqlIndex, TQSqlRecord and TQSqlRecordInfo. -\e {Driver Layer.} This comprises three classes, \l QSqlResult, \l -QSqlDriver and QSqlDriverFactoryInterface. This layer provides the +\e {Driver Layer.} This comprises three classes, \l TQSqlResult, \l +TQSqlDriver and TQSqlDriverFactoryInterface. This layer provides the low level bridge between the database and the SQL classes. This layer is \link sql-driver.html documented separately \endlink since it is only relevant to driver writers, and is rarely used in standard @@ -208,21 +208,21 @@ The \link sql-driver.html SQL driver documentation\endlink describes how to build plugins for specific database management systems. Once a plugin is built, TQt will automatically load it, and the driver -will be available for use by QSqlDatabase (see QSqlDatabase::drivers() +will be available for use by TQSqlDatabase (see TQSqlDatabase::drivers() for more information). \target Connecting_to_Databases \section1 Connecting to Databases At least one database connection must be created and opened before the -\l QSqlQuery or \l QSqlCursor classes can be used. +\l TQSqlQuery or \l TQSqlCursor classes can be used. If the application only needs a single database connection, the \l -QSqlDatabase class can create a connection which is used by default +TQSqlDatabase class can create a connection which is used by default for all SQL operations. If multiple database connections are required these can easily be set up. -\l QSqlDatabase requires the \c ntqsqldatabase.h header file. +\l TQSqlDatabase requires the \c tqsqldatabase.h header file. \target Connecting_to_a_Single_Database \section1 Connecting to a Single Database @@ -238,7 +238,7 @@ connection. \printline \caption From \l sql/overview/connect1/main.cpp -First we activate the driver by calling \l QSqlDatabase::addDatabase(), +First we activate the driver by calling \l TQSqlDatabase::addDatabase(), passing the name of the driver we wish to use for this connection. At the time of writing the available drivers are: QODBC3 (Open Database Connectivity, includes Microsoft SQL Server support), QOCI8 (Oracle 8 and 9), @@ -259,13 +259,13 @@ Source Name (DSN) should be used in the setDatabaseName() call. Third we call open() to open the database and give us access to the data. If this call fails it will return FALSE; error information can -be obtained from \l QSqlDatabase::lastError(). +be obtained from \l TQSqlDatabase::lastError(). \target Connecting_to_Multiple_Databases \section2 Connecting to Multiple Databases Connecting to multiple databases is achieved using the two argument form -of \l QSqlDatabase::addDatabase() where the second argument is a unique +of \l TQSqlDatabase::addDatabase() where the second argument is a unique identifier distinguishing the connection. In the example below we have moved the connections into their own @@ -307,7 +307,7 @@ createConnections() function.cpp. \printline \caption From \l sql/overview/create_connections/main.cpp -The static function \l QSqlDatabase::database() can be called from +The static function \l TQSqlDatabase::database() can be called from anywhere to provide a pointer to a database connection. If we call it without a parameter it will return the default connection. If called with the identifier we've used for a connection, e.g. "ORACLE", in the @@ -321,36 +321,36 @@ will not run unless you implement your own database connections function. Note that in the code above the ODBC connection was not named and is -therefore used as the default connection. \l QSqlDatabase maintains +therefore used as the default connection. \l TQSqlDatabase maintains ownership of the pointers returned by the addDatabase() static function. To remove a database from the list of maintained -connections, first close the database with QSqlDatabase::close(), and +connections, first close the database with TQSqlDatabase::close(), and then remove it using the static function -QSqlDatabase::removeDatabase(). +TQSqlDatabase::removeDatabase(). \target Executing_SQL_commands -\section1 Executing SQL Commands Using QSqlQuery +\section1 Executing SQL Commands Using TQSqlQuery -The \l QSqlQuery class provides an interface for executing SQL commands. +The \l TQSqlQuery class provides an interface for executing SQL commands. It also has functions for navigating through the result sets of \c SELECT queries and for retrieving individual records and field values. -The \l QSqlCursor class described in the next section inherits from \l -QSqlQuery and provides a higher level interface that composes SQL -commands for us. \l QSqlCursor is particularly easy to integrate with +The \l TQSqlCursor class described in the next section inherits from \l +TQSqlQuery and provides a higher level interface that composes SQL +commands for us. \l TQSqlCursor is particularly easy to integrate with on-screen widgets. Programmers unfamiliar with SQL can safely skip this -section and use the \l QSqlCursor class covered in -\link #Using_QSqlCursor "Using QSqlCursor" \endlink. +section and use the \l TQSqlCursor class covered in +\link #Using_QSqlCursor "Using TQSqlCursor" \endlink. \target Transactions \section2 Transactions If the underlying database engine supports transactions -QSqlDriver::hasFeature( QSqlDriver::Transactions ) will return TRUE. -You can use QSqlDatabase::transaction() to initiate a transaction, +TQSqlDriver::hasFeature( TQSqlDriver::Transactions ) will return TRUE. +You can use TQSqlDatabase::transaction() to initiate a transaction, followed by the SQL commands you want to execute within the context of -the transaction, and then either QSqlDatabase::commit() or -\l{QSqlDatabase::rollback()}. +the transaction, and then either TQSqlDatabase::commit() or +\l{TQSqlDatabase::rollback()}. \target Basic_Browsing \section2 Basic Browsing @@ -363,7 +363,7 @@ the transaction, and then either QSqlDatabase::commit() or \caption From \l sql/overview/basicbrowsing/main.cpp In the example above we've added an additional header file, -\c ntqsqlquery.h. The first query we create, \c target, uses the default +\c tqsqlquery.h. The first query we create, \c target, uses the default database and is initially empty. For the second query, \c q, we specify the "ORACLE" database that we want to retrieve records from. Both the database connections were set up in the createConnections() function we @@ -374,7 +374,7 @@ to see if the query executed successfully. The next() function is used to iterate through the query results. The value() function returns the contents of fields as QVariants. The insertions are achieved by creating and executing queries against the default -database using the \c target QSqlQuery. +database using the \c target TQSqlQuery. Note that this example and all the other examples in this document use the tables defined in the \link #Example_Tables Example Tables\endlink @@ -405,7 +405,7 @@ cannot be determined, e.g. if the query fails. This example demonstrates straightforward SQL DML (data manipulation language) commands. Since we did not specify a database in the \l -QSqlQuery constructor the default database is used. \l QSqlQuery objects +TQSqlQuery constructor the default database is used. \l TQSqlQuery objects can also be used to execute SQL DDL (data definition language) commands such as \c{CREATE TABLE} and \c{CREATE INDEX}. @@ -415,7 +415,7 @@ such as \c{CREATE TABLE} and \c{CREATE INDEX}. Once a \c SELECT query has been executed successfully we have access to the result set of records that matched the query criteria. We have already used one of the navigation functions, next(), which can be -used alone to step sequentially through the records. \l QSqlQuery also +used alone to step sequentially through the records. \l TQSqlQuery also provides first(), last() and prev(). After any of these commands we can check that we are on a valid record by calling isValid(). @@ -437,12 +437,12 @@ Not all drivers support size(), but we can interrogate the driver to find out: \code - QSqlDatabase* defaultDB = QSqlDatabase::database(); - if ( defaultDB->driver()->hasFeature( QSqlDriver::QuerySize ) ) { - // QSqlQuery::size() supported + TQSqlDatabase* defaultDB = TQSqlDatabase::database(); + if ( defaultDB->driver()->hasFeature( TQSqlDriver::QuerySize ) ) { + // TQSqlQuery::size() supported } else { - // QSqlQuery::size() cannot be relied upon + // TQSqlQuery::size() cannot be relied upon } \endcode @@ -468,52 +468,52 @@ executed. This can be useful to check that the query you think is being executed is the one actually being executed. \target Using_QSqlCursor -\section1 Using QSqlCursor +\section1 Using TQSqlCursor -The \l QSqlCursor class provides a high level interface to browsing and +The \l TQSqlCursor class provides a high level interface to browsing and editing records in SQL database tables or views without the need to write your own SQL. -QSqlCursor can do almost everything that QSqlQuery can, with two +TQSqlCursor can do almost everything that TQSqlQuery can, with two exceptions. Since cursors represent tables or views within the -database, by default, \l QSqlCursor objects retrieve all the fields of +database, by default, \l TQSqlCursor objects retrieve all the fields of each record in the table or view whenever navigating to a new record. If only some fields are relevant simply confine your processing to those and ignore the others. Or, manually disable the -generation of certain fields using QSqlRecord::setGenerated(). Another +generation of certain fields using TQSqlRecord::setGenerated(). Another approach is to create a \c VIEW which only presents the fields you're interested in; but note that some databases do not support editable views. So if you really don't want to retrieve all the fields in the -cursor, then you should use a \l QSqlQuery instead, and customize the -query to suit your needs. You can edit records using a \l QSqlCursor +cursor, then you should use a \l TQSqlQuery instead, and customize the +query to suit your needs. You can edit records using a \l TQSqlCursor providing that the table or view has a primary index that uniquely distinguishes each record. If this condition is not met then you'll -need to use a \l QSqlQuery for edits. +need to use a \l TQSqlQuery for edits. -QSqlCursor operates on a single record at a time. Whenever performing -an insert, update or delete using QSqlCursor, only a single record in +TQSqlCursor operates on a single record at a time. Whenever performing +an insert, update or delete using TQSqlCursor, only a single record in the database is affected. When navigating through records in the cursor, only one record at a time is available in application code. -In addition, QSqlCursor maintains a separate 'edit buffer' which is +In addition, TQSqlCursor maintains a separate 'edit buffer' which is used to make changes to a single record in the database. The edit buffer is maintained in a separate memory area, and is unnaffected by the 'navigation buffer' which changes as the cursor moves from record to record. -Before we can use \l QSqlCursor objects we must first create and open +Before we can use \l TQSqlCursor objects we must first create and open a database connection. Connecting is described in the \link #Connecting_to_Databases Connecting to Databases \endlink section above. For the examples that follow we will assume that the connections have been created using the createConnections() function -defined in the \link #create_connections QSqlDatabase example \endlink +defined in the \link #create_connections TQSqlDatabase example \endlink presented earlier. In the \link #Data-Aware_Widgets data-aware widgets \endlink section that follows this one we show how to link widgets to database cursors. Once we have a knowledge of both cursors and data-aware widgets we can -discuss \link #Subclassing_QSqlCursor subclassing QSqlCursor \endlink. +discuss \link #Subclassing_QSqlCursor subclassing TQSqlCursor \endlink. -The \l QSqlCursor class requires the \c ntqsqlcursor.h header file. +The \l TQSqlCursor class requires the \c tqsqlcursor.h header file. \target Retrieving_Records \section2 Retrieving Records @@ -525,9 +525,9 @@ The \l QSqlCursor class requires the \c ntqsqlcursor.h header file. \printline \caption From \l sql/overview/retrieve2/main.cpp -We create the \l QSqlCursor object, specifying the table or view to use. +We create the \l TQSqlCursor object, specifying the table or view to use. If we need to use a database other than the default we can specify it -in the QSqlCursor constructor. +in the TQSqlCursor constructor. The SQL executed by the cur.select() call is @@ -537,7 +537,7 @@ The SQL executed by the cur.select() call is Next, we iterate through the records returned by this select statement using cur.next(). Field values are retrieved in in a similar way to -QSqlQuery, except that we pass field names rather than numeric indexes +TQSqlQuery, except that we pass field names rather than numeric indexes to value() and setValue(). \target Sorting_Data @@ -562,16 +562,16 @@ This will retrieve only those staff whose \c id is greater than 100. In addition to retrieving selected records we often want to specify a sort order for the returned records. This is achieved by creating a \l -QSqlIndex object which contains the names of the field(s) we wish to +TQSqlIndex object which contains the names of the field(s) we wish to sort by and pass this object to the select() call. \code - QSqlCursor cur( "staff" ); - QSqlIndex nameIndex = cur.index( "surname" ); + TQSqlCursor cur( "staff" ); + TQSqlIndex nameIndex = cur.index( "surname" ); cur.select( nameIndex ); \endcode -Here we create a \l QSqlIndex object with one field, "surname". When +Here we create a \l TQSqlIndex object with one field, "surname". When we call the select() function we pass the index object, which specifies that the records should be returned sorted by staff.surname. Each field in the index object is used in the ORDER BY @@ -588,7 +588,7 @@ is straightforward. cur.select( "staff.surname LIKE 'A%'", nameIndex ); \endcode -We pass in a filter string (the \c WHERE clause), and the \l QSqlIndex +We pass in a filter string (the \c WHERE clause), and the \l TQSqlIndex object to sort by (the \c{ORDER BY} clause). This produces \code @@ -598,16 +598,16 @@ object to sort by (the \c{ORDER BY} clause). This produces To sort by more than one field, an index can be created which contains multiple fields. Ascending and descending order can be set using -QSqlIndex::setDescending(); the default is ascending. +TQSqlIndex::setDescending(); the default is ascending. \quotefile sql/overview/order1/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil while \caption From \l sql/overview/order1/main.cpp Here we create a string list containing the fields we wish to sort by, -in the order they are to be used. Then we create a \l QSqlIndex object +in the order they are to be used. Then we create a \l TQSqlIndex object based on these fields, finally executing the select() call using this index. This executes \code @@ -619,8 +619,8 @@ If we need to retrieve records with fields that match specific criteria we can create a filter based on an index. \quotefile sql/overview/order2/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil while \caption From \l sql/overview/order2/main.cpp @@ -630,8 +630,8 @@ This executes FROM staff WHERE staff.surname='Bloggs' ORDER BY staff.id ASC, staff.forename ASC \endcode -The "order" \l QSqlIndex contains two fields, "id" and "forename" -which are used to order the results. The "filter" \l QSqlIndex +The "order" \l TQSqlIndex contains two fields, "id" and "forename" +which are used to order the results. The "filter" \l TQSqlIndex contains a single field, "surname". When an index is passed as a filter to the select() function, for each field in the filter, a \e{fieldname=value} subclause is created where the value @@ -642,14 +642,14 @@ setValue() to ensure that the value used is the one we want. \section3 Extracting Data \quotefile sql/overview/extract/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil tqDebug \printline \caption From \l sql/overview/extract/main.cpp In this example we begin by creating a cursor on the creditors table. -We create two \l QSqlIndex objects. The first, "order", is created +We create two \l TQSqlIndex objects. The first, "order", is created from the "orderFields" string list. The second, "filter", is created from the "filterFields" string list. We set the values of the two fields used in the filter, "surname" and "city", to the values we're @@ -674,9 +674,9 @@ some processing function, in this example a simple tqDebug() call. \section2 Manipulating Records Records can be inserted, updated or deleted in a table or view using a -\l QSqlCursor providing that the table or view has a primary index +\l TQSqlCursor providing that the table or view has a primary index that uniquely distinguishes each record. If this is not the case a \l -QSqlQuery must be used instead. (Note that not all databases support +TQSqlQuery must be used instead. (Note that not all databases support editable views.) Each cursor has an internal 'edit buffer' which is used by all the @@ -687,7 +687,7 @@ insert() or update() or del() to perform the desired operation. For example, when inserting a record using a cursor, you call primeInsert() to get a pointer to the edit buffer and then call setValue() on this buffer to set each field's value. Then you call -QSQlCursor::insert() to insert the contents of the edit buffer into +TQSQlCursor::insert() to insert the contents of the edit buffer into the database. Similarly, when updating (or deleting) a record, the values of the fields in the edit buffer are used to update (or delete) the record in the database. The 'edit buffer' is unaffected by any @@ -699,16 +699,16 @@ quote is a special character in SQL. The primeInsert(), primeUpdate() and primeDelete() methods all return a pointer to the internal edit buffer. Each method can potentially perform different operations on the edit buffer before returning it. -By default, QSqlCursor::primeInsert() clears all the field values in -the edit buffer (see \l QSqlRecord::clearValues()). Both \l -QSqlCursor::primeUpdate() and QSqlCursor::primeDelete() initialize the +By default, TQSqlCursor::primeInsert() clears all the field values in +the edit buffer (see \l TQSqlRecord::clearValues()). Both \l +TQSqlCursor::primeUpdate() and TQSqlCursor::primeDelete() initialize the edit buffer with the current contents of the cursor before returning it. All three of these functions are virtual, so you can redefine the behavior (for example, reimplementing primeInsert() to auto-number fields in the edit buffer). Data-aware user-interface controls emit signals, e.g. primeInsert(), that you can connect to; these pass a pointer to the appropriate buffer so subclassing may not be necessary. -See \link #Subclassing_QSqlCursor subclassing QSqlCursor \endlink for +See \link #Subclassing_QSqlCursor subclassing TQSqlCursor \endlink for more information on subclassing; see the \link designer-manual.book Qt Designer\endlink manual for more on connecting to the primeInsert() signal. @@ -723,33 +723,33 @@ changes to the database are accurately reflected in the cursor. \section3 Inserting Records \quotefile sql/overview/insert/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil } \caption From \l sql/overview/insert/main.cpp In this example we create a cursor on the "prices" table. Next we create a list of product names which we iterate over. For each iteration we call the cursor's primeInsert() method. This method -returns a pointer to a \l QSqlRecord buffer in which all the fields -are set to \c NULL. (Note that QSqlCursor::primeInsert() is virtual, -and can be customized by derived classes. See \l QSqlCursor). Next we +returns a pointer to a \l TQSqlRecord buffer in which all the fields +are set to \c NULL. (Note that TQSqlCursor::primeInsert() is virtual, +and can be customized by derived classes. See \l TQSqlCursor). Next we call setValue() for each field that requires a value. Finally we call insert() to insert the record. The insert() call returns the number of rows inserted. -We obtained a pointer to a \l QSqlRecord object from the primeInsert() -call. QSqlRecord objects can hold the data for a single record plus some +We obtained a pointer to a \l TQSqlRecord object from the primeInsert() +call. TQSqlRecord objects can hold the data for a single record plus some meta-data about the record. In practice most interaction with a -QSqlRecord consists of simple value() and setValue() calls as shown in +TQSqlRecord consists of simple value() and setValue() calls as shown in this and the following example. \target Updating_Records \section3 Updating Records \quotefile sql/overview/update/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil update \printline \caption From \l sql/overview/update/main.cpp @@ -757,7 +757,7 @@ this and the following example. This example begins with the creation of a cursor over the prices table. We select the record we wish to update with the select() call and move to it with the next() call. We call primeUpdate() to get a \l -QSqlRecord pointer to a buffer which is populated with the contents of +TQSqlRecord pointer to a buffer which is populated with the contents of the current record. We retrieve the value of the price field, calculate a new price, and set the the price field to the newly calculated value. Finally we call update() to update the record. The update() call returns @@ -765,32 +765,32 @@ the number of rows updated. If many identical updates need to be performed, for example increasing the price of every item in the price list, using a single SQL statement -with \l QSqlQuery is more efficient, e.g. +with \l TQSqlQuery is more efficient, e.g. \code - QSqlQuery query( "UPDATE prices SET price = price * 1.05" ); + TQSqlQuery query( "UPDATE prices SET price = price * 1.05" ); \endcode \target Deleting_Records \section3 Deleting Records \quotefile sql/overview/delete/main.cpp -\skipto QSqlCursor -\printline QSqlCursor +\skipto TQSqlCursor +\printline TQSqlCursor \printuntil del \caption From \l sql/overview/delete/main.cpp To delete records, select the record to be deleted and navigate to it. Then call primeDelete() to populate the cursor with the primary key of the selected record, (in this example, the \c prices.id field), and -then call QSqlCursor::del() to delete it. +then call TQSqlCursor::del() to delete it. As with update(), if multiple deletions need to be made with some common criteria it is more efficient to do so using a single SQL statement, e.g. \code - QSqlQuery query( "DELETE FROM prices WHERE id >= 2450 AND id <= 2500" ); + TQSqlQuery query( "DELETE FROM prices WHERE id >= 2450 AND id <= 2500" ); \endcode \target Data-Aware_Widgets @@ -815,14 +815,14 @@ examples provides additional information. \printline \caption From \l sql/overview/table1/main.cpp -Data-Aware tables require the \c ntqdatatable.h and \c ntqsqlcursor.h header +Data-Aware tables require the \c tqdatatable.h and \c tqsqlcursor.h header files. We create our application object, call createConnections() and -create the cursor. We create the \l QDataTable passing it a pointer to +create the cursor. We create the \l TQDataTable passing it a pointer to the cursor, and set the autoPopulate flag to TRUE. Next we make our \l -QDataTable the main widget and call refresh() to populate it with data +TQDataTable the main widget and call refresh() to populate it with data and call show() to make it visible. -The autoPopulate flag tells the \l QDataTable whether or nor it should +The autoPopulate flag tells the \l TQDataTable whether or nor it should create columns based on the cursor. autoPopulate does not affect the loading of data into the table; that is achieved by the refresh() function. @@ -833,7 +833,7 @@ function. \printuntil show \caption From \l sql/overview/table2/main.cpp -We create an empty \l QDataTable which we make into our main widget and +We create an empty \l TQDataTable which we make into our main widget and then we manually add the columns we want in the order we wish them to appear. For each column we specify the field name and optionally a display label. @@ -844,7 +844,7 @@ been achieved by applying the sort to the cursor itself. Once everything is set up we call refresh() to load the data from the database and show() to make the widget visible. -QDataTables only retrieve visible rows which (depending on the driver) +TQDataTables only retrieve visible rows which (depending on the driver) allows even large tables to be displayed very quickly with minimal memory cost. @@ -868,8 +868,8 @@ designer-manual.book TQt Designer\endlink manual for more details. \caption From \l sql/overview/form1/main.cpp We include the header files for the widgets that we need. We also -include \c ntqsqldatabase.h and \c ntqsqlcursor.h as usual, but we now add -\c ntqsqlform.h. +include \c tqsqldatabase.h and \c tqsqlcursor.h as usual, but we now add +\c tqsqlform.h. The form will be presented as a dialog so we subclass \l QDialog with our own FormDialog class. We use a \l QLineEdit for the salary so that @@ -878,23 +878,23 @@ the user can change it. All the widgets are laid out using a grid. We create a cursor on the staff table, select all records and move to the first record. -Now we create a \l QSqlForm object and set the QSqlForm's record buffer +Now we create a \l TQSqlForm object and set the TQSqlForm's record buffer to the cursor's update buffer. For each widget that we wish to make data-aware we insert a pointer to the widget and the associated field -name into the \l QSqlForm. Finally we call readFields() to populate the +name into the \l TQSqlForm. Finally we call readFields() to populate the widgets with data from the database via the cursor's buffer. \target Displaying_a_Record_in_a_DataForm \section3 Displaying a Record in a Data Form -\l QDataView is a Widget that can hold a read-only \l QSqlForm. In -addition to \l QSqlForm it offers the slot refresh( \l QSqlRecord * ) so it -can easily be linked together with a \l QDataTable to display a detailed +\l TQDataView is a Widget that can hold a read-only \l TQSqlForm. In +addition to \l TQSqlForm it offers the slot refresh( \l TQSqlRecord * ) so it +can easily be linked together with a \l TQDataTable to display a detailed view of a record: \code - connect( myDataTable, TQ_SIGNAL( currentChanged( QSqlRecord* ) ), - myDataView, TQ_SLOT( refresh( QSqlRecord* ) ) ); + connect( myDataTable, TQ_SIGNAL( currentChanged( TQSqlRecord* ) ), + myDataView, TQ_SLOT( refresh( TQSqlRecord* ) ) ); \endcode \target Editing_a_Record @@ -910,8 +910,8 @@ differences. \caption From \l sql/overview/form2/main.h The save slot will be used for a button that the user can press to -confirm their update. We also hold pointers to the \l QSqlCursor and the -\l QSqlForm since they will need to be accessed outside the constructor. +confirm their update. We also hold pointers to the \l TQSqlCursor and the +\l TQSqlForm since they will need to be accessed outside the constructor. \quotefile sql/overview/form2/main.cpp \skipto setTrimmed @@ -946,14 +946,14 @@ We add an extra row to the grid containing the save button. \printline staffCursor \printuntil first -We create a \l QSqlIndex object and then execute a select() using the +We create a \l TQSqlIndex object and then execute a select() using the index. We then move to the first record in the result set. -\skipto new QSqlForm +\skipto new TQSqlForm \printline \printline -We create a new QSqlForm object and set it's record buffer to the +We create a new TQSqlForm object and set it's record buffer to the cursor's update buffer. \skipto insert @@ -968,7 +968,7 @@ populated by the readFields() call as before. \printline FormDialog:: \printuntil } -In the destructor we don't have to worry about the widgets or QSqlForm +In the destructor we don't have to worry about the widgets or TQSqlForm since they are children of the form and will be deleted by TQt at the right time. @@ -978,16 +978,16 @@ right time. Finally we add the save functionality for when the user presses the save button. We write back the data from the widgets to the \l -QSqlRecord buffer with the writeFields() call. Then we update the +TQSqlRecord buffer with the writeFields() call. Then we update the database with the updated version of the record with the cursor's update() function. At this point the cursor is no longer positioned at -a valid record so we reissue the select() call using our \l QSqlIndex +a valid record so we reissue the select() call using our \l TQSqlIndex and move to the first record. -QDataBrowser and QDataView are widgets which provide a great deal of -the above functionality. \l QDataBrowser provides a data form which +TQDataBrowser and TQDataView are widgets which provide a great deal of +the above functionality. \l TQDataBrowser provides a data form which allows editing of and navigation through a cursor's records. \l -QDataView provides a read only form for data in a cursor or database +TQDataView provides a read only form for data in a cursor or database record. See the class documentation or the \link designer-manual.book Qt Designer\endlink manual for more information on using these widgets. @@ -997,7 +997,7 @@ Link to \l sql/overview/form2/main.cpp \target Custom_Editor_Widgets \section2 Custom Editor Widgets -QSqlForm uses QSqlPropertyMap to handle the transfer of data between +TQSqlForm uses TQSqlPropertyMap to handle the transfer of data between widgets and database fields. Custom widgets can also be used in a form by installing a property map that contains information about the properties of the custom widget which should be used to transfer the @@ -1066,14 +1066,14 @@ Laying out the grid and setting up the cursor is the same as before. We create a new property map on the heap and register our CustomEdit class and its upperLine property with the property map. -\skipto QSqlForm -\printline QSqlForm +\skipto TQSqlForm +\printline TQSqlForm \printline \printline propMap -The final change is to install the property map into the QSqlForm once -the QSqlForm has been created. This passes responsibility for the -property map's memory to QSqlForm which itself is owned by the +The final change is to install the property map into the TQSqlForm once +the TQSqlForm has been created. This passes responsibility for the +property map's memory to TQSqlForm which itself is owned by the FormDialog, so TQt will delete them at the right time. The behaviour of this example is identical to the previous one except @@ -1083,9 +1083,9 @@ our CustomEdit widget. \target Custom_Editor_Widgets_for_Tables \section3 Custom Editor Widgets for Tables -We must reimpliment QSqlEditorFactory to use custom editor widgets in +We must reimpliment TQSqlEditorFactory to use custom editor widgets in tables. In the following example we will create a custom editor based -on QComboBox and a QSqlEditorFactory subclass to show how a QDataTable +on QComboBox and a TQSqlEditorFactory subclass to show how a TQDataTable can use a custom editor. \quotefile sql/overview/table3/main.h @@ -1103,7 +1103,7 @@ to/from the statusids that we will list in the combobox. \printline CustomSqlEditor \printuntil }; -We also need to subclass QSqlEditorFactory declaring a createEditor() +We also need to subclass TQSqlEditorFactory declaring a createEditor() function since that is the only function we need to reimplement. \quotefile sql/overview/table3/main.cpp @@ -1141,11 +1141,11 @@ the id parameter's value. If we have a match we set the combobox's current item to the index2id element's key (the combobox index), and leave the loop. -When the user edits the status field in the QDataTable they will be +When the user edits the status field in the TQDataTable they will be presented with a combobox of valid status names taken from the status table. However the status displayed is still the raw statusid. To display the status name when the field isn't being edited requires us -to subclass QDataTable and reimplement the paintField() function. +to subclass TQDataTable and reimplement the paintField() function. \quotefile sql/overview/table4/main.h \skipto CustomTable @@ -1153,25 +1153,25 @@ to subclass QDataTable and reimplement the paintField() function. \printuntil }; \caption From \l sql/overview/table4/main.h -We simply call the original QDataTable constructor without changing +We simply call the original TQDataTable constructor without changing anything. We also declare the paintField function. \quotefile sql/overview/table4/main.cpp \skipto CustomTable \printline CustomTable -\printuntil QDataTable +\printuntil TQDataTable \printline \caption From \l sql/overview/table4/main.cpp -The paintField code is based on QDataTable's source code. We need to +The paintField code is based on TQDataTable's source code. We need to make three changes. Firstly add an if clause \c{field->name() == "statusid"} and look up the textual value for the id with a -straighforward QSqlQuery. Secondly call the superclass to handle other +straighforward TQSqlQuery. Secondly call the superclass to handle other fields. The last change is in our main function where we change -staffTable from being a QDataTable to being a CustomTable. +staffTable from being a TQDataTable to being a CustomTable. \target Subclassing_QSqlCursor -\section1 Subclassing QSqlCursor +\section1 Subclassing TQSqlCursor \quotefile sql/overview/subclass1/main.cpp \skipto include @@ -1181,7 +1181,7 @@ staffTable from being a QDataTable to being a CustomTable. \caption From \l sql/overview/subclass1/main.cpp This example is very similar to the table1 example presented earlier. We -create a cursor, add the fields and their display labels to a QDataTable, +create a cursor, add the fields and their display labels to a TQDataTable, call refresh() to load the data and call show() to show the widget. Unfortunately this example is unsatisfactory. It is tedious to set the @@ -1199,7 +1199,7 @@ the values when the user adds a new record. \printuntil }; \caption From \l sql/overview/subclass2/main.h -We have created a separate header file and subclassed QSqlCursor. +We have created a separate header file and subclassed TQSqlCursor. \quotefile sql/overview/subclass2/main.cpp \skipto InvoiceItem @@ -1207,7 +1207,7 @@ We have created a separate header file and subclassed QSqlCursor. \printuntil } \caption From \l sql/overview/subclass2/main.cpp -In our class's constructor we call the QSqlCursor constructor with the +In our class's constructor we call the TQSqlCursor constructor with the name of the table. We don't have any other characteristics to add at this stage. @@ -1215,7 +1215,7 @@ this stage. \printline InvoiceItemCursor Whenever we require a cursor over the invoiceitem table we can create -an InvoiceItemCursor instead of a generic QSqlCursor. +an InvoiceItemCursor instead of a generic TQSqlCursor. We still need to show the product name rather than the pricesid. @@ -1236,7 +1236,7 @@ of the calculateField() function since we will be reimplementing it. \caption From \l sql/overview/subclass3/main.cpp We have changed the InvoiceItemCursor constructor. We now create a new -QSqlField called productname and append this to the +TQSqlField called productname and append this to the InvoiceItemCursor's set of fields. We call setCalculated() on productname to identify it as a calculated field. The first argument to setCalculated() is the field name, the second a bool which if TRUE |