summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/selection.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/selection.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/selection.pod159
1 files changed, 0 insertions, 159 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/selection.pod b/Master/tlpkg/tlperl/lib/Tk/selection.pod
deleted file mode 100644
index f8a3ce54856..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/selection.pod
+++ /dev/null
@@ -1,159 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Selection - Manipulate the X selection
-
-=for category User Interaction
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<Selection>I<Option>?(I<args>)?
-
-=head1 DESCRIPTION
-
-This command provides an interface to the X selection mechanism and
-implements the full selection functionality described in the
-X Inter-Client Communication Conventions Manual (ICCCM).
-
-The widget object used to invoke the methods below determines which
-display is used to access the selection.
-In order to avoid conflicts with B<selection> methods of widget classes
-(e.g. B<Text>) this set of methods uses the prefix B<Selection>.
-The following methods are currently supported:
-
-=over 4
-
-=item I<$widget>-E<gt>B<SelectionClear>?(B<-selection>=E<gt>I<selection>)?
-
-If I<selection> exists anywhere on I<$widget>'s display, clear it
-so that no window owns the selection anymore. I<Selection>
-specifies the X selection that should be cleared, and should be an
-atom name such as PRIMARY or CLIPBOARD; see the Inter-Client
-Communication Conventions Manual for complete details.
-I<Selection> defaults to PRIMARY.
-Returns an empty string.
-
-=item I<$widget>-E<gt>B<SelectionGet>?(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?)?
-
-Retrieves the value of I<selection> from I<$widget>'s display and
-returns it as a result. I<Selection> defaults to PRIMARY.
-
-I<Type> specifies the form in which the selection is to be returned
-(the desired ``target'' for conversion, in ICCCM terminology), and
-should be an atom name such as STRING or FILE_NAME; see the
-Inter-Client Communication Conventions Manual for complete details.
-I<Type> defaults to STRING. The selection owner may choose to
-return the selection in any of several different representation
-formats, such as STRING, ATOM, INTEGER, etc. (this format is different
-than the selection type; see the ICCCM for all the confusing details).
-
-If I<format> is not STRING then things get messy, the following
-description is from the Tcl/Tk man page as yet incompetely translated for
-the perl version - it is misleading at best.
-
-If the selection is returned in a non-string format, such as INTEGER
-or ATOM, the B<SelectionGet> converts it to a list of perl
-values: atoms are converted to their
-textual names, and anything else is converted integers.
-
-A goal of the perl port is to provide better handling of different
-formats than Tcl/Tk does, which should be possible given perl's
-wider range of ``types''. Although some thought went into this
-in very early days of perl/Tk what exactly happens is still
-"not quite right" and subject to change.
-
-=item I<$widget>-E<gt>B<SelectionHandle>(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?,?B<-format>=E<gt>I<format>? I<callback>)
-
-Creates a handler for selection requests, such that I<callback> will
-be executed whenever I<selection> is owned by I<$widget> and
-someone attempts to retrieve it in the form given by I<type>
-(e.g. I<type> is specified in the B<selection get> command).
-I<Selection> defaults to PRIMARY, I<type> defaults to STRING, and
-I<format> defaults to STRING. If I<callback> is an empty string
-then any existing handler for I<$widget>, I<type>, and
-I<selection> is removed.
-
-When I<selection> is requested, I<$widget> is the selection owner,
-and I<type> is the requested type, I<callback> will be executed
-with two additional arguments.
-The two additional arguments
-are I<offset> and I<maxBytes>: I<offset> specifies a starting
-character position in the selection and I<maxBytes> gives the maximum
-number of bytes to retrieve. The command should return a value consisting
-of at most I<maxBytes> of the selection, starting at position
-I<offset>. For very large selections (larger than I<maxBytes>)
-the selection will be retrieved using several invocations of I<callback>
-with increasing I<offset> values. If I<callback> returns a string
-whose length is less than I<maxBytes>, the return value is assumed to
-include all of the remainder of the selection; if the length of
-I<callback>'s result is equal to I<maxBytes> then
-I<callback> will be invoked again, until it eventually
-returns a result shorter than I<maxBytes>. The value of I<maxBytes>
-will always be relatively large (thousands of bytes).
-
-If I<callback> returns an error (e.g. via B<die>)
-then the selection retrieval is rejected
-just as if the selection didn't exist at all.
-
-The I<format> argument specifies the representation that should be
-used to transmit the selection to the requester (the second column of
-Table 2 of the ICCCM), and defaults to STRING. If I<format> is
-STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
-just in the form returned by I<command>).
-
-If I<format> is not STRING then things get messy, the following
-description is from the Tcl/Tk man page as yet untranslated for
-the perl version - it is misleading at best.
-
-If I<format> is
-ATOM, then the return value from I<command> is divided into fields
-separated by white space; each field is converted to its atom value,
-and the 32-bit atom value is transmitted instead of the atom name.
-For any other I<format>, the return value from I<command> is
-divided into fields separated by white space and each field is
-converted to a 32-bit integer; an array of integers is transmitted
-to the selection requester.
-
-The I<format> argument is needed only for compatibility with
-many selection requesters, except Tcl/Tk. If Tcl/Tk is being
-used to retrieve the selection then the value is converted back to
-a string at the requesting end, so I<format> is
-irrelevant.
-
-A goal of the perl port is to provide better handling of different
-formats than Tcl/Tk does, which should be possible given perl's
-wider range of ``types''. Although some thought went into this
-in very early days of perl/Tk what exactly happens is still
-"not quite right" and subject to change.
-
-=item I<$widget>-E<gt>B<SelectionOwner>?(B<-selection>=E<gt>I<selection>)?
-
-B<SelectionOwner> returns the
-window in this application that owns I<selection> on the display
-containing I<$widget>, or an empty string if no window in this
-application owns the selection. I<Selection> defaults to PRIMARY.
-
-=item I<$widget>-E<gt>B<SelectionOwn>?(?B<-command>=E<gt>I<callback>?,?B<-selection>=E<gt>I<selection>?)?
-
-B<SelectionOwn> causes I<$widget> to become
-the new owner of I<selection> on I<$widget>'s display, returning
-an empty string as result. The existing owner, if any, is notified
-that it has lost the selection.
-If I<callback> is specified, it will be executed when
-some other window claims ownership of the selection away from
-I<$widget>. I<Selection> defaults to PRIMARY.
-
-=back
-
-=head1 KEYWORDS
-
-clear, format, handler, ICCCM, own, selection, target, type
-
-=cut
-