From 19894513197f6daa470be12ca7a34720b1942f35 Mon Sep 17 00:00:00 2001 From: Dmitry Karasik Date: Sat, 21 Oct 2023 17:31:09 +0200 Subject: [PATCH] polish some more pods --- Prima.pm | 8 +- Prima/Edit.pm | 270 ++++++++++++++++---------------- Prima/EventHook.pm | 61 ++++---- Prima/ExtLists.pm | 12 +- Prima/FrameSet.pm | 15 +- Prima/Grids.pm | 363 +++++++++++++++++++++---------------------- Prima/HelpViewer.pm | 67 ++++---- Prima/ImageViewer.pm | 127 +++++++-------- 8 files changed, 455 insertions(+), 468 deletions(-) diff --git a/Prima.pm b/Prima.pm index 5f7d50d03..756eb424a 100644 --- a/Prima.pm +++ b/Prima.pm @@ -376,17 +376,17 @@ L - advanced dockable widgets L - dockable widgets -L - text editor widget +L - text editor L - listbox with checkboxes -L - frameset widget class +L - frameset widget L - grid widgets -L - the built-in POD file browser +L - the built-in POD browser -L - bitmap viewer +L - image viewer L - input line widget diff --git a/Prima/Edit.pm b/Prima/Edit.pm index ea31ca64a..8a17dddbb 100644 --- a/Prima/Edit.pm +++ b/Prima/Edit.pm @@ -2939,7 +2939,7 @@ sub wordWrap {($#_)?($_[0]-> set_word_wrap( $_[1])) :ret =head1 NAME -Prima::Edit - standard text editing widget +Prima::Edit - standard text editor =head1 SYNOPSIS @@ -2957,59 +2957,59 @@ Prima::Edit - standard text editing widget =head1 DESCRIPTION The class provides text editing capabilities, three types of selection, text wrapping, -syntax highlighting, auto indenting, undo and redo function, search and replace methods. +syntax highlighting, auto indenting, undo and redo function, and search and replace methods. -The module declares C package, that contains integer constants for selection block type, -used by L property. +The module declares the C package that contains integer constants for the selection of block type, +used by the L property. =head1 USAGE -The text is stored line-wise in C<{lines}> array; to access it use L method. -To access the text chunk-wise, use L method. +The text is stored line-wise in the C<{lines}> array; to access it use the +L method. -All keyboard events, except the character input and tab key handling, are -processed by the accelerator table ( see L ). The default -C table defines names, keyboard combinations, and the corresponding -actions to the class functions. The class does not provide functionality to change -these mappings. To do so, consult L. +All keyboard events except the character input and tab keys are processed by +the accelerator table ( see L ). The default C table +defines names, keyboard combinations, and the corresponding actions to the +class functions. The class does not provide functionality to change these +mappings. To do so, consult L. =head2 Coordinates -The class addresses the text space by (X,Y)-coordinates, where X is visual -cluster offset and Y is line number. The addressing can be 'visual' and -'logical', - in logical case Y is number of line of text. The difference can -be observed if L property is set to 1, when a single text string can -be shown as several sub-strings, called I. +The class addresses the text space by (X,Y)-coordinates, where X is the visual +cluster offset and Y is the line number. The addressing coordinate system can be +I, I, or I. See below. -Cluster shaping and word wrapping can play a role here. Consider f.ex. text -"offset is zero", that for the sake of the example can wrapped by width and -displayed as two lines, "offset" and "is zero". Here, the font substitutes "ff" -text with a single ligature glyph. Here, for example, coord("f") will be (0,1) -in all coordinates, but coord("z") is different: +Cluster shaping and word wrapping can play a role here. Consider f.ex. a text +string "offset is zero", that for the sake of the example can wrapped by width +and displayed as two lines, "offset" and "is zero". Here, the font substitutes +"ff" text with a single ligature glyph. Here, for example, coord("f") will be +(0,1) in all coordinates, but coord("z") is not: =over =item Physical -X coordinate is a character offset from character line number Y. These -coordinates are identical with and without C flag. This coordinate is -used for direct text manipulation. +The X coordinate is a character offset from character line number Y. These +coordinates are identical with and without the C flag. This +coordinate is used for direct text manipulation. Example: coord("z") is (0,10); =item Visual -X coordinate is a glyph cluster offset from character line number Y. These -coordinates are identical with and without C flag. This coordinate is -used for cursor and selection API. +The X coordinate is a glyph cluster offset from the character line number Y. These +coordinates are identical with and without the C flag. This +coordinate is used for cursor and selection API. Example: coord("z") is (0,9); =item Logical -Y coordinates is a wrapped line index. C internal array is addresses -in logical coordinates. X coordinate is a glyph cluster offset from the line start. -This coordinate is used mostly internally. +The Y coordinate is the wrapped line index. The C internal array +contains addresses in the logical coordinates. The X coordinate is a glyph +cluster offset from the line start. This coordinate is used mostly internally. + +To access the text chunk-wise, use the L method. Example: coord("z") is (1,3); @@ -3043,7 +3043,7 @@ Default value: 1 =item blockType INTEGER -Defines type of selection block. Can be one of the following constants: +Defines the type of selection block. Can be one of the following constants: =over @@ -3059,7 +3059,7 @@ See also: L =item bt::Vertical -Rectangular block, where all selected lines are of same offsets and lengths. +Rectangular block, where all selected lines are of the same offsets and lengths. Default key: Alt+B @@ -3077,15 +3077,15 @@ See also: L =item cursor X, Y -Selects visual position of the cursor +Selects the visual position of the cursor =item cursorX X -Selects visual horizontal position of the cursor +Selects the visual horizontal position of the cursor =item cursorY Y -Selects visual vertical position of the cursor +Selects the visual vertical position of the cursor =item cursorWrap BOOLEAN @@ -3096,7 +3096,7 @@ See also: L, L, L, L. =item insertMode BOOLEAN -Set the typing mode - if 1, the typed text is inserted, if 0, the text overwrites +Set the typing mode - if 1, the typed text is inserted, if 0, the new text overwrites the old text. When C is 0, the cursor shape is thick and covers the whole character; when 1, it is of the default cursor width. @@ -3116,40 +3116,42 @@ Selects the color for highlighting the double-quoted strings =item hiliteIDs ARRAY -Array of scalar pairs, that define words to be highlighted. -The first item in the pair is an array of words; the second item is +An array of scalar pairs that define words to be highlighted. +The first item in the pair is an array of words, and the second item is a color value. =item hiliteChars ARRAY -Array of scalar pairs, that define characters to be highlighted. -The first item in the pair is a string of characters; the second item is +An array of scalar pairs that define characters to be highlighted. +The first item in the pair is a string of characters, and the second item is a color value. =item hiliteREs ARRAY -Array of scalar pairs, that define character patterns to be highlighted. -The first item in the pair is a perl regular expression; the second item is +An array of scalar pairs that define character patterns to be highlighted. +The first item in the pair is a perl regular expression, and the second item is a color value. -Note: these are tricky. Generally, they assume that whatever is captured in (), -is highlighted, and that capturing parentheses match from the first character -onwards. So for simple matches like C< (\d+) > (digits) or C< (#.*) > this -works fine. Things become more interesting if you need to check text after, or -especially before the capture. For this you need to make sure that whatever -text is matched by a regexp, need not move C pointer as the regexes are -looped over with C<\G> anchor prepended (i.e. starting each time from the -position the previous regex left off), and with C flags (advancing C< pos -> to the match length). Advancing the C will skip color highlighting on text after the -capture but before end of the match - so you'll need look-ahead assertions, C< (?=pattern) > -and C< (?!pattern) > (see L ). - -For example, we have a string C< ABC123abc >, and we want to match 123 followed by abc. -This won't work +Note: these are tricky. Generally, these assume that whatever is captured in +C<()>, is highlighted, and that capturing parentheses match from the first +character onwards. So for simple matches like C< (\d+) > (digits) or C< (#.*) +> this works fine. Things become more interesting if you need to check text +after, or especially before the capture. For this, you need to make sure that +whatever text is matched by a regexp, it must not move the C pointer as +the regexes are internally concatenated with the C<\G> anchor before the actual +matching takes place (i.e. starting each time from the position the previous +regex left off), and use C flags (advancing C to the match length). +Advancing the C will nullify color highlighting on the text after the +capture but before the end of the match - so you'll need look-ahead assertions +for this type of match, C<(?=pattern) > and C<(?!pattern)> (see +L ). + +For example, we have a string C, and we want to match I<123> followed by I. +This won't work: hiliteREs => [ '(123)abc',cl::LightRed, - '(abc)', cl::LightGreen + '(abc)', cl::LightGreen ] while this will: @@ -3162,7 +3164,7 @@ while this will: If you need to look behind, the corresponding assertions C< (?<=pattern) > and C< (? could be used, but these are even more restrictive in that they only support fixed-width looks-behinds (NB: C< \K > won't work because of -C< \G > either). That way, if we want to match 123 that follow ABC, this won't +C< \G > either). That way, if we want to match 123 that follows ABC, this won't work: hiliteREs => [ @@ -3186,8 +3188,8 @@ unset the value of L is used. =item markers ARRAY -Array of arrays with integer pairs, X and Y, where each represents -a visual coordinates in text. Used as anchor storage for fast navigation. +An array of arrays with integer pairs, X and Y, where each represents +visual coordinates in text. Used as anchor storage for fast navigation. See also: L, L @@ -3213,8 +3215,8 @@ If 1, no user input is accepted. Manipulations with text are allowed though. =item selection X1, Y1, X2, Y2 -Accepts two pair of visual coordinates, (X1,Y1) the beginning and (X2,Y2) the end -of new selection, and sets the block according to L property. +Accepts two pairs of visual coordinates, (X1,Y1) the beginning and (X2,Y2) the end +of the new selection, and sets the block according to the L property. The selection is null if X1 equals to X2 and Y1 equals to Y2. L method returns 1 if the selection is non-null. @@ -3229,11 +3231,11 @@ Manages the selection end. See L, X2 and Y2. =item syntaxHilite BOOLEAN -Governs the syntax highlighting. +Manages the syntax highlighting. =item tabIndent INTEGER -Maps tab ( \t ) key to C amount of space characters. +Maps the tab ( \t ) key to a C number of space characters. =item text TEXT @@ -3249,17 +3251,17 @@ If set, indicates RTL text input. =item textLigation BOOLEAN If set, text may be rendered at better quality with ligation and kerning, -however that comes with a price that some ligatures may be indivisible and form -clusters (f.ex. I or I ligatures). Cursor cannot go inside of such -clusters, and thus one can only select them, delete as whole, or press +however, that comes with a price that some ligatures may be indivisible and form +clusters (f.ex. I or I ligatures). The cursor cannot be positioned inside of +a cluster, and thus one can only select them, delete them as a whole, or press Del/Backspace on the cluster's edge. =item textRef TEXT_PTR Provides access to all the text data. The lines are separated by -the new line ( \n ) character. TEXT_PTR is a pointer to text string. +the new line ( \n ) character. TEXT_PTR is a pointer to a text string. -The property is more efficient than L with the large text, +The property is more efficient than L with large text because the copying of the text scalar to the stack is eliminated. See also: L. @@ -3270,44 +3272,42 @@ Selects the first line of the text drawn. =item undoLimit INTEGER -Sets limit on number of stored atomic undo operations. If 0, +Sets limit on the number of stored atomic undo operations. If 0, undo is disabled. Default value: 1000 =item wantTabs BOOLEAN -Selects the way the tab ( \t ) character is recognized in the user input. -If 1, it is recognized by the Tab key; however, this disallows the toolkit -widget tab-driven navigation. If 0, the tab character can be entered by -pressing Ctrl+Tab key combination. +Selects the way the tab ( \t ) character is recognized in the user input. If +1, it is recognized as the verbatim Tab key with an ascii value of 0x09; however, +this disallows the toolkit widget tab-driven navigation. If 0, the tab +character can be entered by pressing the Ctrl+Tab key combination. Default value: 0 =item wantReturns BOOLEAN Selects the way the new line ( \n ) character is recognized in the user input. -If 1, it is recognized by the Enter key; however, this disallows the toolkit -default button activation. If 0, the new line character can be entered by -pressing Ctrl+Enter key combination. +If 1, it is recognized as the verbatim CR key producing newline character(s); +however, this disallows the default button activation in the toolkit. If 0, the +new line character can be entered by pressing the Ctrl+Enter key combination. Default value: 1 - =item wordDelimiters STRING -Contains string of character that are used for locating a word break. +Contains a string of characters that are used for locating a word break. Default STRING value consists of punctuation marks, space and tab characters, -and C<\xff> character. +and the C<\xff> character. See also: L, L - =item wordWrap BOOLEAN -Selects whether the long lines are wrapped, or can be positioned outside the horizontal -widget inferior borders. If 1, L is not used. A line of text can be represented -by more than one line of screen text ( chunk ) . To access the text chunk-wise, use L +Selects whether the long lines are wrapped, or can be positioned outside the +horizontal widget borders. A line of text can be represented by more than one +line of screen text ( chunk ) . To access the text chunk-wise, use the L method. =back @@ -3318,12 +3318,12 @@ method. =item add_marker X, Y -Adds visual coordinated X,Y to the L property. +Adds visual coordinates X,Y to the L property. =item back_char [ REPEAT = 1 ] -Removes REPEAT times a character left to the cursor. If the cursor is on 0 x-position, -removes the new-line character and concatenates the lines. +Removes REPEAT times a character left to the cursor. If the cursor is on 0 X-position, +removes the new-line character and concatenates the two lines. Default key: Backspace @@ -3335,7 +3335,7 @@ Default key: Alt+U =item change_locked -Returns 1 if the logical locking is on, 0 if it is off. +Returns 1 if the logical locking is on, and 0 if it is off. See also L. @@ -3354,13 +3354,13 @@ Default key: Alt+C =item cursor_cend -Moves cursor to the bottom line +Moves cursor to the last line Default key: Ctrl+End =item cursor_chome -Moves cursor to the top line +Moves cursor to the first line Default key: Ctrl+Home @@ -3444,7 +3444,7 @@ Default key: Alt+D =item delete_char [ REPEAT = 1 ] -Delete REPEAT characters from the cursor position +Deletes REPEAT characters from the cursor position Default key: Delete @@ -3464,11 +3464,11 @@ Removes CHUNKS ( or lines, if L is 0 ) of text at CHUNK_ID =item delete_marker INDEX -Removes marker INDEX in L list. +Removes marker INDEX in the L list. =item delete_to_end -Removes text to the end of the chunk. +Removes the text to the end of the chunk. Default key: Ctrl+E @@ -3480,7 +3480,7 @@ Removes TEXT_LENGTH characters at X,Y physical coordinates Paints the syntax-highlighted chunk taken from LINE_ID line index, at X, Y. COLOR is used if the syntax highlighting information contains C -as color reference. +as a color reference. =item end_block @@ -3488,14 +3488,14 @@ Stops the block selection session. =item find SEARCH_STRING, [ X = 0, Y = 0, REPLACE_LINE = '', OPTIONS ] -Tries to find ( and, if REPLACE_LINE is defined, to replace with it ) -SEARCH_STRING from (X,Y) physical coordinates. OPTIONS is an integer -that consists of the C constants; the same constants are used -in L, which provides graphic interface to the find and replace -facilities of L. +Tries to find ( and, if REPLACE_LINE is defined, to replace with ) +SEARCH_STRING starting from (X,Y) physical coordinates. OPTIONS is an integer +that is a combination of the C constants; the same constants are used in +L, which provides a graphic interface to the find and +replace facilities of this class. Returns X1, Y, X2, NEW_STRING where X1.Y-X2.Y are physical coordinates of -the found string, and NEW_STRING is the replaced version (if any) +the string found, and NEW_STRING is the replaced version (if any) =over @@ -3513,7 +3513,7 @@ If set, SEARCH_STRING is a regular expression. =item fdo::BackwardSearch -If set, the search direction is backwards. +If set, the search direction is backward. =item fdo::ReplacePrompt @@ -3525,49 +3525,49 @@ See also: F =item get_chunk CHUNK_ID -Returns chunk of text, located at CHUNK_ID. -Returns empty string if chunk is nonexistent. +Returns the chunk of text, located at CHUNK_ID. +Returns an empty string if the chunk is nonexistent. =item get_chunk_cluster_length CHUNK_ID -Return length of a chunk in clusters +Return the length of a chunk in clusters =item get_chunk_dimension CHUNK_ID -Finds the line number the CHUNK_ID belongs to, return first chunk of that line and -how many chunks the line occupies. +Finds the line number the CHUNK_ID belongs to, and returns the first chunk of that line and +how many chunks the line consists of. =item get_chunk_width TEXT, FROM, LENGTH, [ RETURN_TEXT_PTR ] Returns the width in pixels of C. If FROM is -larger than length of TEXT, TEXT is padded with space characters. Tab character -in TEXT replaced to L times space character. If RETURN_TEXT_PTR +larger than the length of TEXT, TEXT is padded with the space characters. Tab character +in TEXT replaced to L times space character. If the RETURN_TEXT_PTR pointer is specified, the converted TEXT is stored there. =item get_line INDEX -Returns line of text, located at INDEX. -Returns empty string if line is nonexistent. +Returns the line of text located at INDEX. +Returns an empty string if the line is nonexistent. =item get_line_cluster_length LINE_ID -Return length of a line in clusters +Return the length of the line in clusters =item get_line_dimension INDEX -Returns two integers, representing the line at INDEX in L mode: -the first value is the corresponding chunk index, the second is how many -chunks represent the line. +Returns two integers representing the line at INDEX in the L mode: +the first value is the corresponding chunk index, and the second is how many +chunks are contained in the line. See also: L. =item get_selected_text -Return the text currently selected. +Return the currently selected text. =item has_selection -Returns boolean value, indicating if the selection block is active. +Returns a boolean value, indicating if the selection block is active. =item insert_empty_line LINE_ID, [ REPEAT = 1 ] @@ -3585,42 +3585,42 @@ the selection block is canceled and the newly inserted text is selected. =item lock_change BOOLEAN Increments ( 1 ) or decrements ( 0 ) lock count. Used to defer change notification -in multi-change calls. When internal lock count hits zero, C notification is called. +in multi-change calls. When the internal lock count hits zero, the C notification is called. =item physical_to_logical X, Y -Maps visual X,Y coordinates to the logical and returns the integer pair. -Returns same values when L is 0. +Maps visual X,Y coordinates to the logical coordinate system. +Returns the same values when L is 0. =item logical_to_visual X, Y -Maps logical X,Y coordinates to the visual and returns the integer pair. +Maps logical X,Y coordinates to the visual coordinate system. -Returns same values when L is 0. +Returns the same values when L is 0. =item visual_to_physical X, Y Maps visual X,Y coordinates to the physical text offset relative to the Y line -Returns same X when the line does not contain any right-to-left characters or +Returns the same X when the line does not contain any right-to-left (RTL) characters or complex glyphs. =item physical_to_visual X, Y Maps test offset X from line Y to the visual X coordinate. -Returns same X when the line does not contain any right-to-left characters or +Returns the same X when the line does not contain any right-to-left (RTL) characters or complex glyphs. =item mark_horizontal -Starts block marking session with C block type. +Starts block marking session with the C block type. Default key: Alt+L =item mark_vertical -Starts block marking session with C block type. +Starts block marking session with the C block type. Default key: Alt+B @@ -3633,7 +3633,7 @@ Default key: Alt+O =item paste -Copies text from the clipboard and inserts it in the cursor position. +Copies text from the clipboard and inserts it at the cursor position. Default key: Shift+Insert @@ -3644,11 +3644,11 @@ The deferred operations are those performed by L and L. =item set_line LINE_ID, TEXT, [ OPERATION, FROM, LENGTH ] -Changes line at LINE_ID to new TEXT. Hint scalars OPERATION, FROM and LENGTH -used to maintain selection and marking data. OPERATION is an arbitrary string, +Changes line at LINE_ID to new TEXT. Hint scalars OPERATION, FROM, and LENGTH +are used to maintain selection and marking data. OPERATION is an arbitrary string, the ones that are recognized are C<'overtype'>, C<'add'>, and C<'delete'>. -FROM and LENGTH define the range of the change; FROM is a cluster offset and -LENGTH is a length of changed text. +FROM and LENGTH define the range of the change; FROM is the cluster offset and +LENGTH is the length of the changed text. =item split_line @@ -3662,21 +3662,21 @@ Selects all text =item start_block [ BLOCK_TYPE ] -Begins the block selection session. The block type if BLOCK_TYPE, if it is -specified, or L property value otherwise. +Begins the block selection session. The block type is BLOCK_TYPE, if it is +specified, or the value of the L property is otherwise. =item update_block -Adjusts the selection inside the block session, extending of shrinking it to +Adjusts the selection inside the block session, extending or shrinking it to the current cursor position. =item word_left [ REPEAT = 1 ] -Moves cursor REPEAT words to the left. +Moves the cursor REPEAT words to the left. =item word_right [ REPEAT = 1 ] -Moves cursor REPEAT words to the right. +Moves the cursor REPEAT words to the right. =back diff --git a/Prima/EventHook.pm b/Prima/EventHook.pm index d3f0debe1..d19bf5366 100644 --- a/Prima/EventHook.pm +++ b/Prima/EventHook.pm @@ -116,27 +116,25 @@ Prima::EventHook - event filtering =head1 DESCRIPTION -Prima dispatches events by calling notifications registered -on one or more objects interested in the events. Also, one -event hook can be installed that would receive all events occurred on -all objects. C provides multiplex access to -the core event hook and introduces set of dispatching rules so -the user hook subs receive only a defined subset of events. - -The filtering criteria are event names and object hierarchy. +The toolkit dispatches notifications by calling subroutines registered on one +or more objects. Also, the core part of the toolkit allows a single event hook +callback to be installed that would receive all events occurring on all objects. +C provides multiplexed access to the core event hook and +introduces a set of dispatching rules so that the user hooks can receive only a +subset of events. =head1 API =head2 install SUB, %RULES -Installs SUB into hook list using hash of RULES. +Installs SUB using a hash of RULES. -The SUB is called with variable list of parameters, formed so first passed -parameters from C<'param'> key ( see below ), then event source object, then -event name, and finally parameters to the event. SUB must return an integer, -either 0 or 1, to block or pass the event, respectively. If 1 is returned, -other hook subs are called; if 0 is returned, the event is efficiently blocked -and no hooks are further called. +The SUB is called with a variable list of parameters, formed so that first come +parameters from the C<'param'> key ( see below ), then the event source object, +then the event name, and finally the parameters to the event. The SUB must return +an integer, either 0 or 1, to block or pass the event, respectively. If 1 is +returned, other hook subs are called; if 0 is returned, the event is +efficiently blocked and no hooks are called further. Rules can contain the following keys: @@ -144,10 +142,10 @@ Rules can contain the following keys: =item event -Event is either a string, an array of strings, or C value. In the latter -case it is equal to C<'*'> string, which selects all events to be passed in the -SUB. A string is either name of an event, or one of pre-defined event groups, -declared in C<%groups> package hash. The group names are: +An event is either a string, an array of strings, or an C value. In the latter +case, it is equal to a C<'*'> string which selects all events to be passed to the +SUB. A string is either the name of an event or one of the pre-defined event groups, +declared in the C<%groups> package hash. The group names are: ability focus @@ -158,44 +156,43 @@ declared in C<%groups> package hash. The group names are: objects visibility -These contain respective events. See source for detailed description. +These contain the respective events. See the source for a detailed description. -In case C<'event'> key is an array of strings, each of the strings is -also name of either an event or a group. In this case, if C<'*'> string +In case the C<'event'> key is an array of strings, each of the strings is +also the name of either an event or a group. In this case, if the C<'*'> string or event duplicate names are present in the list, SUB is called several -times which is obviously inefficient. +times. =item object -A Prima object, or an array of Prima objects, or undef; the latter case +A Prima object, or an array of Prima objects, or undef; in the latter case matches all objects. If an object is defined, the SUB is called -if event source is same as the object. +if the event source is the same as the object. =item children -If 1, SUB is called using same rules as described in C<'object'>, but also if +If 1, SUB is called using the same rules as described in C<'object'>, but also if the event source is a child of the object. Thus, selecting C as a filter object and setting C<'children'> to 0 is almost the same as selecting -C<$::application>, which is the root of Prima object hierarchy, as filter +C<$::application>, which is the root of the Prima object hierarchy, as a filter object with C<'children'> set to 1. -Setting together object to C and children to 1 is inefficient. +Setting C to C and children to 1 is inefficient. =item param A scalar or array of scalars passed as first parameters to SUB -whenever it is called. =back =head2 deinstall SUB -Removes the hook sub for the hook list. +Removes the hook sub =head1 NOTES -C by default automatically starts and stops Prima event hook -mechanism when appropriate. If it is not desired, for example for your own +C by default automatically starts and stops the Prima event +hook mechanism when appropriate. If it is not desired, for example for your own event hook management, set C<$auto_hook> to 0. =head1 AUTHOR diff --git a/Prima/ExtLists.pm b/Prima/ExtLists.pm index 115e1ec8a..32eb07f6e 100644 --- a/Prima/ExtLists.pm +++ b/Prima/ExtLists.pm @@ -232,14 +232,14 @@ Prima::ExtLists - extended functionality for list boxes =head1 DESCRIPTION The module is intended to be a collection of list boxes with -particular enhancements. Currently the only package is contained -is C class. +particular enhancements. Currently, the only package defined here +is the C class. =head1 Prima::CheckList -Provides a list box, where each item is equipped with a check box. +Provides a list box class where each item is equipped with a check box. The check box state can interactively be toggled by the enter key; -also the list box reacts differently by click and double click. +also the list box reacts differently to click and double click. =head2 Properties @@ -248,13 +248,13 @@ also the list box reacts differently by click and double click. =item button INDEX, STATE Runtime only. Sets INDEXth button STATE to 0 or 1. -If STATE is -1, the button state is toggled. +If the STATE is -1 the button state is toggled. Returns the new state of the button. =item vector VEC -VEC is a vector scalar, where each bit corresponds to the check state +VEC is a vector scalar where each bit corresponds to the checked state of each list box item. See also: L. diff --git a/Prima/FrameSet.pm b/Prima/FrameSet.pm index 2b0d15ffd..2b9e0e563 100644 --- a/Prima/FrameSet.pm +++ b/Prima/FrameSet.pm @@ -914,7 +914,7 @@ sub insert_to_frame =head1 NAME -Prima::FrameSet - standard frameset widget +Prima::FrameSet - frameset widget =head1 SYNOPSIS @@ -941,15 +941,12 @@ Prima::FrameSet - standard frameset widget =head1 DESCRIPTION -Provides standard means of framesets manipulations. It includes sharing of -common workspace among several widget groups; redistribution of space, occupied -by frames; isolation of different frames from each other. +Provides the standard frameset widget. The frameset divides its surface among +groups of children and allows interactive change of the surface by dragging +the frame bars with the mouse. -This module defines C and C packages for constants, used by L -and L properties, respectively. - -Two additional auxiliary packages are defined within this module: L -and L. +This module defines the C and C constants used by the +L and L properties, respectively. =head1 AUTHOR diff --git a/Prima/Grids.pm b/Prima/Grids.pm index 80581e312..24bc29e9b 100644 --- a/Prima/Grids.pm +++ b/Prima/Grids.pm @@ -2392,53 +2392,51 @@ Prima::Grids - grid widgets =head1 DESCRIPTION -The module provides classes for several abstraction layers -of grid representation. The classes hierarchy is as follows: +The module provides classes for several abstraction layers for the representation +of grid widgets. The class hierarchy is as follows: AbstractGridViewer AbstractGrid GridViewer Grid -The root class, C, provides common -interface, while by itself it is not directly usable. -The main differences between classes -are centered around the way the cell data are stored. The simplest -organization of a text-only cell, provided by C, -stores data as a two-dimensional array of text scalars. More elaborated storage -and representation types are not realized, and the programmer is urged -to use the more abstract classes to derive own mechanisms. -To organize an item storage, different from C, it is -usually enough to overload either the C, C, -and C events, or their method counterparts: C, -C, C, and C. - -The grid widget is designed to contain cells of variable extents, of two types, normal and -indent. The indent rows and columns are displayed in grid margins, and their -cell are drawn with distinguished colors. -An example use for a bottom indent row is a sum row in a spreadsheet application; -the top indent row can be used for displaying columns' headers. The normal cells -can be selected by the user, scrolled, and selected. The cell selection -can only contain rectangular areas, and therefore is operated with -two integer pairs with the beginning and the end of the selection. - -The widget operates in two visual scrolling modes; when the space allows, -the scrollbars affect the leftmost and the topmost cell. When the widget is -not large enough to accommodate at least one cell and all indent cells, the layout -is scrolled pixel-wise. These modes are named 'cell' and 'pixel', after the scrolling -units. - -The widget allows the interactive changing of cell widths and heights by dragging -the grid lines between the cells. +The root class, C, provides a common interface, while +by itself it is not directly usable. The main difference between classes is in +the way the cell data are stored. The simplest organization of a text-only +cell, provided by C, stores data as a two-dimensional array of +text scalars. More elaborated storage and representation types are not +realized, and the programmer is urged to use the more abstract classes to +derive their own mechanisms. To organize an item storage different from +C it is usually enough to overload either the C, +C, and C events, or their method counterparts: +C, C, C, and C. + +The grid widget is designed to contain cells of variable extents, of two types, +normal and indent. The indent rows and columns are displayed near to the widget +borders, and their cells are drawn with distinguished colors. An example usage +for a bottom indent row is a sum row in a spreadsheet application; the top +indent row can be used for displaying columns' headers. The normal cells can be +selected by the user, scrolled, and selected. The cell selection can only +contain rectangular areas and therefore is operated with two integer pairs +at the beginning and the end of the selection. + +The widget operates in two visual scrolling modes; when the space allows, the +scrollbars affect the leftmost and the topmost cell. When the widget is not +large enough to accommodate at least one cell and all indent cells, the layout +is scrolled pixel-wise. These modes are named 'cell' and 'pixel', after the +scrolling units. + +The widget allows the interactive changing of cell widths and heights by +dragging the grid lines between the cells. =head1 Prima::AbstractGridViewer C, the base for all grid widgets in the module, -provides interface to generic grid browsing functionality, -plus functionality for text-oriented grids. The class is not usable directly. +provides the interface to generic grid browsing functionality, plus some +functionality for text-oriented grids. The class is not usable directly. C is a descendant of C, -and some properties are not described here. +and some of its properties are not described here. =head2 Properties @@ -2446,49 +2444,47 @@ and some properties are not described here. =item allowChangeCellHeight BOOLEAN -If 1, the user is allowed to change vertical extents of cells by dragging the -horizontal grid lines. Prerequisites to the options are: -the lines must be set visible via C property, C -property set to 0, and the changes to the vertical extents can be recorded -via C notification. +If 1, the user is allowed to change the vertical extents of cells by dragging the +horizontal grid lines. The prerequisites are: the lines must be set visible via +the C property, the C property set to 0, and the changes +to the vertical extents can be recorded via the C notification. Default value: 0 =item allowChangeCellWidth BOOLEAN -If 1, the user is allowed to change horizontal extents of cells by dragging the -horizontal grid lines. Prerequisites to the options are: -the lines must be set visible via C property, C -property set to 0, and the changes to the horizontal extents can be recorded -via C notification. +If 1, the user is allowed to change the horizontal extents of cells by dragging the +horizontal grid lines. The prerequisites are: the lines must be set visible via +the C property, the C property set to 0, and the changes +to the horizontal extents can be recorded via the C notification. Default value: 0 =item cellIndents X1, Y1, X2, Y2 -Marks the marginal rows and columns as 'indent' cells. The indent cells -are drawn with another color pair ( see L, L ), -cannot be selected and scrolled. X1 and X2 correspond to amount of indent columns, -and Y1 and Y2, - to the indent rows. +Marks the marginal rows and columns as 'indent' cells. The indent cells are +drawn with another color pair ( see L, L +), and cannot be selected and scrolled. X1 and X2 correspond to the number of the +indent columns, and Y1 and Y2 to the number of the indent rows. C and C do not count the indent cells as the leftmost or topmost -visible cell; in other words, X1 and Y1 are minimal values for C and C +visible cells; in other words, X1 and Y1 are minimal values for C and C properties. Default value: 0,0,0,0 =item clipCells INTEGER -A three-state integer property, that manages the way clipping is applied -when cells are drawn. Depending on kind of graphic in cells, the clipping +A three-state integer property that manages the way clipping is applied +when cells are drawn. Depending on the kind of graphic in cells, the clipping may be necessary, or unnecessary. If the value is 1, the clipping is applied for every column drawn, as the -default drawing routines proceed column-wise. If the value is 2, the clipping -as applied for every cell. This setting reduces the drawing speed significantly. +default drawing routines proceeds column-wise. If the value is 2, the clipping +is applied for every cell. This setting reduces the drawing speed significantly. If the value is 0, no clipping is applied. -This property is destined for custom-drawn grid widgets, when it is the +This property is destined for custom-drawn grid widgets when it is the developer's task to decide what kind of clipping suits better. Text grid widgets, C and C, are safe with C set to 1. @@ -2497,19 +2493,18 @@ Default value: 1 =item columns INTEGER -Sets number of columns, including the indent columns. The number of +Sets the number of columns, including the indent columns. The number of columns must be larger than the number of indent columns. Default value: 0. =item columnWidth COLUMN [ WIDTH ] -A run-time property, selects width of a column. To acquire or set -the width, C and C notifications can be invoked. -Result of C may be cached internally using C -method. +A run-time property, selects the width of a column. To acquire or set the width, +C and C notifications can be invoked. The result of C +may be cached internally using the C method. -The width does not include widths of eventual vertical grid lines. +The width does not include the widths of eventual vertical grid lines. If C is defined, the property is used as its alias. @@ -2555,36 +2550,35 @@ Selects coordinates or the focused cell. =item gridColor COLOR -Selects the color of grid lines. +Selects the color of the grid lines. Default value: C . =item gridGravity INTEGER -The property selects the breadth of area around the grid lines, that -reacts on grid-dragging mouse events. The minimal value, 0, marks -only grid lines as the drag area, but makes the dragging operation inconvenient -for the user. -Larger values make the dragging more convenient, but increase the chance that -the user will not be able to select too narrow cells with the mouse. +The property selects the breadth of the area around the grid lines that react to +the grid-dragging mouse events. The minimal value of 0, marks only grid lines +themselves as the dragging areas but makes the operation inconvenient for the +user. Larger values make the dragging more convenient, but increase the chance +that the user will not be able to select too narrow cells with the mouse. Default value: 3 =item indentCellBackColor COLOR -Selects the background color of indent cells. +Selects the background color of the indent cells. Default value: C . =item indentCellColor -Selects the foreground color of indent cells. +Selects the foreground color of the indent cells. Default value: C . =item leftCell INTEGER -Selects index of the leftmost visible normal cell. +Selects the index of the leftmost visible normal cell. =item multiSelect BOOLEAN @@ -2596,33 +2590,32 @@ Default value: 0 =item rows INTEGER -Sets number of rows, including the indent rows. The number of -rows must be larger than the number of indent rows. +Sets the number of rows, including the indent rows. The number of +rows must be larger than the number of the indent rows. Default value: 0. =item topCell -Selects index of the topmost visible normal cell. +Selects the index of the topmost visible normal cell. =item rowHeight INTEGER -A run-time property, selects height of a row. To acquire or set -the height, C and C notifications can be invoked. -Result of C may be cached internally using C -method. +A run-time property, selects the height of a row. To acquire or set the height, +C and C notifications can be invoked. The result of C +may be cached internally using the C method. -The height does not include widths of eventual horizontal grid lines. +The height does not include the heights of eventual horizontal grid lines. If C is defined, the property is used as its alias. =item selection X1, Y1, X2, Y2 -If C is 1, manages the extents of a rectangular area, that -contains selected cells. If no such area is present, selection +If C is 1, manages the extent of a rectangular area that +contains selected cells. If no such area is present, the selection is (-1,-1,-1,-1), and C returns 0 . -If C is 0, in get-mode returns the focused cell, and discards +If C is 0, in get-mode returns the focused cell, and ignores the parameters in the set-mode. =back @@ -2633,22 +2626,23 @@ the parameters in the set-mode. =item cache_geometry_requests CACHE -If CACHE is 1, starts caching results of C notification, thus lighting the -subsequent C and C calls; if CACHE is 0, flushes the cache. +If CACHE is 1, starts caching results of the C notification, thus +making the subsequent C and C calls lighter. If CACHE +is 0, flushes the cache. -If a significant geometry change was during the caching, the cache is not updated, so it is the -caller's responsibility to flush the cache. +If a significant geometry change happens during the caching, the cache is not +updated automatically, so it is the caller's responsibility to flush the cache. =item deselect_all -Nullifies the selection, if C is 1. +Removes the selection if C is 1. =item draw_cells CANVAS, COLUMNS, ROWS, AREA -A bulk draw routine, called from C to draw cells. -AREA is an array of four integers with inclusive-inclusive +A bulk draw routine, called from C to draw individual cells. +AREA is an array of four integers in inclusive-inclusive coordinates of the widget inferior without borders and scrollbars -( result of C call; see L ). +( the result of C call; see L ). COLUMNS and ROWS are structures that reflect the columns and rows of the cells to be drawn. Each item in these corresponds to a column or row, and is an @@ -2662,34 +2656,34 @@ array with the following layout: 5: real cell start 6: real cell end -The coordinates are in inclusive-inclusive coordinate system, and -do not include eventual grid space, nor gaps between indent and +The coordinates are in the inclusive-inclusive coordinate system and +do not include eventual grid space, nor gaps between the indent and normal cells. By default, internal arrays C<{colsDraw}> and C<{rowsDraw}> are passed as COLUMNS and ROWS parameters. -In C and C classes is overloaded to +In the C and C classes is overloaded to transfer the call to C, the text-oriented optimized routine. =item draw_text_cells SCREEN_RECTANGLES, CELL_RECTANGLES, CELL_INDECES, FONT_HEIGHT -A bulk routine for drawing text cells, called from C . +A bulk routine for drawing text cells, is called from C . SCREEN_RECTANGLES and CELL_RECTANGLES are arrays, where each item is a rectangle -with exterior of a cell. SCREEN_RECTANGLES contains rectangles that cover the -cell visible area; CELL_RECTANGLES contains rectangles that span the cell extents +with an exterior of a cell. SCREEN_RECTANGLES contains rectangles that cover the +visible area of the cell; CELL_RECTANGLES contains rectangles that span the cell extent disregarding its eventual partial visibility. For example, a 100-pixel cell with -only its left half visible, would contain corresponding arrays [150,150,200,250] +only its left half visible would contain corresponding arrays [150,150,200,250] in SCREEN_RECTANGLES, and [150,150,250,250] in CELL_RECTANGLES. CELL_INDECES contains arrays of the cell coordinates; each array item is an array of -integer pair where item 0 is column, and item 1 is row of the cell. +integer pairs where item 0 is the column, and item 1 is the row of the cell. -FONT_HEIGHT is a current font height value, cached since C is -often used for text operations and may require vertical text justification. +FONT_HEIGHT is the current font height value, as C is +mostly used for text operations and may require vertical text justification. =item get_cell_area [ WIDTH, HEIGHT ] -Returns screen area in inclusive-inclusive pixel coordinates, that is used +Returns screen area in the inclusive-inclusive pixel coordinates. The area is used to display normal cells. The extensions are related to the current size of a widget, however, can be overridden by specifying WIDTH and HEIGHT. @@ -2697,42 +2691,41 @@ however, can be overridden by specifying WIDTH and HEIGHT. Returns two C constants for horizontal and vertical cell text alignment. Since the class does not assume the item storage organization, -the values are queried via C notification. +the values are queried via the C notification. =item get_cell_text COLUMN, ROW -Returns text string assigned to cell in COLUMN and ROW. +Returns the text string assigned to the cell in COLUMN and ROW. Since the class does not assume the item storage organization, -the text is queried via C notification. +the text is queried via the C notification. =item get_range VERTICAL, INDEX -Returns a pair of integers, minimal and maximal breadth of INDEXth column +Returns a pair of integers, the minimal and maximal breadth of INDEXth column or row in pixels. If VERTICAL is 1, the rows are queried; if 0, the columns. -The method calls C notification. +The method calls the C notification. =item get_screen_cell_info COLUMN, ROW -Returns information about a cell in COLUMN and ROW, if it is currently visible. -The returned parameters are indexed by C constants, -and explained below: +Returns information about the cell in COLUMN and ROW, if it is currently visible. +The returned parameters are indexed by the C constants: - gsci::COL_INDEX - visual column number where the cell displayed - gsci::ROW_INDEX - visual row number where the cell displayed + gsci::COL_INDEX - visual column number where the cell is displayed + gsci::ROW_INDEX - visual row number where the cell is displayed gsci::V_FULL - cell is fully visible - gsci::V_LEFT - inclusive-inclusive rectangle of the visible - gsci::V_BOTTOM part of the cell. These four indices are grouped - gsci::V_RIGHT under list constant, gsci::V_RECT. + gsci::V_LEFT - an inclusive-inclusive rectangle of the visible + gsci::V_BOTTOM part of the cell. These four indices are grouped + gsci::V_RIGHT under list constant, gsci::V_RECT. gsci::V_TOP - gsci::LEFT - inclusive-inclusive rectangle of the cell, as if - gsci::BOTTOM it is fully visible. These four indices are grouped - gsci::RIGHT under list constant, gsci::RECT. If gsci::V_FULL - gsci::TOP is 1, these values are identical to these in gsci::V_RECT. + gsci::LEFT - an inclusive-inclusive rectangle of the cell, as if + gsci::BOTTOM it is fully visible. These four indices are grouped + gsci::RIGHT under list constant, gsci::RECT. If gsci::V_FULL + gsci::TOP is 1, these values are identical to those in gsci::V_RECT. -If the cell is not visible, returns empty array. +If the cell is not visible, returns an empty array. =item has_selection @@ -2740,17 +2733,17 @@ Returns a boolean value, indicating whether the grid contains a selection (1) or =item point2cell X, Y, [ OMIT_GRID = 0 ] -Return information about point X, Y in widget coordinates. The method -returns two integers, CX and CY, with cell coordinates, and -eventual HINTS hash, with more information about pixe localtion. If OMIT_GRID is set to 1 -and the pixel belongs to a grid, the pixels is treated a part of adjacent cell. -The call syntax: +Returns information about the point X, Y in widget coordinates. The method +returns two integers CX and CY with cell coordinates and an eventual HINTS hash +that contains more information about the pixel location. If OMIT_GRID is set to +1 but the pixel belongs to the grid, the pixels are treated as part of an +adjacent cell. The call syntax is: - ( $CX, $CY, %HINTS) = $self->point2cell( $X, $Y); + ($CX, $CY, %HINTS) = $self->point2cell( $X, $Y); -If the pixel lies within cell boundaries by either coordinate, CX and/or CY -are correspondingly set to cell column and/or row. When the pixel is outside -cell space, CX and/or CY are set to -1. +If the pixel lies within the cell boundaries by either coordinate, CX and/or CY +are correspondingly set to that cell column and/or row. When the pixel is outside +the cell space, CX and/or CY are set to -1. HINTS may contain the following values: @@ -2758,14 +2751,14 @@ HINTS may contain the following values: =item C and C -If 0, the coordinate lies within boundaries of a cell. +If 0, the coordinate lies within the boundaries of a cell. -If -1, the coordinate is on the left/top to the cell body. +If -1, the coordinate is on the left/top of the cell body. -If +1, the coordinate is on the right/bottom to the cell body, but within +If +1, the coordinate is on the right/bottom of the cell body, but within the widget. -If +2, the coordinate is on the right/bottom to the cell body, but outside +If +2, the coordinate is on the right/bottom of the cell body, but outside the widget. =item C and C @@ -2774,26 +2767,26 @@ Present when C or C values are 0. If 0, the cell is a normal cell. -If -1, the cell is left/top indent cell. +If -1, the cell is a left or a top indent cell. -If +1, the cell is right/bottom indent cell. +If +1, the cell is a right or a bottom indent cell. =item C and C -If 1, the point is over a grid line. This case can only happen when OMIT_GRID is 0. +If 1, the point is at a grid line. This case can only happen when OMIT_GRID is 0. If C and/or C are set, treats also -C-broad pixels strips on both sides of the line as the grid area. +C-broad pixels strips on both sides of the line as the grid. -Also values of C/C or C/C might be set. +Also, values of C/C or C/C might be set. =item C/C and C/C -Present together with C or C. Select indices of -cells adjacent to the grid line. +Present together with C or C. Contain the indices of +the cells adjacent to the grid line. =item C and C -If 1, the point is within a gap between the last normal cell and the first +If 1, the point is inside a gap between the last normal cell and the first right/bottom indent cell. =item C @@ -2806,17 +2799,17 @@ If 1, the point lies within the boundaries of an indent cell. =item C -If 1, the point is over a grid line. +If 1, the point is at a grid line. =item C -If 1, the point is in inoperable area or outside the widget boundaries. +If 1, the point is in an inoperable area or outside the widget boundaries. =back =item redraw_cell X, Y -Repaints cell with coordinates X and Y. +Repaints the cell with coordinates X and Y. =item reset @@ -2824,18 +2817,18 @@ Recalculates internal geometry variables. =item select_all -Marks all cells as selected, if C is 1. +Marks all cells as selected if C is 1. =item std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA An optimized bulk routine for text-oriented grid widgets. The optimization -is achieved under assumption that each cell is drawn with two colors only, -so the color switching can be reduced. +is achieved under the assumption that each cell is drawn with two colors only +so that the color switching can be reduced. -The routine itself paints the cells background, and calls C -to draw text and/or otherwise draw the cell content. +The routine itself paints the cells' background and then calls C +to draw the cells' content. -For explanation of COLUMNS, ROWS, and AREA parameters see L . +For the explanation of COLUMNS, ROWS, and AREA parameters see L . =back @@ -2847,30 +2840,30 @@ For explanation of COLUMNS, ROWS, and AREA parameters see L . Called when a cell with COLUMN and ROW coordinates is to be drawn on CANVAS. SCREEN_RECT is a cell rectangle in widget coordinates, -where the item is to be drawn. CELL_RECT is same as SCREEN_RECT, but calculated +where the item is to be drawn. CELL_RECT is the same as SCREEN_RECT but calculated as if the cell is fully visible. -SELECTED, FOCUSED, and PRELIGHT are boolean flagss, if the cell must be drawn +SELECTED, FOCUSED, and PRELIGHT are boolean flags, if the cell must be drawn correspondingly in selected, focused, and pre-lighted states. =item GetAlignment COLUMN, ROW, HORIZONTAL_ALIGN_REF, VERTICAL_ALIGN_REF -Puts two text alignment C constants, assigned to cell with COLUMN and ROW coordinates, +Stores two text alignment C constants, assigned to the cell with COLUMN and ROW coordinates, into HORIZONTAL_ALIGN_REF and VERTICAL_ALIGN_REF scalar references. =item GetRange VERTICAL, INDEX, MIN, MAX -Puts minimal and maximal breadth of INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1) -in corresponding MIN and MAX scalar references. +Stores minimal and maximal breadth of INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1) +in the corresponding MIN and MAX scalar references. =item Measure VERTICAL, INDEX, BREADTH -Puts breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1) +Stores breadth in pixels of the INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1) into BREADTH scalar reference. This notification by default may be called from within -C brackets. To disable this feature -set internal flag C<{NoBulkPaintInfo}> to 1. +the C brackets. To disable this feature +set the internal flag C<{NoBulkPaintInfo}> to 1. =item SelectCell COLUMN, ROW @@ -2878,32 +2871,32 @@ Called when a cell with COLUMN and ROW coordinates is focused. =item SetExtent VERTICAL, INDEX, BREADTH -Reports breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1), -as a response to C and C calls. +Reports breadth in pixels of the INDEXth column ( VERTICAL = 0 ) or row ( VERTICAL = 1), +as a response to the C and C calls. =item Stringify COLUMN, ROW, TEXT_REF -Puts text string, assigned to cell with COLUMN and ROW coordinates, into TEXT_REF +Stores the text string, assigned to the cell with COLUMN and ROW coordinates, into the TEXT_REF scalar reference. =back =head1 Prima::AbstractGrid -Exactly the same as its ascendant, C, -except that it does not propagate C message, -assuming that the items must be drawn as text. +The same as its ascendant, C, except that it +does not propagate the C message, assuming that the items must be drawn +as text. =head1 Prima::GridViewer -The class implements cells data and geometry storage mechanism, but leaves -the cell data format to the programmer. The cells are accessible via -C property and several other helper routines. +The class implements cell data and geometry storage mechanisms but leaves +the data format to the programmer. The cells are accessible via +the C property and several other helper routines. The cell data are stored in an array, where each item corresponds to a row, -and contains array of scalars, where each corresponds to a column. All +and contains an array of scalars, where each corresponds to a column. All data managing routines, that accept two-dimensional arrays, assume that -the columns arrays are of the same widths. +the column arrays are of the same width. For example, C<[[1,2,3]]]> is a valid one-row, three-column structure, and C<[[1,2],[2,3],[3,4]]> is a valid three-row, two-column structure. @@ -2926,7 +2919,7 @@ Default value: 1 =item cell COLUMN, ROW, [ DATA ] -Run-time property. Selects the data in cell with COLUMN and ROW coordinates. +Run-time property. Selects the data in the cell with COLUMN and ROW coordinates. =item cells [ ARRAY ] @@ -2935,11 +2928,11 @@ rectangular array or scalars. =item columns INDEX -A read-only property; returns number of columns. +A read-only property; returns the number of columns. =item rows INDEX -A read-only property; returns number of rows. +A read-only property; returns the number of rows. =back @@ -2949,19 +2942,19 @@ A read-only property; returns number of rows. =item add_column CELLS -Inserts one-dimensional array of scalars to the end of columns. +Inserts a one-dimensional array of scalars to the end of columns. =item add_columns CELLS -Inserts two-dimensional array of scalars to the end of columns. +Inserts a two-dimensional array of scalars to the end of columns. =item add_row CELLS -Inserts one-dimensional array of scalars to the end of rows. +Inserts a one-dimensional array of scalars to the end of rows. =item add_rows CELLS -Inserts two-dimensional array of scalars to the end of rows. +Inserts a two-dimensional array of scalars to the end of rows. =item delete_columns OFFSET, LENGTH @@ -2975,31 +2968,31 @@ are accepted. =item insert_column OFFSET, CELLS -Inserts one-dimensional array of scalars as column OFFSET. +Inserts a one-dimensional array of scalars as column OFFSET. Negative values are accepted. =item insert_columns OFFSET, CELLS -Inserts two-dimensional array of scalars in column OFFSET. +Inserts a two-dimensional array of scalars in column OFFSET. Negative values are accepted. =item insert_row -Inserts one-dimensional array of scalars as row OFFSET. +Inserts a one-dimensional array of scalars as row OFFSET. Negative values are accepted. =item insert_rows -Inserts two-dimensional array of scalars in row OFFSET. +Inserts a two-dimensional array of scalars in row OFFSET. Negative values are accepted. =back =head1 Prima::Grid -Descendant of C, declares format of cells -as a single text string. Incorporating all functionality of -its ascendants, provides a standard text grid widget. +Descendant of C, declares format of cell data as a single +text string. Provides the standard text grid widget that has all the +functionality of its ascendants. =head2 Methods @@ -3009,13 +3002,13 @@ its ascendants, provides a standard text grid widget. Returns two C constants for horizontal and vertical cell text alignment. Since the item storage organization is implemented, does -so without calling C notification. +so without calling the C notification. =item get_cell_text COLUMN, ROW -Returns text string assigned to cell in COLUMN and ROW. +Returns text string assigned to the cell in COLUMN and ROW. Since the item storage organization is implemented, does -so without calling C notification. +so without calling the C notification. =back diff --git a/Prima/HelpViewer.pm b/Prima/HelpViewer.pm index bb7a5f612..045571c8f 100644 --- a/Prima/HelpViewer.pm +++ b/Prima/HelpViewer.pm @@ -1045,23 +1045,22 @@ __END__ =head1 NAME -Prima::HelpViewer - the built-in pod file browser +Prima::HelpViewer - the built-in POD browser =head1 USAGE -The module presents two packages, C -and C. Their sole purpose is to serve as a mediator -between C package, the toolkit help interface and the user. -C includes all the user functionality, including ( but -not limited to :) text search, color and font setup, printing etc. -C provides two methods - C and C, used by -C for help viewer invocation. +The module presents two packages, C and +C. Their purpose is to serve as a mediator between the +C package, the toolkit help interface, and the user. +C includes all the user functionality needed, including +text search, color and font setup, printing, etc. C provides +two methods - C and C, used by C for +invocation of the help viewer . =head1 Help -The browser can be used to view and print POD -( plain old documentation ) files. See the command overview below for more -detailed description: +The browser can be used to view and print POD ( plain old documentation ) +files. See the command overview below for a more detailed description =over @@ -1071,13 +1070,12 @@ detailed description: =item Open -Presents a file selection dialog, when the user can select -a file to browse in the viewer. The file must contain POD content, -otherwise a warning is displayed. +Presents a file selection dialog, when the user can select a file to browse. +The file must contain POD content, otherwise, a warning is displayed. =item Goto -Asks for a manpage, that is searched in PATH and the installation +Asks for a manpage, that is searched in PATH and the perl installation directories. =item New window @@ -1092,20 +1090,19 @@ Commands in this group call external processes =item prima-class -prima-class is Prima utility for displaying the widget class hierachies. -The command asks for Prima class to display the hierachy information -for. +prima-class is the utility for displaying the widget class hierarchies. +The command asks for the Prima class to display the hierarchy information. =back =item Print -Provides a dialog, when the user can select the appropriate +Provides a dialog where the user can select the appropriate printer device and its options. Prints the current topic to the selected printer. -If L menu item is checked, prints the whole manpage. +If the L menu item is checked, prints the whole manpage. =item Close window @@ -1132,18 +1129,17 @@ Decreases the currently selected font by 2 points. =item Full text view If checked, the whole manpage is displayed. Otherwise, -its content is presented as a set of topic, and only one +its content is presented as a set of topics, and only a single topic is displayed. =item Find -Presents a find dialog, where the user can -select the text to search and the search options - -the search direction, scope, and others. +Presents a text find dialog where the user can type the text to search, and +select the search options - the search direction, scope, etc. =item Find again -Starts search for the text, entered in the last find dialog, +Starts search for the text, entered in the last text find dialog, with the same search options. =item Fast find @@ -1160,21 +1156,21 @@ performed parallel to the input. =item Backward -Same as L option, except that the serach direction is backwards. +Same as the L option, except that the search direction is backward. =item Repeat forward -Repeat the search in the same direction as the initial search was being invoked. +Repeats the search in the same direction as the initial search =item Repeat backward -Repeat the search in the reverse direction as the initial search was being invoked. +Repeat the search in the reverse direction from the initial search =back =item Setup -Presents a setup dialog, where the user can select appropriate fonts and colors. +Presents a setup dialog where the user can select appropriate fonts and colors. =back @@ -1184,24 +1180,24 @@ Presents a setup dialog, where the user can select appropriate fonts and colors. =item Back -Displays the previously visited manpage ( or topic ) +Displays the previously visited manpage or topic =item Forward -Displays the previously visited manpage ( or topic ), -that was left via L command. +Displays the previously visited manpage or topic +that was left via the L command. =item Up -Displays the upper level topic within a manpage. +Displays the upper-level topic within the manpage =item Previous -Moves to the previous topic within a manpage. +Moves to the previous topic within the manpage =item Next -Moves to the next topic within a manpage. +Moves to the next topic within the manpage =back @@ -1229,5 +1225,4 @@ Dmitry Karasik, Edmitry@karasik.eu.orgE. This program is distributed under the BSD License. - =cut diff --git a/Prima/ImageViewer.pm b/Prima/ImageViewer.pm index 99f4ef7f0..472005b3f 100644 --- a/Prima/ImageViewer.pm +++ b/Prima/ImageViewer.pm @@ -579,7 +579,7 @@ sub unwatch_load_progress =head1 NAME -Prima::ImageViewer - standard image, icon, and bitmap viewer class. +Prima::ImageViewer - image, icon, and bitmap viewer =head2 SYNOPSIS @@ -596,8 +596,9 @@ Prima::ImageViewer - standard image, icon, and bitmap viewer class. =head1 DESCRIPTION -The module contains C class, which provides -image displaying functionality, including different zoom levels. +The module contains the C class which provides image-displaying +functionality. The widget can display images, icons, and bitmaps, and allows +zooming. C is a descendant of C and inherits its document scrolling behavior and programming interface. @@ -628,13 +629,13 @@ given the C. Scrollbars are turned off if C is set to 1 =item image OBJECT -Selects the image object to be displayed. OBJECT can be -an instance of C, C, or C class. +Selects the image object to be displayed. OBJECT can be an instance of +the C, C, or C classes. =item imageFile FILE -Set the image FILE to be loaded and displayed. Is rarely used since does not return -a loading success flag. +Sets the image FILE to be loaded and displayed. Is rarely used since does not +return a success flag. =item scaling ist::XX @@ -652,7 +653,7 @@ keyboard navigation become disabled. =item quality BOOLEAN -A boolean flag, selecting if the palette of C is to be +A boolean flag, selects if the palette of C is to be copied into the widget palette, providing higher visual quality on paletted displays. See also L. @@ -668,16 +669,16 @@ One of the following C constants: Selects the vertical image alignment. -NB: C value is not equal to C's, however -the both constants produce equal effect here. +Note: The C value is not equal to C's, however, +both constants produce an equal effect here. Default value: C =item zoom FLOAT -Selects zoom level for image display. The acceptable value range is between +Selects the image zoom level. The acceptable value range is between 0.01 and 100. The zoom value is rounded to the closest value divisible by -1/C. For example, is C is 100, the zoom values +1/C. For example, if C is 100, the zoom values will be rounded to the precision of hundredth - to fiftieth and twentieth fractional values - .02, .04, .05, .06, .08, and 0.1 . When C is 1000, the precision is one thousandth, and so on. @@ -686,48 +687,51 @@ Default value: 1 =item zoomPrecision INTEGER -Zoom precision of C property. Minimal acceptable value is 10, where zoom -will be rounded to 0.2, 0.4, 0.5, 0.6, 0.8 and 1.0 . +Zoom precision of the C property. The minimal acceptable value is 10, where the zoom +factor will be rounded to 0.2, 0.4, 0.5, 0.6, 0.8, and 1.0 . -The reason behind this arithmetics is that when an image of an arbitrary zoom factor -is requested to be displayed, the image sometimes must be drawn from -a fraction image pixel - for example, 10x zoomed image shifted 3 pixels left, must be -displayed so the first image pixel from the left occupies 7 screen pixels, and -the next ones - 10 screen pixels. That means, that the correct image display -routine must ask the system to draw the image at offset -3 screen pixels, where -the first image pixel column would correspond to that offset. +The reason behind this arithmetics is that when an image of an arbitrary zoom +factor is requested to be displayed, the image sometimes must be drawn from a +fractional image pixel. In an example that only involves integer pixels, a 10x +zoomed image shifted 3 pixels left must be displayed so that the first image +pixel from the left occupies 7 screen pixels, and the next ones - 10 screen +pixels. That means that the correct image display routine must ask the system +to draw the image at the offset of -3 screen pixels, where the first image +pixel column would correspond to that offset. When the zoom factor is fractional, the picture is getting more complex. For -example, with zoom factor 12.345, and zero screen offset, the first image pixel -begins at the 12th screen pixel, the next one - at the 25th ( because of the -roundoff ), then the 37th etc etc. If the image is 2000x2000 pixels wide, and -is asked to be drawn so that it appears shifted 499 screen image pixels left, -it needs to be drawn from the 499/12.345=40.42122th image pixel. Is might seem -that indeed it would be enough to ask the system to begin drawing from image -pixel 40, and offset int(0.42122*12.345)=5 screen pixels to the left, however, -that procedure will not account for the correct fixed point roundoff that -accumulates as system scales the image. For zoom factor 12.345 this roundoff -sequence is, as we seen before, (12,25,37,49,62,74,86,99,111,123) for the first -10 pixels displayed, that occupy (12,13,12,12,13,12,12,13,12,12) screen pixels -correspondingly. For the pixels starting at 499, the sequence is +example, with the zoom factor of 12.345 and zero screen offset, the first +image pixel begins at the 12th screen pixel, the next one - at the 25th ( +because of the roundoff ), then the 37th, etc etc. If the image is 2000x2000 +pixels wide and is asked to be drawn so that it appears shifted 499 screen +image pixels left, it needs to be drawn from the 499/12.345=40.42122th image +pixel. It might seem that indeed it would be enough to ask the system to begin +drawing from image pixel 40, and offset int(0.42122*12.345)=5 screen pixels to +the left, however, that procedure will not account for the correct fixed point +roundoff that accumulates as the system scales the image. For the zoom factor +of 12.345 this roundoff sequence is, as we have seen before, +(12,25,37,49,62,74,86,99,111,123) for the first 10 pixels displayed, that +occupy (12,13,12,12,13,12,12,13,12,12) screen pixels correspondingly. For the +pixels starting at 499, the sequence is (506,519,531,543,556,568,580,593,605,617) offsets or (13,12,12,13,13,12,12,13,12,12) widths -- note the two subsequent 13s there. This sequence begins to repeat itself after 200 iterations -(12.345*200=2469.000), which means that in order to achieve correct display +(12.345*200=2469.000), which means that to achieve correct display results, the image must be asked to be displayed from as far as image pixel 0 if image's first pixel on the screen is between 0 and 199 ( or for screen pixels 0-2468), then from image pixel 200 for offsets 200-399, ( screen pixels 2469-4937), and so on. -Since the system internally allocates memory for image scaling, that means that up -to 2*200*min(window_width,image_width)*bytes_per_pixel unneccessary bytes will -be allocated for each image drawing call (2 because the calculations are valid -for both the vertical and horizontal strips), and this can lead to slowdown or -even request failure when image or window dimensions are large. The proposed -solution is to roundoff accepted zoom factors, so these offsets are kept small -- for example, N.25 zoom factors require only max 1/.25=4 extra pixels. When -C value is 100, zoom factors are rounded to 0.X2, 0.X4, 0.X5, -0.X6, 0.X8, 0.X0, thus requiring max 50 extra pixels. +Since the system internally allocates memory for image scaling, that means that +up to 2*200*min(window_width,image_width)*bytes_per_pixel unnecessary bytes +will be allocated for each image drawing call (2 because the calculations are +valid for both the vertical and horizontal strips), and this can lead to +a slowdown or even request failure when image or window dimensions are large. The +proposed solution is to round off the accepted zoom factors so that these +offsets are kept small. For example, the N.25 zoom factors require only max +1/.25=4 extra pixels. When the C value is set to 100, the zoom +factors are rounded to 0.X2, 0.X4, 0.X5, 0.X6, 0.X8, and 0.X0, thus requiring +max 50 extra pixels. NB. If, despite the efforts, the property gets in the way, increase it to 1000 or even 10000, but note that this may lead to problems. @@ -743,8 +747,8 @@ Default value: 100 =item on_paint SELF, CANVAS The C notification handler is mentioned here for the specific case -of its return value, that is the return value of internal C call. -For those who might be interested in C failures, that mostly occur +of its return value, that is the return value of the internal C call. +For those who might be interested in C failures, which mostly occur when trying to draw an image that is too big, the following code might be useful: @@ -756,48 +760,49 @@ useful: =item screen2point X, Y, [ X, Y, ... ] -Performs translation of integer pairs integers as (X,Y)-points from widget coordinates -to pixel offset in image coordinates. Takes in account zoom level, -image alignments, and offsets. Returns array of same length as the input. +Performs translation of integer pairs as (X,Y)-points from the widget +coordinates to pixel offsets in the image coordinate system. Takes into account +zoom level, image alignments, and offsets. Returns an array of the same length as +the input. Useful for determining correspondence, for example, of a mouse event -to a image point. +to an image point. The reverse function is C. =item point2screen X, Y, [ X, Y, ... ] Performs translation of integer pairs as (X,Y)-points from image pixel offset -to widget image coordinates. Takes in account zoom level, -image alignments, and offsets. Returns array of same length as the input. +to widget image coordinates. Takes into account zoom level, image alignments, and +offsets. Returns an array of the same length as the input. -Useful for determining a screen location of an image point. +Useful for determining the screen location of an image point. The reverse function is C. =item watch_load_progress IMAGE -When called, image viewer watches as IMAGE is being loaded ( see L ) -and displays the progress. As soon as IMAGE begins to load, it replaces the existing C -property. Example: +When called, the image viewer begins to track the progress of the IMAGE being +loaded ( see L ) and incrementally displays the loading +picture. As soon as IMAGE begins to load, it replaces the existing the C +property value. Example: $i = Prima::Image-> new; $viewer-> watch_load_progress( $i); $i-> load('huge.jpg'); $viewer-> unwatch_load_progress; -Similar functionality is present in L. +A similar functionality is present in L. =item unwatch_load_progress CLEAR_IMAGE=1 -Stops monitoring of image loading progress. If CLEAR_IMAGE is 0, the leftovers of the -incremental loading stay intact in C propery. Otherwise, C is set to C. +Stops monitoring the image loading progress. If CLEAR_IMAGE is 0, the leftovers of the +incremental loading stay intact in C property. Otherwise, C is set to C. =item zoom_round ZOOM -Rounds the zoom factor to C precision, returns -the rounded zoom value. The algorithm is the same as used internally -in C property. +Rounds the zoom factor to C precision, returns the rounded zoom +value. The algorithm is the same as used internally in the C property. =back