


XmClipboardCopy(3X)					  XmClipboardCopy(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCClliippbbooaarrddCCooppyy - A clipboard	function that copies a data item to temporary
  storage for later copying to 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dCCooppyy ((_d_i_s_p_l_a_y,	_w_i_n_d_o_w,	_i_t_e_m__i_d, _f_o_r_m_a_t__n_a_m_e,
	    _b_u_f_f_e_r, _l_e_n_g_t_h, _p_r_i_v_a_t_e__i_d,	_d_a_t_a__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;;
       lloonngg	  _i_t_e_m__i_d;;
       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;;
       lloonngg	  _p_r_i_v_a_t_e__i_d;;
       lloonngg	  * _d_a_t_a__i_d;;

DESCRIPTION
  XXmmCClliippbbooaarrddCCooppyy copies a data	item to	temporary storage.  The	data item is
  moved	from temporary storage to the clipboard	data structure when a call to
  XXmmCClliippbbooaarrddEEnnddCCooppyy is	made.  Additional calls	to XXmmCClliippbbooaarrddCCooppyy before a
  call to XXmmCClliippbbooaarrddEEnnddCCooppyy add additional data item formats to the same
  data item or append data to an existing format.  Formats are described in
  the _I_n_t_e_r-_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l (ICCCM) as targets.

  NNOOTTEE::	 Do not	call XXmmCClliippbbooaarrddCCooppyy before a call to XXmmCClliippbbooaarrddSSttaarrttCCooppyy
  has been made.  The latter function allocates	temporary storage required by
  XXmmCClliippbbooaarrddCCooppyy.

  If the _b_u_f_f_e_r	argument is NULL, the data is considered to be passed by
  name.	 When data that	has been passed	by name	is later requested by another
  application, the application that owns the data receives a callback with a
  request for the data.	 The application that owns the data must then
  transfer the data to the clipboard with the XXmmCClliippbbooaarrddCCooppyyBByyNNaammee function.
  When a data item that	was passed by name is deleted from the clipboard, the
  application that owns	the data receives a callback stating that the data is
  no longer needed.

  For information on the callback function, see	the callback argument
  description for XXmmCClliippbbooaarrddSSttaarrttCCooppyy.

  _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.

  _i_t_e_m__i_d     Specifies	the number assigned to this data item.	This number
	      was returned by a	previous call to XXmmCClliippbbooaarrddSSttaarrttCCooppyy.

  _f_o_r_m_a_t__n_a_m_e Specifies	the name of the	format in which	the data item is
	      stored on	the clipboard.	Format is known	as target in the
	      ICCCM.

  _b_u_f_f_e_r      Specifies	the buffer from	which the clipboard copies the data.

  _l_e_n_g_t_h      Specifies	the length of the data being copied to the clipboard.

  _p_r_i_v_a_t_e__i_d  Specifies	the private data that the application wants to store
	      with the data item.

  _d_a_t_a__i_d     Specifies	an identifying number assigned to the data item	that
	      uniquely identifies the data item	and the	format.	 This argu-
	      ment is required only for	data that is passed by name.

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dFFaaiill
	      The function failed because XXmmCClliippbbooaarrddSSttaarrttCCooppyy was not called
	      or because the data item contains	too many formats.

RELATED	INFORMATION
  XXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), and
  XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).


































