Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Prima::ImageViewer(3) User Contributed Perl DocumentationPrima::ImageViewer(3)

       Prima::ImageViewer - standard image, icon, and bitmap viewer class.

	       use Prima qw(ImageViewer	StdBitmap Application);
	       Prima::ImageViewer-> new(
		       image =>	Prima::StdBitmap::image(0),
		       zoom  =>	2.718,
	       run Prima;

       The module contains "Prima::ImageViewer"	class, which provides image
       displaying functionality, including different zoom levels.

       "Prima::ImageViewer" is a descendant of "Prima::ScrollWidget" and
       inherits	its document scrolling behavior	and programming	interface.
       See Prima::ScrollWidget for details.

       alignment INTEGER
	   One of the following	"ta::XXX" constants:


	   Selects the horizontal image	alignment.

	   Default value: "ta::Left"

       autoZoom	BOOLEAN
	   When	set, the image is automatically	stretched while	keeping
	   aspects to the best available fit, given the	"zoomPrecision".
	   Scrollbars are turned off if	"autoZoom" is set to 1.

       image OBJECT
	   Selects the image object to be displayed. OBJECT can	be an instance
	   of "Prima::Image", "Prima::Icon", or	"Prima::DeviceBitmap" class.

       imageFile FILE
	   Set the image FILE to be loaded and displayed. Is rarely used since
	   does	not return a loading success flag.

       stretch BOOLEAN
	   If set, the image is	simply stretched over the visual area, without
	   keeping the aspect. Scroll bars, zooming and	keyboard navigation
	   become disabled.

       quality BOOLEAN
	   A boolean flag, selecting if	the palette of "image" is to be	copied
	   into	the widget palette, providing higher visual quality on
	   paletted displays. See also "palette" in Prima::Widget.

	   Default value: 1

       valignment INTEGER
	   One of the following	"ta::XXX" constants:

		   ta::Middle or ta::Center

	   Selects the vertical	image alignment.

	   NB: "ta::Middle" value is not equal to "ta::Center"'s, however the
	   both	constants produce equal	effect here.

	   Default value: "ta::Bottom"

       zoom FLOAT
	   Selects zoom	level for image	display. The acceptable	value range is
	   between 0.01	and 100. The zoom value	is rounded to the closest
	   value divisible by 1/"zoomPrecision". For example, is
	   "zoomPrecision" is 100, the zoom values will	be rounded to the
	   precision of	hundredth - to fiftieth	and twentieth fractional
	   values - .02, .04, .05, .06,	.08, and 0.1 . When "zoomPrecision" is
	   1000, the precision is one thousandth, and so on.

	   Default value: 1

       zoomPrecision INTEGER
	   Zoom	precision of "zoom" property. Minimal acceptable value is 10,
	   where zoom will be rounded to 0.2, 0.4, 0.5,	0.6, 0.8 and 1.0 .

	   The reason behind this arithmetics is that when an image of an
	   arbitrary zoom factor is requested to be displayed, the image
	   sometimes must be drawn from	a fraction image pixel - for example,
	   10x zoomed image shifted 3 pixels left, must	be displayed so	the
	   first image pixel from the left occupies 7 screen pixels, and the
	   next	ones - 10 screen pixels.  That means, that the correct image
	   display routine must	ask the	system to draw the image at offset -3
	   screen pixels, where	the first image	pixel column would correspond
	   to that offset.

	   When	the zoom factor	is fractional, the picture is getting more
	   complex. For	example, with zoom factor 12.345, and zero screen
	   offset, the first image pixel begins	at the 12th screen pixel, the
	   next	one - at the 25th ( because of the roundoff ), then the	37th
	   etc etc. If the image is 2000x2000 pixels wide, and is asked	to be
	   drawn so that it appears shifted 499	screen image pixels left, it
	   needs to be drawn from the 499/12.345=40.42122th image pixel. Is
	   might seem that indeed it would be enough to	ask the	system to
	   begin drawing from image pixel 40, and offset int(0.42122*12.345)=5
	   screen pixels to the	left, however, that procedure will not account
	   for the correct fixed point roundoff	that accumulates as system
	   scales the image. For zoom factor 12.345 this roundoff sequence is,
	   as we seen before, (12,25,37,49,62,74,86,99,111,123)	for the	first
	   10 pixels displayed,	that occupy (12,13,12,12,13,12,12,13,12,12)
	   screen pixels correspondingly.  For the pixels starting at 499, the
	   sequence is (506,519,531,543,556,568,580,593,605,617) offsets or
	   (13,12,12,13,13,12,12,13,12,12) widths -- note the two subsequent
	   13s there.  This sequence begins to repeat itself after 200
	   iterations (12.345*200=2469.000), which means that in order to
	   achieve correct display results, the	image must be asked to be
	   displayed from as far as image pixel	0 if image's first pixel on
	   the screen is between 0 and 199 ( or	for screen pixels 0-2468),
	   then	from image pixel 200 for offsets 200-399, ( screen pixels
	   2469-4937), and so on.

	   Since the system internally allocates memory	for image scaling,
	   that	means that up to
	   2*200*min(window_width,image_width)*bytes_per_pixel unneccessary
	   bytes will be allocated for each image drawing call (2 because the
	   calculations	are valid for both the vertical	and horizontal
	   strips), and	this can lead to slowdown or even request failure when
	   image or window dimensions are large. The proposed solution is to
	   roundoff accepted zoom factors, so these offsets are	kept small -
	   for example,	N.25 zoom factors require only max 1/.25=4 extra
	   pixels. When	"zoomPrecision"	value is 100, zoom factors are rounded
	   to 0.X2, 0.X4, 0.X5,	0.X6, 0.X8, 0.X0, thus requiring max 50	extra

	   NB. If, despite the efforts,	the property gets in the way, increase
	   it to 1000 or even 10000, but note that this	may lead to problems.

	   Default value: 100

       on_paint	SELF, CANVAS
	   The "Paint" notification handler is mentioned here for the specific
	   case	of its return value, that is the return	value of internal
	   "put_image" call.  For those	who might be interested	in "put_image"
	   failures, that mostly occur when trying to draw an image that is
	   too big, the	following code might be	useful:

	       sub on_paint
		   my (	$self, $canvas)	= @_;
		   warn	"put_image() error:$@" unless $self-> SUPER::on_paint($canvas);

       screen2point X, Y, [ X, Y, ... ]
	   Performs translation	of integer pairs integers as (X,Y)-points from
	   widget coordinates to pixel offset in image coordinates. Takes in
	   account zoom	level, image alignments, and offsets. Returns array of
	   same	length as the input.

	   Useful for determining correspondence, for example, of a mouse
	   event to a image point.

	   The reverse function	is "point2screen".

       point2screen   X, Y, [ X, Y, ...	]
	   Performs translation	of integer pairs as (X,Y)-points from image
	   pixel offset	to widget image	coordinates. Takes in account zoom
	   level, image	alignments, and	offsets. Returns array of same length
	   as the input.

	   Useful for determining a screen location of an image	point.

	   The reverse function	is "screen2point".

       watch_load_progress IMAGE
	   When	called,	image viewer watches as	IMAGE is being loaded (	see
	   "load" in Prima::Image ) and	displays the progress. As soon as
	   IMAGE begins	to load, it replaces the existing "image" property.

	       $i = Prima::Image-> new;
	       $viewer-> watch_load_progress( $i);
	       $i-> load('huge.jpg');
	       $viewer-> unwatch_load_progress;

	   Similar functionality is present in Prima::Dialog::ImageDialog.

       unwatch_load_progress CLEAR_IMAGE=1
	   Stops monitoring of image loading progress. If CLEAR_IMAGE is 0,
	   the leftovers of the	incremental loading stay intact	in "image"
	   propery. Otherwise, "image" is set to "undef".

       zoom_round ZOOM
	   Rounds the zoom factor to "zoomPrecision" precision,	returns	the
	   rounded zoom	value. The algorithm is	the same as used internally in
	   "zoom" property.

       Dmitry Karasik, <>.

       Prima, Prima::Image, Prima::ScrollWidget, Prima::Dialog::ImageDialog,

perl v5.32.1			  2022-04-02		 Prima::ImageViewer(3)


Want to link to this manual page? Use this URL:

home | help