X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/feaca34f3426ac5774fbd7313fe9cabbb7d70446..52ee226853ec422d1517de38a0fa76d866c37153:/docs/latex/wx/db.tex

diff --git a/docs/latex/wx/db.tex b/docs/latex/wx/db.tex
index d08ec080c2..c26a333b59 100644
--- a/docs/latex/wx/db.tex
+++ b/docs/latex/wx/db.tex
@@ -623,7 +623,7 @@ entry is also logged to the defined log file.
 \docparam{aHdbc}{Handle to the ODBC connection.  Pass this in if the ODBC
 function call that erred required a hdbc or hstmt argument.}
 
-\docparam{aHstmt}{Handle to the ODBC statement being executed against.  Pass 
+\docparam{aHstmt}{Handle to the ODBC statement being executed against.  Pass
 this in if the ODBC function call that failed required a hstmt argument.}
 
 \wxheading{Remarks}
@@ -733,7 +733,7 @@ of processing.
 
 Older form (pre-2.3/2.4 of wxWindows) of the
 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}.  This method is
-provided for backward compatability only.  The method
+provided for backward compatibility only.  The method
 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors} should be
 used in place of this method.
 
@@ -980,10 +980,10 @@ in the result set after the current position of the cursor.
 \wxheading{Parameters}
 
 \docparam{aHenv}{A handle to the ODBC environment.}
-\docparam{aHdbc}{{\it OPTIONAL.}  A handle to the ODBC connection.  Pass this 
+\docparam{aHdbc}{{\it OPTIONAL.}  A handle to the ODBC connection.  Pass this
 in if the ODBC function call that failed required a hdbc or hstmt argument.}
-\docparam{AHstmt}{{\it OPTIONAL.}A handle to the ODBC statement being executed 
-against.  Pass this in if the ODBC function call that failed requires a 
+\docparam{AHstmt}{{\it OPTIONAL.}A handle to the ODBC statement being executed
+against.  Pass this in if the ODBC function call that failed requires a
 hstmt argument.}
 
 \wxheading{Example}
@@ -1421,7 +1421,8 @@ at least minimal privileges to the table).
 \docparam{tableName}{Name of the table on which to check privileges.
 {\it tableName} may refer to a table, view, alias or synonym.}
 \docparam{priv}{The table privilege being evaluated. May be one of the
-following (or a datasource specific privilege):}
+following (or a datasource specific privilege):
+
 \begin{verbatim}
     SELECT      : The connected user is permitted to retrieve data for
                   one or more columns of the table.
@@ -1441,25 +1442,28 @@ following (or a datasource specific privilege):}
                   example, a unique, referential, or table check
                   constraint).
 \end{verbatim}
+}
 \docparam{userID}{{\it OPTIONAL.}  User for which to determine if the privilege
 specified to be checked is granted or not.  Default is "".
-{\it userID} is evaluated as follows:}
+{\it userID} is evaluated as follows:
+
 \begin{verbatim}
          userID == NULL  ... NOT ALLOWED!
          userID == ""    ... UserID set equal to 'this->uid'
          userID != ""    ... UserID set equal to 'userID'
 \end{verbatim}
-
+}
 \docparam{schema}{{\it OPTIONAL.}  Owner of the table.  Specify a userID when the datasource
 you are connected to allows multiple unique tables with the same name to be
 owned by different users.  Specifying the table owner makes determination of the
-users privileges MUCH faster.  Default is NULL.  {\it userID} is evaluated as follows:}
+users privileges MUCH faster.  Default is NULL.  {\it userID} is evaluated as follows:
+
 \begin{verbatim}
          schema == NULL  ... Any owner (DEFAULT)
          schema == ""    ... Owned by 'this->uid'
          schema != ""    ... Owned by userID specified in 'schema'
 \end{verbatim}
-
+}
 \docparam{path}{{\it OPTIONAL.}  Path to the table.  Default is "".
 Currently unused.}
 
@@ -1690,9 +1694,9 @@ functions planned to be added for creating/manipulating datasource definitions.
 
 Default constructor.
 
-\func{}{wxDbConnectInf}{\param{HENV }{henv}, \param{const wxString \&}{dsn}, 
-\param{const wxString \&}{userID=""}, \param{const wxString \&}{password}, 
-\param{const wxString \&}{defaultDir=""}, \param{const wxString \&}{description=""}, 
+\func{}{wxDbConnectInf}{\param{HENV }{henv}, \param{const wxString \&}{dsn},
+\param{const wxString \&}{userID=""}, \param{const wxString \&}{password},
+\param{const wxString \&}{defaultDir=""}, \param{const wxString \&}{description=""},
 \param{const wxString \&}{fileType=""}}
 
 Constructor which allows initial settings of all the classes member variables.
@@ -2568,11 +2572,11 @@ by specifying the data in the columns to match on.
 
 To delete all users with a first name of "JOHN", do the following:
 
-\begin{verbatim}
-    1)  Clear all "columns" using wxDbTable::ClearMemberVars().
-    2)  Set the FIRST_NAME column equal to "JOHN".
-    3)  Call wxDbTable::DeleteMatching().
-\end{verbatim}
+\begin{enumerate}\itemsep=0pt
+\item Clear all "columns" using wxDbTable::ClearMemberVars().
+\item Set the FIRST\_NAME column equal to "JOHN".
+\item Call wxDbTable::DeleteMatching().
+\end{enumerate}
 
 The WHERE clause is built by the ODBC class library based on all non-NULL
 columns.  This allows deletion of records by matching on any column(s) in
@@ -3105,7 +3109,7 @@ If the function returns a FALSE value due to the table not existing, a log
 entry is recorded for the datasource connection indicating the problem
 that was detected when checking for table existence.  Note that it is usually
 best for the calling routine to check for the existence of the table and for
-sufficent user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
+sufficient user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
 !wxDB\_QUERY\_ONLY) before trying to open the table for the best possible
 explanation as to why a table cannot be opened.
 
@@ -3264,27 +3268,25 @@ specific function calls.
 
 The requirements of the SELECT statement are the following:
 
-\begin{verbatim}
-    1. Must return the correct number of columns.  In the derived
-       wxDbTable constructor, it is specified how many columns are in
-       the wxDbTable object.  The SELECT statement must return exactly
-       that many columns.
-
-    2. The columns must be returned in the same sequence as specified
-       when defining the bounds columns using wxDbTable::SetColDefs(),
-       and the columns returned must be of the proper data type.  For
-       example, if column 3 is defined in the wxDbTable bound column
-       definitions to be a float, the SELECT statement must return a
-       float for column 3 (e.g. PRICE * 1.10 to increase the price by
-       10%).
-
-    3. The ROWID can be included in your SELECT statement as the {\bf last}
-       column selected, if the datasource supports it.  Use
-       wxDbTable::CanUpdByROWID() to determine if the ROWID can be
-       selected from the datasource.  If it can, much better
-       performance can be achieved on updates and deletes by including
-       the ROWID in the SELECT statement.
-\end{verbatim}
+\begin{enumerate}
+\item Must return the correct number of columns.  In the derived
+wxDbTable constructor, it is specified how many columns are in
+the wxDbTable object. The SELECT statement must return exactly
+that many columns.
+\item The columns must be returned in the same sequence as specified
+when defining the bounds columns using wxDbTable::SetColDefs(),
+and the columns returned must be of the proper data type.  For
+example, if column 3 is defined in the wxDbTable bound column
+definitions to be a float, the SELECT statement must return a
+float for column 3 (e.g. PRICE * 1.10 to increase the price by
+10%).
+\item The ROWID can be included in your SELECT statement as the {\bf last}
+column selected, if the datasource supports it.  Use
+wxDbTable::CanUpdByROWID() to determine if the ROWID can be
+selected from the datasource.  If it can, much better
+performance can be achieved on updates and deletes by including
+the ROWID in the SELECT statement.
+\end{enumerate}
 
 Even though data can be selected from multiple tables (joins) in your select
 statement, only the base table associated with this wxDbTable object
@@ -3928,3 +3930,204 @@ an introduction to using the ODBC classes.
 Simply initializes all member variables to a cleared state.  Called by
 the constructor automatically.
 
+\section{\class{wxDbGridColInfo}}\label{wxdbgridcolinfo}
+
+This class is used  to define columns to be shown, names of the columns,
+order and type of data, when using \helpref{wxdbGridTableBase}{wxdbgridtablebase} to display
+a Table or query in a \helpref{wxGrid}{wxgrid}
+
+See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} for
+an introduction to using the wxDbGrid classes.
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbGridColInfo::wxDbGridColInfo}\label{wxdbgridcolinfo}
+
+\func{}{wxDbGridColInfo}{\param{int }{colNo}, \param{wxString }{type},
+  \param{wxString }{title}, \param{wxDbGridColInfo *}{next}}
+
+Default constructor. See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+
+\wxheading{Parameters}
+
+\docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
+\docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
+ use wxGRID_VALUE_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
+\docparam{title}{The column label to be used in the grid display}
+\docparam{next}{A pointer to the next wxDbGridColInfo structure if using one-step
+construction, NULL  terminates the list. Use Null also if using two step construction.}
+See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+\membersection{wxDbGridColInfo::\destruct{wxDbGridColInfo}}
+
+\func{}{\destruct{wxDbGridColInfo}}{}
+
+Destructor.
+
+\membersection{wxDbGridColInfo::AddColInfo}\label{wxdbgridcolinfoaddcolinfo}
+
+\func{void}{AddColInfo}{\param{int }{colNo},
+\param{wxString }{type}, \param{wxString }{title}}
+
+Use this member function for adding columns. See the database
+grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+It is important to note that this class is merely a specifier to the \helpref{wxDbGridTableBase}{wxdbgridtablebase} 
+constructor. Changes made to this datatype after the \helpref{wxDbGridTableBase}{wxdbgridtablebase} is called will
+not have any effect.
+
+\wxheading{Parameters}
+\docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
+\docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
+ use wxGRID_VALUE_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
+\docparam{title}{The column label to be used in the grid display}
+
+\wxheading{Remarks}
+
+As wxDbTable must be defined with to have columns which match those  to by a wxDbGridColInfo
+info structure as this is the structure which informs the grid of how you want to display your 
+\helpref{wxDbTable}{wxdbtable}. If no datatype conversion or the referenced column number does not exist the
+the behavior is undefined.
+
+See the example at \helpref{wxDbGridColInfo::wxDbGridColInfo}{wxdbgridcolinfo}.
+
+\section{\class{wxDbGridTableBase}}\label{wxdbgridtablebase}
+
+You can view a database table in a grid using this class.
+
+If you are deriving your own wxDbTable subclass for your table , then you may consider
+overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
+be taken when using wxDbGridTableBase in this way.
+
+The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
+object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
+when an new on is assigned or wxGridTableBase's destructor is called.
+However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true); 
+is  an error. If you need to requery an table object the preferred way is
+that the client keeps ownership.
+
+\wxheading{Derived From}
+
+\helpref{wxGridTableBase}{wxgridtablebase}
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+
+\wxheading{Example}
+
+\begin{verbatim}
+	// First step, let's define wxDbTable
+	int numColumns = 2;
+	wxDbTable *table = new wxDbTable (db, tblName, numColumns);
+	int int_var;
+	wxChar string_name[255];
+	table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
+			SQL_C_LONG, sizeof(int_var), TRUE);
+	table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
+			SQL_C_LONG, sizeof(string_name), FALSE);
+
+    // now let's define columns in the grid
+
+    // first way to do it
+    wxDbGridColInfo *columns;
+    columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
+              new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
+              NULL);
+
+    // second way to do it
+    wxDbGridColInfo *columns;
+    // first column is special
+    columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
+    // all the rest
+    columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
+
+    // second way may be better when columns are not known at compile time
+
+    // now, let's open the table and make a Query()
+    table->Open();
+    // this step is very important
+    table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
+    // in the grid we will see only the rows of the result query
+    m_dbTable->Query();
+
+    wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, TRUE);
+    delete columns;  // not needed anymore
+    wxGrid *grid = new wxGrid ( ... );
+    grid->SetTable(dbgrid, TRUE);
+    grid->Fit();
+\end{verbatim}
+
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+\wxheading{Helper classes and data structures}
+
+\membersection{wxDbGridTableBase::wxDbGridTableBase}\label{wxdbgridtablebaseconstr}
+
+\func{}{wxDbGridTableBase}{\param{wxDbTable *}{tab}, \param{wxDbGridColInfo *}{ColInfo},
+  \param{int }{count = wxUSE_QUERY}, \param{bool }{takeOwnership = TRUE}}
+
+Constructor.
+
+\wxheading{Parameters}
+
+\docparam{tab}{ The database table you want to display. Must be opened and queried before display the grid.
+See the example \helpref{above}{wxdbgridtablebase}.}
+\docparam{ColInfo}{ Columns titles, and other values. See \helpref{wxDbGridColInfo}{wxdbgridcolinfo}.}
+\docparam{count}{You can use a query result set (wxUSE_QUERY, to use wxDbTable::Count(wxDbTable::Count() 
+ or you can fix the total number of rows (count >= 0) to display, or specify it if you already know the size in avoid calling }
+
+\docparam{takeOwnership}{ If TRUE, this class deletes wxDbTable when it stops
+referring to it, if FALSE application must
+take care of deleting it.  }
+
+\membersection{wxDbGridTableBase::ValidateRow}\label{wxdbgridtablebasevalidate}
+
+\func{void}{ValidateRow}{\param{int }{row}}
+
+It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
+the row number passed should be the grid row.
+
+\wxheading{Parameters}
+
+\docparam{row}{ Row where validation must be done. }
+
+\membersection{wxDbGridTableBase::UpdateRow}\label{wxdbgridtablebaseupdaterow}
+
+\func{bool}{UpdateRow}{\param{int }{row}}
+
+If row has changed it forces that row to be written back to the database, however support
+for detecting whether insert/update is required is currently not in wxDbTable, so this 
+function is currently unsupported.
+
+\wxheading{Parameters}
+
+\docparam{row}{ Row you want to update. }
+
+\membersection{wxDbGridTableBase::AssignDbTable}\label{wxdbgridtablebaseassigndbtable}
+
+\func{bool}{AssignDbTable}{\param{wxDbTable *}{tab},\param{int }{count = wxUSE_QUERY},
+\param{bool }{takeOwnership = TRUE}}
+
+Resets the grid for using with a new database table, but using the same columns definition.
+This can be useful when re-querying the database and want to see the changes. 
+
+\wxheading{Parameters}
+
+\docparam{tab}{ Database table you want to assign to the grid. }
+\docparam{count}{ Number of rows you want to show or wxUSE_QUERY for using a query. }
+\docparam{takeOwnership}{ If FALSE, user must take care of deleting tab after deleting
+the wxDbGridTableBase. If TRUE, deletion is made by destructor class. }
+
