It is not a direct replacement for the usual application menu bar, but rather a place to hold actions that (as a general rule) do not affect the visual content of the document – such as saving, printing, sharing etc.
Prior to version 5.0, the ribbon frame (org.pushingpixels.flamingo.ribbon.JRibbonFrame class) tracked application calls to Window.setIconImages API, located the closest image that fits in the application menu button and used that image. This was a rather awkward solution that did not sit well with pervasive usage of the ResizableIcon interface in other parts of Flamingo. The latest 5.0dev drop of Flamingo (code-named Imogene) will now throw an UnsupportedOperationException if your code calls the setIconImages API. Instead, the application code must use the new JRibbonFrame.setApplicationIcon(ResizableIcon) API.
The ribbon will use the specified resizable icon to create window images and set them on the underlying frame. As a bonus side effect of using this API, you will also get a 128*128 version of the icon automatically passed to Application.setDockIconImage API, providing much better integration with the native Mac OS X application environment:
Note here how the crispness of the dock icon – which is using the same icon source as the application button menu icon. The original SVG is from the Tango icon library, and org.pushingpixels.flamingo.svg.SvgTranscoder was run offline to create a standalone Java2D implementation of the ResizableIcon interface from it.
To test the new functionality in your applications, you will need just the latest 5.0dev drop of Flamingo. As a side note, now that i have moved to Mac as my primary development environment, expect much better desktop integration for both Flamingo and Substance.