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

FreeBSD Manual Pages

  
 
  

home | help
XmClipboard(3)			LessTif	Manuals			XmClipboard(3)

NAME
       XmClipboard - Motif-compatible clipboard	widget

SYNOPSIS
       #include	<Xm/CutPaste.h>

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.

       The APIs	described in this document are to be used by application writ-
       ers, but	the LessTif widgets use	them internally	as well	when the  user
       performs	 an  action  commanding	 the widget to interact	with the clip-
       board.

       Examples	of the use of these functions can be found in the  implementa-
       tion  of	the XmTextField(3) widget, in lib/Xm/TextF.c under the root of
       the LessTif source directory.  Specifically, the	functions XmTextField-
       Copy and	XmTextFieldPaste have been implemented using the functions de-
       scribed below.

CONVENIENCE FUNCTIONS
       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.

       int  XmClipboardBeginCopy(Display  *display,  Window  window,  XmString
       clip_label, Widget widget, VoidProc callback, long *item_id)

       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 XmClipboard-
       EndCopy.

       int  XmClipboardCancelCopy(Display  *display,   Window	window,	  long
       item_id)

       Just what the name says : cancel	a pending copy operation.

       int XmClipboardCopy(Display *display, Window window, long item_id, char
       *format_name, XtPointer buffer, unsigned	long length, long  private_id,
       long *data_id)

       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.

       int  XmClipboardCopyByName(Display  *display,   Window	window,	  long
       data_id,	XtPointer buffer, unsigned long	length,	long private_id)

       int XmClipboardEndCopy(Display *display,	Window window, long item_id)

       See description of XmClipboardBeginCopy and XmClipboardCopy.

       int XmClipboardEndRetrieve(Display *display, Window window)

       Ends  a cycle of	retrieval calls, started with a	call to	XmClipboardBe-
       ginRetrieve, and	with calls of XmClipboardRetrieve in the middle.

       int  XmClipboardInquireCount(Display  *display,	Window	 window,   int
       *count, unsigned	long *max_length)

       int  XmClipboardInquireFormat(Display  *display,	Window window, int in-
       dex, XtPointer format_name_buf, unsigned	long buffer_len, unsigned long
       *copied_len)

       int  XmClipboardInquireLength(Display  *display,	 Window	 window,  char
       *format_name, unsigned long *length)

       You can call this function just beforeXmClipboardRetrieve to figure out
       how  much  data	is waiting.  This way you can allocate storage dynami-
       cally.  An example of the use  of  this	function  is  in  the  LessTif
       sources in the file lib/Xm/TextF.c, in function XmTextFieldPaste.

       int  XmClipboardInquirePendingItems(Display  *display,  Window  window,
       char *format_name,  XmClipboardPendingList  *item_list,	unsigned  long
       *count)

       int XmClipboardLock(Display *display, Window window)

       int  XmClipboardRegisterFormat(Display *display,	char *format_name, int
       format_length)

       int XmClipboardRetrieve(Display *display,  Window  window,  char	 *for-
       mat_name,   XtPointer  buffer,  unsigned	 long  length,	unsigned  long
       *num_bytes, long	*private_id)

       Copy a chunk of the clipboard's data into application  memory.	Length
       indicates  the  buffer's	size.  Private_id returns private data associ-
       ated with the data item (this is	just a number).

       This function can return	ClipboardLocked.

       int  XmClipboardStartCopy(Display  *display,  Window  window,  XmString
       clip_label,  Time  timestamp,  Widget  widget, XmCutPasteProc callback,
       long *item_id)

       This function creates temporary storage	that  will  receive  clipboard
       data.   It must be called before	any other XmClipboard operation.  Win-
       dow identifies the widget's window; it should be	passed	to  all	 clip-
       board 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.

       This function can return	ClipboardLocked.

       int  XmClipboardStartRetrieve(Display  *display,	 Window	 window,  Time
       timestamp)

       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 iden-
       tical format_name arguments.

       This function can return	ClipboardLocked.

       int XmClipboardUndoCopy(Display *display, Window	window)

       int  XmClipboardUnlock(Display  *display,  Window  window,  Boolean re-
       move_all_locks)

       int  XmClipboardWithdrawFormat(Display  *display,  Window  window,  int
       data_id)

CALLBACKS
       The  callback  functions	 triggered by XmClipboardStartCopy should have
       the following signature :

       void CallbackFunction(Widget w, int *data_id, int *private,  int	 *rea-
       son)

       The  data_id  points  to	 the data passed by name.  The private pointer
       points to data passed from XmClipboardCopy.  The	reason field  can  ei-
       ther return XmCR_CLIPBOARD_DATA_DELETE or XmCR_CLIPBOARD_DATA_REQUEST.

RETURN VALUES
       All  of	the  functions described in this page can return the following
       codes :

       ClipboardSuccess	the call ended successfully

       ClipboardFail failure for various reasons - see	the  explanation  with
       the function

       ClipboardLocked some other application has locked the clipboard already

       ClipboardNoData it's empty or the format	wasn't found

       ClipboardTruncate  the  data  was  truncated because the	buffer was too
       small

       ClipboardBadFormat the format name was NULL or the format  didn't  have
       length 8, 16, or	32

SEE ALSO
LessTif	Project			   May 1998			XmClipboard(3)

NAME | SYNOPSIS | DESCRIPTION | CONVENIENCE FUNCTIONS | CALLBACKS | RETURN VALUES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmClipboard&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help