X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a02afd1452bcb863bebd25c712067e51f8db81d1..2c6f14e1a7b5062fcf77eda40824d820d9ac288e:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index f682056732..ffd7eb45df 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -49,6 +49,10 @@ the corresponding topic. \helpref{wxCopyFile}{wxcopyfile}\\ \helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\ \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\ +\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}\\ +\helpref{wxCRIT\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember}\\ +\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}\\ +\helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro}\\ % wxcs already taken! \helpref{wxDDECleanUp}{wxddecleanup}\\ \helpref{wxDDEInitialize}{wxddeinitialize}\\ \helpref{wxDROP\_ICON}{wxdropicon}\\ @@ -61,9 +65,11 @@ the corresponding topic. \helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\ \helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ \helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\ \helpref{wxEmptyClipboard}{wxemptyclipboard}\\ \helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\ \helpref{wxEndBusyCursor}{wxendbusycursor}\\ +\helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\ \helpref{wxEntry}{wxentry}\\ \helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\ \helpref{wxError}{wxerror}\\ @@ -144,10 +150,13 @@ the corresponding topic. \helpref{wxIsAbsolutePath}{wxisabsolutepath}\\ \helpref{wxIsBusy}{wxisbusy}\\ \helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\ +\helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\ \helpref{wxIsEmpty}{wxisempty}\\ +\helpref{wxIsMainThread}{wxismainthread}\\ \helpref{wxIsNaN}{wxisnan}\\ \helpref{wxIsWild}{wxiswild}\\ \helpref{wxKill}{wxkill}\\ +\helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\ \helpref{wxLoadUserResource}{wxloaduserresource}\\ \helpref{wxLogDebug}{wxlogdebug}\\ \helpref{wxLogError}{wxlogerror}\\ @@ -177,17 +186,6 @@ the corresponding topic. \helpref{wxRegisterId}{wxregisterid}\\ \helpref{wxRemoveFile}{wxremovefile}\\ \helpref{wxRenameFile}{wxrenamefile}\\ -\helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}\\ -\helpref{wxResourceClear}{wxresourceclear}\\ -\helpref{wxResourceCreateBitmap}{wxresourcecreatebitmap}\\ -\helpref{wxResourceCreateIcon}{wxresourcecreateicon}\\ -\helpref{wxResourceCreateMenuBar}{wxresourcecreatemenubar}\\ -\helpref{wxResourceGetIdentifier}{wxresourcegetidentifier}\\ -\helpref{wxResourceParseData}{wxresourcedata}\\ -\helpref{wxResourceParseFile}{wxresourceparsefile}\\ -\helpref{wxResourceParseString}{wxresourceparsestring}\\ -\helpref{wxResourceRegisterBitmapData}{registerbitmapdata}\\ -\helpref{wxResourceRegisterIconData}{wxresourceregistericondata}\\ \helpref{wxRmdir}{wxrmdir}\\ \helpref{wxSafeShowMessage}{wxsafeshowmessage}\\ \helpref{wxSafeYield}{wxsafeyield}\\ @@ -212,6 +210,7 @@ the corresponding topic. \helpref{wxSplitPath}{wxsplitfunction}\\ \helpref{wxStartTimer}{wxstarttimer}\\ \helpref{wxStaticCast}{wxstaticcast}\\ +\helpref{wxStrcmp}{wxstrcmp}\\ \helpref{wxStricmp}{wxstricmp}\\ \helpref{wxStringEq}{wxstringeq}\\ \helpref{wxStringMatch}{wxstringmatch}\\ @@ -461,7 +460,7 @@ the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and \wxheading{Include files} - + \section{Process control functions}\label{processfunctions} @@ -681,6 +680,16 @@ and that this function is only implemented under Unix and Win32. \section{Thread functions}\label{threadfunctions} +The functions and macros here mainly exist to make it writing the code which +may be compiled in multi thread build ({\tt wxUSE\_THREADS} $= 1$) as well as +in single thread configuration ({\tt wxUSE\_THREADS} $= 0$). + +For example, a static variable must be protected against simultaneous access by +multiple threads in the former configuration but in the latter the extra +overhead of using the critical section is not needed. To solve this problem, +the \helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro} macro may be used +to create and use the critical section only when needed. + \wxheading{Include files} @@ -689,6 +698,85 @@ and that this function is only implemented under Unix and Win32. \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview} + +\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare} + +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} + +This macro declares a (static) critical section object named {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. + + +\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember} + +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} + +This macro declares a critical section object named {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. As it doesn't +include the {\tt static} keyword (unlike +\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}), it can be used to declare +a class or struct member which explains its name. + + +\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker} + +\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}} + +This macro creates a \helpref{critical section lock}{wxcriticalsectionlocker} +object named {\it name} and associated with the critical section {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. + + +\membersection{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro} + +\func{}{wxCRITICAL\_SECTION}{\param{}{name}} + +This macro combines \helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare} and +\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}: it creates a static critical +section object and also the lock object associated with it. Because of this, it +can be only used inside a function, not at global scope. For example: + +\begin{verbatim} +int IncCount() +{ + static int s_counter = 0; + + wxCRITICAL_SECTION(counter); + + return ++s_counter; +} +\end{verbatim} + +(note that we suppose that the function is called the first time from the main +thread so that the critical section object is initialized correctly by the time +other threads start calling it, if this is not the case this approach can +{\bf not} be used and the critical section must be made a global instead). + + +\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect} + +\func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} + +This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. + + +\membersection{::wxIsMainThread}\label{wxismainthread} + +\func{bool}{wxIsMainThread}{\void} + +Returns {\tt true} if this thread is the main one. Always returns {\tt true} if +{\tt wxUSE\_THREADS} is $0$. + + +\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect} + +\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} + +This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. + + \membersection{::wxMutexGuiEnter}\label{wxmutexguienter} \func{void}{wxMutexGuiEnter}{\void} @@ -1237,6 +1325,16 @@ as wxGetTranslation. Returns {\tt true} if the pointer is either {\tt NULL} or points to an empty string, {\tt false} otherwise. +\membersection{::wxStrcmp}\label{wxstrcmp} + +\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}} + +Returns a negative value, 0, or positive value if {\it p1} is less than, equal +to or greater than {\it p2}. The comparison is case-sensitive. + +This function complements the standard C function {\it stricmp()} which performs +case-insensitive comparison. + \membersection{::wxStricmp}\label{wxstricmp} \func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}} @@ -1824,7 +1922,7 @@ See also \helpref{wxBusyCursor}{wxbusycursor}. \membersection{::wxMessageBox}\label{wxmessagebox} -\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\ +\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}} General purpose message dialog. {\it style} may be a bit list of the @@ -1836,7 +1934,6 @@ wxCANCEL.} \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with wxYES\_NO or wxOK.} \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.} -\twocolitem{wxCENTRE}{Centres the text.} \twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.} \twocolitem{wxICON\_HAND}{Displays an error symbol.} \twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.} @@ -1860,11 +1957,6 @@ For example: {\it message} may contain newline characters, in which case the message will be split into separate lines, to cater for large messages. -Under Windows, the native MessageBox function is used unless wxCENTRE -is specified in the style, in which case a generic function is used. -This is because the native MessageBox function cannot centre text. -The symbols are not shown when the generic function is used. - \wxheading{Include files} @@ -2263,8 +2355,34 @@ Passes data to the clipboard. The clipboard must have previously been opened for this call to succeed. + \section{Miscellaneous functions}\label{miscellany} +\membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction} + +\func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}} + +When loading a function from a DLL you always have to cast the returned +\tt{void *} pointer to the correct type and, even more annoyingly, you have to +repeat this type twice if you want to declare and define a function pointer all +in one line + +This macro makes this slightly less painful by allowing you to specify the +type only once, as the first parameter, and creating a variable of this type +named after the function but with {\tt pfn} prefix and initialized with the +function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary} +\arg{dynlib}. + +\wxheading{Parameters} + +\docparam{type}{the type of the function} + +\docparam{name}{the name of the function to load, not a string (without quotes, +it is quoted automatically by the macro)} + +\docparam{dynlib}{the library to load the function from} + + \membersection{wxEXPLICIT}\label{wxexplicit} {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if @@ -2519,10 +2637,6 @@ myResource TEXT file.ext where {\tt file.ext} is a file that the resource compiler can find. -One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers -cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed -using \helpref{wxResourceParseString}{wxresourceparsestring}. - This function is available under Windows only. \wxheading{Include files} @@ -3000,201 +3114,6 @@ result of executing an equivalent of {\tt static\_cast(ptr)}. \helpref{wxDynamicCast}{wxdynamiccast}\\ \helpref{wxConstCast}{wxconstcast} -\section{Resource functions}\label{resourcefuncs} - -\overview{Resource functions}{resourceformats} - -This section details functions for manipulating wxWindows (.WXR) resource -files and loading user interface elements from resources. - -\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 @@ -3820,6 +3739,18 @@ In release mode this function does nothing. + +\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} + +\func{bool}{wxIsDebuggerRunning}{\void} + +Returns {\tt true} if the program is running under debugger, {\tt false} +otherwise. + +Please note that this function is currently only implemented for Mac builds +using CodeWarrior and always returns {\tt false} elsewhere. + + \section{Environment access functions}\label{environfunctions} The functions in this section allow to access (get) or change value of