X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/eafc087e69e52add5952190bfd5bcbbf931ad12b..dc9e1e56917ad9b448bd0087a2d1ae3c632c4db1:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 9d3d820f1e..2134147532 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -479,113 +479,6 @@ This function is only available under Windows. Globally sets the cursor; only has an effect in MS Windows. See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. -\section{System event functions} - -The wxWindows system event implementation is incomplete and -experimental, but is intended to be a platform-independent way of -intercepting and sending events, including defining -application-specific events and handlers. - -Ultimately it is intended to be used as a way of testing wxWindows -applications using scripts, although there are currently -problems with this (especially with modal dialogs). - -All this is documented more to provoke comments and suggestions, and -jog my own memory, rather than to be used, since it has not been -tested. However {\bf wxSendEvent} will probably work if you -instantiate the event structure properly for a command event type (see -the code in {\tt wb\_panel.cpp} for \helpref{wxWindow::OnDefaultAction}{wxwindowondefaultaction}\rtfsp -which uses {\bf wxSendEvent} to send a command to the default button). - -\membersection{::wxAddPrimaryEventHandler} - -\func{bool}{wxAddPrimaryEventHandler}{\param{wxEventHandler}{ handlerFunc}} - -Add a primary event handler---the normal event handler for this -event. For built-in events, these would include moving and resizing -windows. User-defined primary events might include the code to -select an image in a diagram (which could of course be achieved by a series -of external events for mouse-clicking, but would be more difficult to specify -and less robust). - -Returns TRUE if it succeeds. - -An event handler takes a pointer to a wxEvent and a boolean flag which is -TRUE if the event was externally generated, and returns a boolean which is -TRUE if that event was handled. - -\membersection{::wxAddSecondaryEventHandler} - -\func{bool}{wxAddSecondaryEventHandler}{\param{wxEventHandler}{ handlerFunc}, \param{bool}{ pre},\\ - \param{bool}{ override}, \param{bool }{append}} - -Add a secondary event handler, pre = TRUE iff it should be called before the -event is executed. override = TRUE iff the handler is allowed to override -all subsequent events by returning TRUE. Returns TRUE if succeeds. - -A secondary event handler is an application-defined handler that may -intercept normal events, possibly overriding them. A primary event handler -provides the normal behaviour for the event. - -An event handler takes a pointer to a wxEvent and a boolean flag which is -TRUE if the event was externally generated, and returns a boolean which is -TRUE if that event was handled. - -\membersection{::wxNotifyEvent} - -\func{bool}{wxNotifyEvent}{\param{wxEvent\&}{ event}, \param{bool}{ pre}} - -Notify the system of the event you are about to execute/have just -executed. If TRUE is returned and pre = TRUE, the calling code should -not execute the event (since it has been intercepted by a handler and -vetoed). - -These events are always internal, because they're generated from within -the main application code. - -\membersection{::wxRegisterEventClass} - -\func{void}{wxRegisterEventClass}{\param{WXTYPE}{ eventClassId},\param{WXTYPE}{ superClassId},\\ - \param{wxEventConstructor}{ constructor}, \param{const wxString\& }{description}} - -Register a new event class (derived from wxEvent), giving the new -event class type, its superclass, a function for creating a new event -object of this class, and an optional description. - -\membersection{::wxRegisterEventName} - -\func{void}{wxRegisterEventName}{\param{WXTYPE}{ eventTypeId},\param{WXTYPE}{ eventClassId},\\ - \param{const wxString\& }{eventName}} - -Register the name of the event. This will allow a simple command -language where giving the event type name and some arguments will -cause a new event of class {\it eventClassId} to be created, with given -event type, and some arguments, allows an event to be dynamically -constructed and sent. - -\membersection{::wxRegisterExternalEventHandlers} - -\func{void}{wxRegisterExternalEventHandlers}{\void} - -Define this and link before wxWindows library to allow registering -events from `outside' the main application. - -\membersection{::wxRemoveSecondaryEventHandler} - -\func{bool}{wxRemoveSecondaryEventHandler}{\param{wxEventHandler}{ handlerFunc}, \param{bool}{ pre}} - -Remove a secondary event handler. Returns TRUE if it succeeds. - -\membersection{::wxSendEvent}\label{wxsendevent} - -\func{bool}{wxSendEvent}{\param{wxEvent\&}{ event}, \param{bool}{ external}} - -Send an event to the system; usually it will be external, but set -external to FALSE if calling from within the main application in -response to other events. - -Returns TRUE if the event was processed. - \section{Printer settings}\label{printersettings} The following functions are used to control PostScript printing. Under @@ -857,6 +750,8 @@ each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s (at least for Watcom C++): preformat your messages and use OutputDebugString instead. +This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + \membersection{::wxDisplaySize} \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} @@ -1228,6 +1123,8 @@ Converts the character to upper case. This is implemented as a macro for efficie Takes printf-style variable argument syntax. Output is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + \membersection{::wxTraceLevel}\label{wxtracelevel} \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} @@ -1238,6 +1135,8 @@ The first argument should be the level at which this information is appropriate. It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than this value. +This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + \membersection{::wxWriteResource}\label{wxwriteresource} \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, @@ -1462,6 +1361,8 @@ base classes. Calls wxTrace with printf-style variable argument syntax. Output is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + \membersection{WXTRACELEVEL}\label{tracelevel} \func{}{WXTRACELEVEL}{level, formatString, ...} @@ -1472,6 +1373,8 @@ The first argument should be the level at which this information is appropriate. It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than this value. +This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + \section{wxWindows resource functions}\label{resourcefuncs} \overview{wxWindows resource system}{resourceformats} @@ -1667,3 +1570,148 @@ is no connection between names used in resources, and the global bitmap data. 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. + +\membersection{::wxLogError}\label{wxlogerror} + +\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}} + +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. + +\membersection{::wxLogFatalError}\label{wxlogfatalerror} + +\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}} + +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{...}{}} + +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{...}{}} + +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{...}{}} + +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}). + +\membersection{::wxLogStatus}\label{wxlogstatus} + +\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}} + +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. + +\membersection{::wxLogSysError}\label{wxlogsyserror} + +\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}} + +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. + +\membersection{::wxLogDebug}\label{wxlogdebug} + +\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}} + +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). + +\membersection{::wxLogTrace}\label{wxlogtrace} + +\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}} + +\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}} + +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. The value of {\it mask} can be: + +\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 +\end{itemize} + +\section{Debugging macros and functions}\label{debugmacros} + +Useful macros and functins for error checking and defensive programming. ASSERTs are only +compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release +builds. + +\membersection{::wxOnAssert}\label{wxonassert} + +\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}} + +This function may be redefined to do something non trivial and is called +whenever one of debugging macros fails (i.e. condition is false in an +assertion). TODO: this should probably be an overridable in wxApp. + +\membersection{wxASSERT}\label{wxassert} + +\func{}{wxASSERT}{\param{}{condition}} + +Assert macro. An error message will be generated if the condition is FALSE. + +\membersection{wxASSERT\_MSG}\label{wxassertmsg} + +\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} + +Assert macro with message. An error message will be generated if the condition is FALSE. + +\membersection{wxFAIL}\label{wxfail} + +\func{}{wxFAIL}{\param{}{condition}} + +Will always generate an assert error if this code is reached (in debug mode). + +\membersection{wxFAIL\_MSG}\label{wxfailmsg} + +\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}} + +Will always generate an assert error with specified message if this code is reached (in debug mode). + +\membersection{wxCHECK}\label{wxcheck} + +\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} + +Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). +This check is done even in release mode. + +\membersection{wxCHECK\_MSG}\label{wxcheckmsg} + +\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} + +Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). +This check is done even in release mode. + +