com.datagis.com4j

Interface NativeWindow

All Superinterfaces:

Disposable

All Known Implementing Classes:

GenericNativeWindow, Map3DWindow

public interface NativeWindow
extends Disposable

A NativeWindow is a top-level native window with a title and a border.

The size of the native window includes any area designated for the border. The dimensions of the border area may be obtained using the getInsets method, however, since these dimensions are platform-dependent, a valid insets value cannot be obtained until the native window is displayed by calling setVisible. Since the border area is included in the overall size of the frame, the border effectively obscures a portion of the frame, constraining the area available for rendering and/or displaying subcomponents to the rectangle which has an upper-left corner location of (insets.left, insets.top), and has a size of width - (insets.left + insets.right) by height - (insets.top + insets.bottom).

A native window may have its native decorations (i.e. Frame and Titlebar) turned off with setUndecorated. In contrast to Java AWT frames, this can not only be done while the frame is not displayed, but regardless or whether the window is displayer or not.

In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, the bounds of all configurations are relative to the virtual-coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device, negative coordinates are possible, as shown in the following figure.

In such an environment, when calling setLocation, you must pass a virtual coordinate to this method. Similarly, calling getLocationOnScreen on a NativeWindow returns virtual device coordinates.

Native windows are capable of generating the following types of NativeWindowEvents:

• WINDOW_OPENED
• WINDOW_CLOSING:
  If the program doesn't explicitly hide or dispose the window while processing this event, the window close operation is canceled.
• WINDOW_CLOSED
• WINDOW_ICONIFIED
• WINDOW_DEICONIFIED
• WINDOW_ACTIVATED
• WINDOW_DEACTIVATED
• WINDOW_GAINED_FOCUS
• WINDOW_LOST_FOCUS
• WINDOW_STATE_CHANGED

Since a native window somehow combines the features, which are provided though the distinct Java objects

• java.awt.Component,
• java.awt.Container,
• java.awt.Window,
• java.awt.Frame,

it also may generate four additional events, which in Java are generated by java.awt.Component. The numeric values of these constants are these defined in java.awt.ComponentEvent.

• WINDOW_MOVED = ComponentEvent.COMPONENT_MOVED
• WINDOW_RESIZED = ComponentEvent.COMPONENT_RESIZED
• WINDOW_SHOWN = ComponentEvent.COMPONENT_SHOWN
• WINDOW_HIDDEN = ComponentEvent.COMPONENT_HIDDEN

A native COM window consists of two distinct parts, which are provided through two distinct interfaces in COM and two classes in Java. One class is this abstract GenericNativeWindow class, which implements the NativeWindow interface, and the other class is the actual descendant of this class. The latter provides the methods that deal with the capabilities and functions implemented in the native window, the first deals with the window itself. Since the functional class derives from this class, it actually provides all the methods available for the native window.

Since:

TEJ1.0

Author:

Carsten Klein

See Also:

GenericNativeWindow

Field Summary

Fields

Modifier and Type	Field and Description
static int	ICONIFIED This state bit indicates that the native window is iconified.
static int	MAXIMIZED_BOTH This state bit mask indicates that the native window is fully maximized (that is both horizontally and vertically).
static int	MAXIMIZED_HORIZ This state bit indicates that the native window is maximized in the horizontal direction.
static int	MAXIMIZED_VERT This state bit indicates that the native window is maximized in the vertical direction.
static int	NORMAL The native window is in the "normal" state.

Method Summary

Modifier and Type	Method and Description
void	addNativeWindowListener(NativeWindowListener listener) Adds the specified native window listener to receive window events from the underlying native window.
void	dispose() Releases the reference to the underlying native window represented by this NativeWindow object.
Color	getBackground() Gets the background color of this native window.
Rectangle	getBounds() Gets the bounds of this native window in the form of a Rectangle object.
Rectangle	getBounds(Rectangle rv) Stores the bounds of this native window into "return value" rv and return rv.
int	getExtendedState() Gets the state of this native window.
int	getHeight() Returns the current height of this native window.
Insets	getInsets() Determines the insets of this native window, which indicate the size of the window's border.
Point	getLocation() Gets the location of this native window in the form of a point specifying the native window's top-left corner.
Point	getLocation(Point rv) Stores the x,y origin of this native window into "return value" rv and return rv.
Point	getLocationOnScreen() Gets the location of this native window in the form of a point specifying the native window's top-left corner in the screen's coordinate space.
String	getName() Returns the native name of the window.
NativeWindowListener[]	getNativeWindowListeners() Returns an array of all the native window listeners registered on this NativeWindow instance.
Container	getParent() Gets the parent of this component.
Dimension	getSize() Returns the size of this native window in the form of a Dimension object.
Dimension	getSize(Dimension rv) Stores the width/height of this native window into "return value" rv and return rv.
int	getState() Gets the state of this native window (obsolete).
String	getTitle() Gets the title of this native window.
int	getWidth() Returns the current width of this native window.
int	getX() Returns the current x coordinate of the native window's origin.
int	getY() Returns the current y coordinate of the native window's origin.
boolean	isActive() Returns whether this native window is active.
boolean	isAlwaysOnTop() Returns whether this native window is an always-on-top window.
boolean	isDisposed() Indicates whether the underlying native window is already disposed.
boolean	isEnabled() Determines whether this native window is enabled.
boolean	isFocused() Returns whether this native window is focused.
boolean	isNativeWindowListener(NativeWindowListener listener) Indicates whether the specified native window listener listener is registered on this NativeWindow instance.
boolean	isResizable() Indicates whether this native window is resizable by the user.
boolean	isShowing() Determines whether this component is native window on screen.
boolean	isUndecorated() Indicates whether this native window is undecorated.
boolean	isVisible() Indicates whether this native window is visible.
void	removeNativeWindowListener(NativeWindowListener listener) Removes the specified native window listener, so that it no longer receives window events from the underlying native window.
void	requestFocus() Requests that this native window become the focused window.
void	setAlwaysOnTop(boolean alwaysOnTop) Changes the always-on-top window state of this native window.
void	setBackground(Color c) Sets the background color of this native window.
void	setBackground(NativeSystemColor c) Sets the background color of this native window.
void	setBounds(int x, int y, int width, int height) Moves and resizes this native window.
void	setBounds(Point p, Dimension d) Moves and resizes this native window.
void	setBounds(Rectangle r) Moves and resizes this native window to conform to the new bounding rectangle r.
void	setEnabled(boolean enabled) Enables or disables this native window, depending on the value of the parameter enabled.
void	setExtendedState(int state) Sets the state of this frame.
void	setLocation(int x, int y) Moves this native window to a new location.
void	setLocation(Point p) Moves this native window to a new location.
void	setResizable(boolean resizable) Sets whether this native window is resizable by the user.
void	setSize(Dimension d) Resizes this native window so that it has width d.width and height d.height.
void	setSize(int width, int height) Resizes this native window so that it has width width and height height.
void	setState(int state) Sets the state of this native window (obsolete).
void	setTitle(String title) Sets the title for this native window to the specified string.
void	setUndecorated(boolean undecorated) Disables or enables decorations for this native window.
void	setVisible(boolean visible) Shows or hides this native window depending on the value of parameter visible.
void	toBack() If this native window is visible, sends this native window to the back and may cause it to lose focus or activation if it is the focused or active window.
void	toFront() If this native window is visible, brings this native window to the front and may make it the focused window.

Field Detail

NORMAL

static final int NORMAL

The native window is in the "normal" state. This symbolic constant names a frame state with all state bits cleared.

See Also:

setExtendedState(int), getExtendedState(), Constant Field Values

ICONIFIED

static final int ICONIFIED

This state bit indicates that the native window is iconified.

See Also:

setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_HORIZ

static final int MAXIMIZED_HORIZ

This state bit indicates that the native window is maximized in the horizontal direction.

See Also:

setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_VERT

static final int MAXIMIZED_VERT

This state bit indicates that the native window is maximized in the vertical direction.

See Also:

setExtendedState(int), getExtendedState(), Constant Field Values

MAXIMIZED_BOTH

static final int MAXIMIZED_BOTH

This state bit mask indicates that the native window is fully maximized (that is both horizontally and vertically). It is just a convenience alias for MAXIMIZED_VERT | MAXIMIZED_HORIZ.

Note that the correct test for the native window being fully maximized is

 (state & GenericNativeWindow.MAXIMIZED_BOTH) == GenericNativeWindow.MAXIMIZED_BOTH
 

To test if the native window is maximized in some direction use

 (state & GenericNativeWindow.MAXIMIZED_BOTH) != 0
 

See Also:

setExtendedState(int), getExtendedState(), Constant Field Values

Method Detail

getName

String getName()

Returns the native name of the window.

Returns:

the native name of the window

getTitle

String getTitle()

Gets the title of this native window. The title is displayed in the window's border.

Returns:

the title of this native window, or an empty string ("") if this window doesn't have a title.

See Also:

setTitle(java.lang.String)

setTitle

void setTitle(String title)

Sets the title for this native window to the specified string.

Parameters:

title - the title to be displayed in the window's border. A null value is treated as an empty string, "".

See Also:

getTitle()

getX

int getX()

Returns the current x coordinate of the native window's origin. This method is preferable to writing window.getBounds().x, or window.getLocation().x because it doesn't cause any heap allocations.

Returns:

the current x coordinate of the native window's origin

getY

int getY()

Returns the current y coordinate of the native window's origin. This method is preferable to writing window.getBounds().y, or window.getLocation().y because it doesn't cause any heap allocations.

Returns:

the current y coordinate of the native window's origin

getWidth

int getWidth()

Returns the current width of this native window. This method is preferable to writing window.getBounds().width, or window.getSize().width because it doesn't cause any heap allocations.

Returns:

the current width of this native window

getHeight

int getHeight()

Returns the current height of this native window. This method is preferable to writing window.getBounds().height, or window.getSize().height because it doesn't cause any heap allocations.

Returns:

the current height of this native window

getParent

Container getParent()

Gets the parent of this component. Since native window is a top-level component, this method will always return null.

Returns:

the parent container of this component

isShowing

boolean isShowing()

Determines whether this component is native window on screen. This means that the component must be visible.

Returns:

true if this native window is showing, false otherwise

See Also:

setVisible(boolean)

isVisible

boolean isVisible()

Indicates whether this native window is visible.

Returns:

true if this native window is visible, false otherwise

See Also:

setVisible(boolean)

setVisible

void setVisible(boolean visible)

Shows or hides this native window depending on the value of parameter visible.

Parameters:

visible - if true, shows this native window; otherwise, hides this native window

See Also:

isVisible()

getBounds

Rectangle getBounds()

Gets the bounds of this native window in the form of a Rectangle object. The bounds specify this native window's width, height, and location relative to its parent.

Returns:

a rectangle indicating this native window's bounds

See Also:

setBounds(int, int, int, int), getLocation(java.awt.Point), getSize()

getBounds

Rectangle getBounds(Rectangle rv)

Stores the bounds of this native window into "return value" rv and return rv. If rv is null a new Rectangle is allocated. This version of getBounds is useful if the caller wants to avoid allocating a new Rectangle object on the heap.

Parameters:

rv - the return value, modified to the native window's bounds

Returns:

rv the bounds of the native window

setBounds

void setBounds(int x,
               int y,
               int width,
               int height)

Moves and resizes this native window. The new location of the top-left corner is specified by x and y, and the new size is specified by width and height.

Parameters:

x - the new x-coordinate of this native window

y - the new y-coordinate of this native window

width - the new width of this native window

height - the new height of this native window

See Also:

getBounds(), setLocation(int, int), setLocation(Point), setSize(int, int), setSize(Dimension)

setBounds

void setBounds(Rectangle r)

Moves and resizes this native window to conform to the new bounding rectangle r. This native window's new position is specified by r.x and r.y, and its new size is specified by r.width and r.height

Parameters:

r - the new bounding rectangle for this component

See Also:

getBounds(), setLocation(int, int), setLocation(Point), setSize(int, int), setSize(Dimension)

setBounds

void setBounds(Point p,
               Dimension d)

Moves and resizes this native window. The new location of the top-left corner is specified by p.x and p.y, and the new size is specified by d.width and d.height.

Parameters:

p - the point defining the top-left corner of the new location

d - the dimension specifying the new size of this component

See Also:

getBounds(), setLocation(int, int), setLocation(Point), setSize(int, int), setSize(Dimension)

getLocation

Point getLocation(Point rv)

Stores the x,y origin of this native window into "return value" rv and return rv. If rv is null a new Point is allocated. This version of getLocation is useful if the caller wants to avoid allocating a new Point object on the heap.

Parameters:

rv - the return value, modified to the native window's location

Returns:

the location of the native window

getLocation

Point getLocation()

Gets the location of this native window in the form of a point specifying the native window's top-left corner. The location will be relative to the parent's coordinate space.

Returns:

an instance of Point representing the top-left corner of the native window's bounds in the coordinate space of the native window's parent

See Also:

setLocation(int, int), getLocationOnScreen()

getLocationOnScreen

Point getLocationOnScreen()

Gets the location of this native window in the form of a point specifying the native window's top-left corner in the screen's coordinate space.

Returns:

an instance of Point representing the top-left corner of the native window's bounds in the coordinate space of the screen

See Also:

setLocation(int, int), getLocation(java.awt.Point)

setLocation

void setLocation(int x,
                 int y)

Moves this native window to a new location. The top-left corner of the new location is specified by the x and y parameters in the coordinate space of this native window's parent.

Parameters:

x - the x-coordinate of the new location's top-left corner in the parent's coordinate space

y - the y-coordinate of the new location's top-left corner in the parent's coordinate space

See Also:

getLocation(java.awt.Point), setBounds(int, int, int, int)

setLocation

void setLocation(Point p)

Moves this native window to a new location. The top-left corner of the new location is specified by point p. Point p is given in the parent's coordinate space.

Parameters:

p - the point defining the top-left corner of the new location, given in the coordinate space of this native window's parent

See Also:

getLocation(java.awt.Point), setBounds(int, int, int, int)

getSize

Dimension getSize()

Returns the size of this native window in the form of a Dimension object. The height field of the Dimension object contains this native window's height, and the width field of the Dimension object contains this native window's width.

Returns:

a Dimension object that indicates the size of this native window

See Also:

setSize(int, int)

getSize

Dimension getSize(Dimension rv)

Stores the width/height of this native window into "return value" rv and return rv. If rv is null a new Dimension object is allocated. This version of getSize is useful if the caller wants to avoid allocating a new Dimension object on the heap.

Parameters:

rv - the return value, modified to the native window's size

Returns:

the size of the native window

setSize

void setSize(int width,
             int height)

Resizes this native window so that it has width width and height height.

Parameters:

width - the new width of this native window in pixels

height - the new height of this native window in pixels

See Also:

getSize(), setBounds(int, int, int, int)

setSize

void setSize(Dimension d)

Resizes this native window so that it has width d.width and height d.height.

Parameters:

d - the dimension specifying the new size of this native window

See Also:

setSize(int, int), setBounds(int, int, int, int)

isEnabled

boolean isEnabled()

Determines whether this native window is enabled. An enabled native window can respond to user input and generate events. Native windows are enabled initially by default. A native window may be enabled or disabled by calling its setEnabled method.

Returns:

true if the native window is enabled; false otherwise

See Also:

setEnabled(boolean)

setEnabled

void setEnabled(boolean enabled)

Enables or disables this native window, depending on the value of the parameter enabled. An enabled native window can respond to user input and generate events. Native windows are enabled initially by default.

Parameters:

enabled - if true, this native window is enabled; otherwise this native window is disabled

See Also:

isEnabled()

getBackground

Color getBackground()

Gets the background color of this native window.

Returns:

this native window's background color

See Also:

setBackground(java.awt.Color)

setBackground

void setBackground(Color c)

Sets the background color of this native window.

Parameters:

c - the color to become this native window's color; if this parameter is null, then this native window will get the operation system's default window background color

See Also:

getBackground()

setBackground

void setBackground(NativeSystemColor c)

Sets the background color of this native window.

Parameters:

c - the color to become this native window's color; if this parameter is null, then this native window will get the operation system's default window background color

See Also:

getBackground()

getExtendedState

int getExtendedState()

Gets the state of this native window. The state is represented as a bitwise mask.

• NORMAL
  Indicates that no state bits are set.
• ICONIFIED
• MAXIMIZED_HORIZ
• MAXIMIZED_VERT
• MAXIMIZED_BOTH
  Concatenates MAXIMIZED_HORIZ and MAXIMIZED_VERT.

Returns:

a bitwise mask of the native window state constants

See Also:

setExtendedState(int)

setExtendedState

void setExtendedState(int state)

Sets the state of this frame. The state is represented as a bitwise mask.

• NORMAL
  Indicates that no state bits are set.
• ICONIFIED
• MAXIMIZED_HORIZ
• MAXIMIZED_VERT
• MAXIMIZED_BOTH
  Concatenates MAXIMIZED_HORIZ and MAXIMIZED_VERT.

Note that if the state is not supported on a given platform, nothing will happen. The application may determine if a specific state is available via the java.awt.Toolkit#isFrameStateSupported(int state) method.

Parameters:

state - a bitwise mask of frame state constants

See Also:

getExtendedState(), Toolkit.isFrameStateSupported(int)

getState

int getState()

Gets the state of this native window (obsolete).

For compatibility with old programs this method still returns GenericNativeWindow.NORMAL and GenericNativeWindow.ICONIFIED but it only reports the iconic state of the native window, other aspects of native window state are not reported by this method.

Returns:

GenericNativeWindow.NORMAL or GenericNativeWindow.ICONIFIED.

See Also:

setState(int), getExtendedState()

setState

void setState(int state)

Sets the state of this native window (obsolete).

For compatibility with old programs this method still accepts GenericNativeWindow.NORMAL and GenericNativeWindow.ICONIFIED but it only changes the iconic state of the native window, other aspects of native window state are not affected by this method.

Parameters:

state - either GenericNativeWindow.NORMAL or GenericNativeWindow.ICONIFIED.

See Also:

getState(), setExtendedState(int)

isAlwaysOnTop

boolean isAlwaysOnTop()

Returns whether this native window is an always-on-top window.

Returns:

true, if this native window is in always-on-top state, false otherwise

See Also:

setAlwaysOnTop(boolean)

setAlwaysOnTop

void setAlwaysOnTop(boolean alwaysOnTop)

Changes the always-on-top window state of this native window. An always-on-top window is a window that stays above all other windows except maybe other always-on-top windows. If there are several always-on-top windows the order in which they stay relative to each other is not specified and is platform dependent.

If some other window already is always-on-top then the relative order between these windows is unspecified (depends on platform). No window can be brought to be over always-on-top window except maybe another always-on-top window.

This method makes this native window always-on-top if alwaysOnTop is true. If the window is visible, this includes bringing window toFront, then "sticking" it to the top-most position. If the window is not visible it does nothing other than setting the always-on-top property. If later the window is shown, it will be always-on-top. If the window is already always-on-top, this call does nothing.

If alwaysOnTop is false this method changes the state from always-on-top to normal. The window remains top-most but its z-order can be changed in the normal way as for any other window. Does nothing if this window is not always-on-top. Has no effect on relative z-order of windows if there are no other always-on-top windows.

Parameters:

alwaysOnTop - new value of always-on-top state of the native window

See Also:

isAlwaysOnTop(), toFront(), toBack()

toBack

void toBack()

If this native window is visible, sends this native window to the back and may cause it to lose focus or activation if it is the focused or active window.

Places this native window at the bottom of the stacking order and shows it behind any other windows in this VM. No action will take place if this window is not visible.

See Also:

toFront()

toFront

void toFront()

If this native window is visible, brings this native window to the front and may make it the focused window.

Places this native window at the top of the stacking order and shows it in front of any other windows in this VM. No action will take place if this window is not visible.

See Also:

toBack()

requestFocus

void requestFocus()

Requests that this native window become the focused window. The window must be visible for the request to be granted. Every effort will be made to honor the request; however, in some cases it may be impossible to do so. Developers must never assume that this native window is the focus owner until it receives a FOCUS_GAINED event.

isActive

boolean isActive()

Returns whether this native window is active. The native windowing system may denote the active window or its children with special decorations, such as a highlighted title bar. The active window is always either the focused window, or the top-level native window that is the owner of the focused window.

Returns:

true, if this native window is currently active, false otherwise

See Also:

isFocused()

isFocused

boolean isFocused()

Returns whether this native window is focused. If there exists a focus owner, the focused window is the window that is, or contains, that focus owner. If there is no focus owner, then no window is focused.

The focused native window is also the active native window.

Returns:

true, if this native window is currently the focused window, false otherwise

See Also:

isActive()

isUndecorated

boolean isUndecorated()

Indicates whether this native window is undecorated. By default, all native windows are initially decorated.

Returns:

true if native window is undecorated; false otherwise.

See Also:

setUndecorated(boolean)

setUndecorated

void setUndecorated(boolean undecorated)

Disables or enables decorations for this native window.

Parameters:

undecorated - true if no frame decorations are to be enabled; false if frame decorations are to be enabled.

See Also:

isUndecorated()

isResizable

boolean isResizable()

Indicates whether this native window is resizable by the user. By default, all native windows are initially resizable.

Returns:

true if the user can resize this native window; false otherwise.

See Also:

setResizable(boolean)

setResizable

void setResizable(boolean resizable)

Sets whether this native window is resizable by the user.

Parameters:

resizable - true if this native window is resizable; false otherwise.

See Also:

isResizable()

getInsets

Insets getInsets()

Determines the insets of this native window, which indicate the size of the window's border.

A NativeWindow object, for example, has a top inset that corresponds to the height of the window's title bar.

Returns:

the insets of this native window.

See Also:

Insets

addNativeWindowListener

void addNativeWindowListener(NativeWindowListener listener)

Adds the specified native window listener to receive window events from the underlying native window. If listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the native window listener to be added

See Also:

removeNativeWindowListener(com.datagis.com4j.NativeWindowListener), getNativeWindowListeners(), NativeWindowListener, NativeWindowAdapter

removeNativeWindowListener

void removeNativeWindowListener(NativeWindowListener listener)

Removes the specified native window listener, so that it no longer receives window events from the underlying native window. This method performs no action, nor does it throw an exception, if either the listener specified by the argument is null or was not previously added to this NativeWindowinstance.

Parameters:

listener - the native window listener to be removed

See Also:

addNativeWindowListener(com.datagis.com4j.NativeWindowListener), getNativeWindowListeners(), NativeWindowListener, NativeWindowAdapter

getNativeWindowListeners

NativeWindowListener[] getNativeWindowListeners()

Returns an array of all the native window listeners registered on this NativeWindow instance.

Returns:

all of this native window's NativeWindowListeners or an empty array if no native window listeners are currently registered

See Also:

addNativeWindowListener(com.datagis.com4j.NativeWindowListener), removeNativeWindowListener(com.datagis.com4j.NativeWindowListener)

isNativeWindowListener

boolean isNativeWindowListener(NativeWindowListener listener)

Indicates whether the specified native window listener listener is registered on this NativeWindow instance.

Parameters:

listener - the native window listener to test

Returns:

true if the specified native window listener listener is registered with this NativeWindow instance; false otherwise.

See Also:

addNativeWindowListener(com.datagis.com4j.NativeWindowListener), removeNativeWindowListener(com.datagis.com4j.NativeWindowListener), getNativeWindowListeners()

dispose

void dispose()

Releases the reference to the underlying native window represented by this NativeWindow object. Although, dispose can be called on a COM object multiple times, regardless whether the object is already disposed, method isDisposed may be used to determine, whether an object is disposed or not.

Since Java objects tend to live longer in memory until they are garbage collected, and applications have generally no control over when this happens, calling the dispose method at any time enables applications to dispose the underlying native windows deterministically.

After having disposed a native window, one has no longer access to the window's methods nor will any events be delivered to any event listener that still may be registered. Accessing methods of a disposed native window will throw an IllegalStateException.

Specified by:

dispose in interface Disposable

See Also:

isDisposed()

isDisposed

boolean isDisposed()

Indicates whether the underlying native window is already disposed. This method just takes advantage of the fact, that a disposed object will return 0 as its hash code value. So, this method could easily be replaced by:

 return (this.hashCode() != 0);
 

Returns:

true if the underlying COM object is disposed; false otherwise