From 7aacf07442248533c4fdbc53c01a946053a359b1 Mon Sep 17 00:00:00 2001 From: Dmitry Karasik Date: Mon, 2 Oct 2023 14:09:30 +0200 Subject: [PATCH] some proofreading --- Prima.pm | 116 +++++---- Prima/Application.pm | 475 ++++++++++++++++------------------ Prima/Const.pm | 14 +- Prima/DetailedOutline.pm | 2 +- Prima/Dialog/FileDialog.pm | 2 +- Prima/Widget/MouseScroller.pm | 2 +- 6 files changed, 298 insertions(+), 313 deletions(-) diff --git a/Prima.pm b/Prima.pm index 187da5e33..9fc47c819 100644 --- a/Prima.pm +++ b/Prima.pm @@ -127,7 +127,6 @@ Prima - a Perl graphic toolkit =for html

- use Prima qw(Application Buttons); Prima::MainWindow->new( @@ -145,12 +144,21 @@ See more screenshots at L. =head1 DESCRIPTION -The toolkit is a combination of two basic sets of classes - core and external. The -core classes are coded in C and form a baseline for every Prima object -written in Perl. The usage of C is possible together with the toolkit; however, -its full power is revealed in the Perl domain. The external classes present -an easily expandable set of widgets, written entirely in Perl and communicating -with the system using Prima library calls. +Prima is a classic 2D GUI toolkit that works under Windows and X11 +environments. The toolkit features a rich widget library, extensive 2D +graphic support, PDF generation, modern Unicode text input and output, and +supports a wide set of image formats. Additionally, the RAD-style Visual +Builder and POD viewer are included. The toolkit can interoperate with other +popular event loop libraries. + +=head1 CLASS HIERARCHY + +The toolkit is built with a combination of two basic sets of classes - core and +external. The core classes are coded in C and form a baseline for every Prima +object written in Perl. The usage of C is possible together with the toolkit; +however, its full power is revealed in the Perl domain. The external classes +present an easily expandable set of widgets, written entirely in Perl and +communicating with the system using Prima library calls. The core classes form a hierarchy, which is displayed below: @@ -178,19 +186,18 @@ can be found below in L. =head1 BASIC PROGRAM -The very basic code shown in L<"SYNOPSIS"> is explained here. -The code creates a window with 'Hello, -world' title and a centered button with the same text. The program -terminates after the button is pressed. +The very basic code shown in L<"SYNOPSIS"> is explained here. The code creates +a window with a 'Hello, world' title and a button with the same text. +The program terminates after the button is pressed. -A basic construct for a program written with Prima obviously requires +A basic construct for a program written with Prima requires use Prima; -code; however, effective programming requires usage of the other -modules, for example, C, which contains a set of -button widgets. The C module can be -invoked with a list of such modules, which makes the construction +code; however, effective programming requires the usage of the other modules, for +example, C, which contains various button widgets. The +C module can be invoked together with a list of such modules, which makes the +construction use Prima; use Prima::Application; @@ -204,12 +211,12 @@ Another basic issue is the event loop, which is called by run Prima; -sentence and requires a C object to be created beforehand. -Invoking the C standard module is one of the possible ways to -create an application object. The program usually terminates after the event loop -is finished. +code and requires a C object to be created beforehand. +Invoking the C standard module is one of the possible ways +to create an application object. The program usually terminates after the event +loop is finished. -The window is created by invoking +The main window is created by invoking Prima::MainWindow->new(); @@ -217,11 +224,9 @@ or Prima::MainWindow->create() -code with additional parameters. Actually, all Prima objects are created by such a -scheme. The class name is passed as the first parameter, and a custom set -of parameters is passed afterwards. These parameters are usually -represented in a hash syntax, although actually passed as an array. -The hash syntax is preferred for code readability: +code with additional parameters. All Prima objects are created by the same +scheme; the class name is passed as the first parameter, and a custom set +of parameters is passed afterward: $new_object = Class->new( parameter => value, @@ -230,10 +235,10 @@ The hash syntax is preferred for code readability: ); Here, parameters are the class property names, and they differ from class to -class. Classes often have common properties, primarily due to the -object inheritance. +class. Classes often have common properties, primarily due to object +inheritance. -In the example, the following properties are set: +In the example, the following properties are used: Window::text Window::size @@ -241,20 +246,20 @@ In the example, the following properties are set: Button::centered Button::onClick -Property values can be of any type, given that they are scalar. As depicted -here, C<::text> property accepts a string, C<::size> - an anonymous array -of two integers, and C - a sub. +Property values can be of any scalar type. For example, the C<::text> property +accepts a string, C<::size> - an anonymous array of two integers, and +C - a sub. -onXxxx are special properties that form a class of I, -which share the C/C syntax, and are additive when -the regular properties are substitutive (read more in L). -Events are called in the object context when a specific condition occurs. -The C event here, for example, is called when the -user presses (or otherwise activates) the button. +onXxxx are special properties that describe I that can be used together +with the C/C syntax, and are additive when the regular properties +are substitutive (read more in L). Events are called in the +object context when a specific condition occurs. The C event here, +for example, is called when the user presses (or otherwise activates) the +button. =head1 API -This section describes miscellaneous methods, registered in C +This section describes miscellaneous methods, registered in the C namespace. =over @@ -286,27 +291,26 @@ Parses Prima options from @ARGS, returns unparsed arguments. =head1 OPTIONS Prima applications do not have a portable set of arguments; it depends on the -particular platform. Run +particular platform. Run perl -e '$ARGV[0]=q(--help); require Prima' -or any Prima program with C<--help> argument to get the list of supported +or any Prima program with a C<--help> argument to get the list of supported arguments. Programmatically, setting and obtaining these options can be done -by using C routine. +by using the C routine. -In cases where Prima argument parsing conflicts with application options, use -L to disable automatic parsing; also see L. -Alternatively, the construct +In cases where the Prima argument parsing conflicts with the application +options, use L to disable the automatic parsing; also see +L. Alternatively, the construct - BEGIN { local @ARGV; require Prima; } + BEGIN { local @ARGV; require Prima; } will also do. =head1 SEE ALSO -The toolkit documentation is divided by several -subjects, and the information can -be found in the following files: +The toolkit documentation is divided into several sections; the individual +manuals can be found in the following files: =over @@ -350,7 +354,7 @@ L - pull-down and pop-up menu objects L - programmable periodical events -L - root of widget objects hierarchy +L - the root of widget objects hierarchy L - system printing services @@ -366,7 +370,7 @@ L - combo box widget L - multi-column list viewer with controlling header widget -L - a multi-column outline viewer with controlling header widget +L - multi-column outline viewer with controlling header widget L - advanced dockable widgets @@ -420,7 +424,7 @@ L - color selection facilities L - find and replace dialogs -L - file system related widgets and dialogs +L - file system-related widgets and dialogs L - font dialog @@ -486,7 +490,7 @@ L - links embedded in widgets L - common paint routine for listboxes -L - auto repeating mouse events +L - auto-repeating mouse events L - simple panel widget @@ -550,9 +554,9 @@ L - unicode-aware core file functions The Prima manual pages often provide information for more than one Prima class. To quickly find out the manual page of a desired class, as well as display the -inheritance information, use the C command. The command can produce output in -text and pod formats; the latter feature is used by the standard Prima documentation -viewer C ( see File/Run/prima-class ). +inheritance information, use the C command. The command can +produce output in the text and pod formats; the latter feature is used by the +standard Prima documentation viewer C ( see File/Run/prima-class ). =back diff --git a/Prima/Application.pm b/Prima/Application.pm index 08dd67e24..a3a0c5bf6 100644 --- a/Prima/Application.pm +++ b/Prima/Application.pm @@ -23,117 +23,103 @@ __END__ =head1 NAME -Prima::Application - root of widget objects hierarchy +Prima::Application - the root of widget objects hierarchy =head1 DESCRIPTION -Prima::Application class serves as a hierarchy root for all objects with -child-owner relationship. All toolkit objects, existing with non-null owner -property, belong by their top-level parental relationship to Prima::Application -object. There can be only one instance of Prima::Application class at a time. +The Prima::Application class serves as the hierarchy root for the majority of +Prima objects. All toolkit widgets are ultimately owned by the application +object. There can be only one instance of the Prima::Application class at a time. =head1 SYNOPSIS - use Prima; - use Prima::Application; - -or - use Prima qw(Application); - - Prima::MainWindow-> create(); - + Prima::MainWindow->new(); run Prima; =head1 USAGE -Prima::Application class, and its only instance are treated specially -throughout the toolkit. The object instance is contained in +Prima::Application class and its only instance are treated specially +throughout the toolkit. The object instance is contained in the $::application scalar, defined in I module. The application instance must be -created whenever widget and window, or event loop functionality is desired. -Usually +created whenever widget, window, or event loop functionality is needed. +Usually the use Prima::Application; +or + + use Prima qw(Application); + code is enough, but I<$::application> can also be assigned explicitly. The -'use' syntax has advantage as more resistant to eventual changes in the toolkit -design. It can also be used in conjunction with custom parameters hash, alike -the general create() syntax: +'use' syntax has an advantage as more resistant to eventual changes in the toolkit +design. It can also be used in conjunction with custom parameters hash, like +the general new() syntax: use Prima::Application name => 'Test application', icon => $icon; -In addition to this functionality Prima::Application is also a wrapper to a set -of system functions, not directly related to object classes. This functionality +In addition to this functionality, Prima::Application is also a wrapper to a set +of system functions, not directly related to the object classes. This functionality is generally explained in L<"API">. =head2 Inherited functionality -Prima::Application is a descendant of Prima::Widget, but it is designed so -because their functional outliers are closest to each other. -Prima::Application does not strictly conform ( in OO sense ) to any of the -built-in classes. It has methods copied from both Prima::Widget and -Prima::Window at one time, and the inherited Prima::Widget methods and -properties function differently. For example, C<::origin>, a property from -Prima::Widget, is also implemented in Prima::Application, but returns always -(0,0), an expected but not much usable result. C<::size>, on the contrary, -returns the extent of the screen in pixels. There are few properties, -inherited from Prima::Widget, which return actual, but uninformative results, - -C<::origin> is one of those, but same are C<::buffered>, C<::clipOwner>, -C<::enabled>, C<::growMode>, C<::owner> and owner-inheritance properties, -C<::selectable>, C<::shape>, C<::syncPaint>, C<::tabOrder>, C<::tabStop>, -C<::transparent>, C<::visible>. To this group also belongs C<::modalHorizon>, -Prima::Window class property, but defined for consistency and returning always -1. Other methods and properties, like C<::size>, that provide different -functionality are described in L<"API">. +Prima::Application is a descendant of Prima::Widget but does not conform +strictly ( in thethe OO sense ) to any of the built-in classes. It has methods from +both Prima::Widget and Prima::Window, and the methods inherited from the +Prima::Widget class may work quite differently. For example, the C<::origin> +property from Prima::Widget is also implemented in Prima::Application, but +always returns (0,0), an expected but not much usable result. The C<::size> +property, on the contrary, returns the extent of the screen in pixels. There +are a few properties inherited from Prima::Widget, which return actual but +uninformative results, - C<::origin> is one of those, but there are several +others. The methods and properties, that are like C<::size> providing +different functionality, are described separately in L<"API">. =head2 Global functionality -Prima::Application is a wrapper to functionality, that is not related to one or -another class clearly. A notable example, paint mode, which is derived from -Prima::Drawable class, allows painting on the screen, overwriting the graphic -information created by the other programs. Although being subject to -begin_paint()/end_paint() brackets, this functionality can not be attached to a -class-shared API, an therefore is considered global. All such functionality is -gathered in the Prima::Application class. - -These topics enumerated below, related to the global scope, but occupying more -than one method or property - such functions described in L<"API">. +Prima::Application is a wrapper to a set of unrelated functions that do not +belong to other classes. A notable example, the painting functionality that is +inherited from the Prima::Drawable class, allows drawing on the screen, +possibly overwriting the graphic information created by the other programs. +Although it is a subject to the begin_paint()/end_paint() brackets, this +functionality does not belong to a single object and is considered global. =over =item Painting -As stated above, Prima::Application provides interface to the on-screen -painting. This mode is triggered by begin_paint()/end_paint() methods pair, and -the other pair, begin_paint_info()/end_paint_info() triggers the information -mode. This three-state paint functionality is more thoroughly described in -L. +As stated above, the Prima::Application class provides an interface to the +on-screen painting. This mode is triggered by the begin_paint()/end_paint() +methods, while the other pair, begin_paint_info()/end_paint_info() triggers the +information mode. This three-state paint functionality is more thoroughly +described in L. The painting on the screen surfaces under certain environments (XQuartz, XWayland) is either silently ignored or results in an error. There, -C will return a false value (C though returns +C may return a false value (C though always true). -=item Hint +=item Hints -$::application hosts a special Prima::HintWidget class object, accessible via -C, but with color and font functions aliased ( +C<$::application> hosts a special C class object, accessible +via C, but with its color and font functions aliased ( see C<::hintColor>, C<::hintBackColor>, C<::hintFont> ). -This widget serves as a hint label, floating over widgets if the mouse pointer +This widget serves as a hint label, floating over other widgets if the mouse pointer hovers longer than C<::hintPause> milliseconds. -Prima::Application internally manages all hint functionality. The hint widget -itself, however, can be replaced before application object is created, using -C<::hintClass> create-only property. +Prima::Application internally manages all of the hint functionality. The hint widget +itself, however, can be replaced before the application object is created, using +the C<::hintClass> create-only property. =item Printer -Result of L method points to an automatically created printer -object, responsible for the system-driven printing. Depending on the operating +The result of the L method points to an automatically created printer +object, responsible for the system printing. Depending on the operating system, it is either Prima::Printer, if the system provides GUI printing capabilities, or generic Prima::PS::Printer, the PostScript document interface. @@ -141,30 +127,30 @@ See L for details. =item Clipboard -$::application hosts set of Prima::Clipboard objects, created automatically to +C<$::application> hosts a set of Prima::Clipboard objects created automatically to reflect the system-provided clipboard IPC functionality. Their number depends -on the system, - under X11 environment there is three clipboard objects, and +on the system, - under the X11 environment, there are three clipboard objects, and only one under Win32. -These are no methods to access these clipboard objects, except fetch() ( or, -the indirect name calling ) - the clipboard objects are named after the system -clipboard names, which are returned by -Prima::Clipboard::get_standard_clipboards. +There are no specific methods to access these clipboard objects, except bring() +( or the indirect name call ); the clipboard objects are named after the +system clipboard names, which are returned by the +Prima::Clipboard::get_standard_clipboards method. -The default clipboard is named I, and is accessible via +The default clipboard is named I, and is accessible via the my $clipboard = $::application-> Clipboard; -code. +call. See L for details. =item Help subsystem The toolkit has a built-in help viewer, that understands perl's native POD ( -plain old documentation ) format. Whereas the viewer functionality itself is -part of the toolkit, and resides in C module, any custom -help viewing module can be assigned. Create-only C +plain old documentation ) format. Whereas the viewer functionality itself is a +part of the toolkit that resides in the C module, any custom +help viewing module can be assigned. The create-only C properties C<::helpClass> and C<::helpModule> can be used to set these options. C provides two methods for communicating with the help @@ -176,30 +162,30 @@ C closes the window. A complex program will need eventually more information than the toolkit provides. Or, knowing the toolkit boundaries in some platforms, the program changes its behavior accordingly. Both these topics are facilitated by extra -system information, returned by Prima::Application methods. -C returns a system value for one of C constants, so -the program can read the system-specific information. As well as -C method, that returns the short description of the system, it -is the portable call. To the contrary, C method is a wrapper to -system-dependent functionality, called in non-portable way. This method is -never used within the toolkit, and its usage is discouraged, primarily because -its options do not serve the toolkit design, are subject to changes and cannot -be relied upon. +system information returned by Prima::Application methods. The +C method returns a system-defined value for each of the +C constants, so the program can read the system-specific information. +As well as the C method that returns the short description of +the system, it is a portable call. On the contrary, the C method is +a wrapper to system-dependent functionality that is called in a non-portable +way. This method is rarely used within the toolkit, its usage is discouraged, +primarily because its options do not serve the toolkit design, its syntax is +subject to changes, and cannot be relied upon. =item Exceptions and signals By default Prima doesn't track exceptions caused by C, C, and signals. -Currently it is possible to enable a GUI dialog tracking the C exceptions, -by either operating the boolean C property, or using +Currently, it is possible to enable a GUI dialog tracking the C exceptions, +by either operating the boolean C property or using use Prima qw(sys::GUIException) syntax. If you need to track signals or warnings you may do so just by using standard perl -practices. It is though not advisable to call Prima interactive methods inside -signals, but use minimal code in the signal handler instead. F.ex. code that -would ask whether the user really wants to quit would look like this: +practices. It is though not advisable to call Prima interactive methods directly inside +signal handlers but use a minimal code instead. F.ex. code that +would ask whether the user wants to quit would look like this: use Prima qw(Utils MsgBox); $SIG{INT} = sub { @@ -234,7 +220,7 @@ See also: L, L If set to 1, issues C after the last top-level window is destroyed. Does not influence anything if set to 0. -This feature is designed to help with general 'one main window' application +This feature is designed to help with generic 'one main window' application layouts. Default value: 0 @@ -246,13 +232,13 @@ allowing the user to choose the course of action -- to stop, to continue, etc. Is 0 by default. -Note that the exception is only called inside the C call; if there -is a call to f ex C or a manual event loop run with C, -the dialog will not be shown. One needs to explicitly call -C<< $::application->notify(Die => $@) >> and check the notification result to +Note that the exception is only handled inside the C call; if there +is a call to f ex C or a manual event loop run with +C, the dialog will not be shown. One needs to explicitly call C<< +$::application->notify(Die => $@) >> and check the notification result to decide whether to propagate the exception or not. -Alternative syntax for setting C to 1 is a +The alternative syntax for setting C to 1 is the use Prima::sys::GUIException; @@ -262,102 +248,99 @@ or statement. -If for some reason an exception will be thrown during the dialog, it will not be handled +If for some reason an exception is thrown during dialog execution, it will not be handled by Prima but by the current C< $SIG{__DIE__} > handler. See also L . =item icon OBJECT -Holds the icon object, associated with the application. If C, a -system-provided default icon is assumed. Prima::Window object instances -inherit the application icon by default. +Holds the icon object associated with the application. If C, the +system-provided default icon is assumed. Prima::Window objects +inherit this application icon by default. =item insertMode BOOLEAN -A system boolean flag, showing whether text widgets through the system should +The system boolean flag signaling whether text widgets through the system should insert ( 1 ) or overwrite ( 0 ) text on user input. Not all systems provide the global state of the flag. =item helpClass STRING -Specifies a class of object, used as a help viewing package. The default value -is Prima::HelpViewer. - -Run-time changes to the property do not affect the help subsystem until -C call is made. +Specifies the class of the object used as the help viewing package. The +default value is Prima::HelpViewer. Run-time changes to the property do not +affect the help subsystem until a call to C is made. =item helpModule STRING -Specifies a perl module, loaded indirectly when a help viewing call is made via -C. Used when C<::helpClass> property is overridden and the new -class is contained in a third-party module. - -Run-time changes to the property do not affect the help subsystem until -C call is made. +Specifies the perl module loaded indirectly when a help viewing call is made +via the C method. Used when the C<::helpClass> property is +overridden and the new class is contained in a third-party module. Run-time +changes to the property do not affect the help subsystem until a call to C +is made. =item hintClass STRING Create-only property. -Specifies a class of widget, used as the hint label. +Specifies the class of the widget used as the hint label. Default value: Prima::HintWidget =item hintColor COLOR -An alias to foreground color property for the hint label widget. +The alias to the foreground color property of the hint label widget. =item hintBackColor COLOR -An alias to background color property for the hint label widget. +The alias to the background color property of the hint label widget. =item hintFont %FONT -An alias to font property for the hint label widget. +The alias to the font property of the hint label widget. =item hintPause TIMEOUT -Selects the timeout in milliseconds before the hint label is shown +Sets the timeout in milliseconds before the hint label is shown when the mouse pointer hovers over a widget. =item language STRING -By default contains user interface language, deduced either from C<$ENV{LANG}> -or GUI default. When changed, updates C propertly. +By default contains the user interface language deduced either from the +C<$ENV{LANG}> environment variable (unix) or a system default setting (win32). +When changed, updates the C property. See also: C. =item modalHorizon BOOLEAN -A read-only property. Used as a landmark for -the lowest-level modal horizon. -Always returns 1. +A read-only property. Used as the lowest-level modal horizon. Always returns +1. =item palette [ @PALETTE ] -Used only within paint and information modes. Selects solid colors in a system -palette, as many as possible. PALETTE is an array of integer triplets, where -each is red, green, and blue component, with intensity range from 0 to 255. +Used only within the paint and information modes. Selects solid colors in the system +palette, as many as possible. PALETTE is an array of 8-bit integer triplets, where +each is a red, green, and blue component. =item printerClass STRING Create-only property. -Specifies a class of object, used as a printer. The default value is +Specifies the class of the object used as the printer. The default value is system-dependent, but is either C or C. =item printerModule STRING Create-only property. -Specifies a perl module, loaded indirectly before a printer object of -C<::printerClass> class is created. Used when C<::printerClass> property is +Specifies the perl module loaded indirectly before the printer object of +the C<::printerClass> class is created. Used when the C<::printerClass> property is overridden and the new class is contained in a third-party module. =item pointerVisible BOOLEAN -Governs the system pointer visibility. If 0, hides the pointer so it is not +Manages the system pointer visibility. If 0, hides the pointer so it is not visible in all system windows. Therefore this property usage must be considered with care. @@ -365,19 +348,19 @@ with care. A read-only property. -Returns two integers, width and height of the screen. +Returns two integers, the width and height of the screen. =item showHint BOOLEAN If 1, the toolkit is allowed to show the hint label over a widget. If 0, the -display of the hint is forbidden. In addition to functionality of C<::showHint> +display of the hint is forbidden. In addition to the functionality of the C<::showHint> property in Prima::Widget, Prima::Application::showHint is another layer of hint visibility control - if it is 0, all hint actions are disabled, -disregarding C<::showHint> value in widgets. +disregarding C<::showHint> value in the widgets. =item skin SCALAR -Exactly same as L, but is mentioned here because +The same as L, but is mentioned here because it is possible to change the whole application skin by changing this property, f ex like this: @@ -385,9 +368,9 @@ f ex like this: =item textDirection BOOLEAN -Contains preferred text direction, initially calculated from the preferred +Contains the preferred text direction initially calculated from the preferred interface language. If 0 ( default ), the preferred text direction is -left-to-right (LTR), otherwise right-to-left (RTL), f.ex. for arabic and hebrew +left-to-right (LTR), otherwise right-to-left (RTL), f.ex. for Arabic and Hebrew languages. The value is used as a default when shaping text and setting widget input @@ -400,10 +383,10 @@ that have a fixed pixel value, but that would like to be represented in a useful manner when the display resolution is too high (on modern High-DPI displays) or too low (on ancient monitors). -By default, it acquires the system display resolution, and sets the scaling +By default, it acquires the system display resolution and sets the scaling factor so that when the DPI is 96 it is 1.0, 192 it is 2.0, etc. The increase step is 0.25, so that bitmaps may look not that distorted. However, when the -value is manually set, there is no such step, any value can be set. +value is manually set the step is not enforced and any value can be accepted. See also: L. @@ -411,9 +394,9 @@ See also: L. Selects if the system is allowed to generate key codes in unicode. Returns the effective state of the unicode input flag, which cannot be changed if perl or -operating system do not support UTF8. +the operating system does not support UTF8. -If 1, C property may return UTF8 text from system +If 1, the C property may return UTF8 text from system clipboards is available. Default value: 1 @@ -427,11 +410,11 @@ Default value: 1 =item Clipboard $CLIPBOARD, $ACTION, $TARGET With (the only implemented) C<$ACTION> I, is called whenever another -application requests clipboard data in format C<$TARGET>. This notification is -handled internally to optimize image pasting through the cliboard. Since the +application requests clipboard data in the format C<$TARGET>. This notification is +handled internally to optimize image pasting through the clipboard. Since the clipboard pasting semantics in Prima is such that data must be supplied to the clipboard in advance, before another application can request it, there is a -problem which format to use. In order to not encode an image or other complex +problem with which format to use. To avoid encoding an image or other complex data in all possible formats but do that on demand and in the format the other application wants, this notification can be used. @@ -439,17 +422,17 @@ Only implemented for X11. =item CopyImage $CLIPBOARD, $IMAGE -The notification stores C<$IMAGE> in clipboard. +The notification stores C<$IMAGE> in the clipboard. =item CopyText $CLIPBOARD, $TEXT -The notification stores C<$TEXT> in clipboard. +The notification stores C<$TEXT> in the clipboard. =item Die $@, $STACK Called when an exception occurs inside the event loop C. By default, consults the C property, and if it is set, displays the -system message dialog allowing the user to decide when to do next. +system message dialog allowing the user to decide what to do next. =item Idle @@ -459,22 +442,22 @@ is about to sleep waiting for more. =item PasteImage $CLIPBOARD, $$IMAGE_REF The notification queries C<$CLIPBOARD> for image content and stores in -C<$$IMAGE_REF>. Default action is that C<'Image'> format is queried. On unix, +C<$$IMAGE_REF>. The default action is that the C<'Image'> format is queried. On unix, encoded formats C<'image/bmp'>, C<'image/png'> etc are queried if the default C<'Image'> is not found. -The C mechanism is devised to read images from clipboard in GTK +The C mechanism can read images from the clipboard in the GTK environment. =item PasteText $CLIPBOARD, $$TEXT_REF -The notification queries C<$CLIPBOARD> for text content and stores in -C<$$TEXT_REF>. Default action is that C<'Text'> format is queried if -C is unset. Otherwise, C<'UTF8'> format is queried -beforehand. +The notification queries C<$CLIPBOARD> for text content and stores it in the +C<$$TEXT_REF> scalar. Its default action is that only the C<'Text'> format is +queried if C is unset. Otherwise, the C<'UTF8'> format is queried +first. The C mechanism is devised to ease defining text unicode/ascii -conversion between clipboard and standard widgets, in a standard way. +conversion between clipboard and standard widgets, in a standardized way. =back @@ -484,29 +467,29 @@ conversion between clipboard and standard widgets, in a standard way. =item add_startup_notification @CALLBACK -CALLBACK is an array of anonymous subs, which is executed when -Prima::Application object is created. If the application object is already -created during the call, CALLBACKs called immediately. +CALLBACK is an array of anonymous subs, which are all executed when +the Prima::Application object is created. If the application object is already +created during the call, CALLBACKs are called immediately. -Useful for add-on packages initialization. +Useful for initialization of add-on packages. =item begin_paint -Enters the enabled ( active paint ) state, returns success flag. Once the -object is in enabled state, painting and drawing methods can perform write +Enters the enabled ( active paint ) state, and returns the success flag. Once the +object is in the enabled state, painting and drawing methods can perform drawing operations on the whole screen. =item begin_paint_info -Enters the information state, returns success flag. The object information -state is same as enabled state ( see C), except that painting +Enters the information state, and returns the success flag. The object information +state is the same as the enabled state ( see C), except that painting and drawing methods are not permitted to change the screen. =item close -Issues a system termination call, resulting in calling C for all -top-level windows. The call can be interrupted by these, and thus canceled. If -not canceled, stops the application event loop. +Issues a system termination call, resulting in calling the C method for +all top-level windows. The call can be interrupted by the latter, and +effectively canceled. If not canceled stops the application event loop. =item close_help @@ -514,48 +497,48 @@ Closes the help viewer window. =item end_paint -Quits the enabled state and returns application object to the normal state. +Quits the enabled state and returns the application object to the normal state. =item end_paint_info -Quits the information state and returns application object to the normal state. +Quits the information state and returns the application object to the normal state. =item font_encodings -Returns array of encodings, represented by strings, that are recognized by the -system and available for at least one font. Each system provides different sets -of encoding strings; the font encodings are not portable. +Returns an array of encodings represented by strings, that are recognized by +the system and available for at least one font. Each system provides different +sets of encoding strings; the font encodings are not portable. =item fonts NAME = '', ENCODING = '' -Returns hash of font hashes ( see L ) describing fonts -of NAME font family and of ENCODING. If NAME is '' or C, returns one -fonts hash for each of the font families that match the ENCODING string. If +Returns a hash of font hashes ( see L ) describing fonts +of NAME font family and of ENCODING text encoding. If NAME is '' or C, returns one +font hash for each of the font families that match the ENCODING string. If ENCODING is '' or C, no encoding match is performed. If ENCODING is not -valid ( not present in C result), it is treated as if it was '' +valid ( not present in the C result), it is treated as if it was '' or C. -In the special case, when both NAME and ENCODING are '' or C, each font -metric hash contains element C, that points to array of the font -encodings, available for the fonts of NAME font family. +In the special case when both NAME and ENCODING are '' or C, each font +metric hash contains the element C, which points to an array of the font +encodings, available for the fonts of the NAME font family. =item get_active_window -Returns object reference to a currently active window, if any, that belongs to +Returns the object reference to the currently active window, if any, that belongs to the program. If no such window exists, C is returned. The exact definition of 'active window' is system-dependent, but it is -generally believed that an active window is the one that has keyboard focus on +generally believed that an active window is the one that has a keyboard focus on one of its children widgets. =item get_caption_font -Returns a title font, that the system uses to draw top-level window captions. +Returns the title font that the system uses to draw top-level window captions. The method can be called with a class string instead of an object instance. =item get_default_cursor_width -Returns width of the system cursor in pixels. The method can be called with a +Returns the width of the system cursor in pixels. The method can be called with a class string instead of an object instance. =item get_default_font @@ -571,7 +554,7 @@ called with a class string instead of an object instance. =item get_dnd_clipboard -Returns the predefined special clipboard used as a proxy for drag and drop +Returns the predefined special clipboard used as a proxy for drag-and-drop interactions. See also: C, C. @@ -579,53 +562,52 @@ See also: C, C. =item get_default_window_borders BORDER_STYLE = bs::Sizeable Returns width and height of standard system window border decorations for one -of C constants. The method can be called with a class string instead +of the C constants. The method can be called with a class string instead of an object instance. =item get_focused_widget -Returns object reference to a currently focused widget, if any, that belongs to +Returns object reference to the currently focused widget, if any, that belongs to the program. If no such widget exists, C is returned. =item get_fullscreen_image -Syntax sugar for grabbing whole screen as in +Syntax sugar for grabbing the whole screen as in $::application->get_image( 0, 0, $::application->size) -(MacOSX/XQuartz: get_image() does not grab all screen bits, but -C does (given Prima is compiled with Cocoa library)). +(MacOSX/XQuartzi note: get_image() does not grab all screen bits, but +C does if Prima is compiled with the Cocoa library). =item get_hint_widget -Returns the hint label widget, attached automatically to Prima::Application -object during startup. The widget is of C<::hintClass> class, Prima::HintWidget +Returns the hint label widget, attached automatically to the Prima::Application +object during startup. The widget is of the C<::hintClass> class, Prima::HintWidget by default. - =item get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT Returns Prima::Image object with WIDTH and HEIGHT dimensions filled with graphic content of the screen, copied from X_OFFSET and Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen dimensions, they are adjusted. If -the offsets are outside screen boundaries, or WIDTH and HEIGHT are zero or +the offsets are outside the screen boundaries, or WIDTH and HEIGHT are zero or negative, C is returned. Note: When running on MacOSX under XQuartz, the latter does not give access to -the whole screen, so the function will not be able to grab top-level menu bar. -This problem is addressed in C. +the whole screen, so the function will not be able to grab the top-level menu bar. +This problem is addressed in the C method. =item get_indents -Returns 4 integers that corresponds to extensions of eventual desktop +Returns 4 integers that correspond to extensions of eventual desktop decorations that the windowing system may present on the left, bottom, right, and top edges of the screen. For example, for win32 this reports the size of -the part of the scraan that windows taskbar may occupies, if any. +the part of the screen that the windows taskbar may occupy, if any. =item get_printer -Returns the printer object, attached automatically to Prima::Application -object. The object is of C<::printerClass> class. +Returns the printer object attached automatically to the Prima::Application +object. The object is an instance of the C<::printerClass> class. =item get_message_font @@ -634,74 +616,70 @@ called with a class string instead of an object instance. =item get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1 -Returns the modal window, that resides on an end of a modality chain. +Returns the modal window that resides on an end of the modality chain. MODALITY_TYPE selects the chain, and can be either C or -C. TOPMOST is a boolean flag, selecting the lookup direction; if it -is 1, the 'topmost' window is returned, if 0, the 'lowest' one ( in a simple +C. TOPMOST is a boolean flag selecting the lookup direction: if it +is 1, the 'topmost' window is returned, if 0, the 'lower-most' one ( in a simple case when window A is made modal (executed) after modal window B, the A window is the 'topmost' one ). -If a chain is empty C is returned. In case when a chain consists of just -one window, TOPMOST value is apparently irrelevant. +If the chain is empty C is returned. In case the chain consists of just +one window, the TOPMOST value is irrelevant. =item get_monitor_rects -Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying monitor -configurations. Currently works under X11 only. +Returns set of rectangles in the format of (X,Y,WIDTH,HEIGHT) identifying monitor +layouts. =item get_scroll_rate Returns two integer values of two system-specific scrolling timeouts. The first -is the initial timeout, that is applied when the user drags the mouse from a +is the initial timeout that is applied when the user drags the mouse from a scrollable widget ( a text field, for example ), and the widget is about to -scroll, but the actual scroll is performed after the timeout is expired. The -second is the repetitive timeout, - if the dragging condition did not change, +scroll, but the actual scroll is performed after the timeout has expired. The +second value is the repetitive timeout, - if the dragging condition did not change, the scrolling performs automatically after this timeout. The timeout values are in milliseconds. =item get_system_info -Returns a hash with information about the system. The hash result contains the -following keys: +Returns a hash with the following keys containing information about the system: =over =item apc -One of C constants, reflecting the platform. -Currently, the list of the supported platforms is: +One of the C constants reporting the platform the program is running on. +Currently, the list of the supported platforms is one of these two: apc::Win32 apc::Unix =item gui -One of C constants, reflecting the graphic -user interface used in the system: +One of the C constants reporting the graphic user interface used in +the system: gui::Default - gui::PM gui::Windows gui::XLib gui::GTK =item guiDescription -Description of graphic user interface, returned as an arbitrary string. +Description of the graphic user interface returned as an arbitrary string. =item guiLanguage -Preferred language of the interface, returned as an ISO 639 code. +The preferred language of the interface returned as an ISO 639 code. =item system -An arbitrary string, representing the operating -system software. +An arbitrary string representing the operating system software. =item release -An arbitrary string, reflecting the OS version -information. +An arbitrary string, contains the OS version information. =item vendor @@ -718,7 +696,7 @@ The method can be called with a class string instead of an object instance. =item get_system_value Returns the system integer value, associated with one -of C constants. The constants are: +of the C constants. The constants are: sv::YMenu - height of menu bar in top-level windows sv::YTitleBar - height of title bar in top-level windows @@ -756,39 +734,41 @@ of C constants. The constants are: sv::DblClickDelay - mouse double-click timeout in milliseconds sv::ShapeExtension - 1 if Prima::Widget::shape functionality is supported, 0 otherwise - sv::ColorPointer - 1 if system accepts color pointer icons. - sv::CanUTF8_Input - 1 if system can generate key codes in unicode - sv::CanUTF8_Output - 1 if system can output utf8 text - sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop, + sv::ColorPointer - 1 if the system accepts color pointer icons. + sv::CanUTF8_Input - 1 if the system can generate key codes in unicode + sv::CanUTF8_Output - 1 if the system can output utf8 text + sv::CompositeDisplay - 1 if the system uses double-buffering and alpha composition for the desktop, 0 if it doesn't, -1 if unknown - sv::LayeredWidgets - 1 if system supports layering - sv::FixedPointerSize - 0 if system doesn't support arbitrary sized pointers and will resize custom icons to the system size + sv::LayeredWidgets - 1 if the system supports layering + sv::FixedPointerSize - 0 if the system doesn't support arbitrarily sized pointers and will resize custom icons to the system size sv::MenuCheckSize - width and height of default menu check icon sv::FriBidi - 1 if Prima is compiled with libfribidi and full bidi unicode support is available - sv::Antialias - 1 if system supports antialiasing and alpha layer for primitives + sv::Antialias - 1 if the system supports antialiasing and alpha layer for primitives sv::LibThai - 1 if Prima is compiled with libthai The method can be called with a class string instead of an object instance. =item get_widget_from_handle HANDLE -HANDLE is an integer value of a toolkit widget. It is usually passed to the +HANDLE is an integer value of a toolkit widget handle as used in the underlying +GUI level, for example, it is a HWND value on win32. It is usually passed to the program by other IPC means, so it returns the associated widget. If no widget is associated with HANDLE, C is returned. =item get_widget_from_point X_OFFSET, Y_OFFSET -Returns the widget that occupies screen area under (X_OFFSET,Y_OFFSET) -coordinates. If no toolkit widget are found, C is returned. +Returns the widget that occupies the screen area under (X_OFFSET,Y_OFFSET) +coordinates. If no toolkit widgets are found, C is returned. =item go -The main event loop. Called by +The main event loop. Called by the -run Prima; + run Prima; -standard code. Returns when the program is about to terminate, if C was called, or if the -exception was signaled. In the latter two cases, the loop can be safely re-started. +standard code. Returns when the program is about to terminate, if C was +called, or if the exception was signaled. In the latter two cases, the loop can +be safely restarted. =item lock @@ -797,8 +777,8 @@ restored with C. =item load_font FONTNAME -Registers font resource in system-specific format. The resource is freed after -prgram ends. +Registers a font resource in the system-specific format. The resource is freed after the +program ends. Notes for win32: To add a font whose information comes from several resource files, point FONTNAME to a string with the file names separated by a C<|> - for @@ -806,22 +786,22 @@ example, C< abcxxxxx.pfm | abcxxxxx.pfb >. Notes for unix: available only when Prima is compiled with fontconfig and Xft . -Returns number of font resources added. +Returns the number of the font resources added. =item open_help TOPIC Opens the help viewer window with TOPIC string in -link POD format ( see L ) - the string is treated +the link POD format ( see L ) - the string is treated as "manpage/section", where 'manpage' is the file with POD content and 'section' is the topic inside the manpage. -Alternatively can handle the syntax in form of C< file://path|section > +Alternatively can handle the syntax in the form of C< file://path|section > where C is the file with the pod content and C

is an optional pod section within the file. =item stop -Breaks the event loop. The loop can be started again by C thereafter. +Stops the event loop. The loop can be started again. =item sync @@ -832,13 +812,13 @@ C on X11, and is a no-op otherwise. CALL is an arbitrary string of the system service name and the parameters to it. This functionality is non-portable, and its usage should be avoided. The -system services provided are not documented and subject to change. The actual -services can be looked in the toolkit source code under I +system services provided are not documented and are subject to change. The actual +services can be looked at in the toolkit source code under the I tag. =item unlock -Unblocks the graphic output for all widgets, previously locked with C. +Unlocks the graphic output for all widgets, previously locked with C. =item yield $wait_for_event=0 @@ -849,22 +829,23 @@ If the event loop can be schematized, then in yield } -draft yield() is the only function, called repeatedly within the event loop. -yield(0) call shouldn't be used to organize event loops, but it can be employed -to process stacked system events explicitly, to increase responsiveness of a +the draft, yield() is the only function called repeatedly within the event loop. +The yield(0) call shouldn't be used to organize event loops, but it can be employed +to process stacked system events explicitly, to increase the responsiveness of a program, for example, inside a long calculation cycle. yield(1) though is adapted exactly for external implementation of event loops; -it does exactly the same as yeild(0), but if there are no events, it sleeps +it does the same as yield(0), but if there are no events it sleeps until there comes at least one, processes it, and then returns. The return -value is 0 if the application doesn't need more event processings, because of +value is 0 if the application doesn't need more event processing, because of shutting down. The corresponding code will be while ( yield(1)) { ... } -but in turn, this call cannot be used for UI responsiveness inside tight cycles. +but in turn, this call cannot be used for increasing UI responsiveness inside +tight calculation loops. The method can be called with a class string instead of an object instance; however, the $::application object must be initialized. diff --git a/Prima/Const.pm b/Prima/Const.pm index 46a63e7c1..45ac82c98 100644 --- a/Prima/Const.pm +++ b/Prima/Const.pm @@ -1320,16 +1320,16 @@ See also L sv::DblClickDelay - mouse double-click timeout in milliseconds sv::ShapeExtension - 1 if Prima::Widget::shape functionality is supported, 0 otherwise - sv::ColorPointer - 1 if system accepts color pointer icons. - sv::CanUTF8_Input - 1 if system can generate key codes in unicode - sv::CanUTF8_Output - 1 if system can output utf8 text - sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop, + sv::ColorPointer - 1 if the system accepts color pointer icons. + sv::CanUTF8_Input - 1 if the system can generate key codes in unicode + sv::CanUTF8_Output - 1 if the system can output utf8 text + sv::CompositeDisplay - 1 if the system uses double-buffering and alpha composition for the desktop, 0 if it doesn't, -1 if unknown - sv::LayeredWidgets - 1 if system supports layering - sv::FixedPointerSize - 0 if system doesn't support arbitrary sized pointers and will resize custom icons to the system size + sv::LayeredWidgets - 1 if the system supports layering + sv::FixedPointerSize - 0 if the system doesn't support arbitrarily sized pointers and will resize custom icons to the system size sv::MenuCheckSize - width and height of default menu check icon sv::FriBidi - 1 if Prima is compiled with libfribidi and full bidi unicode support is available - sv::Antialias - 1 if system supports antialiasing and alpha layer for primitives + sv::Antialias - 1 if the system supports antialiasing and alpha layer for primitives sv::LibThai - 1 if Prima is compiled with libthai =head2 ta:: - alignment constants diff --git a/Prima/DetailedOutline.pm b/Prima/DetailedOutline.pm index a0d508a55..c1285e96e 100644 --- a/Prima/DetailedOutline.pm +++ b/Prima/DetailedOutline.pm @@ -326,7 +326,7 @@ sub autoRecalc {($#_)?$_[0]->set_auto_recalc ($_[1]):return $_[0]->{autoRecalc} =head1 NAME -Prima::DetailedOutline - a multi-column outline viewer with controlling +Prima::DetailedOutline - multi-column outline viewer with controlling header widget. =head1 SYNOPSIS diff --git a/Prima/Dialog/FileDialog.pm b/Prima/Dialog/FileDialog.pm index 998381d06..97e684226 100644 --- a/Prima/Dialog/FileDialog.pm +++ b/Prima/Dialog/FileDialog.pm @@ -1740,7 +1740,7 @@ sub showDotDirs =head1 NAME -Prima::Dialog::FileDialog - File system related widgets and dialogs. +Prima::Dialog::FileDialog - File system-related widgets and dialogs. =head1 SYNOPSIS diff --git a/Prima/Widget/MouseScroller.pm b/Prima/Widget/MouseScroller.pm index c68f661e6..0009c0562 100644 --- a/Prima/Widget/MouseScroller.pm +++ b/Prima/Widget/MouseScroller.pm @@ -69,7 +69,7 @@ sub ScrollTimer_Tick =head1 NAME -Prima::Widget::MouseScroller - auto repeating mouse events +Prima::Widget::MouseScroller - auto-repeating mouse events =head1 DESCRIPTION