diff --git a/Prima.pm b/Prima.pm index bfedb8115..8b2efa13c 100644 --- a/Prima.pm +++ b/Prima.pm @@ -494,7 +494,7 @@ L - auto-repeating mouse events L - simple panel widget -L - draw rubberbands +L - dynamic rubberbands L - scrollable generic document widget diff --git a/Prima/Widget/BidiInput.pm b/Prima/Widget/BidiInput.pm index 2e040dcd4..c79139cc6 100644 --- a/Prima/Widget/BidiInput.pm +++ b/Prima/Widget/BidiInput.pm @@ -58,13 +58,15 @@ sub handle_bidi_input 1; +=pod + =head1 NAME Prima::Widget::BidiInput - heuristics for i18n input =head1 DESCRIPTION -Provides the common functionality for the bidirectional input to be used in +Provides common functionality for the bidirectional input to be used in editable widgets =head1 Methods @@ -73,7 +75,7 @@ editable widgets =item handle_bidi_input %OPTIONS -Given C and C in C<%OPTIONS>, returns new text and suggested new cursor position. +Given C and C in C<%OPTIONS>, returns new text and a suggested cursor position. The following options are understood: @@ -85,7 +87,7 @@ One of: backspace, delete, cut, insert, overtype =item at INTEGER -Current cursor position in clusters +Current cursor position, calculated in clusters =item glyphs Prima::Drawable::Glyphs object @@ -93,15 +95,15 @@ Shaped text =item n_clusters INTEGER -Amount of clusters in the text +The number of clusters in the text =item rtl BOOLEAN -Is widget or currently selected method is RTL (right-to-left) +Set to 1 if the default input direction is RTL (right-to-left) =item text STRING -A text to edit +The text to edit =back diff --git a/Prima/Widget/Date.pm b/Prima/Widget/Date.pm index 772865700..456f55e71 100644 --- a/Prima/Widget/Date.pm +++ b/Prima/Widget/Date.pm @@ -354,7 +354,7 @@ sub List_Leave {} # don't mix up with the explicit focus by .on_show =head1 NAME -Prima::Widget::Date - date picker widget +Prima::Widget::Date - standard date picker widget =head1 SYNOPSIS @@ -373,7 +373,7 @@ Prima::Widget::Date - date picker widget =head1 DESCRIPTION -Standard date picker +Standard date picker widget, derived from the C class. =head1 API @@ -383,19 +383,20 @@ Standard date picker =item date2str DATE -Converts DATE to string representation according to the current C string +Converts the DATE to a string representation according to the current C string =item default_format -Returns a string to be used in C, where the string is constructed in such a way -to reflect regional date formatting preferences. +Returns a string to be used in C where the string is constructed +to reflect the formatting of the regional date preferences. See also: C . =item str2date STRING -Tries to extract date from STRING assuming it is constructed according to the current C string. -Doesn't fail but values that could not be extracted are assigned to today's day/month/year instead. +Tries to extract the date from the STRING, assuming it is constructed according +to the current C string. Doesn't fail but values that could not be +extracted are assigned to today's day/month/year instead. =item today @@ -403,8 +404,8 @@ Returns today's date in widgets [D,M,Y] format =item validate_date D, M, Y -Checks whether D, M, Y values are valid and within understood range; adjusts the values if not. -Returns the final values. +Checks if D, M, Y form a valid date, and adjusts the values if not. Returns +the corrected values. =back @@ -414,21 +415,21 @@ Returns the final values. =item date DAY, MONTH, YEAR | [ DAY, MONTH, YEAR ] -Accepts three integers / arrayref with three integers in format of C. +Accepts three integers / arrayref with three integers in the format of C. DAY can be from 1 to 31, MONTH from 0 to 11, YEAR from 0 to 199. Default value: today's date. =item day INTEGER -Selects the day in month. +Selects the day of the month. =item format STRING -The format string is used when converting date to its visual interpretation, -also with regional preferences, like YYYY-MM-DD or DD/MM/YY. The syntax of the -format is exctly this, it recognizes fixed patterns YYYY, YY, MM, and DD, -replacing them with the date values. +The format string is used when converting the date to its visual interpretation, +also with regional preferences, f ex YYYY-MM-DD or DD/MM/YY. The syntax of the +format is verbatim as this, i e it recognizes fixed patterns YYYY, YY, MM, and +DD, replacing them with the date values. =item month diff --git a/Prima/Widget/Fader.pm b/Prima/Widget/Fader.pm index 470303c8d..f6fda2053 100644 --- a/Prima/Widget/Fader.pm +++ b/Prima/Widget/Fader.pm @@ -266,13 +266,15 @@ sub fader_set_blended_color 1; +=pod + =head1 NAME -Prima::Widget::Fader +Prima::Widget::Fader - fading- in/out functions =head1 DESCRIPTION -Fading- in/out functions +The role implements fading effects in widgets =head1 SYNOPSIS @@ -316,12 +318,12 @@ Initiates a fade-out transition, calls repaint on each step. =item fader_current_value Returns the current fader value in the range from 0 to 1. -Returns C if there is no current fading transition running +Returns C if there is no current fading transition in effect =item fader_prelight_color $COLOR [, $MULTIPLIER ] Given a base C<$COLOR>, increases (or decreases) its brightness according to -C, and an eventual C<$MULTIPLIER> that is expected to be in +C and an eventual C<$MULTIPLIER> that is expected to be in the range from 0 to 1. =back @@ -332,12 +334,12 @@ the range from 0 to 1. =item FadeIn $ENDS_OK -Called when C is finished the fading, the C<$ENDS_OK> flag +Called when C finishes the fading, the C<$ENDS_OK> flag is set to 0 if the process was overridden by another fader call, 1 otherwise. =item FadeOut $ENDS_OK -Called when C is finished the fading, the C<$ENDS_OK> flag +Called when C finishes the fading, the C<$ENDS_OK> flag is set to 0 if the process was overridden by another fader call, 1 otherwise. =item FadeRepaint diff --git a/Prima/Widget/GroupScroller.pm b/Prima/Widget/GroupScroller.pm index 30d113836..a1d80f578 100644 --- a/Prima/Widget/GroupScroller.pm +++ b/Prima/Widget/GroupScroller.pm @@ -306,34 +306,32 @@ Prima::Widget::GroupScroller - optional automatic scroll bars =head1 DESCRIPTION -The class is used for widgets that contain optional scroll bars, and provides means for -their maintenance. The class is the descendant of L, and adjusts -the L property when scrollbars are shown or hidden, or L is changed. +The class is used for widgets that contain optional scroll bars and provides means for +their management. The class is the descendant of L and adjusts +its L property when scrollbars are shown, hidden, or L is changed. -The class does not provide range selection for the scrollbars; the descentant classes +The class does not provide range selection for the scrollbars; the descendant classes must implement that. -The descendant classes must follow the guidelines: +The descendant classes must follow the following guidelines: =over =item * -A class must provide C, C, and C property keys in profile_default() . -A class may provide C and C property keys in profile_default() . +A class may provide C, C, C, C, and +C property keys in profile_default() . =item * -A class' init() method must set C<{borderWidth}>, C<{hScroll}>, and C<{vScroll}> -variables to 0 before the initialization, call C method, -and then assign the properties from the object profile. +A class' init() method must call the C method -If a class provides C and C properties, these must be set to +If a class overrides the C and C properties, these must be set to 0 before the initialization. =item * -If a class needs to overload one of C, C, C, +If a class needs to overload one of the C, C, C, C, and C properties, it is mandatory to call the inherited properties. @@ -391,9 +389,9 @@ depending on the widget layout. =item borderWidth INTEGER -Width of 3d-shade border around the widget. +Width of the border around the widget. -Recommended default value: 2 +Depends on the C property. =item hScroll BOOLEAN @@ -407,11 +405,11 @@ points to it. =item scrollBarClass STRING = Prima::ScrollBar -Create-only property that allows to change scrollbar class +A create-only property that allows to change the scrollbar class =item hScrollBarProfile, vScrollBarProfile HASH -Create-only property that allows to change scrollbar parameters when it is being created +Create-only properties that allows to adjust the scrollbar parameters when the scrollbars are created =back @@ -421,18 +419,18 @@ Create-only property that allows to change scrollbar parameters when it is being =item setup_indents -The method is never called directly; it should be called whenever widget -layout is changed so that indents are affected. The method is a request -to recalculate indents, depending on the widget layout. +The method is never called directly; it should be called whenever the widget +layout is changed so that its indents are affected. The method is a request +to recalculate indents, depending on the new widget layout. The method is not reentrant; to receive this callback and update the widget -layout, that in turn can result in more C calls, overload +layout that in turn can result in more C calls, overload C . =item reset_indents -Called after C is called and internal widget layout is updated, -to give a chance to follow-up the layout changes. +Called after C updates the internal widget layout, to give a +chance to follow up the layout changes. Does not do anything by default. =back diff --git a/Prima/Widget/Header.pm b/Prima/Widget/Header.pm index f03412139..1540bd777 100644 --- a/Prima/Widget/Header.pm +++ b/Prima/Widget/Header.pm @@ -586,6 +586,8 @@ sub pressed 1; +=pod + =head1 NAME Prima::Widget::Header - multi-column header widget @@ -594,7 +596,7 @@ Prima::Widget::Header - multi-column header widget The widget class provides functionality of several button-like caption tabs, that can be moved and resized by the user. -The class was implemented with a view to serve as a table header +The class was implemented to serve as a table header for list and grid widgets. =head1 API @@ -605,36 +607,35 @@ for list and grid widgets. =item Click INDEX -Called when the user clicks on the tab, positioned at INDEX. +Called when the user clicks on the tab positioned at INDEX. =item DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, TEXT_BASELINE -A callback used to draw the tabs. CANVAS is the output object; -INDEX is the index of a tab. -X1,Y2,X2,Y2 are the coordinates of the boundaries of the tab rectangle; -TEXT_BASELINE is a pre-calculated vertical position for eventual -centered text output. +A callback to draw the tabs. CANVAS is the output object; INDEX is the index of +a tab. X1,Y2,X2,Y2 are the coordinates of the boundaries of the tab rectangle; +TEXT_BASELINE is a pre-calculated vertical position for eventual centered text +output. =item MeasureItem INDEX, RESULT -Stores in scalar, referenced by RESULT, the width or height ( depending -on L property value ) of the tab in pixels. +Stores in scalar referenced by RESULT the width or height ( depending +on the L property value ) of the INDEXth tab, in pixels. =item MoveItem OLD_INDEX, NEW_INDEX Called when the user moves a tab from its old location, specified by OLD_INDEX, -to the NEW_INDEX position. By the time of call, all internal structures are +to the NEW_INDEX position. By the time of the call, all internal structures are updated. =item SizeItem INDEX, OLD_EXTENT, NEW_EXTENT -Called when the user resizes a tab in INDEX position. OLD_EXTENT and NEW_EXTENT -are either width or height of the tab, depending on L property value. +Called when the user resizes a tab in the INDEXth position. OLD_EXTENT and NEW_EXTENT +are either the width or height of the tab, depending on the L property value. =item SizeItems -Called when more than one tab has changed its extent. This might happen as a result -of user action, as well as an effect of set-calling to some properties. +Called when more than one tab changes its extent. This might happen as a result +of both user and programmatic actions. =back @@ -650,14 +651,14 @@ Default value: 1 =item dragable BOOLEAN -Selects if the user is allowed to move of the tabs. +Selects if the user is allowed to move the tabs. Default value: 1 =item items ARRAY -Array of scalars, representing the internal data of the tabs. -By default the scalars are treated as text strings. +An array of scalars representing the internal data of the tabs. +By default, the scalars are treated as text strings. =item minTabWidth INTEGER @@ -667,7 +668,7 @@ Default value: 2 =item offset INTEGER -An offset on the major axis ( depends on L property value ) +An offset on the major axis ( depends on the L property value ) that the widget is drawn with. Used for the conjunction with list widgets ( see L ), when the list is horizontally or vertically scrolled. @@ -690,8 +691,8 @@ Default value: 1 =item vertical BOOLEAN If 1, the tabs are aligned vertically; -the L, L property and extent parameters of the callback -notification assume heights of the tabs. +the L, L property, and extent parameters of the callback +notification assume the heights of the tabs. If 0, the tabs are aligned horizontally, and the extent properties and parameters assume tab widths. @@ -709,12 +710,12 @@ The extents are widths ( C is 0 ) or heights ( C is 1 ). =item tab2offset INDEX -Returns offset of the INDEXth tab ( without regard to L property value ). +Returns the offset of the INDEXth tab ( without regard to the L property value ). =item tab2rect INDEX -Returns four integers, representing the rectangle area, occupied by -the INDEXth tab ( without regard to L property value ). +Returns four integers representing the rectangle area occupied by +the INDEXth tab ( without regard to the L property value ). =back diff --git a/Prima/Widget/IntIndents.pm b/Prima/Widget/IntIndents.pm index 70dd02f0e..28e8b2d11 100644 --- a/Prima/Widget/IntIndents.pm +++ b/Prima/Widget/IntIndents.pm @@ -33,15 +33,17 @@ sub get_active_area 1; +=pod + =head1 NAME Prima::Widget::IntIndents - indenting support =head1 DESCRIPTION -Provides the common functionality for the widgets that delegate part of their -surface to the border elements. A list box can be of an example, where its -scroll bars and 3-d borders are such elements. +Provides common functionality for the widgets that delegate part of their +surface to border elements. For example, scroll bars and borders in a list box +are such elements. =head1 Properties @@ -49,12 +51,12 @@ scroll bars and 3-d borders are such elements. =item indents ARRAY -Contains four integers, specifying the breadth of decoration elements for -each side. The first integer is width of the left element, the second - height -of the lower element, the third - width of the right element, the fourth - height -of the upper element. +Contains four integers specifying the breadth of decoration elements for each +side. The first integer is the width of the left element, the second is the height +of the lower element, the third is the width of the right element, and the fourth is +the height of the upper element. -The property can accept and return the array either as a four scalars, or as +The property can accept and return the array either as four scalars, or as an anonymous array of four scalars. =back @@ -66,10 +68,10 @@ an anonymous array of four scalars. =item get_active_area [ TYPE = 0, WIDTH, HEIGHT ] Calculates and returns the extension of the area without the border elements, -or the active area. -The extension are related to the current size of a widget, however, can be +or the I. +The extension is related to the current size of a widget, however, can be overridden by specifying WIDTH and HEIGHT. TYPE is an integer, indicating -the type of calculation: +the requested type of calculation: =over diff --git a/Prima/Widget/Link.pm b/Prima/Widget/Link.pm index 977ce882b..c94db5d58 100644 --- a/Prima/Widget/Link.pm +++ b/Prima/Widget/Link.pm @@ -306,17 +306,20 @@ sub reset_positions_markup 1; +=pod + =head1 NAME Prima::Widget::Link - routines for interactive links =head1 DESCRIPTION -The class can be used in widgets that need to feature links, i e a highlighted -rectangle, usually of text. When the user moves mouse or click on a link, -depending on the link type, various action can be executed. A "tooltip" link -type can display a hint with (rich) text, and a "hyperlink" link can open a -browser or pod viewer. The programmer can also customize these actions. +The class can be used in widgets that need to feature I, i e highlighted +rectangles, usually with a line of text. When the user moves the mouse or clicks on +a link, depending on the link type, various actions can be executed. A +"tooltip" link can display a hint with (rich) text, and a "hyperlink" link can +open a browser or a pod viewer. The programmer can also customize these +actions. =head1 SYNOPSIS @@ -346,27 +349,28 @@ browser or pod viewer. The programmer can also customize these actions. =head1 Link types -Link types can be set with the I syntax. There are four recognized link types that behave differently. +Link types can be set with the I syntax. Four recognized link +types behave differently =head2 Tooltips -These are not really links in the strict sense, as clicking on them doesn't cause any action, -however when the user hovers mouse over a tooltip, the module loads the pod content from the url, -and displays it as a hint. +These are not links in the strict sense, as clicking on them doesn't +cause any action, however when the user hovers the mouse over a tooltip, the module +loads the pod content from the URL and displays it as a hint. -The idea behind this feature is to collect all tootip cards in a pod section, and referencing them -in a text like in the example code in L above. +The idea behind this feature is to collect all tooltip cards in a pod section and reference them +in the text like in the example code in L above. Syntax: C<< LEtip://FILEPATH_OR_MODULE/SECTIONE >> or C<< LEtip://FILEPATH_OR_MODULEE >> where C can refer either to a file (path with slashes/backslashes) or a perl module (with C<::>s ). -Tooltip text, when selected, is underscored by a dashed line, vs all other link types that -draw solid line. +The tooltip text, when selected, is underscored by a dashed line, vs all other link types that +use a solid line. =head2 Pod sections -These links both diplay a pod section preview, like the toolkip, but also open a pod viewer +These links display a pod section preview like the tooltip but also open a pod viewer with the referred section when clicked on. Syntax: C<< LEpod://FILEPATH_OR_MODULE/SECTIONE >> or @@ -379,28 +383,32 @@ Links with schemes C, C, and C open a browser when cl =head2 Custom links -All other urls, not matched by either scheme above, are expected to be handled programmatically. -The preview, if any is handled by the C event, and click by C event. +All other URLs, not matched by either scheme above, are expected to be handled +programmatically. The preview, if any, should be handled by the C +event, and the mouse click by the C event. See L below. =head1 Usage Since C is not a widget by itself but a collection of routines in a class, -an object of such class should be instantiated programmatically and attached to a widget -that needs to display links, an I widget. +an object of such class should be instantiated programmatically and attached to an I widget +that needs to display links. -The owner needs to call mouse and paint methods from inside its C etc relevant events. -The owner might also want to overload link events, see below. +The owner widget needs to call the mouse and paint methods from inside its +C etc relevant events. The owner widget class might also want to +overload link events, see below how. =head1 Markup -L understands the C<< LE..|..E >> command, which is, unlike perlpod, is formatted -with its arguments reversed, to stay consistent with the other markup commands (i e it is C<< LEhttp://google.com|searchE >>, +L understands the C<< LE..|..E >> command, +which, unlike perlpod, is formatted with its arguments reversed, to stay +consistent with the other markup commands +(i e it is C<< LEhttp://google.com|searchE >>, not C<< LEsearch|http://google.comE >> . -The simple way to incorporate rich text in both widget and link handler is to -use C to handle the markup parsing, and use the +The simple way to incorporate rich text in both the widget and link handler is to +use C to handle the markup parsing and use the resulting object from the same class both for widget drawing and for the link reactions. One just needs to add C< markup => $markup_object > to C< Prima::Widget::Link->new() >. @@ -413,7 +421,7 @@ Prima::Widget::Link->new() >. =item rectangles -Contains array of rectangles in arbitrary coordinates that could be used to map screen coordinates to a url. +Contains an array of rectangles in arbitrary coordinates that could be used to map screen coordinates to a URL. Filled automatically. =item references @@ -428,10 +436,10 @@ An array of URLs =item add_positions_from_blocks LINK_ID, BLOCKS, %DEFAULTS -To be used when the link object is not bound to a markup object and link -rectangle recalculation is needed due to formatting change, f ex widget size, -font size etc. C<%DEFAULTS> is sent internally to C that might -need eventual default parameters. +Used when the link object is not bound to any markup object but recalculation +of the visual rectangle that the link occupies is needed due to change in +formatting, f ex after a change in widget size, font size, etc. C<%DEFAULTS> is +sent internally to C which may need eventual default parameters. Scans BLOCKS and add monotonically increasing LINK_ID to new link rectangles. Return new LINK_ID. @@ -442,8 +450,8 @@ Clears the content of C =item id2rectangles ID -Returns rectangles mapped to a link id. There can be more than 1 rectangle bound -to a single link ID since link text could be, f ex, wrapped. +Returns rectangles mapped to a link ID. There can be more than 1 rectangle bound +to a single link ID since link text could be f ex wrapped. =item open_podview URL @@ -455,34 +463,35 @@ Opens a web browser with the URL =item reset_positions_markup BLOCKS, %DEFAULTS -To be used when the link object is bound to a markup object and link rectangle recalculation -is needed due to formatting change, f ex widget size, font size etc. C<%DEFAULTS> is sent -internally to C that might need eventual default parameters. +Used when the link object is bound to a markup object and recalculation of the +visual rectangle that the link occupies is needed due to change in formatting, +f ex after a change in widget size, font size, etc. C<%DEFAULTS> is sent +internally to C which may need eventual default parameters. =back =head2 Events -All events are send to the owner, not to the link object itself, however the -C parameter is sent and contains the link object. +All events are sent to the owner, not to the link object itself, however, the +C parameter which contains the link object is always the first parameter =over =item Link SELF, URL, BUTTON, MOD -Send to the owner, if any, from within C event, to indicate that -a link as pressed on. +Sent to the owner, if any, from within the C event to indicate that +the link was pressed on. =item LinkPreview SELF, URL_REF -Send to the owner, if any, from within C event. -The owner might want to fill URL_REF with (rich) text that will be displayed as -a link preview +Sent to the owner, if any, from within the C event. The owner +may want to fill URL_REF with (rich) text that will be displayed as a link +preview =item LinkAdjustRect SELF, RECT_REF -Since the owner might implement a scrollable view, or any other view that has a -coordinate system that is no necessary consistent with the rectangles stored in +Since the owner may implement a scrollable view or any other view that has a +coordinate system that is not necessarily consistent with the rectangles stored in the link object, this event will be called when a link rectangle needs to be mapped to the owner coordinates. diff --git a/Prima/Widget/ListBoxUtils.pm b/Prima/Widget/ListBoxUtils.pm index 2b582b357..36c00d7ac 100644 --- a/Prima/Widget/ListBoxUtils.pm +++ b/Prima/Widget/ListBoxUtils.pm @@ -37,7 +37,7 @@ Prima::Widget::ListBoxUtils - common paint routine for listboxes =head1 DESCRIPTION -To be used by list-like widgets +Used internally by list-like widgets =head1 AUTHOR diff --git a/Prima/Widget/Panel.pm b/Prima/Widget/Panel.pm index b18c6fad8..08a8c31ba 100644 --- a/Prima/Widget/Panel.pm +++ b/Prima/Widget/Panel.pm @@ -155,9 +155,9 @@ sub raise {($#_)?$_[0]-> set_raise($_[1]):return $_[0]-> {raise}} Prima::Widget::Panel - simple panel widget -Provides a simple panel widget, capable of displaying a single line +Provides a simple panel widget capable of displaying a single line of centered text on a custom background. Probably this functionality -is better to be merged into C's. +is better to be merged with C. =head1 Properties @@ -171,24 +171,24 @@ Default value: 1 =item image OBJECT -Selects image to be drawn as a tiled background. -If C, the background is drawn with the background color. +Selects the image to be drawn as a tiled background. +If C the background is drawn with the background color. =item imageFile PATH -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 the success flag. =item raise BOOLEAN -Style of 3d-shade border around the widget. +The style of the 3d-shade border around the widget. If 1, the widget is 'risen'; if 0 it is 'sunken'. Default value: 1 =item zoom INTEGER -Selects zoom level for image display. +Selects the zoom level for the image display. The acceptable value range is between 1 and 10. Default value: 1 diff --git a/Prima/Widget/RubberBand.pm b/Prima/Widget/RubberBand.pm index 440a93c10..8c7ed2c53 100644 --- a/Prima/Widget/RubberBand.pm +++ b/Prima/Widget/RubberBand.pm @@ -292,21 +292,21 @@ sub rubberband =head1 NAME -Prima::Widget::RubberBand - draw rubberbands +Prima::Widget::RubberBand - dynamic rubberbands =head1 DESCRIPTION -The motivation for this module was that I was tired to see corrupted screens on +The motivation for this module was that I was tired of seeing corrupted screens on Windows 7 when dragging rubberbands in Prima code. Even though MS somewhere warned of not doing any specific hacks to circumvent the bug, I decided to give it a go anyway. This module thus is a C with a safeguard. The only thing it can do is to draw a static rubberband - but also remember the last -coordinates drawn, so cleaning comes for free. +coordinates drawn, so cleaning and animation come for free. The idea is that a rubberband object is meant to be a short-lived one: as soon -as it get instantiated it draws itself on the screen. When it is destroyed, the +as it gets instantiated it draws itself on the screen. When it is destroyed, the rubberband is erased too. =head1 SYNOPSIS @@ -323,7 +323,7 @@ rubberband is erased too. ); } - Prima::MainWindow-> create( + Prima::MainWindow-> new( onMouseDown => sub { my ( $self, $btn, $mod, $x, $y) = @_; $self-> {anchor} = [$self-> client_to_screen( $x, $y)]; @@ -349,7 +349,7 @@ rubberband is erased too. =item new %properties -Creates a new RubberBand instance. See description of properties below. +Creates a new RubberBand instance. See the description of its properties below. =back @@ -359,7 +359,7 @@ Creates a new RubberBand instance. See description of properties below. =item breadth INTEGER = 1 -Defines rubberband breadth, in pixels. +Defines the rubberband breadth in pixels. =item canvas = $::application @@ -367,13 +367,13 @@ Sets the painting surface, and also the widget (it must be a widget) used for dr =item clipRect X1, Y1, X2, Y2 -Defines the clipping rectangle, in inclusive-inclusive coordinates. If set to [-1,-1,-1,-1], -means no clipping is done. +Defines the clipping rectangle in inclusive-inclusive coordinates. If set to [-1,-1,-1,-1], +means no clipping is needed. =item rect X1, Y1, X2, Y2 -Defines the band geometry, in inclusive-inclusive coordinates. The band is drawn so that its body -is always inside these coordinates, no matter what breadth is. +Defines the band geometry in inclusive-inclusive coordinates. The band is drawn so that its body +is always inside these coordinates, no matter what the breadth is. =back @@ -383,11 +383,11 @@ is always inside these coordinates, no matter what breadth is. =item hide -Hides the band, if drawn +Hides the band =item has_clip_rect -Checks whether clipRect contains an actual clippring rectangle or it is empty. +Checks whether clipRect contains an actual clipping rectangle or it is empty. =item set %profile @@ -395,25 +395,25 @@ Applies all properties =item left, right, top, bottom, width, height, origin, size -Same shortcuts as in C, but read-only. +The same shortcuts as in C, but read-only. =item show -Show the band, if invisible +Shows the band =back =head1 Prima::Widget interface -The module adds a single method to C namespace, C +The module adds a single method to the C namespace, C (see example of use in the synopsis). =over =item rubberband(%profile) -Instantiates a C with C<%profile>, also sets C to C<$self> -unless C is set explicitly. +Instantiates a C object with C<%profile>, also sets C to C<$self> +( unless C is set explicitly ). =item rubberband() @@ -446,7 +446,7 @@ to the primary anyhow, for that very reason... if you try to access the DirectDraw primary, for instance, the DWM will turn off until the accessing application exits)" -This quote seems to explain the effect why screen sometimes gets badly +This quote seems to explain the effect of why the screen sometimes gets badly corrupted when using a normal xor rubberband. UCE ( Update Compatibility Evaluator ?? ) seems to be hacky enough to recognize some situations, but not all. diff --git a/Prima/Widget/ScrollWidget.pm b/Prima/Widget/ScrollWidget.pm index b6480fa41..9bfbdd4da 100644 --- a/Prima/Widget/ScrollWidget.pm +++ b/Prima/Widget/ScrollWidget.pm @@ -415,21 +415,24 @@ sub geomSize =head1 NAME -Prima::Widget::ScrollWidget - scrollable generic document widget. +Prima::Widget::ScrollWidget - scrollable generic document widget =head1 DESCRIPTION -C is a simple class that declares two pairs of properties, -I and I for vertical and horizontal axes, which define a -a virtual document. I is the document dimension, and I is -the current offset. +C is a simple class that declares two pairs of +properties, I and I for vertical and horizontal axes, which +define the extensions of a virtual document. I is the document +dimension, and I is the current offset. -C is a descendant of C, and, as well as its -ascendant, provides same user navigation by two scrollbars. The scrollbars' C -and C properties are maintained if the document or widget extensions change. +C is a descendant of +C, and as well as its ascendant, provides the +same user navigation by two scrollbars. The scrollbars' C and C +properties are automatically updated when the document or widget extensions +change. -C in addition provides capability to host other widgets inside, and -scroll them. Useful for widget group panels that cannot. fit in window +C provides the capability of hosting other widgets +inside, and also scrolling them. Useful for widget group panels that cannot fit +in a window =head1 Prima::Widget::ScrollWidget @@ -439,27 +442,27 @@ scroll them. Useful for widget group panels that cannot. fit in window =item deltas X, Y -Selects horizontal and vertical document offsets. +Selects the horizontal and vertical document offsets. =item deltaX INTEGER -Selects horizontal document offset. +Selects the horizontal document offset. =item deltaY INTEGER -Selects vertical document offset. +Selects the vertical document offset. =item limits X, Y -Selects horizontal and vertical document extensions. +Selects the horizontal and vertical document extensions. =item limitX INTEGER -Selects horizontal document extension. +Selects the horizontal document extension. =item limitY INTEGER -Selects vertical document extension. +Selects the vertical document extension. =back @@ -482,23 +485,23 @@ action calls C . =item client -Return a parent widget to insert other widgets to. The client size is fixed, -and is panned through the slave widget when scrolling. The client is unaffected by -eventual automated pack/place/growMode size alteration the parent or slave might have. +Returns the parent widget to insert other widgets. The client size is fixed +and is panned through the slave widget when scrolling. The client is unaffected +by the eventual automated pack/place/growMode size alteration the parent or slave +might be subjected to. =item clientClass -C widget is inserted in the C widget. +A C widget is inserted in the C widget. =item slave -Returns the slave widget. The slave widget designated the area desired to be -scrollable, and is just a normal widget that is allowed to be resized, moved, -etc. +Returns the slave widget. The slave widget covers the scrollable area and is +otherwise just a normal C object that can be resized, moved, etc. =item slaveClass -C widget is inserted directly in the scroll group widget. +A C widget is inserted directly in the scroll group widget. =back @@ -510,5 +513,4 @@ Dmitry Karasik, Edmitry@karasik.eu.orgE. L, L, L, F. - =cut diff --git a/Prima/Widget/StartupWindow.pm b/Prima/Widget/StartupWindow.pm index 75cbed809..d57f471d0 100644 --- a/Prima/Widget/StartupWindow.pm +++ b/Prima/Widget/StartupWindow.pm @@ -55,11 +55,11 @@ Prima::Widget::StartupWindow - a simplistic startup banner window =head1 DESCRIPTION -The module, when imported by C call, creates a temporary window -which appears with 'loading...' text while the modules required by +The module, when imported by the C call, creates a temporary window +which appears with the 'loading...' text while the modules required by a program are loading. The window parameters can be modified by -passing custom parameters after C statement, -which are passed to C class as creation parameters. +passing custom parameters after the C statement, +that are passed to the C class as creation parameters. The window is discarded by explicit unimporting of the module ( see L<"SYNOPSIS"> ). diff --git a/Prima/Widget/Time.pm b/Prima/Widget/Time.pm index 772502360..9f8308f5a 100644 --- a/Prima/Widget/Time.pm +++ b/Prima/Widget/Time.pm @@ -282,7 +282,7 @@ sub insertMode { $#_ ? shift->SUPER::insertMode(0) : shift->SUPER::insertMode } =head1 NAME -Prima::Widget::Time - time inputline +Prima::Widget::Time - standard time input widget =head1 SYNOPSIS @@ -301,7 +301,7 @@ Prima::Widget::Time - time inputline =head1 DESCRIPTION -Standard time inputline +Standard time input widget derived from the C class. =head1 API @@ -311,24 +311,25 @@ Standard time inputline =item time2str TIME -Converts TIME to string representation according to the current C string +Converts the TIME to a string representation according to the current C string =item default_format -Returns a string to be used in C, where the string is constructed in such a way -to reflect regional time formatting preferences. +Returns a string to be used in C where the string is constructed +to reflect the formatting of the regional time preferences. See also: C . =item str2time STRING -Tries to extract time from STRING assuming it is constructed according to the current C string. -Doesn't fail but values that could not be extracted are assigned to current second/minute/hour instead. +Tries to extract time from STRING, assuming it is constructed according to the +current C string. Doesn't fail but values that could not be extracted +are assigned to the current second/minute/hour instead. =item validate_time S, M, H -Checks whether S, M, H values are valid and within understood range; adjusts the values if not. -Returns the final values. +Checks whether S, M, H form a valid point in time, adjusts the values if not. +Returns the corrected values. =back @@ -338,9 +339,9 @@ Returns the final values. =item format STRING -The format string is used when converting time to its visual interpretation, -also with regional preferences, like hh:mm:ss or hh:mm:AA . The syntax of the -format is exctly this, it recognizes fixed patterns hh, mm, ss, aa, and AA, +The format string is used when converting the time to its visual interpretation, +also with regional preferences, f ex hh:mm:ss or hh:mm:AA . The syntax of the +format is verbatim as this, i e it recognizes fixed patterns hh, mm, ss, aa, and AA, replacing them with the time values. (C is for , C is for ). @@ -359,8 +360,8 @@ Selects the second =item time SEC, MIN, HOUR | [ SEC, MIN, HOUR ] -Accepts three integers / arrayref with three integers in format of C. -SEC and MIN can be from 0 to 59, HOUR from 0 to 23. +Accepts three integers / arrayref with three integers in the format of C. +SEC and MIN can be from 0 to 59, and HOUR from 0 to 23. Default value: today's time. diff --git a/Prima/Widget/UndoActions.pm b/Prima/Widget/UndoActions.pm index 84419afcd..7b091f3b5 100644 --- a/Prima/Widget/UndoActions.pm +++ b/Prima/Widget/UndoActions.pm @@ -135,6 +135,8 @@ sub undoLimit 1; +=pod + =head1 NAME Prima::Widget::UndoActions - undo and redo the content of editable widgets @@ -145,7 +147,20 @@ Generic helpers that implement stored actions for undo/redo. =head1 SYNOPSIS - + package MyUndoableWidget; + use base qw(Prima::Widget Prima::Widget::UndoActions); + + sub on_mousedown + { + if ( $button == mb::Left ) { + $self->begin_undo_group; + $self->push_undo_action(text => $self->text); + $self->text($self->text . '.'); + $self->end_undo_group; + } else { + $self->undo; # will call $self->text( old text ) + } + } =head1 Properties @@ -153,7 +168,7 @@ Generic helpers that implement stored actions for undo/redo. =item undoLimit INTEGER -Sets limit on number of stored atomic undo operations. If 0, +Sets the limit on the number of atomic undo operations. If 0, undo is disabled. =back @@ -164,17 +179,18 @@ undo is disabled. =item begin_undo_group -Opens bracket for group of actions, undone as single operation. +Opens a bracket for a group of actions that can be undone as a single operation. The bracket is closed by calling C. =item can_undo, can_redo -Return boolean flags whether undo or redo could be done. -Useful for graying a menu f ex. +Return a boolean flag that reflects if the undo or redo actions could be done. +Useful for graying a menu, f ex. =item end_undo_group -Closes bracket for group of actions, opened by C. +Closes the bracket for a group of actions, that was previously opened by +C. =item init_undo @@ -182,27 +198,27 @@ Should be called once, inside init() =item has_undo_action ACTION -Checks whether there is any ACTION in the undo list. +Checks whether there are any undo-able ACTIONs in the undo list. =item push_grouped_undo_action ACTION, @PARAMS Stores a single undo action where ACTION is a method to be called inside -undo/redo, if any. Each action is added to the last undo group, and will be +undo/redo, if any. Each action is added to the last undo group and will be removed/replayed together with the other actions in the group. =item push_undo_action ACTION, @PARAMS -Stores a single undo action where ACTION is a method to be called inside +Stores a single undo action where ACTION is the method to be called inside undo/redo, if any. Each action is a single undo/redo operation. =item redo -Re-applies changes, formerly rolled back by C. +Re-applies changes, previously rolled back by C. =item undo -Rolls back changes into internal array, which size cannot extend C -value. In case C is 0, no undo actions can be made. +Rolls back changes into an internal array. The array size cannot extend the +C value. In case C is 0 no undo actions can be made. =back