From c9dfdb03cff585d6a37a26551b60b76cc22954b6 Mon Sep 17 00:00:00 2001 From: Dmitry Karasik Date: Sun, 22 Oct 2023 22:10:04 +0200 Subject: [PATCH] polish some pods --- Prima.pm | 6 +- Prima/IniFile.pm | 59 ++++---- Prima/InputLine.pm | 68 +++++----- Prima/KeySelector.pm | 59 ++++---- Prima/Label.pm | 53 ++++---- Prima/Lists.pm | 314 +++++++++++++++++++++---------------------- pod/Prima/Menu.pod | 2 +- 7 files changed, 270 insertions(+), 291 deletions(-) diff --git a/Prima.pm b/Prima.pm index 756eb424a..18f2d5153 100644 --- a/Prima.pm +++ b/Prima.pm @@ -396,7 +396,7 @@ L - menu widgets L - static text widget -L - user-selectable item list widgets +L - list widgets L - top-level windows emulation classes @@ -414,9 +414,9 @@ L - spinner animation L - rich text browser widget -L - standard date picker widget +L - date picker widget -L - standard time input widget +L - time input widget =item Standard dialogs diff --git a/Prima/IniFile.pm b/Prima/IniFile.pm index f8ec56300..2da9e1fca 100644 --- a/Prima/IniFile.pm +++ b/Prima/IniFile.pm @@ -524,12 +524,11 @@ Prima::IniFile - support of Windows-like initialization files =head1 DESCRIPTION -The module contains a class, that provides mapping of text initialization file to -a two-level hash structure. The first level -is called sections, which groups the second level hashes, called items. -Sections must have unique keys. The items hashes values are arrays of -text strings. The methods, operated on these arrays are L, -L, L and L. +The module provides mapping of a text initialization file to a two-level hash +structure. The first level is I, which groups the second level +hashes, I. Sections must have unique keys. The values of the I hashes are +arrays of text strings. The methods that operate on these arrays are +L, L, L, and L. =head1 SYNOPSIS @@ -583,33 +582,33 @@ Cleans all internal data in the object, including the name of the file. =item create PROFILE -Creates an instance of the class. The PROFILE is treated partly as -an array, partly as a hash. If PROFILE consists of a single item, -the item is treated as a filename. Otherwise, PROFILE is treated as a hash, -where the following keys are allowed: +Creates an instance of the class. The PROFILE is treated partly as an array, +and partly as a hash. If PROFILE consists of a single item, the item is treated as +a filename. Otherwise, PROFILE is treated as a hash, where the following keys +are allowed: =over =item file FILENAME -Selects name of file. +Selects the name of the file. =item default %VALUES -Selects the initial values for the file, where VALUES is a two-level -hash of sections and items. It is passed to L, where it is merged -with the file data. +Selects the initial values for the file, where VALUES is a two-level hash of +sections and items. It is passed to L, where it is merged with the file +data. =back =item get_values SECTION, ITEM -Returns array of values for ITEM in SECTION. If called in scalar context, -and there is more than one value, the first value in list is returned. +Returns an array of values for ITEM in SECTION. If called in scalar context +and there is more than one value, the first value in the list is returned. =item items SECTION [ HINTS ] -Returns items in SECTION. HINTS parameters is used to tell if a multiple-valued +Returns items in SECTION. HINTS parameters are used to tell if a multiple-valued item must be returned as several items of the same name; HINTS can be supplied in the following forms: @@ -622,25 +621,24 @@ Same as L. =item nvalues SECTION, ITEM -Returns number of values in ITEM in SECTION. +Returns the number of values in ITEM in SECTION. =item read FILENAME, %PROFILE -Flushes the old content and opens new file. FILENAME is a text string, -PROFILE is a two-level hash of default values for the new file. PROFILE is -merged with the data from file, and the latter keep the precedence. -Does not return any success values but, warns if any error -is occurred. +Flushes the old content and opens a new file. FILENAME is a text string, PROFILE +is a two-level hash of default values for the new file. PROFILE is merged with +the data from the file, and the latter keeps the precedence. Does not return +any success values but warns if any error is occurred. =item replace_values SECTION, ITEM, @VALUES -Removes all values form ITEM in SECTION and assigns it to the new +Removes all values from ITEM in SECTION and assigns it to the new list of VALUES. =item section SECTION Returns a tied hash for SECTION. All its read and write operations are reflected -in the caller object, which allows the following syntax: +in the caller object which allows the following syntax: my $section = $inifile-> section( 'Sample section'); $section-> {Item1} = 'Value1'; @@ -651,18 +649,19 @@ which is identical to =item sections -Returns array of section names. +Returns an array of section names. =item set_values SECTION, ITEM, @VALUES -Assigns VALUES to ITEM in SECTION. If number of new values are equal or greater -than the number of the old, the method is same as L. Otherwise, +Assigns VALUES to ITEM in SECTION. If the number of new values is equal to or greater +than the number of the old, the method is the same as L. Otherwise, the values with indices higher than the number of new values are not touched. =item write -Rewrites the file with the object content. The object keeps an internal modification flag -under name C<{changed}>; in case it is C, no actual write is performed. +Rewrites the file with the object content. The object keeps an internal +modification flag C<{changed}>; in case it is C, no actual write is +performed. =back diff --git a/Prima/InputLine.pm b/Prima/InputLine.pm index da8af1205..55d7e9f61 100644 --- a/Prima/InputLine.pm +++ b/Prima/InputLine.pm @@ -1214,7 +1214,7 @@ sub blink =head1 NAME -Prima::InputLine - standard input line widget +Prima::InputLine - input line widget =head2 SYNOPSIS @@ -1228,10 +1228,9 @@ Prima::InputLine - standard input line widget =head1 DESCRIPTION -The class provides basic functionality of an input line, -including hidden input, read-only state, selection, and -clipboard operations. The input line text data is -contained in L property. +The class provides the basic functionality of an input line, including hidden +input, read-only state, selection, and clipboard operations. The input line +text data is stored in the L property. =head1 API @@ -1242,12 +1241,12 @@ contained in L property. =item Change The notification is called when the L property is changed, either -interactively or as a result of direct call. +interactively or as a result of a direct call. =item Validate TEXT_REF The notification is called right before the L property is changed, either -interactively or as a result of direct call. The custom code has a chance to +interactively or as a result of a direct call. The custom code has a chance to validate the text and/or provide some sort of interactive feedback. See also: L @@ -1282,24 +1281,22 @@ Default value: 1 =item autoTab BOOLEAN -If 1, the keyboard C and C commands, if received -when the cursor is at the beginning or at the end of text, and cannot be -mover farther, not processed. The result of this is that the default handler -moves focus to a neighbor widget, in a way as if the Tab key -was pressed. +If 1, ignores the keyboard C and C commands, when these +are received when the cursor is at the beginning or the end of text and +cannot be moved farther. The result of this is that the default handler moves +focus to a neighbor widget, in a way as if the Tab key was pressed. Default value: 0 =item borderWidth INTEGER -Width of 3d-shade border around the widget. +Width of the border around the widget. -Default value: 2 +Default value: depends on the skin =item charOffset INTEGER -charOffset gets the current position of the cursor -charOffset N sets the cursor at position N +Managets the current position of the cursor =item firstChar @@ -1307,9 +1304,9 @@ Selects the first visible cluster of text =item insertMode BOOLEAN -Governs the typing mode - if 1, the typed text is inserted, if 0, the text overwrites -the old text. When C is 0, the cursor shape is thick and covers the whole -character; when 1, it is of default width. +Manages the typing mode - if 1, the typed text is inserted, if 0, the 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 width. Default toggle key: Insert @@ -1338,11 +1335,11 @@ clusters. A case with no selection is when START equals END. =item selStart INTEGER -Selects the start of text selection. +Selects the start of the text selection. =item selEnd INTEGER -Selects the end of text selection. +Selects the end of the text selection. =item textDirection BOOLEAN @@ -1351,17 +1348,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 go inside such +clusters, and thus one can only select them, delete them as a whole, or press Del/Backspace on the cluster's edge. Toggle during runtime with Ctrl+Shift+L. =item wordDelimiters STRING -Contains string of character that are used for locating a word break. -Default STRING value consists of punctuation marks, space and tab characters, +Contains the string of characters that are used for locating a word break. +Default STRING value consists of punctuation marks, space, tab, and C<\xff> character. =item writeOnly BOOLEAN @@ -1379,9 +1376,9 @@ Default value: 0 =item blink %options -Produces a short blink by setting background to red color. -Can be used to signal invalid input, f ex from C. -C<%options> allows C and C entries. +Produces a short blink by setting the background to red color. +Can be used to signal an invalid input, f ex from C. +C<%options> allows the C and C entries. =item copy @@ -1416,17 +1413,18 @@ Selects all text =head2 Bi-directional input and output When working on bidirectional texts, or text represented by complex script -shaping, methods C, C, C etc cannot be used -to calculate text offsets f.ex. via C. Note that these values are in -clusters, not in characters (see L for the -description>. Also, selection ranges of bidi text become not straighforward. -Use the following methods whenever text manipulations are needed: +shaping, values returned from the methods C, C, +C, etc cannot be used to calculate text offsets f.ex. via C. +Note that these values are in clusters, not in characters (see +L for the description>. Also, the selection ranges of +bidi text become not straightforward. Use the following methods whenever text +manipulations are needed: =over =item char_at OFFSET -Returns character at OFFSET +Returns character at cluster OFFSET =item selection_strpos diff --git a/Prima/KeySelector.pm b/Prima/KeySelector.pm index de1fab3b5..e757eafaa 100644 --- a/Prima/KeySelector.pm +++ b/Prima/KeySelector.pm @@ -724,12 +724,10 @@ Prima::KeySelector - key combination widget and routines =head1 DESCRIPTION -The module provides a standard widget for selecting a user-defined -key combination. The widget class allows import, export, and modification of -key combinations. - -The module provides a set of routines, useful for conversion of -a key combination between representations. +The module provides a standard widget for selecting user-defined key +combinations. The widget class allows import, export, and modification of key +combinations. The module also provides a set of routines useful for the conversion +of key combinations between various representations. =head1 SYNOPSIS @@ -745,44 +743,40 @@ a key combination between representations. =item key INTEGER -Selects a key combination in integer format. The format is -described in L, and is a combination -of C key modifiers and either a C virtual -key, or a character code value. +Selects a key combination in integer format. The format is described in +L, and is a combination of the C key modifiers and +is either a C virtual key or a character code value. -The property allows almost, but not all possible combinations of -key constants. Only C, C, and C -modifiers are allowed. +The property allows almost, but not all possible combinations of key constants. +Only the C, C, and C modifiers are allowed. =back =head2 Methods -All methods here can ( and must ) be called without the object -syntax; - the first parameter must not be neither package nor -widget. +All methods must be called without the object as a first parameter. =over =item describe KEY -Accepts KEY in integer format, and returns string -description of the key combination in human readable +Accepts KEY in integer format and returns a string +description of the key combination in a human-readable format. Useful for supplying an accelerator text to a menu. - print describe( km::Shift|km::Ctrl|km::F10); + print Prima::KeySelector::describe( km::Shift|km::Ctrl|km::F10); Ctrl+Shift+F10 =item export KEY -Accepts KEY in integer format, and returns string -with a perl-evaluable expression, which after +Accepts KEY in integer format and returns a string +with a perl-evaluable expression, which after the evaluation resolves to the original KEY value. Useful for storing -a key into text config files, where value must be both -human readable and easily passed to a program. +a key into text config files, where the value must be both +human-readable and easily passed to a program. - print export( km::Shift|km::Ctrl|km::F10); + print Prima::KeySelector::export( km::Shift|km::Ctrl|km::F10); km::Shift|km::Ctrl|km::F10 =item shortcut KEY @@ -790,19 +784,18 @@ human readable and easily passed to a program. Converts KEY from integer format to a string, acceptable by C input methods. - print shortcut( km::Ctrl|ord('X')); + print Prima::KeySelector::shortcut( km::Ctrl|ord('X')); ^X =item translate_codes KEY, [ USE_CTRL = 0 ] -Converts KEY in integer format to three integers -in the format accepted by L event: -code, key, and modifier. USE_CTRL is only relevant when -KEY first byte ( C ) is between 1 and 26, what -means that the key is a combination of an alpha key with the control key. -If USE_CTRL is 1, code result is unaltered, and is in range 1 - 26. -Otherwise, code result is converted to the character code -( 1 to ord('A'), 2 to ord('B') etc ). +Converts KEY in integer format to three integers in the format accepted by the +L event: code, key, and modifier. USE_CTRL is only +relevant when the KEY first byte ( C ) is between 1 and 26, which means +that the key is a combination of an alpha key with the control key. If +USE_CTRL is 1, the code result is unaltered and is in range 1 - 26. Otherwise, +the code result is converted to the character code ( 1 to ord('A'), 2 to ord('B'), +etc ). =back diff --git a/Prima/Label.pm b/Prima/Label.pm index d751e83a3..54133f150 100644 --- a/Prima/Label.pm +++ b/Prima/Label.pm @@ -512,12 +512,12 @@ Prima::Label - static text widget =head1 DESCRIPTION -The class is designed for display of text, and assumes no user interaction. The +The class is designed for the display of text and provides no user interaction. The text output capabilities include wrapping, horizontal and vertical alignment, -and automatic widget resizing to match text extension. If text contains a +and automatic widget resizing to match text extensions. If the text contains a tilde-escaped ( hot ) character, the label can explicitly focus the specified -widget upon press of the character key, what feature is useful for dialog -design. +widget upon pressing of the character key; this feature is useful for the design of +dialogs. Labels can display rich text with links. See L for more. @@ -578,35 +578,35 @@ Default value: 1 =item focusLink WIDGET Points to a widget or a widget name (has to be a sibling widget), which is -explicitly focused when the user presses the combination of a hotkey with the +explicitly focused when the user presses the combination of the hotkey with the C key. -Prima::Label does not provide a separate property to access the -hotkey value, however it can be read from the C<{accel}> variable. +Prima::Label does not provide a separate property to access the hotkey value +from the tilde-escaped string, however, it can be read from the C<{accel}> +variable. Default value: C. =item hotKey CHAR -A key (defined by CHAR) that the label will react to if pressed, if the label has the focus -The combination ALT + Key works always if the label has the focus or not +A key (defined by CHAR) that the label will react to if pressed if the label has the focus +The combination ALT + Key works always whether the label has the focus or not =item linkColor COLOR -The color that is used to draw link texts. +The color of text in links. -Default value is taken from L, and is currently hardcoded as green. +The default value is taken from L and is currently hardcoded as green. So far there is no support for the system link color. =item showAccelChar BOOLEAN -If 0, the tilde ( ~ ) character is collapsed from the text, -and the hot character is underlined. When the user presses combination -of the escaped character with the C key, the C -widget is explicitly focused. +If 0, the tilde ( ~ ) character is collapsed from the text, and the hot +character is underlined. When the user presses the combination of the escaped +character with the C key, the C widget is explicitly focused. -If 1, the text is showed as is, and no hot character is underlined. -Key combinations with C key are not recognized. See also: C. +If 1, the text is shown as is, and no hot character is underlined. +Key combinations with the C key are not recognized. See also: C. Default value: 0 @@ -621,16 +621,16 @@ Default value: 1 =item textJustify $BOOL | { letter => 0, word => 0, kashida => 0, min_kashida => 0 } | %VALUES -If set, justifies wrapped text according to the option passwd in the hash +If set, justifies wrapped text according to the option passed in the hash ( see L and L ). Can accept three forms: -If anonymous hash is used, overwrites all the currently defined options. +If an anonymous hash is used, overwrites all the currently defined options. If C<$BOOL> is used, treated as a shortcut for C<< { letter => $BOOL, word => $BOOL, kashida => $BOOL } >>; -consequent get-calls return full hash, not the C<$BOOL>. +consequent get-calls return a full hash, not the C<$BOOL> value. -If C<%VALUES> form is used, overwrites only values found in C<%VALUES>. +If the C<%VALUES> form is used, overwrites only values found in C<%VALUES>. Only actual when C is set. @@ -640,14 +640,11 @@ If set, indicates RTL text direction. =item wordWrap BOOLEAN -If 1, the text is wrapped if it can not be horizontally fit in the -widget interior. - If 0, the text is not wrapped unless new line characters are present in the text. -New line characters signal line wrapping with no respect to C -property value. +If 1, the text is wrapped if it can not be fit horizontally in the +widget interior. The text is also wrapped over new lines. Default value: 0 @@ -661,8 +658,8 @@ One of the following C constants: Selects the vertical text 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 diff --git a/Prima/Lists.pm b/Prima/Lists.pm index 82ab9586a..c280fe9ec 100644 --- a/Prima/Lists.pm +++ b/Prima/Lists.pm @@ -1993,12 +1993,12 @@ sub draw_items =head1 NAME -Prima::Lists - user-selectable item list widgets +Prima::Lists - list widgets =head1 DESCRIPTION -The module provides classes for several abstraction layers -of item representation. The hierarchy of classes is as follows: +The module provides several listbox classes that differ in the way items in the +list widget are associated with data. The hierarchy of classes is as follows: AbstractListViewer AbstractListBox @@ -2006,28 +2006,27 @@ of item representation. The hierarchy of classes is as follows: ProtectedListBox ListBox -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 item list is stored. The simplest -organization of a text-only item list, provided by C, -stores an array of text scalars in a widget. More elaborated storage -and representation types are not realized, and the programmer is urged -to use the more abstract classes to derive own mechanisms. -For example, for a list of items that contain text strings and icons -see L. -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, and C. +The root class C provides a common interface that is +though not usable directly. The main differences between classes are centered +around the way the items are stored. The simplest organization of a text-only +item list, provided by C, stores an array of text scalars in a +widget. 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. For example, for a list of items that contain text strings and +icons see L. 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, and +C. =head1 Prima::AbstractListViewer -C is a descendant of C, -and some properties are not described here. +C is a descendant of +C, and some of its properties are not described +here. -The class provides interface to generic list browsing functionality, -plus functionality for text-oriented lists. The class is not usable directly. +The class provides an interface to generic list browsing functionality, plus +functionality for text-oriented lists. The class is not usable directly. =head2 Properties @@ -2035,23 +2034,23 @@ plus functionality for text-oriented lists. The class is not usable directly. =item autoHeight BOOLEAN -If 1, the item height is changed automatically -when the widget font is changed; this is useful for text items. -If 0, item height is not changed; this is useful for non-text items. +If 1, the item height is changed automatically when the widget font is changed; +this is useful for text items. If 0, the item height is not changed; this is +useful for non-text items. Default value: 1 =item count INTEGER -An integer property, destined to reflect number of items in the list. -Since it is tied to the item storage organization, and hence, -to possibility of changing the number of items, this property -is often declared as read-only in descendants of C. +An integer property, used to access the number of items in the list. Since it +is tied to the item storage organization, and hence the possibility of changing +the number of items, this property is often declared as read-only in +descendants of C. =item dragable BOOLEAN -If 1, allows the items to be dragged interactively by pressing control key -together with left mouse button. If 0, item dragging is disabled. +If 1, allows the items to be dragged interactively by pressing the Control key +together with the left mouse button. If 0, item dragging is disabled. Default value: 1 @@ -2064,53 +2063,51 @@ Default value: 1 =item extendedSelect BOOLEAN -Regards the way the user selects multiple items and is only actual -when C is 1. If 0, the user must click each item -in order to mark as selected. If 1, the user can drag mouse -or use C key plus arrow keys to perform range selection; -the C key can be used to select individual items. +Manages the way the user selects multiple items that is only actual when +C is 1. If 0, the user must click each item to mark it as +selected. If 1, the user can drag the mouse or use the Shift key plus arrow +keys to perform range selection; the Control key can be used to select +individual items. Default value: 0 =item focusedItem INDEX -Selects the focused item index. If -1, no item is focused. -It is mostly a run-time property, however, it can be set -during the widget creation stage given that the item list is -accessible on this stage as well. +Selects the focused item index. If -1, no item is focused. It is mostly a +run-time property, however, it can be set during the widget creation stage +given that the item list is accessible at this stage as well. Default value: -1 =item gridColor COLOR -Color, used for drawing vertical divider lines for multi-column -list widgets. The list classes support also the indirect way -of setting the grid color, as well as widget does, via -the C property. To achieve this, C constant -is declared ( for more detail see L ). +Color used for drawing vertical divider lines for multi-column list widgets. +The list classes support also the indirect way of setting the grid color, as +well as the widget does, via the C property. To achieve this, +the C constant is declared ( for more detail see +L ). Default value: C. =item integralHeight BOOLEAN -If 1, only the items that fit vertically in the widget interiors -are drawn. If 0, the items that are partially visible are drawn also. +If 1, only the items that fit vertically in the widget interiors are drawn. If +0, the partially visible items are drawn also. Default value: 0 =item integralWidth BOOLEAN -If 1, only the items that fit horizontally in the widget interiors -are drawn. If 0, the items that are partially visible are drawn also. -Actual only in multi-column mode. +If 1, only the items that fit horizontally in the widget interiors are drawn. +If 0, the partially visible items are drawn also. Actual only in +the multi-column mode. Default value: 0 - =item itemHeight INTEGER Selects the height of the items in pixels. Since the list classes do -not support items with different dimensions, changes to this property +not support items with variable heights, changes to this property affect all items. Default value: default font height @@ -2118,7 +2115,7 @@ Default value: default font height =item itemWidth INTEGER Selects the width of the items in pixels. Since the list classes do -not support items with different dimensions, changes to this property +not support items with variable widths, changes to this property affect all items. Default value: default widget width @@ -2127,16 +2124,16 @@ Default value: default widget width If 0, the user can only select one item, and it is reported by the C property. If 1, the user can select more than one item. -In this case, C'th item is not necessarily selected. -To access selected item list, use C property. +In this case, the C'th item is not necessarily selected. +To access the selected item list use the C property. Default value: 0 =item multiColumn BOOLEAN -If 0, the items are arrayed vertically in one column, and the main scroll bar -is vertical. If 1, the items are arrayed in several columns, C -pixels wide each. In this case, the main scroll bar is horizontal. +If 0, the items are arranged vertically in a single column and the main scroll +bar is vertical. If 1, the items are arranged in several columns, each +C pixels wide. In this case, the main scroll bar is horizontal. =item offset INTEGER @@ -2148,7 +2145,7 @@ Selects the first item drawn. =item selectedCount INTEGER -A read-only property. Returns number of selected items. +A read-only property. Returns the number of selected items. =item selectedItems ARRAY @@ -2156,7 +2153,7 @@ ARRAY is an array of integer indices of selected items. =item vertical BOOLEAN -Sets general direction of items in multi-column mode. If 1, items increase +Sets the general direction of items in multi-column mode. If 1, items increase down-to-right. Otherwise, right-to-down. Doesn't have any effect in single-column mode. @@ -2171,124 +2168,121 @@ Default value: 1. =item add_selection ARRAY, FLAG Sets item indices from ARRAY in selected -or deselected state, depending on FLAG value, correspondingly 1 or 0. +or deselected state, depending on the FLAG value, correspondingly 1 or 0. -Only for multi-select mode. +Only for the multi-select mode. =item deselect_all -Removes selection from all items. +Clears the selection -Only for multi-select mode. +Only for the multi-select mode. =item draw_items CANVAS, ITEM_DRAW_DATA -Called from within C notification to draw items. The default behavior is -to call C notification for every item in ITEM_DRAW_DATA array. -ITEM_DRAW_DATA is an array or arrays, where each array consists of parameters, -passed to C notification. +Called from within the C notification to draw items. The default +behavior is to call the C notification for every item in the +ITEM_DRAW_DATA array. ITEM_DRAW_DATA is an array or arrays, where each array +consists of parameters passed to the C notification. -This method is overridden in some descendant classes, to increase the speed of -drawing routine. For example, C is the optimized routine -for drawing unified text-based items. It is used in C class. +This method is overridden in some descendant classes to increase the speed of +drawing. For example, C is the optimized routine for +drawing text-based items. It is used in the C class. -See L for parameters description. +See L for the description of the parameters. =item draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT -Called by C to draw sequence of text items with -indices from FIRST to LAST, by STEP, on CANVAS, starting at point X, Y, and -incrementing the vertical position with OFFSET. CLIP_RECT is a reference -to array of four integers with inclusive-inclusive coordinates of the active -clipping rectangle. +Called by C to draw a sequence of text items with indices +from FIRST to LAST, by STEP, on CANVAS, starting at point X, Y, and +incrementing the vertical position with OFFSET. CLIP_RECT is a reference to an +array of four integers given in the inclusive-inclusive coordinates that +represent the active clipping rectangle. Note that OFFSET must be an integer, otherwise bad effects will be observed when text is drawn below Y=0 =item get_item_text INDEX -Returns text string assigned to INDEXth item. +Returns the text string assigned to the INDEXth item. 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_item_width INDEX -Returns width in pixels of INDEXth item. +Returns width in pixels of the INDEXth item. Since the class does not assume the item storage organization, -the value is queried via C notification. +the value is queried via the C notification. =item is_selected INDEX -Returns 1 if INDEXth item is selected, 0 if it is not. +Returns 1 if the INDEXth item is selected, 0 otherwise. =item item2rect INDEX, [ WIDTH, HEIGHT ] -Calculates and returns four integers with rectangle coordinates -of INDEXth item within the widget. WIDTH and HEIGHT are optional -parameters with pre-fetched dimension of the widget; if not set, -the dimensions are queried by calling C property. If set, however, -the C property is not called, thus some speed-up can be achieved. +Calculates and returns four integers with rectangle coordinates of the INDEXth +item. WIDTH and HEIGHT are optional parameters with pre-fetched dimensions of +the widget; if not set, the dimensions are queried by calling the C +property. If set, however, the C property is not called, thus some +speed-up can be achieved. =item point2item X, Y -Returns the index of an item that contains point (X,Y). If the point +Returns the index of an item that contains the point at (X,Y). If the point belongs to the item outside the widget's interior, returns the index of the first item outside the widget's interior in the direction of the point. =item redraw_items INDICES -Redraws all items in INDICES array. +Redraws all items in the INDICES array. =item select_all Selects all items. -Only for multi-select mode. +Only for the multi-select mode. =item set_item_selected INDEX, FLAG -Sets selection flag of INDEXth item. +Sets the selection flag on the INDEXth item. If FLAG is 1, the item is selected. If 0, it is deselected. -Only for multi-select mode. +Only for the multi-select mode. =item select_item INDEX -Selects INDEXth item. +Selects the INDEXth item. -Only for multi-select mode. +Only for the multi-select mode. =item std_draw_text_items CANVAS, ITEM_DRAW_DATA -An optimized method, draws unified text-based items. -It is fully compatible to C interface, -and is used in C class. +An optimized method, draws text-based items. It is fully compatible with the +C interface and is used in the C class. -The optimization is derived from the assumption that items -maintain common background and foreground colors, that differ -in selected and non-selected states only. The routine groups -drawing requests for selected and non-selected items, and -draws items with reduced number of calls to C property. -While the background is drawn by the routine itself, the foreground -( usually text ) is delegated to the C method, so -the text positioning and eventual decorations would not require -full rewrite of code. +The optimization is derived from the assumption that items maintain common +background and foreground colors, that only differ in the selected and +non-selected states. The routine groups drawing requests for selected and +non-selected items, and then draws items with a reduced number of calls to the +C property. While the background is drawn by the routine itself, the +foreground ( usually text ) is delegated to the C method, so +that the text positioning and eventual decorations would be easier to implement. -ITEM_DRAW_DATA is an array of arrays of scalars, where each array -contains parameters of C notification. -See L for parameters description. +ITEM_DRAW_DATA is an array of arrays of scalars, where each array contains +parameters of the C notification. See L for the +description of the parameters. =item toggle_item INDEX -Toggles selection of INDEXth item. +Toggles selection of the INDEXth item. -Only for multi-select mode. +Only for the multi-select mode. =item unselect_item INDEX -Deselects INDEXth item. +Deselects the INDEXth item. -Only for multi-select mode. +Only for the multi-select mode. =back @@ -2298,57 +2292,57 @@ Only for multi-select mode. =item Click -Called when the user presses return key or double-clicks on +Called when the user presses the return key or double-clicks on an item. The index of the item is stored in C. =item DragItem OLD_INDEX, NEW_INDEX Called when the user finishes the drag of an item from OLD_INDEX to NEW_INDEX position. The default action -rearranges the item list in accord with the dragging action. +rearranges the item list according to the dragging action. =item DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT, COLUMN -Called when an INDEXth item is to be drawn on CANVAS. -X1, Y1, X2, Y2 designate the item rectangle in widget coordinates, -where the item is to be drawn. SELECTED, FOCUSED, and PRELIGHT are boolean -flags, if the item must be drawn correspondingly in selected and -focused states, with or without the prelight effect. +Called when the INDEXth item is to be drawn on CANVAS. X1, Y1, X2, Y2 define +the item rectangle in widget coordinates where the item is to be drawn. +SELECTED, FOCUSED, and PRELIGHT are boolean flags, if the item must be drawn +correspondingly in selected and focused states, with or without the prelight +effect. =item MeasureItem INDEX, REF -Puts width in pixels of INDEXth item into REF +Stores width in pixels of the INDEXth item into the REF scalar reference. This notification must be called -from within C block. +from within the C block. =item SelectItem INDEX, FLAG -Called when the item changed its selection state. +Called when an item changes its selection state. INDEX is the index of the item, FLAG is its new selection state: 1 if it is selected, 0 if it is not. =item Stringify INDEX, TEXT_REF -Puts text string, assigned to INDEXth item into TEXT_REF +Stores the text string associated with the INDEXth item into TEXT_REF scalar reference. =back =head1 Prima::AbstractListBox -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 +the propagate C message, assuming that all items must be drawn as +text strings. =head1 Prima::ListViewer -The class implements items storage mechanism, but leaves -the items format to the programmer. The items are accessible via +The class implements an item storage mechanism but leaves the definition of +the format of the item to the programmer. The items are accessible via the C property and several other helper routines. -The class also defines the user navigation, by accepting character +The class also defines user navigation by accepting character keyboard input and jumping to the items that have text assigned -with the first letter that match the input. +with the first letter that matches the input. C is derived from C. @@ -2358,18 +2352,18 @@ C is derived from C. =item autoWidth BOOLEAN -Selects if the gross item width must be recalculated automatically -when either the font changes or item list is changed. +Selects if the item width must be recalculated automatically +when either the font or item list is changed. Default value: 1 =item count INTEGER -A read-only property; returns number of items. +A read-only property; returns the number of items. =item items ARRAY -Accesses the storage array of items. The format of items is not +Accesses the storage array of the items. The format of items is not defined, it is merely treated as one scalar per index. =back @@ -2380,64 +2374,62 @@ defined, it is merely treated as one scalar per index. =item add_items ITEMS -Appends array of ITEMS to the end of the list. +Appends an array of ITEMS to the end of the item list. =item calibrate -Recalculates all item widths and adjusts C if +Recalculates all item widths. Adjusts C if C is set. =item delete_items INDICES -Deletes items from the list. INDICES can be either an array, +Deletes items from the list. INDICES can be either an array or a reference to an array of item indices. =item get_item_width INDEX -Returns width in pixels of INDEXth item from internal cache. +Returns the width in pixels of the INDEXth item from the internal cache. =item get_items INDICES -Returns array of items. INDICES can be either an array, or a reference to an +Returns an array of items. INDICES can be either an array or a reference to an array of item indices. Depending on the caller context, the results are -different: in array context the item list is returned; in scalar - only the -first item from the list. The semantic of the last call is naturally usable -only for single item retrieval. +different: in the array context the item list is returned; in scalar - only the +first item from the list. =item insert_items OFFSET, ITEMS -Inserts array of items at OFFSET index in the list. Offset must be a valid -index; to insert items at the end of the list use C method. +Inserts an array of items at the OFFSET index in the list. Offset must be a valid +index; to insert items at the end of the list use the C method. -ITEMS can be either an array, or a reference to an array of items. +ITEMS can be either an array or a reference to an array of items. =item replace_items OFFSET, ITEMS -Replaces existing items at OFFSET index in the list. Offset must be a valid -index. +Replaces existing items at the OFFSET index in the list. The offset must be a +valid index. -ITEMS can be either an array, or a reference to an array of items. +ITEMS can be either an array or a reference to an array of items. =back =head1 Prima::ProtectedListBox -A semi-demonstrational class, derived from C, -that applies certain protection for every item drawing session. -Assuming that several item drawing routines can be assembled in one -widget, C provides a safety layer between -these, so, for example, one drawing routine that selects a font -or a color and does not care to restore the old value back, -does not affect the outlook of the other items. +A semi-demonstrational class derived from C, implements +certain protections for every item during drawing. Assuming that several item +drawing algorithms can be used in the same widget, C +provides a safety layer between these. If an algorithm selects a font or a +color and does not restore the old value, this does not affect the outlook of +other items. -This functionality is implementing by overloading C +This functionality is implemented by overloading the C method and also all graphic properties. =head1 Prima::ListBox -Descendant of C, declares format of items -as a single text string. Incorporating all of functionality of -its predecessors, provides a standard listbox widget. +Descendant of C, declares that an item must be a single +text string. Incorporating all the functionality of its predecessors, provides +the standard workhorse listbox widget. =head2 Synopsis @@ -2455,9 +2447,9 @@ its predecessors, provides a standard listbox widget. =item get_item_text INDEX -Returns text string assigned to INDEXth item. +Returns the text string associated with the INDEXth item. Since the item storage organization is implemented, does -so without calling C notification. +so without calling the C notification. =back diff --git a/pod/Prima/Menu.pod b/pod/Prima/Menu.pod index 989e42be1..d59a62157 100644 --- a/pod/Prima/Menu.pod +++ b/pod/Prima/Menu.pod @@ -158,7 +158,7 @@ Note: there is the C function which converts an integer key value to a string in the human-readable format, perfectly usable as accelerator text. -=item hotkey +=item Hotkey An integer value, is a combination of either a C constant or a character index with the modifier key values ( C constant ). This format is