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.
| | focusable |
An
int
that is non-zero (the default)
when the desktoppane can accept the keyboard focus and zero
when it can not.
Reading returns the desktoppane's current focusable state.
Writing immediately changes the desktoppane's focusable state to the new value,
which means the focus is automatically transferred if the new value is zero
and the desktoppane is the current focus owner.
| | 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 identifies 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).
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 desktoppane.
A
NULL
value means the component that gets the focus after this desktoppane 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 desktoppane.
| | 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
|
|
