home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / TEXT_FOC.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  10.7 KB  |  316 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. import sub_arctic.lib.interactor;
  5.  
  6. /** 
  7.  * Focus based dispatch agent for delivering text input.  This agent dispatches
  8.  * under the text_acceptor input protocol.  That protocol provides features 
  9.  * for filtering characters, recognizing and acting of special "action 
  10.  * characters", and performing standard edit functions (i.e., character delete 
  11.  * and line kill) in addition to normal text input.
  12.  *
  13.  * @see sub_arctic.input.text_acceptor
  14.  * @author Scott Hudson
  15.  */
  16. public class text_focus_agent extends single_focus_agent {
  17.  
  18.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  19.  
  20.   /** Simple constructor. */
  21.   public text_focus_agent()
  22.     {
  23.     }
  24.  
  25.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  26.  
  27.   /** 
  28.    * Handle informing an object that it has become the new text focus.
  29.    * This calls the start_text_entry() method.
  30.    *
  31.    * @param focusable obj       the object receiving focus
  32.    * @param event     evt       the event that "caused" the focus.
  33.    * @param Object    user_info the user info to be passed to the object.
  34.    */
  35.   protected void inform_focus_enter(
  36.     focusable obj, 
  37.     event     evt, 
  38.     Object    user_info)
  39.     {
  40.       event evt_copy;
  41.  
  42.       /* do a start_text_entry rather than the default focus_set_enter() */
  43.       evt_copy = new event(evt);
  44.       if (obj instanceof interactor)
  45.         evt_copy.global_to_local((interactor)obj);
  46.       else
  47.         evt_copy.reset_to_global();
  48.       ((text_acceptor)obj).start_text_entry(evt_copy, user_info);
  49.     }
  50.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  51.  
  52.   /** 
  53.    * Handle informing an object that it has lost the text focus.
  54.    * This calls the end_text_entry() method.
  55.    *
  56.    * @param focusable obj       the object loosing focus
  57.    * @param event     evt       the event that "caused" the loss of focus.
  58.    * @param Object    user_info the user info to be passed to the object.
  59.    */
  60.   protected void inform_focus_exit(
  61.     focusable obj, 
  62.     event     evt, 
  63.     Object    user_info)
  64.     {
  65.       event evt_copy;
  66.  
  67.       /* do an end_text_entry rather than the normal focus_set_exit() */
  68.       evt_copy = new event(evt);
  69.       if (obj instanceof interactor)
  70.         evt_copy.global_to_local((interactor)obj);
  71.       else
  72.         evt_copy.reset_to_global();
  73.       ((text_acceptor)obj).end_text_entry(evt_copy, user_info);
  74.     }
  75.  
  76.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  77.  
  78.   /** First character to be treated as a "delete character".  This can be 
  79.    *  disabled by setting it to '\0'.   Defaults to backspace.  Note: once 
  80.    *  the system allows user preferences for edit character to be determined, 
  81.    *  this will become protected.
  82.    */
  83.   public char del_char1 = '\b';
  84.  
  85.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  86.  
  87.   /** Second character to be treated as a "delete character".  This can be 
  88.    *  disabled by setting it to '\0' or the same as del_char2.   Defaults to
  89.    *  delete.  Note: once the system allows user preferences for edit 
  90.    *  character to be determined, this will become protected.
  91.    */
  92.   public char del_char2 = (char)127;
  93.  
  94.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  95.  
  96.   /** Character to be treated as a "line kill character".  This can be disabled
  97.    *  by setting it to '\0'.  Defaults to ^U ('\025').  Note: once the system 
  98.    *  allows user preferences for edit character to be determined, this will 
  99.    *  become protected.
  100.    */
  101.   public char line_kill_char = '\025';
  102.  
  103.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  104.  
  105.   /**
  106.    * Indicate whether the given object is suitable to be our focus.  In this
  107.    * case it needs to be a text_acceptor object.
  108.    *
  109.    * @param focusable candidate_obj the object being inquired about.
  110.    * @return boolean indicating if the object is suitable.
  111.    */
  112.   public boolean allowable_focus(focusable candidate_obj)
  113.     {
  114.       /* must be a text acceptor */
  115.       return candidate_obj instanceof text_acceptor;
  116.     }
  117.  
  118.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  119.  
  120.   /**
  121.    * Indicate if the given event is wanted by this agent.  Here we are 
  122.    * interested in KEY_ACTION and KEY_PRESS events.
  123.    *
  124.    * @param event evt the event being inquired about.
  125.    * @return boolean indicating if we want the event.
  126.   public boolean event_is_useful(event evt)
  127.     {
  128.       return evt.id() == event.KEY_ACTION || evt.id() == event.KEY_PRESS;
  129.     }
  130.  
  131.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  132.  
  133.   /**
  134.    * Attempt to dispatch the given event as text input.
  135.    *
  136.    * @param event      evt       the event to dispatch.
  137.    * @param Object     user_info ignored (since we are focus agent).
  138.    * @param interactor to_obj    ignored (since we are focus agent).
  139.    * @param int        seq_num   ignored (since we are focus agent).
  140.    * @return boolean indicating if the input was consumed.
  141.    */
  142.   public boolean dispatch_event(
  143.     event      evt,
  144.     Object     user_info,
  145.     interactor to_obj,
  146.     int        seq_num)
  147.     {
  148.       text_acceptor target;
  149.       int           filtered;
  150.       event         evt_copy;
  151.  
  152.       /* get the focus object and if we don't have one bail now */
  153.       target = (text_acceptor)_focus_set.elementAt(0);
  154.       if (target == null) return false;
  155.  
  156.       /* put event in target object's coords */
  157.       evt_copy = new event(evt);
  158.       if (target instanceof interactor)
  159.         evt_copy.global_to_local((interactor)target);
  160.       else
  161.     evt_copy.reset_to_global();
  162.  
  163.       /* do we have a "regular" key or a special "action" key? */
  164.       if (evt.id() == event.KEY_PRESS)
  165.     {
  166.       /* look for our edit keys first */
  167.       if ((del_char1 != '\0' && del_char1 == evt.key()) ||
  168.           (del_char2 != '\0' && del_char2 == evt.key()))
  169.         return target.delete_char(evt, user_info);
  170.       if (line_kill_char != '\0' && line_kill_char == evt.key())
  171.         return target.line_kill(evt_copy, user_info);
  172.  
  173.       /* its a "regular" character, so filter it */
  174.       filtered = target.char_filter(evt.key(),evt.modifiers());
  175.  
  176.       /* do any special actions that indicates */
  177.       if (filtered == text_acceptor.DISCARD_CHAR) return false;
  178.       if (filtered == text_acceptor.CLOSURE_ACTION_CHAR)
  179.         return target.action_char(evt_copy, (char)evt.key(), user_info);
  180.  
  181.       /* if all else fails dispatch as a normal character */
  182.       return target.new_char(evt_copy, (char)filtered, user_info);
  183.     }
  184.       else 
  185.     {
  186.       /* it was an "action" char, dispatch as a special */
  187.       return target.special_key(evt_copy, evt.key(), user_info);
  188.     }
  189.     }
  190.  
  191.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  192.  
  193.   /** 
  194.    * Standard translation filter for mapping to all upper case.  Special 
  195.    * values are passed through unaltered, so this filter can be composed with
  196.    * others if desired.
  197.    * 
  198.    * @param int ch ordinal value of the character to translate.
  199.    * @return int the ordinal value of the character converted to upper case. 
  200.    */
  201.   public static int translate_to_upper(int ch)
  202.     {
  203.       if (ch < 0 || ch > 0xffff) return ch;
  204.       return Character.toUpperCase((char)ch);
  205.     }
  206.  
  207.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  208.  
  209.   /** 
  210.    * Standard translation filter for mapping to all lower case. Special 
  211.    * values are passed through unaltered, so this filter can be composed with
  212.    * others if desired.
  213.    * 
  214.    * @param int ch ordinal value of the character to translate.
  215.    * @return int the ordinal value of the character converted to lower case. 
  216.    */
  217.   public static int translate_to_lower(int ch)
  218.     {
  219.       if (ch < 0 || ch > 0xffff) return ch;
  220.       return Character.toLowerCase((char)ch);
  221.     }
  222.  
  223.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  224.  
  225.   /** 
  226.    * Standard filter that removes all whitespace.  As with other filters, 
  227.    * this can be composed with other standard filters.  For example, one 
  228.    * can code something like: <br>
  229.    * <pre>
  230.    *  return no_white(eol_action(translate_to_lower(ch)));
  231.    * </pre>
  232.    * @param int ch ordinal value of the character to filter.
  233.    * @return int the ordinal value of the filtered character. 
  234.    */
  235.   public static int no_white(int ch)
  236.     {
  237.       if (ch < 0 || ch > 0xffff) return ch;
  238.       if (Character.isSpace((char)ch)) return text_acceptor.DISCARD_CHAR;
  239.       return ch;
  240.     }
  241.  
  242.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  243.  
  244.   /** 
  245.    * Standard filter to accept only decimal digits. 
  246.    *
  247.    * @param int ch ordinal value of the character to filter.
  248.    * @return int the ordinal value of the filtered character. 
  249.    */
  250.   public static int only_digits(int ch)
  251.     {
  252.       if (ch < 0 || ch > 0xffff) return ch;
  253.       if (!Character.isDigit((char)ch)) return text_acceptor.DISCARD_CHAR;
  254.       return ch;
  255.     }
  256.  
  257.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  258.  
  259.   /** 
  260.    * Standard filter to accept only decimal digits, plus, minus, and decimal 
  261.    * point.
  262.    *
  263.    * @param int ch ordinal value of the character to filter.
  264.    * @return int the ordinal value of the filtered character. 
  265.    */
  266.   public static int only_numeric(int ch)
  267.     {
  268.       if (ch < 0 || ch > 0xffff) return ch;
  269.       if (!Character.isDigit((char)ch)) 
  270.     {
  271.       if (ch == '+' || ch == '-' || ch == '.') return ch;
  272.       return text_acceptor.DISCARD_CHAR;
  273.     }
  274.       return ch;
  275.     }
  276.  
  277.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  278.  
  279.   /** 
  280.    * Standard filter to translate end of line characters into closure actions.
  281.    * As with other filters, this can be composed with other standard filters.  
  282.    * For example, one can  code something like: <br>
  283.    * <pre>
  284.    *   return only_digits(eol_action(ch));
  285.    * </pre>
  286.    * @param int ch ordinal value of the character to filter.
  287.    * @return int the ordinal value of the filtered character. 
  288.    */
  289.   public static int eol_action(int ch)
  290.     {
  291.       /* catch end of line characters */
  292.       if (ch == '\n' || ch == '\r') return text_acceptor.CLOSURE_ACTION_CHAR;
  293.  
  294.       /* pass everything else */
  295.       return ch;
  296.     }
  297.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  298.   // later need to add tabbing between fields
  299. }
  300. /*=========================== COPYRIGHT NOTICE ===========================
  301.  
  302. This file is part of the subArctic user interface toolkit.
  303.  
  304. Copyright (c) 1996 Scott Hudson and Ian Smith
  305. All rights reserved.
  306.  
  307. The subArctic system is freely available for most uses under the terms
  308. and conditions described in 
  309.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  310. and appearing in full in the lib/interactor.java source file.
  311.  
  312. The current release and additional information about this software can be 
  313. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  314.  
  315. ========================================================================*/
  316.