-
Notifications
You must be signed in to change notification settings - Fork 16
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: ui.action_group #895
Merged
AkshatJawne
merged 18 commits into
deephaven:main
from
AkshatJawne:829_action_group_docs
Oct 2, 2024
Merged
Changes from 14 commits
Commits
Show all changes
18 commits
Select commit
Hold shift + click to select a range
ef9a1f8
docs: ui.action_group
AkshatJawne 39eb31f
complete docs
AkshatJawne 26948ed
Update plugins/ui/docs/components/action_group.md
AkshatJawne c436e68
Update plugins/ui/docs/components/action_group.md
AkshatJawne 2d214a2
Update plugins/ui/docs/components/action_group.md
AkshatJawne 9c55424
Update plugins/ui/docs/components/action_group.md
AkshatJawne 2b25bb5
Update plugins/ui/docs/components/action_group.md
AkshatJawne 4964cf7
Merge branch '829_action_group_docs' of https://github.com/AkshatJawn…
AkshatJawne af62064
make changes based on PR comments
AkshatJawne 00073e9
remove unneccesary file
AkshatJawne a05fd24
Update plugins/ui/docs/components/action_group.md
AkshatJawne cb118e5
Update plugins/ui/docs/components/action_group.md
AkshatJawne 49388d7
Update plugins/ui/docs/components/action_group.md
AkshatJawne 5e56321
Update action_group.md
margaretkennedy 4ec3445
Update plugins/ui/docs/components/action_group.md
AkshatJawne 3a55aad
Merge branch '829_action_group_docs' of https://github.com/AkshatJawn…
AkshatJawne 252589e
modify icons
AkshatJawne 74b4908
add to sidebar.json
AkshatJawne File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,310 @@ | ||
# Action Group | ||
|
||
An action group is a UI component that groups multiple actions together. | ||
|
||
## Example | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_basic = ui.action_group( | ||
ui.item("Add"), | ||
ui.item("Edit"), | ||
ui.item("Delete"), | ||
) | ||
``` | ||
|
||
## UI recommendations | ||
|
||
Consider using a [`button_group`] to align multiple buttons that do not necessarily correspond to an action. | ||
|
||
|
||
## Icons | ||
|
||
Icons can be added to action group items by wrapping the label in a `ui.text` element and adding a `ui.icon` as a sibling component. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_icon_example = ui.action_group( | ||
ui.item(ui.icon("vsEdit"), ui.text("Edit")), | ||
ui.item(ui.icon("vsCopy"), ui.text("Copy")), | ||
ui.item(ui.icon("vsTrash"), ui.text("Delete")), | ||
) | ||
``` | ||
|
||
The `button_label_behavior` prop can be set to "hide" label text within buttons and show it in a tooltip on hover. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_button_label_behavior_example = ui.action_group( | ||
ui.item(ui.icon("vsEdit"), ui.text("Edit")), | ||
ui.item(ui.icon("vsCopy"), ui.text("Copy")), | ||
ui.item(ui.icon("vsTrash"), ui.text("Delete")), | ||
button_label_behavior="hide", | ||
) | ||
``` | ||
|
||
|
||
## Selection | ||
|
||
Action groups support multiple selection modes, which are configurable via the `selection_mode` prop. | ||
|
||
The `default_selected_keys` can be used for uncontrolled default selections. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_default_selected_keys_example = ui.action_group( | ||
ui.item("Grid view", key="grid"), | ||
ui.item("List view", key="list"), | ||
ui.item("Gallery view", key="gallery"), | ||
selection_mode="single", | ||
default_selected_keys=["list"], | ||
) | ||
``` | ||
|
||
The `selected_keys` prop can be used for controlled selections. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
@ui.component | ||
def ui_action_group_selected_keys_example(): | ||
selected, set_selected = ui.use_state([]) | ||
return [ | ||
ui.action_group( | ||
ui.item("Grid view", key="grid"), | ||
ui.item("List view", key="list"), | ||
ui.item("Gallery view", key="gallery"), | ||
selection_mode="multiple", | ||
selected_keys=selected, | ||
on_change=set_selected, | ||
), | ||
ui.text(f"Current selection (controlled): {selected}"), | ||
] | ||
|
||
|
||
my_action_group_selected_keys_example = ui_action_group_selected_keys_example() | ||
``` | ||
|
||
|
||
## Events | ||
|
||
The `on_selection_change` property is triggered whenever the value in the action group selection changes. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
@ui.component | ||
def ui_action_group_on_change_example(): | ||
selected_option, set_selected_option = ui.use_state("") | ||
return [ | ||
ui.action_group( | ||
ui.item("Grid view", key="grid"), | ||
ui.item("List view", key="list"), | ||
ui.item("Gallery view", key="gallery"), | ||
selection_mode="single", | ||
on_selection_change=set_selected_option, | ||
), | ||
ui.text(f"You have selected: {selected_option}"), | ||
] | ||
|
||
|
||
my_action_group_on_change_example = ui_action_group_on_change_example() | ||
``` | ||
|
||
|
||
## Collapsing Behavior | ||
|
||
By default, the items of an action group wrap to a new line when space is limited. To keep them in a single line, set the `overflow_mode` prop to "collapse", which collapses the items into a menu. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_overflow_example = ui.action_group( | ||
ui.item(ui.icon("vsEdit"), ui.text("Edit")), | ||
ui.item(ui.icon("vsCopy"), ui.text("Copy")), | ||
ui.item(ui.icon("vsTrash"), ui.text("Delete")), | ||
ui.item(ui.icon("vsMove"), ui.text("Move")), | ||
ui.item(ui.icon("vsDiffMultiple"), ui.text("Duplicate")), | ||
overflow_mode="collapse", | ||
max_width=250, | ||
) | ||
``` | ||
|
||
When selection is enabled, the action group collapses all items into a menu when space is limited, with a highlighted menu button indicating a selection. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
my_action_group_selection_collapsing_example = ui.action_group( | ||
ui.item(ui.icon("vsEdit"), ui.text("Edit")), | ||
ui.item(ui.icon("vsCopy"), ui.text("Copy")), | ||
ui.item(ui.icon("vsTrash"), ui.text("Delete")), | ||
static_color="white", | ||
summary_icon=ui.icon("vsSearch"), | ||
overflow_mode="collapse", | ||
selection_mode="multiple", | ||
is_emphasized=True, | ||
max_width=10, | ||
) | ||
``` | ||
|
||
|
||
## Quiet State | ||
|
||
The `is_quiet` prop makes action groups "quiet". This can be useful when the action group and its corresponding styling should not distract users from surrounding content. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_is_quiet_example = ui.action_group( | ||
ui.item("Add"), | ||
ui.item("Edit"), | ||
ui.item("Delete"), | ||
is_quiet=True, | ||
) | ||
``` | ||
|
||
|
||
## Emphasized | ||
|
||
The `is_emphasized` prop makes the selected action item the user's accent color, adding a visual prominence to the selection. | ||
|
||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_is_emphasized_example = ui.action_group( | ||
AkshatJawne marked this conversation as resolved.
Show resolved
Hide resolved
|
||
ui.item("Add"), | ||
ui.item("Edit"), | ||
ui.item("Delete"), | ||
selection_mode="single", | ||
is_emphasized=True, | ||
AkshatJawne marked this conversation as resolved.
Show resolved
Hide resolved
|
||
) | ||
``` | ||
|
||
|
||
## Static Color | ||
|
||
The `static_color` prop can be used when the action group is placed over a color background. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_static_color_example = ui.view( | ||
ui.action_group( | ||
ui.item(ui.icon("vsEdit"), ui.text("Edit")), | ||
ui.item(ui.icon("vsCopy"), ui.text("Copy")), | ||
ui.item(ui.icon("vsTrash"), ui.text("Delete")), | ||
static_color="white", | ||
), | ||
background_color="blue-700", | ||
padding="size-500", | ||
) | ||
``` | ||
|
||
|
||
## Disabled State | ||
|
||
Action groups can be disabled to prevent user interaction. This is useful when the group is not currently available, but the button should still be visible. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_is_disabled_example = ui.action_group( | ||
ui.item("Add"), | ||
ui.item("Edit"), | ||
ui.item("Delete"), | ||
is_disabled=True, | ||
) | ||
``` | ||
|
||
|
||
## Orientation | ||
|
||
While aligned horizontally by default, the axis with which the action items align can be changed via the `orientation` prop. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_orientation_example = ui.action_group( | ||
ui.item("Add"), | ||
ui.item("Edit"), | ||
ui.item("Delete"), | ||
orientation="vertical", | ||
) | ||
``` | ||
|
||
|
||
## Density | ||
|
||
The `density` prop can increase or reduce margins between action buttons. When the `is_quiet` prop is set to true, margin size is reduced. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
@ui.component | ||
def ui_action_group_density_examples(): | ||
AkshatJawne marked this conversation as resolved.
Show resolved
Hide resolved
|
||
return [ | ||
ui.action_group( | ||
ui.item(ui.icon("vsEdit")), | ||
ui.item(ui.icon("vsCopy")), | ||
ui.item(ui.icon("vsTrash")), | ||
density="compact", | ||
), | ||
ui.action_group( | ||
ui.item(ui.icon("vsEdit")), | ||
ui.item(ui.icon("vsCopy")), | ||
ui.item(ui.icon("vsTrash")), | ||
is_quiet=True, | ||
density="compact", | ||
), | ||
ui.action_group( | ||
ui.item(ui.icon("vsEdit")), | ||
ui.item(ui.icon("vsCopy")), | ||
ui.item(ui.icon("vsTrash")), | ||
density="spacious", | ||
), | ||
] | ||
|
||
|
||
my_action_group_density_examples = ui_action_group_density_examples() | ||
``` | ||
|
||
|
||
## Justified | ||
|
||
The `is_justified` prop evenly divides all available horizontal space among the action items. | ||
|
||
```python | ||
from deephaven import ui | ||
|
||
|
||
my_action_group_is_justified_example = ui.flex( | ||
ui.action_group( | ||
ui.item(ui.icon("vsEdit")), | ||
ui.item(ui.icon("vsCopy")), | ||
ui.item(ui.icon("vsTrash")), | ||
is_justified=True, | ||
density="compact", | ||
), | ||
width="size-3000", | ||
direction="column", | ||
) | ||
``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about:
Are there other options?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It can be set "show", "collapse", and "hide", but usually, users would only be setting it to "hide"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dsmmcken worth mentioning? I assume show is the default?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just hide is fine, I have no preference on how you guys word it.