| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| |
| <html> |
| <head> |
| <!-- -*- xhtml -*- --> |
| <title>Platform Ribbon Bar Integration Tutorial for NetBeans Platform</title> |
| <meta name="AUDIENCE" content="NBUSER"/> |
| <meta name="TYPE" content="ARTICLE"/> |
| <meta name="EXPIRES" content="N"/> |
| <meta name="developer" content="geertjan.wielenga@oracle.com"/> |
| <meta name="indexed" content="y"/> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| <meta name="description" |
| content="A guide to integrating a ribbon bar into the NetBeans Platform."/> |
| <link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/> |
| </head> |
| |
| <!-- Copyright (c) 2009, 2010, 2011, 2012, 2013, 2014 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><strong class="notes">Note: </strong>This document uses NetBeans Platform 8.0 and |
| NetBeans IDE 8.0. If you |
| are using an earlier version, see <a href="74/nbm-ribbonbar.html">the previous version |
| of this document</a>.</p> |
| |
| <p><b>Contents</b></p> |
| |
| <p><img src="../images/articles/80/netbeans-stamp.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 8.0" title="Content on this page applies to NetBeans IDE 8.0"/></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 8.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"><folder name="Ribbon"> |
| <folder name="AppMenu"> |
| <attr name="position" intvalue="0"/> |
| <file name="SaveAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| <file name="SeparatorAfterSave.instance"> |
| <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/> |
| <attr name="position" intvalue="110"/> |
| </file> |
| <file name="SeparatorBeforeExit.instance"> |
| <attr name="instanceClass" stringvalue="javax.swing.JSeparator"/> |
| <attr name="position" intvalue="3990"/> |
| </file> |
| <file name="ExitAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/> |
| <attr name="position" intvalue="4000"/> |
| </file> |
| </folder> |
| </folder></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"><folder name="Ribbon"> |
| <folder name="AppMenu"> |
| <attr name="position" intvalue="0"/> |
| <file name="SaveAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| </folder> |
| <b><folder name="AppMenuFooter"> |
| <file name="org-netbeans-core-actions-SystemExit.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/> |
| <attr name="position" intvalue="100"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/> |
| </file> |
| <file name="org-netbeans-modules-options-OptionsWindowAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/> |
| <attr name="position" intvalue="200"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/> |
| </file> |
| </folder></b> |
| </folder></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"><folder name="Ribbon"> |
| <folder name="AppMenu"> |
| <file name="SaveAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| <b><folder name="Print"> |
| <attr name="position" intvalue="200"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <folder name="Print Actions"> |
| <file name="org-netbeans-modules-print-action-PageSetupAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/> |
| </file> |
| <file name="org-netbeans-modules-print-action-PrintAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/> |
| <attr name="position" intvalue="600"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/> |
| </file> |
| </folder> |
| </folder></b> |
| <file name="org-netbeans-modules-options-OptionsWindowAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/> |
| <attr name="position" intvalue="200"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/> |
| </file> |
| <file name="org-netbeans-core-actions-SystemExit.shadow"> |
| <attr name="position" intvalue="300"/> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/> |
| </file> |
| </folder> |
| <folder name="AppMenuFooter"> |
| <file name="org-netbeans-core-actions-SystemExit.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/> |
| <attr name="position" intvalue="100"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/> |
| </file> |
| </folder> |
| </folder></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"><folder name="Ribbon"> |
| <folder name="TaskBar"> |
| <file name="SaveAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| <folder name="Print"> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <attr name="position" intvalue="200"/> |
| <folder name="Print Actions"> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <file name="org-netbeans-modules-print-action-PageSetupAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/> |
| </file> |
| <file name="org-netbeans-modules-print-action-PrintAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/> |
| <attr name="position" intvalue="600"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/> |
| </file> |
| </folder> |
| <folder name="Print Options"> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/> |
| <file name="org-netbeans-modules-options-OptionsWindowAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/> |
| <attr name="position" intvalue="200"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/> |
| </file> |
| </folder> |
| </folder> |
| <file name="org-netbeans-core-actions-SystemExit.shadow"> |
| <attr name="position" intvalue="300"/> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-core-actions-SystemExit.instance"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Exit.png"/> |
| </file> |
| </folder> |
| </folder></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"><folder name="Ribbon"> |
| <folder name="TaskPanes"> |
| <folder name="Main"> |
| <folder name="File"> |
| <file name="SaveAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-openide-actions-SaveAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| </file> |
| </folder> |
| </folder> |
| <folder name="Tools"> |
| <folder name="Use"> |
| <attr name="position" intvalue="100"/> |
| <file name="org-netbeans-modules-print-action-PageSetupAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PageSetupAction.instance"/> |
| <attr name="position" intvalue="100"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PageSetupAction"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Config.png"/> |
| </file> |
| <file name="org-netbeans-modules-print-action-PrintAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/File/org-netbeans-modules-print-action-PrintAction.instance"/> |
| <attr name="position" intvalue="600"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Print.png"/> |
| <attr name="description" bundlevalue="com.pinkmatter.test.flamingo.actions.Bundle#HINT_PrintAction"/> |
| </file> |
| </folder> |
| <folder name="Change"> |
| <attr name="position" intvalue="200"/> |
| <file name="org-netbeans-modules-options-OptionsWindowAction.shadow"> |
| <attr name="originalFile" stringvalue="Actions/Window/org-netbeans-modules-options-OptionsWindowAction.instance"/> |
| <attr name="position" intvalue="200"/> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Tools.png"/> |
| </file> |
| </folder> |
| </folder> |
| </folder> |
| </folder></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"><folder name="Ribbon"> |
| <folder name="HelpButton"> |
| <file name="org-netbeans-core-actions-AboutAction.instance"> |
| <attr name="iconBase" stringvalue="org/netbeans/paint/resources/Info.png"/> |
| </file> |
| </folder> |
| </folder></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"><folder name="Actions"> |
| <folder name="File"> |
| <file name="org-openide-actions-SaveAction.instance"> |
| <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.context"/> |
| <attr name="delegate" newvalue="org.openide.actions.SaveAction"/> |
| <attr name="selectionType" stringvalue="EXACTLY_ONE"/> |
| <attr name="surviveFocusChange" boolvalue="false"/> |
| <attr name="displayName" bundlevalue="org/openide/actions/Bundle#Save"/> |
| <attr name="noIconInMenu" boolvalue="false"/> |
| <attr name="iconBase" stringvalue="org/openide/resources/actions/save.png"/> |
| <attr name="type" stringvalue="org.openide.cookies.SaveCookie"/> |
| <b><attr name="description" bundlevalue="org.netbeans.paint.Bundle#HINT_SaveAction"/> |
| <attr name="tooltipTitle" bundlevalue="org.netbeans.paint.Bundle#CTL_SaveActionTitle"/> |
| <attr name="tooltipFooter" bundlevalue="org.netbeans.paint.Bundle#HINT_HelpAction"/> |
| <attr name="tooltipFooterIcon" stringvalue="org/netbeans/paint/resources/Info.png"/></b> |
| </file> |
| ... |
| ... |
| ...</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"><folder name="Ribbon"> |
| <folder name="TaskPanes"> |
| <folder name="Formatting"> |
| <file name="org-netbeans-paint-FontRibbonBand.instance"/> |
| </folder> |
| </folder> |
| </folder></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> |
| |
| <!-- ======================================================================================== --> |
| |
| <div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback: NetBeans Platform Ribbon Bar Tutorial 8.0">Send Us Your Feedback</a> |
| <br style="clear:both;" /></div> |
| |
| </body> |
| |
| </html> |