X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2edb0bdef6238c8c246b6978bc14828b7033d931..fcf77487edae715c75f0f802a96e203d88dd56c6:/docs/latex/wx/db.tex

diff --git a/docs/latex/wx/db.tex b/docs/latex/wx/db.tex
index 807f9b9a38..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}
@@ -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
@@ -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. }
+
