diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Tk/selection.pod')
-rwxr-xr-x | Master/tlpkg/tlperl0/lib/Tk/selection.pod | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Tk/selection.pod b/Master/tlpkg/tlperl0/lib/Tk/selection.pod new file mode 100755 index 00000000000..f8a3ce54856 --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/Tk/selection.pod @@ -0,0 +1,159 @@ +# 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 + |