


XmClipboardRetrieve(3X)				      XmClipboardRetrieve(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCClliippbbooaarrddRReettrriieevvee -	A clipboard function that retrieves a data item	from
  the clipboard

SYNOPSIS


  ##iinncclluuddee <<XXmm//XXmm..hh>>
  ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>
  iinntt XXmmCClliippbbooaarrddRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _f_o_r_m_a_t__n_a_m_e,
	    _b_u_f_f_e_r, _l_e_n_g_t_h, _n_u_m__b_y_t_e_s, _p_r_i_v_a_t_e__i_d))
       DDiissppllaayy	  * _d_i_s_p_l_a_y;;
       WWiinnddooww	  _w_i_n_d_o_w;;
       cchhaarr	  * _f_o_r_m_a_t__n_a_m_e;;
       XXttPPooiinntteerr  _b_u_f_f_e_r;;
       uunnssiiggnneedd	lloonngg_l_e_n_g_t_h;;
       uunnssiiggnneedd	lloonngg* _n_u_m__b_y_t_e_s;;
       lloonngg	  * _p_r_i_v_a_t_e__i_d;;

DESCRIPTION
  XXmmCClliippbbooaarrddRReettrriieevvee 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 XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and a call	to XXmmCClliippbbooaarrddEEnnddRRee--
  ttrriieevvee, multiple calls to XXmmCClliippbbooaarrddRReettrriieevvee	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 CClliippbbooaarrddTTrruunnccaattee from calls	to XXmmCClliippbbooaarrddRReettrriieevvee indi-
  cates	that more data remains to be copied in the given format.  It is
  recommended that any calls to	the IInnqquuiirree functions that the application
  needs	to make	to effect the copy from	the clipboard be made between the
  call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and the first call to XXmmCClliippbbooaarrddRReettrriieevvee.
  That way, the	application does not need to call XXmmCClliippbbooaarrddLLoocckk and XXmmCClliipp--
  bbooaarrddUUnnlloocckk.

  _d_i_s_p_l_a_y     Specifies	a pointer to the DDiissppllaayy structure that	was returned
	      in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

  _w_i_n_d_o_w      Specifies	a widget's window ID that relates the application
	      window to	the clipboard.	The widget's window ID can be
	      obtained by using	XXttWWiinnddooww.  The same application	instance
	      should pass the same window ID to	each of	the clipboard func-
	      tions that it calls.

  _f_o_r_m_a_t__n_a_m_e Specifies	the name of a format in	which the data is stored on
	      the clipboard.

  _b_u_f_f_e_r      Specifies	the buffer to which the	application wants the clip-
	      board to copy the	data.

  _l_e_n_g_t_h      Specifies	the length of the application buffer.

  _n_u_m__b_y_t_e_s   Specifies	the number of bytes of data copied into	the applica-
	      tion buffer.

  _p_r_i_v_a_t_e__i_d  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 zero.

RETURN VALUE

  CClliippbbooaarrddSSuucccceessss
	      The function is successful.

  CClliippbbooaarrddLLoocckkeedd
	      The function failed because the clipboard	was locked by another
	      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.

  CClliippbbooaarrddTTrruunnccaattee
	      The data returned	is truncated because the user did not provide
	      a	buffer large enough to hold the	data.

  CClliippbbooaarrddNNooDDaattaa
	      The function could not find data on the clipboard	corresponding
	      to the format requested.	This could occur because the clip-
	      board 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.

RELATED	INFORMATION
  XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)), XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)),
  XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)),	and XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).



































