<!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>