Adapt overlay icon calculation for customization by LSP4E clients

- Extract method for determining all overlay icons so that clients can
override it to customize overlay icons.
- Introduce convenience method for determining a symbol's name.
- Forward the symbol object to methods for calculating the symbol's icon
and overlay icons so that clients could use additional symbol details
for customization, e.g. name and details fields.

Author: travkin79

org.eclipse.lsp4e/src/org/eclipse/lsp4e/callhierarchy/CallHierarchyLabelProvider.java

@@ -39,7 +39,7 @@ public CallHierarchyLabelProvider(SymbolIconProvider symbolIconProvider) {
 	public @Nullable Image getImage(final @Nullable Object element) {
 		if (element instanceof CallHierarchyViewTreeNode treeNode) {
 			CallHierarchyItem callContainer = treeNode.getCallContainer();
-			Image res = symbolIconProvider.getImageFor(callContainer.getKind(), callContainer.getTags());
+			Image res = symbolIconProvider.getImageFor(callContainer.getKind(), callContainer.getTags(), element);
 			if (res != null) {
 				return res;
 			}

org.eclipse.lsp4e/src/org/eclipse/lsp4e/operations/typeHierarchy/TypeHierarchyItemLabelProvider.java

@@ -39,7 +39,7 @@ public String getText(Object element) {
 	@Override
 	public @Nullable Image getImage(@Nullable Object element) {
 		if (element instanceof TypeHierarchyItem item) {
-			return symbolIconProvider.getImageFor(item.getKind(), item.getTags());
+			return symbolIconProvider.getImageFor(item.getKind(), item.getTags(), element);
 		}
 		return element == null ? null : super.getImage(element);
 	}

org.eclipse.lsp4e/src/org/eclipse/lsp4e/outline/SymbolsLabelProvider.java

@@ -170,7 +170,7 @@ public void dispose() {
 		}
 
 		if (actualElement != null && symbolKind != null) {
-			return symbolIconProvider.getImageFor(symbolKind, symbolTags, getMaxSeverity(actualElement));
+			return symbolIconProvider.getImageFor(symbolKind, symbolTags, getMaxSeverity(actualElement), actualElement);
 		}
 
 		return null;

org.eclipse.lsp4e/src/org/eclipse/lsp4e/ui/LSPImages.java

@@ -292,8 +292,8 @@ public static ImageRegistry getImageRegistry() {
 	 *
 	 * @see #getImage(String))
 	 * @see #getImageDescriptor(String)
-	 * @see SymbolIconProvider#getImageFor(SymbolKind, java.util.List)
-	 * @see SymbolIconProvider#getImageFor(SymbolKind, java.util.List, int)
+	 * @see SymbolIconProvider#getImageFor(SymbolKind, java.util.List, Object)
+	 * @see SymbolIconProvider#getImageFor(SymbolKind, java.util.List, int, Object)
 	 */
 	public static @Nullable Image imageFromSymbolKind(@Nullable SymbolKind kind) {
 		if (kind == null) {

org.eclipse.lsp4e/src/org/eclipse/lsp4e/ui/SymbolIconProvider.java

@@ -21,8 +21,12 @@
 import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.jface.viewers.LabelProvider;
 import org.eclipse.lsp4e.operations.symbols.SymbolsUtil;
+import org.eclipse.lsp4e.outline.SymbolsModel.DocumentSymbolWithURI;
+import org.eclipse.lsp4j.DocumentSymbol;
+import org.eclipse.lsp4j.SymbolInformation;
 import org.eclipse.lsp4j.SymbolKind;
 import org.eclipse.lsp4j.SymbolTag;
+import org.eclipse.lsp4j.WorkspaceSymbol;
 import org.eclipse.swt.graphics.Image;
 import org.eclipse.ui.ISharedImages;
 
@@ -33,6 +37,30 @@
  */
 public class SymbolIconProvider {
 
+	/**
+	 * Returns a symbol's name if the given symbol is an instance of
+	 * {@link DocumentSymbol}, or {@link DocumentSymbolWithURI},
+	 * {@link SymbolInformation}, or {@link WorkspaceSymbol},
+	 * returns <code>null</code> otherwise.
+	 *
+	 * @param symbol the symbol to get the name for
+	 * @return the symbol's name or <code>null</code>.
+	 */
+	protected @Nullable String getName(Object symbol) {
+		String name = null;
+		if (symbol instanceof SymbolInformation info) {
+			name = info.getName();
+		} else if (symbol instanceof WorkspaceSymbol wpSymbol) {
+			name = wpSymbol.getName();
+		} else if (symbol instanceof DocumentSymbol docSymbol) {
+			name = docSymbol.getName();
+		} else if (symbol instanceof DocumentSymbolWithURI symbolWithURI) {
+			name = symbolWithURI.symbol.getName();
+		}
+
+		return name;
+	}
+
 	/**
 	 * Returns an overlay icon {@link ImageDescriptor} for the given severity.
 	 *
@@ -154,6 +182,10 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 		Optional<SymbolTag> visibilityTag = getHighestPrecedenceVisibilitySymbolTag(symbolTags);
 
 		if (visibilityTag.isEmpty()) {
+			if (kind == SymbolKind.Constructor) {
+				// we'll add a constructor overlay icon instead in #getOverlaysFor(...), this way, the overlays will be customizable
+				return LSPImages.IMG_METHOD;
+			}
 			return LSPImages.imageKeyFromSymbolKind(kind);
 		}
 
@@ -189,12 +221,14 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 	 *
 	 * @param symbolKind the kind of symbol
 	 * @param symbolTags the symbol tags
+	 * @param symbol the symbol for which an image should be returned, may be used by subclasses to determine the image to return
 	 * @return a new or cached image for the given symbol kind with overlay icons computed for the given arguments.
 	 *
-	 * @see #getImageFor(SymbolKind, List, int)
+	 * @see #getImageFor(SymbolKind, List, int, Object)
 	 */
-	public @Nullable Image getImageFor(@Nullable SymbolKind symbolKind, @Nullable List<SymbolTag> symbolTags) {
-		return getImageFor(symbolKind, symbolTags, -1);
+	public @Nullable Image getImageFor(@Nullable SymbolKind symbolKind, @Nullable List<SymbolTag> symbolTags,
+			Object symbol) {
+		return getImageFor(symbolKind, symbolTags, -1, symbol);
 	}
 
 	/**
@@ -206,12 +240,13 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 	 * @param symbolKind the kind of symbol
 	 * @param symbolTags the symbol tags
 	 * @param severity one of -1, {@link IMarker#SEVERITY_WARNING}, and {@link IMarker#SEVERITY_ERROR}. -1 indicates no overlay icon.
+	 * @param symbol the symbol for which an image should be returned, may be used by subclasses to determine the image to return
 	 * @return a new or cached image for the given symbol kind with overlay icons computed for the given arguments.
 	 *
-	 * @see #getImageFor(SymbolKind, List)
+	 * @see #getImageFor(SymbolKind, List, Object)
 	 */
 	public @Nullable Image getImageFor(final @Nullable SymbolKind symbolKind,
-			final @Nullable List<SymbolTag> symbolTags, int severity) {
+			final @Nullable List<SymbolTag> symbolTags, int severity, Object symbol) {
 
 		if (symbolKind == null) {
 			return LSPImages.imageFromSymbolKind(symbolKind);
@@ -221,10 +256,29 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 
 		String baseImageKey = getImageKeyFromSymbolKindWithVisibility(symbolKind, finalSymbolTags);
 
+		Overlays overlays = getOverlaysFor(symbolKind, finalSymbolTags, severity, symbol);
+
+		return LSPImages.getImageWithOverlays(baseImageKey, overlays.topLeft, overlays.topRight,
+				overlays.bottomLeft, overlays.bottomRight, overlays.underlay);
+	}
+
+	/**
+	 * Determines the overlay icons to be shown for a symbol with the given arguments.
+	 * Sub-classes may override this method to customize the overlay icons.
+	 *
+	 * @param symbolKind the symbol kind, e.g. field, method, constructor, class, property
+	 * @param symbolTags the symbol tags, e.g. visibility tags, deprecation tag, static tag, final tag
+	 * @param severity the severity of the most severe marker associated with the symbol, or -1 if no marker is associated with the symbol
+	 * @param symbol the original symbol, i.e. an instance of {@link DocumentSymbol}, {@link DocumentSymbolWithURI}, {@link SymbolInformation}, or {@link WorkspaceSymbol}
+	 * @return The overlay icons to display for the given symbol
+	 */
+	protected Overlays getOverlaysFor(final SymbolKind symbolKind,
+			final List<SymbolTag> symbolTags, int severity, Object symbol) {
+
 		ImageDescriptor severityImageDescriptor = getOverlayForMarkerSeverity(severity);
-		ImageDescriptor deprecatedImageDescriptor = getUnderlayForDeprecation(SymbolsUtil.isDeprecated(finalSymbolTags));
+		ImageDescriptor deprecatedImageDescriptor = getUnderlayForDeprecation(SymbolsUtil.isDeprecated(symbolTags));
 
-		List<SymbolTag> additionalTags = getAdditionalSymbolTagsSorted(finalSymbolTags);
+		List<SymbolTag> additionalTags = getAdditionalSymbolTagsSorted(symbolTags);
 
 		ImageDescriptor topLeftOverlayDescriptor = null;
 		ImageDescriptor topRightOverlayDescriptor = null;
@@ -233,8 +287,7 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 		ImageDescriptor underlayDescriptor = deprecatedImageDescriptor;
 
 		// special case for a constructor with visibility tag => we need to add a "C" overlay to show it's a constructor
-		if (SymbolKind.Constructor == symbolKind
-				&& !baseImageKey.equals(LSPImages.imageKeyFromSymbolKind(symbolKind))) {
+		if (SymbolKind.Constructor == symbolKind) {
 			topRightOverlayDescriptor = LSPImages.getImageDescriptor(LSPImages.IMG_OVR_CONSTRUCTOR);
 		}
 
@@ -262,11 +315,29 @@ protected String getImageKeyFromSymbolKindWithVisibility(SymbolKind kind, List<S
 			// The top left and top right corners remain for additional symbol tags (besides visibility, severity, deprecation)
 			// In case of constructors we already have a "C" for "constructor" in the upper right corner
 			// and have use the lower right corner for another additional symbol tag.
-			bottomRightOverlayDescriptor = getOverlayForVisibility(finalSymbolTags);
+			bottomRightOverlayDescriptor = getOverlayForVisibility(symbolTags);
 		}
 
-		return LSPImages.getImageWithOverlays(baseImageKey, topLeftOverlayDescriptor, topRightOverlayDescriptor,
-				bottomLeftOverlayDescriptor, bottomRightOverlayDescriptor, underlayDescriptor);
+		return new Overlays(topLeftOverlayDescriptor, topRightOverlayDescriptor, bottomLeftOverlayDescriptor,
+				bottomRightOverlayDescriptor, underlayDescriptor);
+	}
+
+	public static final class Overlays {
+		public final @Nullable ImageDescriptor topLeft;
+		public final @Nullable ImageDescriptor topRight;
+		public final @Nullable ImageDescriptor bottomLeft;
+		public final @Nullable ImageDescriptor bottomRight;
+		public final @Nullable ImageDescriptor underlay;
+
+		public Overlays(@Nullable ImageDescriptor topLeft, @Nullable ImageDescriptor topRight,
+				@Nullable ImageDescriptor bottomLeft, @Nullable ImageDescriptor bottomRight,
+				@Nullable ImageDescriptor underlay) {
+			this.topLeft = topLeft;
+			this.topRight = topRight;
+			this.bottomLeft = bottomLeft;
+			this.bottomRight = bottomRight;
+			this.underlay = underlay;
+		}
 	}
 
 }