Google Git
Sign in
apache / netbeans-website-cleanup / refs/heads/master / . / src / content / platform / tutorials / 74 / nbm-ribbonbar.html
blob: b370c6f5e6ccaecd4a0e2c10df7776c65f35bdd6 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- -*- xhtml -*- -->
<title>NetBeans Platform Ribbon Bar Integration Tutorial for NetBeans Platform 7.0</title>
<meta name="AUDIENCE" content="NBUSER"/>
<meta name="TYPE" content="ARTICLE"/>
<meta name="EXPIRES" content="N"/>
<meta name="developer" content="geertjan.wielenga@sun.com"/>
<meta name="indexed" content="y"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="description"
content="A guide describing how to collect gestures in NetBeans Platform applications."/>
<link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/>
</head>
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
<!-- Use is subject to license terms.-->
<body>
<h1><a name="top"></a>NetBeans Platform Ribbon Bar Integration Tutorial</h1>
<p>Microsoft Office introduced the concept of a ribbon bar, which Kirill Grouchnikov
made available to Java applications via his <a href="http://java.dzone.com/articles/flamingo-tutorial">Flamingo library</a>:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/briefcase_16.png"/></p>
<p>Based on this work,
Chris Bohme from <a href="http://pinkmatter.com/">PinkMatter Solutions</a> created an extensible ribbon bar for
NetBeans Platform applications. The work done by Chris Bohme has been open sourced and forms
the basis of this tutorial.</p>
<p><b class="notes">Note:</b> The instructions that follow focus on a lot of XML tags. None of these
need to be typed by hand. Instead, as described in the section entitled
"Using Annotations to Register the NetBeans Ribbon Bar", you do not need to use any XML tags at all
since these can be generated at compile-time by a NetBeans Platform annotation processor.
However, it helps to understand how the Ribbon integration works and therefore we begin by looking
at XML tags. Once you are familiar with them, you can simply forget about them, and use the annotations
instead.</p>
<p><b>Contents</b></p>
<p><img src="../images/articles/74/netbeans_stamp_74_73_72.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.9" title="Content on this page applies to NetBeans IDE 6.9"/></p>
<ul class="toc">
<li><a href="#intro">Getting to Know the Ribbon Bar</a></li>
<li><a href="#setup">Setting Up the NetBeans Ribbon Bar</a></li>
<li><a href="#features">Using the NetBeans Ribbon Bar Features</a>
<ul>
<li><a href="#appmenu">Application Menu</a></li>
<li><a href="#taskbar">Task Bar</a></li>
<li><a href="#taskpane">Task Pane</a></li>
<li><a href="#helpbutton">Help Button</a></li>
</ul>
</li>
<li><a href="#annotations">Using Annotations to Register the NetBeans Ribbon Bar</a></li>
<li><a href="#tooltip">Creating Ribbon Tooltips</a></li>
<li><a href="#api">Using the Ribbon API</a></li>
<li><a href="#customize-appmenu">Customizing the Application Menu</a></li>
<li><a href="#reading">Further Reading</a></li>
</ul>
<p><b>To follow this tutorial, you need the software and resources listed in the following
table.</b></p>
<table>
<tbody>
<tr>
<th class="tblheader" scope="col">Software or Resource</th>
<th class="tblheader" scope="col">Version Required</th>
</tr>
<tr>
<td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
<td class="tbltd1">version 7.0 or above</td>
</tr>
<tr>
<td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td>
<td class="tbltd1">version 7 or above</td>
</tr>
</tbody>
</table>
<!-- ===================================================================================== -->
<h2 class="tutorial"><a name="intro"></a>Getting to Know the Ribbon Bar</h2>
<p>Chris Bohme extrapolated the NetBeans ribbon bar from
an application named <a href="http://netbeans.dzone.com/news/intelligence-gathering">Maltego</a>, created by himself
and others at PinkMatter Solutions.
Maltego is an artificial intelligence application. Take note of
the toolbar in the screenshot of Maltego below:</p>
<p><img src="http://netbeans.dzone.com/sites/all/files/Maltego3-small.png"/></p>
<p>Now, watch Chris Bohme's introduction to the NetBeans ribbon bar integration here:</p>
<p><iframe width="480" height="390" src="https://www.youtube.com/embed/SUILKGVntDQ" frameborder="0" allowfullscreen></iframe></p>
<p><b class="notes">Note:</b> The YouTube video above stops unexpectedly. Attempts are being made
to provide the full video, though the main points of the PinkMatter integration are already addressed
in the above.</p>
<!-- ===================================================================================== -->
<h2 class="tutorial"><a name="setup"></a>Setting Up the NetBeans Ribbon Bar</h2>
<p>The NetBeans ribbon bar is open sourced on java.net. In this section, you download
the sources that make up the ribbon bar integration. Taken together, the sources form
an application in themselves. When you run them, you see a basic NetBeans Platform
application that includes the ribbon bar. You are then shown how to set up your own
application to use the ribbon bar as a platform for integration into your own
application.</p>
<p class="tips">If you want to try out these instructions on an actual
application prior to trying them out on your own
sources, you can use the NetBeans Platform Paint
Application, which you can get from the Samples
category in the New Project wizard (Ctrl-Shift-N). That is the
example application that will be referred to throughout this
tutorial.</p>
<div class="indent">
<ol>
<li><p>Check out the NetBeans ribbon bar integration here:</p>
<p><a href="http://java.net/projects/nbribbonbar/">http://java.net/projects/nbribbonbar/</a></p>
<!-- <p><b class="notes">Note:</b> At the time of writing, 'nbribbonbar' is still a private project
in an incubator on java.net. If you click the above link and cannot access the sources, <a href="http://www.pinkmatter.co.za/Blog/tabid/65/EntryId/2/Netbeans-platform-ribbon-bar-library.aspx">go to this location</a>
instead, where they are found within a PinkMatter blog entry.</p>-->
</li>
<li><p>You should now have these folders on disk:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/suite-on-disk.png"/></p>
</li>
<li><p>Open the application into NetBeans IDE. You should now see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/suite-on-disk2.png"/></p></li>
<li><p>Run the application and explore the ribbon bar:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/rundemo-1.png"/></p>
<p>Above, you see the initial appearance of the demo application. It consists of the
NetBeans Platform modules, plus a module wrapping the Flamingo JARs, plus
a module providing NetBeans Platform integration code for the Flamingo JARs,
plus a test module showing how to use the other two modules to create a
ribbon bar.</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/rundemo-2.png"/></p>
<p>Above, you see the application menu. It is shown when you click on the
big icon top left in the application. Each action in the application menu
can expand, as shown above, depending on whether a folder is registered
or just an individual file.</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/rundemo-3.png"/></p>
<p>Above, you see a composite panel, constructed from the Ribbon API, as shown
towards the end of this tutorial, and registered in the application via
the <tt>layer.xml</tt> file.</p>
</li>
<li><p>Now let's set up our own application to use the ribbon bar. Right-click your own
application, go to Properties, and then choose Libraries. You should now see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/projprop1.png"/></p>
<p class="tips"> Depending on the modules you're using in your own application,
you will have different clusters included in the list above. For the
NetBeans Paint Application, which is the sample application used in this
tutorial, only the "platform" cluster is included.</p></li>
<li><p>Click Add Cluster and then browse to the top folder of the platform
that you checked out:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/projprop2.png"/></p>
<p>Click OK and you will see that you have the ribbon platform as a new cluster, with the
two modules selected that you need:</p>
<p><img style="border:1px solid black" alt="enable harness" src="../images/tutorials/ribbon/projprop3.png"/></p>
<p>Click OK to exit the Project Properties dialog.</p>
</li>
<li><p>Run the application and you should see the application menu, without any content, with
all the existing menus and toolbars removed:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/projprop4.png"/></p>
</li>
</ol>
<p>You have now set up your own application to use the PinkMatter ribbon integration. In the next
section, you will add actions from your application to the application menu, task bar,
and task panes of the ribbon.</p>
</div>
<!-- ===================================================================================== -->
<h2 class="tutorial"><a name="features"></a>Using the NetBeans Ribbon Bar Features</h2>
<p>Now that our ribbon bar is set up, we will use its features.</p>
<div class="indent">
<p><a name="appmenu"></a></p><h3 class="tutorial">Application Menu</h3>
<p>The application menu is one of the most visible differentiators
of the ribbon bar. It is accessed via the large button in the
top left of the application. In this section, you learn how to
add new items to the application menu.</p>
<ol>
<li><p>In the <tt>layer.xml</tt> of the Paint module in the Paint Application,
copy the content of the Menu/File folder into a new folder
named Ribbon/AppMenu:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="AppMenu"&gt;
&lt;attr name="position" intvalue="0"/&gt;
&lt;file name="SaveAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;/file&gt;
&lt;file name="SeparatorAfterSave.instance"&gt;
&lt;attr name="instanceClass" stringvalue="javax.swing.JSeparator"/&gt;
&lt;attr name="position" intvalue="110"/&gt;
&lt;/file&gt;
&lt;file name="SeparatorBeforeExit.instance"&gt;
&lt;attr name="instanceClass" stringvalue="javax.swing.JSeparator"/&gt;
&lt;attr name="position" intvalue="3990"/&gt;
&lt;/file&gt;
&lt;file name="ExitAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/&gt;
&lt;attr name="position" intvalue="4000"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre>
</li>
<li><p>Run the application and you should see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-1.png"/></p>
<p class="tips">The icons used above and throughout this tutorial come from
the sources you downloaded from Kenai. One of the modules contains a folder
named "com.pinkmatter.test.flamingo.resources", which provides a very long
list of icons that you can use for many of the most commonly used actions
in your application.</p>
</li>
<li><p>It would be more idiomatic to place the Exit action, as well as an Options action, inside
buttons within the application menu. That "AppMenuFooter" folder exists for that
purpose Therefore, rewrite the layer entries above
to these:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="AppMenu"&gt;
&lt;attr name="position" intvalue="0"/&gt;
&lt;file name="SaveAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
<b>&lt;folder name="AppMenuFooter"&gt;
&lt;file name="org-netbeans-core-actions-SystemExit.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/&gt;
&lt;/file&gt;
&lt;file name="org-netbeans-modules-options-OptionsWindowAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;</b>
&lt;/folder&gt;</pre>
<li><p>Run the application again and you should see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-2.png"/></p>
</li>
<li><p>By creating a subfolder within Ribbon/AppMenu, you can register an action that
expands to show the actions within its folder:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="AppMenu"&gt;
&lt;file name="SaveAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;/file&gt;
<b>&lt;folder name="Print"&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;folder name="Print Actions"&gt;
&lt;file name="org-netbeans-modules-print-action-PageSetupAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/&gt;
&lt;/file&gt;
&lt;file name="org-netbeans-modules-print-action-PrintAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/&gt;
&lt;attr name="position" intvalue="600"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;</b>
&lt;file name="org-netbeans-modules-options-OptionsWindowAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/&gt;
&lt;/file&gt;
&lt;file name="org-netbeans-core-actions-SystemExit.shadow"&gt;
&lt;attr name="position" intvalue="300"/&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;folder name="AppMenuFooter"&gt;
&lt;file name="org-netbeans-core-actions-SystemExit.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre> </li>
<li><p>Run the application again and you should see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-3.png"/></p>
</li>
</ol>
<p>You have now used all the features of the ribbon bar's application menu.</p>
</div>
<div class="indent">
<p><a name="taskbar"></a></p><h3 class="tutorial">Task Bar</h3>
<p>The task bar is the small toolbar at the top of the application, above
the task panes. Each action registered in the task base causes a
toolbar button to be created. Folders registered in the task bar
cause drop-down buttons to be created from which the actions that are
children of the folder can be invoked.</p>
<ol>
<li><p>Rewrite the whole Ribbon folder to the following:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="TaskBar"&gt;
&lt;file name="SaveAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;/file&gt;
&lt;folder name="Print"&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;folder name="Print Actions"&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;file name="org-netbeans-modules-print-action-PageSetupAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/&gt;
&lt;/file&gt;
&lt;file name="org-netbeans-modules-print-action-PrintAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/&gt;
&lt;attr name="position" intvalue="600"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;folder name="Print Options"&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/&gt;
&lt;file name="org-netbeans-modules-options-OptionsWindowAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;file name="org-netbeans-core-actions-SystemExit.shadow"&gt;
&lt;attr name="position" intvalue="300"/&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre>
</li>
<li><p>You should now see the task bar with the following content:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-5.png"/></p>
<p>A drop-down button is created because you registered a folder:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-4.png"/></p>
<p>Each drop-down button shows the actions registered as files with the folder:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-6.png"/></p>
</li>
</ol>
<p>You have now used the ribbon task bar in your application.</p>
</div>
<div class="indent">
<p><a name="taskpane"></a></p><h3 class="tutorial">Task Pane</h3>
<p>The task pane is a pane within the tabbed toolbar of the application. Actions are
registered into a task pane via the Ribbon/TaskPanes folder. Each folder within
Ribbon/TaskPanes defines a new pane. For example, "Ribbon/TaskPanes/Tools" defines
a new task pane named "Tools". Each task pane is further split into separate containers.
For example, "Ribbon/TaskPanes/Tools/Use" could be a folder for registering actions that
can be used, while "Ribbon/TaskPanes/Tools/Change" could be a container for changing
or customizing features relating to Tools in the application.</p>
<ol>
<li><p>Rewrite the Ribbon folder in the <tt>layer.xml</tt> to the following:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="TaskPanes"&gt;
&lt;folder name="Main"&gt;
&lt;folder name="File"&gt;
&lt;file name="SaveAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;folder name="Tools"&gt;
&lt;folder name="Use"&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;file name="org-netbeans-modules-print-action-PageSetupAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/&gt;
&lt;attr name="position" intvalue="100"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/&gt;
&lt;/file&gt;
&lt;file name="org-netbeans-modules-print-action-PrintAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/&gt;
&lt;attr name="position" intvalue="600"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/&gt;
&lt;attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;folder name="Change"&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;file name="org-netbeans-modules-options-OptionsWindowAction.shadow"&gt;
&lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/&gt;
&lt;attr name="position" intvalue="200"/&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre>
</li>
<li><p>Run the application again and you should see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-7.png"/></p>
</li>
</ol>
<p>You have now used task panes in your ribbon bar to organize actions into a tabbed toolbar.</p>
</div>
<div class="indent">
<p><a name="helpbutton"></a></p><h3 class="tutorial">Help Button</h3>
<p>The help button is always displayed top right in the ribbon bar.</p>
<ol>
<li><p>Rewrite the Ribbon folder as follows:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="HelpButton"&gt;
&lt;file name="org-netbeans-core-actions-AboutAction.instance"&gt;
&lt;attr name="iconBase" stringvalue="org/netbeans/paint/resources/Info.png"/&gt;
&lt;/file&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre>
</li>
<li><p>Run the application again and you should see this, take note
of the small button on the right of the application:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-8.png"/></p>
</li>
</ol>
</div>
<p>You now have used all the features of the ribbon bar in your own application.</p>
<!-- ======================================================================================== -->
<h2><a name="annotations"></a>Using Annotations to Register the NetBeans Ribbon Bar</h2>
<p>None of the XML tags described in previous sections needs to be typed anywhere, nor do
you even need to <i>see</i> any of it. Imagine that the Paint Application
has a "BucketAction". This is how the action
would be registered via annotations into the Ribbon folders shown above:</p>
<pre code="examplecode">@ActionID(category = "Paint",
id = "org.paint.bucket.BucketAction")
@ActionRegistration(displayName = "#CTL_BucketAction", iconBase="org/paint/bucket/bucket.png")
@ActionReferences({
<b>@ActionReference(path = "Ribbon/AppMenu", position = 0),
@ActionReference(path = "Ribbon/AppMenuFooter", position = 0),
@ActionReference(path = "Ribbon/TaskBar", position = 0),
@ActionReference(path = "Ribbon/TaskPanes/Main/File", position = 0)</b>
})
@Messages("CTL_BucketAction=Bucket")
public final class BucketAction implements ActionListener {
@Override
public void actionPerformed(ActionEvent e) {
// TODO implement action body
}
}</pre>
<p class="tips">When the module is compiled, the annotations in bold above will cause
the Ribbon folder to be created, as well as its subfolders, and register the action
into them.</p>
<!-- ======================================================================================== -->
<h2><a name="tooltip"></a>Creating Ribbon Tooltips</h2>
<p>In this section, you learn how to create tooltips in the ribbon bar. The PinkMatter
ribbon integration provides the attributes "description", "tooltipTitle", "tooltipFooter",
and "tooltipFooterIcon" to define the content of predefined tooltip placeholders in the ribbon bar.</p>
<div class="indent">
<ol>
<li><p>In the Actions folder, add the following attributes in bold to the
definition of the Save action:</p>
<pre class="examplecode">&lt;folder name="Actions"&gt;
&lt;folder name="File"&gt;
&lt;file name="org-openide-actions-SaveAction.instance"&gt;
&lt;attr name="instanceCreate" methodvalue="org.openide.awt.Actions.context"/&gt;
&lt;attr name="delegate" newvalue="org.openide.actions.SaveAction"/&gt;
&lt;attr name="selectionType" stringvalue="EXACTLY_ONE"/&gt;
&lt;attr name="surviveFocusChange" boolvalue="false"/&gt;
&lt;attr name="displayName" bundlevalue="org/openide/actions/Bundle#Save"/&gt;
&lt;attr name="noIconInMenu" boolvalue="false"/&gt;
&lt;attr name="iconBase" stringvalue="org/openide/resources/actions/save.png"/&gt;
&lt;attr name="type" stringvalue="org.openide.cookies.SaveCookie"/&gt;
<b>&lt;attr name="description" bundlevalue="org.netbeans.paint.Bundle#HINT_SaveAction"/&gt;
&lt;attr name="tooltipTitle" bundlevalue="org.netbeans.paint.Bundle#CTL_SaveActionTitle"/&gt;
&lt;attr name="tooltipFooter" bundlevalue="org.netbeans.paint.Bundle#HINT_HelpAction"/&gt;
&lt;attr name="tooltipFooterIcon" stringvalue="org/netbeans/paint/resources/Info.png"/&gt;</b>
&lt;/file&gt;
...
...
...</pre>
</li>
<li>
<p>Add the following keys to the <tt>Bundle.properties</tt> file in the main package, that is,
the <tt>Bundle.properties</tt> file referred to in the XML tags above:</p>
<pre class="examplecode">HINT_SaveAction=Save the image
HINT_HelpAction=If you still don't know whats going on, click the Help icon
CTL_SaveActionTitle=Save Image</pre>
</li>
<li><p>Run the application again and you should see this, when you hover
with the mouse over the Save button:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-0.png"/></p>
</li>
</ol>
</div>
<p>You have now learned how to define tooltips in the ribbon bar.</p>
<!-- ======================================================================================== -->
<h2><a name="api"></a>Using the Ribbon API</h2>
<p>The NetBeans ribbon bar integration enables you to use the <a href="http://www.pushing-pixels.org/category/swing">Ribbon APIs</a>, as follows:</p>
<pre class="examplecode">
package org.netbeans.paint;
import com.pinkmatter.api.flamingo.ResizableIcons;
import javax.swing.JComboBox;
import org.pushingpixels.flamingo.api.common.CommandToggleButtonGroup;
import org.pushingpixels.flamingo.api.common.JCommandButton;
import org.pushingpixels.flamingo.api.common.JCommandButtonStrip;
import org.pushingpixels.flamingo.api.common.JCommandToggleButton;
import org.pushingpixels.flamingo.api.common.RichTooltip;
import org.pushingpixels.flamingo.api.common.icon.ResizableIcon;
import org.pushingpixels.flamingo.api.ribbon.JFlowRibbonBand;
import org.pushingpixels.flamingo.api.ribbon.JRibbonComponent;
public class FontRibbonBand extends JFlowRibbonBand {
public FontRibbonBand() {
super("Font", null);
JComboBox fontCombo = new JComboBox(new Object[]{
"Calibri ", "Columbus ",
"Consolas ", "Cornelius ",
"Cleopatra ", "Cornucopia ",
"Candella ", "Cambria "});
JRibbonComponent fontComboWrapper = new JRibbonComponent(fontCombo);
addFlowComponent(fontComboWrapper);
JComboBox sizeCombo = new JComboBox(new Object[]{"10 ","11 ","12 ","14 "});
JRibbonComponent sizeComboWrapper = new JRibbonComponent(sizeCombo);
addFlowComponent(sizeComboWrapper);
JCommandButtonStrip indentStrip = new JCommandButtonStrip();
JCommandButton indentLeftButton = new JCommandButton("",
getIcon("indent_left.gif"));
indentStrip.add(indentLeftButton);
JCommandButton indentRightButton = new JCommandButton("",
getIcon("indent_right.gif"));
indentStrip.add(indentRightButton);
addFlowComponent(indentStrip);
JCommandButtonStrip styleStrip = new JCommandButtonStrip();
JCommandToggleButton styleBoldButton = new JCommandToggleButton("",
getIcon("bold.gif"));
styleBoldButton.getActionModel().setSelected(true);
styleBoldButton.setActionRichTooltip(new RichTooltip("Bold", "Make the selected text bold"));
styleStrip.add(styleBoldButton);
JCommandToggleButton styleItalicButton = new JCommandToggleButton("",
getIcon("italics.gif"));
styleItalicButton.setActionRichTooltip(new RichTooltip("Italic", "Italicise the selected text"));
styleStrip.add(styleItalicButton);
JCommandToggleButton styleUnderlineButton = new JCommandToggleButton(
"", getIcon("underline.gif"));
styleUnderlineButton.setActionRichTooltip(new RichTooltip("Underline", "Underline the selected text"));
styleStrip.add(styleUnderlineButton);
JCommandToggleButton styleStrikeThroughButton = new JCommandToggleButton(
"", getIcon("strikethrough.gif"));
styleStrikeThroughButton.setActionRichTooltip(new RichTooltip("Strikethrough", "Strike the selected text"));
styleStrip.add(styleStrikeThroughButton);
addFlowComponent(styleStrip);
JCommandButtonStrip alignStrip = new JCommandButtonStrip();
CommandToggleButtonGroup alignGroup = new CommandToggleButtonGroup();
JCommandToggleButton alignLeftButton = new JCommandToggleButton("",
getIcon("justify_left.gif"));
alignLeftButton.getActionModel().setSelected(true);
alignGroup.add(alignLeftButton);
alignStrip.add(alignLeftButton);
JCommandToggleButton alignCenterButton = new JCommandToggleButton("",
getIcon("justify_center.gif"));
alignGroup.add(alignCenterButton);
alignStrip.add(alignCenterButton);
JCommandToggleButton alignRightButton = new JCommandToggleButton("",
getIcon("justify_right.gif"));
alignGroup.add(alignRightButton);
alignStrip.add(alignRightButton);
JCommandToggleButton alignFillButton = new JCommandToggleButton("",
getIcon("justify_justify.gif"));
alignGroup.add(alignFillButton);
alignStrip.add(alignFillButton);
addFlowComponent(alignStrip);
}
private static ResizableIcon getIcon(String name) {
return ResizableIcons.fromResource("org/netbeans/paint/resources/"+name);
}
}
</pre>
<p>The above is registered in the <tt>layer.xml</tt> file as follows:</p>
<pre class="examplecode">&lt;folder name="Ribbon"&gt;
&lt;folder name="TaskPanes"&gt;
&lt;folder name="Formatting"&gt;
&lt;file name="org-netbeans-paint-FontRibbonBand.instance"/&gt;
&lt;/folder&gt;
&lt;/folder&gt;
&lt;/folder&gt;</pre>
<p>Run the above and you should see this:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/runpaint-9.png"/></p>
<!-- ======================================================================================== -->
<h2><a name="customize-appmenu"></a>Customizing the Application Menu</h2>
<p>In this section, you use the standard NetBeans Platform branding mechanism
to change the texts and icon used in the application menu.</p>
<div class="indent">
<ol>
<li><p>Switch to the Files window and create the folder structure below
within the application's "branding" folder:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/customized-appmenu2.png"/></p>
<p>In other words, within "branding/modules", create this folder structure:</p>
<pre class="examplecode">com-pinkmatter-modules-flamingo.jar/com/pinkmatter/modules/flamingo</pre>
<p>Within that folder, create a file named <tt>Bundle.properties</tt>. Also, add
an icon of 24x24 pixels, with the name "app-button-icon24.png".
</li>
<li>
<p>In the <tt>Bundle.properties</tt> file that you created above,
add the following key/value pairs:<p>
<pre class="examplecode">LBL_AppMenuTitle=Main Menu
HINT_AppMenu=Click here to save, print or access other important features of the Paint Application
HINT_AppMenuHelp=Still don't get it? Click the Help icon</pre>
</li>
<li><p>Run the application again and you should see your icon used together with
your texts, when you hover
with the mouse over the application menu:</p>
<p><img alt="enable harness" src="../images/tutorials/ribbon/customized-appmenu.png"/></p>
</li>
</ol>
</div>
<p>You have now learned how to customize the application menu.</p>
<!-- ======================================================================================== -->
<h2><a name="reading"></a>Further Reading</h2>
<p>This concludes the NetBeans Platform Ribbon Bar Integration Tutorial.
This document has described
how to integrate a ribbon bar into a NetBeans Platform application.
For information about the ribbon bar, and other similar implementations, see the following resources:</p>
<ul>
<li><a href="http://java.net/projects/nbribbonbar/">http://java.net/projects/nbribbonbar/</a></li>
<li><a href="http://www.youtube.com/watch?v=SUILKGVntDQ">YouTube: NetBeans Ribbon Bar Integration Tutorial</a></li>
<li><a href="http://pinkmatter.com/">PinkMatter Solutions</a></li>
<li><a href="http://java.dzone.com/articles/flamingo-tutorial">Flamingo Tutorial</a></li>
<li><a href="http://netbeans.dzone.com/news/intelligence-gathering">Interview: Intelligence Gathering Software on the NetBeans Platform</a></li>
<li><a href="http://netbeans.dzone.com/news/office-laf-netbeans-platform">OfficeLAF for NetBeans Platform</a></li>
<li><a href="http://netbeans.dzone.com/how-create-tabbed-toolbar-on-nb">Tabbed Toolbar for NetBeans Platform</a></li>
</ul>
<!-- ======================================================================================== -->
</body>
</html>