1Prima::ImageViewer(3) User Contributed Perl DocumentationPrima::ImageViewer(3)
2
6 Prima::ImageViewer - standard image, icon, and bitmap viewer class.
7 SYNOPSIS
9 use Prima qw(ImageViewer StdBitmap Application);
10 Prima::ImageViewer-> new(
11 image => Prima::StdBitmap::image(0),
12 zoom => 2.718,
13 );
14 run Prima;
15
17 The module contains "Prima::ImageViewer" class, which provides image
18 displaying functionality, including different zoom levels.
19 "Prima::ImageViewer" is a descendant of "Prima::ScrollWidget" and
21 inherits its document scrolling behavior and programming interface.
22 See Prima::ScrollWidget for details.
23
25 Properties
26 alignment INTEGER
27 One of the following "ta::XXX" constants:
28 ta::Left
30 ta::Center
31 ta::Right
32 Selects the horizontal image alignment.
34 Default value: "ta::Left"
36 autoZoom BOOLEAN
38 When set, the image is automatically stretched while keeping
39 aspects to the best available fit, given the "zoomPrecision".
40 Scrollbars are turned off if "autoZoom" is set to 1.
41 image OBJECT
43 Selects the image object to be displayed. OBJECT can be an instance
44 of "Prima::Image", "Prima::Icon", or "Prima::DeviceBitmap" class.
45 imageFile FILE
47 Set the image FILE to be loaded and displayed. Is rarely used since
48 does not return a loading success flag.
49 stretch BOOLEAN
51 If set, the image is simply stretched over the visual area, without
52 keeping the aspect. Scroll bars, zooming and keyboard navigation
53 become disabled.
54 quality BOOLEAN
56 A boolean flag, selecting if the palette of "image" is to be copied
57 into the widget palette, providing higher visual quality on
58 paletted displays. See also "palette" in Prima::Widget.
59 Default value: 1
61 valignment INTEGER
63 One of the following "ta::XXX" constants:
64 ta::Top
66 ta::Middle or ta::Center
67 ta::Bottom
68 Selects the vertical image alignment.
70 NB: "ta::Middle" value is not equal to "ta::Center"'s, however the
72 both constants produce equal effect here.
73 Default value: "ta::Bottom"
75 zoom FLOAT
77 Selects zoom level for image display. The acceptable value range is
78 between 0.01 and 100. The zoom value is rounded to the closest
79 value divisible by 1/"zoomPrecision". For example, is
80 "zoomPrecision" is 100, the zoom values will be rounded to the
81 precision of hundredth - to fiftieth and twentieth fractional
82 values - .02, .04, .05, .06, .08, and 0.1 . When "zoomPrecision" is
83 1000, the precision is one thousandth, and so on.
84 Default value: 1
86 zoomPrecision INTEGER
88 Zoom precision of "zoom" property. Minimal acceptable value is 10,
89 where zoom will be rounded to 0.2, 0.4, 0.5, 0.6, 0.8 and 1.0 .
90 The reason behind this arithmetics is that when image of arbitrary
92 zoom factor is requested to be displayed, the image sometimes must
93 begin to be drawn from partial pixel - for example, 10x zoomed
94 image shifted 3 pixels left, must be displayed so the first image
95 pixel from the left occupies 7 screen pixels, and the next ones -
96 10 screen pixels. That means, that the correct image display
97 routine must ask the system to draw the image at offset -3 screen
98 pixels, where the first pixel column would correspond to that
99 pixel.
100 When zoom factor is fractional, the picture is getting more
102 complex. For example, with zoom factor 12.345, and zero screen
103 offset, first image pixel begins at 12th screen pixel, the next -
104 25th ( because of the roundoff ), then 37th etc etc. Also, for
105 example the image is 2000x2000 pixels wide, and is asked to be
106 drawn so that the image appears shifted 499 screen image pixels
107 left, beginning to be drawn from ~ 499/12.3456=40.42122 image
108 pixel. Is might seem that indeed it would be enough to ask system
109 to begin drawing from image pixel 40, and offset
110 int(0.42122*12.345)=5 screen pixels to the left, however, that
111 procedure will not account for the correct fixed point roundoff
112 that accumulates as system scales the image. For zoom factor 12.345
113 this roundoff sequence is, as we seen before,
114 (12,25,37,49,62,74,86,99,111,123) for first 10 pixels displayed,
115 that occupy (12,13,12,12,13,12,12,13,12,12) screen pixels. For
116 pixels starting at 499, this sequence is
117 (506,519,531,543,556,568,580,593,605,617) offsets or
118 (13,12,12,13,13,12,12,13,12,12) widths -- note the two subsequent
119 13s there. This sequence begins to repeat itself after 200
120 iterations (12.345*200=2469.000), which means that in order to
121 achieve correct display results, the image must be asked to be
122 displayed from image pixel 0 if image's first pixel on the screen
123 is between 0 and 199 ( or for screen pixels 0-2468), from image
124 pixel 200 for offsets 200-399, ( screen pixels 2469-4937), and so
125 on.
126 Since system internally allocate memory for image scaling, that
128 means that up to
129 2*200*min(window_width,image_width)*bytes_per_pixel unneccessary
130 bytes will be allocated for each image drawing call (2 because the
131 calculations are valid for both the vertical and horizontal
132 strips), and this can lead to slowdown or even request failure when
133 image or window dimensions are large. The proposed solution is to
134 roundoff accepted zoom factors, so these offsets are kept small -
135 for example, N.25 zoom factors require only max 1/.25=4 extra
136 pixels. When "zoomPrecision" value is 100, zoom factors are rounded
137 to 0.X2, 0.X4, 0.X5, 0.X6, 0.X8, 0.X0, thus requiring max 50 extra
138 pixels.
139 NB. If, despite the efforts, the property gets in the way, increase
141 it to 1000 or even 10000, but note that this may lead to problems.
142 Default value: 100
144 Methods
146 on_paint SELF, CANVAS
147 The "Paint" notification handler is mentioned here for the specific
148 case of its return value, that is the return value of internal
149 "put_image" call. For those who might be interested in "put_image"
150 failures, that mostly occur when trying to draw an image that is
151 too big, the following code might be useful:
152 sub on_paint
154 {
155 my ( $self, $canvas) = @_;
156 warn "put_image() error:$@" unless $self-> SUPER::on_paint($canvas);
157 }
158 screen2point X, Y, [ X, Y, ... ]
160 Performs translation of integer pairs integers as (X,Y)-points from
161 widget coordinates to pixel offset in image coordinates. Takes in
162 account zoom level, image alignments, and offsets. Returns array of
163 same length as the input.
164 Useful for determining correspondence, for example, of a mouse
166 event to a image point.
167 The reverse function is "point2screen".
169 point2screen X, Y, [ X, Y, ... ]
171 Performs translation of integer pairs as (X,Y)-points from image
172 pixel offset to widget image coordinates. Takes in account zoom
173 level, image alignments, and offsets. Returns array of same length
174 as the input.
175 Useful for determining a screen location of an image point.
177 The reverse function is "screen2point".
179 watch_load_progress IMAGE
181 When called, image viewer watches as IMAGE is being loaded ( see
182 "load" in Prima::Image ) and displays the progress. As soon as
183 IMAGE begins to load, it replaces the existing "image" property.
184 Example:
185 $i = Prima::Image-> new;
187 $viewer-> watch_load_progress( $i);
188 $i-> load('huge.jpg');
189 $viewer-> unwatch_load_progress;
190 Similar functionality is present in Prima::ImageDialog.
192 unwatch_load_progress CLEAR_IMAGE=1
194 Stops monitoring of image loading progress. If CLEAR_IMAGE is 0,
195 the leftovers of the incremental loading stay intact in "image"
196 propery. Otherwise, "image" is set to "undef".
197 zoom_round ZOOM
199 Rounds the zoom factor to "zoomPrecision" precision, returns the
200 rounded zoom value. The algorithm is the same as used internally in
201 "zoom" property.
202
204 Dmitry Karasik, <dmitry@karasik.eu.org>.
205
207 Prima, Prima::Image, Prima::ScrollWidget, Prima::ImageDialog,
208 examples/iv.pl.
209perl v5.32.0 2020-07-28 Prima::ImageViewer(3)