Add Dashboard API and use to provide replacement for Welcome page

[neilcsmith-net]

This PR provides a new, in-development, Dashboard API in the platform, and uses it to provide a replacement for the current Welcome page in the IDE.

A widget is a way of contextually grouping actions, textual information, images and links on a dashboard. A widget is a logical description of these elements (similar perhaps to NotifyDescriptor) - a dashboard displayer handles actual rendering to a UI, providing ability to unify design, or output other than with Swing. Widgets are registered in the layer (Dashboard/Widgets) and referenced where used (currently just Dashboard/Main). The idea is to allow for future customization similar to how toolbars reference actions, and to allow alternative contextual dashboards, such as perhaps an editor dashboard providing a customizable quick overview of the file in question.

Why an API? Well, initially I was writing this for two platform applications that need to collate and show information from different modules. It overlapped with improvements I think need to be made to the current Welcome page, which looks out of place now, and doesn't "grow" with the user to remain a useful tool. Ideally, widgets get provided by modules in the same way that actions are, rather than all residing within the IDE welcome page replacement. The addition of two friend API here provides evidence of why we might want to do that in future, and means that at the moment, those widgets could not be replicated in a platform application. We might also provide additional widgets that the user can add as they get more experienced.

Post NB22 development should (and will from me) focus on adding customization, layer generating annotations, additional widgets and stabilization. Possibly also an overlay displayer in addition to top component.

I realise this is a somewhat large change close to freeze. I was hoping to get it in a bit earlier, and realise it is likely to require some discussion, additional testing and tweaks. Would love to get it in to NB22 though - I'd still like to use it in those platform applications!

Current dashboard display with light and dark themes -

[ebarboni]

make sense

just a pointer for API related tasks that look or in this PR for me, https://netbeans.apache.org/wiki/main/wiki/APIDevelopment/ (not reviewed)

[neilcsmith-net]

Thanks @ebarboni - specifically this is using (hopefully correctly!) the approach outlined at https://netbeans.apache.org/wiki/main/wiki/APIDevelopment/#Support_for_Early_Adoption One exception would be that with a quarterly release cycle, we should probably consider "next release" to mean "next few releases".

[mbien]

could the dashboard open on second launch? The new minimalistic empty-editor-pane has all the bootstrap actions already and once the user has something open there would be no empty pane anyway, thats when the dashboard becomes more useful.

[neilcsmith-net]

I've pushed a change to disable on start by default. And fixed the issue with the background editor actions not showing - bizarrely caused by the removed Welcome component not opening and closing before display. Also added the missing license text rat was complaining about in the generated arch.xml.

@mbien I'm not a fan of behaviour changes based on how many times you've run something - I think it's confusing for the user. I've disabled for now, and possibly we go with this for now while it matures? However, one other option would be to make the showOnStartup attribute an enum rather than a boolean flag - with Never, Always and WithOpenEditors or similar?

[mhalachev]

@neilcsmith-net Looks very nice! :) Below are some suggestions, partially inspired by the old Welcome screen which actually contains some helpful information scattered across the tabs.

Should the layout be rearranged a little bit, an additional pane may be placed, for example, a set of links to demos and tutorials, or something else:

With a little bit of rearrangement a 3x2 layout may be obtained in a way, that on the first row, there will be items that can be open (projects, files, tutorials), and on the second -- items related to the IDE itself:

Eventually, the atom feed (preferably with the latest item only) may be added below as a "counterweight" to the header. It is also useful -- actually, I often get the new release announcements there first :)

Here is a mockup of what it might look like:

What about making the dashboard itself customisable in future releases, so that the user can add/remove and rearrange items?

P.S. Noticed a small glitch with the dev build: While using some themes (CDE/Motif, Mac OS X), each pane is delineated by borders, and the links/buttons share the same color as the main text:

[neilcsmith-net]

Thanks @mhalachev

Header and footer elements are unlikely to be added, because the default displayer is not a fixed 3x2 grid - it's fluid. Nor is a dashboard displayer guaranteed to have that configuration. It might be possible to consider, but it would take some thought to incorporate into the API, and I'm not convinced it's actually desirable.

What about making the dashboard itself customisable in future releases, so that the user can add/remove and rearrange items?

Yes! The API is designed to allow this, and already provides the ability for platform applications to register their own widgets for display. A UI for customization can hopefully come in the next release or so, but without a selection of other widgets to display, doesn't offer much at this stage besides moving around what's there. This is covered in the description. One step at a time! 😄

an additional pane may be placed, for example, a set of links to demos and tutorials,

These were left out deliberately at this stage, because I think we need to look at providing useful and current demos and tutorials if we're going to put them front and centre. There is the possibility of linking these into Learn & Discover already - I don't think we need another widget for that. That's where they are on the old welcome page. We could consider a link to https://netbeans.apache.org/tutorial/main/kb/docs/ but that landing page should probably be rearranged. The sample projects need to probably include something other than Ant for Java!

Eventually, the atom feed ...

A feed widget is possible. But, if the only point of the feed is to give notification of a new release (and that's all that's been there for a long time!) we already have another mechanism for that. I started looking at making the Check for Updates link dynamic so that it eg. changes to Updates Available, New IDE release available, etc. It would probably also change from hyperlink to button to grab attention.

each pane is delineated by borders ...

Yes, thanks. I'd noticed on macOS, but hadn't checked with Motif. The code removes the scrollpane border, but not the one some UIs set on the viewport. Will look at fixing that and update this PR before moving out of draft. The link colour is from nb.html.link.foreground, but not every look-and-feel customs is setting that. I'm not sure about adding a hardcoded fallback in the displayer. It works on the supported (and default) look and feels.

[neilcsmith-net]

Have hopefully fixed the issue with the viewport border, link colours and hover underline on a few non-default LAFs. Seems OK on Motif, but not verified macOS yet. The fallback link colour is the one used elsewhere in the codebase where that UI value is null.

[mhalachev]

Thanks @neilcsmith-net

I missed that the view is actually fluid, which is actually also useful as the dash can be kept visible as a narrow side pane:

Regarding the "header" layout, what about a little trick, with an additional row to hold separate dashboard items?

In this case, given that the layout is fluid, it possibly should fold like this by itself in a narrow window:

Update:

Have hopefully fixed the issue with the viewport border, link colours and hover underline on a few non-default LAFs. Seems OK on Motif, but not verified macOS yet.

I can confirm that it is now fine with Motif, but still with border with the Mac OS X theme:

Links are ok with both themes.

[neilcsmith-net]

That could involve widgets knowing far more about how they're displayed than I wanted to expose. At the moment a widget is just an instance registered in the layer file system that produces a list of logical elements that it wants to display (eg. text, image, link). How those elements are rendered is in the hands of the displayer.

See eg. https://github.com/apache/netbeans/blob/55834afe83a504f9854bab2297f776cc3fe010ac/nb/ide.dashboard/src/org/netbeans/modules/ide/dashboard/HelpWidget.java and the available element types https://github.com/apache/netbeans/blob/55834afe83a504f9854bab2297f776cc3fe010ac/platform/api.dashboard/src/org/netbeans/spi/dashboard/WidgetElement.java These things deliberately know nothing about how they are displayed, or have any reference to grids, size or Swing.

Fluid sized widgets could be a thing, along with a spacer (empty) widget, to achieve your suggested rendering. It was a lot easier to achieve the fluid grid with fixed size widgets though!

[Chris2011]

Just make it simple as possible as you alraedy have the checkbox "show on startup". Thats it.

[neilcsmith-net]

@Chris2011 I wasn't proposing anything more complicated in the IDE dashboard than a checkbox, just whether the API (and the showOnStartup attribute is effectively part of that) should be able to handle more options than a simple boolean.

This PR adds a new platform API as well as a new IDE dashboard. While it's marked as still in development, it would be good to review that aspect, and apply any necessary changes, so that this can be merged this week if it's going to go in at all.

Adding Platform label as well as temporarily ci:all-tests in case the additional modules cause anything to need to be addressed. Might need excluding in VSCode for now?

[mhalachev]

Thanks @neilcsmith-net for the information regarding the actual widget implementation! I'll definitely look into it more extensively.

The overall concept of the Dashboard API is presenting a lot of opportunities. One may envision practical enhancements like Tasks and ToDos as widgets, and other stuff in the form of Plugins...

I hope the layout suggestions, albeit raw (spacers, headers, etc.), may offer utility for future use.

Meanwhile, I think I managed to fix the MacOS X theme border issue.

I can confirm that it is now fine with Motif, but still with border with the Mac OS X theme:

Setting the border to 0 in WidgetPanel.java (l. 107) seems to do the trick:

        scrollPane.setBorder(BorderFactory.createEmptyBorder());

PS: Can also confirm that looks good with CDE/Motif as well.

[neilcsmith-net]

Thanks @mhalachev - hopefully this change fixes things. I can't remember why the extra pixel was there, but seems OK without now, and I guess was allowing a background colour to show through???

The overall concept of the Dashboard API is presenting a lot of opportunities. One may envision practical enhancements like Tasks and ToDos as widgets, and other stuff in the form of Plugins...

Thanks. Yes, that's definitely part of my thinking, and allowing these things to be in the relevant modules, not require exposing API, while keeping the overall display coordinated.

[eirikbakke]

Ooh, nice work! Trying to build NetBeans with this patch included, I get the following error:

-do-compile:
 [nb-javac] Compiling 10 source files to Z:\nbsrc\incubator-netbeans\platform\api.dashboard\build\classes
 [nb-javac] Ignoring source, target and bootclasspath as release has been set
   [repeat] error: release version 17 not supported
   [repeat] Usage: javac <options> <source files>
   [repeat] use --help for a list of possible options
  [nbmerge] Failed to build target: all-api.dashboard

My environment system is currently set up to use Java 11. Is NetBeans supposed to require a higher Java version to build these days?

[neilcsmith-net]

My environment system is currently set up to use Java 11. Is NetBeans supposed to require a higher Java version to build these days?

Yes, Java 17 from NetBeans 22. As this is a completely new API, and there are some benefits to using 17, I did so.

Ooh, nice work!

Thanks! 😄 Do you think this is something you might find useful in a platform application? If so, are there any concerns or things you'd like to see even in this first iteration?

[mhalachev]

hopefully this change fixes things. I can't remember why the extra pixel was there, but seems OK without now, and I guess was allowing a background colour to show through???

@neilcsmith-net I can confirm that it now works as expected:

Indeed, it was possibly either a background color popping in or an explicitly set border in the theme if the default is transparent...

PS: Just noticed something... the shortcut color in #7171 also gets black with CDE/Motif and Mac OS X themes:

Here is FlatLaf (blue):

Maybe it could be fixed similarly to links and buttons colours for the dashboard, but for the shortcut color in the editor background... 🤔

[mbien]

I like it! Code looks good too.

Since it is essentially a editor tab, I checked how it would look with the editor bg color:

diff --git a/platform/api.dashboard/src/org/netbeans/modules/dashboard/DashboardTopComponent.java b/platform/api.dashboard/src/org/netbeans/modules/dashboard/DashboardTopComponent.java
index 4aa9cb1..ebdeea0 100644
--- a/platform/api.dashboard/src/org/netbeans/modules/dashboard/DashboardTopComponent.java
+++ b/platform/api.dashboard/src/org/netbeans/modules/dashboard/DashboardTopComponent.java
@@ -18,6 +18,7 @@
  */
 package org.netbeans.modules.dashboard;
 
+import java.awt.Color;
 import java.util.List;
 import org.netbeans.api.dashboard.DashboardManager;
 import org.netbeans.api.settings.ConvertAsProperties;
@@ -59,6 +60,7 @@
         scrollPane.getVerticalScrollBar().setUnitIncrement(20);
         setName(Bundle.CTL_DashboardTopComponent());
         setToolTipText(Bundle.HINT_DashboardTopComponent());
+        dashContainer.setBackground(new Color(43, 43, 43));  // take editor bg
     }
 
     /**
diff --git a/platform/api.dashboard/src/org/netbeans/modules/dashboard/WidgetPanel.java b/platform/api.dashboard/src/org/netbeans/modules/dashboard/WidgetPanel.java
index ab76b22..18f5005 100644
--- a/platform/api.dashboard/src/org/netbeans/modules/dashboard/WidgetPanel.java
+++ b/platform/api.dashboard/src/org/netbeans/modules/dashboard/WidgetPanel.java
@@ -63,6 +63,7 @@
         title = "";
         elements = List.of();
         attachWidget();
+        setOpaque(false);
     }
 
     private void attachWidget() {
@@ -99,10 +100,13 @@
             add(titleComponent, BorderLayout.NORTH);
         }
         JPanel container = new JPanel(new GridBagLayout());
+        container.setOpaque(false);
         JScrollPane scrollPane = new JScrollPane(
                 container,
                 JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED,
                 JScrollPane.HORIZONTAL_SCROLLBAR_NEVER);
+        scrollPane.setOpaque(false);
+        scrollPane.getViewport().setOpaque(false);
         scrollPane.getVerticalScrollBar().setUnitIncrement(20);
         scrollPane.setBorder(BorderFactory.createEmptyBorder());
         scrollPane.setViewportBorder(BorderFactory.createEmptyBorder());

both looks fine imo. Not sure if its better or worse.

[neilcsmith-net]

Thanks @mbien With regards colours, I kept the default background and opaque components (for now at least) for a number of reasons - it should hopefully work across all LAFs (even if we don't support them!); it blends with the active tab colour (which Eirik pointed out in discussions about the new tabs); and I'd still like to look at an alternative overlay displayer in future anyway, which would make sense of higher contrast colours.

I'll squash this and prepare for merging tomorrow unless anyone has additional comments / changes they want to see?

[mhalachev]

PS: Just noticed something... the shortcut color in #7171 also gets black with CDE/Motif and Mac OS X themes:

I can confirm that this works as expected and colors appear in editor background like in the Dashboard while using the aforementioned themes:

diff --git a/platform/core.windows/src/org/netbeans/core/windows/view/EditorView.java b/platform/core.windows/src/org/netbeans/core/windows/view/EditorView.java
index 40662c1af7..32b59cbf52 100644
--- a/platform/core.windows/src/org/netbeans/core/windows/view/EditorView.java
+++ b/platform/core.windows/src/org/netbeans/core/windows/view/EditorView.java
@@ -487,6 +487,9 @@ public class EditorView extends ViewElement {
             Color shortcutColor = UIManager.getColor("EditorTab.underlineColor");
             if (shortcutColor != null) {
                 shortcut.setTitleColor(shortcutColor);
+            } else {
+                shortcutColor = new Color(0x164B7B);
+                shortcut.setTitleColor(shortcutColor);
             }
             Font font = getFont();
             if (font != null) {

Result:

@neilcsmith-net Could we get this in here, without another PR? It fixes the same theme-specific color issue...

[neilcsmith-net]

@mhalachev please open another PR for that one.

[mbien]

I forgot to mention: please check if the old welcome page code can be removed during NB 23 dev cycle. I don't think its public api, if it is, it should be deprecated asap, ideally with this PR.

[neilcsmith-net]

@mbien it's not API, and it's already removed from the list of modules for the source zip and build, but not from the repository, as part of this. I am planning to put in a follow up PR to remove the module code during NB23, once we're sure everything in there is no longer required.

[eirikbakke]

@neilcsmith-net Adding a Welcome page to Ultorg is actually on my short-term TODO list. My platform app has its own project management system (not the NetBeans Projects/Files API anymore), and an existing TopComponent subclass that I need to reuse, so I probably will end up with a custom impementation. But I find it very useful to look at existing NetBeans code to see how similar things are done within the framework of the platform. I'll be using your code as a reference!

[neilcsmith-net]

@eirikbakke the platform API is designed for this purpose. In fact, none of the IDE's widgets can be reused in the platform currently - the files and projects widgets require friends access for now, but could move into those modules for reuse later.

The API supports alternative displayers. You could certainly display it wherever you want, including in a custom TopComponent. The missing piece at the moment is an SPI support class to access the default Swing-based panel, widget and component renderers. You'd have to copy that across. I was planning that access as part of the additional improvements I personally intend to work on for this in NB23, alongside those in the original description. If access to that is useful for you earlier, it's an easy addition for NB22. Just say. I'm personally going to be using the default displayer for now.

[eirikbakke]

@neilcsmith-net Thanks for those notes! I haven't finished the design of the Ultorg welcome tab yet, but the current goal is to have it work like the "New Tab" tab in Google Chrome, where the welcome tab "becomes" the editor when you open an item from a Search bar or the Recents list, rather than opening a new tab. That's why I'm thinking of Ultorg's welcome tab more as an alternative panel in my existing custom TopComponent than as an entirely new kind of TopComponent.

One API feature that I will probably add for my own use is the ability to add "+" button after the row of tabs, which, if clicked, would open an application-specified "New Tab" tab.

I'll probably just hack my own access to relevant classes and private APIs for now, and once my own code has stabilized and been in use for a while, I might request or propose relevant APIs to be opened.