home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.n / selection.n < prev    next >
Encoding:
Text File  |  1995-07-26  |  8.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))                 TTTTkkkk (((( ))))                  sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           selection - Manipulate the X selection
  12.  
  13.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.           sssseeeelllleeeeccccttttiiiioooonnnn _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  15.      _________________________________________________________________
  16.  
  17.  
  18.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.           This command provides a Tcl interface  to  the  X  selection
  20.           mechanism  and  implements  the full selection functionality
  21.           described in the X  Inter-Client  Communication  Conventions
  22.           Manual  (ICCCM),  except  that  it supports only the primary
  23.           selection.
  24.  
  25.           The first argument to sssseeeelllleeeeccccttttiiiioooonnnn determines the format of the
  26.           rest  of the arguments and the behavior of the command.  The
  27.           following forms are currently supported:
  28.  
  29.           sssseeeelllleeeeccccttttiiiioooonnnn cccclllleeeeaaaarrrr _w_i_n_d_o_w
  30.                If there is a selection anywhere on  _w_i_n_d_o_w's  display,  |
  31.                clear  it so that no window owns the selection anymore.  |
  32.                Returns an empty string.
  33.  
  34.           sssseeeelllleeeeccccttttiiiioooonnnn ggggeeeetttt ?_t_y_p_e?
  35.                Retrieves  the  value  of  the  primary  selection  and
  36.                returns  it  as  a  result.  TTTTyyyyppppeeee specifies the form in
  37.                which the selection is  to  be  returned  (the  desired
  38.                ``target''  for  conversion, in ICCCM terminology), and
  39.                should be an atom name such  as  STRING  or  FILE_NAME;
  40.                see  the  Inter-Client Communication Conventions Manual
  41.                for complete details.  TTTTyyyyppppeeee defaults  to  STRING.   The
  42.                selection  owner  may choose to return the selection in
  43.                any of several different representation  formats,  such
  44.                as   STRING,   ATOM,  INTEGER,  etc.  (this  format  is
  45.                different than the selection type;  see the  ICCCM  for
  46.                all  the  confusing  details).   If  the  selection  is
  47.                returned in a non-string format,  such  as  INTEGER  or
  48.                ATOM,  the  sssseeeelllleeeeccccttttiiiioooonnnn  command  converts  it  to string
  49.                format as a collection of fields separated  by  spaces:
  50.                atoms   are  converted  to  their  textual  names,  and
  51.                anything else is converted to hexadecimal integers.
  52.  
  53.           sssseeeelllleeeeccccttttiiiioooonnnn hhhhaaaannnnddddlllleeee _w_i_n_d_o_w _c_o_m_m_a_n_d ?_t_y_p_e? ?_f_o_r_m_a_t?
  54.                Creates a handler for  selection  requests,  such  that
  55.                _c_o_m_m_a_n_d will be executed whenever the primary selection
  56.                is owned by _w_i_n_d_o_w and someone attempts to retrieve  it
  57.                in  the  form  given by _t_y_p_e (e.g. _t_y_p_e is specified in
  58.                the sssseeeelllleeeeccccttttiiiioooonnnn ggggeeeetttt command).  _T_y_p_e defaults  to  STRING.  |
  59.                If _c_o_m_m_a_n_d is an empty string then any existing handler  |
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))                 TTTTkkkk (((( ))))                  sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))
  71.  
  72.  
  73.  
  74.                for _w_i_n_d_o_w and _t_y_p_e is removed.
  75.  
  76.                When the selection  is  requested  and  _w_i_n_d_o_w  is  the
  77.                selection owner and _t_y_p_e is the requested type, _c_o_m_m_a_n_d
  78.                will be executed as a Tcl command with  two  additional
  79.                numbers  appended  to  it (with space separators).  The
  80.                two additional numbers are _o_f_f_s_e_t and _m_a_x_B_y_t_e_s:  _o_f_f_s_e_t
  81.                specifies   a   starting   character  position  in  the
  82.                selection and _m_a_x_B_y_t_e_s  gives  the  maximum  number  of
  83.                bytes  to  retrieve.  The command should return a value
  84.                consisting  of  at  most  _m_a_x_B_y_t_e_s  of  the  selection,
  85.                starting at position _o_f_f_s_e_t.  For very large selections
  86.                (larger than _m_a_x_B_y_t_e_s) the selection will be  retrieved
  87.                using  several  invocations  of _c_o_m_m_a_n_d with increasing
  88.                _o_f_f_s_e_t values.   If  _c_o_m_m_a_n_d  returns  a  string  whose
  89.                length  is  less  than  _m_a_x_B_y_t_e_s,  the  return value is
  90.                assumed  to  include  all  of  the  remainder  of   the
  91.                selection;   if the length of _c_o_m_m_a_n_d's result is equal
  92.                to _m_a_x_B_y_t_e_s then _c_o_m_m_a_n_d will be invoked  again,  until
  93.                it  eventually  returns a result shorter than _m_a_x_B_y_t_e_s.
  94.                The value of _m_a_x_B_y_t_e_s will always be  relatively  large
  95.                (thousands of bytes).
  96.  
  97.                If  _c_o_m_m_a_n_d  returns  an  error  then   the   selection
  98.                retrieval  is  rejected just as if the selection didn't  |
  99.                exist at all.
  100.  
  101.                The _f_o_r_m_a_t argument specifies the  representation  that
  102.                should  be  used  to  transmit  the  selection  to  the
  103.                requester (the second column of Table 2 of the  ICCCM),
  104.                and  defaults  to  STRING.   If  _f_o_r_m_a_t  is STRING, the
  105.                selection is  transmitted  as  8-bit  ASCII  characters
  106.                (i.e.   just  in  the  form  returned  by _c_o_m_m_a_n_d).  If
  107.                _f_o_r_m_a_t is ATOM, then the return value from  _c_o_m_m_a_n_d  is
  108.                divided  into  fields  separated  by white space;  each
  109.                field is converted to its atom value,  and  the  32-bit
  110.                atom  value  is  transmitted  instead of the atom name.
  111.                For any other _f_o_r_m_a_t, the return value from _c_o_m_m_a_n_d  is
  112.                divided  into  fields separated by white space and each
  113.                field is converted to a 32-bit integer;   an  array  of
  114.                integers is transmitted to the selection requester.
  115.  
  116.                The _f_o_r_m_a_t argument is needed  only  for  compatibility
  117.                with selection requesters that don't use Tk.  If the Tk
  118.                toolkit is being used to retrieve  the  selection  then
  119.                the  value  is  converted  back  to  a  string  at  the
  120.                requesting end, so _f_o_r_m_a_t is irrelevant.
  121.  
  122.           sssseeeelllleeeeccccttttiiiioooonnnn oooowwwwnnnn ?_w_i_n_d_o_w? ?_c_o_m_m_a_n_d?
  123.                If  _w_i_n_d_o_w  is  specified,  then  it  becomes  the  new  |
  124.                selection owner and the command returns an empty string  |
  125.                as result.  The existing owner,  if  any,  is  notified  |
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))                 TTTTkkkk (((( ))))                  sssseeeelllleeeeccccttttiiiioooonnnn((((nnnn))))
  137.  
  138.  
  139.  
  140.                that   it  has  lost  the  selection.   If  _c_o_m_m_a_n_d  is  |
  141.                specified, it is a Tcl  script  to  execute  when  some  |
  142.                other  window  claims  ownership  of the selection away  |
  143.                from  _w_i_n_d_o_w.   If  neither  _w_i_n_d_o_w  nor   _c_o_m_m_a_n_d   is  |
  144.                specified then the command returns the path name of the  |
  145.                window in this application that owns the selection,  or  |
  146.                an  empty  string if no window in this application owns  |
  147.                the selection.
  148.  
  149.  
  150.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  151.           clear, format, handler, ICCCM, own, selection, target, type
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  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.