AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YDAT | YWAIT | Byzgraf | FAQs
JTextField typedict
 
A JTextField is the interface to the Java Swing JTextField Component. Yoix programs normally interact with a JTextField using event handlers and by reading or writing the following fields:
autotrim An int that is 1 when white space is automatically trimmed from both ends of every string read from or written to the text field, and 0 otherwise.
background The Color that is used to paint the background of the textfield. Reading returns a snapshot of the current color. Writing immediately changes the background to the new color. Storing NULL in background is special and means use the background of the nearest component that contains the textfield and was assigned a background color other than NULL; if no component qualifies the textfield uses white.
border An Object that should be a Border, Insets, Number, or String that describes the border that is drawn around this textfield. A NULL value, which is the default, means no border. A border that is an Insets or Number is an easy way to describe margins (i.e., an EmptyBorder), in units of 72 dots per inch, that are left around the sides of this textfield. A border that is a String is a quick way to surround this textfield with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the textfield's border to the new value.
caret An int that represents the position of the text insertion caret. Reading returns the current position. Writing immediately moves the caret to the new position.
caretcolor The Color used to paint the text caret. Reading returns the current color. Writing immediately repaints the text caret using the new color.
caretmodel An int that should be 0 (the default) or 1 and currently is only used during a drag and drop operation that is managed by drag and drop event handlers. A value of 0 tries to reproduce the caret and selection behavior that Swing's automatic drag handling provides. A value of 1 means the caret and selection will not moved or hidden during the drag and drop operation.
caretownercolor The Color used to paint the owner of the caret, if there is one. The caret owner is a special highlight that can be set using the setHighlights builtin that is defined in yoix.swing, but only if highlightflags explicitly allows a caret owner. Reading returns the current color. Writing immediately repaints the caret owner using the new color.
columns An int that specifies the number of columns in a textfield. Layout managers usually get the final say, so setting columns should be viewed as a request that will not always be honored. Reading returns the number of columns currently used by the textfield. Writing tries to immediately change the number of columns.
command A String that is assigned to the command field in the ActionEvent that is generated when the enter key is used within the field. The value stored in the textfield's text field is used when command is set to NULL.
cursor An Object that should be an int, Image, or String that selects the cursor shown when the pointer is over the textfield. A cursor that is an int should be one of the cursors defined in the yoix.awt.Cursor dictionary. A cursor that is an Image can describe the cursor using its size and hotspot fields and often draws it using its paint function. A cursor that is a String should be the name of a cursor that is already defined in yoix.awt.Cursor or the name a local a file or URL that contains a GIF or JPEG image that will be used as the cursor.

Reading returns the current cursor. Writing immediately changes the textfield's cursor to the new value. Storing STANDARD_CURSOR (the default) or NULL in cursor is special and means use the cursor assigned to the nearest component that contains the textfield and was assigned a cursor other than STANDARD_CURSOR; if no component qualifies the textfield uses TEXT_CURSOR.

doublebuffered An int that is 1 when the textfield uses double-buffering to draw itself, 0 when it does not, and starts with a default value that is selected by Java for the textfield. Reading returns the current double-buffering behavior. Writing immediately sets the textfield's double-buffering behavior to the new value. Note that double-buffering may be required when transparent components are used.
dragenabled An int that should be set to 1 when this textfield wants to use the automatic drag handling that Swing provides for some components, and 0 (the default) when it does not. Components that do not provide automatic drag handling always return 0 when their dragenabled field is read, so storing 1 in dragenabled should only be viewed as a request for a service that may not be available. Swing components can always take complete control of their drag and drop handling using their transferhandler field or special drag and drop event handlers.
echo An int that represents the character that is displayed in the textfield when the user types characters. A value of 0 means all typed characters appear. Reading returns the current echo character. Writing immediately changes the echo character to the new value. If the initial value of this field is 0, then the field becomes read-only, typed characters will always appear and, internally, a Java JTextField object is used to render the field. If the initial field value is non-zero, then changes to the value, including zero, can be made at any time and, internally, a Java JPasswordField object is used to render the field.
edit An int that is 1 when the contents of the textfield can be changed, and 0 otherwise. Reading returns the current edit flag. Writing immediately sets the textfield's edit flag to the new state.
enabled An Object that is 1 when the textfield can respond to user input, 0 when it can not respond, and NULL (the default) when the textfield inherits the value from the nearest lightweight container, like a JPanel, that contains the textfield and has its enabled field set to something other than NULL. The top-level application window that contains the textfield always gets the final say, so disabling that window always disables the textfield. Reading returns the current state. Writing immediately sets the textfield's state to the new value.
focusowner A read-only int that is non-zero when the textfield has the focus.
font The Font, or font name if it is a String, used to paint the characters stored in the text field. Reading returns a snapshot of the current font. Writing immediately repaints the text in the new font.
foreground The Color that is used to paint the characters stored in the text field. Reading returns a snapshot of the current color. Writing immediately repaints the text in the new color. Storing NULL in foreground is special and means use the foreground of the nearest component that contains the textfield and was assigned a foreground color other than NULL; if no component qualifies the textfield uses black.
highlightflags An int that controls special text highlighting capabilities that are available using the getHighlights and setHighlights builtins that are defined in yoix.swing. The two most common settings are 0 (all flags off) which is the default and produces normal behavior, and 0xFF (almost all flags on) which enables fancy things like multiple highlights (0x04) that are not changed by user actions (0x02) and are not removed when the focus changes (0x01). In addition one highlight can be marked as a caret (0x10) and different highlight can be marked as the owner of the caret (0x20), which restricts the movement of the caret to the bounds of its owner.
insets An Object, usually an Insets or Number, that describes the margins, in units of 72 dots per inch, that separate the textfield from its default border. This field is not automatically used when the textfield builds its own border. An insets that is a number is an easy way to describe a uniform margin. Writing immediately changes the margins that are drawn around the textfield by the default border.
layer An int, often a small number between 0 and 99, that identifies the depth of this textfield when it is added to a JLayeredPane or JDesktopPane. Components assigned to lower numbered layers are drawn before the components in higher numbered layers. Writing immediately changes the textfield's layer, which usually means the JLayeredPane or JDesktopPane that contains the textfield will be repainted.
location A Point that determines the location of the textfield in a coordinate system that has its origin at the upper left corner of the container closest to the textfield (in the component hierarchy) that actually contains it, positive x to the right, positive y down, and a resolution of 72 dots per inch. Reading returns a snapshot of the current location. Writing is allowed, but layout managers usually get the final say, so setting location should be viewed as a request that may not be honored.
modelToView(Number index) A Builtin that returns a Point that is the location of the character closest to index in text in a coordinate system that has its origin at the upper left corner of the textfield, positive x to the right, positive y down, and a resolution of 72 dots per inch.
nextfocus An Object that is the component that receives the focus after this textfield when the focus traverses from one component to the next (usually by means of the keyboard TAB character). A NULL value indicates that the default Java focus traversal is in effect. Reading returns the value last stored. Writing immediately sets the new focus traversal behavior.
opaque An Object that is 1 when the textfield is opaque, 0 when it is transparent, and NULL (the default) when the textfield inherits the value from the nearest component that contains the textfield and has its opaque field set to something other than NULL.
popup A JPopupMenu that is associated with the textfield. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the textfield's coordinate system specified by the popup menu's location field, assuming of course that the textfield is showing on the screen. Storing TRUE in the popup menu's visible field, which was added in release 1.2.0, is an easy way to show the popup menu that currently belongs to the textfield.
preferredsize A Dimension that is used by layout managers when they need to know the textfield's preferred size in units of 72 dots per inch. A NULL value means the textfield has no preference. A non-positive height or width is allowed and simply means the textfield has no preference for that dimension. Reading returns the current preferred size. Writing changes the preferred size and immediately notifies root.layoutmanager, which means the components contained in root may be repositioned and resized.
requestfocus An int that can be used to request or transfer the keyboard focus. Storing a non-zero value in requestfocus tries to get the focus. Storing 0 tries to transfer the focus. Reading requestfocus does not currently return any useful information.
requestfocusenabled An int that is 1 (the default) when actions, like mouse clicks or changes to the requestfocus field, can steal the keyboard focus and 0 when they can not. Note that this field does not affect acceptance of the keyboard focus during normal focus traversal. Reading returns the current state. Writing immediately sets the textfield's state to the new value.
root An Object that is automatically updated by the interpreter's layout machinery so it is always the top-level object that contains the textfield. For example, put a textfield in a panel and root will be set to that panel; add the panel to a frame and the textfield's root field will be set to that frame. A textfield's event handlers can use root when they need to interact with the other components in the container.
selected Reading returns a String with the currently selected text. Writing a String replaces the currently selected text with the supplied text. The insertion caret is left at the end of the added text.
selectedends An Array that contains entries that are used to set the starting and ending positions of the current selection. Writing NULL to selectedends clears the current selection, otherwise the first array element controls the start position, while the second element controls the end position. The starting position is either 0 or the integer value of the number at selectedends[0]. The ending position is either the length of the text string, which puts it just to the right of the last character, or the integer value of the number at selectedends[1]. Requesting an ending value that is less than or equal to the starting value also clears the current selection. Reading returns an Array of two integers that are the starting and ending positions of the current selection. When writing, the insertion caret is set to the end of the selection.
selectionbackground The Color used to highlight the selected text. Reading returns the current color. Writing immediately repaints the selected text using the new color.
selectionforeground The Color used to paint the characters of the text that has been selected. Reading returns the current color. Writing immediately repaints the selected text using the new color.
showing A read-only int that is non-zero when the textfield is showing on the screen.
size A Dimension that determines the size of the textfield in units of 72 dots per inch. Reading returns a snapshot of the current size. Writing is allowed, but layout managers usually get the final say, so setting size should be viewed as a request that may not be honored.
subtext([int offset[, int length]]) A built-in that returns the current text within the given range. When absent, offset defaults to the zero position and length defaults to the length from the offset to the end of the current text.
tag A String used to identify the textfield that is either supplied when the textfield is declared, or automatically generated otherwise. Add a textfield to a container, like a JFrame or JPanel, and the interpreter's layout machinery updates the root field so it points at the top-level container and then adds the textfield, as tag, to the root.components dictionary.
text A String of characters that is displayed in the textfield. Reading returns the current text. Writing immediately paints the new text.
tooltiptext A String of characters that is displayed in a tightly sized pop-up window that appears near the cursor whenever the cursor lingers over the textfield. Setting this value to NULL (the default) disables the tooltip mechanism. Reading returns the current tooltip text. Writing immediately sets the new tooltip text.
transferhandler An Object that should be a TransferHandler or String that determines how the textfield handles data transfer operations like drag and drop. A value that is a String but not "" means the field named by the String should be used as the source and sink of the data that is transferred by the textfield. The result is the same as assigning the String to the property field in a TransferHandler and then assigning that TransferHandler to transferhandler. The empty String "" is special and refers to the TransferHandler that Swing uses for automatic drag handling, if there is one.

Swing components that provide automatic drag handling start out with a transferhandler field that is not NULL, but the automatic drag handling is not enabled until 1 is stored in dragenabled. Swing components that provide their own drag and drop event handlers currently must store NULL in transferhandler before those event handlers will start working.

viewToModel(Point p) A Builtin that returns an int that is the index in text of the character that is closest to p, which should be a Point in a coordinate system that has its origin at the upper left corner of the textfield, positive x to the right, positive y down, and a resolution of 72 dots per inch. The location field in a MouseEvent is often used as the argument to viewToModel.
visible An int that is 1 when the textfield is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the textfield's visibility to the new state.
Several permanent fields have not been documented and should not be used in Yoix applications. Event handlers are functions that must be added to a textfield when it is declared. The handlers that work with textfields are listed below; the names should be familiar if you have done some Java programming. The itemStateChanged event handler is only for menus.
 
 Event Handlers:   actionPerformed, caretUpdate, componentHidden, componentMoved, componentResized, componentShown, dragDropEnd, dragEnter, dragExit, dragGestureRecognized, dragMouseMoved, dragOver, drop, dropActionChanged, focusGained, focusLost, invocationRun, itemStateChanged, keyPressed, keyReleased, keyTyped, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheelMoved, textValueChanged
 
 Example:   The program,
import yoix.*.*;

JDialog d = {
  int modal = TRUE;

  Dimension size = {
    double width = 4.0*72;
    double height = 2.0*72;
  };

  GridBagLayout layoutmanager;

  Array layout = {
    new JPanel {
      GridLayout layoutmanager = {
        int rows = 0;
        int columns = 2;
      };

      Array layout = {
        new JLabel {
            String text = "Name: ";
            int    alignment = RIGHT;
        },
        new JTextField {
          String tag = "name";
	  int    requestfocus = TRUE;
          int    columns = 12;

          focusGained(e) {
            root.components.failed.text = NULL;
          }
        },

        new JLabel {
          String text = "Password: ";
          int    alignment = RIGHT;
        },
        new JTextField {
          String tag = "password";
          int    columns = 12;
          int    echo = '*';

          focusGained(e) {
            root.components.failed.text = NULL;
          }

          actionPerformed(e) {
            if (!Validate(root.components.name.text, text)) {
              root.components.failed.text = "Login failed";
              root.components.failed.requestfocus = 1;
            }
          }
        },
      };
    },
    new GridBagConstraints {
      int gridwidth = REMAINDER;
      int insets = 16;
    },

    new JLabel {
      String tag = "failed";
      Color  foreground = Color.red;
      int    alignment = CENTER;
    },
    new GridBagConstraints {
      int gridwidth = REMAINDER;
    },
  };
};

Validate(String name, String pswd) {
 int result = 0;
 // do validation
 return(result);
}

d.visible = TRUE;
is a non-trivial example that shows how labels and textfields can be used to build a simple login dialog. We will leave the obvious missing pieces, like adding buttons, as an exercise.
 
 See Also:   appendText, BevelBorder, Border, deleteText, EmptyBorder, EtchedBorder, getHighlights, insertText, invokeLater, JButton, JCanvas, JCheckBox, JCheckBoxMenuItem, JChoice, JColorChooser, JComboBox, JDesktopPane, JDialog, JFileChooser, JFileDialog, JFrame, JInternalFrame, JLabel, JLayeredPane, JList, JMenu, JMenuBar, JMenuItem, JPanel, JPasswordField, JPopupMenu, JProgressBar, JRadioButton, JRadioButtonMenuItem, JScrollBar, JScrollPane, JSeparator, JSlider, JSplitPane, JTabbedPane, JTable, JTextArea, JTextCanvas, JTextPane, JTextTerm, JToggleButton, JToolBar, JTree, JWindow, LineBorder, MatteBorder, postEvent, replaceText, setHighlights, SoftBevelBorder, TransferHandler

 

Yoix is a registered trademark of AT&T Intellectual Property.