view release on metacpan or  search on metacpan

pod/Prima/faq.pod  view on Meta::CPAN

must always be supplied, or never supplied, or a particular combination of properties is
expected. See if the DWIM principle can be applied instead.

=item *

Do not be afraid to define and re-define notification types. These have large number
of options, to be programmed once and then used as a DWIM helper. Consider for which
notifications user callback routines ( onXxxx ) would be best to be called first, or
last, whether a notification should be of multiple or single callback type.

If there is a functionality better off performed by the user-level code, consider
creating an individual notification for this purpose.

=item *

Repaint only the changed areas, not the whole widget.

If your widget has scrollable areas, use C<scroll> method.

Inside C<on_paint> check whether the whole or only a part of the widget is
about to be repainted. Simple optimizations here increase the speed.

Avoid using pre-cooked data in C<on_paint>, such as when for example only a
particular part of a widget was invalidated, and this fact is stored in an
internal variable. This is because when the actual C<on_paint> call is
executed, the invalid area may be larger than was invalidated by the class
actions. If you must though, compare values of C<clipRect> property to see
whether the invalid area is indeed the same as it is expected.

Remember, that inside on_paint all coordinates are inclusive-inclusive,
while the widget coordinates generally are inclusive-exclusive.

Note, that C<buffered> property does not guarantee that the widget
output would be actually buffered. Same goes with C<antialias> and C<layered>;
these functions are opportunistic.

=item *

Write some documentation and example of use.

=back

=head2 How would I add my widget class to the VB palette?

Check Prima/VB/examples/Widgety.pm . This file, if loaded through
'Add widget' command in VB, adds example widget class and example
VB property into the VB palette and Object Inspector.

=head2 How would I use unicode/UTF8 in Prima?

Prima by default is unicode-aware, in some areas more than the Perl (as of 5.32) itself.

For example on win32 Perl has big difficulties with files with unicode
characters, and this is recommended to mitigate using L<Prima::sys::FS>, which
overrides C<open>, C<opendir> and the like builtin functions with their
unicode-friendly versions. It doesn't though overload C<-f>,C<-e> syntax, so
use C<_f>,C<_e> etc instead.

Displaying UTF8 text is unproblematic, because Perl scalars can be
unambiguously told whether the text they contain is in UTF8 or not. The text
that comes from the user input, i e keyboard and clipboard, can be treated and
reported to Prima either as UTF8 r plain text, depending on
C<Prima::Application::wantUnicodeInput> property, which is set to 1 by default.
Remember though that if data are to be put through file I/O, the C<'utf8'> IO
layer must be selected ( see L<open> ).

The keyboard input is also easy, because a character key event comes with the
character code, not the character itself, and conversion between these is done
via standard perl's C<chr> and C<ord>.

The clipboard input is more complicated, because the clipboard may contain both
UTF8 and plain text data at once, and it must be decided by the programmer
explicitly which one is desired.  See more in L<Prima::Clipboard/Unicode>.

=head2 Is there a way to display POD text that comes with my program / package ?

   $::application-> open_help( "file://$0" );
   $::application-> open_help( "file://$0|DESCRIPTION" );
   $::application-> open_help( 'My::Package/BUGS' );

=head2 How to implement parallel processing?

Prima doesn't work if called from more than one thread, since Perl scalars
cannot be shared between threads automatically, but only if explicitly told,
by using L<thread::shared>. Prima does work in multithread environments though,
but only given it runs within a dedicated thread. It is important not to
call Prima methods from any other thread, because scalars that may be created
inside these calls will be unavailable to the Prima core, which would result
in strange errors.

It is possible to run things in parallel by calling the event processing
by hands: instead of entering the main loop with

   run Prima;

one can write

   while ( 1) {
      ... do some calculations ..
      $::application->yield;
   }

That'll give Prima a chance to handle accumulated events, but that technique is
only viable if calculations can be quantized into relatively short time frames.

The generic solution would be harder to implement and debug, but it scales
well. The idea is to fork a process, and communicate with it via its stdin
and/or stdout ( see L<perlipc> how to do that), and use L<Prima::File> to
asynchronously read data passed through a pipe or a socket.

Note: Win32 runtime library does not support asynchronous pipes, only asynchronous sockets.
Cygwin does support both asynchronous pipes and sockets.

=head2 How do I use Prima with AnyEvent or POE ?

L<AnyEvent> kind of knows about Prima, so if Prima is loaded then AnyEvent promises 
to detect it and load the corresponding backend.

If that doesn't work, the AnyEvent::Impl::Prima module is there in cpan.

If you want to use Prima's internal event loop system you have to install
L<POE::Loop::Prima> and include it in your code before Prima is loaded like
below:
        use POE 'Loop::Prima';
        use Prima qw/Application/;
        use AnyEvent;

You can call C<AnyEvent::detect> to check if the implementation is
C<'AnyEvent::Impl::POE'> if you want to use Prima's event loop or it should be
the event loop implementation you expect such as C<'AnyEvent::Impl::EV'>;