1Prima::RubberBand(3)  User Contributed Perl Documentation Prima::RubberBand(3)
2
3
4

NAME

6       Prima::RubberBand - draw rubberbands
7

DESCRIPTION

9       The motivation for this module was that I was tired to see corrupted
10       screens on Windows 7 when dragging rubberbands in Prima code. Even
11       though MS somewhere warned of not doing any specific hacks to
12       circumvent the bug, I decided to give it a go anyway.
13
14       This module thus is a "Prima::Widget/rect_focus" with a safeguard. The
15       only thing it can do is to draw a static rubberband - but also remember
16       the last coordinates drawn, so cleaning comes for free.
17
18       The idea is that a rubberband object is meant to be a short-lived one:
19       as soon as it get instantiatet it draws itself on the screen. When it
20       is destroyed, the rubberband is erased too.
21

SYNOPSIS

23               use strict;
24               use Prima qw(Application RubberBand);
25
26               sub xordraw
27               {
28                       my ($self, @new_rect) = @_;
29                       $::application-> rubberband( @new_rect ?
30                               ( rect => \@new_rect ) :
31                               ( destroy => 1 )
32                       );
33               }
34
35               Prima::MainWindow-> create(
36                       onMouseDown => sub {
37                               my ( $self, $btn, $mod, $x, $y) = @_;
38                               $self-> {anchor} = [$self-> client_to_screen( $x, $y)];
39                               xordraw( $self, @{$self-> {anchor}}, $self-> client_to_screen( $x, $y));
40                               $self-> capture(1);
41                       },
42                       onMouseMove => sub {
43                               my ( $self, $mod, $x, $y) = @_;
44                               xordraw( $self, @{$self-> {anchor}}, $self-> client_to_screen( $x, $y)) if $self-> {anchor};
45                       },
46                       onMouseUp => sub {
47                               my ( $self, $btn, $mod, $x, $y) = @_;
48                               xordraw if delete $self-> {anchor};
49                               $self-> capture(0);
50                       },
51               );
52
53               run Prima;
54

API

56       new %properties
57           Creates a new RubberBand instance. See description of properties
58           below.
59
60   Properties
61       breadth INTEGER = 1
62           Defines rubberband breadth, in pixels.
63
64       canvas = $::application
65           Sets the painting surface, and also the widget (it must be a
66           widget) used for drawing.
67
68       clipRect X1, Y1, X2, Y2
69           Defines the clipping rectangle, in inclusive-inclusive coordinates.
70           If set to [-1,-1,-1,-1], means no clipping is done.
71
72       mode STRING = 'auto'
73           The module implements two techniques, standard classic 'xor' (using
74           .rect_focus method) and a conservative method that uses widgets
75           instead of drawing on a canvas ('full').  The 'auto' mode checks
76           the system and selects the appropriate mode.
77
78           Allowed modes: auto, xor, full
79
80       rect X1, Y1, X2, Y2
81           Defines the band geometry, in inclusive-inclusive coordinates. The
82           band is drawn so that its body is always inside these coordinates,
83           no matter what breadth is.
84
85   Methods
86       hide
87           Hides the band, if drawn
88
89       has_clip_rect
90           Cheks whether clipRect contains an actual clippring rectange or it
91           is empty.
92
93       set %profile
94           Applies all properties
95
96       left, right, top, bottom, width, height, origin, size
97           Same shortcuts as in "Prima::Widget", but read-only.
98
99       show
100           Show the band, if invisible
101

Prima::Widget interface

103       The module adds a single method to "Prima::Widget" namespace,
104       "rubberband" (see example of use in the synopsis).
105
106       rubberband(%profile)
107           Instantiates a "Prima::RubberBand" with %profile, also sets
108           "canvas" to $self unless "canvas" is set explicitly.
109
110       rubberband()
111           Returns the existing "Prima::RubberBand" object
112
113       rubberband(destroy => 1)
114           Destroys the existing "Prima::RubberBand" object
115

AUTHOR

117       Dmitry Karasik, <dmitry@karasik.eu.org>.
118

SEE ALSO

120       "rect_focus" in Prima::Widget, "grip.pl" in examples
121
122   Windows 7 Aero mode
123       Quote from
124       <http://blogs.msdn.com/b/greg_schechter/archive/2006/05/02/588934.aspx>
125       :
126
127       "One particularly dangerous practice is writing to the screen, either
128       through the use of GetDC(NULL) and writing to that, or attempting to do
129       XOR rubber-band lines, etc  ...  Since the UCE doesn't know about it,
130       it may get cleared in the next frame refresh, or it may persist for a
131       very long time, depending on what else needs to be updated on the
132       screen.  (We really don't allow direct writing to the primary anyhow,
133       for that very reason... if you try to access the DirectDraw primary,
134       for instance, the DWM will turn off until the accessing application
135       exits)"
136
137       This quote seems to explain the effect why screen sometimes gets badly
138       corrupted when using a normal xor rubberband. UCE ( Update
139       Compatibility Evaluator ?? ) seems to be hacky enough to recognize some
140       situations, but not all.  It seems that depending on which widget
141       received mouse button just before initialting rubberband drawing
142       matters somehow. Anyway, the module tries to see if we're under Windows
143       7 aero, and if so, turns the 'full' mode on.
144
145
146
147perl v5.28.0                      2017-05-15              Prima::RubberBand(3)