documented wxStackWalker/Frame

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

docs/latex/wx/classes.tex

@@ -297,6 +297,8 @@
 \input splitevt.tex
 \input splitter.tex
 \input splitpar.tex
+\input stackframe.tex
+\input stackwalker.tex
 \input stdpaths.tex
 \input statbmp.tex
 \input statbox.tex

docs/latex/wx/stackframe.tex

@@ -0,0 +1,126 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        stackframe.tex
+%% Purpose:     wxStackFrame documentation
+%% Author:      Vadim Zeitlin
+%% Created:     2005-01-19
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2005 Vadim Zeitlin
+%% License:     wxWidgets license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxStackFrame}}\label{wxstackframe}
+
+
+wxStackFrame represents a single stack frame, or a single function in the call
+stack, and is used exclusively together with 
+\helpref{wxStackWalker}{wxstackwalker}, see there for a more detailed
+discussion.
+
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/stackwalk.h>
+
+Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only
+implemented for Win32 and Unix versions using recent version of GNU libc.
+
+\wxheading{See also}
+
+\helpref{wxStackWalker}{wxstackwalker}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxStackFrame::GetAddress}\label{wxstackframegetaddress}
+
+\constfunc{void*}{GetAddress}{\void}
+
+Return the address of this frame.
+
+
+\membersection{wxStackFrame::GetFileName}\label{wxstackframegetfilename}
+
+\constfunc{wxString}{GetFileName}{\void}
+
+Return the name of the file containing this frame, empty if
+unavailable (typically because debug info is missing).
+
+Use \helpre{HasSourceLocation}{wxstackframehassourcelocation} to check whether
+the file name is available.
+
+
+\membersection{wxStackFrame::GetLevel}\label{wxstackframegetlevel}
+
+\constfunc{size\_t}{GetLevel}{\void}
+
+Get the level of this frame (deepest/innermost one is $0$).
+
+
+\membersection{wxStackFrame::GetLine}\label{wxstackframegetline}
+
+\constfunc{size\_t}{GetLine}{\void}
+
+Return the line number of this frame, $0$ if unavailable.
+
+\wxheading{See also}
+
+\helpref{GetFileName}{wxstackframegetfilename}
+
+
+\membersection{wxStackFrame::GetModule}\label{wxstackframegetmodule}
+
+\constfunc{wxString}{GetModule}{\void}
+
+Get the module this function belongs to (empty if not available).
+
+
+\membersection{wxStackFrame::GetName}\label{wxstackframegetname}
+
+\constfunc{wxString}{GetName}{\void}
+
+Return the unmangled (if possible) name of the function containing this
+frame.
+
+
+\membersection{wxStackFrame::GetOffset}\label{wxstackframegetoffset}
+
+\constfunc{size\_t}{GetOffset}{\void}
+
+Return the return address of this frame.
+
+
+\membersection{wxStackFrame::GetParam}\label{wxstackframegetparam}
+
+\constfunc{bool}{GetParam}{\param{size\_t }{n}, \param{wxString * }{type}, \param{wxString * }{name}, \param{wxString * }{value}}
+
+Get the name, type and value (in text form) of the given parameter.
+Any pointer may be \textt{NULL} if you're not interested in the corresponding
+value.
+
+Return \true if at least some values could be retrieved.
+
+This function currently is only implemented under Win32 and requires a PDB
+file.
+
+
+\membersection{wxStackFrame::GetParamCount}\label{wxstackframegetparamcount}
+
+\constfunc{size\_t}{GetParamCount}{\void}
+
+Return the number of parameters of this function (may return $0$ if we
+can't retrieve the parameters info even although the function does have
+parameters).
+
+
+\membersection{wxStackFrame::HasSourceLocation}\label{wxstackframehassourcelocation}
+
+\constfunc{bool}{HasSourceLocation}{\void}
+
+Return \true if we have the file name and line number for this frame.
+
+

docs/latex/wx/stackwalker.tex

@@ -0,0 +1,88 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        stackwalker.tex
+%% Purpose:     wxStackWalker documentation
+%% Author:      Vadim Zeitlin
+%% Created:     2005-01-19
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2005 Vadim Zeitlin
+%% License:     wxWidgets license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxStackWalker}}\label{wxstackwalker}
+
+wxStackWalker allows to enumerate, or walk, the stack frames or, in other
+words, the functions callstack. It is mostly useful in only two situations:
+inside \helpref{wxApp::OnFatalException}{wxapponfatalexception} function to
+programmatically get the location of the crash and, in debug builds, in 
+\helpref{wxApp::OnAssert}{wxapponassert} to report the caller of the failed
+assert.
+
+wxStackWalker works by repeatedly calling 
+\helpref{OnStackFrame}{wxstackwalkeronstackframe} method for each frame in the
+stack, so to use it you must derive your own class from it and override this
+method.
+
+This class will not return anything except raw stack frame addresses if the
+debug information is not available. See 
+\helpref{debugging overview}{debuggingoverview} for how to make it available.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/stackwalk.h>
+
+Only available if \texttt{wxUSE\_STACKWALKER} is $1$, currently only
+implemented for Win32 and Unix versions using recent version of GNU libc.
+
+\wxheading{See also}
+
+\helpref{wxStackFrame}{wxstackframe}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxStackWalker::wxStackWalker}\label{wxstackwalkerwxstackwalker}
+
+\func{}{wxStackWalker}{\void}
+
+Constructor does nothing, use \helpref{Walk()}{wxstackwalkerwalk} to walk the
+stack.
+
+
+\membersection{wxStackWalker::\destruct{wxStackWalker}}\label{wxstackwalkerdtor}
+
+\func{}{\destruct{wxStackWalker}}{\void}
+
+Destructor does nothing neither but should be virtual as this class is used as
+a base one.
+
+
+\membersection{wxStackWalker::OnStackFrame}\label{wxstackwalkeronstackframe}
+
+\func{void}{OnStackFrame}{\param{const wxStackFrame\& }{frame}}
+
+This function must be overrided to process the given frame.
+
+
+\membersection{wxStackWalker::Walk}\label{wxstackwalkerwalk}
+
+\func{void}{Walk}{\param{size\_t }{skip = 1}}
+
+Enumerate stack frames from the current location, skipping the initial
+number of them (this can be useful when Walk() is called from some known
+location and you don't want to see the first few frames anyhow; also
+notice that Walk() frame itself is not included if skip $\ge 1$).
+
+
+\membersection{wxStackWalker::WalkFromException}\label{wxstackwalkerwalkfromexception}
+
+\func{void}{WalkFromException}{\void}
+
+Enumerate stack frames from the location of uncaught exception.
+This method can only be called from 
+\helpref{wxApp::OnFatalException()}{wxapponfatalexception}.
+