From d40d090f3f5ebb15720a4e80cc407f6fdbd5aed8 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Mon, 16 Dec 2024 16:26:15 +0100 Subject: [PATCH] popups.md: Cleanup --- topics/user_interface_components/popups.md | 35 ++++++++++++++-------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/topics/user_interface_components/popups.md b/topics/user_interface_components/popups.md index 85fa675e1..35ffe1829 100644 --- a/topics/user_interface_components/popups.md +++ b/topics/user_interface_components/popups.md @@ -4,7 +4,7 @@ Creating different kinds of popups. -The IntelliJ Platform user interface makes extensive use of popups \- semi-modal windows that have no chrome (explicit closing buttons) and disappear automatically on focus loss. +The IntelliJ Platform user interface makes extensive use of popups - semi-modal windows that have no chrome (explicit closing buttons) and disappear automatically on focus loss. Making use of these controls in your plugin ensures a consistent user experience between your plugin and the rest of the IDE. Popups can optionally display a title, are optionally movable and resizable (and support remembering their size), and can be nested (show another popup when an item is selected). @@ -21,22 +21,28 @@ The most commonly used methods are: ### Action Groups -Action group popups support different ways of choosing an action from the keyboard, in additional to the normal arrow keys. -By passing one of the constants in the [`JBPopupFactory.ActionSelectionAid`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) enumeration, you can choose whether an action can be selected by pressing a key corresponding to its sequential number, typing part of its text (speed search) or pressing a mnemonic character. -For popups with a fixed set of items, the recommended selection method is sequential numbering; -for popups with a variable and potentially large number of items, speed search typically works best. +Action group popups support different ways of choosing an action from the keyboard, in addition to the normal arrow keys. +By passing one of the constants in the [`JBPopupFactory.ActionSelectionAid`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) enumeration, you can choose whether an action can be selected by +- pressing a key corresponding to its sequential number +- typing part of its text (speed search) +- pressing a mnemonic character + +For popups with a fixed set of items, the recommended selection method is sequential numbering. +For popups with a variable and potentially large number of items, speed search typically works best. ### List Popups -If you need to create a list-like popup which is more flexible than a simple +To create a list-like popup which is more flexible than a simple [`JList`](https://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html) -but don't want to represent the possible choices as actions in an action group, you can work directly with the -[`ListPopupStep`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/ui/popup/ListPopupStep.java) -interface and the +and doesn't represent the possible choices as actions in an action group, use [`JBPopupFactory.createListPopup()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) -method. -Normally you don't need to implement the entire interface; instead, you can derive from the [`BaseListPopupStep`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/popup/util/BaseListPopupStep.java) class. -The key methods to override are `getTextFor()` (returning the text to display for an item) and `onChosen()` (called when an item is selected). +with a +[`ListPopupStep`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/ui/popup/ListPopupStep.java) +implementation (usually, [`BaseListPopupStep`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/popup/util/BaseListPopupStep.java) is used as a base). +The key methods to override are: +- `getTextFor()` - returning the text to display for an item +- `onChosen()` - called when an item is selected + By returning a new popup step from the `onChosen()` method, you can implement hierarchical (nested) popups. ### Showing Popup @@ -48,4 +54,7 @@ You can let the IntelliJ Platform automatically choose the position based on the > {style="note"} -If you need to perform some action when the popup is closed, you can either attach a listener to it using the `addListener()` method, override a method of the popup contents such as [`PopupStep.onChosen()`](%gh-ic%/platform/core-ui/src/openapi/ui/popup/PopupStep.java), or attach an event handler to your own component within the popup. +To perform some action when the popup is closed, use one of the following approaches: +- attach a listener to it using the `addListener()` method +- override a method of the popup contents such as [`PopupStep.onChosen()`](%gh-ic%/platform/core-ui/src/openapi/ui/popup/PopupStep.java) +- attach an event handler to your own component within the popup