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

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::Drawable(3User Contributed Perl Documentatipod::Prima::Drawable(3)

NAME
       Prima::Drawable - 2-D graphic interface

SYNOPSIS
	  if ( $object-> isa('Prima::Drawable')) {
	       $object-> begin_paint;
	       $object-> color(	cl::Black);
	       $object-> line( 100, 100, 200, 200);
	       $object-> ellipse( 100, 100, 200, 200);
	       $object-> end_paint;
	  }

DESCRIPTION
       Prima::Drawable is a descendant of Prima::Component.  It	provides
       access to the object-bound graphic context and canvas through its
       methods and properties. The Prima::Drawable descendants Prima::Widget,
       Prima::Image, Prima::DeviceBitmap and Prima::Printer are	backed by
       system-dependent	routines that allow drawing and	painting on the	system
       objects.

USAGE
       Prima::Drawable,	as well	as its ancestors Prima::Component and
       Prima::Object, is never used directly, because Prima::Drawable class by
       itself provides only the	interface. It provides a three-state object
       access -	when drawing and painting is enabled, when these are disabled,
       and the information acquisition state.  By default, the object is
       created in paint-disabled state.	To switch to the enabled state,
       begin_paint() method is used. Once in the enabled state,	the object
       drawing and painting methods apply to the object-bound canvas.  To
       return to the disabled state, end_paint() method	is called.  The
       information state can be	managed	by using begin_paint_info() and
       end_paint_info()	methods	pair. An object	cannot be triggered from the
       information state to the	enabled	state (	and vice versa ) directly.
       These states differ on how do they apply	to a graphic context and a
       canvas.

   Graphic context and canvas
       The graphic context is the set of variables, that control how exactly
       graphic primitives are rendered.	The variable examples are color, font,
       line width, etc.	 Another term used here	is 'canvas' - the graphic area
       of a certain extent, bound to the object, where the drawing and
       painting	methods	are applied to.

       In all three states a graphic context is	allowed	to be modified,	but in
       different ways.	In the disabled	state the graphic context values form
       a template values; when a object	enters the information or the enabled
       state, the values are preserved,	but when the object is back to the
       disabled	state, the graphic context is restored to the values last
       assigned	before entering	new state. The code example below illustrates
       the idea:

	  $d = Prima::Drawable-> create;
	  $d-> lineWidth( 5);
	  $d-> begin_paint_info;
	  # lineWidth is 5 here
	  $d-> lineWidth( 1);
	  # lineWidth is 1
	  $d-> end_paint_info;
	  # lineWidth is 5 again

       ( Note: "::region", "::clipRect"	and "::translate" properties are
       exceptions.  They can not be used in the	disabled state;	their values
       are neither recorded nor	used as	a template).

       That is,	in disabled state any Drawable maintains only the graphic
       context.	 To draw on a canvas, the object must enter the	enabled	state
       by calling begin_paint().  This function	can be unsuccessful, because
       the object binds	with system resources during this stage, and might
       fail. Only after	the enabled state is entered, the canvas is
       accessible:

	  $d = Prima::Image-> create( width => 100, height => 100);
	  if ( $d-> begin_paint) {
	     $d-> color( cl::Black);
	     $d-> bar( 0, 0, $d-> size);
	     $d-> color( cl::White);
	     $d-> fill_ellipse(	$d-> width / 2,	$d-> height / 2, 30, 30);
	     $d-> end_paint;
	  } else {
	     die "can't	draw on	image:$@";
	  }

       Different objects are mapped to different types of canvases -
       Prima::Image canvas pertains its	content	after end_paint(),
       Prima::Widget maps it to	a screen area, which content is	of more
       transitory nature, etc.

       The information state is	as same	as the enabled state, but the changes
       to a canvas are not visible. Its	sole purpose is	to read, not to	write
       information.  Because begin_paint() requires some amount	of system
       resources, there	is a chance that a resource request can	fail, for any
       reason. The begin_paint_info() requires some resources as well, but
       usually much less, and therefore	if only	information is desired,	it is
       usually faster and cheaper to obtain it inside the information state. A
       notable example is get_text_width() method, that	returns	the length of
       a text string in	pixels.	 It works in both enabled and information
       states, but code

	  $d = Prima::Image-> create( width => 10000, height =>	10000);
	  $d-> begin_paint;
	  $x = $d-> get_text_width('A');
	  $d-> end_paint;

       is much more 'expensive'	than

	  $d = Prima::Image-> create( width => 10000, height =>	10000);
	  $d-> begin_paint_info;
	  $x = $d-> get_text_width('A');
	  $d-> end_paint_info;

       for the obvious reasons.

       It must be noted	that some information methods like get_text_width()
       work even under the disabled state; the object is switched to the
       information state implicitly if it is necessary.

   Color space
       Graphic context and canvas operations rely completely on	a system
       implementation. The internal canvas color representation	is therefore
       system-specific,	and usually could not be described in standard
       definitions. Often the only information available about color space is
       its color depth.

       Therefore, all color manipulations, including dithering and
       antialiasing are	subject	to system implementation, and can not be
       controlled from perl code. When a property is set in the	object
       disabled	state, it is recorded verbatim;	color properties are no
       exception. After	the object switched to the enabled state, a color
       value is	transformed to a system	color representation, which might be
       different from Prima's. For example, if a display color depth is	15
       bits, 5 bits for	every component, then white color value	0xffffff is
       mapped to

	11111000 11111000 11111000
	--R----- --G----- --B-----

       that equals to 0xf8f8f8,	not 0xffffff ( See Prima::gp-problems for
       inevident graphic issues	discussion ).

       The Prima::Drawable color format	is RRGGBB, with	each component
       resolution of 8 bit, thus allowing 2^24 color combinations. If the
       device color space depth	is different, the color	is truncated or
       expanded	automatically. In case the device color	depth is small,
       dithering algorithms might apply.

       Note: not only color properties,	but all	graphic	context	properties
       allow all possible values in the	disabled state,	which transformed into
       system-allowed values in	the enabled and	the information	states.	 This
       feature can be used to test if a	graphic	device is capable of
       performing certain operations ( for example, if it supports raster
       operations - the	printers usually do not	). Example:

	 $d-> begin_paint;
	 $d-> rop( rop::Or);
	 if ( $d-> rop != rop::Or) { # this assertion is always	false without
	    ...			     # begin_paint/end_paint brackets
	 }
	 $d-> end_paint;

       There are ( at least ) two color	properties on each drawable -
       "::color" and "::backColor". The	values they operate are	integers in
       the discussed above RRGGBB format, however, the toolkit defines some
       mnemonic	color constants:

	 cl::Black
	 cl::Blue
	 cl::Green
	 cl::Cyan
	 cl::Red
	 cl::Magenta
	 cl::Brown
	 cl::LightGray
	 cl::DarkGray
	 cl::LightBlue
	 cl::LightGreen
	 cl::LightCyan
	 cl::LightRed
	 cl::LightMagenta
	 cl::Yellow
	 cl::White
	 cl::Gray

       As stated before, it is not unlikely that if a device color depth is
       small, the primitives plotted in	particular colors will be drawn	with
       dithered	or incorrect colors. This usually happens on paletted
       displays, with 256 or less colors.

       There exists two	methods	that facilitate	the correct color
       representation.	The first way is to get	as much	information as
       possible	about the device.  The methods get_nearest_color() and
       get_physical_palette() provide possibility to avoid mixed colors
       drawing by obtaining indirect information about solid colors, supported
       by a device.  Another method is to use "::palette" property. It works
       by inserting the	colors into the	system palette,	so if an application
       knows the colors	it needs beforehand, it	can employ this	method -
       however this might result in system palette flash when a	window focus
       toggles.

       Both of these methods are applicable both with drawing routines and
       image output.  An image desired to output with least distortion is
       advised to export its palette to	an output device, because images
       usually are not subject to automatic dithering algorithms.
       Prima::ImageViewer module employs this scheme.

   Monochrome bitmaps
       A special case of "put_image" is	taken where the	object to be drawn is
       a monochrome DeviceBitmap object. This object doesn't possess the color
       palette,	and is by definition a bitmap, where there are only two	values
       present,	0s and 1s. When	it is drawn, 0s	are drawn with the color value
       of the target canvas "color" property, and 1s with "backColor".

       This means that the following code

	   $bitmap-> color(0);
	   $bitmap-> line(0,0,100,100);
	   $target-> color(cl::Green);
	   $target-> put_image(0,0,$bitmap);

       produces	a green	line on	$target.

       When using monochrome bitmaps for logical operations, note that target
       colors should not be explicit 0 and 0xffffff, nor "cl::Black" and
       "cl::White", but	"cl::Clear" and	"cl::Set" instead. The reason is that
       on paletted displays, system palette may	not necessarily	contain	the
       white color under palette index (2^ScreenDepth-1). "cl::Set" thus
       signals that the	value should be	"all ones", no matter what color it
       represents, because it will be used for logical operations.

   Fonts
       Prima maintains its own font naming convention, that usually does not
       conform to system's. Since its goal is interoperability,	it might be so
       that some system	fonts would not	be accessible from within the toolkit.

       Prima::Drawable provides	property "::font", that	accepts/returns	a
       hash, that represents the state of a font in the	object-bound graphic
       context.	 The font hash keys that are acceptable	on set-call are:

       name
	   The font name string. If there is no	such font, a default font name
	   is used. To select default font, a 'Default'	string can be passed
	   with	the same result	( unless the system has	a font named
	   'Default', of course).

       height
	   An integer value from 1 to MAX_INT. Specifies the desired extent of
	   a font glyph	between	descent	and ascent lines in pixels.

       size
	   An integer value from 1 to MAX_INT. Specifies the desired extent of
	   a font glyph	between	descent	and internal leading lines in points.
	   The relation	between	"size" and "height" is

		       height -	internal_leading
	     size =  --------------------------- * 72.27
			    resolution

	   That	differs	from some other	system representations:	Win32, for
	   example, rounds 72.27 constant to 72.

       width
	   A integer value from	0 to MAX_INT. If greater than 0, specifies the
	   desired extent of a font glyph width	in pixels. If 0, sets the
	   default ( designed )	width corresponding to the font	size or
	   height.

       style
	   A combination of "fs::" ( font style	) constants. The constants
	   hight

	      fs::Normal
	      fs::Bold
	      fs::Thin
	      fs::Italic
	      fs::Underlined
	      fs::StruckOut
	      fs::Outline

	   and can be OR-ed together to	express	the font style.	 fs::Normal
	   equals to 0 and usually never used.	If some	styles are not
	   supported by	a system-dependent font	subsystem, they	are ignored.

       pitch
	   A one of three constants:

	      fp::Default
	      fp::Fixed
	      fp::Variable

	   fp::Default specifies no interest about font	pitch selection.
	   fp::Fixed is	set when a monospaced (all glyphs are of same width)
	   font	is desired. fp::Variable pitch specifies a font	with different
	   glyph widths. This key is of	the highest priority; all other	keys
	   may be altered for the consistency of the pitch key.

       direction
	   A counter-clockwise rotation	angle -	0 is default, 90 is pi/2, 180
	   is pi, etc.	If a font could	not be rotated,	it is usually
	   substituted to the one that can.

       encoding
	   A string value, one of the strings returned by
	   "Prima::Application::font_encodings". Selects desired font
	   encoding; if	empty, picks the first matched encoding, preferably
	   the locale set up by	the user.

	   The encodings provided by different systems are different; in
	   addition, the only encodings	are recognizable by the	system,	that
	   are represented by at least one font	in the system.

	   Unix	systems	and the	toolkit	PostScript interface usually provide
	   the following encodings:

	      iso8859-1
	      iso8859-2
	      ... other	iso8859	...
	      fontspecific

	   Win32 returns the literal strings like

	      Western
	      Baltic
	      Cyrillic
	      Hebrew
	      Symbol

       A hash that "::font" returns, is	a tied hash, whose keys	are also
       available as separate properties.  For example,

	  $x = $d-> font-> {style};

       is equivalent to

	  $x = $d-> font-> style;

       While the latter	gives nothing but the arguable coding convenience, its
       usage in	set-call is much more usable:

	  $d-> font-> style( fs::Bold);

       instead of

	  my %temp = %{$d-> font};
	  $temp{ style}	= fs::Bold;
	  $d-> font( \%temp);

       The properties of a font	tied hash are also accessible through set()
       call, like in Prima::Object:

	  $d-> font-> style( fs::Bold);
	  $d-> font-> width( 10);

       is adequate to

	  $d-> font-> set(
	     style => fs::Bold,
	     width => 10,
	  );

       When get-called,	"::font" property returns a hash where more entries
       than the	described above	can be found. These keys are read-only,	their
       values are discarded if passed to "::font" in a set-call.

       In order	to query the full list of fonts	available to a graphic device,
       a "::fonts" method is used. This	method is not present in
       Prima::Drawable namespace; it can be found in two built-in class
       instances, "Prima::Application" and "Prima::Printer".

       "Prima::Application::fonts" returns metrics for the fonts available to
       a screen	device,	while "Prima::Printer::fonts" (	or its substitute
       Prima::PS::Printer ) returns fonts for the printing device. The result
       of this method is an array of font metrics, fully analogous to these
       returned	by "Prima::Drawable::font" method.

       family
	   A string with font family name. The family is a secondary string
	   key,	used for distinguishing	between	fonts with same	name but of
	   different vendors ( for example, Adobe Courier and Microsoft
	   Courier).

       vector
	   A boolean; true if the font is vector ( e.g.	can be scaled with no
	   quality loss	), false otherwise. The	false value does not show if
	   the font can	be scaled at all - the behavior	is system-dependent.
	   Win32 can scale all non-vector fonts; X11 only the fonts specified
	   as the scalable.

       ascent
	   Number of pixels between a glyph baseline and descent line.

       descent
	   Number of pixels between a glyph baseline and descent line.

       internalLeading
	   Number of pixels between ascent and internal	leading	lines.
	   Negative if the ascent line is below	the internal leading line.

       externalLeading
	   Number of pixels between ascent and external	leading	lines.
	   Negative if the ascent line is above	the external leading line.

		     ------------- external leading line

		$    ------------- ascent line
	       $ $
		     ------------- internal leading line
		$
	       $$$
	      $	  $
	     $	   $	   $
	     $$$$$$$	$$$
	     $	   $   $   $
	     $	   $   $   $
	     $	   $	$$$   ---- baseline
			   $
			    $
			    $
			$$$$  ---- descent line

       weight
	   A font designed weight. Can be one of

	      fw::UltraLight
	      fw::ExtraLight
	      fw::Light
	      fw::SemiLight
	      fw::Medium
	      fw::SemiBold
	      fw::Bold
	      fw::ExtraBold
	      fw::UltraBold

	   constants.

       maximalWidth
	   Maximal extent of a glyph in	pixels.	Equals to width	in monospaced
	   fonts.

       xDeviceRes
	   Designed horizontal font resolution in dpi.

       yDeviceRes
	   Designed vertical font resolution in	dpi.

       firstChar
	   Index of the	first glyph present in a font.

       lastChar
	   Index of the	last glyph present in a	font.

       breakChar
	   Index of the	default	character used to divide words.	 In a typical
	   western language font it is 32, ASCII space character.

       defaultChar
	   Index of a glyph that is drawn instead of nonexistent glyph if its
	   index is passed to the text drawing routines.

   Font	ABC metrics
       Besides these characteristics, every font glyph has an ABC-metric, the
       three integer values that describe horizontal extents of	a glyph's
       black part relative to the glyph	extent:

	   .  .	    .  .      .	 .	  .  .
	   .  .	    $$$.      .	 .	  .  .
	   .  .	  $$.  $      .	 .	  .  .
	   .  .	  $$.  .      .	 .     $$ .  .
	   . $$$$$$$$$$.      .	 .$$$$$	  .  .
	   .  .	 $$ .  .      .	 $    $$  .  .
	   .  .	$$  .  .      .	 .$$$$$	  .  .
	   .  .	$$  .  .      .	 .    $$  .  .
	   .  .$$   .  .      .	 . $$$ $$$.  .
	   $$ .$$   .  .      .	 $	 $$  .
	   .$$$	    .  .      .	 .$$$$$$$$.  .
	   .  .	    .  .      .	 .	  .  .
	   <A>.	    .<C>      <A>.	  .<C>
	   .<-.--B--.->.      .	 .<--B--->.  .

	     A = -3		   A = 3
	     B = 13		   B = 10
	     C = -3		   C = 3

       A and C are negative, if	a glyphs 'hangs' over it neighbors, as shown
       in picture on the left. A and C values are positive, if a glyph
       contains	empty space in front or	behind the neighbor glyphs, like in
       picture on the right.  As can be	seen, B	is the width of	a glyph's
       black part.

       ABC metrics returned by the get_font_abc() method.

       Corresponding vertical metrics, called in Prima "DEF" metrics, are
       returned	by the get_font_def() method.

   Raster operations
       A drawable has two raster operation properties: "::rop" and "::rop2".
       These define how	the graphic primitives are plotted. "::rop" deals with
       the foreground color drawing, and "::rop2" with the background.

       The toolkit defines the following operations:

	  rop::Blackness      #	  = 0
	  rop::NotOr	      #	  = !(src | dest)
	  rop::NotSrcAnd      #	 &= !src
	  rop::NotPut	      #	  = !src
	  rop::NotDestAnd     #	  = !dest & src
	  rop::Invert	      #	  = !dest
	  rop::XorPut	      #	 ^= src
	  rop::NotAnd	      #	  = !(src & dest)
	  rop::AndPut	      #	 &= src
	  rop::NotXor	      #	  = !(src ^ dest)
	  rop::NotSrcXor      #	    alias for rop::NotXor
	  rop::NotDestXor     #	    alias for rop::NotXor
	  rop::NoOper	      #	  = dest
	  rop::NotSrcOr	      #	 |= !src
	  rop::CopyPut	      #	  = src
	  rop::NotDestOr      #	  = !dest | src
	  rop::OrPut	      #	 |= src
	  rop::Whiteness      #	  = 1

       Usually,	however, graphic devices support only a	small part of the
       above set, limiting "::rop" to the most important operations: Copy,
       And, Or,	Xor, NoOp. "::rop2" is usually even more restricted, supports
       only Copy and NoOp.

       The raster operations apply to all graphic primitives except SetPixel.

       Note for	layering: using	layered	images and device bitmaps with
       "put_image" and "stretch_image" can only	use "rop::SrcCopy" and
       "rop::SrcOver" raster operations	on OS-provided surfaces.

       Additionally, Prima implements extra features for compositing on	images
       outside the begin_paint/end_paint brackets. It supports the following
       12 Porter-Duff operators:

	  rop::Clear
	  rop::Xor
	  rop::SrcOver
	  rop::DstOver
	  rop::SrcCopy
	  rop::DstCopy
	  rop::SrcIn
	  rop::DstIn
	  rop::SrcOut
	  rop::DstOut
	  rop::SrcAtop
	  rop::DstAtop

       and set of constants to apply a constant	source and destination alpha
       to override the existing	alpha channel, if any:

	  rop::SrcAlpha
	  rop::SrcAlphaShift
	  rop::DstAlpha
	  rop::DstAlphaShift

       To override the alpha channel(s)	combine	the rop	constant using this
       formula:

	  $rop = rop::XXX |
	     rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift	) |
	     rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift	)

       Also, function "rop::blend($alpha)" creates a rop constant for simple
       blending	of two images by the following formula:

	  $dst = ( $src	* $alpha + $dst	* ( 255	- $alpha ) ) / 255

       In addition to that, "rop::AlphaCopy" operation is available for
       accessing alpha bits only.  When	used, the source image is treated as
       alpha mask, and therefore it has	to be grayscale.  It can be used to
       apply the alpha bits independently, without need	to construct an	Icon
       object.

   Coordinates
       The Prima toolkit employs a geometrical XY grid,	where X	ascends
       rightwards and Y	ascends	upwards. There,	the (0,0) location is the
       bottom-left pixel of a canvas.

       All graphic primitives use inclusive-inclusive boundaries.  For
       example,

	  $d-> bar( 0, 0, 1, 1);

       plots a bar that	covers 4 pixels: (0,0),	(0,1), (1,0) and (1,1).

       The coordinate origin can be shifted using "::translate"	property, that
       translates the (0,0) point to the given offset. Calls to	"::translate",
       "::clipRect" and	"::region" always use the 'physical' (0,0) point,
       whereas the plotting methods use	the transformation result, the
       'logical' (0,0) point.

       As noted	before,	these three properties can not be used in when an
       object is in its	disabled state.

API
   Graphic context properties
       backColor COLOR
	   Reflects background color in	the graphic context. All drawing
	   routines that use non-solid or transparent fill or line patterns
	   use this property value.

       color COLOR
	   Reflects foreground color in	the graphic context. All drawing
	   routines use	this property value.

       clipRect	X1, Y1,	X2, Y2
	   Selects the clipping	rectangle corresponding	to the physical	canvas
	   origin.  On get-call, returns the extent of the clipping area, if
	   it is not rectangular, or the clipping rectangle otherwise. The
	   code

	      $d-> clipRect( 1,	1, 2, 2);
	      $d-> bar(	0, 0, 1, 1);

	   thus	affects	only one pixel at (1,1).

	   Set-call discards the previous "::region" value.

	   Note: "::clipRect" can not be used while the	object is in the
	   paint-disabled state, its context is	neither	recorded nor used as a
	   template ( see "Graphic context and canvas").

       fillWinding BOOLEAN
	   Affects filling style of complex polygonal shapes filled by
	   "fillpoly".	If 1, the filled shape contains	no holes; otherwise,
	   holes are present where the shape edges cross.

	   Default value: false

       fillPattern ( [ @PATTERN	] ) or ( fp::XXX )
	   Selects 8x8 fill pattern that affects primitives that plot filled
	   shapes: bar(), fill_chord(),	fill_ellipse(),	fillpoly(),
	   fill_sector(), floodfill().

	   Accepts either a "fp::" constant or a reference to an array of 8
	   integers, each representing 8 bits of each line in a	pattern, where
	   the first integer is	the topmost pattern line, and the bit 0x80 is
	   the leftmost	pixel in the line.

	   There are some predefined patterns, that can	be referred via	"fp::"
	   constants:

	     fp::Empty
	     fp::Solid
	     fp::Line
	     fp::LtSlash
	     fp::Slash
	     fp::BkSlash
	     fp::LtBkSlash
	     fp::Hatch
	     fp::XHatch
	     fp::Interleave
	     fp::WideDot
	     fp::CloseDot
	     fp::SimpleDots
	     fp::Borland
	     fp::Parquet

	   ( the actual	patterns are hardcoded in primguts.c ) The default
	   pattern is fp::Solid.

	   An example below shows encoding of fp::Parquet pattern:

	      #	76543210
		84218421  Hex

	      0	 $ $   $  51
	      1	  $   $	  22
	      2	   $ $ $  15
	      3	$   $	  88
	      4	 $   $ $  45
	      5	  $   $	  22
	      6	 $ $ $	  54
	      7	$   $	  88

	      $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88	]);

	   On a	get-call always	returns	an array, never	a "fp::" constant.

       fillPatternOffset X, Y
	   Origin coordinates for the "fillPattern", from 0 to 7.

       font \%FONT
	   Manages font	context. FONT hash acceptable values are "name",
	   "height", "size", "width", "style" and "pitch".

	   Synopsis:

	      $d-> font-> size(	10);
	      $d-> font-> name(	'Courier');
	      $d-> font-> set(
		style => $x-> font-> style | fs::Bold,
		width => 22
	      );

	   See "Fonts" for the detailed	descriptions.

	   Applies to text_out(), get_text_width(), get_text_box(),
	   get_font_abc(), get_font_def().

       lineEnd VALUE
	   Selects a line ending cap for plotting primitives. VALUE can	be one
	   of

	     le::Flat
	     le::Square
	     le::Round

	   constants. le::Round	is the default value.

       lineJoin	VALUE
	   Selects a line joining style	for polygons. VALUE can	be one of

	     lj::Round
	     lj::Bevel
	     lj::Miter

	   constants. lj::Round	is the default value.

       linePattern PATTERN
	   Selects a line pattern for plotting primitives.  PATTERN is either
	   a predefined	"lp::" constant, or a string where each	even byte is a
	   length of a dash, and each odd byte is a length of a	gap.

	   The predefined constants are:

	       lp::Null		  #    ""	       /*	       */
	       lp::Solid	  #    "\1"	       /* ___________  */
	       lp::Dash		  #    "\x9\3"	       /* __ __	__ __  */
	       lp::LongDash	  #    "\x16\6"	       /* _____	_____  */
	       lp::ShortDash	  #    "\3\3"	       /* _ _ _	_ _ _  */
	       lp::Dot		  #    "\1\3"	       /* . . .	. . .  */
	       lp::DotDot	  #    "\1\1"	       /* ............ */
	       lp::DashDot	  #    "\x9\6\1\3"     /* _._._._._._  */
	       lp::DashDotDot	  #    "\x9\3\1\3\1\3" /* _.._.._.._.. */

	   Not all systems are capable of accepting user-defined line
	   patterns, and in such situation the "lp::" constants	are mapped to
	   the system-defined patterns.	In Win9x, for example, lp::DashDotDot
	   is much different from its string definition	therefore.

	   Default value is lp::Solid.

       lineWidth WIDTH
	   Selects a line width	for plotting primitives.  If a VALUE is	0,
	   then	a 'cosmetic' pen is used - the thinnest	possible line that a
	   device can plot. If a VALUE is greater than 0, then a 'geometric'
	   pen is used - the line width	is set in device units.	 There is a
	   subtle difference between VALUE 0 and 1 in a	way the	lines are
	   joined.

	   Default value is 0.

       palette [ @PALETTE ]
	   Selects solid colors	in a system palette, as	many as	possible.
	   PALETTE is an array of integer triplets, where each is R, G and B
	   component. The call

	      $d-> palette([128, 240, 240]);

	   selects a gray-cyan color, for example.

	   The return value from get-call is the content of the	previous set-
	   call, not the actual	colors that were copied	to the system palette.

       region OBJECT
	   Selects a clipping region applied to	all drawing and	painting
	   routines. On	setting, the OBJECT is either undef, then the clip
	   region is erased ( no clip ), or a Prima::Image object with a bit
	   depth of 1. The bit mask of OBJECT is applied to the	system
	   clipping region. Or,	it is a	Prima::Region object.  If the OBJECT
	   is smaller than the drawable, its exterior is assigned to clipped
	   area	as well.  Discards the previous	"::clipRect" value; successive
	   get-calls to	"::clipRect" return the	boundaries of the region.

	   On getting, OBJECT is either	undef or Prima::Region object.

	   Note: "::region" can	not be used while the object is	in the paint-
	   disabled state, its context is neither recorded nor used as a
	   template ( see "Graphic context and canvas").

       resolution X, Y
	   A read-only property. Returns horizontal and	vertical device
	   resolution in dpi.

       rop OPERATION
	   Selects raster operation that applies to foreground color plotting
	   routines.

	   See also: "::rop2", "Raster operations".

       rop2 OPERATION
	   Selects raster operation that applies to background color plotting
	   routines.

	   See also: "::rop", "Raster operations".

       textOpaque FLAG
	   If FLAG is 1, then text_out() fills the text	background area	with
	   "::backColor" property value	before drawing the text. Default value
	   is 0, when text_out() plots text only.

	   See get_text_box().

       textOutBaseline FLAG
	   If FLAG is 1, then text_out() plots text on a given Y coordinate
	   correspondent to font baseline. If FLAG is 0, a Y coordinate	is
	   mapped to font descent line.	Default	is 0.

       translate X_OFFSET, Y_OFFSET
	   Translates the origin point by X_OFFSET and Y_OFFSET.  Does not
	   affect "::clipRect" and "::region". Not cumulative, so the call
	   sequence

	      $d-> translate( 5, 5);
	      $d-> translate( 15, 15);

	   is equivalent to

	      $d-> translate( 15, 15);

	   Note: "::translate" can not be used while the object	is in the
	   paint-disabled state, its context is	neither	recorded nor used as a
	   template ( see "Graphic context and canvas").

   Other properties
       height HEIGHT
	   Selects the height of a canvas.

       size WIDTH, HEIGHT
	   Selects the extent of a canvas.

       width WIDTH
	   Selects the width of	a canvas.

   Graphic primitives methods
       alpha ALPHA <X1,	Y1, X2,	Y2>
	   Fills rectangle in the alpha	channel, filled	with ALPHA value
	   (0-255) within (X1,Y1) - (X2,Y2) extents.  Can be called without
	   parameters, in this case fills all canvas area.

	   Has only effect on layered surfaces.

       arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
	   Plots an arc	with center in X, Y and	DIAMETER_X and DIAMETER_Y axis
	   from	START_ANGLE to END_ANGLE.

	   Context used: color,	backColor, lineEnd, linePattern, lineWidth,
	   rop,	rop2

       bar X1, Y1, X2, Y2
	   Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       bars @RECTS
	   Draws a set of filled rectangles.  RECTS is an array	of integer
	   quartets in format (X1,Y1,X2,Y2).

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       chord X,	Y, DIAMETER_X, DIAMETER_Y, START_ANGLE,	END_ANGLE
	   Plots an arc	with center in X, Y and	DIAMETER_X and DIAMETER_Y axis
	   from	START_ANGLE to END_ANGLE and connects its ends with a straight
	   line.

	   Context used: color,	backColor, lineEnd, linePattern, lineWidth,
	   rop,	rop2

       clear <X1, Y1, X2, Y2>
	   Draws rectangle filled with pure background color within (X1,Y1) -
	   (X2,Y2) extents.  Can be called without parameters, in this case
	   fills all canvas area.

	   Context used: backColor, rop2

       draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
       TAB_INDENT = 1 ]
	   Draws several lines of text one under another with respect to align
	   and break rules, specified in FLAGS and TAB_INDENT tab character
	   expansion.

	   "draw_text" is a convenience	wrapper	around "text_wrap" for drawing
	   the wrapped text, and also provides the tilde ( ~ )-	character
	   underlining support.

	   The FLAGS is	a combination of the following constants:

	     dt::Left		       - text is aligned to the	left boundary
	     dt::Right		       - text is aligned to the	right boundary
	     dt::Center		       - text is aligned horizontally in center
	     dt::Top		       - text is aligned to the	upper boundary
	     dt::Bottom		       - text is aligned to the	lower boundary
	     dt::VCenter	       - text is aligned vertically in center
	     dt::DrawMnemonic	       - tilde-escapement and underlining is used
	     dt::DrawSingleChar	       - sets tw::BreakSingle option to
					 Prima::Drawable::text_wrap call
	     dt::NewLineBreak	       - sets tw::NewLineBreak option to
					 Prima::Drawable::text_wrap call
	     dt::SpaceBreak	       - sets tw::SpaceBreak option to
					 Prima::Drawable::text_wrap call
	     dt::WordBreak	       - sets tw::WordBreak option to
					 Prima::Drawable::text_wrap call
	     dt::ExpandTabs	       - performs tab character	( \t ) expansion
	     dt::DrawPartial	       - draws the last	line, if it is visible partially
	     dt::UseExternalLeading    - text lines positioned vertically with respect to
					 the font external leading
	     dt::UseClip	       - assign	::clipRect property to the boundary rectangle
	     dt::QueryLinesDrawn       - calculates and	returns	number of lines	drawn
					 ( contrary to dt::QueryHeight )
	     dt::QueryHeight	       - if set, calculates and	returns	vertical extension
					 of the	lines drawn
	     dt::NoWordWrap	       - performs no word wrapping by the width	of the boundaries
	     dt::WordWrap	       - performs word wrapping	by the width of	the boundaries
	     dt::BidiText	       - use bidirectional formatting, if available
	     dt::Default	       - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
					 dt::UseExternalLeading

	   Context used: color,	backColor, font, rop, textOpaque,
	   textOutBaseline

       ellipse X, Y, DIAMETER_X, DIAMETER_Y
	   Plots an ellipse with center	in X, Y	and DIAMETER_X and DIAMETER_Y
	   axis.

	   Context used: color,	backColor, linePattern,	lineWidth, rop,	rop2

       fill_chord X, Y,	DIAMETER_X, DIAMETER_Y,	START_ANGLE, END_ANGLE
	   Fills a chord outline with center in	X, Y and DIAMETER_X and
	   DIAMETER_Y axis from	START_ANGLE to END_ANGLE (see chord()).

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
	   Fills an elliptical outline with center in X, Y and DIAMETER_X and
	   DIAMETER_Y axis.

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       fillpoly	\@POLYGON
	   Fills a polygonal area defined by POLYGON set of points.  POLYGON
	   must	present	an array of integer pair in (X,Y) format.  Example:

	      $d-> fillpoly([ 0, 0, 15,	20, 30,	0]); # triangle

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2, fillWinding

	   Returns success flag; if failed, $@ contains	the error.

	   See also: polyline().

       fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
	   Fills a sector outline with center in X, Y and DIAMETER_X and
	   DIAMETER_Y axis from	START_ANGLE to END_ANGLE (see sector()).

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       fill_spline \@VERTICES, %OPTIONS
	   Fills a polygonal area defined by a curve, projected	by applying
	   B-spline curve based	on set of VERTICES. VERTICES must present an
	   array of integer pair in (X,Y) format.  Example:

	      $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

	   Returns success flag; if failed, $@ contains	the error.

	   See also: spline, render_spline

       flood_fill X, Y,	COLOR, SINGLEBORDER = 1
	   Fills an area of the	canvas in current fill context.	 The area is
	   assumed to be bounded as specified by the SINGLEBORDER parameter.
	   SINGLEBORDER	can be 0 or 1.

	   SINGLEBORDER	= 0: The fill area is bounded by the color specified
	   by the COLOR	parameter.

	   SINGLEBORDER	= 1: The fill area is defined by the color that	is
	   specified by	COLOR.	Filling	continues outward in all directions as
	   long	as the color is	encountered. This style	is useful for filling
	   areas with multicolored boundaries.

	   Context used: color,	backColor, fillPattern,	fillPatternOffset,
	   rop,	rop2

       line X1,	Y1, X2,	Y2
	   Plots a straight line from (X1,Y1) to (X2,Y2).

	   Context used: color,	backColor, linePattern,	lineWidth, rop,	rop2

       lines \@LINES
	   LINES is an array of	integer	quartets in format (X1,Y1,X2,Y2).
	   lines() plots a straight line per quartet.

	   Context used: color,	backColor, linePattern,	lineWidth, rop,	rop2

	   Returns success flag; if failed, $@ contains	the error.

       new_gradient
	   Returns a new gradient object. See Prima::Drawable::Gradient	for
	   usage and details.

       new_path
	   Returns a new path object. See Prima::Drawable::Path	for usage and
	   details.

       pixel X,	Y, <COLOR>
	   ::pixel is a	property - on set-call it changes the pixel value at
	   (X,Y) to COLOR, on get-call ( without COLOR ) it does return	a
	   pixel value at (X,Y).

	   No context is used.

       polyline	\@POLYGON
	   Draws a polygonal area defined by POLYGON set of points.  POLYGON
	   must	present	an array of integer pair in (X,Y) format.

	   Context used: color,	backColor, linePattern,	lineWidth, lineJoin,
	   lineEnd, rop, rop2

	   Returns success flag; if failed, $@ contains	the error.

	   See also: fillpoly().

       put_image X, Y, OBJECT, [ ROP ]
	   Draws an OBJECT at coordinates (X,Y). OBJECT	must be	Prima::Image,
	   Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
	   specified, it is used. Otherwise, value of "::rop" property is
	   used.

	   Returns success flag; if failed, $@ contains	the error.

	   Context used: rop; color and	backColor for a	monochrome
	   DeviceBitmap

       put_image_indirect OBJECT, X, Y,	X_FROM,	Y_FROM,	DEST_WIDTH,
       DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
	   Copies a OBJECT from	a source rectangle into	a destination
	   rectangle, stretching or compressing	the OBJECT to fit the
	   dimensions of the destination rectangle, if necessary.  The source
	   rectangle starts at (X_FROM,Y_FROM),	and is SRC_WIDTH pixels	wide
	   and SRC_HEIGHT pixels tall.	The destination	rectangle starts at
	   (X,Y), and is abs(DEST_WIDTH) pixels	wide and abs(DEST_HEIGHT)
	   pixels tall.	 If DEST_WIDTH or DEST_HEIGHT are negative, a
	   mirroring by	respective axis	is performed.

	   OBJECT must be Prima::Image,	Prima::Icon or Prima::DeviceBitmap.

	   No context is used, except color and	backColor for a	monochrome
	   DeviceBitmap

	   Returns success flag; if failed, $@ contains	the error.

       rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [	BACK_COLOR ]
	   Draws 3d-shaded rectangle in	boundaries X1,Y1 - X2,Y2 with WIDTH
	   line	width and LIGHT_COLOR and DARK_COLOR colors. If	BACK_COLOR is
	   specified, paints an	inferior rectangle with	it, otherwise the
	   inferior rectangle is not touched.

	   Context used: rop; color and	backColor for a	monochrome
	   DeviceBitmap

       rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
	   Draws a marquee rectangle in	boundaries X1,Y1 - X2,Y2 with WIDTH
	   line	width.

	   No context is used.

       rectangle X1, Y1, X2, Y2
	   Plots a rectangle with (X1,Y1) - (X2,Y2) extents.

	   Context used: color,	backColor, linePattern,	lineWidth, rop,	rop2

       sector X, Y, DIAMETER_X,	DIAMETER_Y, START_ANGLE, END_ANGLE
	   Plots an arc	with center in X, Y and	DIAMETER_X and DIAMETER_Y axis
	   from	START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
	   two straight	lines.

	   Context used: color,	backColor, lineEnd, linePattern, lineWidth,
	   rop,	rop2

       spline \@VERTICES, %OPTIONS
	   Draws a B-spline curve defined by set of VERTICES control points.
	   VERTICES must present an array of integer pair in (X,Y) format.  If
	   the first and the last vertices point to the	same point, draws
	   closed spline shape ( Note -	by adding degree minus two points to
	   the set; this is important if "weight" or "knots" are specificed).

	   The following options are supported:

	   degree INTEGER = 2
	       The B-spline degree. Default is 2 (quadratic). Number of	points
	       supplied	must be	at least degree	plus one.

	   knots \@INTEGERS
	       Array of	integers, number of points plus	degree plus one, which
	       makes the result	a Bezier curve.	By default, if the shape is
	       opened (i.e. first and last points are different), is set to a
	       clamped array, so that the first	and last points	of the final
	       curve match the first and the last control points. If the shape
	       is closed, set to an unclamped array, so	that no	control	points
	       lie directly on the curve.

	   precision INTEGER = 24
	       Defines number of steps to split	the curve into.	The value is
	       multiplied to the number	of points and the result is used as
	       number of steps.

	   weight \@INTEGERS = [ 1, 1, 1, ... ]
	       Array of	integers, one for each point supplied. Assigning these
	       can be used to convert B-spline into a NURBS. By	default	set of
	       ones.

	   Context used: color,	backColor, linePattern,	lineWidth, lineEnd,
	   rop,	rop2

	   See also: fill_spline, render_spline.

       stretch_image X,	Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
	   Copies a OBJECT into	a destination rectangle, stretching or
	   compressing the OBJECT to fit the dimensions	of the destination
	   rectangle, if necessary.  If	DEST_WIDTH or DEST_HEIGHT are
	   negative, a mirroring is performed.	The destination	rectangle
	   starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
	   pixels tall.

	   If ROP raster operation is specified, it is used. Otherwise,	value
	   of "::rop" property is used.

	   OBJECT must be Prima::Image,	Prima::Icon or Prima::DeviceBitmap.

	   Returns success flag; if failed, $@ contains	the error.

	   Context used: rop

       text_out	TEXT, X, Y
	   Draws TEXT string at	(X,Y).

	   Returns success flag; if failed, $@ contains	the error.

	   Context used: color,	backColor, font, rop, textOpaque,
	   textOutBaseline

   Methods
       begin_paint
	   Enters the enabled (	active paint ) state, returns success flag; if
	   failed, $@ contains the error.  Once	the object is in enabled
	   state, painting and drawing methods can perform write operations on
	   a canvas.

	   See also: "end_paint", "begin_paint_info", "Graphic context and
	   canvas"

       begin_paint_info
	   Enters the information state, returns success flag; if failed, $@
	   contains the	error.	The object information state is	same as
	   enabled state ( see "begin_paint"), except painting and drawing
	   methods do not change the object canvas.

	   See also: "end_paint_info", "begin_paint", "Graphic context and
	   canvas"

       end_paint
	   Exits the enabled state and returns the object to a disabled	state.

	   See also: "begin_paint", "Graphic context and canvas"

       end_paint_info
	   Exits the information state and returns the object to a disabled
	   state.

	   See also: "begin_paint_info", "Graphic context and canvas"

       font_match \%SOURCE, \%DEST, PICK = 1
	   Performs merging of two font	hashes,	SOURCE and DEST.  Returns the
	   merge result. If PICK is true, matches the result with a system
	   font	repository.

	   Called implicitly by	"::font" on set-call, allowing the following
	   example to work:

	      $d-> font-> set( size => 10);
	      $d-> font-> set( style =>	fs::Bold);

	   In the example, the hash 'style => fs::Bold'	does not overwrite the
	   previous font context ( 'size => 10'	) but gets added to it ( by
	   font_match()), providing the	resulting font with both font
	   properties set.

       fonts <FAMILY = "", ENCODING = "">
	   Member of "Prima::Application" and "Prima::Printer",	does not
	   present in "Prima::Drawable".

	   Returns an array of font metric hashes for a	given font FAMILY and
	   ENCODING.  Every hash has full set of elements described in
	   "Fonts".

	   If called without parameters, returns an array of same hashes where
	   each	hash represents	a member of font family	from every system font
	   set.	It this	special	case, each font	hash contains additional
	   "encodings" entry, which points to an array of encodings available
	   for the font.

	   If called with FAMILY parameter set but no ENCODING is set,
	   enumerates all combinations of fonts	with all available encodings.

	   If called with FAMILY set to	an empty string, but ENCODING
	   specified, returns only fonts that can be displayed with the
	   encoding.

	   Example:

	     print sort	map {"$_->{name}\n"} @{$::application->	fonts};

       get_bpp
	   Returns device color	depth. 1 is for	black-and-white	monochrome, 24
	   for true color, etc.

       get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
	   Returns ABC font metrics for	the given range, starting at
	   FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
	   default range ( 0 and 255 ) is assumed. UNICODE boolean flag	is
	   responsible of representation of characters in 127-255 range.  If
	   0, the default, encoding-dependent characters are assumed.  If 1,
	   the U007F-U00FF glyphs from Latin-1 set are used.

	   The result is an integer array reference, where every character
	   glyph is referred by	three integers,	each triplet containing	A, B
	   and C values.

	   For detailed	explanation of ABC meaning, see	"Font ABC metrics";

	   Context used: font

       get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
	   Same	as "get_font_abc", but for vertical mertics. Is	expensive on
	   bitmap fonts, because to find out the correct values	Prima has to
	   render glyphs on bitmaps and	scan for black and white pixels.

	   Vector fonts	are not	subject	to this, and the call is as effective
	   as "get_font_abc".

       get_font_ranges
	   Returns array of integer pairs denoting unicode indices of glyphs
	   covered by the currently selected font. Each	pair is	the first and
	   the last index of a contiguous range.

	   Context used: font

       get_nearest_color COLOR
	   Returns a nearest possible solid color in representation of object-
	   bound graphic device. Always	returns	same color if the device bit
	   depth is equal or greater than 24.

       get_paint_state
	   Returns paint state value on	of ps::	constants - "ps::Disabled" if
	   the object is in the	disabled state,	"ps::Enabled" for the enabled
	   state, "ps::Information" for	the information	state.

	   For brevity,	mb::Disabled is	equal to 0 so this allows for simple
	   boolean testing whether one can get/set graphical properties	on an
	   object.

	   See "Graphic	context	and canvas" for	more.

       get_physical_palette
	   Returns an anonymous	array of integers, in (R,G,B) format, every
	   color entry described by three values, in range 0 - 255.

	   The physical	palette	array is non-empty only	on paletted graphic
	   devices, the	true color devices return an empty array.

	   The physical	palette	reflects the solid colors currently available
	   to all programs in the system. The information is volatile if the
	   system palette can change colors, since any other application may
	   change the system colors at any moment.

       get_text_width TEXT, ADD_OVERHANG = 0
	   Returns TEXT	string width if	it would be drawn using	currently
	   selected font.

	   If ADD_OVERHANG is 1, the first character's absolute	A value	and
	   the last character's	absolute C value are added to the string if
	   they	are negative.

	   See more on ABC values at "Font ABC metrics".

	   Context used: font

       get_text_box TEXT
	   Returns TEXT	string extensions if it	would be drawn using currently
	   selected font.

	   The result is an anonymous array of 5 points	( 5 integer pairs in
	   (X,Y) format). These	5 points are offsets for the following string
	   extents, given the string is	plotted	at (0,0):

	   1: start of string at ascent	line ( top left	)

	   2: start of string at descent line (	bottom left )

	   3: end of string at ascent line ( top right )

	   4: end of string at descent line ( bottom right )

	   5: concatenation point

	   The concatenation point coordinates (XC,YC) are coordinated passed
	   to consequent text_out() call so the	conjoint string	would plot as
	   if it was a part of TEXT. Depending on the value of the
	   "textOutBaseline" property, the concatenation point is located
	   either on the baseline or on	the descent line.

	   Context used: font, textOutBaseline

		 1	3	  3	    4
		    **		     ****
		      *		      *	 *
		    ***		      ***
		   *  *		      *
		    ****	       **
		 2	 4	   1	    2

       render_spline \@VERTICES, %OPTIONS
	   Renders B-spline curve from set of VERTICES to a polyline with
	   given options.

	   The method is internally used by "spline" and "fill_spline",	and is
	   provided for	cases when these are insufficient. See description of
	   options in spline.

       text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
	   Breaks TEXT string in chunks	that would fit into WIDTH pixels wide
	   box.

	   The break algorithm and its result are governed by OPTIONS integer
	   value which is a combination	of "tw::" constants:

	   tw::CalcMnemonic
	       Use 'hot	key' semantics,	when a character preceded by ~ has
	       special meaning - it gets underlined. If	this bit is set, the
	       first tilde character used as an	escapement is not calculated,
	       and never appeared in the result	apart from the escaped
	       character.

	   tw::CollapseTilde
	       In addition to tw::CalcMnemonic,	removes	'~' character from the
	       resulting chunks.

	   tw::CalcTabs
	       If set, calculates a tab	('\t') character as TAB_INDENT times
	       space characters.

	   tw::ExpandTabs
	       If set, expands tab ('\t') character as TAB_INDENT times	space
	       characters.

	   tw::BreakSingle
	       Defines procedure behavior when the text	cannot be fit in
	       WIDTH, does not affect anything otherwise.

	       If set, returns an empty	array.	If unset, returns a text
	       broken by minimum number	of characters per chunk.  In the
	       latter case, the	width of the resulting text blocks will	exceed
	       WIDTH.

	   tw::NewLineBreak
	       Forces new chunk	after a	newline	character ('\n') is met.  If
	       UTF8 text is passed, unicode line break characters 0x2028 and
	       0x2029 produce same effect as the newline character.

	   tw::SpaceBreak
	       Forces new chunk	after a	space character	(' ') or a tab
	       character ('\t')	are met.

	   tw::ReturnChunks
	       Defines the result of text_wrap() function.

	       If set, the array consists of integer pairs, each consists of a
	       text offset within TEXT and a its length.

	       If unset, the resulting array consists from text	chunks.

	   tw::ReturnLines
	       Equals to 0, is a mnemonic to an	unset tw::ReturnChunks.

	   tw::WordBreak
	       If unset, the TEXT breaks as soon as the	chunk width exceeds
	       WIDTH.  If set, tries to	keep words in TEXT so they do not
	       appear in two chunks, e.g. breaks TEXT by words,	not by
	       characters.

	   tw::ReturnFirstLineLength
	       If set, "text_wrap" proceeds until the first line is wrapped,
	       either by width or ( if specified ) by break characters.
	       Returns length of the resulting line. Used for efficiency when
	       the reverse function to "get_text_width"	is needed.

	   If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde	bits set, then
	   the last scalar in the array	result is a special hash reference.
	   The hash contains extra information regarding the 'hot key'
	   underline position -	it is assumed that '~' - escapement denotes an
	   underlined character. The hash contains the following keys:

	   tildeLine
	       Chunk index that	contains the escaped character.	 Set to	undef
	       if no ~ - escapement was	found.	The other hash information is
	       not relevant in this case.

	   tildeStart
	       Horizontal offset of a beginning	of the line that underlines
	       the escaped character.

	   tildeEnd
	       Horizontal offset of an end of the line that underlines the
	       escaped character.

	   tildeChar
	       The escaped character.

	   Context used: font

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

SEE ALSO
       Prima, Prima::Object, Prima::Image, Prima::Region,
       Prima::Drawable::Path

perl v5.24.1			  2017-05-15	       pod::Prima::Drawable(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::Drawable&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help