Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pod::Prima::Clipboard(User Contributed Perl Documentatpod::Prima::Clipboard(3)

       Prima::Clipboard	- GUI interprocess data	exchange

       Prima::Clipboard	class is a descendant of Prima::Component.  It serves
       as an interface to the specific data storage, called clipboard, visible
       to all clients of one GUI space.	The system clipboard is	intended for
       the exchange of information of an arbitrary type	between	graphic

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

	  # paste data
	  my $string = $c-> text;
	  my $image  = $c-> image;
	  my $other  = $c-> fetch('Other type');

	  # copy datum
	  $c-> text( $string);

	  # copy data
	  $c-> open;
	  $c-> text( $string);
	  $c-> image( $image);
	  $c-> store( $image);
	  $c-> close;

	  # clear
	  $c-> clear;

       Prima::Clipboard	provides access	to the system clipboard	data storage.
       For the easier communication, the system	clipboard has one 'format'
       field, that is stored along with	the data.  This	field is used to
       distinguish between data	formats.  Moreover, a clipboard	can hold
       simultaneously several data instances, of different data	formats. Since
       the primary usage of a clipboard	is 'copying' and 'pasting', an
       application can store copied information	in several formats, increasing
       possibility that	the receiving application recognizes the data.

       Different systems provide spectrum of predefined	data types, but	the
       toolkit uses only three of these	- ascii	text, utf8 text, and image. It
       does not	limit, however,	the data format	being one of these three types
       - an application	is free	to register its	own formats. Both predefined
       and newly defined data formats are described by a string, and the three
       predefined formats are represented by 'Text', 'UTF8', and 'Image'
       string constants.

       The most	frequent usage of Prima::Clipboard is to preform two tasks -
       copying and pasting. Both can be	exemplified by the following:

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

	  # paste
	  my $string = $c-> text;

	  # copy
	  $c-> text( $string);

       This simplistic code hides other	aspects	of Prima::Clipboard class.

       First, the default clipboard is accessible by an	implicit name call, as
       an object named 'Clipboard'. This scheme	makes it easily	overridable.
       A more important	point is, that the default clipboard object might be
       accompanied by other clipboard objects. This is the case	with X11
       environment, which defines also 'Primary' and 'Secondary' system
       clipboards. Their functionality is identical to the default clipboard,
       however.	"get_standard_clipboards()" method returns strings for the
       clipboards, provided by the system.

       Second, code for	fetching and storing multi-format data is somewhat
       different.  Clipboard is	viewed as a shared system resource, and	have
       to be 'opened', before a	process	can grab it, so	other processes	can
       access the clipboard data only after the	clipboard is 'closed' (	Note:
       It is not so under X11, where there the clipboard locking is advisory,
       and any process can grab	clipboard at any time) .

       "fetch()" and "store()" implicitly call "open()"	and "close()", but
       these functions must be called explicitly for the multi-format data
       handling. The code below	illustrates the	said:

	   # copy text and image
	   if (	$c-> open) {
	      $c-> clear;
	      $c-> store('Text', $string);
	      $c-> store('Image', $image);
	      $c-> close;

	   # check present formats and paste
	  if ( $c-> open) {
	     if	( $c-> format_exists('Text')) {
		$string	= $c-> fetch('Text');
	     # or, check the desired format alternatively
	     my	%formats = map { $_ => 1 } $c->	get_formats;
	     if	( $formats{'Image'}) {
		$image = $c-> fetch('Image');

	     $c-> close;

       The clear() call	in the copying code is necessary so the	newly written
       data will not mix with the old.

       At last,	the newly registered formats can be accessed by	a program:

	  my $myformat = 'Very Special Old Pale	Data Format';
	  if ( $c-> register_format($myformat))	{
	     $c-> open;
	     $c-> clear;
	     $c-> store('Text',	'sample	text');
	     $c-> store($myformat', 'sample ## text');
	     $c-> close;

   Custom formats
       Once registered,	all processes in a GUI space can access	the data by
       this format. The	registration must take place also if a Prima-driven
       program needs to	read data in a format, defined by an another program.
       In either case, the duplicate registration is a valid event.  When no
       longer needed, a	format can be de-registered.  It is not	a mandatory
       action, however - the toolkit cleans up before exit. Moreover, the
       system maintains	a reference counter on the custom-registered formats;
       de-registering does not mean deletion, thus. If two processes use a
       custom format, and one exits and	re-starts, it still can	access the
       data in the same	format,	registered by its previous incarnation.

       In real life, application often interchange text	in both	ascii and
       utf8, leaving the choice	to reader programs.  While it is possible to
       access both at the same time, by	"fetch"'ing content of "Text" and
       "UTF8" clipboard	slots, widgets implement their own pasting scheme. To
       avoid hacking widget code, usage	of "text" property is advised instead
       of indicating 'Text' and	'UTF8' constants. This method is used in
       standard	widgets, and is	implemented so the programmer can reprogram
       its default action by overloading "PasteText" notification of
       "Prima::Application" ( see "PasteText" in Prima::Application ).

       The default action of "PasteText" is to query first if 'Text' format is
       available, and if so, return the	ascii text scalar. If
       "Prima::Application::wantUnicodeInput" is set, 'UTF8' format is checked
       before resorting	to 'Text'. It is clear that this scheme	is not the
       only possibly needed, for example, an application may want to ignore
       ASCII text, or, ignore UTF8 text	but have
       "Prima::Application::wantUnicodeInput" set, etc.

       The symmetric action is "CopyText", that	allows for a custom text
       conversion code to be installed.

       Image data can be transferred in	different formats in different OSes.
       The lowest level	is raw pixel data in display-based format, whereas
       GTK-based applications can also exchange	images in file-based formats,
       such as bmp, png	etc. To	avoid further complications in the
       implementations,	"PasteImage" action was	introduced to handle these
       cases, together with a symmetrical "CopyImage".

       The default action of "PasteImage" is to	check whether lossless encoded
       image data is present, and if so, load a	new image from this data,
       before falling back to OS-dependent image storage.

       When storing the	image on the clipboard,	only the default format, raw
       pixel data is used.

   Exact and meta formats
       Prima registers two special meta	formats, "Image" and "Text", that
       interoperate with the system clipboard, storing data in the format that
       matches best with system	convention when	copying	and pasting images and
       text, correspondinly. It	is recommended to use meta-format calls
       (has_format, text, image, copy, paste) rather than exact	format calls
       (format_exists, store, fetch) when possible.

       Where the exact format method operate on	a single format	data storage,
       meta format calls may operate on	several	exact formats. F.ex. "text"
       can check whether there exists a	UTF-8 text storage, before resorting
       to 8-bit	text.  "image" on X11 is even more complicated,	and may	use
       image codecs to transfer	encoded	PNG streams, for example.

       image OBJECT, [KEEP]
	   Provides access to an image,	stored in the system clipboard.	 In
	   get-mode call, return "undef" if no image is	stored.	 In set-mode
	   clears the clipboard	unless KEEP is set.

       text STRING, [KEEP]
	   Provides access to text stored in the system	clipboard.  In get-
	   mode	call, return "undef" if	no text	information is present.	 In
	   set-mode clears the clipboard unless	KEEP is	set.

	   Deletes all data from clipboard.

	   Closes the open/close brackets. open() and close() can be called
	   recursively;	only the last close() removes the actual clipboard
	   locking, so other processes can use it as well.

       copy FORMAT, DATA, KEEP
	   Sets	DATA in	FORMAT.	Clears the clipboard before unless KEEP	is

       deregister_format FORMAT_STRING
	   De-registers	a previously registered	data format.  Called
	   implicitly for all not de-registered	format before a	clipboard
	   object is destroyed.

       fetch FORMAT_STRING
	   Returns the data of exact FORMAT_STRING data	format,	if present in
	   the clipboard.  Depending on	FORMAT_STRING, data is either text
	   string for 'Text' format, Prima::Image object for 'Image' format
	   and a binary	scalar value for all custom formats.

       format_exists FORMAT_STRING
	   Returns a boolean flag, showing whether FORMAT_STRING exact format
	   data	is present in the clipboard or not.

       has_format FORMAT_STRING
	   Returns a boolean flag, showing whether FORMAT_STRING meta format
	   data	is present in the clipboard or not.

	   Returns a system handle for a clipboard object.

       get_formats INCLUDE_UNREGISTERED	= 0
	   Returns array of strings, where each	is a format ID,	reflecting the
	   formats present in the clipboard.

	   Only	the predefined formats,	and the	formats	registered via
	   "register_format()" are returned if "INCLUDE_UNREGISTERED" is
	   unset.  If the flag is set, then all	existing formats returned,
	   however their names are not necessarily are the same	as registered
	   with	Prima.

	   Returns array of strings, each representing a registered format.
	   "Text" and "Image" are returned also.

	   Returns array of strings, each representing a system	clipboard. The
	   default "Clipboard" is always present. Other	clipboards are
	   optional.  As an example, this function returns only	"Clipboard"
	   under win32,	but also "Primary" and "Secondary" under X11. The
	   code, specific to these clipboards must refer to this function

	   Returns 1 if	the clipboard is the special clipboard used as a proxy
	   for drag and	drop interactions.

	   See also: "Widget/Drag and drop", "Application/get_dnd_clipboard".

	   Opens a system clipboard and	locks it for the process single	use;
	   returns a success flag. Subsequent "open" calls are possible, and
	   always return 1. Each "open()" must correspond to "close()",
	   otherwise the clipboard will	stay locked until the blocking process
	   is finished.

       paste FORMAT_STRING
	   Returns data	of meta	format FORMAT_STRING if	found in the
	   clipboard, or undef otherwise.

       register_format FORMAT_STRING
	   Registers a data format under FORMAT_STRING string ID, returns a
	   success flag. If a format is	already	registered, 1 is returned. All
	   formats, registered via "register_format()" are de-registered with
	   "deregister_format()" when a	program	is finished.

	   Stores SCALAR value into the	clipboard in FORMAT_STRING exact data
	   format. Depending of	FORMAT_STRING, SCALAR is treated as follows:

	      Text		text string in ASCII
	      UTF8		text string in UTF8
	      Image		Prima::Image object
	      other formats	binary scalar value

	   NB. All custom formats treated as a binary data. In case when the
	   data	are transferred	between	hosts with different byte orders no
	   implicit conversions	are made. It is	up to the programmer whether
	   to convert the data in a portable format, or	leave it as is.	The
	   former option is of course preferable. As far as the	author knows,
	   the Storable	module from CPAN collection provides the system-
	   independent conversion routines.

       Dmitry Karasik, <>.

       Prima, Prima::Component,	Prima::Application

perl v5.32.1			  2021-08-26	      pod::Prima::Clipboard(3)


Want to link to this manual page? Use this URL:

home | help