


XmClipboardStartRetrieve(3X)			 XmClipboardStartRetrieve(3X)
OSF/Motif							    OSF/Motif



NAME
  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 - A clipboard function that starts a	copy 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dSSttaarrttRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _t_i_m_e_s_t_a_m_p))
       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;;
       TTiimmee	 _t_i_m_e_s_t_a_m_p;;

DESCRIPTION
  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 tells the clipboard routines	that the application
  is ready to start copying an item from the clipboard.	 The clipboard is
  locked by this routine and stays locked until	XXmmCClliippbbooaarrddEEnnddRReettrriieevvee is
  called.  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p--
  bbooaarrddEEnnddRReet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	for-
  mat 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.

  _t_i_m_e_s_t_a_m_p   Specifies	the time of the	event that triggered the copy.	A
	      valid timestamp must be supplied;	it is not sufficient to	use
	      CCuurrrreennttTTiimmee.

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.




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dIInnqquuiirreeCCoouunntt((33XX)),
  XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX)),	XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX)),
  XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss((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dRReettrriieevvee((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)), and
  XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).



























































