mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 09:17:50 +08:00
d8e83b57ea
* Add UI Guidelines to SDK docs * Add UI Guidelines to SDK docs * Fixing build errors * optimize PNGs * add UI guidelines landing page placeholder * IJ SDK Docs <-> UI guidelines crosslinks updated * split_button.md: remove reference to removed setting * use <ui-path> * use MD instead of <note> * use %gh-ic% links * drop_down.md: fix <control> * code samples: fix most obvious issues * remove obsolete `_defaults.md` * ijs.tree: UI cleanup * Delete "under construction" pages * Fix headers * Add link-summary * Remove invalid links * Delete unused files * Remove ''@2x' from image file names * Use Markdown syntax for some images and tables * Rename non-unique files to unique * Remove alpha in images where content is unreadable * align quotation marks * Controls: cleanup/fixes, add code links, edit * tooltip.md: fix HTML * misc fixes * typography.md: fix table contents * typography.md: fix table header * UI guidelines landing page + TOC fixes * remove unused icons_list.md * Normalize image paths * validation_errors.md: Fix broken tab * "correct"/"incorrect" labels styling * Resize images to 50% * button.topic: fixes * grammar, spelling, minor edits * remove ' ' * fix 99px * cleanup * UI_kit.md: minor * Fix "MRK058: Large image in paragraph rendered as a block element by default." * button.topic: Add img[alt] * mnemonics.md: Update "Contact Us" link to the IJSDK YouTrack * split_button.md: Use ui-path * UI landing: add feedback snippet * Improve code snippets formatting and naming * Fix code samples * Fix code samples * Add Kotlin variants for code samples * Add icons_list.md * crosslinks * Change external link to https://intellij-icons.jetbrains.design/ * icons list -> https://intellij-icons.jetbrains.design * Hide info about reducing split button to simple action button (now it is available through the registry only) * reformat * icons_style.md: Images in new line --------- Co-authored-by: marianna.kononenko <marianna.kononenko@jetbrains.com> Co-authored-by: Yann Cébron <yann.cebron@jetbrains.com>
81 lines
4.2 KiB
Markdown
81 lines
4.2 KiB
Markdown
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
|
|
# User Interface FAQ
|
|
|
|
<link-summary>UI-related FAQs and utilities.</link-summary>
|
|
|
|
<include from="user_interface_components.md" element-id="inspectingExistingUI"/>
|
|
|
|
## Useful classes
|
|
|
|
- Package [`com.intellij.ui`](%gh-ic%/platform/util/ui/src/com/intellij/ui/)
|
|
- Package [`com.intellij.util.ui`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/)
|
|
|
|
## Colors
|
|
|
|
Always use [`JBColor`](%gh-ic%/platform/util/ui/src/com/intellij/ui/JBColor.java) instead of plain `java.awt.Color`
|
|
(highlighted via inspection <control>Plugin DevKit | Code | Use Darcula aware JBColor</control>).
|
|
Custom colors must be retrieved via `JBColor.namedColor()` set by the current [Theme](themes_getting_started.md).
|
|
See [](themes_metadata.md) on how to expose corresponding metadata.
|
|
|
|
If it's needed to retrieve a color from one place and use it in another, do not just retrieve once and use the retrieved value.
|
|
Instead, use `JBColor.lazy()` and pass in a lambda expression to retrieve the color.
|
|
This lambda expression needs to be fast and safe enough, as it will be called every time the color is retrieved, for example, for painting.
|
|
Following this approach ensures that the color will be properly updated if it's changed at the source, for example, due to a theme or scheme change.
|
|
|
|
Generic UI colors (e.g., for drawing borders) can be accessed via [`UIUtil`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/UIUtil.java)
|
|
and [`JBUI`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBUI.java).
|
|
A number of hardcoded colors is defined in `JBColor`, [`Gray`](%gh-ic%/platform/util/ui/src/com/intellij/ui/Gray.java), and [`LightColors`](%gh-ic%/platform/util/ui/src/com/intellij/ui/LightColors.java)
|
|
|
|
[`ColorUtil`](%gh-ic%/platform/util/ui/src/com/intellij/ui/ColorUtil.java) allows tuning existing colors.
|
|
|
|
## Text
|
|
|
|
<tldr>
|
|
|
|
**UI Guidelines:** [](data_formats.md)
|
|
|
|
</tldr>
|
|
|
|
Use [`NaturalComparator`](%gh-ic%/platform/util/base/src/com/intellij/openapi/util/text/NaturalComparator.java) for "natural" sorting of items.
|
|
|
|
[`StringUtil`](%gh-ic%/platform/util/src/com/intellij/openapi/util/text/StringUtil.java) contains a number of useful methods for manipulating text for UI usage:
|
|
|
|
- `unpluralize()/pluralize()` using English rules
|
|
- `formatDuration()` to format duration: _2 m 3 s 456 ms_
|
|
- `formatFileSize()` to format filesize: _1.23 KB_
|
|
- `escapeLineBreak()` and related methods to escape special characters
|
|
- `shortenTextWithEllipsis()` and `shortenPathWithEllipsis()` to produce abbreviated UI texts ending with '…'
|
|
- `quote()` and `unquoteString()` to wrap values: _Usages of "$value$": 218 found_
|
|
|
|
See [](internationalization.md) for information about internationalizing plugins.
|
|
|
|
See [`NlsMessages`](%gh-ic%/platform/ide-core-impl/src/com/intellij/ide/nls/NlsMessages.java) to produce localized messages.
|
|
|
|
## "Recently Used" entries
|
|
|
|
To store and retrieve values for *Recently Used* entries (e.g., filter values), use
|
|
[`RecentsManager`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/RecentsManager.java).
|
|
|
|
## Current Theme: Dark or Bright?
|
|
|
|
To determine the current [Theme](themes_getting_started.md)'s style, use [`JBColor.isBright()`](%gh-ic%/platform/util/ui/src/com/intellij/ui/JBColor.java).
|
|
|
|
## Borders and Insets
|
|
|
|
|
|
<tldr>
|
|
|
|
**UI Guidelines:** [](layout.md)
|
|
|
|
</tldr>
|
|
|
|
Always create borders and insets via factory methods from [`JBUI.Borders`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBUI.java) and [`JBUI.Insets`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBUI.java), which create DPI-aware instances.
|
|
Using standard DPI-agnostic instances (reported by inspection <ui-path>Plugin DevKit | Code | Use DPI-aware borders</ui-path> and <ui-path>Plugin DevKit | Code | Use DPI-aware insets</ui-path>)
|
|
can result in UI layout problems.
|
|
|
|
If you use DPI-aware insets in an empty border (`JBUI.Borders.empty()`), then the insets will be updated automatically, for example, if scaling is changed because the <ui-path>IDE Zoom</ui-path> action was performed or for any other reason.
|
|
If you use the insets elsewhere, you need to manually call `JBInsets.update()` in your component's `updateUI()` method to update the insets accordingly.
|
|
|
|
<include from="snippets.md" element-id="missingContent"/>
|