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
JToolBar typedict
 
A JToolBar represents a simple container that is implemented using the Java Swing JToolBar class. Toolbars 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 JToolBar using event handlers and by reading or writing the following fields:
background The Color that is used to paint the background of the toolbar. 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 toolbar's background, and the background of components contained in the toolbar 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 toolbar. 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 toolbar. A border that is a String is a quick way to surround this toolbar with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the toolbar'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 toolbar has an entry in the dictionary. Add the toolbar 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 toolbar. It is also the default cursor assigned to components in the toolbar'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 toolbar's cursor, and the cursor of components contained in the toolbar that do not pick their own, to the new value. A toolbar that does not set its own cursor uses DEFAULT_CURSOR.

doublebuffered An int that is 1 when the toolbar uses double-buffering to draw itself, 0 when it does not, and starts with a default value that is selected by Java for the toolbar. Reading returns the current double-buffering behavior. Writing immediately sets the toolbar'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 toolbar 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 toolbar can respond to user input, 0 when it can not respond, and NULL (the default) when the toolbar inherits the value from the nearest lightweight container, like a JPanel, that contains the toolbar and has its enabled field set to something other than NULL. The top-level application window that contains the toolbar always gets the final say, so disabling that window always disables the toolbar. Reading returns the current state. Writing immediately sets the toolbar's state to the new value, which can also change the state of the components contained in the toolbar.
floatable An int that is 1 (the default) when the toolbar can be dragged out of the window in which it appears and into a separate window or moved to a different position within its container, and 0 when it can not dragged or repositioned. Reading returns the current state. Writing immediately sets the toolbar's floatable state to the new value.
focusable An int that is non-zero (the default) when the toolbar can accept the keyboard focus and zero when it can not. Reading returns the toolbar's current focusable state. Writing immediately changes the toolbar's focusable state to the new value, which means the focus is automatically transferred if the new value is zero and the toolbar is the current focus owner.
focusowner A read-only int that is non-zero when the toolbar 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 toolbar's font, and the font used by all components contained in the toolbar 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 toolbar's foreground, and the foreground of components contained in the toolbar that do not pick their own, to the new color.
insets An Object, usually an Insets or Number, that describes the margins, in units of 72 dots per inch, that separate the toolbar from its default border. This field is not automatically used when the toolbar 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 toolbar by the default border.
layer An int, often a small number between 0 and 99, that identifies the depth of this toolbar 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 toolbar's layer, which usually means the JLayeredPane or JDesktopPane that contains the toolbar will be repainted.
layout An Array of Swing components and optional separation information that can be included as Numberss or Dimensions, that the layoutmanager arranges in the toolbar. Toolbars use a special-purpose layoutmanager arranges the components in layout in a row or column as determined by orientation. Reading returns the current array. Writing immediately clears toolbar and then arranges the new set of components in the toolbar.
layoutmanager A LayoutManager that is permanently set to NULL, because toolbars use a special-purpose layout manager for placing its components. However, the toolbar 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 toolbar. Writing is not allowed and will result in an invalidaccess error.
location A Point that determines the location of the toolbar in a coordinate system that has its origin at the upper left corner of the container closest to the toolbar (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 identifies the component that receives the focus after this toolbar when the focus traverses from one component to the next (usually by means of the keyboard TAB character). When nextfocus is a String it is assumed to be the tag associated with the target component, which must belong to the same top-level container (e.g., the same JFrame) as this toolbar. A NULL value means the component that gets the focus after this toolbar will be selected by Java's default focus traversal policy. Reading returns the value last stored or NULL if the value was a String that did not reference a component. Writing immediately changes the component that gets the focus after this toolbar.
opaque An Object that is 1 when the toolbar is opaque, 0 when it is transparent, and NULL (the default) when the toolbar inherits the value from the nearest component that contains the toolbar and has its opaque field set to something other than NULL. Changing a toolbar's opaque field can immediately change the appearance of the components contained in the toolbar. Unfortunately this field may not work properly on all versions of Java.
orientation An int that determines whether the components are arranged in a row or column. The value should be HORIZONTAL or VERTICAL which are defined in yoix.swing.
popup A JPopupMenu that is associated with the toolbar. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the toolbar's coordinate system specified by the popup menu's location field, assuming of course that the toolbar 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 toolbar.
preferredsize A Dimension that is used by layout managers when they need to know the toolbar's preferred size in units of 72 dots per inch. A NULL value means the toolbar has no preference. A non-positive height or width is allowed and simply means the toolbar 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 toolbar'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 toolbar. For example, put a toolbar in a panel and root will be set to the panel; add that panel to a frame and the toolbar's root field will be set to that frame. A toolbar's event handlers can use root when they need to interact with the other components in the container.
showing A read-only int that is non-zero when the toolbar is showing on the screen.
size A Dimension that determines the size of the toolbar 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 toolbar that is either supplied when the toolbar is declared, or automatically generated otherwise. Add a toolbar 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 toolbar, as tag, to the root.components dictionary.
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 toolbar. 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 toolbar 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 toolbar. 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 toolbar is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the toolbar'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 toolbar when it is declared. The handlers that work with toolbars 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, 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 = {
    Array layout = {
        new JToolBar {
            String tag = "$_bar";
            Color  background = Color.green;
            int    floatable = TRUE;

            Array layout = {
                new Dimension {
                    double height = 72;
                },
                new JButton {
                    String text = "Close";
                    String tooltiptext = "Hide for a few seconds";

                    actionPerformed(e) {
                        root.visible = FALSE;
                        sleep(3);
                        root.visible = TRUE;
                    }
                },
                72/18,
                new JButton {
                    String text = "Toggle";
                    String tooltiptext = "Change floatable state";

                    actionPerformed(e) {
                        root.ToggleFloatable();
                    }
                },
                2*72,
                new JButton {
                    String text = "Dismiss";

                    actionPerformed(e) {
                        exit(0);
                    }
                },
            };
        }, NORTH,
    };

    ToggleFloatable() {
        int state = components.$_bar.floatable;

        components.$_bar.floatable = !state;
    }
};

f.visible = TRUE;
puts three buttons in a toolbar and adds it to a frame. Press the close button and the frame will disappear for a few seconds; drag the toolbar out of the frame and into its own window before pressing the close and both windows will disappear.
 
 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, JScrollPane, JSeparator, JSlider, JSplitPane, JTabbedPane, JTable, JTextArea, JTextCanvas, JTextField, JTextPane, JTextTerm, JTree, JWindow, LayoutManager, LineBorder, MatteBorder, postEvent, SoftBevelBorder, TransferHandler

 

Yoix is a registered trademark of AT&T Inc.