From 76519499e02ee67d3e19b27ad36845013919fcb9 Mon Sep 17 00:00:00 2001 From: mikebender Date: Thu, 5 Oct 2023 13:13:36 -0400 Subject: [PATCH 01/12] Add the ui.table spec - Includes a whole bunch of methods and deprecations --- plugins/ui/DESIGN.md | 293 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 39effc0d5..0ed7cd756 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -892,6 +892,299 @@ def my_dashboard(): d = my_dashboard() ``` +#### ui.table + +`ui.table` is a wrapper for a Deephaven `Table` object where you can add customizations or callbacks to the table that the UI will handle. The basic syntax for creating a `UITable` is: + +```py +import deephaven.ui as ui +ui_table = ui.table(table: Table) -> UITable +``` + +It has an [immutable fluent](https://en.wikipedia.org/wiki/Fluent_interface#Immutability) interface, similar to Deephaven `Table`. That means each method below will return a new `UITable` object, rather than modifying the existing one. This allows you to chain multiple customizations together, e.g.: + +```py +from deephaven import ui + +# Create a table with some customizations +ui_table = ( + ui.table(source) + .format_columns(["X = Y > 5 ? RED : NO_FORMATTING"]) + .column_group("Group 1", ["Col1", "Col2"], "RED") +) +``` + +`ui.table` will support the below methods. + +##### always_fetch_columns + +Set the columns to always fetch from the server. These will not be affected by the users current viewport/horizontal scrolling. Useful if you have a column with key value data that you want to always include in the data sent for row click operations. + +###### Syntax + +```py +ui_table.always_fetch_columns(columns: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | ------------------------------------------------------------------------- | +| `columns` | `Union[str, list[str]]` | The columns to always fetch from the server. May be a single column name. | + +##### back_columns + +Set the columns to show at the back of the table. + +###### Syntax + +```py +ui_table.back_columns(columns: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | -------------------------------------------------------------------------- | +| `columns` | `Union[str, list[str]]` | The columns to show at the back of the table. May be a single column name. | + +##### column_group + +Create a group for columns in the table. + +###### Syntax + +```py +ui_table.column_group(name: str, children: list[str], color: Optional[str]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `name` | `str` | The group name. Must be a valid column name and not a duplicate of another column or group. | +| `children` | `list[str]` | The children in the group. May contain column names or other group names. Each item may only be specified as a child once. | +| `color` | `Optional[str]` | The hex color string or Deephaven color name. | + +##### context_menu + +Add custom items to the context menu. You can provide a list of actions that always appear, or a callback that can process the selected rows and send back menu items asynchronously. + +###### Syntax + +```py +ui_table.context_menu( + items: Union[ + list[ContextMenuAction], + Callable[[int, dict[str, Any]], list[ContextMenuAction]], + ] +) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `Union[list[ContextMenuAction], Callable[[int, dict[str, Any]], list[ContextMenuAction]]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the row index and row data and returns a list of `ContextMenuAction` objects. | + +##### format_columns + +Applies color formatting to the columns of the table. + +###### Syntax + +```py +ui_table.format_columns(column_formats: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | +| `column_formats` | `Union[str, list[str]]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"`. | + +##### format_column_where + +Applies color formatting to the specified column conditionally. + +###### Syntax + +```py +ui_table.format_column_where(self, col: str, cond: str, formula: str) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----- | ------------------------------------------------------------------------------------ | +| `col` | `str` | The column name | +| `cond` | `str` | The condition expression | +| `formula` | `str` | The formatting string in the form of assignment expression "column=color expression" | + +##### format_row_where + +Applies color formatting to rows of the table conditionally. + +###### Syntax + +```py +ui_table.format_row_where(self, cond: str, formula: str) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----- | ------------------------------------------------------------------------------------ | +| `cond` | `str` | The condition expression | +| `formula` | `str` | The formatting string in the form of assignment expression "column=color expression" | + +##### format_data_bar + +Applies data bar formatting to the specified column. + +###### Syntax + +```py +ui_table.format_data_bar(self, + col: str, + value_col: str = None, + min: Union[float, str] = NULL_DOUBLE, + max: Union[float, str] = NULL_DOUBLE, + axis: Union[DataBarAxisOption, str] = None, + positive_color: Union['Color', List['Color']] = None, + negative_color: Union['Color', List['Color']] = None, + value_placement: Union[DataBarValuePlacementOption, str] = None, + direction: Union[DataBarDirectionOption, str] = None, + opacity: float = NULL_DOUBLE, + marker_col: str = None, + marker_color: 'Color' = None +) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ----------------- | ----------------------------------------- | -------------------------------------------------------------- | +| `col` | `str` | column to generate data bars in | +| `value_col` | `str` | column containing the values to generate data bars from | +| `min` | `Union[float, str]` | minimum value for data bar scaling or column to get value from | +| `max` | `Union[float, str]` | maximum value for data bar scaling or column to get value from | +| `axis` | `Union[DataBarAxisOption, str]` | orientation of data bar relative to cell | +| `positive_color` | `Union['Color', List['Color']]` | color for positive bars. Use list of colors to form a gradient | +| `negative_color` | `Union['Color', List['Color']]` | color for negative bars. Use list of colors to form a gradient | +| `value_placement` | `Union[DataBarValuePlacementOption, str]` | orientation of values relative to data bar | +| `direction` | `Union[DataBarDirectionOption, str]` | orientation of data bar relative to horizontal axis | +| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | +| `marker_col` | `str` | column containing the values to generate markers from | +| `marker_color` | `'Color'` | color for markers | + +##### freeze_columns + +Set the columns to freeze to the front of the table. These will not be affected by horizontal scrolling. + +###### Syntax + +```py +ui_table.freeze_columns(columns: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | ----------------------------------------------------------------------------- | +| `columns` | `Union[str, list[str]]` | The columns to freeze to the front of the table. May be a single column name. | + +##### front_columns + +Set the columns to show at the front of the table. + +###### Syntax + +```py +ui_table.front_columns(columns: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | --------------------------------------------------------------------------- | +| `columns` | `Union[str, list[str]]` | The columns to show at the front of the table. May be a single column name. | + +##### hide_columns + +Set the columns to hide from the table. + +###### Syntax + +```py +ui_table.hide_columns(columns: Union[str, list[str]]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | ---------------------------------------------------------------- | +| `columns` | `Union[str, list[str]]` | The columns to hide from the table. May be a single column name. | + +##### on_row_click + +Add a callback for when a row is clicked. + +###### Syntax + +```py +ui_table.on_row_click(callback: Callable[[int, dict[str, Any]], None]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | + +##### on_row_double_click + +Add a callback for when a row is double clicked. + +###### Syntax + +```py +ui_table.on_row_double_click(callback: Callable[[int, dict[str, Any]], None]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is double clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | + +##### search_display_mode + +Set the search bar to explicitly be accessible or inaccessible, or use the system default. + +###### Syntax + +```py +ui_table.search_display_mode(mode: Literal["show", "hide", "default"]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | +| `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | + +#### Deprecations + +The functionality provided my `ui.table` replaces many of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. + +| Table Function | ui.table Replacement | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `format_columns` | [format_columns](#format_columns) | +| `format_column_where` | [format_column_where](#format_column_where) | +| `format_row_where` | [format_row_where](#format_row_where) | +| `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display_mode](#search_display_mode) | + #### Context By default, the context of a `@ui.component` will be created per client session (same as [Parameterized Query's "parallel universe" today](https://github.com/deephaven-ent/iris/blob/868b868fc9e180ee948137b10b6addbac043605e/ParameterizedQuery/src/main/java/io/deephaven/query/parameterized/impl/ParameterizedQueryServerImpl.java#L140)). However, it would be interesting if it were possible to share a context among all sessions for the current user, and/or share a context with other users even; e.g. if one user selects and applies a filter, it updates immediately for all other users with that dashboard open. So three cases: From 17f16a26f94897164e67e87f90be12f993fbd015 Mon Sep 17 00:00:00 2001 From: mikebender Date: Thu, 5 Oct 2023 14:56:26 -0400 Subject: [PATCH 02/12] Added sort, quick_filter, totals_table functions - Also specified that we will not be adding dropColumnFormats functionality (not sure it's necessary ... ) --- plugins/ui/DESIGN.md | 177 ++++++++++++++++++++++++++++++------------- 1 file changed, 123 insertions(+), 54 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 0ed7cd756..ee4124a4b 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -923,14 +923,14 @@ Set the columns to always fetch from the server. These will not be affected by t ###### Syntax ```py -ui_table.always_fetch_columns(columns: Union[str, list[str]]) -> UITable +ui_table.always_fetch_columns(columns: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----------------------- | ------------------------------------------------------------------------- | -| `columns` | `Union[str, list[str]]` | The columns to always fetch from the server. May be a single column name. | +| Parameter | Type | Description | +| --------- | ------------------ | ------------------------------------------------------------------------- | +| `columns` | `str \| list[str]` | The columns to always fetch from the server. May be a single column name. | ##### back_columns @@ -939,14 +939,14 @@ Set the columns to show at the back of the table. ###### Syntax ```py -ui_table.back_columns(columns: Union[str, list[str]]) -> UITable +ui_table.back_columns(columns: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----------------------- | -------------------------------------------------------------------------- | -| `columns` | `Union[str, list[str]]` | The columns to show at the back of the table. May be a single column name. | +| Parameter | Type | Description | +| --------- | ------------------ | -------------------------------------------------------------------------- | +| `columns` | `str \| list[str]` | The columns to show at the back of the table. May be a single column name. | ##### column_group @@ -974,18 +974,15 @@ Add custom items to the context menu. You can provide a list of actions that alw ```py ui_table.context_menu( - items: Union[ - list[ContextMenuAction], - Callable[[int, dict[str, Any]], list[ContextMenuAction]], - ] + items: list[ContextMenuAction] | Callable[[int, dict[str, Any]], list[ContextMenuAction]] ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `items` | `Union[list[ContextMenuAction], Callable[[int, dict[str, Any]], list[ContextMenuAction]]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the row index and row data and returns a list of `ContextMenuAction` objects. | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `list[ContextMenuAction] \| Callable[[int, dict[str, Any]], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the row index and row data and returns a list of `ContextMenuAction` objects. | ##### format_columns @@ -994,14 +991,14 @@ Applies color formatting to the columns of the table. ###### Syntax ```py -ui_table.format_columns(column_formats: Union[str, list[str]]) -> UITable +ui_table.format_columns(column_formats: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | -| `column_formats` | `Union[str, list[str]]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"`. | +| Parameter | Type | Description | +| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------- | +| `column_formats` | `str \| list[str]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"`. | ##### format_column_where @@ -1048,35 +1045,35 @@ Applies data bar formatting to the specified column. ui_table.format_data_bar(self, col: str, value_col: str = None, - min: Union[float, str] = NULL_DOUBLE, - max: Union[float, str] = NULL_DOUBLE, - axis: Union[DataBarAxisOption, str] = None, - positive_color: Union['Color', List['Color']] = None, - negative_color: Union['Color', List['Color']] = None, - value_placement: Union[DataBarValuePlacementOption, str] = None, - direction: Union[DataBarDirectionOption, str] = None, - opacity: float = NULL_DOUBLE, + min: float | str = None, + max: float | str = None, + axis: Literal["Proportional", "Middle", "Directional"] = None, + positive_color: Color | list[Color] = None, + negative_color: Color | list[Color] = None, + value_placement: Literal["Beside", "Overlap", "Hide"] = None, + direction: Literal["LTR", "RTL"] = None, + opacity: float = None, marker_col: str = None, - marker_color: 'Color' = None + marker_color: Color = None ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ----------------- | ----------------------------------------- | -------------------------------------------------------------- | -| `col` | `str` | column to generate data bars in | -| `value_col` | `str` | column containing the values to generate data bars from | -| `min` | `Union[float, str]` | minimum value for data bar scaling or column to get value from | -| `max` | `Union[float, str]` | maximum value for data bar scaling or column to get value from | -| `axis` | `Union[DataBarAxisOption, str]` | orientation of data bar relative to cell | -| `positive_color` | `Union['Color', List['Color']]` | color for positive bars. Use list of colors to form a gradient | -| `negative_color` | `Union['Color', List['Color']]` | color for negative bars. Use list of colors to form a gradient | -| `value_placement` | `Union[DataBarValuePlacementOption, str]` | orientation of values relative to data bar | -| `direction` | `Union[DataBarDirectionOption, str]` | orientation of data bar relative to horizontal axis | -| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | -| `marker_col` | `str` | column containing the values to generate markers from | -| `marker_color` | `'Color'` | color for markers | +| Parameter | Type | Description | +| ----------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- | +| `col` | `str` | column to generate data bars in | +| `value_col` | `str` | column containing the values to generate data bars from | +| `min` | `float \| str` | minimum value for data bar scaling or column to get value from | +| `max` | `float \| str` | maximum value for data bar scaling or column to get value from | +| `axis` | `Literal["Proportional", "Middle", "Directional"]` | orientation of data bar relative to cell | +| `positive_color` | `Color \| list[Color]` | color for positive bars. Use list of colors to form a gradient | +| `negative_color` | `Color \| list[Color]` | color for negative bars. Use list of colors to form a gradient | +| `value_placement` | `Literal["Beside", "Overlap", "Hide"]` | orientation of values relative to data bar | +| `direction` | `Literal["LTR", "RTL"]` | orientation of data bar relative to horizontal axis | +| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | +| `marker_col` | `str` | column containing the values to generate markers from | +| `marker_color` | `'Color'` | color for markers | ##### freeze_columns @@ -1085,14 +1082,14 @@ Set the columns to freeze to the front of the table. These will not be affected ###### Syntax ```py -ui_table.freeze_columns(columns: Union[str, list[str]]) -> UITable +ui_table.freeze_columns(columns: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----------------------- | ----------------------------------------------------------------------------- | -| `columns` | `Union[str, list[str]]` | The columns to freeze to the front of the table. May be a single column name. | +| Parameter | Type | Description | +| --------- | ------------------ | ----------------------------------------------------------------------------- | +| `columns` | `str \| list[str]` | The columns to freeze to the front of the table. May be a single column name. | ##### front_columns @@ -1101,14 +1098,14 @@ Set the columns to show at the front of the table. ###### Syntax ```py -ui_table.front_columns(columns: Union[str, list[str]]) -> UITable +ui_table.front_columns(columns: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----------------------- | --------------------------------------------------------------------------- | -| `columns` | `Union[str, list[str]]` | The columns to show at the front of the table. May be a single column name. | +| Parameter | Type | Description | +| --------- | ------------------ | --------------------------------------------------------------------------- | +| `columns` | `str \| list[str]` | The columns to show at the front of the table. May be a single column name. | ##### hide_columns @@ -1117,14 +1114,14 @@ Set the columns to hide from the table. ###### Syntax ```py -ui_table.hide_columns(columns: Union[str, list[str]]) -> UITable +ui_table.hide_columns(columns: str | list[str]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----------------------- | ---------------------------------------------------------------- | -| `columns` | `Union[str, list[str]]` | The columns to hide from the table. May be a single column name. | +| Parameter | Type | Description | +| --------- | ------------------ | ---------------------------------------------------------------- | +| `columns` | `str \| list[str]` | The columns to hide from the table. May be a single column name. | ##### on_row_click @@ -1158,6 +1155,25 @@ ui_table.on_row_double_click(callback: Callable[[int, dict[str, Any]], None]) -> | ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is double clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | +##### quick_filter + +Add a quick filter for the UI to apply to the table. + +###### Syntax + +```py +ColumnName = str +QuickFilterExpression = str + +ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------- | --------------------------------------- | +| `filter` | `dict[ColumnName, QuickFilterExpression]` | The quick filter to apply to the table. | + ##### search_display_mode Set the search bar to explicitly be accessible or inaccessible, or use the system default. @@ -1174,6 +1190,35 @@ ui_table.search_display_mode(mode: Literal["show", "hide", "default"]) -> UITabl | --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | +##### totals_table + +Set the totals table to display below the main table. + +###### Syntax + +```py +ColumnName = str +AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique"] + +ui_table.totals_table( + operations: dict[ColumnName, list[AggregationOperation]], + operation_order: list[AggregationOperation] = [], + default_operation: "Sum", + group_by: list[ColumnName] = [], + show_on_top: bool = False, +) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | +| `operations` | `dict[ColumnName, list[AggregationOperation]]` | The operations to apply to the columns of the table. | +| `operation_order` | `list[AggregationOperation]` | The order in which to display the operations. | +| `default_operation` | `AggregationOperation` | The default operation to apply to columns that do not have an operation specified. | +| `group_by` | `list[ColumnName]` | The columns to group by. | +| `show_on_top` | `bool` | Whether to show the totals table above the main table. | + #### Deprecations The functionality provided my `ui.table` replaces many of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. @@ -1184,6 +1229,30 @@ The functionality provided my `ui.table` replaces many of the existing functions | `format_column_where` | [format_column_where](#format_column_where) | | `format_row_where` | [format_row_where](#format_row_where) | | `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display_mode](#search_display_mode) | +| `dropColumnFormats` | No replacement | +| `setTotalsTable` | [totals_table](#totals_table) | + +##### sort + +Provide the default sort that will be used by the UI. + +###### Syntax + +```py +SortDirection = Literal["ASC", "DESC"] + +ui_table.sort( + order_by: str | Sequence[str], + order: Optional[SortDirection | Sequence[SortDirection]] +) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `order_by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | +| `order` | `Optional[SortDirection \| Sequence[SortDirection]]` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | #### Context From 342dadcc849d87fe4336199b1e96ed0f7f84c9af Mon Sep 17 00:00:00 2001 From: mikebender Date: Tue, 10 Oct 2023 13:35:48 -0400 Subject: [PATCH 03/12] Address some review comments --- plugins/ui/DESIGN.md | 77 ++++++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index ee4124a4b..8a9cef012 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -894,7 +894,7 @@ d = my_dashboard() #### ui.table -`ui.table` is a wrapper for a Deephaven `Table` object where you can add customizations or callbacks to the table that the UI will handle. The basic syntax for creating a `UITable` is: +`ui.table` is a wrapper for a Deephaven `Table` object that allows you to add UI customizations or callbacks. The basic syntax for creating a `UITable` is: ```py import deephaven.ui as ui @@ -934,7 +934,7 @@ ui_table.always_fetch_columns(columns: str | list[str]) -> UITable ##### back_columns -Set the columns to show at the back of the table. +Set the columns to show at the back of the table. These will not be moveable in the UI. ###### Syntax @@ -973,16 +973,23 @@ Add custom items to the context menu. You can provide a list of actions that alw ###### Syntax ```py +# Index will be -1 for the header row/column +RowIndex = int +ColumnIndex = int +CellIndex = [RowIndex, ColumnIndex] +RowData = dict[str, Any] +ContextMenuAction = dict[str, Any] + ui_table.context_menu( - items: list[ContextMenuAction] | Callable[[int, dict[str, Any]], list[ContextMenuAction]] + items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]] ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `items` | `list[ContextMenuAction] \| Callable[[int, dict[str, Any]], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the row index and row data and returns a list of `ContextMenuAction` objects. | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | ##### format_columns @@ -996,9 +1003,9 @@ ui_table.format_columns(column_formats: str | list[str]) -> UITable ###### Parameters -| Parameter | Type | Description | -| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------- | -| `column_formats` | `str \| list[str]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"`. | +| Parameter | Type | Description | +| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `column_formats` | `str \| list[str]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"` which makes the cells in column X red if the value for Y in that row is greater than 5. | ##### format_column_where @@ -1007,7 +1014,7 @@ Applies color formatting to the specified column conditionally. ###### Syntax ```py -ui_table.format_column_where(self, col: str, cond: str, formula: str) -> UITable +ui_table.format_column_where(self, col: str, cond: str, formula: str) -> UITable ``` ###### Parameters @@ -1077,7 +1084,7 @@ ui_table.format_data_bar(self, ##### freeze_columns -Set the columns to freeze to the front of the table. These will not be affected by horizontal scrolling. +Set the columns to freeze to the front of the table. These will always be visible and not affected by horizontal scrolling. ###### Syntax @@ -1093,7 +1100,7 @@ ui_table.freeze_columns(columns: str | list[str]) -> UITable ##### front_columns -Set the columns to show at the front of the table. +Set the columns to show at the front of the table. These will not be moveable in the UI. ###### Syntax @@ -1174,14 +1181,14 @@ ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITabl | --------- | ----------------------------------------- | --------------------------------------- | | `filter` | `dict[ColumnName, QuickFilterExpression]` | The quick filter to apply to the table. | -##### search_display_mode +##### search_display Set the search bar to explicitly be accessible or inaccessible, or use the system default. ###### Syntax ```py -ui_table.search_display_mode(mode: Literal["show", "hide", "default"]) -> UITable +ui_table.search_display(mode: Literal["show", "hide", "default"]) -> UITable ``` ###### Parameters @@ -1190,7 +1197,7 @@ ui_table.search_display_mode(mode: Literal["show", "hide", "default"]) -> UITabl | --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | -##### totals_table +##### show_totals Set the totals table to display below the main table. @@ -1198,12 +1205,12 @@ Set the totals table to display below the main table. ```py ColumnName = str -AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique"] +AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] -ui_table.totals_table( +ui_table.show_totals( operations: dict[ColumnName, list[AggregationOperation]], operation_order: list[AggregationOperation] = [], - default_operation: "Sum", + default_operation: AggregationOperation = "Skip", group_by: list[ColumnName] = [], show_on_top: bool = False, ) -> UITable @@ -1219,19 +1226,6 @@ ui_table.totals_table( | `group_by` | `list[ColumnName]` | The columns to group by. | | `show_on_top` | `bool` | Whether to show the totals table above the main table. | -#### Deprecations - -The functionality provided my `ui.table` replaces many of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. - -| Table Function | ui.table Replacement | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `format_columns` | [format_columns](#format_columns) | -| `format_column_where` | [format_column_where](#format_column_where) | -| `format_row_where` | [format_row_where](#format_row_where) | -| `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display_mode](#search_display_mode) | -| `dropColumnFormats` | No replacement | -| `setTotalsTable` | [totals_table](#totals_table) | - ##### sort Provide the default sort that will be used by the UI. @@ -1249,10 +1243,23 @@ ui_table.sort( ###### Parameters -| Parameter | Type | Description | -| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `order_by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | -| `order` | `Optional[SortDirection \| Sequence[SortDirection]]` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | +| Parameter | Type | Description | +| ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | +| `direction` | `Optional[SortDirection \| Sequence[SortDirection]]` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | + +#### Deprecations + +The functionality provided my `ui.table` replaces many of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. + +| Table Function | ui.table Replacement | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `format_columns` | [format_columns](#format_columns) | +| `format_column_where` | [format_column_where](#format_column_where) | +| `format_row_where` | [format_row_where](#format_row_where) | +| `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display](#search_display) | +| `dropColumnFormats` | No replacement | +| `setTotalsTable` | [show_totals](#show_totals) | #### Context From 296b290b472d04d7b236a2cb9021cf5ee7a00024 Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 11 Oct 2023 11:45:31 -0400 Subject: [PATCH 04/12] Update based on review - `search_display_mode` => `can_search`, a more concise name - `show_totals` => `aggregations`, since it's about setting aggregations and that's how we show it in the side bar --- plugins/ui/DESIGN.md | 106 +++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 8a9cef012..ce6ce4259 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -916,6 +916,35 @@ ui_table = ( `ui.table` will support the below methods. +##### aggregations + +Set the totals table to display below the main table. + +###### Syntax + +```py +ColumnName = str +AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] + +ui_table.aggregations( + operations: dict[ColumnName, list[AggregationOperation]], + operation_order: list[AggregationOperation] = [], + default_operation: AggregationOperation = "Skip", + group_by: list[ColumnName] = [], + show_on_top: bool = False, +) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | +| `operations` | `dict[ColumnName, list[AggregationOperation]]` | The operations to apply to the columns of the table. | +| `operation_order` | `list[AggregationOperation]` | The order in which to display the operations. | +| `default_operation` | `AggregationOperation` | The default operation to apply to columns that do not have an operation specified. | +| `group_by` | `list[ColumnName]` | The columns to group by. | +| `show_on_top` | `bool` | Whether to show the totals table above the main table. | + ##### always_fetch_columns Set the columns to always fetch from the server. These will not be affected by the users current viewport/horizontal scrolling. Useful if you have a column with key value data that you want to always include in the data sent for row click operations. @@ -948,6 +977,22 @@ ui_table.back_columns(columns: str | list[str]) -> UITable | --------- | ------------------ | -------------------------------------------------------------------------- | | `columns` | `str \| list[str]` | The columns to show at the back of the table. May be a single column name. | +##### can_search + +Set the search bar to explicitly be accessible or inaccessible, or use the system default. + +###### Syntax + +```py +ui_table.can_search(mode: Literal["show", "hide", "default"]) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | +| `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | + ##### column_group Create a group for columns in the table. @@ -1116,7 +1161,7 @@ ui_table.front_columns(columns: str | list[str]) -> UITable ##### hide_columns -Set the columns to hide from the table. +Set the columns to hide by default in the table. The user can still resize the columns to view them. ###### Syntax @@ -1130,14 +1175,14 @@ ui_table.hide_columns(columns: str | list[str]) -> UITable | --------- | ------------------ | ---------------------------------------------------------------- | | `columns` | `str \| list[str]` | The columns to hide from the table. May be a single column name. | -##### on_row_click +##### on_row_press -Add a callback for when a row is clicked. +Add a callback for when a press on a row is released (e.g. a row is clicked). ###### Syntax ```py -ui_table.on_row_click(callback: Callable[[int, dict[str, Any]], None]) -> UITable +ui_table.on_row_press(callback: Callable[[int, dict[str, Any]], None]) -> UITable ``` ###### Parameters @@ -1146,14 +1191,14 @@ ui_table.on_row_click(callback: Callable[[int, dict[str, Any]], None]) -> UITabl | ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | -##### on_row_double_click +##### on_row_double_press Add a callback for when a row is double clicked. ###### Syntax ```py -ui_table.on_row_double_click(callback: Callable[[int, dict[str, Any]], None]) -> UITable +ui_table.on_row_double_press(callback: Callable[[int, dict[str, Any]], None]) -> UITable ``` ###### Parameters @@ -1181,51 +1226,6 @@ ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITabl | --------- | ----------------------------------------- | --------------------------------------- | | `filter` | `dict[ColumnName, QuickFilterExpression]` | The quick filter to apply to the table. | -##### search_display - -Set the search bar to explicitly be accessible or inaccessible, or use the system default. - -###### Syntax - -```py -ui_table.search_display(mode: Literal["show", "hide", "default"]) -> UITable -``` - -###### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | -| `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | - -##### show_totals - -Set the totals table to display below the main table. - -###### Syntax - -```py -ColumnName = str -AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] - -ui_table.show_totals( - operations: dict[ColumnName, list[AggregationOperation]], - operation_order: list[AggregationOperation] = [], - default_operation: AggregationOperation = "Skip", - group_by: list[ColumnName] = [], - show_on_top: bool = False, -) -> UITable -``` - -###### Parameters - -| Parameter | Type | Description | -| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | -| `operations` | `dict[ColumnName, list[AggregationOperation]]` | The operations to apply to the columns of the table. | -| `operation_order` | `list[AggregationOperation]` | The order in which to display the operations. | -| `default_operation` | `AggregationOperation` | The default operation to apply to columns that do not have an operation specified. | -| `group_by` | `list[ColumnName]` | The columns to group by. | -| `show_on_top` | `bool` | Whether to show the totals table above the main table. | - ##### sort Provide the default sort that will be used by the UI. @@ -1250,7 +1250,7 @@ ui_table.sort( #### Deprecations -The functionality provided my `ui.table` replaces many of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. +The functionality provided my `ui.table` replaces some of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. | Table Function | ui.table Replacement | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -1259,7 +1259,7 @@ The functionality provided my `ui.table` replaces many of the existing functions | `format_row_where` | [format_row_where](#format_row_where) | | `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display](#search_display) | | `dropColumnFormats` | No replacement | -| `setTotalsTable` | [show_totals](#show_totals) | +| `setTotalsTable` | [aggregations](#aggregations) | #### Context From e9c47a74e210149c593bb6fd2ceb73a54652954d Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 11 Oct 2023 13:35:51 -0400 Subject: [PATCH 05/12] Reorganize format_columns - Replace format_columns with color_column, color_row, and format instead - Rather than having one method that accepts everything, break it out into what is expected instead --- plugins/ui/DESIGN.md | 124 ++++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 54 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index ce6ce4259..c807213b4 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1011,90 +1011,89 @@ ui_table.column_group(name: str, children: list[str], color: Optional[str]) -> U | `children` | `list[str]` | The children in the group. May contain column names or other group names. Each item may only be specified as a child once. | | `color` | `Optional[str]` | The hex color string or Deephaven color name. | -##### context_menu +##### color_column -Add custom items to the context menu. You can provide a list of actions that always appear, or a callback that can process the selected rows and send back menu items asynchronously. +Applies color formatting to a column of the table. ###### Syntax ```py -# Index will be -1 for the header row/column -RowIndex = int -ColumnIndex = int -CellIndex = [RowIndex, ColumnIndex] -RowData = dict[str, Any] -ContextMenuAction = dict[str, Any] - -ui_table.context_menu( - items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]] +ui_table.color_column( + column: ColumnName, + where: QuickFilterExpression | None = None, + color: Color | None = None, + background_color: Color | None = None, ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | - -##### format_columns - -Applies color formatting to the columns of the table. - -###### Syntax - -```py -ui_table.format_columns(column_formats: str | list[str]) -> UITable -``` - -###### Parameters +| Parameter | Type | Description | +| ------------------ | ------------------------------- | ----------------------------------------------------------------------------- | +| `column` | `ColumnName` | The column name | +| `where` | `QuickFilterExpression \| None` | The filter to apply to the expression. Uses quick filter format (e.g. `>10`). | +| `color` | `Color \| None` | The text color. Accepts hex color strings or Deephaven color names. | +| `background_color` | `Color \| None` | The background color. Accepts hex color strings or Deephaven color names. | -| Parameter | Type | Description | -| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `column_formats` | `str \| list[str]` | Formulas to compute formats for columns or rows in the table; e.g., `"X = Y > 5 ? RED : NO_FORMATTING"` which makes the cells in column X red if the value for Y in that row is greater than 5. | + -##### format_column_where +##### color_row -Applies color formatting to the specified column conditionally. +Applies color formatting to rows of the table conditionally based on the value of a column. ###### Syntax ```py -ui_table.format_column_where(self, col: str, cond: str, formula: str) -> UITable +ui_table.color_row( + column: ColumnName, + where: QuickFilterExpression, + color: Color | None = None, + background_color: Color | None = None +) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----- | ------------------------------------------------------------------------------------ | -| `col` | `str` | The column name | -| `cond` | `str` | The condition expression | -| `formula` | `str` | The formatting string in the form of assignment expression "column=color expression" | +| Parameter | Type | Description | +| ------------------ | ----------------------- | ----------------------------------------------------------------------------- | +| `column` | `str` | The column name | +| `where` | `QuickFilterExpression` | The filter to apply to the expression. Uses quick filter format (e.g. `>10`). | +| `color` | `Color \| None` | The text color. Accepts hex color strings or Deephaven color names. | +| `background_color` | `Color \| None` | The background color. Accepts hex color strings or Deephaven color names. | -##### format_row_where +##### context_menu -Applies color formatting to rows of the table conditionally. +Add custom items to the context menu. You can provide a list of actions that always appear, or a callback that can process the selected rows and send back menu items asynchronously. ###### Syntax ```py -ui_table.format_row_where(self, cond: str, formula: str) -> UITable +# Index will be -1 for the header row/column +RowIndex = int +ColumnIndex = int +CellIndex = [RowIndex, ColumnIndex] +RowData = dict[str, Any] +ContextMenuAction = dict[str, Any] + +ui_table.context_menu( + items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]] +) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ----- | ------------------------------------------------------------------------------------ | -| `cond` | `str` | The condition expression | -| `formula` | `str` | The formatting string in the form of assignment expression "column=color expression" | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | -##### format_data_bar +##### data_bar Applies data bar formatting to the specified column. ###### Syntax ```py -ui_table.format_data_bar(self, +ui_table.data_bar(self, col: str, value_col: str = None, min: float | str = None, @@ -1127,6 +1126,25 @@ ui_table.format_data_bar(self, | `marker_col` | `str` | column containing the values to generate markers from | | `marker_color` | `'Color'` | color for markers | +##### format + +Specify the formatting to display a column in. + +###### Syntax + +```py +ui_table.format(column: ColumnName,format: str) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | ----- | ------------------------------------------------------------------------ | +| `column` | `str` | The column name | +| `format` | `str` | The format to display the column in. Valid format depends on column type | + + + ##### freeze_columns Set the columns to freeze to the front of the table. These will always be visible and not affected by horizontal scrolling. @@ -1252,14 +1270,12 @@ ui_table.sort( The functionality provided my `ui.table` replaces some of the existing functions on `Table`. Below are the functions that are planned for deprecation/deletion of the `Table` interface, and their replacements with the new `ui.table` interface. -| Table Function | ui.table Replacement | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `format_columns` | [format_columns](#format_columns) | -| `format_column_where` | [format_column_where](#format_column_where) | -| `format_row_where` | [format_row_where](#format_row_where) | -| `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display](#search_display) | -| `dropColumnFormats` | No replacement | -| `setTotalsTable` | [aggregations](#aggregations) | +| Table Function | ui.table Replacement | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `format_columns`
`format_column_where`
`format_row_where` | [color_column](#color_column)
[color_row](#color_row)
[format](#format) | +| `layout_hints` | [back_columns](#back_columns)
[front_columns](#front_columns)
[column_group](#column_groups)
[freeze_columns](#freeze_columns)
[hide_columns](#hide_columns)
[search_display](#search_display) | +| `dropColumnFormats` | No replacement | +| `setTotalsTable` | [aggregations](#aggregations) | #### Context From 6783e3fcd34870637ac95676472d99f65a0b5abc Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 11 Oct 2023 16:21:08 -0400 Subject: [PATCH 06/12] Fix up some spacing --- plugins/ui/DESIGN.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index c807213b4..6846290cd 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1111,20 +1111,20 @@ ui_table.data_bar(self, ###### Parameters -| Parameter | Type | Description | -| ----------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- | -| `col` | `str` | column to generate data bars in | -| `value_col` | `str` | column containing the values to generate data bars from | -| `min` | `float \| str` | minimum value for data bar scaling or column to get value from | -| `max` | `float \| str` | maximum value for data bar scaling or column to get value from | -| `axis` | `Literal["Proportional", "Middle", "Directional"]` | orientation of data bar relative to cell | -| `positive_color` | `Color \| list[Color]` | color for positive bars. Use list of colors to form a gradient | -| `negative_color` | `Color \| list[Color]` | color for negative bars. Use list of colors to form a gradient | -| `value_placement` | `Literal["Beside", "Overlap", "Hide"]` | orientation of values relative to data bar | -| `direction` | `Literal["LTR", "RTL"]` | orientation of data bar relative to horizontal axis | -| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | -| `marker_col` | `str` | column containing the values to generate markers from | -| `marker_color` | `'Color'` | color for markers | +| Parameter | Type | Description | +| ----------------- | -------------------------------------------------- | -------------------------------------------------------------- | +| `col` | `str` | column to generate data bars in | +| `value_col` | `str` | column containing the values to generate data bars from | +| `min` | `float \| str` | minimum value for data bar scaling or column to get value from | +| `max` | `float \| str` | maximum value for data bar scaling or column to get value from | +| `axis` | `Literal["Proportional", "Middle", "Directional"]` | orientation of data bar relative to cell | +| `positive_color` | `Color \| list[Color]` | color for positive bars. Use list of colors to form a gradient | +| `negative_color` | `Color \| list[Color]` | color for negative bars. Use list of colors to form a gradient | +| `value_placement` | `Literal["Beside", "Overlap", "Hide"]` | orientation of values relative to data bar | +| `direction` | `Literal["LTR", "RTL"]` | orientation of data bar relative to horizontal axis | +| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | +| `marker_col` | `str` | column containing the values to generate markers from | +| `marker_color` | `'Color'` | color for markers | ##### format @@ -1263,7 +1263,7 @@ ui_table.sort( | Parameter | Type | Description | | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | +| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | | `direction` | `Optional[SortDirection \| Sequence[SortDirection]]` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | #### Deprecations From 47e03969f23a5866766e01266c3fcd509714c807 Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 11 Oct 2023 16:46:18 -0400 Subject: [PATCH 07/12] Add more questions about the color_ methods, view args on ui.table --- plugins/ui/DESIGN.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 6846290cd..8fa493ff6 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -898,7 +898,7 @@ d = my_dashboard() ```py import deephaven.ui as ui -ui_table = ui.table(table: Table) -> UITable +ui_table = ui.table(table: Table, **view_args: dict) -> UITable ``` It has an [immutable fluent](https://en.wikipedia.org/wiki/Fluent_interface#Immutability) interface, similar to Deephaven `Table`. That means each method below will return a new `UITable` object, rather than modifying the existing one. This allows you to chain multiple customizations together, e.g.: @@ -909,11 +909,17 @@ from deephaven import ui # Create a table with some customizations ui_table = ( ui.table(source) - .format_columns(["X = Y > 5 ? RED : NO_FORMATTING"]) + .color_column("X", ["X = Y > 5 ? RED : NO_FORMATTING"]) .column_group("Group 1", ["Col1", "Col2"], "RED") ) ``` +You can also set margins and padding by passing in the appropriate arguments to the `ui.table` function: + +```py +ui_table = ui.table(source, padding="size-250") +``` + `ui.table` will support the below methods. ##### aggregations @@ -1036,6 +1042,10 @@ ui_table.color_column( | `background_color` | `Color \| None` | The background color. Accepts hex color strings or Deephaven color names. | + ##### color_row @@ -1052,6 +1062,11 @@ ui_table.color_row( ) -> UITable ``` + + ###### Parameters | Parameter | Type | Description | From b3bd1bdcebd5e586601b4c14c4fa354d489c06d4 Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 11 Oct 2023 17:26:49 -0400 Subject: [PATCH 08/12] Clean up typings for row press a bit --- plugins/ui/DESIGN.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 8fa493ff6..ae5ef953e 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1215,14 +1215,14 @@ Add a callback for when a press on a row is released (e.g. a row is clicked). ###### Syntax ```py -ui_table.on_row_press(callback: Callable[[int, dict[str, Any]], None]) -> UITable +ui_table.on_row_press(callback: Callable[[RowIndex, RowData], None]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | +| Parameter | Type | Description | +| ---------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `callback` | `Callable[[RowIndex, RowData], None]` | The callback function to run when a row is clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | ##### on_row_double_press @@ -1231,14 +1231,14 @@ Add a callback for when a row is double clicked. ###### Syntax ```py -ui_table.on_row_double_press(callback: Callable[[int, dict[str, Any]], None]) -> UITable +ui_table.on_row_double_press(callback: Callable[[RowIndex, RowData], None]) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `callback` | `Callable[[int, dict[str, Any]], None]` | The callback function to run when a row is double clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | +| Parameter | Type | Description | +| ---------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `callback` | `Callable[[RowIndex, RowData], None]` | The callback function to run when a row is double clicked. The first parameter is the row index, and the second is the row data provided in a dictionary where the column names are the keys. | ##### quick_filter From 67393a97e38d126f03ad25201c11236f361baeca Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 18 Oct 2023 10:53:21 -0400 Subject: [PATCH 09/12] Add `selection_mode`, clean up custom types - Have custom types defined in a common area - Add `selection_mode` API --- plugins/ui/DESIGN.md | 119 ++++++++++++++++++++++++++----------------- 1 file changed, 73 insertions(+), 46 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index ae5ef953e..5932ece9d 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -929,9 +929,6 @@ Set the totals table to display below the main table. ###### Syntax ```py -ColumnName = str -AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] - ui_table.aggregations( operations: dict[ColumnName, list[AggregationOperation]], operation_order: list[AggregationOperation] = [], @@ -990,14 +987,14 @@ Set the search bar to explicitly be accessible or inaccessible, or use the syste ###### Syntax ```py -ui_table.can_search(mode: Literal["show", "hide", "default"]) -> UITable +ui_table.can_search(mode: SearchMode) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | -| `mode` | `Literal["show", "hide", "default"]` | set the search bar to explicitly be accessible or inaccessible, or use the system default. | +| Parameter | Type | Description | +| --------- | ------------ | ------------------------------------------------------------------------------------------ | +| `mode` | `SearchMode` | Set the search bar to explicitly be accessible or inaccessible, or use the system default. | ##### column_group @@ -1006,16 +1003,16 @@ Create a group for columns in the table. ###### Syntax ```py -ui_table.column_group(name: str, children: list[str], color: Optional[str]) -> UITable +ui_table.column_group(name: str, children: list[str], color: str | None) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `name` | `str` | The group name. Must be a valid column name and not a duplicate of another column or group. | -| `children` | `list[str]` | The children in the group. May contain column names or other group names. Each item may only be specified as a child once. | -| `color` | `Optional[str]` | The hex color string or Deephaven color name. | +| Parameter | Type | Description | +| ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `name` | `str` | The group name. Must be a valid column name and not a duplicate of another column or group. | +| `children` | `list[str]` | The children in the group. May contain column names or other group names. Each item may only be specified as a child once. | +| `color` | `str \| None` | The hex color string or Deephaven color name. | ##### color_column @@ -1084,12 +1081,6 @@ Add custom items to the context menu. You can provide a list of actions that alw ```py # Index will be -1 for the header row/column -RowIndex = int -ColumnIndex = int -CellIndex = [RowIndex, ColumnIndex] -RowData = dict[str, Any] -ContextMenuAction = dict[str, Any] - ui_table.context_menu( items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]] ) -> UITable @@ -1113,11 +1104,11 @@ ui_table.data_bar(self, value_col: str = None, min: float | str = None, max: float | str = None, - axis: Literal["Proportional", "Middle", "Directional"] = None, + axis: DataBarAxis | None = None, positive_color: Color | list[Color] = None, negative_color: Color | list[Color] = None, - value_placement: Literal["Beside", "Overlap", "Hide"] = None, - direction: Literal["LTR", "RTL"] = None, + value_placement: DataBarValuePlacement | None = None, + direction: DataBarDirection | None = None, opacity: float = None, marker_col: str = None, marker_color: Color = None @@ -1126,20 +1117,20 @@ ui_table.data_bar(self, ###### Parameters -| Parameter | Type | Description | -| ----------------- | -------------------------------------------------- | -------------------------------------------------------------- | -| `col` | `str` | column to generate data bars in | -| `value_col` | `str` | column containing the values to generate data bars from | -| `min` | `float \| str` | minimum value for data bar scaling or column to get value from | -| `max` | `float \| str` | maximum value for data bar scaling or column to get value from | -| `axis` | `Literal["Proportional", "Middle", "Directional"]` | orientation of data bar relative to cell | -| `positive_color` | `Color \| list[Color]` | color for positive bars. Use list of colors to form a gradient | -| `negative_color` | `Color \| list[Color]` | color for negative bars. Use list of colors to form a gradient | -| `value_placement` | `Literal["Beside", "Overlap", "Hide"]` | orientation of values relative to data bar | -| `direction` | `Literal["LTR", "RTL"]` | orientation of data bar relative to horizontal axis | -| `opacity` | `float` | opacity of data bars. Accepts values from 0 to 1 | -| `marker_col` | `str` | column containing the values to generate markers from | -| `marker_color` | `'Color'` | color for markers | +| Parameter | Type | Description | +| ----------------- | ------------------------------- | -------------------------------------------------------------- | +| `col` | `str` | Column to generate data bars in | +| `value_col` | `str` | Column containing the values to generate data bars from | +| `min` | `float \| str` | Minimum value for data bar scaling or column to get value from | +| `max` | `float \| str` | Maximum value for data bar scaling or column to get value from | +| `axis` | `DataBarAxis \| None` | Orientation of data bar relative to cell | +| `positive_color` | `Color \| list[Color]` | Color for positive bars. Use list of colors to form a gradient | +| `negative_color` | `Color \| list[Color]` | Color for negative bars. Use list of colors to form a gradient | +| `value_placement` | `DataBarValuePlacement \| None` | Orientation of values relative to data bar | +| `direction` | `DataBarDirection \| None` | Orientation of data bar relative to horizontal axis | +| `opacity` | `float` | Opacity of data bars. Accepts values from 0 to 1 | +| `marker_col` | `str` | Column containing the values to generate markers from | +| `marker_color` | `'Color'` | Color for markers | ##### format @@ -1247,9 +1238,6 @@ Add a quick filter for the UI to apply to the table. ###### Syntax ```py -ColumnName = str -QuickFilterExpression = str - ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITable ``` @@ -1259,6 +1247,22 @@ ui_table.quick_filter(filter: dict[ColumnName, QuickFilterExpression]) -> UITabl | --------- | ----------------------------------------- | --------------------------------------- | | `filter` | `dict[ColumnName, QuickFilterExpression]` | The quick filter to apply to the table. | +##### selection_mode + +Set the selection mode for the table. + +###### Syntax + +```py +ui_table.selection_mode(mode: SelectionMode) -> UITable +``` + +###### Parameters + +| Parameter | Type | Description | +| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mode` | `SelectionMode` | The selection mode to use. Must be one of `"ROW"`, `"COLUMN"`, or `"CELL"`:
  • `"ROW"` selects the entire row of the cell you click on.
  • `"COLUMN"` selects the entire column of the cell you click on.
  • `"CELL"` selects only the cells you click on.
    • | + ##### sort Provide the default sort that will be used by the UI. @@ -1266,20 +1270,18 @@ Provide the default sort that will be used by the UI. ###### Syntax ```py -SortDirection = Literal["ASC", "DESC"] - ui_table.sort( order_by: str | Sequence[str], - order: Optional[SortDirection | Sequence[SortDirection]] + order: SortDirection | Sequence[SortDirection] | None = None ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | -| `direction` | `Optional[SortDirection \| Sequence[SortDirection]]` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | +| Parameter | Type | Description | +| ----------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `by` | `str \| Sequence[str]` | The column(s) to sort by. May be a single column name, or a list of column names. | +| `direction` | `SortDirection \| Sequence[SortDirection] \| None` | The sort direction(s) to use. If provided, that must match up with the columns provided. Defaults to "ASC". | #### Deprecations @@ -1292,6 +1294,31 @@ The functionality provided my `ui.table` replaces some of the existing functions | `dropColumnFormats` | No replacement | | `setTotalsTable` | [aggregations](#aggregations) | +#### Custom Types + +Below are some of the custom types that are used in the above API definitions: + +```py +AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] +CellIndex = [RowIndex, ColumnIndex] +Color = DeephavenColor | HexColor +ColumnIndex = int +ColumnName = str +ContextMenuAction = dict[str, Any] +DataBarAxis = Literal["Proportional", "Middle", "Directional"] +DataBarDirection = Literal["LTR", "RTL"] +DataBarValuePlacement = Literal["Beside", "Overlap", "Hide"] +# TODO: Fill in the list of Deephaven Colors we allow +DeephavenColor = Literal[...] +HexColor = str +QuickFilterExpression = str +RowData = dict[str, Any] +RowIndex = int +SearchMode = Literal["show", "hide", "default"] +SelectionMode = Literal["CELL", "ROW", "COLUMN"] +SortDirection = Literal["ASC", "DESC"] +``` + #### Context By default, the context of a `@ui.component` will be created per client session (same as [Parameterized Query's "parallel universe" today](https://github.com/deephaven-ent/iris/blob/868b868fc9e180ee948137b10b6addbac043605e/ParameterizedQuery/src/main/java/io/deephaven/query/parameterized/impl/ParameterizedQueryServerImpl.java#L140)). However, it would be interesting if it were possible to share a context among all sessions for the current user, and/or share a context with other users even; e.g. if one user selects and applies a filter, it updates immediately for all other users with that dashboard open. So three cases: From b7541b67a266f3e62b9faea8fa78dd4aa5d48d76 Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 25 Oct 2023 16:47:17 -0400 Subject: [PATCH 10/12] Add a `mode` to the `context_menu` API --- plugins/ui/DESIGN.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 5932ece9d..a885f95ac 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1075,14 +1075,14 @@ ui_table.color_row( ##### context_menu -Add custom items to the context menu. You can provide a list of actions that always appear, or a callback that can process the selected rows and send back menu items asynchronously. +Add custom items to the context menu. You can provide a list of actions that always appear, or a callback that can process the selection and send back menu items asynchronously. You can also specify whether you want the menu items provided for a cell context menu, a header context menu, or some combination of those. You can also chain multiple sets of menu items by calling `.context_menu` multiple times. ###### Syntax ```py -# Index will be -1 for the header row/column ui_table.context_menu( - items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]] + items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]], + mode: SelectionMode | List[SelectionMode] | None = None ) -> UITable ``` @@ -1091,6 +1091,7 @@ ui_table.context_menu( | Parameter | Type | Description | | --------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | +| `mode` | `SelectionMode \| List[SelectionMode]` | The selection mode(s) to add the context menu to. Using `None` will trigger these menu items in all cases. | ##### data_bar @@ -1302,7 +1303,8 @@ Below are some of the custom types that are used in the above API definitions: AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] CellIndex = [RowIndex, ColumnIndex] Color = DeephavenColor | HexColor -ColumnIndex = int +# A ColumnIndex of None indicates a header row +ColumnIndex = int | None ColumnName = str ContextMenuAction = dict[str, Any] DataBarAxis = Literal["Proportional", "Middle", "Directional"] @@ -1313,7 +1315,8 @@ DeephavenColor = Literal[...] HexColor = str QuickFilterExpression = str RowData = dict[str, Any] -RowIndex = int +# A RowIndex of None indicates a header column +RowIndex = int | None SearchMode = Literal["show", "hide", "default"] SelectionMode = Literal["CELL", "ROW", "COLUMN"] SortDirection = Literal["ASC", "DESC"] From 7b6d38e2075ba88f2a5f77f3b3c2ac8067a3b0dc Mon Sep 17 00:00:00 2001 From: mikebender Date: Wed, 25 Oct 2023 16:56:06 -0400 Subject: [PATCH 11/12] Be more specific about when the menus are triggered --- plugins/ui/DESIGN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index a885f95ac..8694b1e6a 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1088,10 +1088,10 @@ ui_table.context_menu( ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | -| `mode` | `SelectionMode \| List[SelectionMode]` | The selection mode(s) to add the context menu to. Using `None` will trigger these menu items in all cases. | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | +| `mode` | `SelectionMode \| List[SelectionMode]` | The selection mode(s) to add the context menu to, depending on how the context menu was triggered. Using `None` will add these menu items in all cases.
    - `CELL`: Triggered from a cell.
    - `ROW`: Triggered from a row header.
    - `COLUMN`: Triggered from a column header. | ##### data_bar From 7fade48927a939a0fef0f94c8d9f91f73a70a3fa Mon Sep 17 00:00:00 2001 From: mikebender Date: Thu, 26 Oct 2023 09:28:28 -0400 Subject: [PATCH 12/12] Update based on review - Change all constants to SCREAMING_SNAKE_CASE, as per PEP8 - Update `context_menu` to use it's own type instead of using `SelectionMode` so it's a little clearer --- plugins/ui/DESIGN.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index 8694b1e6a..d0d48ae44 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1081,17 +1081,19 @@ Add custom items to the context menu. You can provide a list of actions that alw ```py ui_table.context_menu( - items: list[ContextMenuAction] | Callable[[CellIndex, RowData], list[ContextMenuAction]], - mode: SelectionMode | List[SelectionMode] | None = None + items: ContextMenuAction + | list[ContextMenuAction] + | Callable[[CellIndex, RowData], ContextMenuAction | list[ContextMenuAction]], + mode: ContextMenuMode = "CELL", ) -> UITable ``` ###### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `items` | `list[ContextMenuAction] \| Callable[[CellIndex, RowData], list[ContextMenuAction]]` | The items to add to the context menu. May be a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns a list of `ContextMenuAction` objects. | -| `mode` | `SelectionMode \| List[SelectionMode]` | The selection mode(s) to add the context menu to, depending on how the context menu was triggered. Using `None` will add these menu items in all cases.
    - `CELL`: Triggered from a cell.
    - `ROW`: Triggered from a row header.
    - `COLUMN`: Triggered from a column header. | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `items` | `ContextMenuAction \| list[ContextMenuAction] \| Callable[[CellIndex, RowData], ContextMenuAction \| list[ContextMenuAction]]` | The items to add to the context menu. May be a single `ContextMenuAction`, a list of `ContextMenuAction` objects, or a callback function that takes the cell index and row data and returns either a single `ContextMenuAction` or a list of `ContextMenuAction` objects. | +| `mode` | `ContextMenuMode` | Which specific context menu(s) to add the menu item(s) to. Can be one or more modes. Using `None` will add menu items in all cases.
    - `CELL`: Triggered from a cell.
    - `ROW_HEADER`: Triggered from a row header.
    - `COLUMN_HEADER`: Triggered from a column header. | ##### data_bar @@ -1300,16 +1302,18 @@ The functionality provided my `ui.table` replaces some of the existing functions Below are some of the custom types that are used in the above API definitions: ```py -AggregationOperation = Literal["Count", "CountDistinct", "Distinct", "Min", "Max", "Sum", "AbsSum", "Var", "Avg", "Std", "First", "Last", "Unique", "Skip"] +AggregationOperation = Literal["COUNT", "COUNT_DISTINCT", "DISTINCT", "MIN", "MAX", "SUM", "ABS_SUM", "VAR", "AVG", "STD", "FIRST", "LAST", "UNIQUE", "SKIP"] CellIndex = [RowIndex, ColumnIndex] Color = DeephavenColor | HexColor # A ColumnIndex of None indicates a header row ColumnIndex = int | None ColumnName = str ContextMenuAction = dict[str, Any] -DataBarAxis = Literal["Proportional", "Middle", "Directional"] +ContextMenuModeOption = Literal["CELL", "ROW_HEADER", "COLUMN_HEADER"] +ContextMenuMode = ContextMenuModeOption | list[ContextMenuModeOption] | None +DataBarAxis = Literal["PROPORTIONAL", "MIDDLE", "DIRECTIONAL"] DataBarDirection = Literal["LTR", "RTL"] -DataBarValuePlacement = Literal["Beside", "Overlap", "Hide"] +DataBarValuePlacement = Literal["BESIDE", "OVERLAP", "HIDE"] # TODO: Fill in the list of Deephaven Colors we allow DeephavenColor = Literal[...] HexColor = str @@ -1317,7 +1321,7 @@ QuickFilterExpression = str RowData = dict[str, Any] # A RowIndex of None indicates a header column RowIndex = int | None -SearchMode = Literal["show", "hide", "default"] +SearchMode = Literal["SHOW", "HIDE", "DEFAULT"] SelectionMode = Literal["CELL", "ROW", "COLUMN"] SortDirection = Literal["ASC", "DESC"] ```