From 9ee2d31ccc6741b8af6b30fb2ca8992699d3a2ed Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Wed, 30 Sep 1998 00:48:01 +0000 Subject: [PATCH] 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 --- docs/latex/wx/log.tex | 185 ++++++++++++++++++++++++++++++++++++++ docs/latex/wx/tconfig.tex | 50 +++++++++++ 2 files changed, 235 insertions(+) create mode 100644 docs/latex/wx/log.tex create mode 100644 docs/latex/wx/tconfig.tex diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex new file mode 100644 index 0000000000..f6d877de56 --- /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 index 0000000000..1c5b11a0ab --- /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. -- 2.45.2