view release on metacpan or  search on metacpan

lib/Fl/Clipboard.pod  view on Meta::CPAN

class 'Fl';
include 'FL/Fl.H';

=pod

=head1 NAME

Fl::Clipboard - Global Copy/Cut/Paste Functions

=head1 Synopsis

    use Fl qw[:clipboard];

=head1 Description

This file contains functions related to text copying, cutting, and pasting.
All functions can be imported with the C<:clipboard> import tag.

=pod

=head1 Methods

Here we go...

=head2 C<clipboard_contains(...)>

    my $text = Fl::clipboard_contains(Fl::clipboard_plain_text);

Returns non 0 if the clipboard contains data matching type. Supported types
are C<text/plain> and C<image>.

=cut

xs {name        => 'Fl::clipboard_contains',
    definitions => [{required => [['const char *', 'type']], returns  => 'int'  }
    ],
    export => [qw[clipboard]]
};

=pod

=head2 C<copy(...)>

    Fl::copy('words');
    Fl::copy($raw, 1);
    Fl::copy($stuff, $destination);

Copies the data pointed in C<$stuff> to the selection buffer
(C<$destination == 0>) or the clipboard (C<$destination == 1>).

The selection buffer is used for middle-mouse pastes and for drag-and-drop
selections. The clipboard is used for traditional copy/cut/paste operations.

=cut

xs {name        => 'Fl::copy',
    definitions => [{
        required => [['const char *', 'stuff']],
        optional => [[qw[int destination], ' 0']],
        c_args   => 'stuff, strlen(stuff), destination, Fl::clipboard_plain_text',
        returns  => 'void'
        }
    ],
    export => [qw[clipboard]]
};

=pod

=head2 C<dnd( )>

    Fl::dnd( );

Initiate a Drag And Drop operation.

The selection buffer should be filled with relevant data before calling this
method. Fl will then initiate the system wide drag and drop handling. Dropped
data will be marked as text.

Create a selection first using C<Fl::copy(...)>.

=cut

xs {name        => 'Fl::dnd',
    definitions => [{ returns  => 'int' }],
    export => [qw[clipboard]]
};

=pod

=head2 C<paste(...)>

    Fl::paste( $widget, $source );
    Fl::paste( $widget, $source, $type );

Pastes the data from the selection buffer (C<$source == 0>) or the clipboard
(C<$source is 1>) into receiver.

If C<$source == 1>, the optional C<$type> argument indicates what type of data
is requested from the clipboard. At present, C<text/plain> (requesting text
data) and C<image> (requesting image data) are possible. Set things up so the
handle function of the receiver widget will be called with an C<FL_PASTE>
event some time in the future if the clipboard does contain data of the
requested type. During processing of this event, and if type is C<text/plain>,
the text data from the specified source are in C<Fl::event_text()> with UTF-8
encoding, and the number of characters in C<Fl::event_length()>. If type is
C<image>,C<Fl::event_clipboard()> returns an Fl::Image object. The receiver
should be prepared to be called directly by this, or for it to happen later,
or possibly not at all. This allows the window system to take as long as
necessary to retrieve the paste buffer (or even to screw up completely)
without complex and error-prone synchronization code in Fl.

The selection buffer is used for middle-mouse pastes and for drag-and-drop
selections. The clipboard is used for traditional copy/cut/paste operations.

Platform details for image data:

=over

=item Unix/Linux platform: Image data in PNG or BMP formats are recognized.
Requires linking with the fltk_images library.

=item MSWindows platform: Both bitmap and vectorial (Enhanced metafile) data
from clipboard can be pasted as image data.

=item Mac OS X platform: Both bitmap (TIFF) and vectorial (PDF) data from
clipboard can be pasted as image data.

=back

=cut

xs {name        => 'Fl::paste',
    definitions => [{
        required => [['Fl_Widget *', 'receiver'], [qw[int source]]],
        optional => [['const char *', 'type', 'Fl::clipboard_plain_text']],
        c_args   => '* receiver->cp_ctx, source, type',
        returns  => 'void' }],
    export => [qw[clipboard]]
};

=pod

=head2 C<selection(...)>

    Fl::selection( $widget, $text );

Changes the current selection.

The block of text is copied to an internal buffer by Fl (be careful if doing
this in response to an C<FL_PASTE> as this may be the same buffer returned by
C<event_text()>). The C<selection_owner()> widget is set to the passed owner.

=cut

xs {name        => 'Fl::selection',
    definitions => [{
        required => [['Fl_Widget *', 'owner'], ['const char *', 'text']],
        optional => [['int', 'len', 'strlen(text)']],
        c_args   => '* owner->cp_ctx, text, len',
        returns  => 'void' }],
    export => [qw[clipboard]]
};

# TODO:
#   Fl::add_clipboard_notify(...)

=pod

=head1 LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=cut