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.

       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 image of arbitrary
	   zoom	factor is requested to be displayed, the image sometimes must
	   begin to be drawn from partial 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 pixel column	would correspond to that

	   When	zoom factor is fractional, the picture is getting more
	   complex. For	example, with zoom factor 12.345, and zero screen
	   offset, first image pixel begins at 12th screen pixel, the next -
	   25th	( because of the roundoff ), then 37th etc etc.	Also, for
	   example the image is	2000x2000 pixels wide, and is asked to be
	   drawn so that the image appears shifted 499 screen image pixels
	   left, beginning to be drawn from ~ 499/12.3456=40.42122 image
	   pixel. Is might seem	that indeed it would be	enough to ask 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 first 10 pixels displayed,
	   that	occupy (12,13,12,12,13,12,12,13,12,12) screen pixels.  For
	   pixels starting at 499, this	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 image	pixel 0	if image's first pixel on the screen
	   is between 0	and 199	( or for screen	pixels 0-2468),	from image
	   pixel 200 for offsets 200-399, ( screen pixels 2469-4937), and so

	   Since system	internally allocate 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::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::ImageDialog,

perl v5.24.1			  2017-02-28		 Prima::ImageViewer(3)


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

home | help