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
JDesktopPane typedict
 
A JDesktopPane represents a simple container that is implemented using the Java Swing JDesktopPane class. It behaves more like a JLayeredPane than a JPanel because it lets you group components together, but it does not impose a structure on those components. Instead the components pick their own position and size using their location, size, and layer fields. The most important difference between a JDesktopPane and a JLayeredPane, is how JInternalFrames are handled, and in most situations you should use a JDesktopPane to manage JInternalFrames. In addition, a desktoppane can be used as a drawing canvas. Desktoppanes 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 JDesktopPane using event handlers and by reading or writing the following fields:
background The Color that is used to paint the background of the desktoppane. 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 desktoppane's background, and the background of components contained in the desktoppane that do not pick their own, to the new color.
backgroundhints An int that controls how backgroundimage is displayed in the desktoppane. The value should be one of SCALE_AREA, SCALE_DEFAULT, SCALE_FAST, SCALE_NONE, SCALE_REPLICATE, SCALE_SMOOTH, or SCALE_TILE, which are all defined in yoix.image. SCALE_NONE places the unscaled image in the upper left corner of the desktoppane, while SCALE_TILE (the default) tiles the entire desktoppane with the unscaled image. The other values select the algorithm used to scale backgroundimage so it fills the entire desktoppane. Reading returns the current hints. Writing immediately repaints the desktoppane using the new hints to display the background image.
backgroundimage An Object that should be an Image or String that identifies an image that is automatically displayed as part of the desktoppane's background in a way that is controlled by the value assigned to backgroundhints. A NULL value, which is the default, means there is no image. A backgroundimage that is a String should name a local a file or URL that contains a GIF or JPEG image. Reading returns the current image. Writing immediately repaints the desktoppane using the new image.
border An Object that should be a Border, Insets, Number, or String that describes the border that is drawn around this desktoppane. 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 desktoppane. A border that is a String is a quick way to surround this desktoppane with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the desktoppane'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 desktoppane has an entry in the dictionary. Add the desktoppane 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 desktoppane. It is also the default cursor assigned to components in the desktoppane'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 desktoppane's cursor, and the cursor of components contained in the desktoppane that do not pick their own, to the new value. A desktoppane that does not set its own cursor uses DEFAULT_CURSOR.

doublebuffered An int that is 1 when the desktoppane uses double-buffering to draw itself, 0 when it does not, and starts with a default value that is selected by Java for the desktoppane. Reading returns the current double-buffering behavior. Writing immediately sets the desktoppane'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 desktoppane 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 desktoppane can respond to user input, 0 when it can not respond, and NULL (the default) when the desktoppane inherits the value from the nearest lightweight container, like a JPanel, that contains the desktoppane and has its enabled field set to something other than NULL. The top-level application window that contains the desktoppane always gets the final say, so disabling that window always disables the desktoppane. Reading returns the current state. Writing immediately sets the desktoppane's state to the new value, which can also change the state of the components contained in the desktoppane.
focusowner A read-only int that is non-zero when the desktoppane 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 desktoppane's font, and the font used by all components contained in the desktoppane 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 desktoppane's foreground, and the foreground of components contained in the desktoppane that do not pick their own, to the new color.
frames A read-only Dictionary, something like components, that is maintained by the desktoppane and lists that JInternalFrames that are managed by the desktoppane. JInternalFrames that appear in layout are automatically added to frames, as are any that are indirectly assigned to the desktoppane using their desktop field.
graphics A Graphics object that defines properties and built-ins that are used to apply graphics operations to this desktoppane. Writing after a desktoppane has been created is not allowed and will result in an invalidaccess error.
icon An Image that is displayed in the tab associated with the desktoppane when the desktoppane 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 desktoppane.
layer An int, often a small number between 0 and 99, that identifies the depth of this desktoppane when it is added to a JLayeredPane or another JDesktopPane. Components assigned to lower numbered layers are drawn before the components in higher numbered layers. Writing immediately changes the desktoppane's layer, which usually means the JLayeredPane or JDesktopPane that contains this desktoppane will be repainted.
layout An Array of Swing components that the layoutmanager puts in the desktoppane. The most important difference between a JDesktopPane and a JLayeredPane is the fact that JInternalFrames listed in layout appear in frames rather than components. Reading returns the current array. Writing immediately clears desktoppane and then arranges the new set of components in the desktoppane.
layoutmanager A LayoutManager that is permanently set to NULL, because desktoppanes use a special-purpose layout manager for managing its components. JInternalFrames receive special treatment, but in all cases the layoutmanager does not impose a structure on the components listed in layout. Instead each component picks its own position and size using its location, size, and layer fields. The desktoppane 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 desktoppane, however JInternalFrames receive special treatment and they are not listed in components, but instead are added to the frames dictionary. Writing is not allowed and will result in an invalidaccess error.
location A Point that determines the location of the desktoppane in a coordinate system that has its origin at the upper left corner of the container closest to the desktoppane (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 desktoppane 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 desktoppane is opaque, 0 when it is transparent, and NULL (the default) when the desktoppane inherits the value from the nearest component that contains the desktoppane and has its opaque field set to something other than NULL. Changing a desktoppane's opaque field can immediately change the appearance of the components contained in the desktoppane.
paint([Rectangle rect]) A Function that is called, if it is not NULL, whenever the desktoppane needs to be painted. The optional rect argument describes the rectangle that needs repainting in the coordinate system specified by graphics.CTM, which by default has its origin at the desktoppane's upper left corner, positive x to the right, positive y down, and a resolution of 72 dots per inch.
popup A JPopupMenu that is associated with the desktoppane. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the desktoppane's coordinate system specified by the popup menu's location field, assuming of course that the desktoppane 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 desktoppane.
preferredsize A Dimension that is used by layout managers when they need to know the desktoppane's preferred size in units of 72 dots per inch. A NULL value means the desktoppane has no preference. A non-positive height or width is allowed and simply means the desktoppane 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.
repaint([int immediate]) A Builtin that tells the desktoppane to completely repaint itself, which means the background is regenerated and then the desktoppane's paint function is called. If the optional immediate argument is non-zero the repaint request is handled immediately rather than being queued as an event that is processed later. Obviously repaint should not be called, either directly or indirectly, from the desktoppane's paint function, however erasedrawable is safe because it does not trigger a paint call.
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 desktoppane'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 desktoppane. For example, put a desktoppane in another desktoppane and root will be set to the top-level desktoppane; add the top-level desktoppane to a frame and the original desktoppane's root field will be set to that frame. A desktoppane's event handlers can use root when they need to interact with the other components in the container.
selected The JInternalFrame that is currently active, which is NULL when there is no active frame.
showing A read-only int that is non-zero when the desktoppane is showing on the screen.
size A Dimension that determines the size of the desktoppane 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 desktoppane that is either supplied when the desktoppane is declared, or automatically generated otherwise. Add a desktoppane to a container, like a JFrame or even another JPanel, and the interpreter's layout machinery updates the root field so it points at the top-level container and then adds the desktoppane, as tag, to the root.components dictionary.
title A String that is the text that the tab associated with the desktoppane displays when the desktoppane 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 desktoppane.
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 desktoppane. 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 desktoppane 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 desktoppane. 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 desktoppane is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the desktoppane'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 desktoppane when it is declared. The handlers that work with desktoppanes 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 = {
    String title = "JDesktopPane Test";

    Array layout = {
        new JDesktopPane {
            String tag = "$_desktop";
            Color  background = Color.yellow;
            int    counter;

            JPopupMenu popup = {
                String text = "Popup Menu";

                Menu items = {
                    "Small Frame", "small_frame",
                    "Big Frame", "big_frame",
                    "-", NULL,
                    "Exit", "exit",
                };
            };

            Array layout = {
                new JLabel {
                    String tag = "$_label";
                    String text = "Use popup menu to create frames";
                    String font = "Ludida-bold-12";
                    Color  foreground = red;

                    Point location = {
                        double x = 72;
                        double y = 72;
                    };
                },
            };

            mousePressed(e) {
                if (e.popuptrigger)
                    ShowPopupAt(e.location);
            }

            mouseReleased(e) {
                if (e.popuptrigger)
                    ShowPopupAt(e.location);
            }

            ShowPopupAt(Point location) {
                components.$_label.visible = FALSE;
                popup.location = location;
                popup.visible = TRUE;
            }

            actionPerformed(e) {
                Object desktop = root.components.$_desktop;
                Object frame;

                switch (e.command) {
                    case "small_frame":
                        frame = new JInternalFrame {
                            Dimension size = {
                                double width = 4*72;
                                double height = 3*72;
                            };

                            Point location = {
                                double x = 18*desktop.counter;
                                double y = 18*desktop.counter++;
                            };
                        };
                        break;

                    case "big_frame":
                        frame = new JInternalFrame {
                            Dimension size = desktop.size;
                        };
                        break;

                    case "exit":
                        exit(0);
                        break;
                }

                if (frame != NULL) {
                    frame.desktop = desktop;
                    frame.visible = TRUE;
                }
            }
        }, CENTER,
    };
};

f.visible = TRUE;
puts a JDesktopPane in JFrame and lets you use a popup menu to create JInternalFrames.
 
 See Also:   BevelBorder, Border, BorderLayout, BoxLayout, CardLayout, CustomLayout, EmptyBorder, EtchedBorder, FlowLayout, GridBagLayout, GridLayout, invokeLater, JButton, JCanvas, JCheckBox, JCheckBoxMenuItem, JChoice, JColorChooser, JComboBox, 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, JToggleButton, JToolBar, JTree, JWindow, LayoutManager, LineBorder, MatteBorder, postEvent, SoftBevelBorder, TransferHandler

 

Yoix is a registered trademark of AT&T Inc.