cave_utils.api.appBar

  1"""
  2The app bar is a key element of the CAVE App, positioned on the left or
  3right side of the screen. It provides actions that allow users to
  4navigate between [pages][], launch [panes][], and interact with the
  5CAVE API through [predefined][] or [custom][] commands.
  6
  7If specified, both left and right side app bars can be displayed
  8simultaneously.
  9
 10[pages]: pages.html
 11[panes]: panes.html
 12[predefined]: #appBar_data_star.spec
 13[custom]: #appBar_data_star.spec
 14"""
 15
 16from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
 17import type_enforced
 18
 19
 20@type_enforced.Enforcer
 21class appBar(ApiValidator):
 22    """
 23    The app bar is located under the path **`appBar`**.
 24    """
 25
 26    @staticmethod
 27    def spec(data: dict = dict(), **kwargs):
 28        """
 29        @private
 30        Arguments:
 31
 32        * **`data`**: `[dict]` = `{}` → The data to pass to `appBar.data.*`.
 33        """
 34        return {"kwargs": kwargs, "accepted_values": {}}
 35
 36    def __extend_spec__(self, **kwargs):
 37        data = self.data.get("data", {})
 38        CustomKeyValidator(
 39            data=data, log=self.log, prepend_path=["data"], validator=appBar_data_star, **kwargs
 40        )
 41
 42
 43@type_enforced.Enforcer
 44class appBar_data_star(ApiValidator):
 45    """
 46    The app bar data is located under the path **`appBar.data`**.
 47    """
 48
 49    @staticmethod
 50    def spec(
 51        icon: str,
 52        type: str,
 53        bar: str,
 54        variant: [str, None] = None,
 55        color: [str, None] = None,
 56        apiCommand: [str, None] = None,
 57        apiCommandKeys: [list[str], None] = None,
 58        **kwargs,
 59    ):
 60        """
 61        Arguments:
 62
 63        * **`icon`**: `[str]` → An icon to display in the center of the action element.
 64            * **Note**: It must be a valid icon name from the [react-icons][] bundle, preceded by the abbreviated name of the icon library source.
 65            * **Example**: `"md/MdRocket"`.
 66        * **`type`**: `[str]` → The type of object displayed when the action is triggered.
 67            * **Accepted Values**:
 68                * `"session"`: The Session Pane
 69                * `"settings"`: The Application Settings Pane
 70                * `"button"`: A button that allows you to send a command to the CAVE API
 71                * `"pane"`: A [custom pane][]
 72                * `"page"`: A [page][]
 73        * **`bar`**: `[str]` → The location of the action element.
 74            * **Accepted Values**:
 75                * `"upperLeft"`: Upper section of the left-side bar
 76                * `"lowerLeft"`: Lower section of the left-side bar
 77                * `"upperRight"`: Upper section of the right-side bar
 78                * `"lowerRight"`: Lower section of the right-side bar
 79        * **`variant`**: `[str]` = `None` → The variant of the button.
 80            * **Accepted Values**:
 81                * When **`type`** == `"pane"`:
 82                    * `"modal"`: A [modal pane][]
 83                    * `"wall"`: A [wall pane][]
 84                * Otherwise:
 85                    * `None`
 86        * **`color`**: `[str]` = `<system-default-value>` &rarr;
 87            * The color of the button. If omitted, the default value is set by the system.
 88            * **Note**: It must be a valid RGBA string.
 89            * **Example**: `"rgba(255, 255, 255, 1)"`.
 90        * **`apiCommand`**: `[str]` = `None` &rarr; The name of the [API command][] to trigger.
 91        * **`apiCommandKeys`**: `[list[str]]` = `None` &rarr;
 92            * The root API keys to pass to your `execute_command` function if an
 93            `apiCommand` is provided. If omitted, all API keys are
 94            passed to `execute_command`.
 95
 96        [page]: pages.html
 97        [pane]: panes.html
 98        [modal pane]: panes.html
 99        [wall pane]: panes.html
100        [API command]: #appBar_data_star.spec
101        [react-icons]: https://react-icons.github.io/react-icons/search
102        """
103        return {
104            "kwargs": kwargs,
105            "accepted_values": {
106                "type": ["session", "settings", "button", "pane", "page"],
107                "variant": ["modal", "wall"] if type == "pane" else [],
108                "bar": ["upperLeft", "lowerLeft", "upperRight", "lowerRight"],
109            },
110        }
111
112    def __extend_spec__(self, **kwargs):
113        color = self.data.get("color")
114        if color:
115            self.__check_color_string_valid__(color_string=color, prepend_path=["color"])
116        # Validate pageIds
117        bar_type = self.data.get("type")
118        if bar_type == "page":
119            self.__check_subset_valid__(
120                subset=[kwargs.get("CustomKeyValidatorFieldId")],
121                valid_values=kwargs.get("page_validPageIds", []),
122                prepend_path=[],
123            )
124        if bar_type == "pane":
125            self.__check_subset_valid__(
126                subset=[kwargs.get("CustomKeyValidatorFieldId")],
127                valid_values=kwargs.get("pane_validPaneIds", []),
128                prepend_path=[],
129            )