Allow to show status bar entries with an id and name

[bpasero]

This would allow us to hide/show individual entries from an extension to the status bar as opposed to hiding them all.

PS: this concept may be useful also for notifications to allow fine grained filtering.

[bpasero]

Current idea:

/**
 * Options to configure the status bar item.
 */
export interface StatusBarItemOptions {

	/**
	 * A unique identifier of the status bar item.
	 */
	id: string;

	/**
	 * A human readable name of the status bar item.
	 */
	name: string;

	/**
	 * The alignment of the status bar item.
	 */
	alignment?: StatusBarAlignment;

	/**
	 * The priority of the status bar item. Higher value means the item should
	 * be shown more to the left.
	 */
	priority?: number;
}

/**
 * Creates a status bar [item](#StatusBarItem).
 *
 * @param options The options of the item.
 * @return A new status bar item.
 */
export function createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem;

[Tyriar]

@bpasero what's the fallback name/id when options isn't specified?

[bpasero]

@Tyriar it will be the extension identifier and the extension name. See 3d91fa8

[jrieken]

We could also consider grouping id/name into a separate object and explain its purpose and (maybe) reuse that object elsewhere (notification & don't show again)?

[bpasero]

@jrieken yeah, I am not sure I can come up with a good name though unless we make this very specific to what it is used (filtering). To be honest, we already talk about identifiers in certain places, e.g. viewId in createTreeView, so it seems statusEntryId and notificationId are not too far off. Problem is that it needs a label too..

[bpasero]

Pushed as proposed API but we should only have the discussion about finalizing the API when we looked at notifications too where we have an interest to hide based on id.

[jrieken]

export function createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem;

export interface StatubarItem {
  readonly id: string;

  description?: string;
}

[bpasero]

Slight update to the proposal: I went with name and not description because I feel description is being used in many places to indicate further verbose text for an item (e.g. in custom trees). I think the risk is that extensions would fill in lots of text for a description property.

With name, it becomes more obvious that we want a short value. We also use name internally in the workbench.

export interface StatusBarItem {

	/**
	 * The identifier of this item.
	 *
	 * *Note*: if no identifier was provided by the {@link window.createStatusBarItem `window.createStatusBarItem`}
	 * method, the identifier will match the {@link Extension.id extension identifier}.
	 */
	readonly id: string;

	/**
	 * The (short) name of the entry, like 'Language Indicator', 'Git Status' etc.
	 */
	name: string | undefined;
}

/**
 * Creates a status bar {@link StatusBarItem item}.
 *
 * @param id The unique identifier of the item.
 * @param alignment The alignment of the item.
 * @param priority The priority of the item. Higher values mean the item should be shown more to the left.
 * @return A new status bar item.
 */
export function createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem;

[DanTup]

How will this be rendered in the menu? Will it be prefixed with the extensions name or should the name be descriptive enough to make it clear which extension it's for? (For example if I'm showing the Dart SDK Version in the status bar, should I use "SDK Version" and assume it'll render like "Dart: SDK Version" or should I set it to "Dart SDK Version"?)

[bpasero]

@DanTup that is a good point, currently it will not be prefixed. I feel this is something we can always add later when we think it is needed.

To be honest, we do not prefix in other locations so I think we should not just do it without good reasons. E.g. here an extension provides the "GitHub" view and it is not treated any different from other views:

[DanTup]

@bpasero sounds good to me. It may be worth noting that in the doc to encourage people to make the names descriptive enough.

It does raise a question about what if there are dupes from different extensions, although it seems like even if they had the same labels here it'd be fairly easy to know which is which by just toggling.

[bpasero]

Yeah good point, updated the JSDoc to:

/**
 * The name of the entry, like 'Python Language Indicator', 'Git Status' etc.
 * Try to keep the length of the name short, yet descriptive enough that
 * users can understand what the status bar item is about.
 */
name: string | undefined;