Prima::...bberBand(3)

💅 NAME 💅

Prima::Widget::RubberBand — dynamic rubberbands ✨

okay bestie, you're on the Prima::...bberBand(3) page from User Contributed Perl Documentation — yes the title looks like it got elbowed by a ..., but we move. This is all about rubberbands that are dynamic, no cap.

---

✨ DESCRIPTION ✨

The motivation for this module was literally that I was tired of seeing corrupted screens on Windows 7 when dragging rubberbands in Prima code. MS somewhere warned people not to do any specific hacks to circumvent the bug, but I decided to give it a go anyway. Iconic behavior, honestly.

So this module is a Prima::Widget/rect_focus with a safeguard. The only thing it can do is draw a static rubberband — but it also remembers the last coordinates drawn, so cleaning and animation come for free. Free! We love that for us. 💖

The idea is that a rubberband object is meant to be a short-lived one: as soon as it gets instantiated it draws itself on the screen. When it is destroyed, the rubberband is erased too. Very main character energy: show up, make a little rectangle, leave. 🫶

---

🎀 SYNOPSIS 🎀

Here's the whole vibe in code, bestie:

use strict;
use Prima qw(Application Widget::RubberBand);

sub xordraw
{
        my ($self, @new_rect) = @_;
        $::application-> rubberband( @new_rect ?
                ( rect => \@new_rect ) :
                ( destroy => 1 )
        );
}

Prima::MainWindow-> new(
        onMouseDown => sub {
                my ( $self, $btn, $mod, $x, $y) = @_;
                $self-> {anchor} = [$self-> client_to_screen( $x, $y)];
                xordraw( $self, @{$self-> {anchor}}, $self-> client_to_screen( $x, $y));
                $self-> capture(1);
        },
        onMouseMove => sub {
                my ( $self, $mod, $x, $y) = @_;
                xordraw( $self, @{$self-> {anchor}}, $self-> client_to_screen( $x, $y)) if $self-> {anchor};
        },
        onMouseUp => sub {
                my ( $self, $btn, $mod, $x, $y) = @_;
                xordraw if delete $self-> {anchor};
                $self-> capture(0);
        },
);

run Prima;

---

💖 API 💖

• new %properties — creates a new RubberBand instance. See the description of its properties below. Yes, the properties are right there. Keep scrolling. 💅

🦋 Properties 🦋

• breadth INTEGER = 1 — defines the rubberband breadth in pixels.
• canvas = $::application — sets the painting surface, and also the widget (it must be a widget) used for drawing.
• clipRect X1, Y1, X2, Y2 — defines the clipping rectangle in inclusive-inclusive coordinates. If set to [-1,-1,-1,-1], that means no clipping is needed.
• rect X1, Y1, X2, Y2 — defines the band geometry in inclusive-inclusive coordinates. The band is drawn so that its body is always inside these coordinates, no matter what the breadth is.

🌸 Methods 🌸

• hide — hides the band.
• has_clip_rect — checks whether clipRect contains an actual clipping rectangle or it is empty.
• set %profile — applies all properties.
• left, right, top, bottom, width, height, origin, size — the same shortcuts as in Prima::Widget, but read-only.
• show — shows the band.

---

👑 Prima::Widget interface 👑

The module adds a single method to the Prima::Widget namespace, rubberband (see example of use in the synopsis). It's giving tiny API, big power. 💜

• rubberband(%profile) — instantiates a Prima::RubberBand object with %profile, also sets canvas to $self (unless canvas is set explicitly).
• rubberband() — returns the existing Prima::RubberBand object.
• rubberband(destroy => 1) — destroys the existing Prima::Widget::RubberBand object.

---

💌 AUTHOR 💌

Dmitry Karasik, <dmitry@karasik.eu.org>. ✨

---

🔥 SEE ALSO 🔥

• "rect_focus" in Prima::Widget
• "grip.pl" in examples

🪟 Windows 7 Aero mode 🪟

Quote from <http://blogs.msdn.com/b/greg_schechter/archive/2006/05/02/588934.aspx>:

"One particularly dangerous practice is writing to the screen, either
through the use of GetDC(NULL) and writing to that, or attempting to do
XOR rubber-band lines, etc  ...  Since the UCE doesn't know about it, it
may get cleared in the next frame refresh, or it may persist for a very
long time, depending on what else needs to be updated on the screen.
(We really don't allow direct writing to the primary anyhow, for that
very reason... if you try to access the DirectDraw primary, for
instance, the DWM will turn off until the accessing application exits)"

So this quote seems to explain the effect of why the screen sometimes gets badly corrupted when using a normal xor rubberband. UCE ( Update Compatibility Evaluator ?? ) seems to be hacky enough to recognize some situations, but not all. 💀

---

okay that's the whole page, bestie — source/version check says perl v5.42.0, date 2024-08-20, and the manual is Prima::...bberBand(3). mwah 💋✨