| Version: 3.3.1

Macros | Functions
Graphics Device Interface (GDI)
Functions and Macros by Category

## Detailed Description

The following are functions and macros related to GDI (Graphics Device Interface) access.

Related Overviews: Device Contexts

Related class group: Graphics Device Interface (GDI)

## Macros
#define | wxDROP_ICON(name)
| This macro creates either a cursor (MSW) or an icon (elsewhere) with the given name (of type `const char*`). More...
#define | wxBITMAP(bitmapName)
| This macro loads a bitmap from either application resources (on the platforms for which they exist, i.e. Windows) or from an XPM file. More...
#define | wxBITMAP_PNG(bitmapName)
| Creates a bitmap from either application resources or embedded image data in PNG format. More...
#define | wxBITMAP_PNG_FROM_DATA(bitmapName)
| Creates a bitmap from embedded image data in PNG format. More...
#define | wxICON(iconName)
| This macro loads an icon from either application resources (on the platforms for which they exist, i.e. Windows) or from an XPM file. More...

## Functions
bool | wxIsDragResultOk (wxDragResult res)
| Returns true if res indicates that something was done during a DnD operation, i.e. More...
bool | wxColourDisplay ()
| Returns true if the display is colour, false otherwise. More...
int | wxDisplayDepth ()
| Returns the depth of the display (a value of 1 denotes a monochrome display). More...
void | wxSetCursor (const wxCursorBundle &cursors)
| Globally sets the cursor. More...
void | wxClientDisplayRect (int *x, int *y, int *width, int *height)
| Returns the dimensions of the work area on the display. More...
wxRect | wxGetClientDisplayRect ()
| Returns the dimensions of the work area on the display. More...
wxSize | wxGetDisplayPPI ()
| Returns the display resolution in pixels per inch. More...
void | wxDisplaySize (int *width, int *height)
| Returns the display size in pixels. More...
wxSize | wxGetDisplaySize ()
| Returns the display size in pixels. More...
void | wxDisplaySizeMM (int *width, int *height)
| Returns the display size in millimeters. More...
wxSize | wxGetDisplaySizeMM ()
| Returns the display size in millimeters. More...
bool | wxMakeMetafilePlaceable (const wxString &filename, int minX, int minY, int maxX, int maxY, float scale=1.0)
| Given a filename for an existing, valid metafile (as constructed using wxMetafileDC) makes it into a placeable metafile by prepending a header containing the given bounding box. More...

## Macro Definition Documentation

## ◆ wxBITMAP

#define wxBITMAP | ( |  | bitmapName | ) |

This macro loads a bitmap from either application resources (on the platforms for which they exist, i.e. Windows) or from an XPM file.

You can use `wxHAS_IMAGES_IN_RESOURCES` to check if the XPM needs to be included when using this macro.

See also wxBITMAP_PNG() if you want to use images with alpha channel.

See also
  Including Bitmaps in Your Program, wxICON()

Include file:

    #include <wx/gdicmn.h>

## ◆ wxBITMAP_PNG

#define wxBITMAP_PNG | ( |  | bitmapName | ) |

Creates a bitmap from either application resources or embedded image data in PNG format.

This macro is similar to wxBITMAP() but works with bitmap data in PNG format and not BMP or XPM.

Under Windows the given bitmapName must be present in the application resource file with the type `RCDATA` and refer to a PNG image. I.e. you should have a definition similar to the following in your ``.rc file:

mybitmap RCDATA "mybitmap.png"

to be able to use `wxBITMAP_PNG(mybitmap)` in the code.

Under macOS the file with the specified name and "png" extension must be present in the "Resources" subdirectory of the application bundle.

Under the other platforms, this is equivalent to wxBITMAP_PNG_FROM_DATA() and so loads the image data from the array called `bitmapName_png` that must exist. Notice that it must be an array and not a pointer as the macro needs to be able to determine its size. Such an array can be produced by a number of conversion programs. A very simple one is included in wxWidgets distribution as `misc/scripts/png2c.py`.

Finally notice that you must register PNG image handler to be able to load bitmaps from PNG data. This can be done either by calling wxInitAllImageHandlers() which also registers all the other image formats or including the necessary header:

#include <wx/imagpng.h>
imagpng.h

and calling

wxImage::AddHandler(new wxPNGHandler);
wxImage::AddHandler
static void AddHandler(wxImageHandler *handler)
Register an image handler.
wxPNGHandler
This is the image handler for the PNG format.
Definition: imagpng.h:40

in your application startup code.

See also
  Including Bitmaps in Your Program, wxBITMAP_PNG_FROM_DATA()

Include file:

    #include <wx/gdicmn.h>

Since
  2.9.5

## ◆ wxBITMAP_PNG_FROM_DATA

#define wxBITMAP_PNG_FROM_DATA | ( |  | bitmapName | ) |

Creates a bitmap from embedded image data in PNG format.

This macro is a thin wrapper around wxBitmap::NewFromPNGData() and takes just the base name of the array containing the image data and computes its size internally. In other words, the array called `bitmapName_png` must exist. Notice that it must be an array and not a pointer as the macro needs to be able to determine its size. Such an array can be produced by a number of conversion programs. A very simple one is included in wxWidgets distribution as `misc/scripts/png2c.py`.

You can use wxBITMAP_PNG() to load the PNG bitmaps from resources on the platforms that support this and only fall back to loading them from data under the other ones (i.e. not Windows and not macOS).

Include file:

    #include <wx/gdicmn.h>

Since
  2.9.5

## ◆ wxDROP_ICON

#define wxDROP_ICON | ( |  | name | ) |

This macro creates either a cursor (MSW) or an icon (elsewhere) with the given name (of type `const char*`).

Under MSW, the cursor is loaded from the resource file and the icon is loaded from XPM file under other platforms.

This macro should be used with wxDropSource::wxDropSource().

Returns
  wxCursor on MSW, otherwise returns a wxIcon

Include file:

    #include <wx/dnd.h>

## ◆ wxICON

#define wxICON | ( |  | iconName | ) |

This macro loads an icon from either application resources (on the platforms for which they exist, i.e. Windows) or from an XPM file.

You can use `wxHAS_IMAGES_IN_RESOURCES` to check if the XPM needs to be included when using this macro.

See also wxBITMAP_PNG() if you want to use images with alpha channel.

See also
  Including Bitmaps in Your Program, wxBITMAP()

Include file:

    #include <wx/gdicmn.h>

## Function Documentation

## ◆ wxClientDisplayRect()

void wxClientDisplayRect | ( | int * | x,
|  | int * | y,
|  | int * | width,
|  | int * | height
| ) |  |

Returns the dimensions of the work area on the display.

This is the same as wxGetClientDisplayRect() but allows retrieving the individual components instead of the entire rectangle.

Any of the output pointers can be nullptr if the corresponding value is not needed by the caller.

See also
  wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxColourDisplay()

bool wxColourDisplay | ( |  | ) |

Returns true if the display is colour, false otherwise.

Note
  Use of this function is not recommended in the new code as it only works for the primary display. Use wxDisplay::GetDepth() to retrieve the depth of the appropriate display and compare it with 1 instead.

Include file:

    #include <wx/gdicmn.h>

## ◆ wxDisplayDepth()

int wxDisplayDepth | ( |  | ) |

Returns the depth of the display (a value of 1 denotes a monochrome display).

Note
  Use of this function is not recommended in the new code as it only works for the primary display. Use wxDisplay::GetDepth() to retrieve the depth of the appropriate display instead.

Include file:

    #include <wx/gdicmn.h>

## ◆ wxDisplaySize()

void wxDisplaySize | ( | int * | width,
|  | int * | height
| ) |  |

Returns the display size in pixels.

Note
  Use of this function is not recommended in the new code as it only works for the primary display. Use wxDisplay::GetGeometry() to retrieve the size of the appropriate display instead.

Either of output pointers can be nullptr if the caller is not interested in the corresponding value.

See also
  wxGetDisplaySize(), wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxDisplaySizeMM()

void wxDisplaySizeMM | ( | int * | width,
|  | int * | height
| ) |  |

Returns the display size in millimeters.

Either of output pointers can be nullptr if the caller is not interested in the corresponding value.

See also
  wxGetDisplaySizeMM(), wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxGetClientDisplayRect()

wxRect wxGetClientDisplayRect | ( |  | ) |

Returns the dimensions of the work area on the display.

On Windows this means the area not covered by the taskbar, etc. Other platforms are currently defaulting to the whole display until a way is found to provide this info for all window managers, etc.

See also
  wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxGetDisplayPPI()

wxSize wxGetDisplayPPI | ( |  | ) |

Returns the display resolution in pixels per inch.

The `x` component of the returned wxSize object contains the horizontal resolution and the `y` one – the vertical resolution.

Note
  Use of this function is not recommended in the new code as it only works for the primary display. Use wxDisplay::GetPPI() to retrieve the resolution of the appropriate display instead.

Include file:

    #include <wx/gdicmn.h>

See also
  wxDisplay

Since
  2.9.0

## ◆ wxGetDisplaySize()

wxSize wxGetDisplaySize | ( |  | ) |

Returns the display size in pixels.

Note
  Use of this function is not recommended in the new code as it only works for the primary display. Use wxDisplay::GetGeometry() to retrieve the size of the appropriate display instead.

See also
  wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxGetDisplaySizeMM()

wxSize wxGetDisplaySizeMM | ( |  | ) |

Returns the display size in millimeters.

See also
  wxDisplay

Include file:

    #include <wx/gdicmn.h>

## ◆ wxIsDragResultOk()

bool wxIsDragResultOk | ( | wxDragResult | res | ) |

Returns true if res indicates that something was done during a DnD operation, i.e.

is neither error nor none nor cancel.

## ◆ wxMakeMetafilePlaceable()

bool wxMakeMetafilePlaceable | ( | const wxString & | filename,
|  | int | minX,
|  | int | minY,
|  | int | maxX,
|  | int | maxY,
|  | float | scale = `1.0`
| ) |  |

Given a filename for an existing, valid metafile (as constructed using wxMetafileDC) makes it into a placeable metafile by prepending a header containing the given bounding box.

The bounding box may be obtained from a device context after drawing into it, using the functions wxDC::MinX(), wxDC::MinY(), wxDC::MaxX() and wxDC::MaxY().

In addition to adding the placeable metafile header, this function adds the equivalent of the following code to the start of the metafile data:

SetMapMode(dc, MM_ANISOTROPIC);
SetWindowOrg(dc, minX, minY);
SetWindowExt(dc, maxX - minX, maxY - minY);

This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes.

Placeable metafiles may be imported by many Windows applications, and can be used in RTF (Rich Text Format) files.

scale allows the specification of scale for the metafile.

This function is only available under Windows.

Include file:

    #include <wx/metafile.h>

## ◆ wxSetCursor()

void wxSetCursor | ( | const wxCursorBundle & | cursors | ) |

Globally sets the cursor.

The globally set cursor overrides any cursor set for the individual windows, i.e. the specified cursor will be used for all windows of the application until this function is called again with an empty cursor bundle to restore the default behaviour of using the window-specific cursors.

Note that this function won't update the cursor size if the DPI or user preferred cursor size changes, as this is considered unlikely to happen while this temporary cursor is shown. If you do want to update the cursor size, you need to handle wxEVT_DPI_CHANGED and wxEVT_SYS_METRIC_CHANGED events and call this function again from their handlers.

See also
  wxCursor, wxWindow::SetCursor(), wxWindow::SetCursorBundle()

Include file:

    #include <wx/gdicmn.h>