blob: 329c0042b3280d0710d3361e8839699cb467146f [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_181) on Fri Sep 14 11:36:53 BST 2018 -->
<title>Overview (Actions APIs)</title>
<meta name="date" content="2018-09-14">
<link rel="stylesheet" type="text/css" href="javadoc.css" title="Style">
<script type="text/javascript" src="script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="Overview (Actions APIs)";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li class="navBarCell1Rev">Overview</li>
<li><a href="org/openide/actions/package-summary.html">Package</a></li>
<li>Class</li>
<li>Use</li>
<li><a href="org/openide/actions/package-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage">org.openide.actions 6.41.1 </div>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev</li>
<li>Next</li>
</ul>
<ul class="navList">
<li><a href="index.html?overview-summary.html" target="_top">Frames</a></li>
<li><a href="overview-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">
<h1 class="title">Actions APIs<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ffffff;'><a href='http://wiki.netbeans.org/API_Stability#Official' target='_blank'>Official</a></span></h1>
</div>
<div class="header">
<p>See: <a href="#overview.description">Description</a></p>
</div>
<div class="contentContainer">
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="&lt;a href="org/openide/actions/doc-files/api.html"&gt;Actions APIs&lt;/a&gt; table, listing packages, and an explanation">
<caption><span><a href="org/openide/actions/doc-files/api.html">Actions APIs</a></span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Package</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="org/openide/actions/package-summary.html">org.openide.actions</a></td>
<td class="colLast">
<div class="block">There are a number of standard
<a href="org/openide/actions/doc-files/api.html"><em>system actions</em></a>
available for use in NetBeans.</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="contentContainer"><a name="overview.description">
<!-- -->
</a>
<div class="block"><p>
<p>
XXX no answer for arch-overall
</p>
</p>
<h3>What is New (see <a href="apichanges.html">all changes</a>)?</h3>
<ul>
<!--Search for dates that are later or equal to 1997-09-01 in
.-->
<!--Checking date 2010-12-14 with count of newer 0--><!--year ok-->
<li>Dec 14 '10 <a href="apichanges.html#issue-192948"><code>SelectionType ANY in SaveAction</code></a>
<p>
<code>SaveAction</code> has been modified to allow one or more <code>SaveCookie</code>s
into it's context. The previous behavior was to allow EXACTLY_ONE.
</p>
</li>
<!--Checking date 2010-2-26 with count of newer 1--><!--year ok-->
<li>Feb 26 '10 <a href="apichanges.html#issue-180979 "><code>ToolsAction</code> via layers</a>
<p>
Register your actions for <code>ToolsAction</code> via
layer, don't use the deprecated manifest style.
</p>
</li>
<!--Checking date 2008-6-24 with count of newer 2--><!--year ok-->
<li>Jun 24 '08 <a href="apichanges.html#issue-135104"><code>HeapView</code> preserves its settings between sessions</a>
<p>
Settings of <code>showDropShadow</code>, <code>showText</code> and <code>tickStyle</code>
are now preserved between sessions in NBPreferences of the same corresponding names.
</p>
</li>
<!--Checking date 2005-3-23 with count of newer 3--><!--year ok-->
<li>Mar 23 '05 <a href="apichanges.html#jump-prev-next">A way how to implement "Jump Next" and "Jump Prev" action handlers</a>
<p>
Use
<pre xml:space="preserve">
topComponent.getActionMap().put("jumpPrev", new YourPrevAction());
topComponent.getActionMap().put("jumpNext", new YourNextAction());
</pre>
if your component provides items and you want the user to jump
among them using standard next/prev actions.
</p>
</li>
<!--Checking date 2003-3-18 with count of newer 4--><!--year ok-->
<li>Mar 18 '03 <a href="apichanges.html#issue-32092">
<code>ActionManager.getDefault()</code> added</a>
<p>
This method should be more convenient than looking for an instance in
lookup. Also there is a simple implementation for standalone use
available.
</p>
</li>
<!--Checking date 2003-2-27 with count of newer 5--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2003-1-8 with count of newer 6--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2000-10-6 with count of newer 7--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2000-3-23 with count of newer 8--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2000-3-14 with count of newer 9--><!--Skipped as the amount of changes is too big-->
</ul>
<h3>Use Cases</h3>
<answer id="arch-usecases">
First see the <a href="org/openide/actions/doc-files/api.html" shape="rect">API description</a>. Here is just
a list of frequently asked or interesting questions slowly expanding as
people ask them:
<h3>Actions faq:</h3>
<h5>How to define configurable Shortcut for Component based shortcut?</h5>
<em><b>Q:</b>
The usual Swing way of defining Actions for your component is to create an Action instance and put it into the Input and Action maps of your component.
However how to make this Action's shortcut configurable from the Tools/Keyboard Shortcuts dialog?</em>
<p>
In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the
layer file under "Actions" folder and have the shortcut defined there under "Keymaps/&lt;Profile Name&gt;" linking to your action.
</p>
<pre xml:space="preserve">
&lt;folder name="Actions" &gt;
&lt;folder name="Window"&gt;
&lt;file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;folder name="Keymaps"&gt;
&lt;folder name="NetBeans"&gt;
&lt;file name="S-A-Left.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;
</pre>
<p>
The mentioned Action has to be a subclass of <code>org.openide.util.actions.CallbackSystemAction</code>. It does not necessarily has to
perform the action, it's just a placeholder for linking the shortcut. You might want to override it's <code>getActionMapKey()</code> and give it a
reasonable key.
</p>
<p>
The actual action that does the work in your component (preferably a simple Swing <code>javax.swing.Action</code>)
is to be put into your <code>TopComponent</code>'s <code>ActionMap</code>. The key for the <code>ActionMap</code>
has to match the key defined in the global action's <code>getActionMapKey()</code> method.
</p>
<pre xml:space="preserve">
getActionMap().put("PreviousViewAction", new MyPreviousTabAction());
</pre>
<p>
This way even actions from multiple <code>TopComponent</code>s with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.
</p>
<p>
Note: Don't define your action's shortcut and don't put it into any of the <code>TopComponent</code>'s
<code>javax.swing.InputMap</code>. Otherwise the component would not pick up the changed shortcut from the
global context.
</p>
</answer>
<h3>Exported Interfaces</h3>
This table lists all of the module exported APIs
with
defined stability classifications. It is generated
based on answers to questions about the architecture
of the module. <a href="architecture-summary.html">Read them all</a>...
<a name="group-java">
<h5>Group of java interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>ActionsAPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-ActionsAPI"><a href="overview-summary.html">overview-summary.html</a>
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-property">
<h5>Group of property interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>OpenIDE-Transmodal-Action</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-OpenIDE-Transmodal-Action">
<p></p>Inidicates action can be performed
(typicaly via shortcut) even when dialog is popped out (modal or modeless).<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>delegates</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-delegates">
<p></p>Used internaly in <code>PasteAction</code> delegate action
which serves to pass an array of <code>PasteType</code> or <code>Action</code> to global instance (it is the only one
which actually performs paste operation).<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>iconBase</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-iconBase">
<p></p>Used in companion to Actions.SMALL_ICON. Because there
is no way to specify values for other types of icons the value of "iconBase" is used
to construct the resource names of disabled, pressed and rollover icons. The value is
expected to contain a resource path of the normal icon. Strings "_pressed",
"_disabled" and "_rollover" are inserted before the suffix when searching for
the other types of icons.<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>noIconInMenu</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-noIconInMenu">
<p></p>
Allowed value <code>Boolean.TRUE</code>.
Influences the display of the action in the main menu, the item will have no icon there. Works for Actions that don't define custom MenuPresenter.
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>PreferredIconSize</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="property-PreferredIconSize">
<p></p>
Used to support 24x24 icons in toolbars. If toolbar button has client property "PreferredIconSize"
set to Integer(24) button tries to load icon with name "iconBase" + "24" eg. "cut24.gif".
Strings "_pressed","_disabled" and "_rollover" are inserted before the suffix when searching for
the other types of icons eg.:"cut24_pressed.gif".<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>waitFinished</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Friend">Friend</a></td><td><a name="property-waitFinished">
<p></p>
There is a new contract established between the caller of an action that
allows mutual communication and possible synchronous execution even for
actions that by default perform their operations asynchronously. If the
action's <code>actionPeformed</code> method is passed <code>ActionEvent</code>
with command <q>waitFinished</q> the action shall be executed synchronously.
The code:
<pre xml:space="preserve">
action.actionPerformed (new ActionEvent (this, 0, "waitFinished"))
</pre>
shall be executed synchronously, even if the action by default runs asynchronously.
All asynchronous actions are asked to obey this contract, <code>CallableSystemAction</code>
does it by default. However this contract is defined as friend one
and may be abandoned in future.
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>ActionMapKeys</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="property-ActionMapKeys">
<p></p>
<code>CallableSystemAction</code> uses its <code>getActionMapKey()</code> method
(usually overriden by subclasses) to get a key which is then searched in the
<code>ActionMap</code> obtained from the action's context. Other modules can
register their own action then:
<pre xml:space="preserve">
topComponent.getActionMap ().put (theKey, new YourOwnSwingAction ());
</pre>
Here is the list of special keys:
<ul>
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
<li>
<code>"delete"</code> - delete action handler</li>
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
<!-- new since 5.8 -->
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
</ul>
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-systemproperty">
<h5>Group of systemproperty interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>org.openide.util.actions.CallableSystemAction.synchronousByDefault</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Friend">Friend</a></td><td><a name="systemproperty-org.openide.util.actions.CallableSystemAction.synchronousByDefault">
<p></p>
If set to <code>true</code>, changes default value of the
<code>asynchronous()</code> method. Useful for unit tests
which would prefer to run all tested actions synchronously.
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-layer">
<h5>Group of layer interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>UI-ToolActions</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="layer-UI-ToolActions">
<p></p>
Register your <a href="http://download.oracle.com/javase/8/docs/api/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
instances in <code>UI/ToolActions</code> folder to make them known
to <a href="org/openide/actions/ToolsAction.html" shape="rect">ToolsAction</a>.
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-preferences">
<h5>Group of preferences interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>org.openide.actions.HeapView</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Private">Private</a></td><td><a name="preferences-org.openide.actions.HeapView">
<p></p>
<table>
<tbody>
<tr>
<th colspan="1" rowspan="1">key</th>
<th colspan="1" rowspan="1">description</th>
<th colspan="1" rowspan="1">read</th>
<th colspan="1" rowspan="1">write</th>
</tr>
<tr>
<td colspan="1" rowspan="1">showDropShadow</td>
<td colspan="1" rowspan="1">Preserves "Drop Shadow" setting of the view</td>
<td colspan="1" rowspan="1">x</td>
<td colspan="1" rowspan="1">x</td>
</tr>
<tr>
<td colspan="1" rowspan="1">showText</td>
<td colspan="1" rowspan="1">Preserves "Show Text" setting of the view</td>
<td colspan="1" rowspan="1">x</td>
<td colspan="1" rowspan="1">x</td>
</tr>
<tr>
<td colspan="1" rowspan="1">tickStyle</td>
<td colspan="1" rowspan="1">Preserves "Overlay Grid" setting of the view</td>
<td colspan="1" rowspan="1">x</td>
<td colspan="1" rowspan="1">x</td>
</tr>
</tbody>
</table>
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<h3>Implementation Details</h3>
<h5>Where are the sources for the module?</h5>
<p>
<p>
The sources for the module are in the
<a href="http://hg.netbeans.org/" shape="rect">NetBeans Mercurial repositories</a>.
</p>
</p>
<h5>What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?</h5>
<p>
Nothing.
</p>
<p>
Read more about the implementation in the <a href="architecture-summary.html">answers to
architecture questions</a>.
</p></div>
</div>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li class="navBarCell1Rev">Overview</li>
<li><a href="org/openide/actions/package-summary.html">Package</a></li>
<li>Class</li>
<li>Use</li>
<li><a href="org/openide/actions/package-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage">org.openide.actions 6.41.1 </div>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev</li>
<li>Next</li>
</ul>
<ul class="navList">
<li><a href="index.html?overview-summary.html" target="_top">Frames</a></li>
<li><a href="overview-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><span class="footnote">Built on September 14 2018.&nbsp;&nbsp;|&nbsp;&nbsp; Copyright &#169; 2017-2018 Apache Software Foundation. All Rights Reserved.</span></small></p>
</body>
</html>