xmclipboard.3

安装DDD之前

.\"
.\" $Header: /cvsroot/lesstif/lesstif/doc/lessdox/widgets/XmClipboard.3,v 1.4 1998/10/07 22:12:59 danny Exp $
.\"
.\" Copyright (C) 1997-1998 Free Software Foundation, Inc.
.\" 
.\" This file is part of the GNU LessTif Library.
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Library General Public
.\" License as published by the Free Software Foundation; either
.\" version 2 of the License, or (at your option) any later version.
.\" 
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" Library General Public License for more details.
.\" 
.\" You should have received a copy of the GNU Library General Public
.\" License along with this library; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\" 
.TH XmClipboard 3 "May 1998" "LessTif Project" "LessTif Manuals"
.SH NAME
XmClipboard
.SH SYNOPSIS
.B #include <Xm/CutPaste.h>
.SH DESCRIPTION
The clipboard is represented by a number of convenience functions which
allow a widget or an application to exchange information with other widgets
or applications.
.PP
The API's described in this document are to be used by application writers,
but the LessTif widgets use them internally as well when the user performs
an action commanding the widget to interact with the clipboard.
.PP
Examples of the use of these functions can be found in the implementation
of the
.BR XmTextField (3)
widget, in
.I lib/Xm/TextF.c
under the root of the LessTif source directory.
Specifically, the functions XmTextFieldCopy and XmTextFieldPaste have
been implemented using the functions described below.
.SH CONVENIENCE FUNCTIONS
.PP
The functions are listed alphabetically below.
Do note however that XmClipboardStartCopy is to be called before any of the
other functions described in this document.
.PP
.\" @Document XmClipboardBeginCopy
.BR "int XmClipboardBeginCopy(Display *display, Window window, XmString clip_label, Widget widget, VoidProc callback, long *item_id)"
.PP
This appears to be the same as XmClipboardStartCopy.
This function should be called first,
then XmClipboardCopy may be called,
potentially multiple times;
the sequence must be ended with a call of XmClipboardEndCopy.
.PP
.\" @Document XmClipboardCancelCopy
.BR "int XmClipboardCancelCopy(Display *display, Window window, long item_id)"
.PP
Just what the name says : cancel a pending copy operation.
.PP
.\" @Document XmClipboardCopy
.BR "int XmClipboardCopy(Display *display, Window window, long item_id, char *format_name, XtPointer buffer, unsigned long length, long private_id, long *data_id)"
.PP
This function allows you to try to copy the buffer that needs to be
transferred to the clipboard.
Item_id should be the same as in the call to XmClipboardBeginCopy.
Private_id is a number that you can pass.
.PP
.\" @Document XmClipboardCopyByName
.BR "int XmClipboardCopyByName(Display *display, Window window, long data_id, XtPointer buffer, unsigned long length, long private_id)"
.PP
.\" @Document XmClipboardEndCopy
.BR "int XmClipboardEndCopy(Display *display, Window window, long item_id)"
.PP
See description of XmClipboardBeginCopy and XmClipboardCopy.
.PP
.\" @Document XmClipboardEndRetrieve
.BR "int XmClipboardEndRetrieve(Display *display, Window window)"
.PP
Ends a cycle of retrieval calls,
started with a call to XmClipboardBeginRetrieve,
and with calls of XmClipboardRetrieve in the middle.
.PP
.\" @Document XmClipboardInquireCount
.BR "int XmClipboardInquireCount(Display *display, Window window, int *count, unsigned long *max_length)"
.PP
.\" @Document XmClipboardInquireFormat
.BR "int XmClipboardInquireFormat(Display *display, Window window, int index, XtPointer format_name_buf, unsigned long buffer_len, unsigned long *copied_len)"
.PP
.\" @Document XmClipboardInquireLength
.BR "int XmClipboardInquireLength(Display *display, Window window, char *format_name, unsigned long *length)"
.PP
You can call this function just beforeXmClipboardRetrieve
to figure out how much data is waiting.
This way you can allocate storage dynamically.
An example of the use of this function is in the LessTif sources
in the file lib/Xm/TextF.c, in function XmTextFieldPaste.
.PP
.\" @Document XmClipboardInquirePendingItems
.BR "int XmClipboardInquirePendingItems(Display *display, Window window, char *format_name, XmClipboardPendingList *item_list, unsigned long *count)"
.PP
.\" @Document XmClipboardLock
.BR "int XmClipboardLock(Display *display, Window window)"
.PP
.\" @Document XmClipboardRegisterFormat
.BR "int XmClipboardRegisterFormat(Display *display, char *format_name, int format_length)"
.PP
.\" @Document XmClipboardRetrieve
.BR "int XmClipboardRetrieve(Display *display, Window window, char *format_name, XtPointer buffer, unsigned long length, unsigned long *num_bytes, long *private_id)"
.PP
Copy a chunk of the clipboard's data into application memory.
Length indicates the buffer's size.
Private_id returns private data associated with the data item
(this is just a number).
.PP
This function can return
.BR ClipboardLocked .
.PP
.\" @Document XmClipboardStartCopy
.BR "int XmClipboardStartCopy(Display *display, Window window, XmString clip_label, Time timestamp, Widget widget, XmCutPasteProc callback, long *item_id)"
.PP
This function creates temporary storage that will receive clipboard data.
It must be called before any other XmClipboard operation.
Window identifies the widget's window;
it should be passed to all clipboard routines in the same application.
Clip_label identifies the data item by name.
Widget is the widget ID receiving callbacks mentioned in callback.
Item_id returns a number to be used by the other clipboard copy functions
to refer to this particular object.
.PP
This function can return
.BR ClipboardLocked .
.PP
.\" @Document XmClipboardStartRetrieve
.BR "int XmClipboardStartRetrieve(Display *display, Window window, Time timestamp)"
.PP
This function indicates the start of incremental retrieval of data from
the clipboard.
Increments can be copied now with XmClipboardRetrieve,
while XmClipboardEndRetrieve should be called
to finish copying the contents of the clipboard.
These functions should be called with identical format_name arguments.
.PP
This function can return
.BR ClipboardLocked .
.PP
.\" @Document XmClipboardUndoCopy
.BR "int XmClipboardUndoCopy(Display *display, Window window)"
.PP
.\" @Document XmClipboardUnlock
.BR "int XmClipboardUnlock(Display *display, Window window, Boolean remove_all_locks)"
.PP
.\" @Document XmClipboardWithdrawFormat
.BR "int XmClipboardWithdrawFormat(Display *display, Window window, int data_id)"
.SH CALLBACKS
.PP
The callback functions triggered by XmClipboardStartCopy should have the
following signature :
.PP
.BR "void CallbackFunction(Widget w, int *data_id, int *private, int *reason)"
.PP
The data_id points to the data passed by name.
The private pointer points to data passed from XmClipboardCopy.
The reason field can either return XmCR_CLIPBOARD_DATA_DELETE or
XmCR_CLIPBOARD_DATA_REQUEST.
.SH RETURN VALUES
All of the functions described in this page can return the following codes :
.PP
.B ClipboardSuccess
the call ended successfully
.PP
.B ClipboardFail
failure for various reasons - see the explanation with the function
.PP
.B ClipboardLocked
some other application has locked the clipboard already
.PP
.B ClipboardNoData
it's empty or the format wasn't found
.PP
.B ClipboardTruncate
the data was truncated because the buffer was too small
.PP
.B ClipboardBadFormat
the format name was NULL or the format didn't have length 8, 16, or 32
.SH SEE ALSO