wxLog and wxConfig docs update

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@748 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/config.tex

@@ -2,7 +2,8 @@
 
 wxConfigBase class defines the basic interface of all config classes. It can
 not be used by itself (it's an abstract base class) and you'll always use one
-of its derivations: wxIniConfig, wxFileConfig, wxRegConfig or
+of its derivations: \helpref{wxIniConfig}{wxiniconfig},
+\helpref{wxFileConfig}{wxfileconfig}, \helpref{wxRegConfig}{wxregconfig} or
 any other.
 
 However, usually you don't even need to know the precise nature of the class
@@ -15,8 +16,8 @@ which is mapped onto the native wxConfigBase implementation on the given
 platform: i.e. wxRegConfig under Win32, wxIniConfig under Win16 and
 wxFileConfig otherwise.
 
-%See \helpref{config overview}{configoverview} for the descriptions of all
+See \helpref{config overview}{wxconfigoverview} for the descriptions of all
-%features of this class.
+features of this class.
 
 \wxheading{Derived from}
 
@@ -98,8 +99,8 @@ disable this behaviour {\it DontCreateOnDemand()} is provided.
 
 \membersection{Path management}
 
-%As explained in \helpref{config overview}{configoverview},
+As explained in \helpref{config overview}{wxconfigoverview}, the config classes
-The config classes support a file system-like hierarchy of keys (files) and groups (directories).
+support a file system-like hierarchy of keys (files) and groups (directories).
 As in the file system case, to specify a key in the config class you must use
 a path to it. Config classes also support the notion of the current group,
 which makes it possible to use the relative paths. To clarify all this, here
@@ -315,35 +316,38 @@ The following functions control this option:
  \param{const wxString\& }{globalFilename = wxEmptyString},
  \param{long}{ style = 0}}
 
-This is the default and only constructor of the wxConfigBase class, and derived classes.
+This is the default and only constructor of the wxConfigBase class, and
+derived classes.
 
 \wxheading{Parameters}
 
-\docparam{appName}{The application name. If this is empty, the class will normally
+\docparam{appName}{The application name. If this is empty, the class will
-use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The application name
+normally use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The
-is used in the registry key on Windows, and can be used to deduce the local filename
+application name is used in the registry key on Windows, and can be used to
-parameter if that is missing.}
+deduce the local filename parameter if that is missing.}
 
 \docparam{vendorName}{The vendor name. If this is empty, it is assumed that
 no vendor name is wanted, if this is optional for the current config class.
 The vendor name is appended to the application name for wxRegConfig.}
 
-\docparam{localFilename}{Some config classes require a local filename. If this is not
+\docparam{localFilename}{Some config classes require a local filename. If this
-present, but required, the application name will be used instead.}
+is not present, but required, the application name will be used instead.}
 
-\docparam{globalFilename}{Some config classes require a global filename. If this is not
+\docparam{globalFilename}{Some config classes require a global filename. If
-present, but required, the application name will be used instead.}
+this is not present, but required, the application name will be used instead.}
 
-\docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and wxCONFIG\_USE\_GLOBAL\_FILE.
+\docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
-The style interpretation depends on the config class and is ignored by some.
+wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
-For wxFileConfig, these styles determine whether a local or global config file is created or used.
+class and is ignored by some. For wxFileConfig, these styles determine whether
-If the flag is present but the parameter is empty, the parameter will be set to a default.
+a local or global config file is created or used. If the flag is present but
-If the parameter is present but the style flag not, the relevant flag will be added to the style.}
+the parameter is empty, the parameter will be set to a default. If the
+parameter is present but the style flag not, the relevant flag will be added
+to the style.}
 
 \wxheading{Remarks}
 
-By default, environment variable expansion is on and recording
+By default, environment variable expansion is on and recording defaults is
-defaults is off.
+off.
 
 \membersection{wxConfigBase::\destruct{wxConfigBase}}\label{wxconfigbasedtor}
 
@@ -356,9 +360,9 @@ Empty but ensures that dtor of all derived classes is virtual.
 \func{static wxConfigBase *}{Create}{\void}
 
 Create a new config object: this function will create the "best"
-implementation of wxConfig available for the current platform, see
+implementation of wxConfig available for the current platform, see comments
-comments near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns
+near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns the
-the created object and also sets it as the current one.
+created object and also sets it as the current one.
 
 \membersection{wxConfigBase::DontCreateOnDemand}\label{wxconfigbasedontcreateondemand}
 
@@ -377,10 +381,11 @@ for use by desinstallation routine.
 
 \membersection{wxConfigBase::DeleteEntry}\label{wxconfigbasedeleteentry}
 
-\func{bool}{DeleteEntry}{\param{const wxString\& }{ key}, \param{bool}{ bDeleteGroupIfEmpty = TRUE}}
+\func{bool}{DeleteEntry}{\param{const wxString\& }{ key}, \param{bool}{
+bDeleteGroupIfEmpty = TRUE}}
 
-Deletes the specified entry and the group it belongs to if
+Deletes the specified entry and the group it belongs to if it was the last key
-it was the last key in it and the second parameter is true.
+in it and the second parameter is true.
 
 \membersection{wxConfigBase::DeleteGroup}\label{wxconfigbasedeletegroup}
 
@@ -416,25 +421,29 @@ Returns the application name.
 
 \membersection{wxConfigBase::GetFirstGroup}\label{wxconfigbasegetfirstgroup}
 
-\constfunc{bool}{GetFirstGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
+\constfunc{bool}{GetFirstGroup}{\param{wxString\& }{str}, \param{long\&}{
+index}}
 
 Gets the first group.
 
 \membersection{wxConfigBase::GetFirstEntry}\label{wxconfigbasegetfirstentry}
 
-\constfunc{bool}{GetFirstEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
+\constfunc{bool}{GetFirstEntry}{\param{wxString\& }{str}, \param{long\&}{
+index}}
 
 Gets the first entry.
 
 \membersection{wxConfigBase::GetNextGroup}\label{wxconfigbasegetnextgroup}
 
-\constfunc{bool}{GetNextGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
+\constfunc{bool}{GetNextGroup}{\param{wxString\& }{str}, \param{long\&}{
+index}}
 
 Gets the next group.
 
 \membersection{wxConfigBase::GetNextEntry}\label{wxconfigbasegetnextentry}
 
-\constfunc{bool}{GetNextEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
+\constfunc{bool}{GetNextEntry}{\param{wxString\& }{str}, \param{long\&}{
+index}}
 
 Gets the next entry.
 
@@ -446,8 +455,8 @@ Gets the next entry.
 
 \constfunc{uint}{GetNumberOfGroups}{\param{bool }{bRecursive = FALSE}}
 
-Get number of entries/subgroups in the current group, with or without
+Get number of entries/subgroups in the current group, with or without its
-its subgroups.
+subgroups.
 
 \membersection{wxConfigBase::GetPath}\label{wxconfigbasegetpath}
 
@@ -487,71 +496,72 @@ Returns TRUE if we are writing defaults back to the config file.
 
 \membersection{wxConfigBase::Read}\label{wxconfigbaseread}
 
-\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}}
+\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{
+str}}
 
-Read a string from the key, returning TRUE if the value was read. If the key was not
+Read a string from the key, returning TRUE if the value was read. If the key
-found, {\it str} is not changed.
+was not found, {\it str} is not changed.
 
-\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}, \param{const wxString\& }{defaultVal}}
+\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{
+str}, \param{const wxString\& }{defaultVal}}
 
-Read a string from the key. The default value is returned if the key was not found.
+Read a string from the key. The default value is returned if the key was not
+found.
 
 Returns TRUE if value was really read, FALSE if the default was used.
 
-\constfunc{wxString}{Read}{\param{const wxString\& }{key}, \param{const wxString\& }{defaultVal}}
+\constfunc{wxString}{Read}{\param{const wxString\& }{key}, \param{const
+wxString\& }{defaultVal}}
 
 Another version of {\it Read()}, returning the string value directly.
 
 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}}
 
-Reads a long value, returning TRUE if the value was
+Reads a long value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it l} is not changed.
+not found, {\it l} is not changed.
 
-\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}, \param{long}{ defaultVal}}
+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l},
+\param{long}{ defaultVal}}
 
-Reads a long value, returning TRUE if the value was
+Reads a long value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it defaultVal} is used instead.
+not found, {\it defaultVal} is used instead.
 
-\constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
+\constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{
+defaultVal}}
 
-Reads a long value from the key and returns it. {\it defaultVal} is returned if the key is not
+Reads a long value from the key and returns it. {\it defaultVal} is returned
-found.
+if the key is not found.
 
 NB: writing
 
-{\small
+{\small \begin{verbatim} conf->Read("key", 0); \end{verbatim} }
-\begin{verbatim}
-  conf->Read("key", 0);
-\end{verbatim}
-}
 
-won't work because the call is ambiguous: compiler can not choose between two {\it Read} functions. Instead, write:
+won't work because the call is ambiguous: compiler can not choose between two
+{\it Read} functions. Instead, write:
 
-{\small
+{\small \begin{verbatim} conf->Read("key", 0l); \end{verbatim} }
-\begin{verbatim}
-  conf->Read("key", 0l);
-\end{verbatim}
-}
 
 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
 
-Reads a double value, returning TRUE if the value was
+Reads a double value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it d} is not changed.
+not found, {\it d} is not changed.
 
-\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}, \param{double}{ defaultVal}}
+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d},
+\param{double}{ defaultVal}}
 
-Reads a double value, returning TRUE if the value was
+Reads a double value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it defaultVal} is used instead.
+not found, {\it defaultVal} is used instead.
 
 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ b}}
 
-Reads a bool value, returning TRUE if the value was
+Reads a bool value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it b} is not changed.
+not found, {\it b} is not changed.
 
-\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ d}, \param{bool}{ defaultVal}}
+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ d},
+\param{bool}{ defaultVal}}
 
-Reads a bool value, returning TRUE if the value was
+Reads a bool value, returning TRUE if the value was found. If the value was
-found. If the value was not found, {\it defaultVal} is used instead.
+not found, {\it defaultVal} is used instead.
 
 \membersection{wxConfigBase::Set}\label{wxconfigbaseset}
 
@@ -577,8 +587,8 @@ Determine whether we wish to expand environment variables in key values.
 \func{void}{SetPath}{\param{const wxString\& }{strPath}}
 
 Set current path: if the first character is '/', it's the absolute path,
-otherwise it's a relative path. '..' is supported. If the strPath
+otherwise it's a relative path. '..' is supported. If the strPath doesn't
-doesn't exist it is created.
+exist it is created.
 
 \membersection{wxConfigBase::SetRecordDefaults}\label{wxconfigbasesetrecorddefaults}
 
@@ -586,9 +596,9 @@ doesn't exist it is created.
 
 Sets whether defaults are written back to the config file.
 
-If on (default is off) all default values are written back to the config file. This allows
+If on (default is off) all default values are written back to the config file.
-the user to see what config options may be changed and is probably useful only
+This allows the user to see what config options may be changed and is probably
-for wxFileConfig.
+useful only for wxFileConfig.
 
 \membersection{wxConfigBase::SetVendorName}\label{wxconfigbasesetvendorname}
 
@@ -598,7 +608,8 @@ Sets the vendor name.
 
 \membersection{wxConfigBase::Write}\label{wxconfigbasewrite}
 
-\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxString\& }{ value}}
+\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxString\& }{
+value}}
 
 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{long}{ value}}
 
@@ -606,7 +617,7 @@ Sets the vendor name.
 
 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
 
-These functions write the specified value to the config file and
+These functions write the specified value to the config file and return TRUE
-return TRUE on success.
+on success.
 
 

docs/latex/wx/tlog.tex

@@ -0,0 +1,158 @@
+\section{Log classes overview}\label{wxlogoverview}
+
+Classes: \helpref{wxLog}wxlog, \helpref{wxLogStderr}wxlogstderr,
+\helpref{wxLogOstream}wxlogostream, \helpref{wxLogTextCtrl}wxlogtextctrl,
+\helpref{wxLogWindow}{wxlogwindow}, \helpref{wxLogGui}{wxloggui},
+\helpref{wxLogNull}{wxlognull}
+
+This is a general overview of logging classes provided by wxWindows. The word
+logging here has a broad sense, including all of the program output, not only
+non interactive messages. The logging facilities included in wxWindows provide
+the base {\it wxLog} class which defines the standard interface for a {\it log
+target} as well as several standard implementations of it and a family of
+functions to use with them.
+
+First of all, no knowledge of {\it wxLog} classes is needed to use them. For
+this, you should only know about {\it wxLogXXX()} functions. All of them have
+the same syntax as {\it printf()}, i.e. they take the format string as the
+first argument and a variable number of arguments. Here are all of them:
+\begin{itemize}\itemsep=0pt
+\item{\bf wxLogFatalError} which is like {\it wxLogError}, but also
+terminates the program with the exit code 3 (using {\it abort()} standard
+function also terminates the program with this exit code).
+
+\item{\bf wxLogError} is the function to use for error messages, i.e. the
+messages that must be shown to the user. The default processing is to pop up a
+message box to inform the user about it.
+
+\item{\bf wxLogWarning} for warnings - they are also normally shown to the
+user, but don't interrupt the program work.
+
+\item{\bf wxLogMessage} is for all normal, informational messages. They also
+appear in a message box by default (but it can be changed, see below). Notice
+that the standard behaviour is to not show informational messages if there are
+any errors later - the logic being that the later error messages make the
+informational messages preceding them meaningless.
+
+\item{\bf wxLogVerbose} is for verbose output. Normally, it's suppressed, but
+might be activated if the user wishes to know more details about the program
+progress (another, but possibly confusing name for the same function is {\bf
+wxLogInfo}
+
+\item{\bf wxLogStatus} is for status messages - they will go into the status
+bar of the active or specified (as the first argument)
+\helpref{wxFrame}{wxframe} if it has one.
+
+\item{\bf wxLogSysError} is mostly used by wxWindows itself, but might be
+handy for logging errors after system call (API function) failure. It logs the
+specified message text as well as the last system error code ({\it errno} or
+{\it ::GetLastError()} depending on the platform) and the corresponding error
+message. The second form of this function takes the error code explitly as the
+first argument.
+
+\item{\bf wxLogDebug} is {\bf the} right function for debug output. It only
+does anything at all in the debug mode (when the preprocessor symbol
+\_\_WXDEBUG\_\_ is defined) and expands to nothing in release mode (otherwise).
+
+\item{\bf wxLogTrace} as {\bf wxLogDebug} only does something in debug
+build. The reason for making it a separate function from it is that usually
+there are a lot of trace messages, so it might make sense to separate them
+from other debug messages which would be flooded in them. Moreover, the second
+version of this function takes a trace mask as the first argument which allows
+to further restrict the amount of messages generated.
+
+\end{itemize}
+
+% VZ: Julian, am I pushing too much here?
+The usage of these functions should be fairly straightforward, however it may
+be asked why not use the other logging facilities, such as C standard stdio
+functions or C++ streams. The short answer is that they're all very good
+generic mechanisms, but are not really adapted for wxWindows, while the log
+classes are. Some of advantages in using wxWindows log functions are:
+\begin{itemize}\itemsep=0pt
+
+\item{Portability} It's a common practice to use {\it printf()} statements or
+cout/cerr C++ streams for writing out some (debug or otherwise) information.
+Although it works just fine under Unix, these messages go strictly nowever
+under Windows where the stdout of GUI programs is not assigned to anything.
+Thus, you might view {\it wxLogMessage()} as a simple substitute for {\it
+printf()}.
+
+\item{Flexibility} The output of wxLog functions can be redirected or
+suppressed entirely based on their importance, which is either impossible or
+difficult to do with traditional methods. For example, only error messages, or
+only error messages and warnings might be logged, filtering out all
+informational messages.
+
+\item{Comlpeteness} Usually, an error message should be presented to the user
+when some operation fails. Let's take a quite simple but common case of a file
+error: suppose that you're writing your data file on disk and there is not
+enough space. The actual error might have been detected inside wxWindows code
+(say, in {\it wxFile::Write}), so the calling function doesn't really know the
+exact reason of the failure, it only knows that the data file couldn't be
+written to the disk. However, as wxWindows uses {\it wxLogError()} in this
+situation, the exact error code (and the corresponding error message) will be
+given to the user together with "high level" message about data file writing
+error.
+
+\end{itemize}
+
+After having enumerated all the functions which are normally used to log the
+messages, and why would you want to use them we now describe how all this
+works.
+
+wxWindows has the notion of a {\it log target}: it's just a class deriving
+from \helpref{wxLog}{wxlog}. As such, it implements the virtual functions of
+the base class which are called when a message is logged. Only one log target
+is {\it active} at any moment, this is the one used by \it{wxLogXXX()}
+functions. The normal usage of a log object (i.e. object of a class derived
+from wxLog) is to install it as the active target with a call to {\it
+SetActiveTarget()} and it will be used automatically by all subsequent calls
+to {\it wxLogXXX()} functions.
+
+To create a new log target class you only need to derive it from wxLog and
+implement one (or both) of {\it DoLog()} and {\it DoLogString()} in it. The
+second one is enough if you're happy with the standard wxLog message
+formatting (prepending "Error:" or "Warning:", timestamping \&c) but just want
+to send the messages somewhere else. The first one may be overridden to do
+whatever you want but you have to distinguish between the different message
+types yourself.
+
+There are some predefined classes deriving from wxLog and which might be
+helpful to see how you can create a new log target class and, of course, may
+also be used without any change. There are:
+\begin{itemize}\itemsep=0pt
+\item{\bf wxLogStderr} This class logs messages to a {\it FILE *}, using
+stderr by default as its name suggests.
+
+\item{\bf wxLogStream} This class has the same functionality as wxLogStderr,
+but uses {\it ostream} and cerr instead of {\it FILE *} and stderr.
+
+\item{\bf wxLogGui} This is the standard log target for wxWindows
+applications (it's used by default if you don't do anything) and provides the
+most reasonable handling of all types of messages for given platform.
+
+\item{\bf wxLogWindow} This log target provides a "log console" which
+collects all messages generated by the application and also passes them to the
+previous active log target. The log window frame has a menu allowing user to
+clear the log, close it completely or save all messages to file.
+
+\item{\bf wxLogNull} The last log class is quite particular: it doesn't do
+anything. The objects of this class may be instantiated to (temporarily)
+suppress output of {\it wxLogXXX()} functions. As an example, trying to open a
+non-existing file will usually provoke an error message, but if you for some
+reason it's unwanted, just use this construction:
+\begin{verbatim}
+  wxFile file;
+
+  // wxFile.Open() normally complains if file can't be opened, we don't want it
+  {
+    wxLogNull logNo;
+    if ( !file.Open("bar") )
+      ... process error ourselves ...
+  } // ~wxLogNull called, old log sink restored
+  
+  wxLogMessage("..."); // ok
+\end{verbatim}
+
+\end{itemize}

docs/latex/wx/topics.tex

@@ -5,6 +5,8 @@
 This chapter contains a selection of topic overviews.
 
 \input tapp.tex
+\input tlog.tex
+\input tconfig.tex
 \input tbitmap.tex
 \input tdialog.tex
 \input tfont.tex