view release on metacpan or  search on metacpan

Prima/Application.pm  view on Meta::CPAN

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">.

=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">.

=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<Prima::Drawable>.

The painting on the screen surfaces under certain environments (XQuartz,
XWayland) is either silently ignored or results in an error. There,
C<begin_paint> will return a false value (C<begin_paint_info> though returns
true).

=item Hint

$::application hosts a special Prima::HintWidget class object, accessible via
C<get_hint_widget()>, but with color and font functions aliased (
C<::hintColor>, C<::hintBackColor>, C<::hintFont> ).

This widget serves as a hint label, floating over 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.

=item Printer

Result of L<get_printer> method points to an automatically created printer
object, responsible for the system-driven 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.

See L<Prima::Printer> for details.

=item Clipboard

$::application hosts 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
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.

The default clipboard is named I<Clipboard>, and is accessible via

	my $clipboard = $::application-> Clipboard;

code.

See L<Prima::Clipboard> 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<Prima::HelpViewer> module, any custom
help viewing module can be assigned. Create-only C<Prima::Application>
properties C<::helpClass> and C<::helpModule> can be used to set these options.

C<Prima::Application> provides two methods for communicating with the help
viewer window: C<open_help()> opens a selected topic in the help window, and
C<close_help()> closes the window.

=item System-dependent information

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<get_system_value> returns a system value for one of C<sv::XXX> constants, so
the program can read the system-specific information. As well as
C<get_system_info> method, that returns the short description of the system, it
is the portable call.  To the contrary, C<sys_action> 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.

=item Exceptions and signals

By default Prima doesn't track exceptions caused by C<die>, C<warn>, and signals.
Currently it is possible to enable a GUI dialog tracking the C<die> exceptions,
by either operating the boolean C<guiException> 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:

   use Prima qw(Utils MsgBox);
   $SIG{INT} = sub {
      Prima::Utils::post( sub {
          exit if message_box("Got Ctrl+C", "Do you really want to quit?", mb::YesNo) == mb::Yes;
      });
   };

and if you want to treat all warnings as potentially fatal, like this:

   use Prima qw(Utils MsgBox);
   $SIG{__WARN__} = sub {
      my ($warn, $stack) = ($_[0], Carp::longmess);
      Prima::Utils::post( sub {

Prima/Application.pm  view on Meta::CPAN

=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
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
visible in all system windows. Therefore this property usage must be considered
with care.

=item size WIDTH, HEIGHT

A read-only property.

Returns two integers, 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>
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.

=item textDirection BOOLEAN

Contains 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
languages.

The value is used as a default when shaping text and setting widget input
direction.

=item uiScaling FLOAT

The property contains an advisory multiplier factor, useful for UI elements
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
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.

See also: L<Prima/Stress>.

=item wantUnicodeInput BOOLEAN

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.

If 1, C<Prima::Clipboard::text> property may return UTF8 text from system
clipboards is available.

Default value: 1

=back

=head2 Events

=over

=item Clipboard $CLIPBOARD, $ACTION, $TARGET

With (the only implemented) C<$ACTION> I<copy>, 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
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
data in all possible formats but do that on demand and in the format the other
application wants, this notification can be used.

Only implemented for X11.

=item CopyImage $CLIPBOARD, $IMAGE

The notification stores C<$IMAGE> in clipboard.

=item CopyText $CLIPBOARD, $TEXT

The notification stores C<$TEXT> in clipboard.

=item Die $@, $STACK

Called when an exception occurs inside the event loop C<Prima::run>.  By
default, consults the C<guiException> property, and if it is set, displays the
system message dialog allowing the user to decide when to do next.

=item Idle

Called when the event loop handled all pending events, and
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,
encoded formats C<'image/bmp'>, C<'image/png'> etc are queried if the default
C<'Image'> is not found.

The C<PasteImage> mechanism is devised to read images from clipboard in 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<wantUnicodeInput> is unset. Otherwise, C<'UTF8'> format is queried
beforehand.

The C<PasteText> mechanism is devised to ease defining text unicode/ascii
conversion between clipboard and standard widgets, in a standard way.

=back

=head2 Methods

=over

=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.

Useful for add-on packages initialization.

=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
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<begin_paint()>), except that painting
and drawing methods are not permitted to change the screen.

=item close

Issues a system termination call, resulting in calling C<close> for all
top-level windows. The call can be interrupted by these, and thus canceled. If
not canceled, stops the application event loop.

=item close_help

Closes the help viewer window.

=item end_paint

Quits the enabled state and returns application object to the normal state.

=item end_paint_info

Quits the information state and returns 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.

=item fonts NAME = '', ENCODING = ''

Returns hash of font hashes ( see L<Prima::Drawable/Fonts> ) describing fonts
of NAME font family and of ENCODING. If NAME is '' or C<undef>, returns one
fonts hash for each of the font families that match the ENCODING string. If
ENCODING is '' or C<undef>, no encoding match is performed.  If ENCODING is not
valid ( not present in C<font_encodings> result), it is treated as if it was ''
or C<undef>.

In the special case, when both NAME and ENCODING are '' or C<undef>, each font
metric hash contains element C<encodings>, that points to array of the font
encodings, available for the fonts of NAME font family.

=item get_active_window

Returns object reference to a currently active window, if any, that belongs to
the program. If no such window exists, C<undef> 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
one of its children widgets.

=item get_caption_font

Returns a 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
class string instead of an object instance.

=item get_default_font

Returns the default system font.  The method can be called with a class string
instead of an object instance.

=item get_default_scrollbar_metrics

Returns dimensions of the system scrollbars - width of the standard vertical
scrollbar and height of the standard horizon scrollbar.  The method can be
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
interactions.

See also: C<Widget/Drag and drop>, C<Clipboard/is_dnd>.

=item get_default_window_borders BORDER_STYLE = bs::Sizeable

Returns width and height of standard system window border decorations for one
of C<bs::XXX> 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
the program. If no such widget exists, C<undef> is returned.

=item get_fullscreen_image

Syntax sugar for grabbing whole screen as in

   $::application->get_image( 0, 0, $::application->size)

(MacOSX/XQuartz: get_image() does not grab all screen bits, but
C<get_fullscreen_image> does (given Prima is compiled with 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
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
negative, C<undef> 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<get_fullscreen_image>.

=item get_indents

Returns 4 integers that corresponds 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.

=item get_printer

Returns the printer object, attached automatically to Prima::Application
object. The object is of C<::printerClass> class.

=item get_message_font

Returns the font the system uses to draw the message text.  The method can be
called with a class string instead of an object instance.