NetBeans Platform Ribbon Bar Integration Tutorial

Microsoft Office introduced the concept of a ribbon bar, which Kirill Grouchnikov
made available to Java applications via his Flamingo library:

Based on this work,
Chris Bohme from PinkMatter Solutions 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.

Note: 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.

Getting to Know the Ribbon Bar

Chris Bohme extrapolated the NetBeans ribbon bar from
an application named Maltego, 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:

Note: 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.

Setting Up the NetBeans Ribbon Bar

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.

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.

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.

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.

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 layer.xml file.

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:

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.

Click Add Cluster and then browse to the top folder of the platform
that you checked out:

Click OK and you will see that you have the ribbon platform as a new cluster, with the
two modules selected that you need:

Click OK to exit the Project Properties dialog.

Run the application and you should see the application menu, without any content, with
all the existing menus and toolbars removed:

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.

Using the NetBeans Ribbon Bar Features

Now that our ribbon bar is set up, we will use its features.

Application Menu

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.

In the layer.xml of the Paint module in the Paint Application,
copy the content of the Menu/File folder into a new folder
named Ribbon/AppMenu:

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.

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:

You have now used all the features of the ribbon bar's application menu.

Task Bar

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.

Each drop-down button shows the actions registered as files with the folder:

You have now used the ribbon task bar in your application.

Task Pane

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.

Run the application again and you should see this, take note
of the small button on the right of the application:

You now have used all the features of the ribbon bar in your own application.

Using Annotations to Register the NetBeans Ribbon Bar

None of the XML tags described in previous sections needs to be typed anywhere, nor do
you even need to see 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:

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.

Creating Ribbon Tooltips

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.

In the Actions folder, add the following attributes in bold to the
definition of the Save action:

Customizing the Application Menu

In this section, you use the standard NetBeans Platform branding mechanism
to change the texts and icon used in the application menu.

Switch to the Files window and create the folder structure below
within the application's "branding" folder:

In other words, within "branding/modules", create this folder structure:

com-pinkmatter-modules-flamingo.jar/com/pinkmatter/modules/flamingo

Within that folder, create a file named Bundle.properties. Also, add
an icon of 24x24 pixels, with the name "app-button-icon24.png".

In the Bundle.properties file that you created above,
add the following key/value pairs:

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

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:

You have now learned how to customize the application menu.

Further Reading

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: