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

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
JScrollPane typedict
 
A JScrollPane represents a simple container that is implemented using the Java Swing JScrollPane class. It is used primarily to display a single child in a scrollable viewport, though additional component children can be supplied to provide scrollable row or column labelling and placement of components in the pane corners. Scrollpanes do not create windows, which means you only see them when they are in a visible JFrame, JDialog, or JWindow. Yoix programs normally interact with a JScrollPane using event handlers and by reading or writing the following fields:
background The Color that is used to paint the background of the scrollpane. It is also the default background color assigned to components in the layout array that do not pick their own. Reading returns a snapshot of the current color. Writing immediately sets the scrollpane's background, and the background of components contained in the scrollpane that do not pick their own, to the new color.
border An Object that should be a Border, Insets, Number, or String that describes the border that is drawn around this scrollpane. 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 scrollpane. A border that is a String is a quick way to surround this scrollpane with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the scrollpane's border to the new value.
components A Dictionary maintained by the interpreter's layout machinery that maps tag fields to actual components; every component contained in the scrollpane has an entry in the dictionary. Add the scrollpane to another container (e.g., a frame or panel) and entries in the components dictionary are copied into the new container's components dictionary. In addition, the root field in each component is automatically set to the top-level container, so the components dictionary is easy to find, and that means individual components can find each other by name using the root.components dictionary.
cursor An Object that should be an int, Image, or String that selects the cursor shown when the pointer is over the scrollpane. It is also the default cursor assigned to components in the scrollpane's layout array that do not pick their own. 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 sets the scrollpane's cursor, and the cursor of components contained in the scrollpane that do not pick their own, to the new value. A scrollpane that does not set its own cursor uses DEFAULT_CURSOR.

doublebuffered An int that is 1 when the scrollpane uses double-buffering to draw itself, 0 when it does not, and starts with a default value that is selected by Java for the scrollpane. Reading returns the current double-buffering behavior. Writing immediately sets the scrollpane'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 scrollpane 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.
enabled An Object that is 1 when the scrollpane can respond to user input, 0 when it can not respond, and NULL (the default) when the scrollpane inherits the value from the nearest lightweight container, like a JPanel, that contains the scrollpane and has its enabled field set to something other than NULL. The top-level application window that contains the scrollpane always gets the final say, so disabling that window always disables the scrollpane. Reading returns the current state. Writing immediately sets the scrollpane's state to the new value, which can also change the state of the components contained in the scrollpane.
focusowner A read-only int that is non-zero when the scrollpane has the focus.
font The Font, or font name if it is a String, that is used as the default font assigned to components in the layout array that do not pick their own. Reading returns a snapshot of the current font. Writing immediately changes the scrollpane's font, and the font used by all components contained in the scrollpane that do not pick their own, to the new font.
foreground The Color that is used as the default foreground color assigned to components in the layout array that do not pick their own. Reading returns a snapshot of the current color. Writing immediately sets the scrollpane's foreground, and the foreground of components contained in the scrollpane that do not pick their own, to the new color.
icon An Image that is displayed in the tab associated with the scrollpane when the scrollpane is put in a JTabbedPane. Reading returns a snapshot of the current icon. Writing immediately changes the icon displayed by the tab that a JTabbedPane associates with the scrollpane.
layer An int, often a small number between 0 and 99, that identifies the depth of this scrollpane 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 scrollpane's layer, which usually means the JLayeredPane or JDesktopPane that contains the scrollpane will be repainted.
layout An Array of objects, usually just a panel or large canvas, that the layoutmanager arranges in the scrollpane. Scrollpanes use a special-purpose layoutmanager which allows you to place column and row header components as well as corner components all in addition to the central viewport. When more than the central viewport is to be used, certain constants need to follow each component in the layout array. Use NORTH or TOP. for scrollable column header, WEST or LEFT, for a scrollable row header, and LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, NORTHEAST, NORTHWEST, SOUTHEAST or SOUTHWEST. the components that go in corners. When more than one component is placed in a scrollpane use CENTER to identify the component to be displayed in the scrollable viewport. Reading returns the current array. Writing immediately clears scrollpane and then arranges the new set of components in the scrollpane.
layoutmanager A LayoutManager that is permanently set to NULL, because scrollpanes use a special-purpose layout manager for placing its components. However, the scrollpane updates its own components dictionary, just like other layout managers, and makes sure the root field in each component is set to the top-level component containing the scrollpane. Writing is not allowed and will result in an invalidaccess error.
location A Point that determines the location of the scrollpane in a coordinate system that has its origin at the upper left corner of the container closest to the scrollpane (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.
nextfocus An Object that is the component that receives the focus after this scrollpane 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 scrollpane is opaque, 0 when it is transparent, and NULL (the default) when the scrollpane inherits the value from the nearest component that contains the scrollpane and has its opaque field set to something other than NULL. Changing a scrollpane's opaque field can immediately change the appearance of the components contained in the scrollpane.
popup A JPopupMenu that is associated with the scrollpane. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the scrollpane's coordinate system specified by the popup menu's location field, assuming of course that the scrollpane 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 scrollpane.
preferredsize A Dimension that is used by layout managers when they need to know the scrollpane's preferred size in units of 72 dots per inch. A NULL value means the scrollpane has no preference. A non-positive height or width is allowed and simply means the scrollpane 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 when actions, like mouse clicks or changes to the requestfocus field, can steal the keyboard focus and 0 (the default) 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 scrollpane'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 scrollpane. For example, put a scrollpane in a panel and root will be set to the panel; add that panel to a frame and the scrollpane's root field will be set to that frame. A scrollpane's event handlers can use root when they need to interact with the other components in the container.
scroll An int that controls the scrollbar display policy for the scrollpane. The value should normally be ALWAYS, AS_NEEDED, or NEVER, which are all defined in yoix.swing. More precise control is available by forming a bitwise combination of HORIZONTAL_ALWAYS, HORIZONTAL_AS_NEEDED, HORIZONTAL_NEVER, VERTICAL_ALWAYS, VERTICAL_AS_NEEDED or VERTICAL_NEVER, which are also defined in yoix.swing, and assigning that value to scroll. The same technique can be used in other Swing components, like a JTextArea or JTextPane, that handle their own scrolling.
showing A read-only int that is non-zero when the scrollpane is showing on the screen.
size A Dimension that determines the size of the scrollpane 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.
tag A String used to identify the scrollpane that is either supplied when the scrollpane is declared, or automatically generated otherwise. Add a scrollpane 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 scrollpane, as tag, to the root.components dictionary.
title A String that is the text that the tab associated with the scrollpane displays when the scrollpane is put in a JTabbedPane. Reading returns a snapshot of the current title. Writing immediately changes the text displayed by the tab that a JTabbedPane associates with the scrollpane.
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 scrollpane. 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 scrollpane 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 scrollpane. 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.

validate An int that is 1 when changing the layoutmanager field takes effect immediately, and 0 when the change is delayed, often until after the layout, size, or validate fields change. Storing a 1 in validate always runs Java's layout manager, even when nothing has changed.
visible An int that is 1 when the scrollpane is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the scrollpane'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 scrollpane when it is declared. The handlers that work with scrollpanes are listed below; the names should be familiar if you have done some Java programming. The actionPerformed and itemStateChanged event handlers are only for menus.
 
 Event Handlers:   actionPerformed, adjustmentValueChanged, 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
 
 Example:   The program,
import yoix.*.*;

JFrame f = {
    Dimension size = {
	int width = 200;
	int height = 200;
    };
    Array layout = {
	new JScrollPane {
	    String tag = "$_pane";
	    Color  background = Color.green;
	    int    scroll = AS_NEEDED;

	    Array layout = {
		new JPanel {
		    Dimension preferredsize = {
			int width = 400;
			int height = 400;
		    };
		    BorderLayout layoutmanager;
		    Array layout = {
			new JPanel {
			    Array layout = {
				new JLabel {
				    String text = "Hello world";
				    Color  background = Color.blue;
				    Color  foreground = Color.white;
				},
			    };
			}, CENTER,

			new JPanel {
			    GridLayout layoutmanager = {
				int rows = 2;
				int columns = 2;
			    };
			    Array layout = {
				new JButton {
				    String text = "Button One";
				    actionPerformed(e) {
					root.components.$_pane.scroll =
                                            VERTICAL_AS_NEEDED;
				    }
				},
				new JButton {
				    String text = "Button Two";
				},
				new JButton {
				    String text = "Button Three";
				    actionPerformed(e) {
					root.components.$_pane.scroll =
                                            AS_NEEDED;
				    }
				},
				new JButton {
				    String text = "Button Four";
				},
			    };
			}, SOUTH,
		    };
		}, CENTER,

		new JLabel {
		    String text = "A Column Header Label";
		}, NORTH,

		new JCanvas {
		    Color background = Color.pink;
		}, UPPER_RIGHT_CORNER,

		new JButton {
		    String text = "";
		    Color  background = Color.red;
		    actionPerformed(e) {
			exit(0);
		    }
		}, LOWER_RIGHT_CORNER,
	    };
	},
    };
};

f.visible = TRUE;
creates a garish display involving a scrollable panel with a scrollable column header, a pink upper-right corner and a red exit button in the lower-right corner. Pressing "Button One" removes the horizontal scrollbar while leaving the vertical scrollbar available as needed. Pressing "Button Three" restores the scrollbars to their original AS_NEEDED state. As you press the buttons or resize the frame, notice how the visibility of the header and corners are tied to the visibility of the scrollbars.
 
 See Also:   BevelBorder, Border, BorderLayout, BoxLayout, CardLayout, CustomLayout, EmptyBorder, EtchedBorder, FlowLayout, GridBagLayout, GridLayout, 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, JSeparator, JSlider, JSplitPane, JTabbedPane, JTable, JTextArea, JTextCanvas, JTextField, JTextPane, JTextTerm, JToggleButton, JToolBar, JTree, JWindow, LayoutManager, LineBorder, MatteBorder, postEvent, SoftBevelBorder, TransferHandler

 

Yoix is a registered trademark of AT&T Inc.