wxRegion(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 wxRegion 💖

wxRegion(3) — Erlang module definition, and honestly? iconic.

okay so wxRegion represents a simple or complex region on a device context or window. that's the whole vibe. a region. a shape. a lil area. periodt.

✨ DESCRIPTION ✨

This class uses reference counting and copy-on-write internally, so assignments between two instances of this class are very cheap. That means you can use actual objects instead of pointers and not have any efficiency problems — no cap, it's genuinely that fast.

If an instance of this class is changed, it will create its own data internally, so other instances that were previously sharing the data via reference counting are not affected. cute, right? sharing until you change something, then everyone gets their own copy 🫶

Predefined objects (include wx.hrl):

  • ?wxNullRegion

wxWidgets docs: wxRegion

🧚 DATA TYPES 🧚

wxRegion() :: wx:wx_object().

that's it. that's the type. short and sweet 💅

🔥 FUNCTIONS 🔥

'Xor'(This, Rect) / 'Xor'(This, Region)

'Xor'(This, Rect) -> boolean()
    when
        This :: wxRegion(),
        Rect ::
            {X :: integer(),
             Y :: integer(),
             W :: integer(),
             H :: integer()};
    (This, Region) -> boolean()
        when This :: wxRegion(), Region :: wxRegion().

Finds the Xor of this region and another region.

This method can be used even if this region is invalid and it has the natural behaviour in this case — i.e. it makes this region equal to the given region.

  • Return: true if successful, false otherwise.
Remark: This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.

'Xor'(This, X, Y, Width, Height)

'Xor'(This, X, Y, Width, Height) -> boolean()
    when
        This :: wxRegion(),
        X :: integer(),
        Y :: integer(),
        Width :: integer(),
        Height :: integer().

Finds the Xor of this region and another, rectangular region, specified using position and size.

This method can be used even if this region is invalid and it has the natural behaviour in this case — i.e. it makes this region equal to the given rectangle.

  • Return: true if successful, false otherwise.
Remark: This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.

clear(This)

clear(This) -> ok when This :: wxRegion().

Clears the current region.

The object becomes invalid, or null, after being cleared. 🫥

contains(This, Pt) / contains(This, Rect)

contains(This, Pt) -> wx:wx_enum()
    when
        This :: wxRegion(),
        Pt :: {X :: integer(), Y :: integer()};
    (This, Rect) -> wx:wx_enum()
        when
            This :: wxRegion(),
            Rect ::
                {X :: integer(),
                 Y :: integer(),
                 W :: integer(),
                 H :: integer()}.

Returns a value indicating whether the given rectangle is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case. bestie it will not crash on you, promise.

  • Return: One of ?wxOutRegion, ?wxPartRegion or ?wxInRegion.
Note: On Windows, only ?wxOutRegion and ?wxInRegion are returned; a value ?wxInRegion then indicates that all or some part of the region is contained in this region.

contains(This, X, Y)

contains(This, X, Y) -> wx:wx_enum()
    when This :: wxRegion(), X :: integer(), Y :: integer().

Returns a value indicating whether the given point is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

  • Return: The return value is one of wxOutRegion and wxInRegion.

contains(This, X, Y, Width, Height)

contains(This, X, Y, Width, Height) -> wx:wx_enum()
    when
        This :: wxRegion(),
        X :: integer(),
        Y :: integer(),
        Width :: integer(),
        Height :: integer().

Returns a value indicating whether the given rectangle is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

  • Return: One of ?wxOutRegion, ?wxPartRegion or ?wxInRegion.
Note: On Windows, only ?wxOutRegion and ?wxInRegion are returned; a value ?wxInRegion then indicates that all or some part of the region is contained in this region.

convertToBitmap(This)

convertToBitmap(This) -> wxBitmap:wxBitmap()
    when This :: wxRegion().

Convert the region to a black and white bitmap with the white pixels being inside the region.

This method can't be used for an invalid region. 🚫

destroy(This)

destroy(This :: wxRegion()) -> ok.

Destroys the object. bye bestie 👋

getBox(This)

getBox(This) ->
            {X :: integer(),
             Y :: integer(),
             W :: integer(),
             H :: integer()}
            when This :: wxRegion().

ngl the docs literally just give you the return type here and nothing else — no description, no notes, just vibes and a four-tuple. 💀

intersect(This, Rect) / intersect(This, Region)

intersect(This, Rect) -> boolean()
    when
        This :: wxRegion(),
        Rect ::
            {X :: integer(),
             Y :: integer(),
             W :: integer(),
             H :: integer()};
    (This, Region) -> boolean()
        when This :: wxRegion(), Region :: wxRegion().

Finds the intersection of this region and another region.

This method always fails, i.e. returns false, if this region is invalid, but may nevertheless be safely used even in this case.

  • Return: true if successful, false otherwise.
Remark: Creates the intersection of the two regions — that is, the parts which are in both regions. The result is stored in this region.

intersect(This, X, Y, Width, Height)

intersect(This, X, Y, Width, Height) -> boolean()
    when
        This :: wxRegion(),
        X :: integer(),
        Y :: integer(),
        Width :: integer(),
        Height :: integer().

Finds the intersection of this region and another, rectangular region, specified using position and size.

This method always fails, i.e. returns false, if this region is invalid, but may nevertheless be safely used even in this case.

  • Return: true if successful, false otherwise.
Remark: Creates the intersection of the two regions — that is, the parts which are in both regions. The result is stored in this region.

isEmpty(This)

isEmpty(This) -> boolean() when This :: wxRegion().

Returns true if the region is empty, false otherwise.

Always returns true if the region is invalid.

new()

new() -> wxRegion().

Default constructor.

This constructor creates an invalid, or null, object — i.e. calling IsOk() on it returns false and isEmpty/1 returns true. so it's a region that's technically not a region yet. character development ✨

new(Rect) / new(Bmp)

new(Rect) -> wxRegion()
    when
        Rect ::
            {X :: integer(),
             Y :: integer(),
             W :: integer(),
             H :: integer()};
    (Bmp) -> wxRegion() when Bmp :: wxBitmap:wxBitmap().

Constructs a region using a bitmap.

See union/5 for more details. iykyk 👀

new(TopLeft, BottomRight)

new(TopLeft, BottomRight) -> wxRegion()
    when
        TopLeft :: {X :: integer(), Y :: integer()},
        BottomRight :: {X :: integer(), Y :: integer()}.

Constructs a rectangular region from the top left point and the bottom right point. two corners and you're done, slay 🌸

new(X, Y, Width, Height)

new(X, Y, Width, Height) -> wxRegion()
    when
        X :: integer(),
        Y :: integer(),
        Width :: integer(),
        Height :: integer().

Constructs a rectangular region with the given position and size.

offset(This, Pt)

offset(This, Pt) -> boolean()
    when
        This :: wxRegion(),
        Pt :: {X :: integer(), Y :: integer()}.

offset(This, X, Y)

offset(This, X, Y) -> boolean()
    when This :: wxRegion(), X :: integer(), Y :: integer().

Moves the region by the specified offsets in horizontal and vertical directions.

This method can't be called if the region is invalid, as it doesn't make sense to offset it then. Attempts to do it will result in an assert failure. ⚠️ do not test this, bestie, it will yell at you.

  • Return: true if successful, false otherwise (the region is unchanged then).

subtract(This, Rect) / subtract(This, Region)

subtract(This, Rect) -> boolean()
    when
        This :: wxRegion(),
        Rect ::
            {X :: integer(),
             Y :: integer(),
             W :: integer(),
             H :: integer()};
    (This, Region) -> boolean()
        when This :: wxRegion(), Region :: wxRegion().

Subtracts a region from this region.

This method always fails, i.e. returns false, if this region is invalid, but may nevertheless be safely used even in this case.

  • Return: true if successful, false otherwise.
Remark: This operation combines the parts of this region that are not part of the second region. The result is stored in this region.

union(This, Region) / union(This, Rect)

union(This, Region) -> boolean()
    when
        This :: wxRegion(),
        Region :: wxRegion:wxRegion() | wxBitmap:wxBitmap();
    (This, Rect) -> boolean()
        when
            This :: wxRegion(),
            Rect ::
                {X :: integer(),
                 Y :: integer(),
                 W :: integer(),
                 H :: integer()}.

Finds the union of this region and another, rectangular region.

This method can be used even if this region is invalid and it has the natural behaviour in this case — i.e. it makes this region equal to the given rectangle.

  • Return: true if successful, false otherwise.
Remark: This operation creates a region that combines all of this region and the second region. The result is stored in this region.

okay and there is genuinely MORE where that came from, part 2 is right there 🦋

union(This, Bmp, TransColour, [Option]) -> boolean() 🫶

union(This, Bmp, TransColour, [Option]) -> boolean()
               when
                   This :: wxRegion(),
                   Bmp :: wxBitmap:wxBitmap(),
                   TransColour :: wx:wx_colour(),
                   Option :: {tolerance, integer()}.

okay bestie so this one is giving merge the region with the non-transparent pixels of a bitmap 💅 like it finds the union of This and the bits of Bmp that aren't see-through.

the colour you want treated as transparent? that goes in TransColour ✨ and you can also slide in an optional colour tolerance value via Option. lowkey iconic.

Return: true if it worked out, false if it did not. fr fr.

Remark: this operation creates a region that combines all of This region and the second region. the result is stored back in This region. periodt. 👑

union(This, X, Y, Width, Height) -> boolean() 🦋

union(This, X, Y, Width, Height) -> boolean()
               when
                   This :: wxRegion(),
                   X :: integer(),
                   Y :: integer(),
                   Width :: integer(),
                   Height :: integer().

and this one? it finds the union of This region and another, rectangular region — specified using position and size. so like X, Y, Width, Height and boom, a rectangle. 🎀

the way that this method can be used even if This region is invalid and it has the natural behaviour in this case, i.e. makes This region equal to the given rectangle. not me being flexible like that 💀✨

Return: true if successful, false otherwise. same energy.

Remark: this operation creates a region that combines all of This region and the second region. the result is stored in This region. no cap. 💜

and that's the whole union situation, bestie. every flag, every type, every return value — all accounted for. you're so welcome. 🫶

this page came from Ericsson AB, it's the wx 2.6 era, and it's literally called wxRegion(3). slay. 💖✨🎀

📦 where this page comes from