home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / CrtSelHdlr.3 < prev    next >
Encoding:
Text File  |  1995-07-26  |  10.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))       TTTTkkkk (((( ))))        TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tk_CreateSelHandler, Tk_DeleteSelHandler - arrange to handle
  12.           requests for the primary selection
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  16.  
  17.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr(_t_k_w_i_n, _t_a_r_g_e_t, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _f_o_r_m_a_t)
  18.  
  19.           TTTTkkkk____DDDDeeeelllleeeetttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr(_t_k_w_i_n, _t_a_r_g_e_t)
  20.  
  21.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  22.           Tk_Window          _t_k_w_i_n        (in)      Window  for  which
  23.                                                     _p_r_o_c  will provide
  24.                                                     selection
  25.                                                     information.
  26.  
  27.           Atom               _t_a_r_g_e_t       (in)      Form in which _p_r_o_c
  28.                                                     can   provide  the
  29.                                                     selection    (e.g.
  30.                                                     STRING          or
  31.                                                     FILE_NAME).
  32.                                                     Corresponds     to
  33.                                                     _t_y_p_e arguments  in
  34.                                                     sssseeeelllleeeeccccttttiiiioooonnnn
  35.                                                     commands.
  36.  
  37.           Tk_SelectionProc   *_p_r_o_c        (in)      Procedure       to
  38.                                                     invoke    whenever
  39.                                                     the  selection  is
  40.                                                     owned by _t_k_w_i_n and
  41.                                                     the      selection
  42.                                                     contents       are
  43.                                                     requested  in  the
  44.                                                     format   given  by
  45.                                                     _t_a_r_g_e_t.
  46.  
  47.           ClientData         _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary one-word
  48.                                                     value  to  pass to
  49.                                                     _p_r_o_c.
  50.  
  51.           Atom               _f_o_r_m_a_t       (in)      If  the  selection
  52.                                                     requestor isn't in
  53.                                                     this      process,
  54.                                                     _f_o_r_m_a_t  determines
  55.                                                     the representation
  56.                                                     used  to  transmit
  57.                                                     the  selection  to
  58.                                                     its requestor.
  59.      _________________________________________________________________
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))       TTTTkkkk (((( ))))        TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr  arranges  for  a  particular  procedure
  76.           (_p_r_o_c) to be called whenever the selection is owned by _t_k_w_i_n
  77.           and the selection contents are requested in the  form  given
  78.           by  _t_a_r_g_e_t.   _T_a_r_g_e_t should be one of the entries defined in
  79.           the  left  column  of  Table  2  of   the   X   Inter-Client
  80.           Communication  Conventions  Manual (ICCCM) or any other form
  81.           in which an application is willing to present the selection.
  82.           The most common form is STRING.
  83.  
  84.           _P_r_o_c should have arguments and result that  match  the  type
  85.           TTTTkkkk____SSSSeeeelllleeeeccccttttiiiioooonnnnPPPPrrrroooocccc:
  86.                typedef int Tk_SelectionProc(
  87.                     ClientData _c_l_i_e_n_t_D_a_t_a,
  88.                     int _o_f_f_s_e_t,
  89.                     char *_b_u_f_f_e_r,
  90.                     int _m_a_x_B_y_t_e_s);
  91.           The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  92.           argument    given    to   TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr.    Typically,
  93.           _c_l_i_e_n_t_D_a_t_a   points   to   a   data   structure   containing
  94.           application-specific  information that is needed to retrieve
  95.           the selection.  _O_f_f_s_e_t specifies an offset position into the
  96.           selection,  _b_u_f_f_e_r  specifies  a  location  at which to copy
  97.           information about the selection, and _m_a_x_B_y_t_e_s specifies  the
  98.           amount  of  space  available at _b_u_f_f_e_r.  _P_r_o_c should place a
  99.           NULL-terminated string  at  _b_u_f_f_e_r  containing  _m_a_x_B_y_t_e_s  or
  100.           fewer  characters  (not including the terminating NULL), and
  101.           it  should  return  a  count  of  the  number  of   non-NULL
  102.           characters  stored  at  _b_u_f_f_e_r.   If the selection no longer
  103.           exists (e.g. it once existed but the user deleted the  range
  104.           of characters containing it), then _p_r_o_c should return -1.
  105.  
  106.           When transferring large selections, Tk will  break  them  up
  107.           into  smaller  pieces  (typically a few thousand bytes each)
  108.           for more efficient transmision.  It will do this by  calling
  109.           _p_r_o_c  one or more times, using successively higher values of
  110.           _o_f_f_s_e_t to retrieve successive portions of the selection.  If
  111.           _p_r_o_c  returns  a  count less than _m_a_x_B_y_t_e_s it means that the
  112.           entire remainder of the selection  has  been  returned.   If
  113.           _p_r_o_c's  return  value  is  _m_a_x_B_y_t_e_s  it  means  there may be
  114.           additional information in the selection,  so  Tk  must  make
  115.           another call to _p_r_o_c to retrieve the next portion.
  116.  
  117.           _P_r_o_c always returns selection information in the form  of  a
  118.           character string.  However, the ICCCM allows for information
  119.           to be transmitted from the selection owner to the  selection
  120.           requestor  in  any  of several formats, such as a string, an
  121.           array of atoms, an  array  of  integers,  etc.   The  _f_o_r_m_a_t
  122.           argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr indicates what format should
  123.           be used to transmit the selection to its requestor (see  the
  124.           middle  column  of  Table  2 of the ICCCM for examples).  If
  125.           _f_o_r_m_a_t is not STRING, then Tk will take the  value  returned
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))       TTTTkkkk (((( ))))        TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.           by _p_r_o_c and divided it into fields separated by white space.
  141.           If _f_o_r_m_a_t is ATOM, then Tk will return the selection  as  an
  142.           array  of atoms, with each field in _p_r_o_c's result treated as
  143.           the name of one atom.  For any other  value  of  _f_o_r_m_a_t,  Tk
  144.           will return the selection as an array of 32-bit values where
  145.           each field of _p_r_o_c's result  is  treated  as  a  number  and
  146.           translated to a 32-bit value.  In any event, the _f_o_r_m_a_t atom
  147.           is returned  to  the  selection  requestor  along  with  the
  148.           contents of the selection.
  149.  
  150.           If TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr is called when there already exists a
  151.           handler  for  _t_a_r_g_e_t  on _t_k_w_i_n, then the existing handler is
  152.           replaced with a new one.
  153.  
  154.           TTTTkkkk____DDDDeeeelllleeeetttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr removes the handler given by  _t_k_w_i_n  and  |
  155.           _t_a_r_g_e_t,  if  such  a  handler  exists.   If there is no such  |
  156.           handler then it has no effect.
  157.  
  158.  
  159.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  160.           format, handler, selection, target
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/23/95)
  196.  
  197.  
  198.  
  199.