Method Detail

activeReferenceQueue

Useful queue for all parts of system that use java.lang.ref.References
together with some ReferenceQueue and need to do some clean up
when the reference is enqueued. Usually, in order to be notified about that, one
needs to either create a dedicated thread that blocks on the queue and is
Object.notify-ed, which is the right approach but consumes
valuable system resources (threads) or one can periodically check the content
of the queue by RequestProcessor.Task.schedule which is
completely wrong, because it wakes up the system every (say) 15 seconds.
In order to provide useful support for this problem, this queue has been
provided.

If you have a reference that needs cleanup, make it implement Runnable
and register it with the queue:

When the ref object is garbage collected, your run method
will be invoked by calling
((Runnable) reference).run()
and you can perform whatever cleanup is necessary. Be sure not to block
in such cleanup for a long time as this prevents other waiting references
from cleaning themselves up.

Do not call any ReferenceQueue methods. They
will throw exceptions. You may only enqueue a reference.

Be sure to call this method anew for each reference.
Do not attempt to cache the return value.

parseParameters

Parses parameters from a given string in shell-like manner.
Users of the Bourne shell (e.g. on Unix) will already be familiar with the behavior.
For example, when using org.openide.execution.NbProcessDescriptor (Execution API)
you should be able to:

Include command names with embedded spaces, such as c:\Program Files\jdk\bin\javac.

Include extra command arguments, such as -Dname=value.

Do anything else which might require unusual characters or processing. For example:

This example would create the following executable name and arguments:

c:\program files\jdk\bin\java

-Dmessage=Hello /\/\ there!

-Xmx128m

Note that the command string does not escape its backslashes--under the assumption
that Windows users will not think to do this, meaningless escapes are just left
as backslashes plus following character.

Caveat: even after parsing, Windows programs (such as the Java launcher)
may not fully honor certain
characters, such as quotes, in command names or arguments. This is because programs
under Windows frequently perform their own parsing and unescaping (since the shell
cannot be relied on to do this). On Unix, this problem should not occur.

stringToKey

Construct a new key description from a given universal string
description.
Provides mapping between Emacs-like textual key descriptions and the
KeyStroke object used in Swing.

This format has following form:

[C][A][S][M]-identifier

Where:

C stands for the Control key

A stands for the Alt key

S stands for the Shift key

M stands for the Meta key

The format also supports two wildcard codes, to support differences in
platforms. These are the preferred choices for registering keystrokes,
since platform conflicts will automatically be handled:

D stands for the default menu accelerator - the Control
key on most platforms, the Command (meta) key on Macintosh

O stands for the alternate accelerator - the Alt key on
most platforms, the Ctrl key on Macintosh (Macintosh uses Alt as a
secondary shift key for composing international characters - if you bind
Alt-8 to an action, a mac user with a French keyboard will not be able
to type the [ character, which is a significant handicap

If you use the wildcard characters, and specify a key which will conflict
with keys the operating system consumes, it will be mapped to whichever
choice can work - for example, on Macintosh, Command-Q is always consumed
by the operating system, so D-Q will always map to Control-Q.

Every modifier before the hyphen must be pressed.
identifier can be any text constant from KeyEvent but
without the leading VK_ characters. So KeyEvent.VK_ENTER is described as
ENTER.

Parameters:

s - the string with the description of the key

Returns:

key description object, or null if the string does not represent any valid key

getUsableScreenBounds

Returns the usable area of the screen where applications can place its
windows. The method subtracts from the screen the area of taskbars,
system menus and the like. The screen this method applies to is the one
which is considered current, ussually the one where the current input
focus is.

Returns:

the rectangle of the screen where one can place windows

Since:

2.5

getUsableScreenBounds

Returns the usable area of the screen where applications can place its
windows. The method subtracts from the screen the area of taskbars,
system menus and the like.
On certain platforms this methods uses a cache to avoid performance degradation due to repeated calls.
This can be disabled by setting the property "-Dnetbeans.screen.insetsCache=false"
See issue http://netbeans.org/bugzilla/show_bug.cgi?id=219507

Sort a list according to a specified partial order.
Note that in the current implementation, the comparator will be called
exactly once for each distinct pair of list elements, ignoring order,
so caching its results is a waste of time.

Parameters:

l - the list to sort (will not be modified)

c - a comparator to impose the partial order; "equal" means that the elements
are not ordered with respect to one another, i.e. may be only a partial order

stable - whether to attempt a stable sort, meaning that the position of elements
will be disturbed as little as possible; might be slightly slower

topologicalSort

There may not be any nulls among the objects, nor duplicates
(as per hash/equals), nor duplicates among the edge lists.
The edge map need not contain an entry for every object, only if it
has some outgoing edges (empty but not null map values are permitted).
The edge map shall not contain neither keys nor value entries for objects not
in the collection to be sorted, if that happens they will be ignored (since version 7.9).

The incoming parameters will not be modified; they must not be changed
during the call and possible calls to TopologicalSortException methods.
The returned list will support modifications.

There is a weak stability guarantee: if there are no edges
which contradict the incoming order, the resulting list will be in the same
order as the incoming elements. However if some elements need to be rearranged,
it is not guaranteed that others will not also be rearranged, even
if they did not strictly speaking need to be.

Parameters:

c - a collection of objects to be topologically sorted

edges - constraints among those objects, of type Map<Object,Collection>;
if an object is a key in this map, the resulting order will
have that object before any objects listed in the value

Returns:

a partial ordering of the objects in the collection,

Throws:

TopologicalSortException - if the sort cannot succeed due to cycles in the graph, the
exception contains additional information to describe and possibly recover from the error

translate

Provides support for parts of the system that deal with classnames
(use Class.forName, NbObjectInputStream, etc.) or filenames
in layers.

Often class names (especially package names) changes during lifecycle
of a module. When some piece of the system stores the name of a class
in certain point of a time and wants to find the correct Class
later it needs to count with the possibility of rename.

For such purposes this method has been created. It allows modules to
register their classes that changed names and other parts of system that
deal with class names to find the correct names.

To register a mapping from old class names to new ones create a file
META-INF/netbeans/translate.names in your module and fill it
with your mapping:

#
# Mapping of legacy classes to new ones
#
org.oldpackage.MyClass=org.newpackage.MyClass # rename of package for one class
org.mypackage.OldClass=org.mypackage.NewClass # rename of class in a package
# rename of class and package
org.oldpackage.OldClass=org.newpackage.NewClass
# rename of whole package
org.someoldpackage=org.my.new.package.structure
# class was removed without replacement
org.mypackage.OldClass=

Btw. one can use spaces instead of = sign.
For a real world example
check the
xml module.

For purposes of org.openide.util.io.NbObjectInputStream there is
a following special convention:
If the
className is not listed as one that is to be renamed, the returned
string == className, if the className is registered to be renamed
than the className != returned value, even in a case when className.equals (retValue)

Similar behaviour applies to filenames provided by layers (system filesystem). Filenames
can be also translated to adapt to location changes e.g. in action registrations. Note that
no spaces or special characters are allowed in both translated filenames or translation
results. Filenames must conform to regexp ^[/a-zA-Z0-9$_.+-]+$. Keys and values are treated
as paths from fs root.

mergeImages

This method merges two images into the new one. The second image is drawn
over the first one with its top-left corner at x, y. Images need not be of the same size.
New image will have a size of max(second image size + top-left corner, first image size).
Method is used mostly when second image contains transparent pixels (e.g. for badging).

actionsToPopup

Builds a popup menu from actions for provided context specified by
Lookup.
Takes list of actions and for actions whic are instances of
ContextAwareAction creates and uses the context aware instance.
Then gets the action presenter or simple menu item for the action to the
popup menu for each action (or separator for each 'lonely' null array member).

Parameters:

actions - array of actions to build menu for. Can contain null
elements, they will be replaced by separators

actionsToPopup

Builds a popup menu for provided component. It retrieves context
(lookup) from provided component instance or one of its parent
(it searches up to the hierarchy for Lookup.Provider instance).
If none of the components is Lookup.Provider instance, then
it is created context which is fed with composite ActionMap which delegates
to all components up to hierarchy started from the specified one.
Then actionsToPopup(Action[], Lookup)} is called with
the found Lookup instance, which actually creates a popup menu.

Parameters:

actions - array of actions to build menu for. Can contain null
elements, they will be replaced by separators

actionsGlobalContext

Global context for actions. Toolbar, menu or any other "global"
action presenters shall operate in this context.
Presenters for context menu items should not use
this method; instead see ContextAwareAction.

loadImage

Loads an image based on resource path.
Exactly like loadImage(String) but may do a localized search.
For example, requesting org/netbeans/modules/foo/resources/foo.gif
might actually find org/netbeans/modules/foo/resources/foo_ja.gif
or org/netbeans/modules/foo/resources/foo_mybranding.gif.

Caching of loaded images can be used internally to improve performance.

Since:

3.24

createProgressCursor

Returns a cursor with an arrow and an hourglass (or stop watch) badge,
to be used when a component is busy but the UI is still responding to the user.
Similar to the predefined Cursor.WAIT_CURSOR, but has an arrow to indicate
a still-responsive UI.

Typically you will set the cursor only temporarily:

// code is running in other then event dispatch thread
currentComponent.setCursor(Utilities.createProgressCursor(currentComponent));
try {
// perform some work in other than event dispatch thread
// (do not block UI)
} finally {
currentComponent.setCursor(null);
}

This implementation provides one cursor for all Mac systems, one for all
Unix systems (regardless of window manager), and one for all other systems
including Windows. Note: The cursor does not have to look native in some
cases on some platforms!

Parameters:

component - the non-null component that will use the progress cursor

Returns:

a progress cursor (Unix, Windows or Mac)

Since:

3.23

createCustomCursor

attachInitJob

Attaches asynchronous init job to given component.
AsyncGUIJob.construct() will be called after first
paint, when paint event arrives. Later, AsyncGUIJob.finished()
will be called according to the rules of the AsyncGUIJob interface.
Useful for components that have slower initialization phase, component
can benefit from more responsive behaviour during init.

Parameters:

comp4Init - Regular component in its pre-inited state, state in which
component will be shown between first paint and init completion.

initJob - Initialization job to be called asynchronously. Job can
optionally implement Cancellable
interface for proper cancel logic. Cancel method will be called
when component stops to be showing during job's progress.
See Component.isShowing()