view release on metacpan or  search on metacpan

lib/Mac/CocoaDialog.pm  view on Meta::CPAN

   my $self = shift;
   system {$self->path()} $self->path(), $self->command_line(@_);
}

{
   no warnings;
   *grab       = \&qx;
   *foreground = \&foreground_system;
   *background = \&background_system;
}

package Mac::CocoaDialog::Runner;
use strict;
use warnings;
use English qw( -no_match_vars );
use base qw( Mac::CocoaDialog );

sub AUTOLOAD {
   my $self = shift;

   (my $name = our $AUTOLOAD) =~ s{.*::}{}mxs;
   $name =~ tr/_/-/;
   $self->push_params('--' . $name, @_);

   return $self;
} ## end sub AUTOLOAD

sub new {
   my $package = shift;
   my %opts = (@_ == 1) ? %$_ : @_;

   my $self = $package->SUPER::new(%opts);
   $self->push_params($opts{runmode});

   return $self;
} ## end sub new

1;    # Magic true value required at end of module
__END__

=encoding iso-8859-1

=head1 NAME

Mac::CocoaDialog - script with CocoaDialog

=head1 VERSION

This document describes Mac::CocoaDialog version 0.0.1. Most likely, this
version number here is outdate, and you should peek the source.


=head1 SYNOPSIS

   use Mac::CocoaDialog;

   my $cocoa = Mac::CocoaDialog->new('/path/to/CocoaDialog');

   # As factory
   my $bubble = $cocoa->bubble();
   $bubble->text('whatever')->title('Hello!');  # cascaded
   $bubble->no_timeout();  # underscores become dashes
   $bubble->background();  # actual call to CocoaDialog

   # Another one, as factory
   my $multi = $cocoa->bubble();
   $multi->titles(qw( first second third ));
   $multi->texts(qw(   #1     #2    #3 ));
   $multi->no_timeout()->independent()->foreground();

   # Directly from $cocoa object
   $cocoa->foreground(
      'bubble',
      text => 'whatever',
      title => 'Hello!',
      icon => 'heart',
   );


=head1 DESCRIPTION

This module eases calls to the CocoaDialog program in Mac. Be sure to
look at CocoaDialog's documentation at
L<http://cocoadialog.sourceforge.net/> to see what's this all
about. Briefly speaking, CocoaDialog gives you the possibility to
let the user interact with a very basic GUI, providing basic
input boxes, progress bars, etc.

This module is object oriented, and can be used in two different
manners. Either way, first of all you need an object, and to have it
you need to ensure that it's able to find CocoaDialog in some way:

   my $cocoa  = Mac::CocoaDialog->new();  # uses default
   my $cocoa2 = Mac::CocoaDialog->new(path => '/path/to/CocoaDialog');

In the first example, no explicit path is passed, so the module will
try to find it in the following paths (in order):

=over

=item B</Applications/CocoaDialog.app/Contents/MacOS/CocoaDialog>

=item B<~/Applications/CocoaDialog.app/Contents/MacOS/CocoaDialog>

=back

In the second case, the path is explicitly passed and no default is
looked for.

The most direct mode in which you can use this object is by calling
a method that suits to the way you want to interact with the CocoaDialog.
Depending on your needs and on the type of CocoaDialog runmode you
want to use, you can invoke it in different manners:

=over

=item *

piping data to the CocoaDialog. In this case, you'll want a filehandle
where you can send data, and you can get it using the L</pipe_to>
method;

=item *

getting data from the CocoaDialog, either with a filehandle (that 
you can get with L</pipe_from>) or all at once (using method L</qx>
or its alias L</grab>);

=item *

simply calling the CocoaDialog, either in foreground (blocking mode,
using methods L</foreground> or its alias L</foreground_system>)
or in background (using either L</background> or L</background_system>);

=back

Once you have chosen the method that better suits you needs, you simply
have to call it like you were calling the CocoaDialog program, i.e.
passing the runmode and the list of options (where each option's name
starts with C<-->), like this:

   $cocoa->foreground(qw( bubble --title Hello --text World! ));
   my $rv = $cocoa->grab( qw( yesno-msgbox --title Hi --text there ));

If you have your parameters in a hash, you can pass that as well:

   $cocoa->background(bubble => { 
      title => 'Hello',
      text  => 'World!',
   });

In this case, you have to provide the runmode and the hash, in which:

=over

=item B<keys>

will be used as parameter names, with a C<--> prepended and underscores
transformed into dashes;

=item B<values>

will be ignored if C<undef>, expanded if they're a reference to an
array, and used as they are otherwise.

=back

The other way you can use your C<$cocoa> object is like a factory to
get objects for individual runmode calls, in order to "build" your
command line using methods:

   my $bubble = $cocoa->bubble();
   $bubble->text('whatever')->title('Hello!');  # cascaded
   $bubble->no_timeout();  # underscores become dashes
   $bubble->background();  # actual call to CocoaDialog

Each time you call a method for a new parameter on the C<$bubble> 
object, the object itself is given back so that you can cascade
calls. When you're happy with the parameters, you can call one of
the activation methods seen before, without passing any parameter.


=head1 INTERFACE 

=over

=item B<< new >>

create a new instance for interacting with CocoaDialog.

Passing a C<$path> is optional. If C<$path> cannot be found, the module
will try to see if either 
B</Applications/CocoaDialog.app/Contents/MacOS/CocoaDialog>
or 
B<~/Applications/CocoaDialog.app/Contents/MacOS/CocoaDialog>
can be used instead.

=item B<< path >>

get the path to the CocoaDialog program.

=item B<< command_line >>

get the current command line (this is likely to work only when you
use your object as a factory, but give an eye to L</push_params>).


=item B<< push_params >>

register parameters as command line to use by default by the different
invocation methods, when the parameters aren't explicitly passed.

=back

=head2 Invocation Methods

=over

=item B<< foreground >>

=item B<< foreground_system >>

=item B<< background >>

=item B<< background_system >>

call CocoaDialog either in foreground or in background, without
any input/output interaction.

If you don't pass C<@params>, then the output of L</command_line>
will be used. Otherwise, the parameters will be expanded as described
in L</command_line>.

=item B<< qx >>

=item B<< grab >>

grab some stuff from the output of the CocoaDialog invocation.