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

FreeBSD Manual Pages


home | help
XmClipboardRetrieve(3)	   Library Functions Manual	XmClipboardRetrieve(3)

       XmClipboardRetrieve  -- A clipboard function that retrieves a data item
       from the	clipboard

       #include	<Xm/CutPaste.h>
       int XmClipboardRetrieve (display, window, format_name,
	       buffer, length, num_bytes, private_id)
	       Display * display;
	       Window  window;
	       char    * format_name;
	       XtPointer       buffer;
	       unsigned	long   length;
	       unsigned	long   * num_bytes;
	       long    * private_id;

       XmClipboardRetrieve retrieves the  current  data	 item  from  clipboard
       storage.	 It  returns a warning if the clipboard	is locked, if there is
       no data on the clipboard, or if the data	needs to be truncated  because
       the buffer length is too	short.

       Between a call to XmClipboardStartRetrieve and a	call to	XmClipboardEn-
       dRetrieve, multiple calls to XmClipboardRetrieve	with the  same	format
       name result in data being incrementally copied from the clipboard until
       the data	in that	format has all been copied.

       The return value	XmClipboardTruncate from calls to  XmClipboardRetrieve
       indicates  that more data remains to be copied in the given format.  It
       is recommended that any calls to	the Inquire functions that the	appli-
       cation  needs to	make to	effect the copy	from the clipboard be made be-
       tween the call to XmClipboardStartRetrieve and the first	 call  to  Xm-
       ClipboardRetrieve.  This	way, the application does not need to call Xm-
       ClipboardLock and XmClipboardUnlock.

       display	 Specifies a pointer to	the Display  structure	that  was  re-
		 turned	in a previous call to XOpenDisplay or XtDisplay.

       window	 Specifies the window ID of a widget that relates the applica-
		 tion window to	the clipboard. The widget's window ID  can  be
		 obtained  through  XtWindow.	The  same application instance
		 should	pass the same window ID	to each	of the clipboard func-
		 tions that it calls.

		 Specifies the name of a format	in which the data is stored on
		 the clipboard.

       buffer	 Specifies the buffer to which the application wants the clip-
		 board to copy the data.  The function allocates space to hold
		 the data returned into	the buffer.  The  application  is  re-
		 sponsible for managing	this allocated space.  The application
		 can recover this allocated space by calling XtFree.

       length	 Specifies the length of the application buffer.

       num_bytes Specifies the number of bytes of data copied into the	appli-
		 cation	buffer.

		 Specifies  the	 private data stored with the data item	by the
		 application that placed the data item on  the	clipboard.  If
		 the  application  did	not  store  private data with the data
		 item, this argument returns 0 (zero).

		 The function was successful.

		 The function failed because the clipboard was locked  by  an-
		 other	application.  The application can continue to call the
		 function again	with the same parameters until the  lock  goes
		 away.	This  gives  the application the opportunity to	ask if
		 the user wants	to keep	trying or to give up on	the operation.

		 The data returned is truncated	because	the user did not  pro-
		 vide a	buffer large enough to hold the	data.

		 The function could not	find data on the clipboard correspond-
		 ing to	the format requested. This  could  occur  because  the
		 clipboard is empty; there is data on the clipboard but	not in
		 the requested format; or the data in the requested format was
		 passed	by name	and is no longer available.

       XmClipboardEndRetrieve(3), XmClipboardLock(3), XmClipboardStartCopy(3),
       XmClipboardStartRetrieve(3), and	XmClipboardUnlock(3).



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

home | help