wxDC(3erl)

🎀 NAME 🎀

Okay so bestie, welcome to wxDC(3erl) — that's the Erlang Module Definition page for the wxDC class, and it's a lot, but we're gonna get through it together. Buckle up. 💖

wxDC — Functions for wxDC class. That's it, that's the name. Short king. 👑

---

✨ DESCRIPTION ✨

A wxDC is a "device context" onto which graphics and text can be drawn. Think of it as a canvas vibe — it's meant to represent all different output devices and it serves up one common abstract API so you can draw on literally any of them. Slay, honestly. 🎨

wxWidgets also offers a whole alternative drawing API built on the modern drawing backends GDI+, CoreGraphics, Cairo and Direct2D. Peep wxGraphicsContext, wxGraphicsRenderer and the related classes. There's also wxGCDC, which links the two APIs together by offering the wxDC API on top of a wxGraphicsContext. Iconic bridging behaviour. 🌉

Now the important part, no cap: wxDC is an abstract base class and cannot be created directly. You use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or wxPrinterDC (not implemented in wx) instead. And heads up — device contexts that are associated with windows (that's wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours by default (starting with wxWidgets 2.9.0), but the other device context classes use system-default values, so you always must set the appropriate fonts and colours before using them. Like, always always. 🙈

In addition to the versions of the methods documented below, there are also versions which accept a single {X,Y} parameter instead of the two wxCoord ones, or {X,Y} and {Width,Height} instead of the four wxCoord parameters. So many versions. We love options. 💅

Beginning with wxWidgets 2.9.0 the entire wxDC code has been reorganized. All platform dependent code (actually, all drawing code) has been moved into backend classes which derive from a common wxDCImpl class. The user-visible classes such as wxClientDC and wxPaintDC merely forward all calls to the backend implementation. Middle-management energy, but make it graphics. 😭

---

🌸 Device and logical units 🌸

In the wxDC context there is a distinction between logical units and device units. This is the part where everybody gets confused, so pay attention bestie.

Device units are the units native to the particular device. E.g. for a screen, a device unit is a pixel. For a printer, the device unit is defined by the resolution of the printer (usually given in DPI: dot-per-inch).

All wxDC functions use logical units instead, unless where explicitly stated. Logical units are arbitrary units mapped to device units using the current mapping mode (see setMapMode/2).

And why do we care? Because this mechanism allows reusing the same code which prints on e.g. a window on the screen to print on e.g. a paper. Write once, print anywhere. Main character code fr fr. 🔥

---

🦋 Support for Transparency / Alpha Channel 🦋

In general wxDC methods don't support alpha transparency and the alpha component of wx_color() is simply ignored — if you want full transparency support you need to use wxGraphicsContext. That's just the rules.

There are, however, a few exceptions, and they're kinda iconic:

• First, under macOS and GTK+ 3 colours with alpha channel are supported in all the normal wxDC-derived classes as they use wxGraphicsContext internally.
• Second, under all platforms wxSVGFileDC (not implemented in wx) also fully supports alpha channel.

In both of these cases the instances of wxPen or wxBrush that are built from wx_color() use the colour's alpha values when stroking or filling. Gorgeous. 🎀

---

🧚 Support for Transformation Matrix 🧚

On some platforms (currently under MSW, GTK+ 3, macOS) wxDC has support for applying an arbitrary affine transformation matrix to its coordinate system (since 3.1.1 this feature is also supported by wxGCDC in all ports).

So how do you know if you got it? Call CanUseTransformMatrix() (not implemented in wx) to check if this support is available, and then call SetTransformMatrix() (not implemented in wx) if it is. If the transformation matrix is not supported, SetTransformMatrix() (not implemented in wx) always simply returns false and doesn't do anything. Polite decline. 💀

⚠️ This feature is only available when the wxUSE_DC_TRANSFORM_MATRIX build option is enabled. Don't come crying to me if it's off, I warned you.

See: Overview dc, wxGraphicsContext, wxDCFontChanger (not implemented in wx), wxDCTextColourChanger (not implemented in wx), wxDCPenChanger (not implemented in wx), wxDCBrushChanger (not implemented in wx), wxDCClipper (not implemented in wx)

wxWidgets docs: wxDC

---

💜 DATA TYPES 💜

One (1) type. She's simple, she's efficient:

wxDC() = wx:wx_object()

---

🍓 EXPORTS 🍓

Alright, this is the long part, so grab a snack. 🍓 Everything here is documented exactly as it appears, so you can trust me.

blit(This, Dest, Size, Source, Src) -> boolean()

Types:

This = wxDC()
Dest = {X :: integer(), Y :: integer()}
Size = {W :: integer(), H :: integer()}
Source = wxDC()
Src = {X :: integer(), Y :: integer()}

No extra blurb on this one — it's just types. Cute and mysterious. ✨

---

blit(This, Dest, Size, Source, Src, Options :: [Option]) -> boolean()

Types:

This = wxDC()
Dest = {X :: integer(), Y :: integer()}
Size = {W :: integer(), H :: integer()}
Source = wxDC()
Src = {X :: integer(), Y :: integer()}
Option =
    {rop, wx:wx_enum()} |
    {useMask, boolean()} |
    {srcPtMask, {X :: integer(), Y :: integer()}}

Copy from a source DC to this DC. With this method you can specify the destination coordinates and the size of area to copy, which will be the same for both the source and target DCs. If you need to apply scaling while copying, use StretchBlit() (not implemented in wx).

Now this bit is lowkey important: notice that source DC coordinates xsrc and ysrc are interpreted using the current source DC coordinate system — i.e. the scale, origin position and axis directions are all taken into account when transforming them to physical (pixel) coordinates. It's giving respect the source's whole situation. 🙌

Remark: There is partial support for blit/6 in wxPostScriptDC, under X.

See: StretchBlit() (not implemented in wx), wxMemoryDC, wxBitmap, wxMask

---

calcBoundingBox(This, X, Y) -> ok

Types:

This = wxDC()
X = Y = integer()

Adds the specified point to the bounding box, which can be retrieved with the minX/1, maxX/1 and minY/1, maxY/1 functions. It's like keeping receipts for your own drawing. 📦

See: resetBoundingBox/1

---

clear(This) -> ok

Types:

This = wxDC()

Clears the device context using the current background brush. Fresh start, clean slate, new era. 🧼

⚠️ Note that the setBackground/2 method must be used to set the brush used by clear/1 — the brush used for filling the shapes set by setBrush/2 is ignored by it. Yes, they're two different brushes. Yes, that trips everyone up.

If no background brush was set, solid white brush is used to clear the device context. Default is just plain white, no thoughts head empty. 🤍

---

crossHair(This, Pt) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Basically the same thing wearing a different outfit. 💅

---

destroyClippingRegion(This) -> ok

Types:

This = wxDC()

Destroys the current clipping region so that none of the DC is clipped. Free at last, free at last. 🦋

See: setClippingRegion/3

---

deviceToLogicalX(This, X) -> integer()

Types:

This = wxDC()
X = integer()

Convert device X coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. That's the whole toolkit right there. 🔧

---

deviceToLogicalXRel(This, X) -> integer()

Types:

This = wxDC()
X = integer()

Convert device X coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation. Use this for converting a width, for example. Widths don't care about your axis drama. 📏

---

deviceToLogicalY(This, Y) -> integer()

Types:

This = wxDC()
Y = integer()

Converts device Y coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. Same deal as the X one, just vertical. ⬆️

---

deviceToLogicalYRel(This, Y) -> integer()

Types:

This = wxDC()
Y = integer()

Convert device Y coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation. Use this for converting a height, for example. 📐

---

drawArc(This, PtStart, PtEnd, Centre) -> ok

Types:

This = wxDC()
PtStart = PtEnd = Centre = {X :: integer(), Y :: integer()}

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

---

drawBitmap(This, Bmp, Pt) -> ok

Types:

This = wxDC()
Bmp = wxBitmap:wxBitmap()
Pt = {X :: integer(), Y :: integer()}

Just the types on this one — no description attached in the original. She's private like that. 🙈

---

drawBitmap(This, Bmp, Pt, Options :: [Option]) -> ok

Types:

This = wxDC()
Bmp = wxBitmap:wxBitmap()
Pt = {X :: integer(), Y :: integer()}
Option = {useMask, boolean()}

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Same bitmap, extra options, more to love. 💖

---

drawCheckMark(This, Rect) -> ok

Types:

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

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

---

drawCircle(This, Pt, Radius) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Radius = integer()

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

---

drawEllipse(This, Rect) -> ok

Types:

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

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

---

drawEllipse(This, Pt, Size) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Size = {W :: integer(), H :: integer()}

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Two ways to draw the same egg, we love versatility. 🌸

---

drawEllipticArc(This, Pt, Sz, Sa, Ea) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Sz = {W :: integer(), H :: integer()}
Sa = Ea = number()

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. An arc but make it elliptical. Weird flex but ok, we respect it. 🌈

---

drawIcon(This, Icon, Pt) -> ok

Types:

😭 And that's genuinely exactly where this part of the page cuts off — the type listing for drawIcon picks up in the next chunk. Don't worry bestie, there's more coming. 🫶

This = wxDC()
Icon = wxIcon:wxIcon()
Pt = {X :: integer(), Y :: integer()}

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

---

✨ drawLabel(This, Text, Rect) -> ok ✨

Types:

This = wxDC()
Text = unicode:chardata()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

drawLabel(This, Text, Rect, Options :: [Option]) -> ok

Types:

This = wxDC()
Text = unicode:chardata()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
Option = {alignment, integer()} | {indexAccel, integer()}

Okay bestie, this is also an overloaded member function, provided for convenience 💅 it differs from the above function only in what argument(s) it accepts. That's the whole vibe check for this one — the Options list is the only thing extra.

---

🎀 drawLine(This, Pt1, Pt2) -> ok 🎀

Types:

This = wxDC()
Pt1 = Pt2 = {X :: integer(), Y :: integer()}

Overloaded member function, provided for convenience — differs from the above function only in what argument(s) it accepts. Yes queen, same disclaimer, we love consistency 💖

drawLines(This, Points) -> ok

Types:

This = wxDC()
Points = [{X :: integer(), Y :: integer()}]

drawLines(This, Points, Options :: [Option]) -> ok

Types:

This = wxDC()
Points = [{X :: integer(), Y :: integer()}]
Option = {xoffset, integer()} | {yoffset, integer()}

Draws lines using an array of points of size n, adding the optional offset coordinate. So good, so clean ✨

The current pen is used for drawing the lines. That's it, that's the rule — the pen you set is the pen that shows up. iykyk 🖊️

---

🦋 drawPolygon(This, Points) -> ok 🦋

Types:

This = wxDC()
Points = [{X :: integer(), Y :: integer()}]

drawPolygon(This, Points, Options :: [Option]) -> ok

Types:

This = wxDC()
Points = [{X :: integer(), Y :: integer()}]
Option =
    {xoffset, integer()} |
    {yoffset, integer()} |
    {fillStyle, wx:wx_enum()}

Draws a filled polygon using an array of points of size n, adding the optional offset coordinate. Iconic behavior, honestly 🌈

The first and last points are automatically closed. You don't gotta do it yourself, she handles it 🙌

The last argument specifies the fill rule: wxODDEVEN_RULE (the default) or wxWINDING_RULE. Note the default, bestie — wxODDEVEN_RULE unless you say otherwise ⭐

The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. So if you're sitting there like "why is my polygon hollow 😭" — check the brush, that's your culprit 💀

---

🌸 drawPoint(This, Pt) -> ok 🌸

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. One point. One little dot. Main character energy for a single pixel 🎀

drawRectangle(This, Rect) -> ok

Types:

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

Overloaded member function, provided for convenience — differs from the above function only in what argument(s) it accepts. Classic overloaded sorry-not-sorry moment 💅

drawRectangle(This, Pt, Sz) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Sz = {W :: integer(), H :: integer()}

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Same rectangle, different shape of arguments. Both slay 🫶

---

🌺 drawRotatedText(This, Text, Point, Angle) -> ok 🌺

Types:

This = wxDC()
Text = unicode:chardata()
Point = {X :: integer(), Y :: integer()}
Angle = number()

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Text but angled, she's quirky like that ✨

drawRoundedRectangle(This, Rect, Radius) -> ok

Types:

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
Radius = number()

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Soft corners, soft life 🎀

drawRoundedRectangle(This, Pt, Sz, Radius) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Sz = {W :: integer(), H :: integer()}
Radius = number()

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Same rounded rectangle, position + size + radius edition 💜

⭐ drawText(This, Text, Pt) -> ok ⭐

Types:

This = wxDC()
Text = unicode:chardata()
Pt = {X :: integer(), Y :: integer()}

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Just text, at a point. Beautiful, no notes 👑

---

🧚 endDoc(This) -> ok 🧚

Types:

This = wxDC()

Ends a document (only relevant when outputting to a printer). So like, if you're not printing, this is lowkey just vibes — but if you are printing, do not skip it, fr fr 🖨️

🧚 endPage(This) -> ok 🧚

Types:

This = wxDC()

Ends a document page (only relevant when outputting to a printer). Same energy, one page at a time 🎀

---

💀 floodFill(This, Pt, Col) -> boolean() 💀

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Col = wx:wx_colour()

floodFill(This, Pt, Col, Options :: [Option]) -> boolean()

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Col = wx:wx_colour()
Option = {style, wx:wx_enum()}

Overloaded member function, provided for convenience — it differs from the above function only in what argument(s) it accepts. Bucket-tool moment, we love a spill 🔥

---

🍓 getBackground(This) -> wxBrush:wxBrush() 🍓

Types:

This = wxDC()

Gets the brush used for painting the background.

See: setBackground/2

🍓 getBackgroundMode(This) -> integer() 🍓

Types:

This = wxDC()

Returns the current background mode: wxPENSTYLE_SOLID or wxPENSTYLE_TRANSPARENT. Two options, that's the whole menu, pick your fighter ✨

See: setBackgroundMode/2

🍓 getBrush(This) -> wxBrush:wxBrush() 🍓

Types:

This = wxDC()

Gets the current brush.

See: setBrush/2

🍓 getCharHeight(This) -> integer() 🍓

Types:

This = wxDC()

Gets the character height of the currently set font. Just the height, she's not gonna overshare 📏

🍓 getCharWidth(This) -> integer() 🍓

Types:

This = wxDC()

Gets the average character width of the currently set font. Average — it's not out here measuring every single glyph, okay? 💅

---

🔍 getClippingBox(This) -> Result 🔍

Types:

Result =
    {X :: integer(),
     Y :: integer(),
     Width :: integer(),
     Height :: integer()}
This = wxDC()

Gets the rectangle surrounding the current clipping region. If no clipping region is set this function returns the extent of the device context. Ngl that's kind of a big deal — no clip means you get the whole canvas 🌈

Remarks from the source docs, translated for the group chat: the clipping region is given in logical coordinates. And here's the parameter tea ☕ — x: if non-NULL, filled in with the logical horizontal coordinate of the top left corner of the clipping region if the function returns true, or 0 otherwise. y: if non-NULL, filled in with the logical vertical coordinate of the top left corner of the clipping region if the function returns true, or 0 otherwise. width: if non-NULL, filled in with the width of the clipping region if the function returns true, or the device context width otherwise. height: if non-NULL, filled in with the height of the clipping region if the function returns true, or the device context height otherwise.

Return: true if there is a clipping region or false if there is no active clipping region — and bestie, note this: that return value is only available since wxWidgets 3.1.2, this function didn't return anything in the previous versions. History lesson, periodt 💀

---

🫶 getFont(This) -> wxFont:wxFont() 🫶

Types:

This = wxDC()

Gets the current font.

Notice that even although each device context object has some default font after creation, this method would return a ?wxNullFont initially and only after calling setFont/2 a valid font is returned.

So like… don't panic if you get a null font right after creating the DC 😭 that's literally documented behavior, she's just not dressed yet. Call setFont/2 first and then come talk to me.

---

🌙 getLayoutDirection(This) -> wx:wx_enum() 🌙

Types:

This = wxDC()

Gets the current layout direction of the device context.

On platforms where RTL layout is supported, the return value will either be wxLayout_LeftToRight or wxLayout_RightToLeft. If RTL layout is not supported, the return value will be wxLayout_Default. Platform-dependent queen 👑

See: setLayoutDirection/2

🌙 getLogicalFunction(This) -> wx:wx_enum() 🌙

Types:

This = wxDC()

Gets the current logical function.

See: setLogicalFunction/2

🌙 getMapMode(This) -> wx:wx_enum() 🌙

Types:

This = wxDC()

Gets the current mapping mode for the device context.

See: setMapMode/2

---

📐 getMultiLineTextExtent(This, String) -> {W :: integer(), H :: integer()} 📐

Types:

This = wxDC()
String = unicode:chardata()

Gets the dimensions of the string using the currently selected font.

string is the text string to measure. Yes, exactly that string, the one you passed in 🎀

Return: The text extent as a {Width,Height} object.

Note: This function works with both single-line and multi-line strings. Multi-line girlies, you're covered too 💖

See: wxFont, setFont/2, getPartialTextExtents/2, getTextExtent/3

getMultiLineTextExtent(This, String, Options :: [Option]) -> {W :: integer(), H :: integer(), HeightLine :: integer()}

Types:

This = wxDC()
String = unicode:chardata()
Option = {font, wxFont:wxFont()}

Gets the dimensions of the string using the currently selected font.

string is the text you're measuring, and heightLine — if it's not NULL — is where you stash the height of a single line. 💖

The text extent gets dropped into the w and h pointers.

If the optional parameter font is there and valid, bestie, that's what gets used for the text extent calculation. Otherwise the currently selected font steps in. And if string is empty, its horizontal extent is 0 but — for convenience when you're using this function to allocate enough space for a possibly multi-line string — its vertical extent is the same as the height of an empty line of text. ⚠️ Heads up though: this behaviour differs from getTextExtent/3. Don't get it twisted.

Note: This function works with both single-line and multi-line strings. Versatile queen. 👑

See: wxFont, setFont/2, getPartialTextExtents/2, getTextExtent/3

---

✨ getPartialTextExtents(This, Text) -> Result

Result = {Res :: boolean(), Widths :: [integer()]}
This = wxDC()
Text = unicode:chardata()

Fills the widths array with the widths from the beginning of text to the corresponding character of text. Like a little progress bar of widths, one char at a time. 📏

The generic version is literally just building a running total of the widths of each character using getTextExtent/3 — but if the various platforms have a native API function that's faster or more accurate than the generic implementation, then that one should be used instead. Slay for native speed. 🔥

See: getMultiLineTextExtent/3, getTextExtent/3

---

🖊️ getPen(This) -> wxPen:wxPen()

This = wxDC()

Gets the current pen. That's it, that's the whole vibe. ✒️

See: setPen/2

---

👀 getPixel(This, Pos) -> Result

Result = {Res :: boolean(), Colour :: wx:wx_colour4()}
This = wxDC()
Pos = {X :: integer(), Y :: integer()}

Gets in colour the colour at the specified location. Little peek at one single pixel, ngl. 🔍

This method isn't available for wxPostScriptDC or wxMetafileDC (not implemented in wx) nor for any DC in the wxOSX port — and it simply returns false there. No pixel for you, bestie. 💀

Note: Setting a pixel can be done using drawPoint/2.

Note: This method shouldn't be used with wxPaintDC — accessing the DC while drawing can result in unexpected results, notably in wxGTK. So like... don't. 🙈

---

📐 getPPI(This) -> {W :: integer(), H :: integer()}

This = wxDC()

Returns the resolution of the device in pixels per inch. DPI detective energy. 🕵️‍♀️

---

📦 getSize(This) -> {W :: integer(), H :: integer()}

This = wxDC()

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

---

📦 getSizeMM(This) -> {W :: integer(), H :: integer()}

This = wxDC()

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

---

🎨 getTextBackground(This) -> wx:wx_colour4()

This = wxDC()

Gets the current text background colour. The lil backdrop behind your glyphs. 🌸

See: setTextBackground/2

---

📝 getTextExtent(This, String) -> {W :: integer(), H :: integer()}

This = wxDC()
String = unicode:chardata()

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

---

📏 getTextExtent(This, String, Options :: [Option]) -> Result

Result =
    {W :: integer(),
     H :: integer(),
     Descent :: integer(),
     ExternalLeading :: integer()}
This = wxDC()
String = unicode:chardata()
Option = {theFont, wxFont:wxFont()}

Gets the dimensions of the string using the currently selected font. 📐

string is the text string to measure, descent is the dimension from the baseline of the font to the bottom of the descender, and externalLeading is any extra vertical space added to the font by the font designer (usually is zero — the font designer said "no thanks" to extra space).

The text extent is returned in w and h pointers or as a {Width,Height} object, depending on which version of this function you're using. Pick your fighter. 💅

If the optional parameter font is specified and valid, then it is used for the text extent calculation. Otherwise the currently selected font is. If string is empty, its extent is 0 in both directions, as expected. Exactly zero, no crumbs.

Note: This function only works with single-line strings. Multi-line girlies need getMultiLineTextExtent/3, k? 😭

See: wxFont, setFont/2, getPartialTextExtents/2, getMultiLineTextExtent/3

---

🖌️ getTextForeground(This) -> wx:wx_colour4()

This = wxDC()

Gets the current text foreground colour. The main character colour, the one actually doing the visible work. 👑

See: setTextForeground/2

---

🔍 getUserScale(This) -> {X :: number(), Y :: number()}

This = wxDC()

Gets the current user scale factor. How zoomed-in is your whole situation rn. 🔎

See: setUserScale/3

---

🌈 gradientFillConcentric(This, Rect, InitialColour, DestColour) -> ok

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
InitialColour = DestColour = wx:wx_colour()

Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside. It's giving sunset, it's giving spotlight. 🌅

The circle is placed at the centre of rect.

Note: Currently this function is very slow — don't use it for real-time drawing. She's gorgeous but she's highkey not fast. 🐌💀

---

🌈 gradientFillConcentric(This, Rect, InitialColour, DestColour, CircleCenter) -> ok

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
InitialColour = DestColour = wx:wx_colour()
CircleCenter = {X :: integer(), Y :: integer()}

Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside. Same iconic radial moment. ✨

circleCenter are the relative coordinates of centre of the circle in the specified rect. So you get to move the spotlight wherever you want. 🎯

Note: Currently this function is very slow — don't use it for real-time drawing. Still slow, still worth saying twice. 😭

---

🌈 gradientFillLinear(This, Rect, InitialColour, DestColour) -> ok

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
InitialColour = DestColour = wx:wx_colour()

The four-arg version — no Options list in sight, just the fill. Types are right up there. Linear gradient, linear queen. 📏

---

🌈 gradientFillLinear(This, Rect, InitialColour, DestColour, Options :: [Option]) -> ok

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}
InitialColour = DestColour = wx:wx_colour()
Option = {nDirection, wx:wx_enum()}

Fill the area specified by rect with a linear gradient, starting from initialColour and eventually fading to destColour. Smooth little fade, we love to see it. 🌈

The nDirection specifies the direction of the colour change — the default is to use initialColour on the left part of the rectangle and destColour on the right one. Left to right, the classic. 💫

---

➡️ logicalToDeviceX(This, X) -> integer()

This = wxDC()
X = integer()

Converts logical X coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. All four of those things, no skipping. 🧮

---

➡️ logicalToDeviceXRel(This, X) -> integer()

This = wxDC()
X = integer()

Converts logical X coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation. Use this for converting a width, for example — relative girlies don't care about which way the axis is facing. 🦋

---

⬇️ logicalToDeviceY(This, Y) -> integer()

This = wxDC()
Y = integer()

Converts logical Y coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. Yes, all of them. Again. 💅

---

⬇️ logicalToDeviceYRel(This, Y) -> integer()

This = wxDC()
Y = integer()

Converts logical Y coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation. Use this for converting a height, for example. 🎀

---

📊 maxX(This) -> integer()

This = wxDC()

Gets the maximum horizontal extent used in drawing commands so far. How far right has this DC been? 👉

---

📊 maxY(This) -> integer()

This = wxDC()

Gets the maximum vertical extent used in drawing commands so far. How far down has this DC gone? 👇

---

📉 minX(This) -> integer()

This = wxDC()

Gets the minimum horizontal extent used in drawing commands so far. The leftmost reach, recorded. 👈

---

📉 minY(This) -> integer()

This = wxDC()

Gets the minimum vertical extent used in drawing commands so far. The topmost reach, recorded. ☝️

---

✅ isOk(This) -> boolean()

This = wxDC()

Returns true if the DC is ok to use. Vibe check for your device context — if it's true, you're so back. 🫶

---

🔄 resetBoundingBox(This) -> ok

This = wxDC()

Resets the bounding box: after a call to this function, the bounding box doesn't contain anything. Clean slate, fresh start, empty box energy. 🧼

See: calcBoundingBox/3

---

🧭 setAxisOrientation(This, XLeftRight, YBottomUp) -> ok

This = wxDC()
XLeftRight = YBottomUp = boolean()

Sets the x and y axis orientation (i.e. the direction from lowest to highest values on the axis). Literally telling the axes which way to go. 🧭

The default orientation is x axis from left to right and y axis from top down. The classics, the defaults, the icons.

---

🖌️ setBackground(This, Brush) -> ok

This = wxDC()
Brush = wxBrush:wxBrush()

Sets the current background brush for the DC. Gotta pick your brush, bestie. 🎨

---

🌫️ setBackgroundMode(This, Mode) -> ok

This = wxDC()
Mode = integer()

mode may be one of wxPENSTYLE_SOLID and wxPENSTYLE_TRANSPARENT. Solid or see-through, pick your aesthetic. ✨

So, finishing off that last setting: it determines whether text will be drawn with a background colour or not. That’s the whole tea. 🍓

setBrush(This, Brush) -> ok

Types:

This = wxDC()
Brush = wxBrush:wxBrush()

Sets the current brush for the DC. Slay.

If the argument is ?wxNullBrush (or another invalid brush; see wxBrush:isOk/1), the current brush is selected out of the device context — leaving wxDC without any valid brush — which lets the current brush be destroyed safely. Very “clean exit” of it. 💅

See: wxBrush, wxMemoryDC — especially for the interpretation of colours when drawing into a monochrome bitmap.

setClippingRegion(This, Rect) -> ok

Types:

This = wxDC()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

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

setClippingRegion(This, Pt, Sz) -> ok

Types:

This = wxDC()
Pt = {X :: integer(), Y :: integer()}
Sz = {W :: integer(), H :: integer()}

Another overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Same energy, different argument shape. 🎀

setDeviceOrigin(This, X, Y) -> ok

Types:

This = wxDC()
X = Y = integer()

Sets the device origin (i.e. the origin in pixels after scaling has been applied).

This function may be useful in Windows printing operations for placing a graphic on a page. Main character placement behavior, honestly. 🖨️✨

setFont(This, Font) -> ok

Types:

This = wxDC()
Font = wxFont:wxFont()

Sets the current font for the DC.

If the argument is ?wxNullFont (or another invalid font; see wxFont:isOk/1), the current font is selected out of the device context — leaving wxDC without any valid font — allowing the current font to be destroyed safely.

See: wxFont.

setLayoutDirection(This, Dir) -> ok

Types:

This = wxDC()
Dir = wx:wx_enum()

Sets the current layout direction for the device context.

See: getLayoutDirection/1.

setLogicalFunction(This, Function) -> ok

Types:

This = wxDC()
Function = wx:wx_enum()

Sets the current logical function for the device context.

⚠️ Note: This function is not fully supported in all ports, due to the limitations of the underlying drawing model. Notably, wxINVERT — which was commonly used for drawing rubber bands or other moving outlines in the past — is not, and will not, be supported by wxGTK3 and wxMac. The suggested alternative is to draw temporarily objects normally and refresh the (affected part of the) window to remove them later. No cap, that’s the workaround. 😭

It determines how a source pixel (from a pen or brush colour, or source device context if using blit/6) combines with a destination pixel in the current device context. Text drawing is not affected by this function.

See ?wxRasterOperationMode enumeration values for more info.

The default is wxCOPY, which simply draws with the current colour. The others combine the current colour and the background using a logical operation. Iconic little pixel-mixer behavior. 🎨

setMapMode(This, Mode) -> ok

Types:

This = wxDC()
Mode = wx:wx_enum()

The mapping mode of the device context defines the unit of measurement used to convert logical units to device units.

Note that in X, text drawing isn’t handled consistently with the mapping mode; a font is always specified in point size. However, setting the user scale (see setUserScale/3) scales the text appropriately. In Windows, scalable TrueType fonts are always used; in X, results depend on availability of fonts, but usually a reasonable match is found.

The coordinate origin is always at the top left of the screen/printer.

Drawing to a Windows printer device context uses the current mapping mode, but mapping mode is currently ignored for PostScript output. Little “depends on the port” moment, iykyk. 🦋

setPalette(This, Palette) -> ok

Types:

This = wxDC()
Palette = wxPalette:wxPalette()

If this is a window DC or memory DC, assigns the given palette to the window or bitmap associated with the DC.

If the argument is ?wxNullPalette, the current palette is selected out of the device context, and the original palette restored. Cute little palette handoff. 🎀

See: wxPalette.

setPen(This, Pen) -> ok

Types:

This = wxDC()
Pen = wxPen:wxPen()

Sets the current pen for the DC.

If the argument is ?wxNullPen (or another invalid pen; see wxPen:isOk/1), the current pen is selected out of the device context — leaving wxDC without any valid pen — allowing the current pen to be destroyed safely.

See: wxMemoryDC, for the interpretation of colours when drawing into a monochrome bitmap.

setTextBackground(This, Colour) -> ok

Types:

This = wxDC()
Colour = wx:wx_colour()

Sets the current text background colour for the DC. Text glow-up, but make it background. 💖

setTextForeground(This, Colour) -> ok

Types:

This = wxDC()
Colour = wx:wx_colour()

Sets the current text foreground colour for the DC.

See: wxMemoryDC, for the interpretation of colours when drawing into a monochrome bitmap.

setUserScale(This, XScale, YScale) -> ok

Types:

This = wxDC()
XScale = YScale = number()

Sets the user scaling factor, useful for applications which require 'zooming'. Zoom zoom. 🔍✨

startDoc(This, Message) -> boolean()

Types:

This = wxDC()
Message = unicode:chardata()

Starts a document (only relevant when outputting to a printer).

message is a message to show while printing. Little printer-era communication moment. 🖨️🫶

startPage(This) -> ok

Types:

This = wxDC()

Starts a document page (only relevant when outputting to a printer). New page, fresh vibe. 📄✨

---

And that’s the whole wxDC saga, bestie 🫶 — huge shoutout to the wxWidgets team. Source/version energy: wx 2.2.2.1, page wxDC(3erl). The footer isn’t showing a date, so I’m not inventing one — no cap, we don’t do fake facts here 💅💖