| Version: 3.3.1

Macros | Typedefs | Enumerations | Functions
Miscellaneous
Functions and Macros by Category

## Detailed Description

Group of miscellaneous functions and macros.

Related class group: Miscellaneous

## Macros
#define | wxCONCAT(x1, x2)
| This macro returns the concatenation of the arguments passed. More...
#define | wxCONCAT3(x1, x2, x3)
#define | wxCONCAT4(x1, x2, x3, x4)
#define | wxCONCAT5(x1, x2, x3, x4, x5)
#define | wxSTRINGIZE(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 `#` operator which doesn't work with macros). More...
#define | wxSTRINGIZE_T(x)
| Returns the string representation of the given symbol as either an ASCII or Unicode string, depending on the current build. More...
#define | __WXFUNCTION__ __func__
| This obsolete macro is the same as the standard `__func__` constant. More...
#define | __WXFUNCTION_SIG__
| Expands to the current function's full signature, if available. More...
#define | wxCHECK_CXX_STD(stdver)
| Returns true if the compiler being used supports the given C++ version. More...
#define | wxHAS_CXX17_INCLUDE(header)
| Returns true if the compiler is using the C++17 standard and the header header exists. More...
#define | wxDECLARE_NO_ASSIGN_CLASS(classname)
| This macro can be used in a class declaration to disable the generation of default assignment operator. More...
#define | wxDECLARE_NO_ASSIGN_DEF_COPY(classname)
| Macro disabling the generation of default assignment operator but generating a default copy constructor. More...
#define | wxDECLARE_NO_COPY_CLASS(classname)
| This macro can be used in a class declaration to disable the generation of default copy ctor and assignment operator. More...
#define | wxDECLARE_NO_COPY_TEMPLATE_CLASS(classname, arg)
| Analog of wxDECLARE_NO_COPY_CLASS() for template classes. More...
#define | wxDECLARE_NO_COPY_TEMPLATE_CLASS_2(classname, arg1, arg2)
| Analog of wxDECLARE_NO_COPY_TEMPLATE_CLASS() for templates with 2 parameters. More...
#define | wxDEPRECATED_ATTR(msg) [[deprecated(msg)]]
| Expands to the standard C++14 [[deprecated]] attribute if supported. More...
#define | wxDEPRECATED_MSG(msg)
| Generate deprecation warning with the given message when a function is used. More...
#define | wxDEPRECATED(function)
| This macro can be used around a function declaration to generate warnings indicating that this function is deprecated (i.e. More...
#define | wxDEPRECATED_BUT_USED_INTERNALLY(function)
| This is a special version of wxDEPRECATED() macro which only does something when the deprecated function is used from the code outside wxWidgets itself but doesn't generate warnings when it is used from wxWidgets. More...
#define | wxDEPRECATED_INLINE(func, body)
| This macro is similar to wxDEPRECATED() but can be used to not only declare the function function as deprecated but to also provide its (inline) implementation body. More...
#define | wxDEPRECATED_ACCESSOR(func, what)
| A helper macro allowing to easily define a simple deprecated accessor. More...
#define | wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(func, body)
| Combination of wxDEPRECATED_BUT_USED_INTERNALLY() and wxDEPRECATED_INLINE(). More...
#define | wxOVERRIDE override
| Expands to "override" keyword. More...
#define | wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)
| GNU C++ compiler gives a warning for any class whose destructor is private unless it has a friend. More...
#define | wxWARN_UNUSED __attribute__((warn_unused))
| Expands to the "warn_unused" attribute (also known as [[gnu::warn_unused]]) on compilers supporting it (GCC and Clang), otherwise to nothing. More...
#define | wxDYNLIB_FUNCTION(type, name, dynlib)
| When loading a function from a DLL you always have to cast the returned `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. More...
#define | wxLongLongFmtSpec
| This macro is defined to contain the `printf()` format specifier using which 64 bit integer numbers (i.e. More...
#define | wxON_BLOCK_EXIT(function, ...)
| Ensure that the global function with a few (up to some implementation-defined limit) is executed on scope exit, whether due to a normal function return or because an exception has been thrown. More...
#define | wxON_BLOCK_EXIT0(function)
#define | wxON_BLOCK_EXIT1(function, p1)
#define | wxON_BLOCK_EXIT2(function, p1, p2)
#define | wxON_BLOCK_EXIT3(function, p1, p2, p3)
#define | wxON_BLOCK_EXIT_OBJ(object, method, ...)
| This family of macros is similar to wxON_BLOCK_EXIT(), but calls a method of the given object instead of a free function. More...
#define | wxON_BLOCK_EXIT_OBJ0(object, method)
#define | wxON_BLOCK_EXIT_OBJ1(object, method, p1)
#define | wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)
#define | wxON_BLOCK_EXIT_OBJ3(object, method, p1, p2, p3)
#define | wxON_BLOCK_EXIT_THIS(method, ...)
| This family of macros is similar to wxON_BLOCK_OBJ(), but calls a method of `this` object instead of a method of the specified object. More...
#define | wxON_BLOCK_EXIT_THIS0(method)
#define | wxON_BLOCK_EXIT_THIS1(method, p1)
#define | wxON_BLOCK_EXIT_THIS2(method, p1, p2)
#define | wxON_BLOCK_EXIT_THIS3(method, p1, p2, p3)
#define | wxON_BLOCK_EXIT_SET(var, value)
| This macro sets a variable to the specified value on scope exit. More...
#define | wxON_BLOCK_EXIT_NULL(ptr)
| This macro sets the pointer passed to it as argument to nullptr on scope exit. More...

## Typedefs
typedef int(* | wxSortCallback) (const void *pItem1, const void *pItem2, const void *user_data)

## Enumerations
enum | wxBase64DecodeMode { wxBase64DecodeMode_Strict , wxBase64DecodeMode_SkipWS , wxBase64DecodeMode_Relaxed }
| Elements of this enum specify the possible behaviours of wxBase64Decode when an invalid character is encountered. More...
enum | { wxStrip_Mnemonics = 1 , wxStrip_Accel = 2 , wxStrip_CJKMnemonics = 4 , wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel , wxStrip_Menu = wxStrip_All | wxStrip_CJKMnemonics }
| flags for wxStripMenuCodes More...

## Functions
size_t | wxBase64Encode (char *dst, size_t dstLen, const void *src, size_t srcLen)
| This function encodes the given data using base64. More...
wxString | wxBase64Encode (const void *src, size_t srcLen)
| This function encodes the given data using base64 and returns the output as a wxString. More...
wxString | wxBase64Encode (const wxMemoryBuffer &buf)
| This function encodes the given data using base64 and returns the output as a wxString. More...
size_t | wxBase64DecodedSize (size_t srcLen)
| Returns the size of the buffer necessary to contain the data encoded in a base64 string of length srcLen. More...
size_t | wxBase64EncodedSize (size_t len)
| Returns the length of the string with base64 representation of a buffer of specified size len. More...
size_t | wxBase64Decode (void *dst, size_t dstLen, const char *src, size_t srcLen=wxNO_LEN, wxBase64DecodeMode mode=wxBase64DecodeMode_Strict, size_t *posErr=nullptr)
| This function decodes a Base64-encoded string. More...
size_t | wxBase64Decode (void *dst, size_t dstLen, const wxString &str, wxBase64DecodeMode mode=wxBase64DecodeMode_Strict, size_t *posErr=nullptr)
| Decode a Base64-encoded wxString. More...
wxMemoryBuffer | wxBase64Decode (const char *src, size_t srcLen=wxNO_LEN, wxBase64DecodeMode mode=wxBase64DecodeMode_Strict, size_t *posErr=nullptr)
| Decode a Base64-encoded string and return decoded contents in a buffer. More...
wxMemoryBuffer | wxBase64Decode (const wxString &src, wxBase64DecodeMode mode=wxBase64DecodeMode_Strict, size_t *posErr=nullptr)
| Decode a Base64-encoded wxString and return decoded contents in a buffer. More...
bool | wxFromString (const wxString &string, wxColour *colour)
| Converts string to a wxColour best represented by the given string. More...
wxString | wxToString (const wxColour &colour)
| Converts the given wxColour into a string. More...
void | wxDDECleanUp ()
| Called when wxWidgets exits, to clean up the DDE system. More...
void | wxDDEInitialize ()
| Initializes the DDE system. More...
template<typename T >
void | wxDELETE (T *&ptr)
| A function which deletes and nulls the pointer. More...
template<typename T >
void | wxDELETEA (T *&array)
| A function which deletes and nulls the pointer. More...
template<class C >
int | wxSsize (const C &c)
| Return the size of the container as int. More...
template<typename T >
void | wxSwap (T &first, T &second)
| Swaps the contents of two variables. More...
void | wxVaCopy (va_list argptrDst, va_list argptrSrc)
| This macro is the same as the standard C99 `va_copy` for the compilers which support it or its replacement for those that don't. More...
bool | wxFromString (const wxString &string, wxFont *font)
| Converts string to a wxFont best represented by the given string. More...
wxString | wxToString (const wxFont &font)
| Converts the given wxFont into a string. More...
wxLongLong_t | wxLL (number)
| This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit compile time constants: More...
wxLongLong_t | wxULL (number)
| This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit compile time constants: More...
template<typename F , typename P1 , ... , typename PN >
wxScopeGuard | wxMakeGuard (F func, P1 p1,..., PN pN)
| Returns a scope guard object which will call the specified function with the given parameters on scope exit. More...
wxString | wxGetStockLabel (wxWindowID id, long flags=wxSTOCK_WITH_MNEMONIC)
| Returns label that should be used for given id element. More...
wxTextOutputStream & | endl (wxTextOutputStream &stream)
| Writes `'\n'` to stream. More...
void | wxSecureZeroMemory (void *p, size_t n)
| Fills the memory block with zeros in a way that is guaranteed not to be optimized away by the compiler. More...
wxBatteryState | wxGetBatteryState ()
| Returns battery state as one of `wxBATTERY_NORMAL_STATE`, `wxBATTERY_LOW_STATE`, `wxBATTERY_CRITICAL_STATE`, `wxBATTERY_SHUTDOWN_STATE` or `wxBATTERY_UNKNOWN_STATE`. More...
wxPowerType | wxGetPowerType ()
| Returns the type of power source as one of `wxPOWER_SOCKET`, `wxPOWER_BATTERY` or `wxPOWER_UNKNOWN`. More...
wxString | wxGetDisplayName ()
| Under X only, returns the current display name. More...
bool | wxGetDiskSpace (const wxString &path, wxLongLong total=nullptr, wxLongLong free=nullptr)
| This function returns the total number of bytes and number of free bytes on the disk containing the directory path (it should exist). More...
bool | wxGetKeyState (wxKeyCode key)
| For normal keys, returns true if the specified key is currently down. More...
wxPoint | wxGetMousePosition ()
| Returns the mouse position in screen coordinates. More...
wxMouseState | wxGetMouseState ()
| Returns the current state of the mouse. More...
void | wxEnableTopLevelWindows (bool enable=true)
| This function enables or disables all top level windows. More...
wxWindow * | wxFindWindowAtPoint (const wxPoint &pt)
| Find the deepest window at the given mouse position in screen coordinates, returning the window if found, or nullptr if not. More...
wxWindow * | wxFindWindowByLabel (const wxString &label, wxWindow *parent=nullptr)
wxWindow * | wxFindWindowByName (const wxString &name, wxWindow *parent=nullptr)
int | wxFindMenuItemId (wxFrame *frame, const wxString &menuString, const wxString &itemString)
| Find a menu item identifier associated with the given frame's menu bar. More...
wxWindowID | wxNewId ()
void | wxRegisterId (wxWindowID id)
| Ensures that Ids subsequently generated by wxNewId() do not clash with the given id. More...
bool | wxLaunchDefaultApplication (const wxString &document, int flags=0)
| Opens the document in the application associated with the files of this type. More...
bool | wxLaunchDefaultBrowser (const wxString &url, int flags=0)
| Opens the url in user's default browser. More...
bool | wxLoadUserResource (const void **outData, size_t *outLen, const wxString &resourceName, const wxChar *resourceType="TEXT", WXHINSTANCE module=0)
| Loads an object from Windows resource file. More...
char * | wxLoadUserResource (const wxString &resourceName, const wxChar *resourceType="TEXT", int *pLen=nullptr, WXHINSTANCE module=0)
| Loads a user-defined Windows resource as a string. More...
void | wxQsort (void *pbase, size_t total_elems, size_t size, wxSortCallback cmp, const void *user_data)
void | wxSetDisplayName (const wxString &displayName)
| Under X only, sets the current display name. More...
wxString | wxStripMenuCodes (const wxString &str, int flags=wxStrip_All)
| Strips any menu codes from str and returns the result. More...
void | wxDecToHex (unsigned char dec, wxChar *buf)
| Convert decimal integer to 2-character hexadecimal string. More...
wxString | wxDecToHex (unsigned char dec)
| Convert decimal integer to 2-character hexadecimal string. More...
void | wxDecToHex (unsigned char dec, char *ch1, char *ch2)
| Returns 2 characters of hexadecimal representation of a given number. More...
int | wxHexToDec (const wxString &buf)
| Convert 2-character hexadecimal string to decimal integer. More...
int | wxHexToDec (const char *buf)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
wxWindow * | wxFindWindowAtPointer (wxPoint &pt)
| Find the deepest window at the mouse pointer position, returning the window and current pointer position in screen coordinates. More...
wxWindow * | wxGetActiveWindow ()
| Gets the currently active window (implemented for MSW and GTK only currently, always returns nullptr in the other ports). More...
wxWindow * | wxGetTopLevelParent (wxWindow *window)
| Returns the first top level parent of the given window, or in other words, the frame or dialog containing it, or nullptr. More...
wxString | wxDumpWindow (const wxWindow *window)
| Return a string with human-readable platform-specific description of the window useful for diagnostic purposes. More...

## Macro Definition Documentation

## ◆ __WXFUNCTION__

#define __WXFUNCTION__ __func__

This obsolete macro is the same as the standard `__func__` constant.

Please use the standard macro instead.

See also
  WXFUNCTION_SIG

Include file:

    #include <wx/cpp.h>

## ◆ __WXFUNCTION_SIG__

#define __WXFUNCTION_SIG__

Expands to the current function's full signature, if available.

Falls back to the function name (i.e., `__func__`) if not available.

As an example, if you have a class named `Calculator` with a `double Add(double, double) const` member function, `__WXFUNCTION_SIG__` may expand to the following:

`double Calculator::Add(double, double) const`

While `__func__` will simply expand to:

`Add`

Include file:

    #include <wx/cpp.h>

Since
  3.3.0

## ◆ wxCHECK_CXX_STD

#define wxCHECK_CXX_STD | ( |  | stdver | ) |

Returns true if the compiler being used supports the given C++ version.

The stdver parameter uses the same values as the standard `__cplusplus` macro, i.e.

- 201103L for C++11
- 201402L for C++14
- 201703L for C++17
- 202002L for C++20

Using this macro also works with MSVC, even when `/Zc`:__cplusplus option is not used, unlike checking for the value of `__cplusplus` directly.

Since
  3.1.7

Include file:

    #include <wx/defs.h>

## ◆ wxCONCAT

#define wxCONCAT | ( |  | x1,
|  |  | x2
| ) |  |

This macro returns the concatenation of the arguments passed.

Unlike when using the preprocessor operator, the arguments undergo macro expansion before being concatenated.

Include file:

    #include <wx/cpp.h>

## ◆ wxCONCAT3

#define wxCONCAT3 | ( |  | x1,
|  |  | x2,
|  |  | x3
| ) |  |

## ◆ wxCONCAT4

#define wxCONCAT4 | ( |  | x1,
|  |  | x2,
|  |  | x3,
|  |  | x4
| ) |  |

## ◆ wxCONCAT5

#define wxCONCAT5 | ( |  | x1,
|  |  | x2,
|  |  | x3,
|  |  | x4,
|  |  | x5
| ) |  |

## ◆ wxDECLARE_NO_ASSIGN_CLASS

#define wxDECLARE_NO_ASSIGN_CLASS | ( |  | classname | ) |

This macro can be used in a class declaration to disable the generation of default assignment operator.

Some classes have a well-defined copy constructor but cannot have an assignment operator, typically because they can't be modified once created. In such case, this macro can be used to disable the automatic assignment operator generation.

See also
  wxDECLARE_NO_COPY_CLASS(), wxDECLARE_NO_ASSIGN_DEF_COPY()

## ◆ wxDECLARE_NO_ASSIGN_DEF_COPY

#define wxDECLARE_NO_ASSIGN_DEF_COPY | ( |  | classname | ) |

Macro disabling the generation of default assignment operator but generating a default copy constructor.

This macro can be useful for the classes that can't be copied after creation, but may be copy-constructed using the default compiler-generated copy constructor.

Note that using wxDECLARE_NO_ASSIGN_CLASS() for such macros results in `-Wdeprecated-copy` warning from clang 13, while this macro avoids such warnings.

Default copy constructor is only generated when using C++11 or later, otherwise this macro is identical to wxDECLARE_NO_ASSIGN_CLASS().

Since
  3.1.6

## ◆ wxDECLARE_NO_COPY_CLASS

#define wxDECLARE_NO_COPY_CLASS | ( |  | classname | ) |

This macro can be used in a class declaration to disable the generation of default copy ctor and assignment operator.

Some classes don't have a well-defined copying semantics. In this case the standard C++ convention is to not allow copying them. One way of achieving it is to use this macro which simply defines a private copy constructor and assignment operator.

Beware that simply not defining copy constructor and assignment operator is not enough as the compiler would provide its own automatically-generated versions of them – hence the usefulness of this macro.

Example of use:

class FooWidget
{
public:
FooWidget();
...
private:
// widgets can't be copied
wxDECLARE_NO_COPY_CLASS(FooWidget);
};
wxDECLARE_NO_COPY_CLASS
#define wxDECLARE_NO_COPY_CLASS(classname)
This macro can be used in a class declaration to disable the generation of default copy ctor and assi...
Definition: defs.h:1625

Notice that a semicolon must be used after this macro and that it changes the access specifier to private internally so it is better to use it at the end of the class declaration.

See also
  wxDECLARE_NO_ASSIGN_CLASS(), wxDECLARE_NO_COPY_TEMPLATE_CLASS()

## ◆ wxDECLARE_NO_COPY_TEMPLATE_CLASS

#define wxDECLARE_NO_COPY_TEMPLATE_CLASS | ( |  | classname,
|  |  | arg
| ) |  |

Analog of wxDECLARE_NO_COPY_CLASS() for template classes.

This macro can be used for template classes (with a single template parameter) for the same purpose as wxDECLARE_NO_COPY_CLASS() is used with the non-template classes.

Parameters

  classname | The name of the template class.
  arg | The name of the template parameter.

See also
  wxDECLARE_NO_COPY_TEMPLATE_CLASS_2

## ◆ wxDECLARE_NO_COPY_TEMPLATE_CLASS_2

#define wxDECLARE_NO_COPY_TEMPLATE_CLASS_2 | ( |  | classname,
|  |  | arg1,
|  |  | arg2
| ) |  |

Analog of wxDECLARE_NO_COPY_TEMPLATE_CLASS() for templates with 2 parameters.

This macro can be used for template classes with two template parameters for the same purpose as wxDECLARE_NO_COPY_CLASS() is used with the non-template classes.

Parameters

  classname | The name of the template class.
  arg1 | The name of the first template parameter.
  arg2 | The name of the second template parameter.

See also
  wxDECLARE_NO_COPY_TEMPLATE_CLASS

## ◆ wxDEPRECATED

#define wxDEPRECATED | ( |  | function | ) |

This macro can be used around a function declaration to generate warnings indicating that this function is deprecated (i.e.

obsolete and planned to be removed in the future) when it is used.

Notice that this macro itself is deprecated in favour of wxDEPRECATED_MSG()!

Example of use:

// old function, use wxString version instead
wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
// ...
wxString wxGetSomething();
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372
wxDEPRECATED
#define wxDEPRECATED(function)
This macro can be used around a function declaration to generate warnings indicating that this functi...
Definition: defs.h:1746

Include file:

    #include <wx/defs.h>

## ◆ wxDEPRECATED_ACCESSOR

#define wxDEPRECATED_ACCESSOR | ( |  | func,
|  |  | what
| ) |  |

A helper macro allowing to easily define a simple deprecated accessor.

Compared to wxDEPRECATED_INLINE() it saves a `return` statement and, especially, a strangely looking semicolon inside a macro.

Example of use

class wxFoo
{
public:
int GetValue() const { return m_value; }
// this one is deprecated because it was erroneously non-const
wxDEPRECATED_ACCESSOR( int GetValue(), m_value )
private:
int m_value;
};
wxDEPRECATED_ACCESSOR
#define wxDEPRECATED_ACCESSOR(func, what)
A helper macro allowing to easily define a simple deprecated accessor.
Definition: defs.h:1806

## ◆ wxDEPRECATED_ATTR

#define wxDEPRECATED_ATTR | ( |  | msg | ) | [[deprecated(msg)]]

Expands to the standard C++14 [[deprecated]] attribute if supported.

If not supported by the compiler, expands to nothing. If support for such compilers is important, use wxDEPRECATED_MSG() which is almost universally available.

Since
  3.1.6

## ◆ wxDEPRECATED_BUT_USED_INTERNALLY

#define wxDEPRECATED_BUT_USED_INTERNALLY | ( |  | function | ) |

This is a special version of wxDEPRECATED() macro which only does something when the deprecated function is used from the code outside wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.

It is used with the virtual functions which are called by the library itself – even if such function is deprecated the library still has to call it to ensure that the existing code overriding it continues to work, but the use of this macro ensures that a deprecation warning will be generated if this function is used from the user code or, in case of Visual C++, even when it is simply overridden.

Include file:

    #include <wx/defs.h>

## ◆ wxDEPRECATED_BUT_USED_INTERNALLY_INLINE

#define wxDEPRECATED_BUT_USED_INTERNALLY_INLINE | ( |  | func,
|  |  | body
| ) |  |

Combination of wxDEPRECATED_BUT_USED_INTERNALLY() and wxDEPRECATED_INLINE().

This macro should be used for deprecated functions called by the library itself (usually for backwards compatibility reasons) and which are defined inline.

Include file:

    #include <wx/defs.h>

## ◆ wxDEPRECATED_INLINE

#define wxDEPRECATED_INLINE | ( |  | func,
|  |  | body
| ) |  |

This macro is similar to wxDEPRECATED() but can be used to not only declare the function function as deprecated but to also provide its (inline) implementation body.

It can be used as following:

class wxFoo
{
public:
// OldMethod() is deprecated, use NewMethod() instead
void NewMethod();
wxDEPRECATED_INLINE( void OldMethod(), NewMethod(); )
};
wxDEPRECATED_INLINE
#define wxDEPRECATED_INLINE(func, body)
This macro is similar to wxDEPRECATED() but can be used to not only declare the function function as ...
Definition: defs.h:1783

Include file:

    #include <wx/defs.h>

## ◆ wxDEPRECATED_MSG

#define wxDEPRECATED_MSG | ( |  | msg | ) |

Generate deprecation warning with the given message when a function is used.

This macro can be used to generate a warning indicating that a function is deprecated (i.e. scheduled for removal in the future) and explaining why is it so and/or what should it be replaced with. It applies to the declaration following it, for example:

wxDEPRECATED_MSG("use safer overload returning wxString instead")
void wxGetSomething(char* buf, size_t len);
wxString wxGetSomething();
wxDEPRECATED_MSG
#define wxDEPRECATED_MSG(msg)
Generate deprecation warning with the given message when a function is used.
Definition: defs.h:1725

Since
  3.0

Include file:

    #include <wx/defs.h>

## ◆ wxDYNLIB_FUNCTION

#define wxDYNLIB_FUNCTION | ( |  | type,
|  |  | name,
|  |  | dynlib
| ) |  |

When loading a function from a DLL you always have to cast the returned `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 `pfn` prefix and initialized with the function name from the wxDynamicLibrary dynlib.

Parameters

  type | The type of the function.
  name | The name of the function to load, not a string (without quotes, it is quoted automatically by the macro).
  dynlib | The library to load the function from.

Include file:

    #include <wx/dynlib.h>

## ◆ wxHAS_CXX17_INCLUDE

#define wxHAS_CXX17_INCLUDE | ( |  | header | ) |

Returns true if the compiler is using the C++17 standard and the header header exists.

This is designed to guard inclusion of C++17 standard library headers, since MSVC will warn if a header for a newer C++ standard is included when compiling for an older standard.

Since
  3.3.0

Include file:

    #include <wx/defs.h>

## ◆ wxLongLongFmtSpec

#define wxLongLongFmtSpec

This macro is defined to contain the `printf()` format specifier using which 64 bit integer numbers (i.e.

those of type `wxLongLong_t`) can be printed. Example of using it:

wxLongLong_t ll = wxLL(0x1234567890abcdef);
printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
wxLongLongFmtSpec
#define wxLongLongFmtSpec
This macro is defined to contain the printf() format specifier using which 64 bit integer numbers (i....
Definition: longlong.h:347
wxLL
wxLongLong_t wxLL(number)
This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit...

See also
  wxLL()

Include file:

    #include <wx/longlong.h>

## ◆ wxON_BLOCK_EXIT

#define wxON_BLOCK_EXIT | ( |  | function,
|  |  | ...
| ) |  |

Ensure that the global function with a few (up to some implementation-defined limit) is executed on scope exit, whether due to a normal function return or because an exception has been thrown.

A typical example of its usage:

void *buf = malloc(size);
wxON_BLOCK_EXIT1(free, buf);
wxON_BLOCK_EXIT1
#define wxON_BLOCK_EXIT1(function, p1)
Definition: scopeguard.h:80

Please see the original article by Andrei Alexandrescu and Petru Marginean published in December 2000 issue of C/C++ Users Journal for more details.

See also
  wxON_BLOCK_EXIT_OBJ0()

Include file:

    #include <wx/scopeguard.h>

## ◆ wxON_BLOCK_EXIT0

#define wxON_BLOCK_EXIT0 | ( |  | function | ) |

## ◆ wxON_BLOCK_EXIT1

#define wxON_BLOCK_EXIT1 | ( |  | function,
|  |  | p1
| ) |  |

## ◆ wxON_BLOCK_EXIT2

#define wxON_BLOCK_EXIT2 | ( |  | function,
|  |  | p1,
|  |  | p2
| ) |  |

## ◆ wxON_BLOCK_EXIT3

#define wxON_BLOCK_EXIT3 | ( |  | function,
|  |  | p1,
|  |  | p2,
|  |  | p3
| ) |  |

## ◆ wxON_BLOCK_EXIT_NULL

#define wxON_BLOCK_EXIT_NULL | ( |  | ptr | ) |

This macro sets the pointer passed to it as argument to nullptr on scope exit.

It may be used instead of wxON_BLOCK_EXIT_SET() when the value being set is nullptr.

Include file:

    #include <wx/scopeguard.h>

## ◆ wxON_BLOCK_EXIT_OBJ

#define wxON_BLOCK_EXIT_OBJ | ( |  | object,
|  |  | method,
|  |  | ...
| ) |  |

This family of macros is similar to wxON_BLOCK_EXIT(), but calls a method of the given object instead of a free function.

Include file:

    #include <wx/scopeguard.h>

## ◆ wxON_BLOCK_EXIT_OBJ0

#define wxON_BLOCK_EXIT_OBJ0 | ( |  | object,
|  |  | method
| ) |  |

## ◆ wxON_BLOCK_EXIT_OBJ1

#define wxON_BLOCK_EXIT_OBJ1 | ( |  | object,
|  |  | method,
|  |  | p1
| ) |  |

## ◆ wxON_BLOCK_EXIT_OBJ2

#define wxON_BLOCK_EXIT_OBJ2 | ( |  | object,
|  |  | method,
|  |  | p1,
|  |  | p2
| ) |  |

## ◆ wxON_BLOCK_EXIT_OBJ3

#define wxON_BLOCK_EXIT_OBJ3 | ( |  | object,
|  |  | method,
|  |  | p1,
|  |  | p2,
|  |  | p3
| ) |  |

## ◆ wxON_BLOCK_EXIT_SET

#define wxON_BLOCK_EXIT_SET | ( |  | var,
|  |  | value
| ) |  |

This macro sets a variable to the specified value on scope exit.

Example of usage:

void foo()
{
bool isDoingSomething = true;
{
wxON_BLOCK_EXIT_SET(isDoingSomething, false);
... do something ...
}
... isDoingSomething is false now ...
}
wxON_BLOCK_EXIT_SET
#define wxON_BLOCK_EXIT_SET(var, value)
This macro sets a variable to the specified value on scope exit.
Definition: scopeguard.h:140

Notice that value is copied, i.e. stored by value, so it can be a temporary object returned by a function call, for example.

See also
  wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL()

Include file:

    #include <wx/scopeguard.h>

## ◆ wxON_BLOCK_EXIT_THIS

#define wxON_BLOCK_EXIT_THIS | ( |  | method,
|  |  | ...
| ) |  |

This family of macros is similar to wxON_BLOCK_OBJ(), but calls a method of `this` object instead of a method of the specified object.

Include file:

    #include <wx/scopeguard.h>

## ◆ wxON_BLOCK_EXIT_THIS0

#define wxON_BLOCK_EXIT_THIS0 | ( |  | method | ) |

## ◆ wxON_BLOCK_EXIT_THIS1

#define wxON_BLOCK_EXIT_THIS1 | ( |  | method,
|  |  | p1
| ) |  |

## ◆ wxON_BLOCK_EXIT_THIS2

#define wxON_BLOCK_EXIT_THIS2 | ( |  | method,
|  |  | p1,
|  |  | p2
| ) |  |

## ◆ wxON_BLOCK_EXIT_THIS3

#define wxON_BLOCK_EXIT_THIS3 | ( |  | method,
|  |  | p1,
|  |  | p2,
|  |  | p3
| ) |  |

## ◆ wxOVERRIDE

#define wxOVERRIDE override

Expands to "override" keyword.

This macro is deprecated and exists only for compatibility, just use `override` directly in the new code.

Include file:

    #include <wx/defs.h>

Since
  3.1.0

## ◆ wxSTRINGIZE

#define wxSTRINGIZE | ( |  | 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 `#` operator which doesn't work with macros).

Notice that this macro always produces a `char` string, use wxSTRINGIZE_T() to build a wide string Unicode build.

See also
  wxCONCAT()

Include file:

    #include <wx/cpp.h>

## ◆ wxSTRINGIZE_T

#define wxSTRINGIZE_T | ( |  | 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 wxSTRINGIZE().

Include file:

    #include <wx/cpp.h>

## ◆ wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING

#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING | ( |  | name | ) |

GNU C++ compiler gives a warning for any class whose destructor is private unless it has a friend.

This warning may sometimes be useful but it doesn't make sense for reference counted class which always delete themselves (hence destructor should be private) but don't necessarily have any friends, so this macro is provided to disable the warning in such case. The name parameter should be the name of the class but is only used to construct a unique friend class name internally.

Example of using the macro:

class RefCounted
{
public:
RefCounted() { m_nRef = 1; }
void IncRef() { m_nRef++ ; }
void DecRef() { if ( !--m_nRef ) delete this; }
private:
~RefCounted() = default;
wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
};

Notice that there should be no semicolon after this macro.

Include file:

    #include <wx/defs.h>

## ◆ wxWARN_UNUSED

#define wxWARN_UNUSED __attribute__((warn_unused))

Expands to the "warn_unused" attribute (also known as [[gnu::warn_unused]]) on compilers supporting it (GCC and Clang), otherwise to nothing.

Include file:

    #include <wx/defs.h>

Since
  3.3.0

## Typedef Documentation

## ◆ wxSortCallback

typedef int(* wxSortCallback) (const void *pItem1, const void *pItem2, const void *user_data)

Deprecated:
  Don't use this typedef nor wxQsort() itself in the new code.

Compare function type for use with wxQsort()

Include file:

    #include <wx/utils.h>

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

flags for wxStripMenuCodes

Enumerator
wxStrip_Mnemonics | Strip '&' characters. This flag removes all the ampersands before another character and replaces double ampersands with a single one.
wxStrip_Accel | Strip everything after '\t'. This flags removes everything following the last TAB character in the string, if any.
wxStrip_CJKMnemonics | Strip everything looking like CJK mnemonic. CJK (Chinese, Japanese, Korean) translations sometimes preserve the original English accelerator or mnemonic in the translated string by putting it after the translated string in parentheses, e.g. the string "&File" could be translated as "<translation-of-word-file> (&F)". This flag strips trailing "(&X)" from the string. Since 3.1.3
wxStrip_All | Strip both mnemonics and accelerators. This is the value used by wxStripMenuCodes() by default. Note that, despite the name, this flag does not strip all, as it doesn't include wxStrip_CJKMnemonics for compatibility.
wxStrip_Menu | Strip everything from menu item labels. This flag is used by wxWidgets internally and removes CJK mnemonics from the labels too, in addition to the usual mnemonics and accelerators. It is only suitable for use with the menu items.

## ◆ wxBase64DecodeMode

enum wxBase64DecodeMode

Elements of this enum specify the possible behaviours of wxBase64Decode when an invalid character is encountered.

Enumerator
wxBase64DecodeMode_Strict | Normal behaviour: stop at any invalid characters.
wxBase64DecodeMode_SkipWS | Skip whitespace characters.
wxBase64DecodeMode_Relaxed | The most lenient behaviour: simply ignore all invalid characters.

## Function Documentation

## ◆ endl()

wxTextOutputStream& endl | ( | wxTextOutputStream & | stream | ) |

Writes `'\n'` to stream.

Include file:

    #include <wx/textstrm.h>

## ◆ wxBase64Decode() [1/4]

wxMemoryBuffer wxBase64Decode | ( | const char * | src,
|  | size_t | srcLen = `wxNO_LEN`,
|  | wxBase64DecodeMode | mode = `wxBase64DecodeMode_Strict`,
|  | size_t * | posErr = `nullptr`
| ) |  |

Decode a Base64-encoded string and return decoded contents in a buffer.

See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*) overload for more information about the parameters of this function. The difference of this overload is that it allocates a buffer of necessary size on its own and returns it, freeing you from the need to do it manually. Because of this, it is simpler to use and is recommended for normal use.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Decode() [2/4]

wxMemoryBuffer wxBase64Decode | ( | const wxString & | src,
|  | wxBase64DecodeMode | mode = `wxBase64DecodeMode_Strict`,
|  | size_t * | posErr = `nullptr`
| ) |  |

Decode a Base64-encoded wxString and return decoded contents in a buffer.

See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*) overload for more information about the parameters of this function.

This overload takes as input a wxString and returns the internally-allocated memory as a wxMemoryBuffer, containing the Base64-decoded data.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Decode() [3/4]

size_t wxBase64Decode | ( | void * | dst,
|  | size_t | dstLen,
|  | const char * | src,
|  | size_t | srcLen = `wxNO_LEN`,
|  | wxBase64DecodeMode | mode = `wxBase64DecodeMode_Strict`,
|  | size_t * | posErr = `nullptr`
| ) |  |

This function decodes a Base64-encoded string.

This overload is a raw decoding function and decodes the data into the provided buffer dst of the given size dstLen. An error is returned if the buffer is not large enough – that is not at least wxBase64DecodedSize(srcLen) bytes. Notice that the buffer will not be nullptr-terminated.

This overload returns the number of bytes written to the buffer or the necessary buffer size if dst was nullptr or `wxCONV_FAILED` on error, e.g. if the output buffer is too small or invalid characters were encountered in the input string.

Parameters

  dst | Pointer to output buffer, may be nullptr to just compute the necessary buffer size.
  dstLen | The size of the output buffer, ignored if dst is nullptr.
  src | The input string, must not be nullptr. For the version using wxString, the input string should contain only ASCII characters.
  srcLen | The length of the input string or special value wxNO_LEN if the string is nullptr-terminated and the length should be computed by this function itself.
  mode | This parameter specifies the function behaviour when invalid characters are encountered in input. By default, any such character stops the decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the white space characters are silently skipped instead. And if it is wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
  posErr | If this pointer is non-null and an error occurs during decoding, it is filled with the index of the invalid character.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Decode() [4/4]

size_t wxBase64Decode | ( | void * | dst,
|  | size_t | dstLen,
|  | const wxString & | str,
|  | wxBase64DecodeMode | mode = `wxBase64DecodeMode_Strict`,
|  | size_t * | posErr = `nullptr`
| ) |  |

Decode a Base64-encoded wxString.

See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*) overload for more information about the parameters of this function, the only difference between it and this one is that a wxString is used instead of a `char*` pointer and its length.

Since
  2.9.1

Include file:

    #include <wx/base64.h>

## ◆ wxBase64DecodedSize()

size_t wxBase64DecodedSize | ( | size_t | srcLen | ) |

Returns the size of the buffer necessary to contain the data encoded in a base64 string of length srcLen.

This can be useful for allocating a buffer to be passed to wxBase64Decode().

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Encode() [1/3]

size_t wxBase64Encode | ( | char * | dst,
|  | size_t | dstLen,
|  | const void * | src,
|  | size_t | srcLen
| ) |  |

This function encodes the given data using base64.

To allocate the buffer of the correct size, use wxBase64EncodedSize() or call this function with dst set to nullptr – it will then return the necessary buffer size.

This raw encoding function overload writes the output string into the provided buffer; the other overloads return it as a wxString.

Parameters

  dst | The output buffer, may be nullptr to retrieve the needed buffer size.
  dstLen | The output buffer size, ignored if dst is nullptr.
  src | The input buffer, must not be nullptr.
  srcLen | The length of the input data.

Returns
  `wxCONV_FAILED` if the output buffer is too small.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Encode() [2/3]

wxString wxBase64Encode | ( | const void * | src,
|  | size_t | srcLen
| ) |  |

This function encodes the given data using base64 and returns the output as a wxString.

There is no error return.

Parameters

  src | The input buffer, must not be nullptr.
  srcLen | The length of the input data.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64Encode() [3/3]

wxString wxBase64Encode | ( | const wxMemoryBuffer & | buf | ) |

This function encodes the given data using base64 and returns the output as a wxString.

There is no error return.

Include file:

    #include <wx/base64.h>

## ◆ wxBase64EncodedSize()

size_t wxBase64EncodedSize | ( | size_t | len | ) |

Returns the length of the string with base64 representation of a buffer of specified size len.

This can be useful for allocating the buffer passed to wxBase64Encode().

Include file:

    #include <wx/base64.h>

## ◆ wxDDECleanUp()

void wxDDECleanUp | ( |  | ) |

Called when wxWidgets exits, to clean up the DDE system.

This no longer needs to be called by the application.

See also
  wxDDEInitialize()

Include file:

    #include <wx/dde.h>

## ◆ wxDDEInitialize()

void wxDDEInitialize | ( |  | ) |

Initializes the DDE system.

May be called multiple times without harm.

This no longer needs to be called by the application: it will be called by wxWidgets if necessary.

See also
  wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp()

Include file:

    #include <wx/dde.h>

## ◆ wxDecToHex() [1/3]

wxString wxDecToHex | ( | unsigned char | dec | ) |

Convert decimal integer to 2-character hexadecimal string.

Parameters

  dec | A number to be converted.

Returns
  String containing hexadecimal string, not prefixed by `0x`, composed of uppercase characters.

Include file:

    #include <wx/utils.h>

## ◆ wxDecToHex() [2/3]

void wxDecToHex | ( | unsigned char | dec,
|  | char * | ch1,
|  | char * | ch2
| ) |  |

Returns 2 characters of hexadecimal representation of a given number.

Parameters

  dec | A number to be converted.
  ch1 | Pointer to the variable that receives 1st hexadecimal character. It must not be nullptr.
  ch2 | Pointer to the variable that receives 2nd hexadecimal character. It must not be nullptr.

Remarks
  Returned characters are uppercase.

Include file:

    #include <wx/utils.h>

## ◆ wxDecToHex() [3/3]

void wxDecToHex | ( | unsigned char | dec,
|  | wxChar * | buf
| ) |  |

Convert decimal integer to 2-character hexadecimal string.

Parameters

  dec | A number to be converted.
  buf | A pointer to the buffer that receives hexadecimal string (not prefixed by `0x`). This buffer should be large enough to hold at least 3 characters: 2 hexadecimal digits and the terminating null character.

Remarks
  Returned string is composed of uppercase hexadecimal characters.

Include file:

    #include <wx/utils.h>

## ◆ wxDELETE()

template<typename T >

void wxDELETE | ( | T *& | ptr | ) |

A function which deletes and nulls the pointer.

This function uses operator delete to free the pointer and also sets it to nullptr. Notice that this does not work for arrays, use wxDELETEA() for them.

MyClass *ptr = new MyClass;
...
wxDELETE(ptr);
wxASSERT(!ptr);
wxASSERT
#define wxASSERT(condition)
Assert macro.
Definition: debug.h:75

Include file:

    #include <wx/defs.h>

## ◆ wxDELETEA()

template<typename T >

void wxDELETEA | ( | T *& | array | ) |

A function which deletes and nulls the pointer.

This function uses vector operator delete (`delete`[]) to free the array pointer and also sets it to nullptr. Notice that this does not work for non-array pointers, use wxDELETE() for them.

MyClass *array = new MyClass[17];
...
wxDELETEA(array);
wxASSERT(!array);

See also
  wxDELETE()

Include file:

    #include <wx/defs.h>

## ◆ wxDumpWindow()

wxString wxDumpWindow | ( | const wxWindow * | window | ) |

Return a string with human-readable platform-specific description of the window useful for diagnostic purposes.

The string returned from this function doesn't have any fixed form and can vary between different wxWidgets ports and versions, but contains some useful description of the window and uniquely identifies it. This can be useful to include in debug or tracing messages.

Parameters

  window | Window pointer which is allowed to be nullptr.

Include file:

    #include <wx/window.h>

Since
  3.1.6

## ◆ wxEnableTopLevelWindows()

void wxEnableTopLevelWindows | ( | bool | enable = `true` | ) |

This function enables or disables all top level windows.

It is used by wxSafeYield().

Include file:

    #include <wx/utils.h>

## ◆ wxFindMenuItemId()

int wxFindMenuItemId | ( | wxFrame * | frame,
|  | const wxString & | menuString,
|  | const wxString & | itemString
| ) |  |

Find a menu item identifier associated with the given frame's menu bar.

Include file:

    #include <wx/utils.h>

## ◆ wxFindWindowAtPoint()

wxWindow* wxFindWindowAtPoint | ( | const wxPoint & | pt | ) |

Find the deepest window at the given mouse position in screen coordinates, returning the window if found, or nullptr if not.

This function takes child windows at the given position into account even if they are disabled. The hidden children are however skipped by it.

Include file:

    #include <wx/utils.h>

## ◆ wxFindWindowAtPointer()

wxWindow* wxFindWindowAtPointer | ( | wxPoint & | pt | ) |

Find the deepest window at the mouse pointer position, returning the window and current pointer position in screen coordinates.

Include file:

    #include <wx/window.h>

## ◆ wxFindWindowByLabel()

wxWindow* wxFindWindowByLabel | ( | const wxString & | label,
|  | wxWindow * | parent = `nullptr`
| ) |  |

Deprecated:
  Replaced by wxWindow::FindWindowByLabel().

Find a window by its label. Depending on the type of window, the label may be a window title or panel item label. If parent is nullptr, the search will start from all top-level frames and dialog boxes; if non-null, the search will be limited to the given window hierarchy. The search is recursive in both cases.

Include file:

    #include <wx/utils.h>

## ◆ wxFindWindowByName()

wxWindow* wxFindWindowByName | ( | const wxString & | name,
|  | wxWindow * | parent = `nullptr`
| ) |  |

Deprecated:
  Replaced by wxWindow::FindWindowByName().

Find a window by its name (as given in a window constructor or Create function call). If parent is nullptr, the search will start from all top-level frames and dialog boxes; if non-null, the search will be limited to the given window hierarchy. The search is recursive in both cases.

If no such named window is found, wxFindWindowByLabel() is called.

Include file:

    #include <wx/utils.h>

## ◆ wxFromString() [1/2]

bool wxFromString | ( | const wxString & | string,
|  | wxColour * | colour
| ) |  |

Converts string to a wxColour best represented by the given string.

Returns true on success.

See also
  wxToString(const wxColour&)

Include file:

    #include <wx/colour.h>

## ◆ wxFromString() [2/2]

bool wxFromString | ( | const wxString & | string,
|  | wxFont * | font
| ) |  |

Converts string to a wxFont best represented by the given string.

Returns true on success.

See also
  wxToString(const wxFont&)

Include file:

    #include <wx/font.h>

## ◆ wxGetActiveWindow()

wxWindow* wxGetActiveWindow | ( |  | ) |

Gets the currently active window (implemented for MSW and GTK only currently, always returns nullptr in the other ports).

Include file:

    #include <wx/window.h>

## ◆ wxGetBatteryState()

wxBatteryState wxGetBatteryState | ( |  | ) |

Returns battery state as one of `wxBATTERY_NORMAL_STATE`, `wxBATTERY_LOW_STATE`, `wxBATTERY_CRITICAL_STATE`, `wxBATTERY_SHUTDOWN_STATE` or `wxBATTERY_UNKNOWN_STATE`.

Currently only implemented on MS Windows; returns `wxBATTERY_UNKNOWN_STATE` elsewhere.

Include file:

    #include <wx/utils.h>

## ◆ wxGetDiskSpace()

bool wxGetDiskSpace | ( | const wxString & | path,
|  | wxLongLong | total = `nullptr`,
|  | wxLongLong | free = `nullptr`
| ) |  |

This function returns the total number of bytes and number of free bytes on the disk containing the directory path (it should exist).

Both total and free parameters may be nullptr if the corresponding information is not needed.

Since
  2.3.2

Note
  The generic Unix implementation depends on the system having the `statfs()` or `statvfs()` function.

Returns
  true on success, false if an error occurred (for example, the directory doesn’t exist).

Include file:

    #include <wx/utils.h>

## ◆ wxGetDisplayName()

wxString wxGetDisplayName | ( |  | ) |

Under X only, returns the current display name.

See also
  wxSetDisplayName()

Include file:

    #include <wx/utils.h>

## ◆ wxGetKeyState()

bool wxGetKeyState | ( | wxKeyCode | key | ) |

For normal keys, returns true if the specified key is currently down.

For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns true if the key is toggled such that its LED indicator is lit. There is currently no way to test whether togglable keys are up or down.

Even though there are virtual key codes defined for mouse buttons, they cannot be used with this function currently.

In wxGTK, this function can be only used with modifier keys (`WXK_ALT`, `WXK_CONTROL` and `WXK_SHIFT`) when not using X11 backend currently.

Include file:

    #include <wx/utils.h>

## ◆ wxGetMousePosition()

wxPoint wxGetMousePosition | ( |  | ) |

Returns the mouse position in screen coordinates.

Include file:

    #include <wx/utils.h>

## ◆ wxGetMouseState()

wxMouseState wxGetMouseState | ( |  | ) |

Returns the current state of the mouse.

Returns a wxMouseState instance that contains the current position of the mouse pointer in screen coordinates, as well as boolean values indicating the up/down status of the mouse buttons and the modifier keys.

Include file:

    #include <wx/utils.h>

## ◆ wxGetPowerType()

wxPowerType wxGetPowerType | ( |  | ) |

Returns the type of power source as one of `wxPOWER_SOCKET`, `wxPOWER_BATTERY` or `wxPOWER_UNKNOWN`.

Currently only implemented on MS Windows; returns `wxPOWER_UNKNOWN` elsewhere.

Include file:

    #include <wx/utils.h>

## ◆ wxGetStockLabel()

wxString wxGetStockLabel | ( | wxWindowID | id,
|  | long | flags = `wxSTOCK_WITH_MNEMONIC`
| ) |  |

Returns label that should be used for given id element.

Parameters

  id | Given id of the wxMenuItem, wxButton, wxToolBar tool, etc.
  flags | Combination of the elements of wxStockLabelQueryFlag.

Include file:

    #include <wx/stockitem.h>

## ◆ wxGetTopLevelParent()

wxWindow* wxGetTopLevelParent | ( | wxWindow * | window | ) |

Returns the first top level parent of the given window, or in other words, the frame or dialog containing it, or nullptr.

Notice that if window is itself already a TLW, it is returned directly.

Include file:

    #include <wx/window.h>

## ◆ wxHexToDec() [1/2]

int wxHexToDec | ( | const char * | buf | ) |

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ wxHexToDec() [2/2]

int wxHexToDec | ( | const wxString & | buf | ) |

Convert 2-character hexadecimal string to decimal integer.

Parameters

  buf | String containing uppercase hexadecimal characters, not prefixed by `0x`. Its length must be at least 2 characters. If it is longer than 2 characters, only first two will be converted to the number.

Returns
  An integer number between 0 and 255 that is equivalent to the number in buf, or `-1` if buf is not a hexadecimal string.

Include file:

    #include <wx/utils.h>

## ◆ wxLaunchDefaultApplication()

bool wxLaunchDefaultApplication | ( | const wxString & | document,
|  | int | flags = `0`
| ) |  |

Opens the document in the application associated with the files of this type.

The flags parameter is currently not used

Returns true if the application was successfully launched.

See also
  wxLaunchDefaultBrowser(), wxExecute()

Include file:

    #include <wx/utils.h>

## ◆ wxLaunchDefaultBrowser()

bool wxLaunchDefaultBrowser | ( | const wxString & | url,
|  | int | flags = `0`
| ) |  |

Opens the url in user's default browser.

If the flags parameter contains `wxBROWSER_NEW_WINDOW` flag, a new window is opened for the URL (currently this is only supported under Windows).

And unless the flags parameter contains `wxBROWSER_NOBUSYCURSOR` flag, a busy cursor is shown while the browser is being launched (using wxBusyCursor).

The parameter url is interpreted as follows:

- if it has a valid scheme (e.g. `"file:"`, `"http:"` or `"mailto:"`) it is passed to the appropriate browser configured in the user system.
- if it has no valid scheme (e.g. it's a local file path without the `"file:"` prefix), then wxFileExists and wxDirExists are used to test if it's a local file/directory; if it is, then the browser is called with the url parameter eventually prefixed by `"file:"`.
- if it has no valid scheme and it's not a local file/directory, then `"http:"` is prepended and the browser is called.

Returns true if the application was successfully launched.

Note
  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).

See also
  wxLaunchDefaultApplication(), wxExecute()

Include file:

    #include <wx/utils.h>

## ◆ wxLL()

wxLongLong_t wxLL | ( | number |  | ) |

This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit compile time constants:

wxLongLong_t ll = wxLL(0x1234567890abcdef);

See also
  wxULL(), wxLongLong

Include file:

    #include <wx/longlong.h>

## ◆ wxLoadUserResource() [1/2]

bool wxLoadUserResource | ( | const void ** | outData,
|  | size_t * | outLen,
|  | const wxString & | resourceName,
|  | const wxChar * | resourceType = `"TEXT"`,
|  | WXHINSTANCE | module = `0`
| ) |  |

Loads an object from Windows resource file.

This function loads the resource with the given name and type from the resources embedded into a Windows application.

The typical use for it is to load some data from the data files embedded into the program itself. For example, you could have the following fragment in your ``.rc file

mydata MYDATA "myfile.dat"

and then use it in the following way:

const void* data = nullptr;
size_t size = 0;
if ( !wxLoadUserResource(&data, &size, "mydata", L"MYDATA") ) {
... handle error ...
}
else {
// Use the data in any way, for example:
wxMemoryInputStream is(data, size);
... read the data from stream ...
}
wxMemoryInputStream
This class allows using all methods taking a wxInputStream reference to read in-memory data.
Definition: mstream.h:99
wxLoadUserResource
bool wxLoadUserResource(const void **outData, size_t *outLen, const wxString &resourceName, const wxChar *resourceType="TEXT", WXHINSTANCE module=0)
Loads an object from Windows resource file.

Parameters

  outData | Filled with the pointer to the data on successful return. Notice that this pointer does not need to be freed by the caller.
  outLen | Filled with the length of the data in bytes.
  resourceName | The name of the resource to load.
  resourceType | The type of the resource in usual Windows format, i.e. either a real string like "MYDATA" or an integer created by the standard Windows `MAKEINTRESOURCE()` macro, including any constants for the standard resources types like `RT_RCDATA`.
  module | The `HINSTANCE` of the module to load the resources from. The current module is used by default.

Returns
  true if the data was loaded from resource or false if it couldn't be found (in which case no error is logged) or was found but couldn't be loaded (which is unexpected and does result in an error message).

This function is available under Windows only.

##

Library: wxBase

Include file:

    #include <wx/utils.h>

Since
  2.9.1

## ◆ wxLoadUserResource() [2/2]

char* wxLoadUserResource | ( | const wxString & | resourceName,
|  | const wxChar * | resourceType = `"TEXT"`,
|  | int * | pLen = `nullptr`,
|  | WXHINSTANCE | module = `0`
| ) |  |

Loads a user-defined Windows resource as a string.

This is a wrapper for the general purpose overload wxLoadUserResource(const void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be more convenient for the string data, but does an extra copy compared to the general version.

Parameters

  resourceName | The name of the resource to load.
  resourceType | The type of the resource in usual Windows format, i.e. either a real string like "MYDATA" or an integer created by the standard Windows `MAKEINTRESOURCE()` macro, including any constants for the standard resources types like `RT_RCDATA`.
  pLen | Filled with the length of the returned buffer if it is non-null. This parameter should be used if NUL characters can occur in the resource data. It is new since wxWidgets 2.9.1
  module | The `HINSTANCE` of the module to load the resources from. The current module is used by default. This parameter is new since wxWidgets 2.9.1.

Returns
  A pointer to the data to be `delete[]`d by caller on success or nullptr on error.

This function is available under Windows only.

##

Library: wxBase

Include file:

    #include <wx/utils.h>

## ◆ wxMakeGuard()

template<typename F , typename P1 , ... , typename PN >

wxScopeGuard wxMakeGuard | ( | F | func,
|  | P1 | p1,
|  |  | ...,
|  | PN | pN
| ) |  |

Returns a scope guard object which will call the specified function with the given parameters on scope exit.

This function is overloaded to take several parameters up to some implementation-defined (but relatively low) limit.

The func should be a functor taking parameters of the types P1, ..., PN, i.e. the expression `func(p1, ..., pN)` should be valid.

## ◆ wxNewId()

wxWindowID wxNewId | ( |  | ) |

Deprecated:
  Ids generated by it can conflict with the Ids defined by the user code, use `wxID_ANY` to assign ids which are guaranteed to not conflict with the user-defined ids for the controls and menu items you create instead of using this function.

Generates an integer identifier unique to this run of the program.

See also
  wxRegisterId()

Include file:

    #include <wx/utils.h>

## ◆ wxQsort()

void wxQsort | ( | void * | pbase,
|  | size_t | total_elems,
|  | size_t | size,
|  | wxSortCallback | cmp,
|  | const void * | user_data
| ) |  |

Deprecated:
  Use `std::sort()` in the new code.

Function implementing quick sort algorithm.

This function sorts total_elems objects of size size located at pbase. It uses cmp function for comparing them and passes user_data pointer to the comparison function each time it's called.

Include file:

    #include <wx/utils.h>

## ◆ wxRegisterId()

void wxRegisterId | ( | wxWindowID | id | ) |

Ensures that Ids subsequently generated by wxNewId() do not clash with the given id.

Include file:

    #include <wx/utils.h>

## ◆ wxSecureZeroMemory()

void wxSecureZeroMemory | ( | void * | p,
|  | size_t | n
| ) |  |

Fills the memory block with zeros in a way that is guaranteed not to be optimized away by the compiler.

Parameters

  p | Pointer to the memory block to be zeroed, must be non-null.
  n | The number of bytes to zero.

Note
  If security is vitally important in your use case, please have a look at the implementations and decide whether you trust them to behave as promised. Depending on the platform and available libraries, this may be implemented as `RtlSecureZeroMemory` (MS Windows), `explicit_bzero()` (FreeBSD), `memset_s()` (macOS), or a generic method which uses `volatile` to avoid the call from being optimized away.

Include file:

    #include <wx/utils.h>

Since
  3.1.6

## ◆ wxSetDisplayName()

void wxSetDisplayName | ( | const wxString & | displayName | ) |

Under X only, sets the current display name.

This is the X host and display name such as "colonsay:0.0", and the function indicates which display should be used for creating windows from this point on. Setting the display within an application allows multiple displays to be used.

See also
  wxGetDisplayName()

Include file:

    #include <wx/utils.h>

## ◆ wxSsize()

template<class C >

int wxSsize | ( | const C & | c | ) |

Return the size of the container as int.

This is similar to C++20 std::ssize() but can be used even even when not using C++20 (if you do use it, please use the standard function).

Include file:

    #include <wx/defs.h>

Since
  3.3.0

## ◆ wxStripMenuCodes()

wxString wxStripMenuCodes | ( | const wxString & | str,
|  | int | flags = `wxStrip_All`
| ) |  |

Strips any menu codes from str and returns the result.

By default, the functions strips both the mnemonics character (`'&'`) 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 `\t` (TAB) character. By using flags of `wxStrip_Mnemonics` or `wxStrip_Accel` to strip only the former or the latter part, respectively.

Notice that in most cases wxMenuItem::GetLabelFromText() or wxControl::GetLabelText() can be used instead.

Include file:

    #include <wx/utils.h>

## ◆ wxSwap()

template<typename T >

void wxSwap | ( | T & | first,
|  | T & | second
| ) |  |

Swaps the contents of two variables.

This is similar to std::swap() but can be used even on the platforms where the standard C++ library is not available (if you don't target such platforms, please use std::swap() instead).

The function relies on type T being copy constructible and assignable.

Example of use:

int x = 3,
y = 4;
wxSwap(x, y);
wxASSERT( x == 4 && y == 3 );
wxSwap
void wxSwap(T &first, T &second)
Swaps the contents of two variables.

## ◆ wxToString() [1/2]

wxString wxToString | ( | const wxColour & | colour | ) |

Converts the given wxColour into a string.

See also
  wxFromString(const wxString&, wxColour*)

Include file:

    #include <wx/colour.h>

## ◆ wxToString() [2/2]

wxString wxToString | ( | const wxFont & | font | ) |

Converts the given wxFont into a string.

See also
  wxFromString(const wxString&, wxFont*)

Include file:

    #include <wx/font.h>

## ◆ wxULL()

wxLongLong_t wxULL | ( | number |  | ) |

This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit compile time constants:

unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
wxULL
wxLongLong_t wxULL(number)
This macro is defined for the platforms with a native 64 bit integer type and allow the use of 64 bit...

See also
  wxLL(), wxLongLong

Include file:

    #include <wx/longlong.h>

## ◆ wxVaCopy()

void wxVaCopy | ( | va_list | argptrDst,
|  | va_list | argptrSrc
| ) |  |

This macro is the same as the standard C99 `va_copy` for the compilers which support it or its replacement for those that don't.

It must be used to preserve the value of a `va_list` object if you need to use it after passing it to another function because it can be modified by the latter.

As with `va_start`, each call to `wxVaCopy` must have a matching `va_end`.

Include file:

    #include <wx/defs.h>