more wxConfig and xwLog docs (sorry for the delay)

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

diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex
new file mode 100644 (file)
index 0000000..f6d877d
--- /dev/null
+++ b/docs/latex/wx/log.tex
@@ -0,0 +1,185 @@
+\section{\class{wxLog}}\label{wxlog}
+
+wxLog class defines the interface for the {\it log targets} used by wxWindows
+logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}.
+The only situations when you need to directly use this class is when you want
+to derive your own log target because the existing ones don't satisfy your
+needs. Another case is if you wish to customize the behaviour of the standard
+logging classes (all of which respect the wxLog settings): for example, set
+which trace messages are logged and which are not or change (or even remove
+completely) the timestamp on the messages.
+
+Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and
+you may not even know about its existence.
+
+See \helpref{log overview}{wxlogoverview} for the descriptions of wxWindows
+logging facilities.
+
+\wxheading{Derived from}
+
+No base class
+
+\latexignore{\rtfignore{\wxheading{Function groups}}}
+
+\membersection{Static functions}
+
+The functions in this section work with and manipulate the active log target.
+The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the
+{\it DoLog()} of the active log target if any. Get/Set methods are used to
+install/query the current active target and, finally, {\it
+DontCreateOnDemand()} disables the automatic creation of a standard log target
+if none actually exists. It is only useful when the application is terminating
+and shouldn't be used in other situations because it may easily lead to a loss
+of messages.
+
+\helpref{OnLog}{wxlogonlog}\\
+\helpref{GetActiveTarget}{wxloggetactivetarget}\\
+\helpref{SetActiveTarget}{wxsetactivetarget}\\
+\helpref{DontCreateOnDemand}{wxlogdontcreateondemand}
+
+\membersection{Message buffering}
+
+Some of wxLog implementations, most notably the standard
+\helpref{wxLogGui}{wxloggui} class, buffer the messages (for example, to avoid
+showing the user a zillion of modal message boxes one after another - which
+would be really annoying). {\it Flush()} shows them all and clears the buffer
+contents. Although this function doesn't do anything if the buffer is already
+empty, {\it HasPendingMessages()} is also provided which allows to explicitly
+verify it.
+
+\helpref{Flush}{wxlogflush}\\
+\helpref{HasPendingMessages}{haspendingmessages}
+
+\membersection{Customization}{wxlogcustomization}
+
+The functions below allow some limited customization of wxLog behaviour
+without writing a new log target class (which, aside of being a matter of
+several minutes, allows you to do anything you want).
+
+The verbose messages are the trace messages which are not disabled in the
+release mode and are generated by {\it wxLogVerbose()}. They are not normally
+shown to the user because they present little interest, but may be activated,
+for example, in order to help the user find some program problem.
+
+As for the (real) trace messages, they come in different kinds:
+\begin{itemize}\itemsep=0pt
+\item{wxTraceMemAlloc} for the messages about creating and deleting objects
+\item{wxTraceMessages} for tracing the windowing system messages/events
+\item{wxTraceResAlloc} for allocating and releasing the system ressources
+\item{wxTraceRefCount} for reference counting related messages
+\item{wxTraceOleCalls} for the OLE (or COM) method invocations (wxMSW only)
+\item{other} the remaining bits are free for user-defined trace levels
+\end{itemize}
+
+The trace mask is a bit mask which tells which (if any) of these trace
+messages are going to be actually logged. For the trace message to appear
+somewhere, all the bits in the mask used in the call to {\it wxLogTrace()}
+function must be set in the current trace mask. For example,
+\begin{verbatim}
+wxLogTrace(wxTraceRefCount | wxTraceOle, "Active object ref count: %d", nRef);
+\end{verbatim}
+will do something only if the current trace mask contains both wxTraceRefCount
+and wxTraceOle.
+
+Finally, the {\it wxLog::DoLog()} function automatically prepends a time stamp
+to all the messages. The format of the time stamp may be changed: it can be
+any string with \% specificators fully described in the documentation of the
+standard {\it strftime()} function. For example, the default format is
+"[\%d/\%b/\%y \%H:\%M:\%S] " which gives something like "[17/Sep/98 22:10:16] "
+(without quotes) for the current date. Setting an empty string as the time
+format disables timestamping of the messages completely.
+
+\helpref{SetVerbose}{wxlogsetverbose}\\
+\helpref{GetVerbose}{wxloggetverbose}\\
+\helpref{SetTimeStampFormat}{wxlogsettimestampformat}\\
+\helpref{GetTimeStampFormat}{wxloggettimestampformat}\\
+\helpref{SetTraceMask}{wxlogsettracemask}\\
+\helpref{GetTraceMask}{wxloggettracemask}
+
+%%%%% MEMBERS HERE %%%%%
+\helponly{\insertatlevel{2}{
+
+\wxheading{Members}
+
+}}
+
+\membersection{wxLog::OnLog}\label{wxlogonlog}
+
+\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}}
+
+Forwards the message at specified level to the {\it DoLog()} function of the
+active log target if there is any, does nothing otherwise.
+
+\membersection{wxLog::GetActiveTarget}\label{wxloggetactivetarget}
+
+\func{static wxLog *}{GetActiveTarget}{\void}
+
+Returns the pointer to the active log target (may be NULL).
+
+\membersection{wxLog::SetActiveTarget}\label{wxlogsetactivetarget}
+
+\func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}}
+
+Sets the specified log target as the active one. Returns the pointer to the
+previous active log target (may be NULL).
+
+\membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand}
+
+\func{static void}{DontCreateOnDemand}{\void}
+
+Instructs wxLog to not create new log targets on the fly if there is none
+currently. (Almost) for internal use only.
+
+\membersection{wxLog::Flush}{wxlogflush}
+
+\func{virtual void}{Flush}{\void}
+
+Shows all the messages currently in buffer and clears it. If the buffer
+is already empty, nothing happens.
+
+\membersection{wxLog::HasPendingMessages}{haspendingmessages}
+
+\constfunc{bool}{HasPendingMessages}{\void}
+
+Returns true if there are any messages in the buffer (not yet shown to the
+user). (Almost) for internal use only.
+
+\membersection{wxLog::SetVerbose}{wxlogsetverbose}
+
+\func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}}
+
+Activates or desactivates verbose mode in which the verbose messages are
+logged as the normal ones instead of being silently dropped.
+
+\membersection{wxLog::GetVerbose}{wxloggetverbose}
+
+\constfunc{bool}{GetVerbose}{\void}
+
+Returns whether the verbose mode is currently active.
+
+\membersection{wxLog::SetTimeStampFormat}{wxlogsettimestampformat}
+
+\func{void}{SetTimeStampFormat}{\param{const char * }{ format}}
+
+Sets the timestamp format prepended by the default log targets to all
+messages. The string may contain any normal characters as well as \%
+prefixed format specificators, see {\it strftime()} manual for details.
+Passing an empty string to this function disables message timestamping.
+
+\membersection{wxLog::GetTimeStampFormat}{wxloggettimestampformat}
+
+\constfunc{const char *}{GetTimeStampFormat}{\void}
+
+Returns the current timestamp format string.
+
+\membersection{wxLog::SetTraceMask}{wxlogsettracemask}
+
+\func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}}
+
+Sets the trace mask, see \helpref{Customization}{wxlogcustomization}
+section for details.
+
+\membersection{wxLog::GetTraceMask}{wxloggettracemask}
+
+Returns the current trace mask, see \helpref{Customization}{wxlogcustomization}
+section for details.

diff --git a/docs/latex/wx/tconfig.tex b/docs/latex/wx/tconfig.tex
new file mode 100644 (file)
index 0000000..1c5b11a
--- /dev/null
+++ b/docs/latex/wx/tconfig.tex
@@ -0,0 +1,50 @@
+\section{Config classes overview}\label{wxconfigoverview}
+
+Classes: \helpref{wxConfig}{wxconfig}, \helpref{wxConfigBase}{wxconfigbase},
+\helpref{wxRegConfig}{wxregconfig}, \helpref{wxFileConfig}{wxfileconfig},
+\helpref{wxIniConfig}{wxiniconfig}
+
+This overview briefly describes what the config classes are and what are the
+for. All the details about how to use them may be found in the description of
+the \helpref{wxConfigBase}{wxconfigbase} class and the documentation of the
+file, registry and INI file based implementations mentions all the
+features/limitations specific to each one of these versions.
+
+The config classes provide a way to store some application configuration
+information. They were especially designed for this usage and, although may
+probably be used for many other things as well, should be limited to it. It
+means that this information should be:
+\begin{itemize}
+\item{1.} Typed, i.e. strings or numbers for the moment. You can not store
+binary data, for example.
+\item{2.} Small. For instance, it is not recommended to use the Windows
+registry for amounts of data more than a couple of kilobytes.
+\item{3.} Not performance critical, neither from speed nor from memory
+consumption point of view.
+\end{itemize}
+
+On the other hand, the provided features make them very useful for storing all
+kind of small to medioum volumes of hierarchically organized heterogenous
+data. In short, this is a place where you can conveniently stuff all your data
+(numbers and strings) organizing it in a tree where you use the
+filesystem-like paths to specify the location of a piece of data. In
+particular, these classes were designed to be as easy to use as possible.
+
+From another point of view, they provide an interface which hides the
+differences between the Windows registry and the standard Unix text format
+configuration files. Other (future) implementations of wxConfigBase might also
+understand GTK ressource files or their analogues on the KDE side.
+
+In any case, each implementation of wxConfigBase does its best (although due
+to the limitations of the underlying physical storage as in the case of
+wxIniConfigs it may not implement 100\% of the base class functionality) to
+make the data look the same way everywhere. So you have the groups of entries
+and the entries themselves. Each entry contains either a string or a number
+(or a boolean value... support for other types of data such as dates or
+timestamps is planned) and is identified by the full path to it: something
+like /MyApp/UserPreferences/Colors/Foreground. The previous elements in the
+path are the group names, each name may contain an arbitrary number of entries
+and subgroups. The path components are {\bf always} separated with a slash,
+even though some implementations use the backslash internally. The further
+details (including how to read/write these entries) may be found in
+\helpref{wxConfigBase}{wxconfigbase} documentation.