AuroraMiddleware/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

wxLog and wxConfig docs update

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@748 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin 1998-09-17 20:57:08 +00:00
parent 9da0d96f87
commit 5f3cd8a22a
3 changed files with 247 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
docs/latex/wx/config.tex
View File

@ -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
%features of this class.
See \helpref{config overview}{wxconfigoverview} for the descriptions of all
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},
The config classes support a file system-like hierarchy of keys (files) and groups (directories).
As explained in \helpref{config overview}{wxconfigoverview}, the config classes
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
use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The application name
is used in the registry key on Windows, and can be used to deduce the local filename
parameter if that is missing.}
\docparam{appName}{The application name. If this is empty, the class will
normally use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The
application name is used in the registry key on Windows, and can be used to
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
present, but required, the application name will be used instead.}
\docparam{localFilename}{Some config classes require a local filename. If this
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
present, but required, the application name will be used instead.}
\docparam{globalFilename}{Some config classes require a global filename. If
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.
The style interpretation depends on the config class and is ignored by some.
For wxFileConfig, these styles determine whether a local or global config file is created or used.
If the flag is present but 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.}
\docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
class and is ignored by some. For wxFileConfig, these styles determine whether
a local or global config file is created or used. If the flag is present but
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
defaults is off.
By default, environment variable expansion is on and recording defaults is
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
comments near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns
the created object and also sets it as the current one.
implementation of wxConfig available for the current platform, see comments
near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns the
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
it was the last key in it and the second parameter is true.
Deletes the specified entry and the group it belongs to if it was the last key
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
its subgroups.
Get number of entries/subgroups in the current group, with or without its
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
found, {\it str} is not changed.
Read a string from the key, returning TRUE if the value was read. If the key
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
found. If the value was not found, {\it l} is not changed.
Reads a long value, returning TRUE if the value was found. If the value was
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
found. If the value was not found, {\it defaultVal} is used instead.
Reads a long value, returning TRUE if the value was found. If the value was
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
found.
Reads a long value from the key and returns it. {\it defaultVal} is returned
if the key is not found.
NB: writing
{\small
\begin{verbatim}
conf->Read("key", 0);
\end{verbatim}
}
{\small \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
\begin{verbatim}
conf->Read("key", 0l);
\end{verbatim}
}
{\small \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
found. If the value was not found, {\it d} is not changed.
Reads a double value, returning TRUE if the value was found. If the value was
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
found. If the value was not found, {\it defaultVal} is used instead.
Reads a double value, returning TRUE if the value was found. If the value was
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
found. If the value was not found, {\it b} is not changed.
Reads a bool value, returning TRUE if the value was found. If the value was
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
found. If the value was not found, {\it defaultVal} is used instead.
Reads a bool value, returning TRUE if the value was found. If the value was
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
doesn't exist it is created.
otherwise it's a relative path. '..' is supported. If the strPath doesn't
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
the user to see what config options may be changed and is probably useful only
for wxFileConfig.
If on (default is off) all default values are written back to the config file.
This allows the user to see what config options may be changed and is probably
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
return TRUE on success.
These functions write the specified value to the config file and return TRUE
on success.

158
docs/latex/wx/tlog.tex Normal file
View File

@ -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}

2
docs/latex/wx/topics.tex
View File

@ -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