+\normalbox{Please note that this use of the word `resource' is different from that used when talking
+about initialisation file resource reading and writing, using such functions
+as wxWriteResource and wxGetResource. It is just an unfortunate clash of terminology.}
+
+\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
+
+See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
+loading from resource data.
+
+\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
+
+\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
+
+Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
+{\tt\#}defining a name to an integer). Unlikely to be used by an application except
+perhaps for implementing resource functionality for interpreted languages.
+
+\membersection{::wxResourceClear}\label{wxresourceclear}
+
+\func{void}{wxResourceClear}{\void}
+
+Clears the wxWindows resource table.
+
+\membersection{::wxResourceCreateBitmap}\label{wxresourcecreatebitmap}
+
+\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
+
+Creates a new bitmap from a file, static data, or Windows resource, given a valid
+wxWindows bitmap resource identifier. For example, if the .WXR file contains
+the following:
+
+\begin{verbatim}
+static const wxString\& project_resource = "bitmap(name = 'project_resource',\
+ bitmap = ['project', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
+ bitmap = ['project.xpm', wxBITMAP_TYPE_XPM, 'X']).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxBitmap *bitmap = wxResourceCreateBitmap("project_resource");
+\end{verbatim}
+
+\membersection{::wxResourceCreateIcon}\label{wxresourcecreateicon}
+
+\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
+
+Creates a new icon from a file, static data, or Windows resource, given a valid
+wxWindows icon resource identifier. For example, if the .WXR file contains
+the following:
+
+\begin{verbatim}
+static const wxString\& project_resource = "icon(name = 'project_resource',\
+ icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
+ icon = ['project', wxBITMAP_TYPE_XBM_DATA, 'X']).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxIcon *icon = wxResourceCreateIcon("project_resource");
+\end{verbatim}
+
+\membersection{::wxResourceCreateMenuBar}\label{wxresourcecreatemenubar}
+
+\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
+
+Creates a new menu bar given a valid wxWindows menubar resource
+identifier. For example, if the .WXR file contains the following:
+
+\begin{verbatim}
+static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
+ menu = \
+ [\
+ ['&File', 1, '', \
+ ['&Open File', 2, 'Open a file'],\
+ ['&Save File', 3, 'Save a file'],\
+ [],\
+ ['E&xit', 4, 'Exit program']\
+ ],\
+ ['&Help', 5, '', \
+ ['&About', 6, 'About this program']\
+ ]\
+ ]).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
+\end{verbatim}
+
+
+\membersection{::wxResourceGetIdentifier}\label{wxresourcegetidentifier}
+
+\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
+
+Used for retrieving the integer value associated with an identifier.
+A zero value indicates that the identifier was not found.
+
+See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
+
+\membersection{::wxResourceParseData}\label{wxresourcedata}
+
+\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
+
+Parses a string containing one or more wxWindows resource objects. If
+the resource objects are global static data that are included into the
+C++ program, then this function must be called for each variable
+containing the resource data, to make it known to wxWindows.
+
+{\it resource} should contain data in the following form:
+
+\begin{verbatim}
+dialog(name = 'dialog1',
+ style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
+ title = 'Test dialog box',
+ x = 312, y = 234, width = 400, height = 300,
+ modal = 0,
+ control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
+ control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
+ 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
+\end{verbatim}
+
+This function will typically be used after including a {\tt .wxr} file into
+a C++ program as follows:
+
+\begin{verbatim}
+#include "dialog1.wxr"
+\end{verbatim}
+
+Each of the contained resources will declare a new C++ variable, and each
+of these variables should be passed to wxResourceParseData.
+
+\membersection{::wxResourceParseFile}\label{wxresourceparsefile}
+
+\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
+
+Parses a file containing one or more wxWindows resource objects
+in C++-compatible syntax. Use this function to dynamically load
+wxWindows resource data.
+
+\membersection{::wxResourceParseString}\label{wxresourceparsestring}
+
+\func{bool}{wxResourceParseString}{\param{char *}{s}, \param{wxResourceTable *}{table = NULL}}
+
+Parses a string containing one or more wxWindows resource objects. If
+the resource objects are global static data that are included into the
+C++ program, then this function must be called for each variable
+containing the resource data, to make it known to wxWindows.
+
+{\it resource} should contain data with the following form:
+
+\begin{verbatim}
+dialog(name = 'dialog1',
+ style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
+ title = 'Test dialog box',
+ x = 312, y = 234, width = 400, height = 300,
+ modal = 0,
+ control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
+ control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
+ 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
+\end{verbatim}
+
+This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
+load an entire {\tt .wxr file} into a string.
+
+\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
+
+\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char *}{xbm\_data}, \param{int }{width},
+\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
+
+\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char **}{xpm\_data}}
+
+Makes {\tt\#}included XBM or XPM bitmap data known to the wxWindows resource system.
+This is required if other resources will use the bitmap data, since otherwise there
+is no connection between names used in resources, and the global bitmap data.
+
+\membersection{::wxResourceRegisterIconData}\label{wxresourceregistericondata}
+
+Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
+
+\section{Log functions}\label{logfunctions}
+
+These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
+further information. The functions use (implicitly) the currently active log
+target, so their descriptions here may not apply if the log target is not the
+standard one (installed by wxWindows in the beginning of the program).
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\membersection{::wxDebugMsg}\label{wxdebugmsg}
+
+\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log
+functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular.
+
+Display a debugging message; under Windows, this will appear on the
+debugger command window, and under Unix, it will be written to standard
+error.
+
+The syntax is identical to {\bf printf}: pass a format string and a
+variable list of arguments.
+
+{\bf Tip:} under Windows, if your application crashes before the
+message appears in the debugging window, put a wxYield call after
+each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
+(at least for Watcom C++): preformat your messages and use OutputDebugString
+instead.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxError}\label{wxerror}
+
+\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
+
+{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
+instead.
+
+Displays {\it msg} and continues. This writes to standard error under
+Unix, and pops up a message box under Windows. Used for internal
+wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxFatalError}\label{wxfatalerror}
+
+\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
+
+{\bf NB:} This function is now obsolete, please use
+\helpref{wxLogFatalError}{wxlogfatalerror} instead.
+
+Displays {\it msg} and exits. This writes to standard error under Unix,
+and pops up a message box under Windows. Used for fatal internal
+wxWindows errors. See also \helpref{wxError}{wxerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxLogError}\label{wxlogerror}
+
+\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+The functions 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.
+
+\membersection{::wxLogFatalError}\label{wxlogfatalerror}
+
+\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+Like \helpref{wxLogError}{wxlogerror}, but also
+terminates the program with the exit code 3. Using {\it abort()} standard
+function also terminates the program with this exit code.
+
+\membersection{::wxLogWarning}\label{wxlogwarning}
+
+\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For warnings - they are also normally shown to the user, but don't interrupt
+the program work.
+
+\membersection{::wxLogMessage}\label{wxlogmessage}
+
+\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For all normal, informational messages. They also appear in a message box by
+default (but it can be changed). 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.
+
+\membersection{::wxLogVerbose}\label{wxlogverbose}
+
+\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For verbose output. Normally, it is 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}).
+
+\membersection{::wxLogStatus}\label{wxlogstatus}
+
+\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+Messages logged by these functions will appear in the statusbar of the {\it
+frame} or of the top level application window by default (i.e. when using
+the second version of the functions).
+
+If the target frame doesn't have a statusbar, the message will be lost.
+
+\membersection{::wxLogSysError}\label{wxlogsyserror}
+
+\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+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 explicitly as the first argument.
+
+\wxheading{See also}
+
+\helpref{wxSysErrorCode}{wxsyserrorcode},
+\helpref{wxSysErrorMsg}{wxsyserrormsg}
+
+\membersection{::wxLogDebug}\label{wxlogdebug}
+
+\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+The right functions for debug output. They only do something in debug
+mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to
+nothing in release mode (otherwise).
+
+\membersection{::wxLogTrace}\label{wxlogtrace}
+
+\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+As {\bf wxLogDebug}, trace functions only do something in debug build and
+expand to nothing in the release one. 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.
+
+The trace messages also usually can be separated into different categories and
+the second and third versions of this function only log the message if the
+{\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This
+allows to selectively trace only some operations and not others by changing
+the value of the trace mask (possible during the run-time).
+
+For the second function (taking a string mask), the message is logged only if
+the mask has been previously enabled by the call to
+\helpref{AddTraceMask}{wxlogaddtracemask}. The predefined string trace masks
+used by wxWindows are:
+
+\begin{itemize}\itemsep=0pt
+\item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
+\item wxTRACE\_Messages: trace window messages/X callbacks
+\item wxTRACE\_ResAlloc: trace GDI resource allocation
+\item wxTRACE\_RefCount: trace various ref counting operations
+\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+The third version of the function only logs the message if all the bit
+corresponding to the {\it mask} are set in the wxLog trace mask which can be
+set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
+flexible than the previous one because it doesn't allow defining the user
+trace masks easily - this is why it is deprecated in favour of using string
+trace masks.
+
+\begin{itemize}\itemsep=0pt
+\item wxTraceMemAlloc: trace memory allocation (new/delete)
+\item wxTraceMessages: trace window messages/X callbacks
+\item wxTraceResAlloc: trace GDI resource allocation
+\item wxTraceRefCount: trace various ref counting operations
+\item wxTraceOleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
+
+\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
+
+This function shows a message to the user in a safe way and should be safe to
+call even before the application has been initialized or if it is currently in
+some other strange state (for example, about to crash). Under Windows this
+function shows a message box using a native dialog instead of
+\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
+it simply prints the message to the standard output using the title as prefix.
+
+\wxheading{Parameters}
+
+\docparam{title}{The title of the message box shown to the user or the prefix
+of the message string}
+
+\docparam{text}{The text to show to the user}
+
+\wxheading{See also}
+
+\helpref{wxLogFatalError}{wxlogfatalerror}
+
+\wxheading{Include files}
+
+<wx/log.h>
projects / wxWidgets.git / blobdiff