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
JCanvas typedict
 
A JCanvas is a convenience type for drawing much like the AWT Canvas component, but it is implemented using the Java Swing JPanel class. Though in many instances one could simply use the Yoix JPanel type in lieu of a JCanvas, having a separate type for drawing is conceptually clearer and also makes conversion from AWT to Swing scripts easier. Yoix programs normally interact with a JCanvas using event handlers and by reading or writing the following fields:
background The Color that is used to paint the background of the canvas. 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 canvas and was assigned a background color other than NULL; if no component qualifies the canvas uses VM.screen.background.
backgroundhints An int that controls how backgroundimage is displayed in the canvas. 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 canvas, while SCALE_TILE (the default) tiles the entire canvas with the unscaled image. The other values select the algorithm used to scale backgroundimage so it fills the entire canvas. Reading returns the current hints. Writing immediately repaints the canvas 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 canvas'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 canvas 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 canvas. A NULL value, which is the default, means no border. A border that is an Insets or Number is handled differently than most other Swing components, because it is used, in combination with the insets field, to set the extent of the highlighted border, in units of 72 dots per inch, that is drawn around the canvas. A border that is a String is a quick way to surround this canvas with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the canvas's border to the new value.
bordercolor The base Color that is used to pick the shadow colors for the highlighted border. The canvas's background is used when bordercolor is NULL. Reading returns a snapshot of the current color. Writing immediately changes the bordercolor to the new color.
buttonmask An int that indicates which mouse button (or buttons) are accepted to trigger an action when the canvas is being used as a custom button. Acceptable value, which can be OR'ed together, are BUTTON1_MASK, BUTTON2_MASK or BUTTON3_MASK, which are defined in yoix.swing. The default mask is BUTTON1_MASK.
cursor An Object that should be an int, Image, or String that selects the cursor shown when the pointer is over the canvas. 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 canvas'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 canvas and was assigned a cursor other than STANDARD_CURSOR; if no component qualifies the canvas uses DEFAULT_CURSOR.

doublebuffered An int that is 1 when the canvas uses double-buffering to draw itself, 0 when it does not, and starts with a default value that is selected by Java for the canvas. Reading returns the current double-buffering behavior. Writing immediately sets the canvas'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 canvas 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 canvas can respond to user input, 0 when it can not respond, and NULL (the default) when the canvas inherits the value from the nearest lightweight container, like a JPanel, that contains the canvas and has its enabled field set to something other than NULL. The top-level application window that contains the canvas always gets the final say, so disabling that window always disables the canvas. Reading returns the current state. Writing immediately sets the canvas's state to the new value.
focusowner A read-only int that is non-zero when the canvas has the focus.
font The Font, or font name if it is a String, that is used as the canvas's font. Reading returns a snapshot of the current font. Writing immediately sets the canvas's font to the new value.
foreground The Color that is used as the foreground of the canvas. Reading returns a snapshot of the current color. Writing immediately sets the canvas's foreground to the new color. Storing NULL in foreground is special and means use the foreground of the nearest component that contains the canvas and was assigned a foreground color other than NULL; if no component qualifies the canvas uses VM.screen.foreground.
graphics A Graphics object that defines properties and built-ins that are used to apply graphics operations to this canvas. Writing after a canvas has been created is not allowed and will result in an invalidaccess error.
layer An int, often a small number between 0 and 99, that identifies the depth of this canvas 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 canvas's layer, which usually means the JLayeredPane or JDesktopPane that contains the canvas will be repainted.
location A Point that determines the location of the canvas in a coordinate system that has its origin at the upper left corner of the container closest to the canvas (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 canvas 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 canvas is opaque, 0 when it is transparent, and NULL (the default) when the canvas inherits the value from the nearest component that contains the canvas and has its opaque field set to something other than NULL.
paint([Rectangle rect]) A Function that is called, if it is not NULL, whenever the canvas 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 canvas'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 canvas. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the canvas's coordinate system specified by the popup menu's location field, assuming of course that the canvas 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 canvas.
preferredsize A Dimension that is used by layout managers when they need to know the canvas's preferred size in units of 72 dots per inch. A NULL value means the canvas has no preference. A non-positive height or width is allowed and simply means the canvas 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() A Builtin that tells the canvas to completely repaint itself, which means the background is regenerated and then the canvas's paint function is called. Obviously repaint should not be called, either directly or indirectly, from the canvas'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 (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 canvas'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 canvas. For example, put a canvas in a panel and root will be set to that panel; add the panel to a frame and the canvas's root field will be set to that frame. A canvas'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 canvas is showing on the screen.
size A Dimension that determines the size of the canvas 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.
state An int that controls how the border of the canvas, if there is one, is drawn. When state is 0 the left and top parts of the border are drawn in a brighter color than the right and bottom parts, which makes it look like the interior of the canvas is raised. The border colors are reversed when state is 1, which makes it look like the interior of the canvas is depressed.
sticky An int which is 1 when a change of state from 0 to 1 caused by a mouse press will not reset to 0 at mouse release. This feature provides a way to simulate check box or radio button behavior with a JCanvas.
tag A String used to identify the canvas that is either supplied when the canvas is declared, or automatically generated otherwise. Add a canvas 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 canvas, 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 canvas. 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 canvas 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 canvas. 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.

visible An int that is 1 when the canvas is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the canvas'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 canvas when it is declared. The handlers that work with canvases are listed below; the names should be familiar if you have done some Java programming.
 
 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 = {
    FlowLayout layoutmanager = {
        int hgap = 72/4;
        int vgap = 72;
    };

    Array layout = {
        new JCanvas {
            Color background = {double red = .5;};
            int   border = 72/12;
            int   state = FALSE;

            Dimension size = {
                int height = 72;
                int width = 2*72;
            };
        },
        new JCanvas {
            Color background = {double green = .5;};
            int   border = 72/12;
            int   state = TRUE;

            Dimension size = {
                int height = 72;
                int width = 72;
            };
        },

        new JCanvas {
            Color background = Color.blue;
            Dimension preferredsize = {
                int height = 36;
                int width = 72;
            };
        },
    };
};

f.visible = TRUE;
sleep(5);
f.visible = FALSE;
shows three canvases in a frame, but only for a few seconds.

The next program,

import yoix.*.*;

final double SHADOW = 72.0/36;

Image att = {
    String source = "http://www.yoix.org/imgs/ATTlogo.gif";
};

JCanvas c = {
    double border = SHADOW;
    Color  background = Color.gray;
    Image  backgroundimage = att;
    int    backgroundhints = SCALE_DEFAULT;
    int    state = FALSE;

    Dimension size = {
        double width = att.size.width + 2*SHADOW;
        double height = att.size.height + 2*SHADOW;
    };

    actionPerformed(ActionEvent e) {
        printf("URL=%s\n", att.source);
    }
};

JFrame f = {
    FlowLayout layoutmanager = {
        int vgap = 72;
    };

    Array layout = {c};
};

f.visible = TRUE;
sleep(5);
exit(0);
shows how to build a custom button out of a canvas that displays an image rather than a text string.
 
 See Also:   BevelBorder, Border, EmptyBorder, EtchedBorder, invokeLater, JButton, 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, JToggleButton, JToolBar, JTree, JWindow, LineBorder, MatteBorder, postEvent, SoftBevelBorder, TransferHandler

 

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