source: trunk/doc/html/qsqlcursor.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 49.9 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/sql/qsqlcursor.cpp:122 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QSqlCursor Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSqlCursor Class Reference<br><small>[<a href="sql.html">sql module</a>]</small></h1>
33
34<p>The QSqlCursor class provides browsing and editing of SQL
35tables and views.
36<a href="#details">More...</a>
37<p><tt>#include &lt;<a href="qsqlcursor-h.html">qsqlcursor.h</a>&gt;</tt>
38<p>Inherits <a href="qsqlrecord.html">QSqlRecord</a> and <a href="qsqlquery.html">QSqlQuery</a>.
39<p>Inherited by <a href="qsqlselectcursor.html">QSqlSelectCursor</a>.
40<p><a href="qsqlcursor-members.html">List of all member functions.</a>
41<h2>Public Members</h2>
42<ul>
43<li class=fn><a href="#QSqlCursor"><b>QSqlCursor</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name = QString::null, bool&nbsp;autopopulate = TRUE, QSqlDatabase&nbsp;*&nbsp;db = 0 )</li>
44<li class=fn><a href="#QSqlCursor-2"><b>QSqlCursor</b></a> ( const&nbsp;QSqlCursor&nbsp;&amp;&nbsp;other )</li>
45<li class=fn>QSqlCursor &amp; <a href="#operator-eq"><b>operator=</b></a> ( const&nbsp;QSqlCursor&nbsp;&amp;&nbsp;other )</li>
46<li class=fn><a href="#~QSqlCursor"><b>~QSqlCursor</b></a> ()</li>
47<li class=fn>enum <a href="#Mode-enum"><b>Mode</b></a> { ReadOnly = 0, Insert = 1, Update = 2, Delete = 4, Writable = 7 }</li>
48<li class=fn>virtual QSqlIndex <a href="#primaryIndex"><b>primaryIndex</b></a> ( bool&nbsp;setFromCursor = TRUE ) const</li>
49<li class=fn>virtual QSqlIndex <a href="#index"><b>index</b></a> ( const&nbsp;QStringList&nbsp;&amp;&nbsp;fieldNames ) const</li>
50<li class=fn>QSqlIndex <a href="#index-2"><b>index</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;fieldName ) const</li>
51<li class=fn>QSqlIndex <a href="#index-3"><b>index</b></a> ( const&nbsp;char&nbsp;*&nbsp;fieldName ) const</li>
52<li class=fn>virtual void <a href="#setPrimaryIndex"><b>setPrimaryIndex</b></a> ( const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;idx )</li>
53<li class=fn>virtual void <a href="#append"><b>append</b></a> ( const&nbsp;QSqlFieldInfo&nbsp;&amp;&nbsp;fieldInfo )</li>
54<li class=fn>virtual void <a href="#insert"><b>insert</b></a> ( int&nbsp;pos, const&nbsp;QSqlFieldInfo&nbsp;&amp;&nbsp;fieldInfo )</li>
55<li class=fn>virtual void <a href="#remove"><b>remove</b></a> ( int&nbsp;pos )</li>
56<li class=fn>virtual void <a href="#clear"><b>clear</b></a> ()</li>
57<li class=fn>virtual void <a href="#setGenerated"><b>setGenerated</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, bool&nbsp;generated )</li>
58<li class=fn>virtual void <a href="#setGenerated-2"><b>setGenerated</b></a> ( int&nbsp;i, bool&nbsp;generated )</li>
59<li class=fn>virtual QSqlRecord * <a href="#editBuffer"><b>editBuffer</b></a> ( bool&nbsp;copy = FALSE )</li>
60<li class=fn>virtual QSqlRecord * <a href="#primeInsert"><b>primeInsert</b></a> ()</li>
61<li class=fn>virtual QSqlRecord * <a href="#primeUpdate"><b>primeUpdate</b></a> ()</li>
62<li class=fn>virtual QSqlRecord * <a href="#primeDelete"><b>primeDelete</b></a> ()</li>
63<li class=fn>virtual int <a href="#insert-2"><b>insert</b></a> ( bool&nbsp;invalidate = TRUE )</li>
64<li class=fn>virtual int <a href="#update"><b>update</b></a> ( bool&nbsp;invalidate = TRUE )</li>
65<li class=fn>virtual int <a href="#del"><b>del</b></a> ( bool&nbsp;invalidate = TRUE )</li>
66<li class=fn>virtual void <a href="#setMode"><b>setMode</b></a> ( int&nbsp;mode )</li>
67<li class=fn>int <a href="#mode"><b>mode</b></a> () const</li>
68<li class=fn>virtual void <a href="#setCalculated"><b>setCalculated</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, bool&nbsp;calculated )</li>
69<li class=fn>bool <a href="#isCalculated"><b>isCalculated</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name ) const</li>
70<li class=fn>virtual void <a href="#setTrimmed"><b>setTrimmed</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, bool&nbsp;trim )</li>
71<li class=fn>bool <a href="#isTrimmed"><b>isTrimmed</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name ) const</li>
72<li class=fn>bool <a href="#isReadOnly"><b>isReadOnly</b></a> () const</li>
73<li class=fn>bool <a href="#canInsert"><b>canInsert</b></a> () const</li>
74<li class=fn>bool <a href="#canUpdate"><b>canUpdate</b></a> () const</li>
75<li class=fn>bool <a href="#canDelete"><b>canDelete</b></a> () const</li>
76<li class=fn>bool <a href="#select-2"><b>select</b></a> ()</li>
77<li class=fn>bool <a href="#select-3"><b>select</b></a> ( const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;sort )</li>
78<li class=fn>bool <a href="#select-4"><b>select</b></a> ( const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;filter, const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;sort )</li>
79<li class=fn>virtual bool <a href="#select"><b>select</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filter, const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;sort = QSqlIndex ( ) )</li>
80<li class=fn>virtual void <a href="#setSort"><b>setSort</b></a> ( const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;sort )</li>
81<li class=fn>QSqlIndex <a href="#sort"><b>sort</b></a> () const</li>
82<li class=fn>virtual void <a href="#setFilter"><b>setFilter</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filter )</li>
83<li class=fn>QString <a href="#filter"><b>filter</b></a> () const</li>
84<li class=fn>virtual void <a href="#setName"><b>setName</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, bool&nbsp;autopopulate = TRUE )</li>
85<li class=fn>QString <a href="#name"><b>name</b></a> () const</li>
86<li class=fn>bool <a href="#isNull"><b>isNull</b></a> ( int&nbsp;i ) const</li>
87<li class=fn>bool <a href="#isNull-2"><b>isNull</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name ) const</li>
88</ul>
89<h2>Protected Members</h2>
90<ul>
91<li class=fn>virtual QVariant <a href="#calculateField"><b>calculateField</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
92<li class=fn>virtual int <a href="#update-2"><b>update</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filter, bool&nbsp;invalidate = TRUE )</li>
93<li class=fn>virtual int <a href="#del-2"><b>del</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filter, bool&nbsp;invalidate = TRUE )</li>
94<li class=fn>virtual QString <a href="#toString-3"><b>toString</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;prefix, QSqlField&nbsp;*&nbsp;field, const&nbsp;QString&nbsp;&amp;&nbsp;fieldSep ) const</li>
95<li class=fn>virtual QString <a href="#toString"><b>toString</b></a> ( QSqlRecord&nbsp;*&nbsp;rec, const&nbsp;QString&nbsp;&amp;&nbsp;prefix, const&nbsp;QString&nbsp;&amp;&nbsp;fieldSep, const&nbsp;QString&nbsp;&amp;&nbsp;sep ) const</li>
96<li class=fn>virtual QString <a href="#toString-4"><b>toString</b></a> ( const&nbsp;QSqlIndex&nbsp;&amp;&nbsp;i, QSqlRecord&nbsp;*&nbsp;rec, const&nbsp;QString&nbsp;&amp;&nbsp;prefix, const&nbsp;QString&nbsp;&amp;&nbsp;fieldSep, const&nbsp;QString&nbsp;&amp;&nbsp;sep ) const</li>
97</ul>
98<hr><a name="details"></a><h2>Detailed Description</h2>
99
100
101The QSqlCursor class provides browsing and editing of SQL
102tables and views.
103<p>
104
105<p> A QSqlCursor is a database record (see <a href="qsqlrecord.html">QSqlRecord</a>) that
106corresponds to a table or view within an SQL database (see <a href="qsqldatabase.html">QSqlDatabase</a>). There are two buffers in a cursor, one used for
107browsing and one used for editing records. Each buffer contains a
108list of fields which correspond to the fields in the table or
109view.
110<p> When positioned on a valid record, the browse buffer contains the
111values of the current record's fields from the database. The edit
112buffer is separate, and is used for editing existing records and
113inserting new records.
114<p> For browsing data, a cursor must first <a href="#select">select</a>() data from the
115database. After a successful select() the cursor is active
116(<a href="qsqlquery.html#isActive">isActive</a>() returns TRUE), but is initially not positioned on a
117valid record (<a href="qsqlquery.html#isValid">isValid</a>() returns FALSE). To position the cursor on
118a valid record, use one of the navigation functions, <a href="qsqlquery.html#next">next</a>(),
119<a href="qsqlquery.html#prev">prev</a>(), <a href="qsqlquery.html#first">first</a>(), <a href="qsqlquery.html#last">last</a>(), or <a href="qsqlquery.html#seek">seek</a>(). Once positioned on a valid
120record, data can be retrieved from the browse buffer using
121<a href="qsqlquery.html#value">value</a>(). If a navigation function is not successful, it returns
122FALSE, the cursor will no longer be positioned on a valid record
123and the values returned by value() are undefined.
124<p> For example:
125<p>
126
127<pre> QSqlCursor cur( "staff" ); // Specify the table/view name
128 <a name="x2178"></a> cur.<a href="#select">select</a>(); // We'll retrieve every record
129 while ( cur.<a href="qsqlquery.html#next">next</a>() ) {
130 <a name="x2179"></a> <a href="qapplication.html#qDebug">qDebug</a>( cur.<a href="qsqlquery.html#value">value</a>( "id" ).toString() + ": " +
131 cur.<a href="qsqlquery.html#value">value</a>( "surname" ).toString() + " " +
132 cur.<a href="qsqlquery.html#value">value</a>( "salary" ).toString() );
133 }
134</pre>
135<p> In the above example, a cursor is created specifying a table or
136view name in the database. Then, <a href="#select">select</a>() is called, which can be
137optionally parameterised to filter and order the records
138retrieved. Each record in the cursor is retrieved using <a href="qsqlquery.html#next">next</a>().
139When next() returns FALSE, there are no more records to process,
140and the loop terminates.
141<p> For editing records (rows of data), a cursor contains a separate
142edit buffer which is independent of the fields used when browsing.
143The functions <a href="#insert">insert</a>(), <a href="#update">update</a>() and <a href="#del">del</a>() operate on the edit
144buffer. This allows the cursor to be repositioned to other
145records while simultaneously maintaining a separate buffer for
146edits. You can get a pointer to the edit buffer using
147<a href="#editBuffer">editBuffer</a>(). The <a href="#primeInsert">primeInsert</a>(), <a href="#primeUpdate">primeUpdate</a>() and <a href="#primeDelete">primeDelete</a>()
148functions also return a pointer to the edit buffer and prepare it
149for insert, update and delete respectively. Edit operations only
150affect a single row at a time. Note that update() and del()
151require that the table or view contain a <a href="#primaryIndex">primaryIndex</a>() to ensure
152that edit operations affect a unique record within the database.
153<p> For example:
154<p>
155
156<pre> QSqlCursor cur( "prices" );
157 <a name="x2200"></a> cur.<a href="#select">select</a>( "id=202" );
158 if ( cur.<a href="qsqlquery.html#next">next</a>() ) {
159 <a name="x2199"></a> <a href="qsqlrecord.html">QSqlRecord</a> *buffer = cur.<a href="#primeUpdate">primeUpdate</a>();
160 <a name="x2204"></a> double price = buffer-&gt;<a href="qsqlrecord.html#value">value</a>( "price" ).toDouble();
161 double newprice = price * 1.05;
162 <a name="x2203"></a> buffer-&gt;<a href="qsqlrecord.html#setValue">setValue</a>( "price", newprice );
163 <a name="x2201"></a> cur.<a href="#update">update</a>();
164 }
165</pre>
166<p> To edit an existing database record, first move to the record you
167wish to update. Call <a href="#primeUpdate">primeUpdate</a>() to get the pointer to the
168cursor's edit buffer. Then use this pointer to modify the values
169in the edit buffer. Finally, call <a href="#update">update</a>() to save the changes to
170the database. The values in the edit buffer will be used to
171locate the appropriate record when updating the database (see
172<a href="#primaryIndex">primaryIndex</a>()).
173<p> Similarly, when deleting an existing database record, first move
174to the record you wish to delete. Then, call <a href="#primeDelete">primeDelete</a>() to get
175the pointer to the edit buffer. Finally, call <a href="#del">del</a>() to delete the
176record from the database. Again, the values in the edit buffer
177will be used to locate and delete the appropriate record.
178<p> To insert a new record, call <a href="#primeInsert">primeInsert</a>() to get the pointer to
179the edit buffer. Use this pointer to populate the edit buffer
180with new values and then <a href="#insert">insert</a>() the record into the database.
181<p> After calling insert(), update() or del(), the cursor is no longer
182positioned on a valid record and can no longer be navigated
183(<a href="qsqlquery.html#isValid">isValid</a>() return FALSE). The reason for this is that any changes
184made to the database will not be visible until <a href="#select">select</a>() is called
185to refresh the cursor. You can change this behavior by passing
186FALSE to insert(), <a href="#update">update</a>() or del() which will prevent the cursor
187from becoming invalid. The edits will still not be visible when
188navigating the cursor until select() is called.
189<p> QSqlCursor contains virtual methods which allow editing behavior
190to be customized by subclasses. This allows custom cursors to be
191created that encapsulate the editing behavior of a database table
192for an entire application. For example, a cursor can be customized
193to always auto-number primary index fields, or provide fields with
194suitable default values, when inserting new records. QSqlCursor
195generates SQL statements which are sent to the database engine;
196you can control which fields are included in these statements
197using <a href="#setGenerated">setGenerated</a>().
198<p> Note that QSqlCursor does not inherit from <a href="qobject.html">QObject</a>. This means
199that you are responsible for destroying instances of this class
200yourself. However if you create a QSqlCursor and use it in a
201<a href="qdatatable.html">QDataTable</a>, <a href="qdatabrowser.html">QDataBrowser</a> or a <a href="qdataview.html">QDataView</a> these classes will
202usually take ownership of the cursor and destroy it when they
203don't need it anymore. The documentation for <a href="qdatatable.html">QDataTable</a>,
204<a href="qdatabrowser.html">QDataBrowser</a> and <a href="qdataview.html">QDataView</a> explicitly states which calls take
205ownership of the cursor.
206<p>See also <a href="database.html">Database Classes</a>.
207
208<hr><h2>Member Type Documentation</h2>
209<h3 class=fn><a name="Mode-enum"></a>QSqlCursor::Mode</h3>
210
211<p> This enum type describes how QSqlCursor operates on records in the
212database.
213<ul>
214<li><tt>QSqlCursor::ReadOnly</tt> - the cursor can only SELECT records from the
215database.
216<li><tt>QSqlCursor::Insert</tt> - the cursor can INSERT records into the database.
217<li><tt>QSqlCursor::Update</tt> - the cursor can UPDATE records in the database.
218<li><tt>QSqlCursor::Delete</tt> - the cursor can DELETE records from the database.
219<li><tt>QSqlCursor::Writable</tt> - the cursor can INSERT, UPDATE and DELETE records
220in the database.
221</ul>
222<hr><h2>Member Function Documentation</h2>
223<h3 class=fn><a name="QSqlCursor"></a>QSqlCursor::QSqlCursor ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name = QString::null, bool&nbsp;autopopulate = TRUE, <a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;*&nbsp;db = 0 )
224</h3>
225Constructs a cursor on database <em>db</em> using table or view <em>name</em>.
226<p> If <em>autopopulate</em> is TRUE (the default), the <em>name</em> of the
227cursor must correspond to an existing table or view name in the
228database so that field information can be automatically created.
229If the table or view does not exist, the cursor will not be
230functional.
231<p> The cursor is created with an initial mode of QSqlCursor::Writable
232(meaning that records can be inserted, updated or deleted using
233the cursor). If the cursor does not have a unique primary index,
234update and deletes cannot be performed.
235<p> Note that <em>autopopulate</em> refers to populating the cursor with
236meta-data, e.g. the names of the table's fields, not with
237retrieving data. The <a href="#select">select</a>() function is used to populate the
238cursor with data.
239<p> <p>See also <a href="#setName">setName</a>() and <a href="#setMode">setMode</a>().
240
241<h3 class=fn><a name="QSqlCursor-2"></a>QSqlCursor::QSqlCursor ( const&nbsp;<a href="qsqlcursor.html">QSqlCursor</a>&nbsp;&amp;&nbsp;other )
242</h3>
243Constructs a copy of <em>other</em>.
244
245<h3 class=fn><a name="~QSqlCursor"></a>QSqlCursor::~QSqlCursor ()
246</h3>
247Destroys the object and frees any allocated resources.
248
249<h3 class=fn>void <a name="append"></a>QSqlCursor::append ( const&nbsp;<a href="qsqlfieldinfo.html">QSqlFieldInfo</a>&nbsp;&amp;&nbsp;fieldInfo )<tt> [virtual]</tt>
250</h3>
251Append a copy of field <em>fieldInfo</em> to the end of the cursor. Note
252that all references to the cursor edit buffer become invalidated.
253
254<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="calculateField"></a>QSqlCursor::calculateField ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [virtual protected]</tt>
255</h3>
256Protected virtual function which is called whenever a field needs
257to be calculated. If calculated fields are being used, derived
258classes must reimplement this function and return the appropriate
259value for field <em>name</em>. The default implementation returns an
260invalid <a href="qvariant.html">QVariant</a>.
261<p> <p>See also <a href="#setCalculated">setCalculated</a>().
262
263<p>Examples: <a href="sql.html#x2259">sql/overview/subclass3/main.cpp</a> and <a href="sql.html#x2263">sql/overview/subclass4/main.cpp</a>.
264<h3 class=fn>bool <a name="canDelete"></a>QSqlCursor::canDelete () const
265</h3>
266Returns TRUE if the cursor will perform deletes; otherwise returns
267FALSE.
268<p> <p>See also <a href="#setMode">setMode</a>().
269
270<h3 class=fn>bool <a name="canInsert"></a>QSqlCursor::canInsert () const
271</h3>
272Returns TRUE if the cursor will perform inserts; otherwise returns
273FALSE.
274<p> <p>See also <a href="#setMode">setMode</a>().
275
276<h3 class=fn>bool <a name="canUpdate"></a>QSqlCursor::canUpdate () const
277</h3>
278Returns TRUE if the cursor will perform updates; otherwise returns
279FALSE.
280<p> <p>See also <a href="#setMode">setMode</a>().
281
282<h3 class=fn>void <a name="clear"></a>QSqlCursor::clear ()<tt> [virtual]</tt>
283</h3>
284Removes all fields from the cursor. Note that all references to
285the cursor edit buffer become invalidated.
286
287<p>Reimplemented from <a href="qsqlrecord.html#clear">QSqlRecord</a>.
288<h3 class=fn>int <a name="del"></a>QSqlCursor::del ( bool&nbsp;invalidate = TRUE )<tt> [virtual]</tt>
289</h3>
290Deletes a record from the database using the cursor's primary
291index and the contents of the cursor edit buffer. Returns the
292number of records which were deleted.
293For error information, use <a href="qsqlquery.html#lastError">lastError</a>().
294<p> Only records which meet the filter criteria specified by the
295cursor's primary index are deleted. If the cursor does not contain
296a primary index, no delete is performed and 0 is returned. If <em>invalidate</em> is TRUE (the default), the current cursor can no longer
297be navigated. A new <a href="#select">select</a>() call must be made before you can move
298to a valid record. For example:
299<p>
300
301<pre> QSqlCursor cur( "prices" );
302 <a name="x2207"></a> cur.<a href="#select">select</a>( "id=999" );
303 <a name="x2208"></a> if ( cur.<a href="qsqlquery.html#next">next</a>() ) {
304 <a name="x2206"></a> cur.<a href="#primeDelete">primeDelete</a>();
305 <a name="x2205"></a> cur.<a href="#del">del</a>();
306 }
307</pre>
308<p> In the above example, a cursor is created on the 'prices' table
309and positioned to the record to be deleted. First <a href="#primeDelete">primeDelete</a>() is
310called to populate the edit buffer with the current cursor values,
311e.g. with an id of 999, and then <a href="#del">del</a>() is called to actually
312delete the record from the database. Remember: all edit operations
313(<a href="#insert">insert</a>(), <a href="#update">update</a>() and delete()) operate on the contents of the
314cursor edit buffer and not on the contents of the cursor itself.
315<p> <p>See also <a href="#primeDelete">primeDelete</a>(), <a href="#setMode">setMode</a>(), and <a href="qsqlquery.html#lastError">lastError</a>().
316
317<p>Example: <a href="sql.html#x2205">sql/overview/delete/main.cpp</a>.
318<h3 class=fn>int <a name="del-2"></a>QSqlCursor::del ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filter, bool&nbsp;invalidate = TRUE )<tt> [virtual protected]</tt>
319</h3>
320This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
321<p> Deletes the current cursor record from the database using the
322filter <em>filter</em>. Only records which meet the filter criteria are
323deleted. Returns the number of records which were deleted. If <em>invalidate</em> is TRUE (the default), the current cursor can no longer
324be navigated. A new <a href="#select">select</a>() call must be made before you can move
325to a valid record. For error information, use <a href="qsqlquery.html#lastError">lastError</a>().
326<p> The <em>filter</em> is an SQL <tt>WHERE</tt> clause, e.g. <tt>id=500</tt>.
327<p> <p>See also <a href="#setMode">setMode</a>() and <a href="qsqlquery.html#lastError">lastError</a>().
328
329<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a>&nbsp;* <a name="editBuffer"></a>QSqlCursor::editBuffer ( bool&nbsp;copy = FALSE )<tt> [virtual]</tt>
330</h3>
331Returns the current internal edit buffer. If <em>copy</em> is TRUE (the
332default is FALSE), the current cursor field values are first
333copied into the edit buffer. The edit buffer is valid as long as
334the cursor remains valid. The cursor retains ownership of the
335returned pointer, so it must not be deleted or modified.
336<p> <p>See also <a href="#primeInsert">primeInsert</a>(), <a href="#primeUpdate">primeUpdate</a>(), and <a href="#primeDelete">primeDelete</a>().
337
338<h3 class=fn><a href="qstring.html">QString</a> <a name="filter"></a>QSqlCursor::filter () const
339</h3>
340Returns the current filter, or an empty string if there is no
341current filter.
342
343<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="index"></a>QSqlCursor::index ( const&nbsp;<a href="qstringlist.html">QStringList</a>&nbsp;&amp;&nbsp;fieldNames ) const<tt> [virtual]</tt>
344</h3>
345Returns an index composed of <em>fieldNames</em>, all in ASCending
346order. Note that all field names must exist in the cursor,
347otherwise an empty index is returned.
348<p> <p>See also <a href="qsqlindex.html">QSqlIndex</a>.
349
350<p>Examples: <a href="sql.html#x2188">sql/overview/extract/main.cpp</a>, <a href="sql.html#x2181">sql/overview/order1/main.cpp</a>, <a href="sql.html#x2184">sql/overview/order2/main.cpp</a>, and <a href="sql.html#x2241">sql/overview/table3/main.cpp</a>.
351<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="index-2"></a>QSqlCursor::index ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;fieldName ) const
352</h3>
353This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
354<p> Returns an index based on <em>fieldName</em>.
355
356<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="index-3"></a>QSqlCursor::index ( const&nbsp;char&nbsp;*&nbsp;fieldName ) const
357</h3>
358This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
359<p> Returns an index based on <em>fieldName</em>.
360
361<h3 class=fn>void <a name="insert"></a>QSqlCursor::insert ( int&nbsp;pos, const&nbsp;<a href="qsqlfieldinfo.html">QSqlFieldInfo</a>&nbsp;&amp;&nbsp;fieldInfo )<tt> [virtual]</tt>
362</h3>
363Insert a copy of <em>fieldInfo</em> at position <em>pos</em>. If a field
364already exists at <em>pos</em>, it is removed. Note that all references
365to the cursor edit buffer become invalidated.
366
367<p>Examples: <a href="sql.html#x2194">sql/overview/insert/main.cpp</a> and <a href="qsqlcursor.html#x2446">sql/overview/insert2/main.cpp</a>.
368<h3 class=fn>int <a name="insert-2"></a>QSqlCursor::insert ( bool&nbsp;invalidate = TRUE )<tt> [virtual]</tt>
369</h3>
370This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
371<p> Inserts the current contents of the cursor's edit record buffer
372into the database, if the cursor allows inserts. Returns the
373number of rows affected by the insert. For error information, use
374<a href="qsqlquery.html#lastError">lastError</a>().
375<p> If <em>invalidate</em> is TRUE (the default), the cursor will no longer
376be positioned on a valid record and can no longer be navigated. A
377new <a href="#select">select</a>() call must be made before navigating to a valid
378record.
379<p>
380
381<pre> QSqlCursor cur( "prices" );
382 <a name="x2447"></a> <a href="qsqlrecord.html">QSqlRecord</a> *buffer = cur.<a href="#primeInsert">primeInsert</a>();
383 <a name="x2448"></a> buffer-&gt;<a href="qsqlrecord.html#setValue">setValue</a>( "id", 53981 );
384 buffer-&gt;<a href="qsqlrecord.html#setValue">setValue</a>( "name", "Thingy" );
385 buffer-&gt;<a href="qsqlrecord.html#setValue">setValue</a>( "price", 105.75 );
386 <a name="x2446"></a> cur.<a href="#insert">insert</a>();
387</pre>
388<p> In the above example, a cursor is created on the 'prices' table
389and a pointer to the insert buffer is aquired using <a href="#primeInsert">primeInsert</a>().
390Each field's value is set to the desired value and then <a href="#insert">insert</a>()
391is called to insert the data into the database. Remember: all edit
392operations (insert(), <a href="#update">update</a>() and delete()) operate on the
393contents of the cursor edit buffer and not on the contents of the
394cursor itself.
395<p> <p>See also <a href="#setMode">setMode</a>() and <a href="qsqlquery.html#lastError">lastError</a>().
396
397<h3 class=fn>bool <a name="isCalculated"></a>QSqlCursor::isCalculated ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name ) const
398</h3>
399Returns TRUE if the field <em>name</em> exists and is calculated;
400otherwise returns FALSE.
401<p> <p>See also <a href="#setCalculated">setCalculated</a>().
402
403<h3 class=fn>bool <a name="isNull"></a>QSqlCursor::isNull ( int&nbsp;i ) const
404</h3>
405Returns TRUE if the field <em>i</em> is NULL or if there is no field at
406position <em>i</em>; otherwise returns FALSE.
407<p> This is the same as calling <a href="qsqlrecord.html#isNull">QSqlRecord::isNull</a>( <em>i</em> )
408
409<h3 class=fn>bool <a name="isNull-2"></a>QSqlCursor::isNull ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name ) const
410</h3>
411This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
412<p> Returns TRUE if the field called <em>name</em> is NULL or if there is no
413field called <em>name</em>; otherwise returns FALSE.
414<p> This is the same as calling <a href="qsqlrecord.html#isNull">QSqlRecord::isNull</a>( <em>name</em> )
415
416<h3 class=fn>bool <a name="isReadOnly"></a>QSqlCursor::isReadOnly () const
417</h3>
418Returns TRUE if the cursor is read-only; otherwise returns FALSE.
419The default is FALSE. Read-only cursors cannot be edited using
420<a href="#insert">insert</a>(), <a href="#update">update</a>() or <a href="#del">del</a>().
421<p> <p>See also <a href="#setMode">setMode</a>().
422
423<h3 class=fn>bool <a name="isTrimmed"></a>QSqlCursor::isTrimmed ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name ) const
424</h3>
425Returns TRUE if the field <em>name</em> exists and is trimmed; otherwise
426returns FALSE.
427<p> When a trimmed field of type string or cstring is read from the
428database any trailing (right-most) spaces are removed.
429<p> <p>See also <a href="#setTrimmed">setTrimmed</a>().
430
431<h3 class=fn>int <a name="mode"></a>QSqlCursor::mode () const
432</h3>
433Returns the current cursor mode.
434<p> <p>See also <a href="#setMode">setMode</a>().
435
436<h3 class=fn><a href="qstring.html">QString</a> <a name="name"></a>QSqlCursor::name () const
437</h3>
438Returns the name of the cursor.
439
440<h3 class=fn><a href="qsqlcursor.html">QSqlCursor</a>&nbsp;&amp; <a name="operator-eq"></a>QSqlCursor::operator= ( const&nbsp;<a href="qsqlcursor.html">QSqlCursor</a>&nbsp;&amp;&nbsp;other )
441</h3>
442Sets the cursor equal to <em>other</em>.
443
444<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="primaryIndex"></a>QSqlCursor::primaryIndex ( bool&nbsp;setFromCursor = TRUE ) const<tt> [virtual]</tt>
445</h3>
446Returns the primary index associated with the cursor as defined in
447the database, or an empty index if there is no primary index. If
448<em>setFromCursor</em> is TRUE (the default), the index fields are
449populated with the corresponding values in the cursor's current
450record.
451
452<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a>&nbsp;* <a name="primeDelete"></a>QSqlCursor::primeDelete ()<tt> [virtual]</tt>
453</h3>
454This function primes the edit buffer's field values for delete and
455returns the edit buffer. The default implementation copies the
456field values from the current cursor record into the edit buffer
457(therefore, this function is equivalent to calling <a href="#editBuffer">editBuffer</a>(
458TRUE ) ). The cursor retains ownership of the returned pointer, so
459it must not be deleted or modified.
460<p> <p>See also <a href="#editBuffer">editBuffer</a>() and <a href="#del">del</a>().
461
462<p>Example: <a href="sql.html#x2206">sql/overview/delete/main.cpp</a>.
463<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a>&nbsp;* <a name="primeInsert"></a>QSqlCursor::primeInsert ()<tt> [virtual]</tt>
464</h3>
465This function primes the edit buffer's field values for insert and
466returns the edit buffer. The default implementation clears all
467field values in the edit buffer. The cursor retains ownership of
468the returned pointer, so it must not be deleted or modified.
469<p> <p>See also <a href="#editBuffer">editBuffer</a>() and <a href="#insert">insert</a>().
470
471<p>Examples: <a href="sql.html#x2195">sql/overview/insert/main.cpp</a>, <a href="qsqlcursor.html#x2447">sql/overview/insert2/main.cpp</a>, <a href="sql.html#x2267">sql/overview/subclass5/main.cpp</a>, and <a href="sqltable-example.html#x2453">sql/sqltable/main.cpp</a>.
472<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a>&nbsp;* <a name="primeUpdate"></a>QSqlCursor::primeUpdate ()<tt> [virtual]</tt>
473</h3>
474This function primes the edit buffer's field values for update and
475returns the edit buffer. The default implementation copies the
476field values from the current cursor record into the edit buffer
477(therefore, this function is equivalent to calling <a href="#editBuffer">editBuffer</a>(
478TRUE ) ). The cursor retains ownership of the returned pointer, so
479it must not be deleted or modified.
480<p> <p>See also <a href="#editBuffer">editBuffer</a>() and <a href="#update">update</a>().
481
482<p>Examples: <a href="sql.html#x2236">sql/overview/custom1/main.cpp</a>, <a href="sql.html#x2223">sql/overview/form1/main.cpp</a>, and <a href="sql.html#x2199">sql/overview/update/main.cpp</a>.
483<h3 class=fn>void <a name="remove"></a>QSqlCursor::remove ( int&nbsp;pos )<tt> [virtual]</tt>
484</h3>
485Removes the field at <em>pos</em>. If <em>pos</em> does not exist, nothing
486happens. Note that all references to the cursor edit buffer become
487invalidated.
488
489<p>Reimplemented from <a href="qsqlrecord.html#remove">QSqlRecord</a>.
490<h3 class=fn>bool <a name="select"></a>QSqlCursor::select ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filter, const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;sort = QSqlIndex ( ) )<tt> [virtual]</tt>
491</h3>
492Selects all fields in the cursor from the database matching the
493filter criteria <em>filter</em>. The data is returned in the order
494specified by the index <em>sort</em>. Returns TRUE if the data was
495successfully selected; otherwise returns FALSE.
496<p> The <em>filter</em> is a string containing a SQL <tt>WHERE</tt> clause but
497without the 'WHERE' keyword. The cursor is initially positioned at
498an invalid row after this function is called. To move to a valid
499row, use <a href="qsqlquery.html#seek">seek</a>(), <a href="qsqlquery.html#first">first</a>(), <a href="qsqlquery.html#last">last</a>(), <a href="qsqlquery.html#prev">prev</a>() or <a href="qsqlquery.html#next">next</a>().
500<p> Example:
501<pre>
502 QSqlCursor cur( "Employee" ); // Use the Employee table or view
503 cur.<a href="#select">select</a>( "deptno=10" ); // select all records in department 10
504 while( cur.<a href="qsqlquery.html#next">next</a>() ) {
505 ... // process data
506 }
507 ...
508 // select records in other departments, ordered by department number
509 cur.<a href="#select">select</a>( "deptno&gt;10", cur.<a href="#index">index</a>( "deptno" ) );
510 ...
511 </pre>
512
513<p> The filter will apply to any subsequent <a href="#select">select</a>() calls that do not
514explicitly specify another filter. Similarly the sort will apply
515to any subsequent select() calls that do not explicitly specify
516another sort.
517<p> <pre>
518 QSqlCursor cur( "Employee" );
519 cur.<a href="#select">select</a>( "deptno=10" ); // select all records in department 10
520 while( cur.<a href="qsqlquery.html#next">next</a>() ) {
521 ... // process data
522 }
523 ...
524 cur.<a href="#select">select</a>(); // re-selects all records in department 10
525 ...
526 </pre>
527
528<p>
529<p>Examples: <a href="sql.html#x2207">sql/overview/delete/main.cpp</a>, <a href="sql.html#x2189">sql/overview/extract/main.cpp</a>, <a href="sql.html#x2182">sql/overview/order1/main.cpp</a>, <a href="sql.html#x2185">sql/overview/order2/main.cpp</a>, <a href="sql.html#x2178">sql/overview/retrieve2/main.cpp</a>, <a href="sql.html#x2242">sql/overview/table3/main.cpp</a>, and <a href="sql.html#x2200">sql/overview/update/main.cpp</a>.
530<h3 class=fn>bool <a name="select-2"></a>QSqlCursor::select ()
531</h3>
532This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
533<p> Selects all fields in the cursor from the database. The rows are
534returned in the order specified by the last call to <a href="#setSort">setSort</a>() or
535the last call to <a href="#select">select</a>() that specified a sort, whichever is the
536most recent. If there is no current sort, the order in which the
537rows are returned is undefined. The records are filtered according
538to the filter specified by the last call to <a href="#setFilter">setFilter</a>() or the
539last call to select() that specified a filter, whichever is the
540most recent. If there is no current filter, all records are
541returned. The cursor is initially positioned at an invalid row. To
542move to a valid row, use <a href="qsqlquery.html#seek">seek</a>(), <a href="qsqlquery.html#first">first</a>(), <a href="qsqlquery.html#last">last</a>(), <a href="qsqlquery.html#prev">prev</a>() or
543<a href="qsqlquery.html#next">next</a>().
544<p> <p>See also <a href="#setSort">setSort</a>() and <a href="#setFilter">setFilter</a>().
545
546<h3 class=fn>bool <a name="select-3"></a>QSqlCursor::select ( const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;sort )
547</h3>
548This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
549<p> Selects all fields in the cursor from the database. The data is
550returned in the order specified by the index <em>sort</em>. The records
551are filtered according to the filter specified by the last call to
552<a href="#setFilter">setFilter</a>() or the last call to <a href="#select">select</a>() that specified a filter,
553whichever is the most recent. The cursor is initially positioned
554at an invalid row. To move to a valid row, use <a href="qsqlquery.html#seek">seek</a>(), <a href="qsqlquery.html#first">first</a>(),
555<a href="qsqlquery.html#last">last</a>(), <a href="qsqlquery.html#prev">prev</a>() or <a href="qsqlquery.html#next">next</a>().
556
557<h3 class=fn>bool <a name="select-4"></a>QSqlCursor::select ( const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;filter, const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;sort )
558</h3>
559This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
560<p> Selects all fields in the cursor matching the filter index <em>filter</em>. The data is returned in the order specified by the index
561<em>sort</em>. The <em>filter</em> index works by constructing a WHERE clause
562using the names of the fields from the <em>filter</em> and their values
563from the current cursor record. The cursor is initially positioned
564at an invalid row. To move to a valid row, use <a href="qsqlquery.html#seek">seek</a>(), <a href="qsqlquery.html#first">first</a>(),
565<a href="qsqlquery.html#last">last</a>(), <a href="qsqlquery.html#prev">prev</a>() or <a href="qsqlquery.html#next">next</a>(). This function is useful, for example,
566for retrieving data based upon a table's primary index:
567<p> <pre>
568 QSqlCursor cur( "Employee" );
569 <a href="qsqlindex.html">QSqlIndex</a> pk = cur.<a href="#primaryIndex">primaryIndex</a>();
570 cur.<a href="qsqlrecord.html#setValue">setValue</a>( "id", 10 );
571 cur.<a href="#select">select</a>( pk, pk ); // generates "SELECT ... FROM Employee WHERE id=10 ORDER BY id"
572 ...
573 </pre>
574
575<p> In this example the <a href="qsqlindex.html">QSqlIndex</a>, pk, is used for two different
576purposes. When used as the filter (first) argument, the field
577names it contains are used to construct the WHERE clause, each set
578to the current cursor value, <tt>WHERE id=10</tt>, in this case. When
579used as the sort (second) argument the field names it contains are
580used for the ORDER BY clause, <tt>ORDER BY id</tt> in this example.
581
582<h3 class=fn>void <a name="setCalculated"></a>QSqlCursor::setCalculated ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, bool&nbsp;calculated )<tt> [virtual]</tt>
583</h3>
584Sets field <em>name</em> to <em>calculated</em>. If the field <em>name</em> does not
585exist, nothing happens. The value of a calculated field is set by
586the <a href="#calculateField">calculateField</a>() virtual function which you must reimplement
587(or the field value will be an invalid <a href="qvariant.html">QVariant</a>). Calculated
588fields do not appear in generated SQL statements sent to the
589database.
590<p> <p>See also <a href="#calculateField">calculateField</a>() and <a href="qsqlrecord.html#setGenerated">QSqlRecord::setGenerated</a>().
591
592<h3 class=fn>void <a name="setFilter"></a>QSqlCursor::setFilter ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filter )<tt> [virtual]</tt>
593</h3>
594Sets the current filter to <em>filter</em>. Note that no new records are
595selected. To select new records, use <a href="#select">select</a>(). The <em>filter</em> will
596apply to any subsequent select() calls that do not explicitly
597specify a filter.
598<p> The filter is a SQL <tt>WHERE</tt> clause without the keyword 'WHERE',
599e.g. <tt>name='Dave'</tt> which will be processed by the DBMS.
600
601<h3 class=fn>void <a name="setGenerated"></a>QSqlCursor::setGenerated ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, bool&nbsp;generated )<tt> [virtual]</tt>
602</h3>
603Sets the generated flag for the field <em>name</em> to <em>generated</em>. If
604the field does not exist, nothing happens. Only fields that have
605<em>generated</em> set to TRUE are included in the SQL that is
606generated by <a href="#insert">insert</a>(), <a href="#update">update</a>() or <a href="#del">del</a>().
607<p> <p>See also <a href="qsqlrecord.html#isGenerated">isGenerated</a>().
608
609<p>Reimplemented from <a href="qsqlrecord.html#setGenerated">QSqlRecord</a>.
610<h3 class=fn>void <a name="setGenerated-2"></a>QSqlCursor::setGenerated ( int&nbsp;i, bool&nbsp;generated )<tt> [virtual]</tt>
611</h3>
612This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
613<p> Sets the generated flag for the field <em>i</em> to <em>generated</em>.
614<p> <p>See also <a href="qsqlrecord.html#isGenerated">isGenerated</a>().
615
616<p>Reimplemented from <a href="qsqlrecord.html#setGenerated-2">QSqlRecord</a>.
617<h3 class=fn>void <a name="setMode"></a>QSqlCursor::setMode ( int&nbsp;mode )<tt> [virtual]</tt>
618</h3>
619Sets the cursor mode to <em>mode</em>. This value can be an OR'ed
620combination of <a href="#Mode-enum">QSqlCursor::Mode</a> values. The default mode for a
621cursor is <a href="#Mode-enum">QSqlCursor::Writable</a>.
622<p> <pre>
623 QSqlCursor cur( "Employee" );
624 cur.<a href="#setMode">setMode</a>( QSqlCursor::<a href="#Mode-enum">Writable</a> ); // allow insert/update/delete
625 ...
626 cur.<a href="#setMode">setMode</a>( QSqlCursor::<a href="#Mode-enum">Insert</a> | QSqlCursor::<a href="#Mode-enum">Update</a> ); // allow inserts and updates only
627 ...
628 cur.<a href="#setMode">setMode</a>( QSqlCursor::<a href="#Mode-enum">ReadOnly</a> ); // no inserts/updates/deletes allowed
629
630 </pre>
631
632
633<h3 class=fn>void <a name="setName"></a>QSqlCursor::setName ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, bool&nbsp;autopopulate = TRUE )<tt> [virtual]</tt>
634</h3>
635Sets the name of the cursor to <em>name</em>. If <em>autopopulate</em> is TRUE
636(the default), the <em>name</em> must correspond to a valid table or
637view name in the database. Also, note that all references to the
638cursor edit buffer become invalidated when fields are
639auto-populated. See the QSqlCursor constructor documentation for
640more information.
641
642<h3 class=fn>void <a name="setPrimaryIndex"></a>QSqlCursor::setPrimaryIndex ( const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;idx )<tt> [virtual]</tt>
643</h3>
644Sets the primary index associated with the cursor to the index <em>idx</em>. Note that this index must contain a field or set of fields
645which identify a unique record within the underlying database
646table or view so that <a href="#update">update</a>() and <a href="#del">del</a>() will execute as expected.
647<p> <p>See also <a href="#update">update</a>() and <a href="#del">del</a>().
648
649<h3 class=fn>void <a name="setSort"></a>QSqlCursor::setSort ( const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;sort )<tt> [virtual]</tt>
650</h3>
651Sets the current sort to <em>sort</em>. Note that no new records are
652selected. To select new records, use <a href="#select">select</a>(). The <em>sort</em> will
653apply to any subsequent select() calls that do not explicitly
654specify a sort.
655
656<h3 class=fn>void <a name="setTrimmed"></a>QSqlCursor::setTrimmed ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, bool&nbsp;trim )<tt> [virtual]</tt>
657</h3>
658Sets field <em>name</em>'s trimmed status to <em>trim</em>. If the field <em>name</em> does not exist, nothing happens.
659<p> When a trimmed field of type string or cstring is read from the
660database any trailing (right-most) spaces are removed.
661<p> <p>See also <a href="#isTrimmed">isTrimmed</a>() and <a href="qvariant.html">QVariant</a>.
662
663<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="sort"></a>QSqlCursor::sort () const
664</h3>
665Returns the current sort, or an empty index if there is no current
666sort.
667
668<h3 class=fn><a href="qstring.html">QString</a> <a name="toString"></a>QSqlCursor::toString ( <a href="qsqlrecord.html">QSqlRecord</a>&nbsp;*&nbsp;rec, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;prefix, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;fieldSep, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;sep ) const<tt> [virtual protected]</tt>
669</h3>
670Returns a formatted string composed of all the fields in <em>rec</em>.
671Each field is composed of the <em>prefix</em> (e.g. table or view name),
672".", the field name, the <em>fieldSep</em> and the field value. If the
673<em>prefix</em> is empty then each field will begin with the field name.
674The fields are then joined together separated by <em>sep</em>. Fields
675where <a href="qsqlrecord.html#isGenerated">isGenerated</a>() returns FALSE are not included. This function
676is useful for generating SQL statements.
677
678<h3 class=fn><a href="qstring.html">QString</a> <a name="toString-3"></a>QSqlCursor::toString ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;prefix, <a href="qsqlfield.html">QSqlField</a>&nbsp;*&nbsp;field, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;fieldSep ) const<tt> [virtual protected]</tt>
679</h3>
680This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
681<p> Returns a formatted string composed of the <em>prefix</em> (e.g. table
682or view name), ".", the <em>field</em> name, the <em>fieldSep</em> and the
683field value. If the <em>prefix</em> is empty then the string will begin
684with the <em>field</em> name. This function is useful for generating SQL
685statements.
686
687<h3 class=fn><a href="qstring.html">QString</a> <a name="toString-4"></a>QSqlCursor::toString ( const&nbsp;<a href="qsqlindex.html">QSqlIndex</a>&nbsp;&amp;&nbsp;i, <a href="qsqlrecord.html">QSqlRecord</a>&nbsp;*&nbsp;rec, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;prefix, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;fieldSep, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;sep ) const<tt> [virtual protected]</tt>
688</h3>
689This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
690<p> Returns a formatted string composed of all the fields in the index
691<em>i</em>. Each field is composed of the <em>prefix</em> (e.g. table or view
692name), ".", the field name, the <em>fieldSep</em> and the field value.
693If the <em>prefix</em> is empty then each field will begin with the field
694name. The field values are taken from <em>rec</em>. The fields are then
695joined together separated by <em>sep</em>. Fields where <a href="qsqlrecord.html#isGenerated">isGenerated</a>()
696returns FALSE are ignored. This function is useful for generating
697SQL statements.
698
699<h3 class=fn>int <a name="update"></a>QSqlCursor::update ( bool&nbsp;invalidate = TRUE )<tt> [virtual]</tt>
700</h3>
701Updates the database with the current contents of the edit buffer.
702Returns the number of records which were updated.
703For error information, use <a href="qsqlquery.html#lastError">lastError</a>().
704<p> Only records which meet the filter criteria specified by the
705cursor's primary index are updated. If the cursor does not contain
706a primary index, no update is performed and 0 is returned.
707<p> If <em>invalidate</em> is TRUE (the default), the current cursor can no
708longer be navigated. A new <a href="#select">select</a>() call must be made before you
709can move to a valid record. For example:
710<p>
711
712<pre> QSqlCursor cur( "prices" );
713 <a name="x2200"></a> cur.<a href="#select">select</a>( "id=202" );
714 if ( cur.<a href="qsqlquery.html#next">next</a>() ) {
715 <a name="x2199"></a> <a href="qsqlrecord.html">QSqlRecord</a> *buffer = cur.<a href="#primeUpdate">primeUpdate</a>();
716 <a name="x2204"></a> double price = buffer-&gt;<a href="qsqlrecord.html#value">value</a>( "price" ).toDouble();
717 double newprice = price * 1.05;
718 <a name="x2203"></a> buffer-&gt;<a href="qsqlrecord.html#setValue">setValue</a>( "price", newprice );
719 <a name="x2201"></a> cur.<a href="#update">update</a>();
720 }
721</pre>
722<p> In the above example, a cursor is created on the 'prices' table
723and is positioned on the record to be updated. Then a pointer to
724the cursor's edit buffer is acquired using <a href="#primeUpdate">primeUpdate</a>(). A new
725value is calculated and placed into the edit buffer with the
726<a href="qsqlrecord.html#setValue">setValue</a>() call. Finally, an <a href="#update">update</a>() call is made on the cursor
727which uses the tables's primary index to update the record in the
728database with the contents of the cursor's edit buffer. Remember:
729all edit operations (<a href="#insert">insert</a>(), update() and delete()) operate on
730the contents of the cursor edit buffer and not on the contents of
731the cursor itself.
732<p> Note that if the primary index does not uniquely distinguish
733records the database may be changed into an inconsistent state.
734<p> <p>See also <a href="#setMode">setMode</a>() and <a href="qsqlquery.html#lastError">lastError</a>().
735
736<p>Example: <a href="sql.html#x2201">sql/overview/update/main.cpp</a>.
737<h3 class=fn>int <a name="update-2"></a>QSqlCursor::update ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filter, bool&nbsp;invalidate = TRUE )<tt> [virtual protected]</tt>
738</h3>
739This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
740<p> Updates the database with the current contents of the cursor edit
741buffer using the specified <em>filter</em>. Returns the number of
742records which were updated.
743For error information, use <a href="qsqlquery.html#lastError">lastError</a>().
744<p> Only records which meet the filter criteria are updated, otherwise
745all records in the table are updated.
746<p> If <em>invalidate</em> is TRUE (the default), the cursor can no longer
747be navigated. A new <a href="#select">select</a>() call must be made before you can move
748to a valid record.
749<p> <p>See also <a href="#primeUpdate">primeUpdate</a>(), <a href="#setMode">setMode</a>(), and <a href="qsqlquery.html#lastError">lastError</a>().
750
751<!-- eof -->
752<hr><p>
753This file is part of the <a href="index.html">Qt toolkit</a>.
754Copyright &copy; 1995-2007
755<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
756<table width=100% cellspacing=0 border=0><tr>
757<td>Copyright &copy; 2007
758<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
759<td align=right><div align=right>Qt 3.3.8</div>
760</table></div></address></body>
761</html>
Note: See TracBrowser for help on using the repository browser.