SubstanceTitlePane requests

[enwired]

My company required me to modify the title bar at the top of the windows so that the title text is centered and there is a custom icon on the right. The custom icon is rather wide.

I was able to implement this, but it was difficult and could be made easier with some changes to `SubstanceTitlePane' class.

I realize that class is part of the "internal" code and there are no guarantees that it will continue to be supported, etc. But still, I'll request anyway. If you have time someday, maybe update that class so that it can optionally center the text and the layout does not make assumptions that all icons are the same size?

One of the trickiest parts to creating my sub-class is that the method addMenuItems() is private. Could that be made protected instead?

[kirill-grouchnikov]

In general I'd like to keep as much of the implementation details private as possible. Going forward into Java 9 land (couple of years down the road?) I'll be using the new module system to make things tighter.

In this particular area, I don't think I want to expose that class as part of the API. So one possible thought here is to expose the more generic mechanism of decorating certain parts of certain areas (adding controls, removing controls, laying out controls) in the same way Substance allows you to tweak the visual appearance of UI without extending its internal classes - with painters.

Here I can see a certain similarity between this bug and https://github.com/kirill-grouchnikov/substance/issues/41 - what would be the right level of granularity for allowing apps to go deeper into how core controls are presented on the screen.

[enwired]

Whatever way you choose to do it, I would hope to retain some possibility of customizing the title bar. My bosses required a wide logo on the left edge plus some centered text.

In certain special windows we also replace the "close" icon with a different icon representing something like "re-dock". (We allow tabs in a tabbed pane to be un-docked to separate windows and then re-docked into the tabbed pane.)

Comments in the existing code hint that you are already aware the class could be improved to better support right-to-left text, for example.

[kirill-grouchnikov]

I'll handle https://github.com/kirill-grouchnikov/substance/issues/61 and this one as part of the same extensibility API

[kirill-grouchnikov]

Reference for how UWP / AppKit handle this:

https://docs.microsoft.com/en-us/windows/uwp/design/shell/title-bar https://developer.apple.com/documentation/appkit/nsfullsizecontentviewwindowmask https://developer.apple.com/documentation/appkit/nswindow/1419167-titlebarappearstransparent

The tentative plan is:

• API to mark a root pane to extend into the title bar
• API to return a new instance of a title button so that it looks consistent with other control buttons (close, minimize, maximize)
• API to return title area left / right insets to prevent extended root pane content from overlapping with control buttons

The intent is to enable apps to create layouts like the attached

[kirill-grouchnikov]

As for the original request, I still do not plan to expose SubstanceTitlePane / SubstanceInternalFrameTitlePane to apps.

Instead, if you want to tweak the contents of the title pane it will be like this:

1. Use the new API to extend your content into the title pane - with proof of concept being the Flamingo plugin for ribbon and a couple of demo apps.
2. Use the new APIs for left / right title pane insets + title pane height.
3. Use the new API to get one or more additional title pane control buttons.

From this point, you will be fully in charge of:

1. Drawing the background of the title pane - with SubstanceDecorationPainter.paintDecorationArea + SubstanceOverlayPainter.paintOverlay
2. Positioning and drawing the title text itself - get the font with FontSet.getWindowTitleFont, apply drop shadow if necessary, etc
3. Positioning of additional content - app logo, etc

All of these need to be validated in at least a couple of demo apps

[kirill-grouchnikov]

Work in progress (code upload coming up shortly)

[kirill-grouchnikov]

The code behind this app is in https://github.com/kirill-grouchnikov/substance-demo/tree/master/src/org/pushingpixels/demo/substance/main/visor at the present moment. It might move to substance-samples at some point in the future.

For now it's showing the usage of the new APIs to extend the content into the title pane, create a title pane button that looks consistent with existing control buttons (the small refresh in the left pane), and tweak the title pane height to accommodate taller content (like in the screenshot above for the search field) to create consistent vertical alignment across the top section.

[kirill-grouchnikov]

Second pass for the mail demo app

[kirill-grouchnikov]

All the planned APIs are in place.

The new SubstanceCortex.WindowScope APIs for extending content into the title pane, querying the insets, creating a button and increasing the height. Plus the existing skin / painter APIs to draw the background of your custom title pane.

SubstanceTitlePane remains an internal implementation detail. At some point in the future with Java 9 modules it will not be accessible at all to apps.

[kirill-grouchnikov]

See the last section of https://github.com/kirill-grouchnikov/substance/blob/master/www/release-info/8.0/release-info.md for the API overview

[enwired]

I have downloaded the demos and played with the VisorMail example (shown above).

I have noticed that when using extendContentIntoTitlePane(true), the "maximize" icon does not change into a "restore" icon when the window is maximized. I think that is a bug.

I think I can do what I need to do by using the API provided. When title pane height is increased using WindowScope.setPreferredTitlePaneHeight, I would probably prefer that the window control icons (close, minimize, etc.) be aligned close to the upper edge of the window rather than vertical center of the title bar. Maybe do that by default, or implement a new SubstanceSlices.Gravity.TOP_EDGE_CENTERED constant, or something like that.

Am I understanding correctly that when using extendContentIntoTitlePane(true), the frame title and icon are simply not displayed at all regardless of any settings for GlobalScope.configureTitleContentGravity ?

[kirill-grouchnikov]

So perhaps setPreferredTitlePaneHeight should get another parameter - vertical gravity for aligning the control buttons.

And then getTitlePaneControlInsets would become getTitlePaneControlBounds that returns a rectangle that app-specific title pane layout should not "go into".

[kirill-grouchnikov]

Tracking the maximize/restore issue in https://github.com/kirill-grouchnikov/substance/issues/67

[kirill-grouchnikov]

And for the last question - calling extendContentIntoTitlePane only displays the control buttons. Nothing else - no background, no title, no icon. Those essentially become part of your content area and need to be positioned and drawn by the app side.

I'll add another small demo showing something like the title pane in HipChat

[kirill-grouchnikov]

The latest sources for the VisorMail demo now live at https://github.com/kirill-grouchnikov/substance-samples/tree/master/src/org/pushingpixels/samples/substance/mail

[kirill-grouchnikov]

Couple more Visor demos that will be in substance-samples shortly. The first one is a retouch of the Cookbook sample that was there all along, with the change that pushes some of the toolbar content into the title pane area:

The second one is much simpler, showing how to use WindowScope.getTitlePaneControlInsets to respect the insets required for the control buttons:

In both examples the title pane area is "marked" with ComponentScope.setDecorationAreaType(DecorationAreaType.PRIMARY_TITLE_PANE) on the relevant components that emulate the appearance of the title pane. No additional work is required to draw consistent visuals (with decoration and overlay painters) - although that is another option, of course.

[kirill-grouchnikov]

Source code for the two additional sample apps is at https://github.com/kirill-grouchnikov/substance-samples/tree/master/src/org/pushingpixels/samples/substance/cookbook and https://github.com/kirill-grouchnikov/substance-samples/tree/master/src/org/pushingpixels/samples/substance/chat