


XmClipboardStartCopy(3X)			     XmClipboardStartCopy(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCClliippbbooaarrddSSttaarrttCCooppyy - A clipboard function that sets	up a storage and data
  structure

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tCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _c_l_i_p__l_a_b_e_l,
	    _t_i_m_e_s_t_a_m_p, _w_i_d_g_e_t, _c_a_l_l_b_a_c_k, _i_t_e_m__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;;
       XXmmSSttrriinngg	 _c_l_i_p__l_a_b_e_l;;
       TTiimmee	 _t_i_m_e_s_t_a_m_p;;
       WWiiddggeett	 _w_i_d_g_e_t;;
       XXmmCCuuttPPaasstteePPrroocc_c_a_l_l_b_a_c_k;;
       lloonngg	 * _i_t_e_m__i_d;;

DESCRIPTION
  XXmmCClliippbbooaarrddSSttaarrttCCooppyy sets up storage and data	structures to receive clip-
  board	data.  An application calls this function during a cut or copy opera-
  tion.	 The data item that these structures receive then becomes the next
  data item in the clipboard.

  Copying a large piece	of data	to the clipboard can take a long time.	It is
  possible that, once copied, no application will ever request that data.
  The Motif Toolkit provides a mechanism so that an application	does not need
  to actually pass data	to the clipboard until the data	has been requested by
  some application.

  Instead, the application passes format and length information	in XXmmCClliipp--
  bbooaarrddCCooppyy to the clipboard functions,	along with a widget ID and a callback
  function address that	is passed in XXmmCClliippbbooaarrddSSttaarrttCCooppyy.  The	widget ID is
  needed for communications between the	clipboard functions in the applica-
  tion that owns the data and the clipboard functions in the application that
  requests the data.

  The callback functions are responsible for copying the actual	data to	the
  clipboard via	XXmmCClliippbbooaarrddCCooppyyBByyNNaammee.	The callback function is also called
  if the data item is removed from the clipboard, and the actual data is
  therefore no longer needed.

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

  _c_l_i_p__l_a_b_e_l  Specifies	the label to be	associated with	the data item.	This
	      argument is used to identify the data item, for example, in a
	      clipboard	viewer.	 An example of a label is the name of the
	      application that places the data in the clipboard.

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

  _w_i_d_g_e_t      Specifies	the ID of the widget that receives messages request-
	      ing data previously passed by name.  This	argument must be
	      present in order to pass data by name.  Any valid	widget ID in
	      your application can be used for this purpose and	all the	mes-
	      sage handling is taken care of by	the cut	and paste functions.

  _c_a_l_l_b_a_c_k    Specifies	the address of the callback function that is called
	      when the clipboard needs data that was originally	passed by
	      name.  This is also the callback to receive the ddeelleettee message
	      for items	that were originally passed by name.  This argument
	      must be present in order to pass data by name.

  _i_t_e_m__i_d     Specifies	the number assigned to this data item.	The applica-
	      tion uses	this number in calls to	XXmmCClliippbbooaarrddCCooppyy, XXmmCClliippbbooaarr--
	      ddEEnnddCCooppyy,	and XXmmCClliippbbooaarrddCCaanncceellCCooppyy.

  For more information on passing data by name,	see XXmmCClliippbbooaarrddCCooppyy((33XX))	and
  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)).

  The _w_i_d_g_e_t and _c_a_l_l_b_a_c_k arguments must be present in order to	pass data by
  name.	The callback format is as follows:


  vvooiidd ((**_c_a_l_l_b_a_c_k) ((_w_i_d_g_e_t, _d_a_t_a__i_d, _p_r_i_v_a_t_e, _r_e_a_s_o_n))
    WWiiddggeett    _w_i_d_g_e_t;;
    iinntt	      **_d_a_t_a__i_d;;
    iinntt	      **_p_r_i_v_a_t_e;;
    iinntt	      **_r_e_a_s_o_n;;

  _w_i_d_g_e_t      Specifies	the ID of the widget passed to this function.

  _d_a_t_a__i_d     Specifies	the identifying	number returned	by XXmmCClliippbbooaarrddCCooppyy,
	      which identifies the pass-by-name	data.

  _p_r_i_v_a_t_e     Specifies	the private information	passed to XXmmCClliippbbooaarrddCCooppyy.

  _r_e_a_s_o_n      Specifies	the reason, which is either
	      XXmmCCRR__CCLLIIPPBBOOAARRDD__DDAATTAA__DDEELLEETTEE or XXmmCCRR__CCLLIIPPBBOOAARRDD__DDAATTAA__RREEQQUUEESSTT.

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dCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)), 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)), 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eggiisstteerrFFoorrmmaatt((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tRReettrriieevvee((33XX)),
  XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX)), XXmmCClliippbbooaarrddUUnnlloocckk((33XX)), and
  XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((33XX)).



