X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7a0a4c095fec738368a4c7a8a4be3dbecc2dce78..4f690a1d5e6192d0861686982e89f9f17a21e679:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 74b7136158..3f35029b21 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -32,6 +32,7 @@ the corresponding topic. \helpref{IMPLEMENT\_CLASS}{implementclass}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ +\helpref{wxAboutBox}{wxaboutbox}\\ \helpref{wxASSERT}{wxassert}\\ \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\ \helpref{wxASSERT\_MSG}{wxassertmsg}\\ @@ -83,6 +84,8 @@ the corresponding topic. \helpref{wxEndBusyCursor}{wxendbusycursor}\\ \helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\ \helpref{wxEntry}{wxentry}\\ +\helpref{wxEntryStart}{wxentrystart}\\ +\helpref{wxEntryCleanup}{wxentrycleanup}\\ \helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\ \helpref{wxError}{wxerror}\\ \helpref{wxExecute}{wxexecute}\\ @@ -103,6 +106,7 @@ the corresponding topic. \helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\ \helpref{wxFindWindowByName}{wxfindwindowbyname}\\ \helpref{wxFinite}{wxfinite}\\ +\helpref{wxGenericAboutBox}{wxgenericaboutbox}\\ \helpref{wxGetActiveWindow}{wxgetactivewindow}\\ \helpref{wxGetApp}{wxgetapp}\\ \helpref{wxGetBatteryState}{wxgetbatterystate}\\ @@ -173,6 +177,8 @@ the corresponding topic. \helpref{wxIsEmpty}{wxisempty}\\ \helpref{wxIsMainThread}{wxismainthread}\\ \helpref{wxIsNaN}{wxisnan}\\ +\helpref{wxIsPlatformLittleEndian}{wxisplatformlittleendian}\\ +\helpref{wxIsPlatform64Bit}{wxisplatform64bit}\\ \helpref{wxIsWild}{wxiswild}\\ \helpref{wxKill}{wxkill}\\ \helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\ @@ -243,6 +249,8 @@ the corresponding topic. \helpref{wxStringTokenize}{wxstringtokenize}\\ \helpref{wxStripMenuCodes}{wxstripmenucodes}\\ \helpref{wxStrlen}{wxstrlen}\\ +\helpref{wxSTRINGIZE}{wxstringize}\\ +\helpref{wxSTRINGIZE\_T}{wxstringizet}\\ \helpref{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{wxsuppressgccprivatedtorwarning}\\ \helpref{wxSysErrorCode}{wxsyserrorcode}\\ \helpref{wxSysErrorMsg}{wxsyserrormsg}\\ @@ -304,10 +312,10 @@ and so normally is not useful. \membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} -\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor}} Returns $1$ if the compiler being used to compile the code is GNU C++ -compiler (g++) version major.minor.release or greater. Otherwise, and also if +compiler (g++) version major.minor or greater. Otherwise, and also if the compiler is not GNU C++ at all, returns $0$. @@ -360,26 +368,27 @@ to control the behaviour of the main event loop of the GUI programs. \membersection{::wxEntry}\label{wxentry} -This initializes wxWidgets in a platform-dependent way. Use this if you -are not using the default wxWidgets entry code (e.g. main or WinMain). For example, -you can initialize wxWidgets from an Microsoft Foundation Classes application using +This initializes wxWidgets in a platform-dependent way. Use this if you are not +using the default wxWidgets entry code (e.g. main or WinMain). For example, you +can initialize wxWidgets from an Microsoft Foundation Classes application using this function. -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = true}} +The following overload of wxEntry is available under all platforms: + +\func{int}{wxEntry}{\param{int\&}{ argc}, \param{wxChar **}{argv}} -wxWidgets initialization under Windows (non-DLL). If {\it enterLoop} is false, the -function will return immediately after calling wxApp::OnInit. Otherwise, the wxWidgets -message loop will be entered. +Under MS Windows, an additional overload suitable for calling from +\texttt{WinMain} is available: -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} +\func{int}{wxEntry}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}} -wxWidgets initialization under Windows (for applications constructed as a DLL). +(notice that under Windows CE platform, and only there, the type of +\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in +Unicode build). -\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} +\wxheading{See also} -wxWidgets initialization under Unix. +\helpref{wxEntryStart}{wxentrystart} \wxheading{Remarks} @@ -403,6 +412,38 @@ int CTheApp::ExitInstance() +\membersection{::wxEntryCleanup}\label{wxentrycleanup} + +\func{void}{wxEntryCleanup}{\void} + +Free resources allocated by a successful call to \helpref{wxEntryStart}{wxentrystart}. + +\wxheading{Include files} + + + + +\membersection{::wxEntryStart}\label{wxentrystart} + +\func{bool}{wxEntryStart}{\param{int\&}{ argc}, \param{wxChar **}{argv}} + +This function can be used to perform the initialization of wxWidgets if you +can't use the default initialization code for any reason. + +If the function returns \true, the initialization was successful and the global +\helpref{wxApp}{wxapp} object \texttt{wxTheApp} has been created. Moreover, +\helpref{wxEntryCleanup}{wxentrycleanup} must be called afterwards. If the +function returns \false, a catastrophic initialization error occured and (at +least the GUI part of) the library can't be used at all. + +Notice that parameters \arg{argc} and \arg{argv} may be modified by this +function. + +\wxheading{Include files} + + + + \membersection{::wxGetApp}\label{wxgetapp} \func{wxAppDerivedClass\&}{wxGetApp}{\void} @@ -955,7 +996,8 @@ Returns true if the file exists and is a plain file. Returns time of last modification of given file. -The return value is $0$ if an error occured (e.g. file not found). +The function returns \texttt{(time\_t)}$-1$ if an error occurred (e.g. file not +found). \membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} @@ -1072,9 +1114,9 @@ or drive name at the beginning. \membersection{::wxDirExists}\label{functionwxdirexists} -\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} +\func{bool}{wxDirExists}{\param{const wxChar *}{dirname}} -Returns true if the path exists. +Returns true if \arg{dirname} exists and is a directory. \membersection{::wxPathOnly}\label{wxpathonly} @@ -1232,6 +1274,11 @@ Removes the directory {\it dir}, returning true if successful. Does not work und The {\it flags} parameter is reserved for future use. +Please notice that there is also a wxRmDir() function which simply wraps the +standard POSIX rmdir() function and so return an integer error code instead of +a boolean value (but otherwise is currently identical to wxRmdir), don't +confuse these two functions. + \membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory} @@ -1404,32 +1451,49 @@ user-readable form. For example, this function may return strings like \membersection{::wxGetOsVersion}\label{wxgetosversion} -\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} +\func{wxOperatingSystemId}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} -Gets operating system version information. +Gets the version and the operating system ID for currently running OS. +See \helpref{wxPlatformInfo}{wxplatforminfo} for more details about wxOperatingSystemId. -\begin{twocollist}\itemsep=0pt -\twocolitemruled{Platform}{Return types} -\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X. - -Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. } -\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. } -\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} -\twocolitem{OS/2}{Return value is wxOS2\_PM.} -\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}.} -\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.} -\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.} -\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Windows PocketPC}{Return value is wxWINDOWS\_POCKETPC, version is returned in {\it major} and {\it minor}.} -\twocolitem{Windows Smartphone}{Return value is wxWINDOWS\_SMARTPHONE, version is returned in {\it major} and {\it minor}.} -\twocolitem{Windows CE (non-specific)}{Return value is wxWINDOWS\_CE, version is returned in {\it major} and {\it minor}.} -\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} -\end{twocollist} +\wxheading{See also} + +\helpref{::wxGetOsDescription}{wxgetosdescription}, +\helpref{wxPlatformInfo}{wxplatforminfo} + +\wxheading{Include files} + + + + +\membersection{::wxIsPlatformLittleEndian}\label{wxisplatformlittleendian} + +\func{bool}{wxIsPlatformLittleEndian}{\void} + +Returns \true if the current platform is little endian (instead of big endian). +The check is performed at run-time. \wxheading{See also} -\helpref{::wxGetOsDescription}{wxgetosdescription} +\helpref{Byte order macros}{byteordermacros} + +\wxheading{Include files} + + + + +\membersection{::wxIsPlatform64Bit}\label{wxisplatform64bit} + +\func{bool}{wxIsPlatform64Bit}{\void} + +Returns \true if the operating system the program is running under is 64 bit. +The check is performed at run-time and may differ from the value available at +compile-time (at compile-time you can just check if {\tt sizeof(void*)==8}) +since the program could be running in emulation mode or in a mixed 32/64 bit system +(bi-architecture operating system). + +Very important: this function is not 100\% reliable on some systems given the fact +that there isn't always a standard way to do a reliable check on the OS architecture. \wxheading{Include files} @@ -1517,15 +1581,19 @@ This function is deprecated, use \helpref{wxString}{wxstring} class instead. \membersection{::wxGetTranslation}\label{wxgettranslation} -\func{const char *}{wxGetTranslation}{\param{const char * }{str}} +\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str}, + \param{const wxChar* }{domain = NULL}} -\func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}} +\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str}, \param{const wxChar* }{strPlural}, \param{size\_t }{n}, + \param{const wxChar* }{domain = NULL}} This function returns the translation of string {\it str} in the current \helpref{locale}{wxlocale}. If the string is not found in any of the loaded message catalogs (see \helpref{internationalization overview}{internationalization}), the original string is returned. In debug build, an error message is logged -- this -should help to find the strings which were not yet translated. As this function +should help to find the strings which were not yet translated. If +{\it domain} is specified then only that domain/catalog is searched +for a matching string. As this function is used very often, an alternative (and also common in Unix world) syntax is provided: the \helpref{\_()}{underscore} macro is defined to do the same thing as wxGetTranslation. @@ -1723,6 +1791,12 @@ wxGetTranslation wouldn't find them. The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list } argument instead of arbitrary number of parameters. +Note that if \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports +positional arguments (see \helpref{wxString::Printf}{wxstringprintf} for more information). +However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, wxVfprintf, +wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional parameters +even when \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is 1. + \wxheading{See also} \helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv} @@ -1773,6 +1847,39 @@ parameter, or (in MS Windows or Motif) the wrong window frame may be brought to the front when the dialog box is popped up. +\membersection{::wxAboutBox}\label{wxaboutbox} + +\func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function shows the standard about dialog containing the information +specified in \arg{info}. If the current platform has a native about dialog +which is capable of showing all the fields in \arg{info}, the native dialog is +used, otherwise the function falls back to the generic wxWidgets version of the +dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}. + +Here is an example of how this function may be used: +\begin{verbatim} +void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) +{ + wxAboutDialogInfo info; + info.SetName(_("My Program")); + info.SetVersion(_("1.2.3 Beta")); + info.SetDescription(_("This program does something great.")); + info.SetCopyright(_T("(C) 2007 Me ")); + + wxAboutBox(info); +} +\end{verbatim} + +Please see the \helpref{dialogs sample}{sampledialogs} for more examples of +using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the +description of the information which can be shown in the about dialog. + +\wxheading{Include files} + + + + \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} @@ -1910,12 +2017,35 @@ See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +\membersection{::wxGenericAboutBox}\label{wxgenericaboutbox} + +\func{void}{wxGenericAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function does the same thing as \helpref{wxAboutBox}{wxaboutbox} except +that it always uses the generic wxWidgets version of the dialog instead of the +native one. This is mainly useful if you need to customize the dialog by e.g. +adding custom controls to it (customizing the native dialog is not currently +supported). + +See the \helpref{dialogs sample}{sampledialogs} for an example of about dialog +customization. + +\wxheading{See also} + +\helpref{wxAboutDialogInfo}{wxaboutdialoginfo} + +\wxheading{Include files} + +\\ + + + \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser} \func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}} Shows the colour selection dialog and returns the colour selected by user or -invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour +invalid colour (use \helpref{wxColour:IsOk}{wxcolourisok} to test whether a colour is valid) if the dialog was cancelled. \wxheading{Parameters} @@ -1936,7 +2066,7 @@ is valid) if the dialog was cancelled. \func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}, \param{const wxString\& }{caption = wxEmptyString}} Shows the font selection dialog and returns the font selected by user or -invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font +invalid font (use \helpref{wxFont:IsOk}{wxfontisok} to test whether a font is valid) if the dialog was cancelled. \wxheading{Parameters} @@ -2722,6 +2852,7 @@ code which might have to be compiled with an old compiler without support for this language feature but still take advantage of it when it is available. + \membersection{::wxGetKeyState}\label{wxgetkeystate} \func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}} @@ -2964,7 +3095,7 @@ always returns \NULL in the other ports). \wxheading{Include files} - + \membersection{::wxGetBatteryState}\label{wxgetbatterystate} @@ -3146,6 +3277,10 @@ Open the \arg{url} in user's default browser. If \arg{flags} parameter contains Returns \true if the application was successfully launched. +Note that for some configurations of the running user, the application which +is launched to open the given URL may be URL-dependent (e.g. a browser may be used for +local URLs while another one may be used for remote URLs). + \wxheading{Include files} @@ -3222,24 +3357,51 @@ See also \helpref{wxGetDisplayName}{wxgetdisplayname}. \membersection{::wxStripMenuCodes}\label{wxstripmenucodes} -\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}} - -\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}} +\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{str}, \param{int }{flags = wxStrip\_All}} -{\bf NB:} This function is obsolete, please use -\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead. +Strips any menu codes from \arg{str} and returns the result. -Strips any menu codes from {\it in} and places the result -in {\it out} (or returns the new string, in the first form). +By default, the functions strips both the mnemonics character (\texttt{'\&'}) +which is used to indicate a keyboard shortkey, and the accelerators, which are +used only in the menu items and are separated from the main text by the +\texttt{$\backslash$t} (TAB) character. By using \arg{flags} of +\texttt{wxStrip\_Mnemonics} or \texttt{wxStrip\_Accel} to strip only the former +or the latter part, respectively. -Menu codes include \& (mark the next character with an underline -as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). +Notice that in most cases +\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} or +\helpref{wxControl::GetLabelText}{wxcontrolgetlabeltext} can be used instead. \wxheading{Include files} +\membersection{wxSTRINGIZE}\label{wxstringize} + +\func{}{wxSTRINGIZE}{\param{}{x}} + +Returns the string representation of the given symbol which can be either a +literal or a macro (hence the advantage of using this macro instead of the +standard preprocessor \texttt{\#} operator which doesn't work with macros). + +Notice that this macro always produces a \texttt{char} string, use +\helpref{wxSTRINGIZE\_T}{wxstringizet} to build a wide string Unicode build. + +\wxheading{See also} + +\helpref{wxCONCAT}{wxconcat} + + +\membersection{wxSTRINGIZE\_T}\label{wxstringizet} + +\func{}{wxSTRINGIZE\_T}{\param{}{x}} + +Returns the string representation of the given symbol as either an ASCII or +Unicode string, depending on the current build. This is the Unicode-friendly +equivalent of \helpref{wxSTRINGIZE}{wxstringize}. + + \membersection{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}\label{wxsuppressgccprivatedtorwarning} \func{}{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{\param{}{name}}