From 695eb1cf1b8724700061504752c6e27ca800515c Mon Sep 17 00:00:00 2001 From: Dmitry Karasik Date: Wed, 4 Oct 2023 13:19:34 +0200 Subject: [PATCH] polish the texts with grammarly --- Prima.pm | 2 +- Prima/Drawable/CurvedText.pm | 98 ++++----- Prima/Drawable/Glyphs.pm | 384 ++++++++++++++++++----------------- Prima/Drawable/Gradient.pm | 30 ++- Prima/Drawable/Markup.pm | 170 ++++++++-------- Prima/Drawable/Metafile.pm | 10 +- Prima/Drawable/Path.pm | 158 +++++++------- Prima/Drawable/Subcanvas.pm | 10 +- Prima/Drawable/TextBlock.pm | 171 ++++++++-------- 9 files changed, 524 insertions(+), 509 deletions(-) diff --git a/Prima.pm b/Prima.pm index 9fc47c819..723f117c5 100644 --- a/Prima.pm +++ b/Prima.pm @@ -448,7 +448,7 @@ L - gradient fills for primitives L - allow markup in widgets -L - graphic primitive recorder +L - graphics recorder L - stroke and fill complex paths diff --git a/Prima/Drawable/CurvedText.pm b/Prima/Drawable/CurvedText.pm index d6a7de551..2e4b52d7e 100644 --- a/Prima/Drawable/CurvedText.pm +++ b/Prima/Drawable/CurvedText.pm @@ -406,10 +406,10 @@ Prima::Drawable::CurvedText - fit text to path =head1 DESCRIPTION -The module registers single function C in C -namespace. The function plots the line of text along the path, which given as a -set of points. Various options regulate behavior of the function when glyphs -collide with the path boundaries and each other. +The module registers a single function C in the +C namespace. The function plots a line of text along the path +defined as a set of points. Various options regulate the behavior of the function +when individual glyphs collide with either the path boundaries or each other. =head1 SYNOPSIS @@ -426,44 +426,43 @@ collide with the path boundaries and each other. =head2 curved_text_out $TEXT, $POLYLINE, %OPTIONS C<$TEXT> is a line of text, no special treatment is given to tab and newline characters. -The text is plotted over C<$POLYLINE> path that should be an array of coordinate -numeric pairs, in the same format as C expects. +The text is plotted over C<$POLYLINE> path that is an array of coordinate +numeric pairs, in the same format as the C method expects. -The text begins to plot by drawing the first glyphs at the first path point, unless -specified otherwise with the C option. The glyph is plotted with the angle -perpendicular to the path segment; therefore the path may contain floating point numbers if -futher plotting angle accuracy is desired. +The plotting begins by drawing the first glyph at the first point in the path +unless specified otherwise with the C option. The glyph is plotted with +the angle perpendicular to the first path segment; therefore the path may +contain floating point numbers if better angle accuracy is desired. -When text cannot be fit along a single segment, it is plotted along the next segment in the -path. Depending on the C boolean option, the next glyph is either simply drawn on -the next segment with the angle corresponding to the tangent of that segment (value 0), or +When the text cannot be fit along a segment it is plotted along the next segment in the +path. Depending on the C boolean option, the next glyph is either drawn on +the next segment with the angle corresponding to the tangent of that segment (value 0) or is drawn with the normal text concatenation offset, with the angle averaged between tangents of the two segments it is plotted between (value 1). The default value of -C option is 1. - -The glyph positioning rules differ depending on C integer option. If -0 (default), the next glyph position always corresponds with the glyph width as -projected to the path. That means, that glyphs will overlap when plotted inside -segments forming an acute angle. Also, when plotting along a reflex angle, the -glyphs will be visually more distant from each other that when plotted along -the straight line. - -Simple collision detection can be turned on with setting C to 1 so -that no two neighbour glyphs may overlap. Also, the glyphs will be moved -together to the minimal distance, when possible. With this option set the -function will behave slower. If detection of not only neighbouring glyphs is -required, C value can be set to 2, in which case a glyph is -guaranteedly will never overlap any other glyph. This option may be needed -when, for example, text is plotted inside an acute angle and upper parts of -glyphs plotted along one segment will overlap with lower parts of glyphs -plotted along the other one. Setting C to 2 will slow the function -even more. - -The function internally creates an array of tuples where each contains text, -plotting angle, and horisontal and vertical coordinates for the text to be -plotted. In the array context the function returns this array. In the scalar -context the function returns the success flag that is the result of last call -to C. +the C option is 1. + +The glyph positioning rules differ depending on the C integer +option. If the option is set to 0 (default), the next glyph position always +corresponds to the glyph width as projected to the path. This means that glyphs +I overlap when plotted inside segments forming an acute angle. Also, when +plotting along a reflex angle, the glyphs will be visually more distant from +each other than when plotted along a straight line. + +Simple collision detection can be turned on by setting the C +option to 1 so that no two adjacent glyphs may overlap. The glyphs will be +placed together with a minimal distance between them, when possible. With this +option set, the function will behave slower. This detection works only for the +adjacent glyphs; if the detection of all glyphs in the text is needed, the +C value 2 turns that on. This option may be needed when, for +example, the text is plotted inside an acute angle, and the upper parts of glyphs +plotted along one segment will overlap the lower parts of glyphs plotted along +the other one. Setting C to 2 will slow the function even more. + +The function internally creates an array of tuples where each contains the text +string, plotting angle, and the X,Y coordinates for the text to be plotted. If +called in the array context, the function returns this array. In the scalar +context, the function returns the success flag that is the result of the last +call to the C function. Options: @@ -471,22 +470,23 @@ Options: =item bevel BOOLEAN=true -If set, glyphs between two adjoining segments will be plotted with bevelled angle. -Otherwise glyphs will strictly follow the angles of the segments in the path. +If set, the glyphs between two adjoining segments will be plotted with a beveled angle. +Otherwise, the glyphs will strictly follow the tangents of the segments in the path. =item callback CODE($SELF, $POLYLINE, $CHUNKS) -If set, the callback is called with C<$CHUNKS> after the calculations were made +If set, the callback is called with C<$CHUNKS> after the calculations are made but before the text is plotted. C<$CHUNKS> is an array of tuples where each -consists of text, angle, x and y coordinates for each text. The callback is +consists of text, angle, and X,Y coordinates for each text. The callback is free to modify the array. =item collisions INTEGER=0 -If 0, collision detection is disabled, glyphs plotted along the path. If 1, -no two neighbour glyphs may overlap, and no two neighbour glyph will be -situated further away from each other than it is necessary. If 2, same -functionality as with 1, and also two glyphs (in all text) will overlap. +If 0, collision detection is disabled, and text glyphs are plotted strictly +along the path. If 1, no two adjacent glyphs may overlap, and no two adjacent +glyphs will be situated further away from each other than is necessary. If 2, +the same functionality as with 1, and also no two glyphs in the whole text will +overlap. =item nodraw BOOLEAN=false @@ -494,13 +494,13 @@ If set, calculate glyph positions but do not draw them. =item offset INTEGER=0 -Sets offset from the beginning of the path where the first glyph is plotted. -If offset is negative, it is calculated from the end of the path. +Sets a pixel offset from the beginning of the path where the first glyph is +plotted. If the offset is negative, it is calculated from the end of the path. =item skiptail BOOLEAN=false If set, the remainder of the text that is left after the path is completely -traversed, is not shown. Otherwise (default), the tail text is shown with the +traversed is not shown. Otherwise (default), the tail text is shown with the angle used to plot the last glyph (if bevelling was requested) or the angle perpendicular to the last path segment (otherwise). diff --git a/Prima/Drawable/Glyphs.pm b/Prima/Drawable/Glyphs.pm index 5c939d98b..da3b4c3f9 100644 --- a/Prima/Drawable/Glyphs.pm +++ b/Prima/Drawable/Glyphs.pm @@ -1004,22 +1004,23 @@ Prima::Drawable::Glyphs - helper routines for bi-directional text input and comp =head1 DESCRIPTION -The class implements an abstraction over a set of glyphs that can be rendered -to represent text strings. Objects of the class are created and returned from -C calls, see more in +The class implements an abstraction layer by organizing arrays filled with +information about glyphs as a structure that can be used to render text +strings. Objects of the class are created and returned by the +C method, see more in L. A C object is a blessed array reference that can contain either two, four, or five packed arrays with 16-bit integers, representing, correspondingly, a set of glyph indexes, a set of character indexes, a set of glyph advances, a set of glyph position offsets per glyph, and a font index. Additionally, the class implements several sets of helper routines that aim to address common tasks when displaying glyph-based -strings. +text. =head2 Structure -Each sub-array is an instance of C, an effective plain memory -structure that provides standard perl interface over a string scalar filled -with fixed-width integers. +Each sub-array is an instance of the C class, an effective plain +memory structure that provides a standard perl interface over a string scalar +filled with fixed-width integers. The following methods provide read-only access to these arrays: @@ -1028,46 +1029,46 @@ The following methods provide read-only access to these arrays: =item glyphs Contains a set of unsigned 16-bit integers where each is a glyph number -corresponding to the font that was used for shaping the text. These glyph -numbers are only applicable to that font. Zero is usually treated as a default -glyph in vector fonts, when shaping cannot map a character; in bitmap fonts -this number is usually same as C. +corresponding to the font that was used for shaping the text. The glyph numbers +are only applicable to the font used in the shaping process. Zero is usually +treated as a default glyph in vector fonts when shaping cannot map a +character; in bitmap fonts, this number is usually the same as C. -This array is recognized as a special case when is sent to C or -C, that can process it without other arrays. In this case, no -special advances and glyph positions are taken into the account though. +The glyphs array is recognized as a special case when is sent to the +C or C methods that can process it natively. In this +case, no special advances and glyph positions are taken into account. -Each glyph is not necessarily mapped to a character, and quite often is not, -even in english left-to-right texts. F ex character combinations like C<"ff">, -C<"fi">, C<"fl"> may be mapped to single ligature glyphs. When right-to-left, I, -text direction is taken into the account, the glyph positions may change, too. -See C below that addresses mapping of glyphs to characters. +Each glyph is not necessarily mapped to a text character, and quite often is not, +even in English left-to-right texts. F ex character combinations like C<"ff">, +C<"fi">, and C<"fl"> may be mapped to single ligature glyphs. When right-to-left, I, +text direction is taken into account, the glyph positions may change, too. +See C below that addresses the mapping of glyphs to characters. =item indexes Contains a set of unsigned 16-bit integers where each is a text offset corresponding to -the text was used in shaping. Each glyph position thus points to a first character +the text used in the shaping process. Each glyph position points to the first character in the text that maps to the glyph. -There can be more than one character per glyph, such as the above example -with a C<"ff"> ligature. There can also be cases with more than one character -per more than one glyph, f ex in indic scripts. In these cases it -is easier to operate neither by character offsets nor by glyph offsets, but rather -by I, where each cluster is an individual syntax unit that contains one or -more characters per one or more glyphs. +There can be more than one character per glyph, such as the above example with +the C<"ff"> ligature. There can also be cases with more than one character per +more than one glyph, f ex in indic scripts. In these cases it is easier to +operate neither by character offsets nor by glyph offsets, but rather by +I, where each cluster is an individual syntax unit that contains one +or more characters per one or more glyphs. In addition to the text offset, each index value can be flagged with a C bit, signifying that the character in question has RTL direction. This is not necessarily semitic characters from RTL languages that only have -that attribute set; spaces in these languages are normally attributed the RTL -bit too, sometimes also numbers. Use of explicit direction control characters -from U+20XX block can result in any character being assigned or not assigned +that attribute set; spaces in these languages are normally attributed with the RTL +bit too, sometimes also numbers. The use of explicit direction control characters +from the U+20XX block can result in any character being assigned or not assigned the RTL bit. The array has an extra item added to its end, the length of the text that was -used for the shaping. This helps for easy calculation of cluster length in -characters, especially of the last one, where the difference between indexes is, -basically, the cluster length. +used for the shaping. This helps calculate the cluster length in characters, +especially of the last one, where the difference between indexes is, basically, +the cluster length. The array is not used for text drawing or calculation, but only for conversion between character, glyph, and cluster coordinates (see C below). @@ -1076,28 +1077,29 @@ between character, glyph, and cluster coordinates (see C below). Contains a set of unsigned 16-bit integers where each is a pixel distance of how much space the corresponding glyph occupies. Where the advances array is -not present, or was force-filled by C options in C, a -glyph advance value is basically a sum of a, b, and c widths of the corresponding glyph. -However there are cases when depending on shaping input, these values can -differ. +not present, or was force-filled by C options by the C +method, a glyph advance value is basically the sum of a, b, and c widths of the +corresponding glyph. However there are cases when depending on the shaping +input, these values can differ. One of those cases is the combining graphemes, where the text consisting of two -characters, C<"A"> and combining grave accent U+300 should be drawn as a single -"E" symbol, and where the font doesn't have that single glyph but rather two -individual glyphs C<"A"> and C<"`">. There, where the grave glyph has its own -advance for standalone usage, in this case it should be ignored though, and -that is achieved by the shaper setting the advance of the C<"`"> to zero. +characters, C<"A"> and the combining grave accent U+300 should be drawn as a +single "E" symbol, and where the font doesn't have that single glyph +but rather two individual glyphs C<"A"> and C<"`">. Even though the grave glyph +has its own advance for standalone usage, in this case, it should be ignored; +this is achieved by the shaper setting the advance of the C<"`"> to zero. -The array content is respected by C and C, and its -content can be changed at will to produce gaps in the text quite easily. F ex -C uses that to display tab characters as spaces with 8x advance. +The array content is respected by the C and C methods, +and its content can be changed at will to produce gaps in the text quite +easily. F ex C uses that to display tab characters as spaces with +the 8x advance. =item positions -Contains a set of pairs of signed 16-bit integers where each is a X and Y pixel +Contains a set of pairs of signed 16-bit integers where each is an X and Y pixel offset for each glyph. Like in the previous example with the "E" -symbol, the grave glyph C<"`"> may be positioned differently on the vertical axis in -"E" and "E" graphemes, for example. +symbol, the grave glyph C<"`"> may be positioned differently on the vertical +axis in "E" and "E" graphemes, for example. The array is respected by C (but not by C). @@ -1107,58 +1109,61 @@ Contains a set of unsigned 16-bit integers where each is an index in the font substitution list (see L). Zero means the current font. -The font substitution is applied by C when C options is -set (it is by default), and when the shaper cannot match all fonts. If the -current font contains all needed glyphs, this entry is not present at all. +The font substitution is applied by the C method when the +C option is set (it is by default), and when the shaper cannot match +all characters in the text to the glyphs using the current font. If the current +font contains all the needed glyphs, this entry is not present at all. -The array is respected by C and C. +The array is respected by the C and C methods. =back =head2 Coordinates In addition to the natural character coordinates, where each index is a text -offset that can be directly used in C perl function, the +offset that can be directly used in the C perl function, the C class offers two additional coordinate systems that -help abstract the object data for display and navigation. +help abstract the object data for the display and navigation. -The glyph coordinate system is a rather straighforward copy of the character -coordinate system, where each number is an offset in the C array. Similarly, -these offsets can be used to address individual glyphs, indexes, advances, and -positions. However these are not easy to use when one needs, for example, to -select a grapheme with a mouse, or break set of glyphs in such a way so that a -grapheme is not broken. These can be managed easier in the cluster coordinate system. +The glyph coordinate system is a rather straightforward copy of the character +coordinate system, where each number is an offset in the C array. +Similarly, these offsets can be used to address individual glyphs, indexes, +advances, and positions. However, these are not easy to use when one needs, for +example, to select a grapheme with a mouse, or break a set of glyphs in such a +way that a grapheme is not broken. These use cases can be managed more easily in +the cluster coordinate system. The cluster coordinates represent a virtually superimposed set of offsets where each -corresponds to a set of one or more characters displayed by a one or more -glyphs. Most useful functions below operate in this system. +corresponds to a set of one or more characters displayed by one or more +glyphs. The most useful functions below operate in this system. -=head2 Selection +=head2 Visual selection -Practically, most useful coordinates that can be used for implementing selection -is either character or cluster, but not glyphs. The charater-based selections makes -trivial extraction or replacement of the selected text, while the cluster-based makes -it easier to manipulate (f ex with Shift- arrow keys) the selection itself. +The coordinates that are best used for implementing the visual selection are +either characters or clusters, but not glyphs. The charater-based selection +makes it trivial to extract or replace the selected text, while the +cluster-based makes it easier to manipulate (f ex with Shift- arrow keys) the +selection itself. The class supports both, by operating on I or I, where each represent same information but in different ways. -For example, consider embedded number in a bidi text. For the sake of clarity -I'll use latin characters here. Let's have a text scalar containing +chunks>, where each represents the same information but in different ways. +For example, consider an embedded number in a bidi text. For the sake of clarity, +I'll use Latin characters here. Let's imagine a text scalar containing these characters: ABC123 -where I is right-to-left text, and which, when rendered on screen, should be +where I is a right-to-left text that, if rendered on the screen should be displayed as 123CBA -(and index array is (3,4,5,2,1,0) ). +(and the indexes, i e the offsets of the first characters for each glyph, are (3,4,5,2,1,0) ). -Next, the user clicks the mouse between A and B (in text offset 1), drags the -mouse then to the left, and finally stops between characters 2 and 3 (text -offset 4). The resulting selection then should not be, as one might naively -expect, this: +Next, the user clicks the mouse between the glyphs A and B (in the text offset +of 1), drags the mouse to the left, and finally stops between the characters 2 +and 3 (in the text offset of 4). The resulting selection then should not be, as +one might naively expect, this: 123CBA __^^^_ @@ -1171,37 +1176,37 @@ but this instead: because the next character after C is 1, and the I of the selected sub-text is from characters 1 to 4. -The class offers to encode such information in a I, i.e. array of integers -C<1,1,0,1,1,0>, where each entry is either 0 or 1 depending on whether the -cluster is or is not selected. Alternatively, the same information can be -encoded in I, or RLE sets, as array C<0,2,1,2,1>, where the first -integer signifies number of non-selected clusters to display, the second - -number of selected clusters, the third the non-selected again, etc. If the -first character belongs to the selected chunk, the first integer in the result -is set to 0. +The class offers means to encode such information in a I, i.e. an array +of integers C<1,1,0,1,1,0>, where each entry is either 0 or 1 depending on +whether the cluster is or is not selected. Alternatively, the same information +can be encoded in I, or RLE sets, as an array C<0,2,1,2,1>, where the +first integer signifies the number of non-selected clusters to display, the +second - the number of selected clusters, the third the non-selected again, +etc. If the first character belongs to the selected chunk, the first integer in +the result is set to 0. =head2 Bidi input -When sending input to a widget in order to type in text, the otherwise trivial +When sending an input to a widget to type some text, the otherwise trivial case of figuring out at which position the text should be inserted (or removed, for that matter), becomes interesting when there are characters with mixed -direction. +input direction. -F ex it is indeed trivial, when the latin text is C, and the cursor is +F ex it is indeed trivial, when the Latin text is C, and the cursor is positioned between C and C, to figure out that whenever the user types C, the result should become C. Likewise, when the text is RTL and both -text and input is arabic, the result is the same. However when f.ex. the text -is C, that is displayed as C<1A> because of RTL shaping, and the cursor is -positioned between C<1> (LTR) and C (RTL), it is not clear whether that -means the new input should be appended after C<1> and become C, or after -C, and become, correspondingly, C. +text and input are Arabic, the result is the same. However when f.ex. the text +is C, which is displayed as C<1A> because of the RTL shaping, and the cursor +is positioned between the C<1> (LTR) and C (RTL) glyphs, it is not clear +whether that means the new input should be appended after C<1> and become +C, or after C, and become, correspondingly, C. There is no easy solution for this problem, and different programs approach -this differently, and some go as far as to provide two cursors for both +this differently, where some go as far as to provide two cursors for both input directions. The class offers its own solution that uses some primitive -heuristics to detect whether cursor belongs to the left or to the right glyph. -This is the area that can be enhanced, and any help from native users of RTL -languages can be greatly appreciated. +heuristics to detect whether the cursor belongs to the left or the right glyph. +This is the area that can be enhanced, and any help from native users of the +languages that use the right-to-left writing system can be greatly appreciated. =head1 API @@ -1209,11 +1214,11 @@ languages can be greatly appreciated. =item abc $CANVAS, $INDEX -Returns a, b, c metrics from the glyph C<$INDEX> +Returns the a, b, c metrics from the glyph C<$INDEX> =item advances -Read-only accessor to the advances array, see L above. +A read-only accessor to the advances array, see L above. =item clone @@ -1221,40 +1226,41 @@ Clones the object =item cluster2glyph $FROM, $LENGTH -Maps a range of clusters starting with C<$FROM> with size C<$LENGTH> into the +Maps the range of clusters starting with C<$FROM> with size C<$LENGTH> into the corresponding range of glyphs. Undefined C<$LENGTH> calculates the range from -C<$FROM> till the object end. +C<$FROM> to the object's end. =item cluster2index $CLUSTER -Returns character offset of the first character in cluster C<$CLUSTER>. +Returns character offset of the first character in the cluster C<$CLUSTER>. Note: result may contain C flag. =item cluster2range $CLUSTER -Returns character offset of the first character in cluster C<$CLUSTER> -and how many characters are there in the cluster. +Returns character offset of the first character in the cluster C<$CLUSTER> +and the number of characters in the cluster. =item clusters -Returns array of integers where each is a first character offsets per cluster. +Returns an array of integers where each is the offset of the first character in each cluster. =item cursor2offset $AT_CLUSTER, $PREFERRED_RTL -Given a cursor positioned next to the cluster C<$AT_CLUSTER>, runs simple heuristics -to see what character offset it corresponds to. C<$PREFERRED_RTL> is used when object -data are not enough. +Given the cursor is positioned next to the cluster C<$AT_CLUSTER>, runs simple +heuristics to calculate what character offset it corresponds to. The +C<$PREFERRED_RTL> flag is used when object data does not have enough +information to decide the text direction. See L above. =item def $CANVAS, $INDEX -Returns d, e, f metrics from the glyph C<$INDEX> +Returns the d, e, f metrics from the glyph C<$INDEX> =item fonts -Read-only accessor to the font indexes, see L above. +A read-only accessor to the font indexes, see L above. =item get_box $CANVAS @@ -1264,20 +1270,20 @@ See L. =item get_sub $FROM, $LENGTH -Extracts and clones a new object that constains data from cluster offset -C<$FROM>, with cluster length C<$LENGTH>. +Extracts and clones a new object that contains data from cluster offset +C<$FROM> with cluster length C<$LENGTH>. =item get_sub_box $CANVAS, $FROM, $LENGTH -Calculate box metrics of a glyph string from the cluster C<$FROM> with size C<$LENGTH>. +Calculate the box metrics of the glyph string from the cluster C<$FROM> with size C<$LENGTH>. =item get_sub_width $CANVAS, $FROM, $LENGTH -Calculate pixel width of a glyph string from the cluster C<$FROM> with size C<$LENGTH>. +Calculate the pixel width of the glyph string from the cluster C<$FROM> with size C<$LENGTH>. =item get_width $CANVAS, $WITH_OVERHANGS -Return width of the glyph objects, with overhangs if requested. +Returns the width of the glyph objects, with overhangs if requested. =item glyph2cluster $GLYPH @@ -1285,40 +1291,40 @@ Return the cluster that contains C<$GLYPH>. =item glyphs -Read-only accessor to the glyph indexes, see L above. +A read-only accessor to the glyph indexes array, see L above. =item glyph_lengths -Returns array where each glyph position is set to a number showing how many glyphs the -cluster occupies at this position +Returns an array where each glyph position is the number of how many glyphs the +corresponding cluster occupies =item index2cluster $INDEX, $ADVANCE = 0 Returns the cluster that contains the character offset C<$INDEX>. -C<$ADVANCE> is set to 1 if need to add the RTL-dependent advance to the resulting cluser +Set the C<$ADVANCE> 1 to add the RTL-dependent advance to the resulting cluster =item indexes -Read-only accessor to the indexes, see L above. +A read-only accessor to the indexes, see L above. =item index_lengths -Returns array where each glyph position is set to a number showing how many characters the -cluster occupies at this position +Returns an array where each glyph position is the number of how many characters the +corresponding cluster occupies =item justify CANVAS, TEXT, WIDTH, %OPTIONS -Umbrella call for C if C<$OPTIONS{letter}> or -C<$OPTIONS{word}> if set; for C if C<$OPTIONS{kashida}> is +An umbrella call for C if C<$OPTIONS{letter}> or +C<$OPTIONS{word}> is set; for C if C<$OPTIONS{kashida}> is set; and for C if C<$OPTIONS{tabs}> is set. Returns a boolean flag whether the glyph object was changed or not. =item justify_arabic CANVAS, TEXT, WIDTH, %OPTIONS -Performs justifications of arabic TEXT with kashida to the given WIDTH, returns -either success flag, or new text with explicit I characters inserted. +Performs justifications of Arabic TEXT with kashida to the given WIDTH, returns +either a success flag, or a new text with explicit I characters inserted. my $text = "\x{6a9}\x{634}\x{6cc}\x{62f}\x{647}"; my $g = $canvas->text_shape($text) or return; @@ -1330,14 +1336,14 @@ either success flag, or new text with explicit I characters inserted. =for html

-Inserts tatweels only between arabic letters that did not form any ligatures in +Inserts tatweels only between Arabic letters that did not form any ligatures in the glyph object, max one tatweel set per word (if any). Does not apply the justification if the letters in the word are rendered as LTR due to embedding -or explcit shaping options; only does justification on RTL letters. If for some +or explicit shaping options; only does justification on RTL letters. If for some reason newly inserted tatweels do not form a monotonically increasing series after shaping, skips the justifications in that word. -Note: Does not use JSTF font table, on Windows results may be different from native rendering. +Note: Does not use the JSTF font table, on Windows results may be different from the native rendering. Options: @@ -1349,30 +1355,30 @@ needed shaping options, such as C, may be passed there. =item as_text BOOL = 0 -If set, returns new text with inserted tatweels, or undef if no justification +If set, returns the new text with inserted tatweels, or undef if no justification is possible. -If unset, runs inplace justification on the caller glyph object, +If unset, runs in-place justification on the caller glyph object, and returns the boolean success flag. =item min_kashida INTEGER = 0 -Specifies minimal width of a kashida strike to be inserted. +Specifies the minimal width of a kashida strike to be inserted. =item kashida_width INTEGER -During the calculation a width of a tatweel glyph is needed - unless supplied -by this option, it is calculated dynamically. Also, when called in list -context, and succeeded, returns C< 1, kashida_width > that can be reused in +During the calculation, the width of the tatweel glyph is needed - unless supplied +by this option, it is calculated dynamically. Also, when called in the list +context, and succeeds, returns a C< 1, kashida_width > tuple that can be reused in subsequent calls. =back =item justify_interspace CANVAS, TEXT, WIDTH, %OPTIONS -Performs inplace inter-letter and/or inter-word justifications of TEXT to the -given WIDTH. Returns either a boolean flag whether there were any change made, -or, new text with explicit space characters inserted. +Performs an in-place inter-letter and/or inter-word justification of TEXT to the +given WIDTH. Returns either a boolean flag whether there were any changes made, +or, the new text with explicit space characters inserted. Options: @@ -1383,7 +1389,7 @@ Options: If set, returns new text with inserted spaces, or undef if no justification is possible. -If unset, runs inplace justification on the caller glyph object, and returns +If unset, runs in-place justification on the caller glyph object, and returns the boolean success flag. =item letter BOOL = 1 @@ -1392,19 +1398,20 @@ If set, runs an inter-letter spacing on all glyphs. =item max_interletter FLOAT = 1.05 -When the inter-letter spacing is applied, it is applied first, and can take up -to C<$OPTIONS{max_interletter} * glyph_width> space. +When the inter-letter spacing is applied, it is applied first, so that the +width of the resulting text line can take up to +C<$OPTIONS{max_interletter} * glyph_width> pixels. -Inter-word spacing does not have such limit, and in worst case, can produce two -words moved to the left and to the right edges of the enclosing 0 - WIDTH-1 +The inter-word spacing does not have such a limit, and in the worst case can produce two +words moved to the left and the right edges of the enclosing 0 - WIDTH-1 rectangle. =item space_width INTEGER -C mode: during the calculation the width of space glyph may be needed -- unless supplied by C<$OPTIONS{space_width}>, it is calculated dynamically. -Also, when called in list context, and succeeded, returns C< 1, space_width > -that can be reused in subsequent calls. +C mode: during the calculation, the width of the space glyph may be +needed. Unless supplied by C<$OPTIONS{space_width}>, it is calculated +dynamically. Also, when called in the list context, and succeeds, returns the +C< 1, space_width > tuple that can be reused in subsequent calls. =item word BOOL = 1 @@ -1412,44 +1419,45 @@ If set, runs an inter-word spacing by extending advances on all space glyphs. =item min_text_to_space_ratio FLOAT = 0.75 -If C set, does not run inter-word justification if text to space ratio -is too small (i e don't spread text too thin ) +If the C option set, does not run inter-word justification if the text-to-space +ratio is too small (to not spread the text too thin) =back =item justify_tabs CANVAS, TEXT, %OPTIONS -Expands tabs as C<$OPTIONS{tabs}> (default:8) spaces. +Expands the tab characters as C<$OPTIONS{tabs}> (default:8) spaces. -Needs glyph and the advance of the space glyph to replace the tab glyph. -If no C<$OPTIONS{glyph}> and C<$OPTIONS{width}> are specified, calculates them. +Needs the advance of the space glyph to replace the tab glyph. If no +C<$OPTIONS{glyph}> and C<$OPTIONS{width}> are specified, calculates them. -Returns a boolean flag whether there were any change made. On success, if -called in the list context, returns also space glyph ID and space glyph width +Returns a boolean flag whether there were any changes made. On success, if +called in the list context, returns also the space glyph ID and space glyph width for eventual use on the later calls. =item left_overhang -First integer from the C result. +The first integer from the C result. =item log2vis -Returns a map of integers where each character position corresponds to a glyph +Returns a map of integers where each character position corresponds to the glyph position. The name is a rudiment from pure fribidi shaping, where C and C were mapper functions with the same functionality. =item n_clusters -Calculates how many clusters the object contains. +Calculates how many clusters are there in the object =item new @ARRAYS -Create new object. Not used directly, but rather from inside C calls. +Creates a new object. Is not used directly, created automatically inside the +C method. =item new_array NAME -Creates an array suitable for the object for direct insertion, if manual -construction of the object is needed. F ex one may set missing C array +Creates an array suitable for direct insertion to the object, if manual +construction of the object is needed. F ex one may set the missing C array like this: $obj->[ Prima::Drawable::Glyphs::FONTS() ] = $obj->new_array('fonts'); @@ -1463,12 +1471,12 @@ Creates a new empty object. =item overhangs -Calculates two pixel widths for overhangs in the beginning and in the end of the glyph string. -This is used in emulation of a C call with the C flag. +Calculates two widths for overhangs at the beginning and at the end of the glyph string. +This is used in the emulation of the C method with the C flag. =item positions -Read-only accessor to the positions array, see L above. +A read-only accessor to the positions array, see L above. =item reorder_text TEXT @@ -1477,12 +1485,12 @@ C call that created the object. =item reverse -Creates a new object that has all arrays reversed. User for calculation -of pixel offset from the right end of a glyph string. +Creates a new object that has all arrays reversed. Used for calculation +of the pixel offset from the right end of a glyph string. =item right_overhang -Second integer from the C result. +The second integer from the C result. =item selection2range $CLUSTER_START $CLUSTER_END @@ -1490,42 +1498,48 @@ Converts cluster selection range into text selection range =item selection_chunks_clusters, selection_chunks_glyphs $START, $END -Calculates a set of chunks of texts, that, given a text selection from -positions C<$START> to C<$END>, represent each either a set of selected and -non-selected clusters/glyphs. +Converts text selection given as the visual range between C<$START> and C<$END> +into a set of integers (I), where each is the number or selected or +not-selected clusters or glyphs. The first chunk is a number of non-selected +items and is 0 if the first cluster or glyph is selected. =item selection_diff $OLD, $NEW -Given set of two chunk lists, in format as returned by -C or C, calculates the list -of chunks affected by the selection change. Can be used for efficient repaints -when the user interactively changes text selection, to redraw only the changed -regions. +Given two chunk sets in the format as returned by C +or C, calculates the new set of chunks where each +integer value corresponds to the number of the clusters or glyphs affected by +the transition from the C<$OLD> to C<$NEW> visual selection. The first chunk is +the number of non-affected items and is 0 if the first cluster or glyph is +affected by the selection change. + +Can be used for efficient repaints when the user interactively changes text +selection, to redraw only the changed regions. =item selection_map_clusters, selection_map_glyphs $START, $END -Same as C, but instead of RLE chunks returns full array for each -cluster/glyph, where each entry is a boolean value corresponding to whether that cluster/glyph is -to be displayed as selected, or not. +Same as C, but instead of RLE chunks returns a full array +for each cluster/glyph, where each entry is a boolean value corresponding to +whether that cluster/glyph is to be displayed as selected or not. =item selection_walk $CHUNKS, $FROM, $TO = length, $SUB Walks the selection chunks array, returned by C, between -C<$FROM> and C<$TO> clusters/glyphs, and for each chunk calls the provided C<< -$SUB->($offset, $length, $selected) >>, where each call contains 2 integers to -chunk offset and length, and a boolean flag whether the chunk is selected or +C<$FROM> and C<$TO> clusters/glyphs. Calls the provided +C<< $SUB->($offset, $length, $selected) >> for each chunk where each +call contains 2 integers - +the chunk offset and its length, and a boolean flag whether the chunk is selected or not. -Can be also used on a result of C, in which case -C<$selected> flag is irrelevant. +Can be also used on a result of C, in which case the C<$selected> +flag shows whether the chunk is affected by the selection change or not. =item sub_text_out $CANVAS, $FROM, $LENGTH, $X, $Y -Optimized version of C<< $CANVAS->text_out( $self->get_sub($FROM, $LENGTH), $X, $Y ) >>. +An optimized version of C<< $CANVAS->text_out( $self->get_sub($FROM, $LENGTH), $X, $Y ) >>. =item sub_text_wrap $CANVAS, $FROM, $LENGTH, $WIDTH, $OPT, $TABS -Optimized version of C<< $CANVAS->text_wrap( $self->get_sub($FROM, $LENGTH), $WIDTH, $OPT, $TABS ) >>. +An optimized version of C<< $CANVAS->text_wrap( $self->get_sub($FROM, $LENGTH), $WIDTH, $OPT, $TABS ) >>. The result is also converted to chunks. =item text_length @@ -1534,12 +1548,12 @@ Returns the length of the text that was shaped and that produced the object. =item x2cluster $CANVAS, $X, $FROM, $LENGTH -Given sub-cluster from C<$FROM> with size C<$LENGTH>, calculates how many -clusters would fit in width C<$X>. +Given the sub-cluster from C<$FROM> with size C<$LENGTH>, calculates how many +clusters would fit in C<$X> pixels. =item _debug -Dumps glyph object content in a readable format. +Dumps the glyph object content in a readable format. =back diff --git a/Prima/Drawable/Gradient.pm b/Prima/Drawable/Gradient.pm index 1262c1bef..a0b39e850 100644 --- a/Prima/Drawable/Gradient.pm +++ b/Prima/Drawable/Gradient.pm @@ -370,10 +370,9 @@ Prima::Drawable::Gradient - gradient fills for primitives =head1 DESCRIPTION -Prima offers primitive gradient services to draw gradually changing colors. A -gradient is requested by setting at least two colors and optionally a set of -quadratic spline points that, when projected, generate the transition curve -between the colors. +Prima offers simple gradient services to draw gradually changing colors. A +gradient is made by setting at least two colors and optionally a set of points +that, when projected, generate the transition curve between the colors. The module augments the C drawing functionality by adding the C function. @@ -394,15 +393,15 @@ adding the C function. =over -=item new $CANVAS, %OPTIONS +=item clone %OPTIONS -Here are %OPTIONS understood in the gradient request: +Creates a new gradient object with %OPTIONS replaced. -=over +=item new $CANVAS, %OPTIONS -=item clone %OPTIONS +Creates a new gradient object. The following %OPTIONS are available: -Creates a new gradient object with %OPTIONS replaced. +=over =item dither BOOLEAN = 0 @@ -413,15 +412,15 @@ Works significantly slower. =item palette @COLORS Each color is a C value. The gradient is calculated as a polyline where -each of its vertex corresponds to a certain blend between two adjacent colors +each of its vertices corresponds to a certain blend between two adjacent colors in the palette. F.ex. the simplest palette going from C to -C over a polyline C<0..1> (default), produces a pure white color at -the start and a pure black color at the end, filling all available shades of gray -in between, and changing monotonically. +C over a transition line C<0..1> (default), produces a pure white color at +the start and a pure black color at the end, with all available shades of gray +in between. =item poly @VERTICES -A set of 2-integer polyline vertexes where the first integer is a coordinate (x, +A set of 2-integer polyline vertices where the first integer is a coordinate (x, y, or whatever is required by the drawing primitive) between 0 and 1, and the second is the color blend value between 0 and 1. @@ -429,7 +428,7 @@ Default: ((0,0),(1,1)) =item spline \@VERTICES, %OPTIONS -Serving the same purpose as the C option but the vertexes are projected first +Serving the same purpose as the C option but the vertices are projected first to a B-spline curve using L and C<%OPTIONS>. The resulting polyline is treated as C. @@ -455,7 +454,6 @@ Context used: fillPattern, rop, rop2 =item colors BREADTH Returns a list of gradient colors for each step from 1 to BREADTH. When - C is set, each color is an array of three items, - the two adjacent colors and an integer value between 0 and 63 that reflects the amount of blending needed between the colors. diff --git a/Prima/Drawable/Markup.pm b/Prima/Drawable/Markup.pm index 5b65ae8af..6ca16a7ec 100644 --- a/Prima/Drawable/Markup.pm +++ b/Prima/Drawable/Markup.pm @@ -6,86 +6,6 @@ use Prima qw(Drawable::TextBlock); use base qw(Prima::Drawable::TextBlock Exporter); our @EXPORT_OK = 'M'; -=head1 NAME - -Prima::Drawable::Markup - allow markup in widgets - -=head1 SYNOPSIS - - use Prima qw(Application Buttons); - use Prima::Drawable::Markup q(M); - my $m = Prima::MainWindow->new; - $m-> insert( Button => - text => Prima::Drawable::Markup->new(markup => "B bUtton"), - hotKey => 'u', - pack => {}, - ); - $m->insert( Button => pack => {}, text => M "I button" ); - $m->insert( Button => pack => {}, text => \ "Not an Q> button" ); - - run Prima; - -=for podview - -=for html

- -=head1 DESCRIPTION - -C adds the ability to recognize POD-like markup to Prima -widgets. Supported markup sequences are C (bold text), C (italic text), -C (underlined text), C (change font), C (change font size), C -(change foreground color), C (change background color), C (move pointer), -C (disable wrapping), and C

(picture). - -The C sequence is used as follows: C<< F >>, where C is a -0-based index into the C. - -The C sequence is used as follows: C<< S >>, where C is the -number of points relative to the current font size. The font size may -optionally be preceded by C<+> or C<->. - -The C and C sequences are used as follows: C<< C >>, where -C is either: a color in any form accepted by Prima, including the C -constants (C C C C C C C -C C C C C C -C C C C). Or, a 0-based index into the -C. Also, C can be used to set the color that the canvas -originaly had. For C a special value C can be used to turn off background -color and set it as transparent. - -The C command has three parameters, comma-separated: X, Y, and flags. X and -Y are coordinates how much to move the current pointer. By default X and are in -pixels, and do not extend block width. C is a set of characters, where -each is: - - m - set units to font height - p - set units to points - x - also extend the block width - -The text inside C sequence will not be wrapped during C calls. - -The text inside C sequence will not be treated as markup. - -The C

sequence is used as follows:C<< PEnE >>, where C is a -0-based index into the C. - -The L sequence parsing is resulted into making 1) C of color C, -and 2) wrapping the text with C commands in the block, that do nothing by default -but could be used by whoever uses the block. See L for more and L -as an example. - -The methods C and C are affected by C. -C will write formatted text to the canvas, and C will -return the width of the formatted text. B: These methods do not save state -between calls, so your markup cannot span lines (since each line is drawn or -measured with a separate call). - -The module can export a single method C that is a shortcut over creation of a new markup -object with default color, font, and image palettes. These can be accessed directly as -C<@COLORS, @FONTS, @IMAGES> correspondingly. - -=cut - our (@FONTS, @COLORS, @IMAGES); our $LINK_COLOR = cl::Green; @@ -561,7 +481,85 @@ sub text_wrap return [ @blocks, @other ]; } -=head1 PROPERTIES +=head1 NAME + +Prima::Drawable::Markup - allow markup in widgets + +=head1 SYNOPSIS + + use Prima qw(Application Buttons); + use Prima::Drawable::Markup q(M); + my $m = Prima::MainWindow->new; + $m-> insert( Button => + text => Prima::Drawable::Markup->new(markup => "B bUtton"), + hotKey => 'u', + pack => {}, + ); + $m->insert( Button => pack => {}, text => M "I button" ); + $m->insert( Button => pack => {}, text => \ "Not an Q> button" ); + + run Prima; + +=for podview + +=for html

+ +=head1 DESCRIPTION + +C adds the ability to recognize POD-like markup to Prima +widgets. Supported markup sequences are C (bold text), C (italic text), +C (underlined text), C (change font), C (change font size), C +(change foreground color), C (change background color), C (move pointer), +C (disable wrapping), and C

(picture). + +The C sequence is used as follows: C<< F >>, where C is a 0-based +index into the C. + +The C sequence is used as follows: C<< S >>, where C is the +number of points relative to the current font size. The font size may +optionally be preceded by C<+> or C<->. + +The C and C sequences are used as follows: C<< C >>, where C +is either: a color in any form accepted by Prima, including the C constants +(C C C C C C C C +C C C C C C +C C C). Or, a 0-based index into the C. +Also, C can be used to set the color that the canvas originally had. +For C a special value C can be used to turn off the background color +and set it as transparent. + +The C command has three parameters, comma-separated: X, Y, and flags. X and +Y are coordinates of how much to move the current pointer. By default X and are in +pixels, and do not extend block width. C is a set of characters, where +each is: + + m - set units to font height + p - set units to points + x - also extend the block width + +The text inside the C sequence will not be wrapped during C calls. + +The text inside the C sequence will not be treated as markup. + +The C

sequence is used as follows:C<< PEnE >>, where C is a +0-based index into the C. + +The L sequence parsing results in making 1) C of color +C, and 2) wrapping the text with C commands in the block, +that do nothing by default but could be used by whoever uses the block. See +L for more and L as an example. + +The methods C and C are affected by +C. C will write formatted text to the +canvas, and C will return the width of the formatted text. +B: These methods do not save the state between calls, so your markup cannot +span lines (since each line is drawn or measured with a separate call). + +The module can export a single method C which is a shortcut over the creation of +a new markup object with default color, font, and image palettes. These can be +accessed directly as C<@COLORS, @FONTS, @IMAGES> correspondingly. + +=head1 API The following properties are used: @@ -569,8 +567,8 @@ The following properties are used: =item colorPalette([@colorPalette]) -Gets or sets the color palette to be used for C sequences within this widget. -Each element of the array should be a C constant. +Gets or sets the color palette to be used for C sequences within this +widget. Each element of the array should be a C constant. =item fontPalette([@fontPalette]) @@ -579,8 +577,8 @@ Each element of the array should be a hashref suitable for setting a font. =item picturePalette([@picturePalette]) -Gets or sets the picture palette to be used for C

sequences within this widget. -Each element of the array should be a C descendant. +Gets or sets the picture palette to be used for C

sequences within this +widget. Each element of the array should be a C descendant. =back @@ -597,7 +595,7 @@ You may redistribute and/or modify this module under the same terms as Perl itse =head1 AUTHOR -This module based on work by Teo Sankaro, Eteo_sankaro@hotmail.comE. +This module is based on work by Teo Sankaro, Eteo_sankaro@hotmail.comE. =cut diff --git a/Prima/Drawable/Metafile.pm b/Prima/Drawable/Metafile.pm index b7de49f43..7677c2ef2 100644 --- a/Prima/Drawable/Metafile.pm +++ b/Prima/Drawable/Metafile.pm @@ -221,11 +221,11 @@ sub execute =head1 NAME -Prima::Drawable::Metafile - graphic primitive recorder +Prima::Drawable::Metafile - graphics recorder =head1 DESCRIPTION -Metafiles can record graphic primitives and replay them later on another canvas. +Metafiles can record graphic primitives and replay them later on another canvas =head1 SYNOPSIS @@ -242,7 +242,7 @@ Metafiles can record graphic primitives and replay them later on another canvas. =item call $SUB::($self,$canvas,@ARGS), @ARGS -C<$SUB> will be called when the metafile is executed, with the first two parameter +C<$SUB> will be called when the metafile is executed, with the first two parameters the metafile and the target canvas, and C<@ARGS> thereafter. =item clear @@ -252,11 +252,11 @@ Otherwise same as C. =item execute CANVAS,X,Y -Draws the content on a CANVAS with X,Y offset +Draws the content on the CANVAS with X,Y offset =item size X,Y -Sets metafile extensions; however the content is not clipped by it. +Sets the metafile extensions; the content is not clipped by it. =back diff --git a/Prima/Drawable/Path.pm b/Prima/Drawable/Path.pm index d813b288e..db2741442 100644 --- a/Prima/Drawable/Path.pm +++ b/Prima/Drawable/Path.pm @@ -1417,19 +1417,21 @@ sub _debug_commands __END__ +=pod + =head1 NAME Prima::Drawable::Path - stroke and fill complex paths =head1 DESCRIPTION -The module augments the C drawing and plotting functionality by -implementing paths that allow arbitrary combination of polylines, splines, and arcs, +The module augments the C's drawing and plotting functionality by +implementing paths that allow arbitrary combinations of polylines, splines, and arcs, to be used for drawing or clipping shapes. =head1 SYNOPSIS - # draws elliptic spiral + # draws an elliptic spiral my ( $d1, $dx ) = ( 0.8, 0.05 ); $canvas-> new_path-> rotate(45)-> @@ -1459,49 +1461,52 @@ the previous primitive (or (0,0) if there's none). =item arc CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0 -Adds elliptic arc to path centered around (CENTER_X,CENTER_Y). +Adds an elliptic arc to the path. The arc is centered around the (CENTER_X,CENTER_Y) point. -Important: if the intention is an immediate rendering, especially with 1-pixel +Important: if the intention is an immediate rendering, especially with a 1-pixel line width, consider decreasing diameters by 1. This is because all arc -calculations are made with floating point, where diameter is also given not in -pixels but in geometrical coordinates, to allow for matrix transformations. -Before rendering is performed, arcs are tranformed into spline vertices and -then transformation matrix is applied, and by that time the notion of an arc -diameter is lost to be successfully converted into pixel size minus one. +calculations are made with the floating point precision, where the diameter is also +given not in pixels but in geometrical coordinates, to allow for matrix +transformations. Before rendering is performed, arcs are transformed into +spline vertices and then the transformation matrix is applied, and by that time the +notion of an arc diameter is lost to be successfully converted into pixel size +minus one. + +Read more about this in L . =item close, open -Closes the current shape and opens a new one -close() is same as open() but makes sure the shape's first point is equal to its last point. +Closes the current shape and opens a new one. close() is the same as open() but +makes sure the shape's first point is equal to its last point. =item circular_arc ANGLE_START, ANGLE_END -Adds circular arc to the path. Note that adding transformations will effectively -make it into elliptic arc, which is used internally by C and C. +Adds a circular arc to the path. Note that adding transformations will effectively +make it into an elliptic arc, which is used internally by C and C. =item chord CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END. -Adds chord to the path. Is there only for compatibility with C. +Adds a chord to the path. Is there only for compatibility with C. =item ellipse CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y = DIAMETER_X, TILT = 0 -Adds full ellipse to the path. +Adds a full ellipse to the path. =item glyph INDEX, %OPTIONS -Adds glyph outline to the path. C<%OPTIONS> are passed as is to +Adds a glyph outline to the path. C<%OPTIONS> are passed as is to L, except the C option. -Note that filled glyphs require C without the C bit set -and the C option set to generate proper shapes with holes. +Note that filled glyphs require C without the C bit set, +and also the C option set to generate proper shapes with holes. =item line, rline @POINTS -Adds a polyline to path +Adds a polyline to the path =item lines [X1, Y1, X2, Y2].. -Adds set of multiple, unconnected lines to the path. Is there only for +Adds a set of multiple, unconnected lines to the path. Is there only for compatibility with C. =item moveto, rmoveto X, Y @@ -1510,37 +1515,45 @@ Stops plotting the current shape and moves the plotting position to X, Y. =item rarc DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0 -Adds elliptic arc to path so that the first point of the arc starts on the last -point of the previous primitive, or (0,0) if there's none. +Adds an elliptic arc to the path so that the first point of the arc starts on +the last point of the previous primitive, or (0,0) if there's none. =item rectangle X1, Y1, X2, Y2 -Adds rectangle to the path. Is there only for compatibility with C. +Adds a rectangle to the path. Is there only for compatibility with +C. =item round_rect X1, Y1, X2, Y2, MAX_DIAMETER -Adds round rectangle to the path. +Adds a round rectangle to the path. =item sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END -Adds sector to the path. Is there only for compatibility with C. +Adds a sector to the path. Is there only for compatibility with C. =item spline, rspline $POINTS, %OPTIONS. -Adds B-spline to path. See L for C<%OPTIONS> descriptions. +Adds a B-spline to the path. See L for C<%OPTIONS> descriptions. =item text TEXT, %OPTIONS -Adds C to the path. C<%OPTIONS> are same as in L, -except that C is deduced automatically based on whether C has utf8 bit -on or off; and an extra option C with a hash can be used to speed up the function -with subsequent calls. C option is same as L. +Adds C to the path. C<%OPTIONS> are the same as in L, +except that C is deduced automatically based on whether the C has utf8 bit +on or off. An extra option C with a hash can be used to speed up the function +with subsequent calls. The C option is the same as L. -Note that filled glyphs require C without the C bit set -and the C option set to generate proper shapes with holes. +Note that filled glyphs require C without the C bit set, +and also the C option set to generate proper shapes with holes. =back +=head2 Transformations + +Transformation calls change the current path properties (matrix etc) so that +all subsequent calls would use them until a call to C is made. The +C and C methods implement the stacking mechanism so that local +transformations can be made. + =head2 Properties =over @@ -1549,31 +1562,16 @@ and the C option set to generate proper shapes with holes. Provides access to the attached drawable object -=back - -=head2 Transformations - -Transformation calls change the current path properties (matrix etc) -so that all subsequent calls will use them until a call to C -is used. C and C implement a stacking mechanism, so that -local transformations can be made. - -The final transformations calculate coordinates the new and the existing matrices: - - P' = NewMatrix * P - -=over - =item matrix A, B, C, D, Tx, Ty -Applies transformation matrix to the path. The matrix, as used by the module, -is formed as such: +Applies a transformation matrix to the path. The matrix, as used by the module, +is formed as follows: A B 0 C D 0 Tx Ty 1 -and when applied to 2D coordinates, is calculated as +When applied to 2D coordinates, the transformed coordinates are calculated as X' = AX + CY + Tx Y' = BX + DY + Ty @@ -1598,7 +1596,7 @@ Adds rotation to the current matrix =item save -Duplicates the current matrix and graphic properties and pushes them to the stack. +Saves the current matrix and graphic properties on the stack. =item shear X, Y = X @@ -1616,34 +1614,34 @@ Default: depends on canvas antialiasing mode =item translate X, Y = X -Adds offset to the current matrix +Adds an offset to the current matrix =back =head2 Operations -These methods perform actual path rendering, that was delayed until that, and will -create an array of points that can be used for actual drawing. +These methods perform path rendering and create an array of points that can be +used for drawing =over =item clip %options -Returns 1-bit image with clipping mask of the path. C<%options> can be used to -pass C property that affects the result of the filled shape. +Returns a 1-bit image with the clipping mask created from the path. C<%options> can be used to +pass the C property that affects the result of the filled shape. =item contours -Same as L but further reduces lines into a 8-connected set of points, +Same as L but further reduces lines into a set of 8-connected points, suitable to be traced pixel-by-pixel. =item extents -Returns 2 points that box the path. +Returns two points that box the path. =item last_matrix -Return CTM resulted after running all commands +Returns the current transform matrix (CTM) after running all commands =item fill fillMode=undef @@ -1652,27 +1650,28 @@ selected on the canvas. =item fill_stroke fillMode=undef -Paints a filled shape over the path with back color. If C is set, it is used instead of the one -selected on the canvas. Thereafter, draws a polyline over the path. +Paints a filled shape over the path with the background color. If C +is set, it is used instead of the one selected on the canvas. Thereafter, draws +a polyline over the path. -=item flatten PRESCALE +=item flatten PRESCALE Returns new objects where arcs are flattened into lines. The lines are -rasterized with scaling factor that is as close as possible to the device -pixels, to be suitable for direct send to the polyline() API call. If PRESCALE +rasterized with a scaling factor that is as close as possible to the device +pixels, to be suitable for a call to the polyline() method. If the PRESCALE factor is set, it is used instead to premultiply coordinates of arc anchor points used to render the lines. =item points -Runs all accumulated commands, and returns rendered set of points, suitable -for further calls to C and C. +Runs all accumulated commands, returns rendered set of points suitable +for the C and C methods. =item region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union -Creates a region object from polygonal shape. If MODE is set, applies fill mode -(see L for more); if RGNOP is set, applies region set operation -(see L). +Creates a region object from the path. If MODE is set, applies fill mode (see +L for more); if RGNOP is set, applies region set +operation (see L). =item stroke @@ -1680,13 +1679,14 @@ Draws a polyline over the path =item widen %OPTIONS -Expands path into a new path object containing outlines of the original path as -if drawn with selected line properties. C, C, C, -C are read from C<%OPTIONS>, or from the attached canvas when -available. Supports C option with values from 0 to 20. +Expands the path into a new path object containing outlines of the original +path as if drawn with selected line properties. The values of C, +C, C, and C are read from C<%OPTIONS>, or from +the attached canvas when available. Supports the C option with +values from 0 to 20. Note: if the intention is to immediately render lines, decrease lineWidth by 1 -(they are 1 pixel wider because paths are built around assumption that pixel size is 0, +(they are 1 pixel wider because paths are built around the assumption that pixel size is 0, which makes them scalable). =back @@ -1703,13 +1703,13 @@ as a macro. =item identity -Returns identity matrix +Returns the identity matrix =item matrix_apply @POINTS -Applies current matrix to POINTS, returns the transformed points. -If @POINTS is a list, returns list; if it is an array reference, returns -array reference. +Applies the CTM to POINTS, returns the transformed points. If @POINTS is a +list, returns the transformed points as a list; if it is an array reference, +returns an array reference. =back diff --git a/Prima/Drawable/Subcanvas.pm b/Prima/Drawable/Subcanvas.pm index 78a2af14c..3d7410b93 100644 --- a/Prima/Drawable/Subcanvas.pm +++ b/Prima/Drawable/Subcanvas.pm @@ -323,8 +323,8 @@ Prima::Drawable::Subcanvas - paint a hierarchy of widgets to any drawable =head1 DESCRIPTION -Needed for painting a screenshot on an image, printer, etc. -When loaded, it aytomatically adds two methods to any Drawable: L and L. +Needed for painting a screenshot on an image, printer, etc. Adds two methods +to the C namespace: L and L. =head1 SYNOPSIS @@ -339,13 +339,13 @@ When loaded, it aytomatically adds two methods to any Drawable: L is in paint mode, traverses all widgets as they are seen on -screen, and paints them on the canvas with given C<$x,$y> offsets. +Given a C<$canvas> is in the paint mode, traverses all widgets as they are seen on +the screen, and paints them on the canvas with given C<$x,$y> offsets. =item screenshot $canvas, %opt Syntax sugar over the paint_with_widgets. Creates an image with the C<$self>'s, size, -and calls C with it. Returns the screen shot. +and calls C with it. Returns the screenshot. =back diff --git a/Prima/Drawable/TextBlock.pm b/Prima/Drawable/TextBlock.pm index 7775234f2..d14215542 100644 --- a/Prima/Drawable/TextBlock.pm +++ b/Prima/Drawable/TextBlock.pm @@ -1245,7 +1245,7 @@ Prima::Drawable::TextBlock - rich text representation =head2 Block header A block's fixed header consists of C integer scalars, -each of those is accessible via the corresponding C constant. +each of which is accessible via the corresponding C constant. The constants are separated into two logical groups: BLK_FLAGS @@ -1265,23 +1265,24 @@ and BLK_COLOR BLK_BACKCOLOR -The second group is enclosed in C - C -range, like the whole header is contained in 0 - C range. -This is done for the backward compatibility, if the future development changes -the length of the header. +The first group defines the offset constants that are used to address the +values in the block header; the constants lie in the 0 - C +range. The second group values line in the C - +C range. This is done for eventual backward compatibility, +if the future development changes the length of the header. -The first group fields define the text block dimension, aperture position -and text offset ( remember, the text is stored as one big chunk ). The second +The fields from the first group define the text block dimension, aperture position, +and text offset ( remember, the text is stored as one big chunk ). The second group defines the initial color and font settings. Prima::TextView needs all fields -of every block to be initialized before displaying. L method -can be used for automated assigning of these fields. +of every block to be initialized before displaying. The L method +can be used for the automated assigning of these fields. =head2 Block parameters -The scalars, beginning from C, represent the commands to the -renderer. These commands have their own parameters, that follow the command. -The length of a command is high 16-bit word of the command. The basic command -set includes C, C, C, C, and +The scalars after C encode the commands to the block renderer. +These commands have their own parameters which follow the command. The length +of the command is encoded in the high 16-bit word of the command. The basic +command set includes C, C, C, C, and C. The additional codes are C and C, not used in drawing but are special commands to L. @@ -1289,122 +1290,125 @@ drawing but are special commands to L. =item OP_TEXT - TEXT_OFFSET, TEXT_LENGTH, TEXT_WIDTH -C commands to draw a string, from offset C, -with a length TEXT_LENGTH. The third parameter TEXT_WIDTH contains the width of the text -in pixels. Such the two-part offset scheme is made for simplification of an imaginary code, -that would alter ( insert to, or delete part of ) the big text chunk; the updating procedure -would not need to traverse all commands, but just the block headers. +C commands to draw a string, from the offset C, with the length TEXT_LENGTH. The third parameter TEXT_WIDTH +contains the width of the text in pixels. The scheme is made for simplification +of an imaginary code, that would alter ( insert to, or delete part of ) the +text; the updating procedure would not need to traverse all commands in all +blocks, but only the block headers. Relative to: C =item OP_COLOR - COLOR C sets foreground or background color. To set the background, -COLOR must be or-ed with C value. In addition to the -two toolkit supported color values ( RRGGBB and system color index ), -COLOR can also be or-ed with C flags, in such case it is -an index in C<::colormap> property array. +COLOR must be or-ed with the C value. In addition to the +two toolkit-supported color values ( RRGGBB and system color index ), +COLOR can also be or-ed with the C flag, in such case it is +treated an index in the C<::colormap> property array. Relative to: C, C. =item OP_FONT - KEY, VALUE -As the font is a complex property, that itself includes font name, size, -direction, etc keys, C KEY represents one of the three -parameters - C, C, C. All three -have different VALUE meaning. +As a font is a complex property which includes font name, size, direction, etc +fields, the C KEY represents one of the three parameters - +C, C, C. All three have different VALUE +meanings. -Relative to: C, C, C. +Relates to: C, C, C. =over =item F_STYLE -Contains a combination of C constants, such as C, C etc. +Contains a combination of the C constants, such as C, C etc. Default value: 0 =item F_SIZE -Contains the relative font size. The size is relative to the current widget's font -size. As such, 0 is a default value, and -2 is the widget's default font decreased by +Contains the relative font size. The size is relative to the current font +size. As such, 0 is a default value, and -2 is the default font decreased by 2 points. Prima::TextView provides no range checking ( but the toolkit does ), so while it is o.k. to set the negative C values larger than the default font size, -one must be vary when relying on the combined font size value . +one must be careful when relying on the combined font size value . -If C value is added to a C constant, then it is treated as a font height -in pixels rather than font size in points. The macros for these opcodes are named respectively -C and C, while the opcode is the same. +If the C value is added to the C constant, then it is treated +as font height in pixels rather than font size in points. The macros for these +opcodes are named respectively C and C, while the +opcode is the same. =item F_ID -All other font properties are collected under an 'ID'. ID is a index in +All other font properties are collected under an 'ID'. ID is an index in the C<::fontPalette> property array, which contains font hashes with the other -font keys initialized - name, encoding, and pitch. These three are minimal required -set, and the other font keys can be also selected. +font keys initialized - name, encoding, and pitch. These three fields are required +to be defined in the font hash; the other font fields are optional. =back =item OP_TRANSPOSE X, Y, FLAGS -Contains a mark for an empty space. The space is extended to the relative coordinates (X,Y), -so the block extension algorithms take this opcode in the account. If FLAGS does not contain -C, then in addition to the block expansion, current coordinate is also -moved to (X,Y). In this regard, C<(OP_TRANSPOSE,0,0,0)> and C<(OP_TRANSPOSE,0,0,X_EXTEND)> are -identical and are empty operators. +Contains a mark for an empty space. The space is extended to the relative +coordinates (X,Y), so the block extension algorithms take this opcode into +account. If FLAGS does not contain C, then in addition to the +block expansion, the current coordinate is also moved to (X,Y). +C<(OP_TRANSPOSE,0,0,0)> and C<(OP_TRANSPOSE,0,0,X_EXTEND)> are identical and +are empty operators. -There are formatting-only flags,in effect with L function. -C indicates that (X,Y) values must be multiplied to +The C flag indicates that (X,Y) values must be multiplied by the current font height. Another flag C does the same but -multiplies by current value of L property divided by 72 ( -basically, treats X and Y not as pixel but point values). +multiplies by the current value of the L property divided by 72 ( +treats X and Y not as pixel but as point values). -C can be used for customized graphics, in conjunction with C -to assign a space, so the rendering -algorithms do not need to be re-written every time the new graphic is invented. As -an example, see how L deals with the images. +C can be used for customized graphics, in conjunction with +C to assign a space, so the rendering algorithms do not need to be +rewritten every time a new graphic is invented. For example, see how +L implements images and bullet points. =item OP_CODE - SUB, PARAMETER Contains a custom code pointer SUB with a parameter PARAMETER, passed when -a block is about to be drawn. SUB is called with the following format: +the block is about to be drawn. SUB is called with the following format: ( $widget, $canvas, $text_block, $font_and_color_state, $x, $y, $parameter); $font_and_color_state ( or $state, through the code ) contains the state of -font and color commands in effect, and is changed as the rendering algorithm advances through a block. -The format of the state is the same as of text block, so one may notice that for readability -F_ID, F_SIZE, F_STYLE constants are paired to BLK_FONT_ID, BLK_FONT_SIZE and BLK_FONT_STYLE. +font and color commands in effect, and is changed as the rendering algorithm +advances through the block. The format of the state is the same as of the text +block, and the F_ID, F_SIZE, the F_STYLE constants are the same as BLK_FONT_ID, +BLK_FONT_SIZE, and BLK_FONT_STYLE. -The SUB code is executed only when the block is about to draw. +The SUB code is executed only when the block is about to be drawn. =item OP_WRAP mode -C is only in effect in L method. C is a flag, +C is only used in the L method. C is a flag, selecting the wrapping command. WRAP_MODE_ON - default, block commands can be wrapped WRAP_MODE_OFF - cancels WRAP_MODE_ON, commands cannot be wrapped - WRAP_IMMEDIATE - proceed with immediate wrapping, unless ignoreImmediateWrap options is set + WRAP_IMMEDIATE - proceed with immediate wrapping, unless the ignoreImmediateWrap option is set L does not support stacking for the wrap commands, so the -C<(OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_OFF)> has same -effect as C<(OP_WRAP,WRAP_MODE_OFF)>. If C is WRAP_MODE_ON, wrapping is -disabled - all following commands treated an non-wrapable until -C<(OP_WRAP,WRAP_MODE_OFF)> is met. +C<(OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_OFF)> command +sequence has the same effect as the C<(OP_WRAP,WRAP_MODE_OFF)> sequence. If C is +WRAP_MODE_ON, wrapping is disabled - all following commands are treated as +non-wrappable until the C<(OP_WRAP,WRAP_MODE_OFF)> command sequence is met. =item OP_MARK PARAMETER, X, Y -C is only in effect in L method and is a user command. -L only sets (!) X and Y to the current coordinates when the command is met. -Thus, C can be used for arbitrary reasons, easy marking the geometrical positions -that undergo the block wrapping. +C is only in effect in the L method and is a user command. +L only sets (!) X and Y to the current coordinates when the command +is met. Thus, C can be used for arbitrary reasons, for example for +saving the geometrical positions during the block wrapping. =back -As can be noticed, these opcodes are far not enough for the full-weight rich text -viewer. However, the new opcodes can be created using C, that accepts -the opcode length and returns the new opcode value. +These opcodes are far not enough for the full-weight rich text viewer. However, +the new opcodes can be created using C, which accepts the opcode +length and returns the new opcode value. =head2 Rendering methods @@ -1412,31 +1416,32 @@ the opcode length and returns the new opcode value. =item block_wrap %OPTIONS -C wraps a block into a given width. It returns one or more text -blocks with fully assigned headers. The returned blocks are located one below +C wraps a block into a given width in pixels. It returns one or more text +blocks with fully formed headers. The returned blocks are located one below another, providing an illusion that the text itself is wrapped. It does not -only traverses the opcodes and sees if the command fit or not in the given +only traverse the opcodes and sees if the command fits in the given width; it also splits the text strings if these do not fit. -By default the wrapping can occur either on a command boundary or by the spaces +By default, the wrapping can occur either on a command boundary or by the spaces or tab characters in the text strings. The unsolicited wrapping can be -prevented by using C command brackets. The commands inside these -brackets are not wrapped; C commands are removed from the output +prevented by using the C command brackets. The commands inside these +brackets are not wrapped; the C commands are removed from the resulting blocks. -In general, C copies all commands and their parameters as is, ( as -it is supposed to do ), but some commands are treated specially: +C copies all commands and their parameters as is, except the following: - C's third parameter, C, is disregarded, and is recalculated for every -C met. +C command. -- If C's third parameter, C contains C flag, -the command coordinates X and Y are multiplied to the current font height and the flag is -cleared in the output block. +- If C's third parameter, C contains the +C flag, the command coordinates X and Y are +multiplied to the current font height, and the flag is cleared in the output +block. The C has a similar effect but the coordinates are +multiplied by the current resolution divided by 72. -- C's second and third parameters assigned to the current (X,Y) coordinates. +- C's second and third parameters are assigned to the current (X,Y) coordinates. -- C removed from the output. +- C is removed from the output. =item justify_interspace %OPTIONS @@ -1445,7 +1450,7 @@ inter-word spacing. Returns new block if successful, undef otherwise. =item walk BLOCK, %OPTIONS -Cycles through block opcodes, calls supplied callbacks on each. +Cycles through the block opcodes, calls supplied callbacks on each. =back