..
  SPDX-License-Identifier: CC-BY-4.0
  Copyright Contributors to the OpenColorIO Project.
  Do not edit! This file was automatically generated by share/docs/frozendoc.py.

.. py:class:: ColorSpaceMenuParameters
   :module: PyOpenColorIO

   Parameters controlling which color spaces appear in menus.

   The :ref:`ColorSpaceMenuHelper` class is intended to be used by applications to get the list of items to show in color space menus.

   The :ref:`ColorSpaceMenuParameters` class is used to configure the behavior as needed for any given menu. Here is the algorithm used to produce a list of "items" (or strings) that will appear in a menu:

   1) Use setRole to identify a role that controls a given menu. If the config has this role, then only that color space is returned. The name is set to the color space name, the UIName is presented as "<role name> (<color space name>)". It may be useful for the application to then grey-out the menu or otherwise indicate to the user that the value for this menu is not user selectable since it was pre-determined by the config. If the config does not have that role, the algorithm continues to the remaining steps.

   2) The IncludeColorSpaces, SearchReferenceSpaceType, and IncludeNamedTransforms parameters are used to identify a set of items from the config that are potential candidates for use in the menu, as follows:
   - IncludeColorSpaces: Set to true to include color spaces in the menu.
   - SearchReferenceSpaceType: Use this to control whether the menu should include all color spaces, only display color spaces, or only non-display color spaces.
   - IncludeNamedTransforms: Set to true to include named transforms in the menu.

   3) The set of items from step 2 is then filtered in step 3 using the following parameters:
   - AppCategories: A list of strings specified by the application based on the purpose of the menu. For example, if the menu is used to select a color space for importing an image, the application might specify the 'file-io' category, whereas if it is to select a working color space, it might specify the 'working-space' category. Application developers should document what strings they are using for each menu so that config authors know what categories to use in their configs. Alternatively, an application could let advanced users customize the string to use for a given menu in the application.
   - Encodings: A list of strings used to further refine the items selected from the AppCategories. For example, an application might specify 'working-space' as the category and then specify 'scene-linear' as the encoding to only use items that have both of those properties (e.g., only select scene-linear working color spaces).
   - UserCategories: A list of strings specified by the end-user of the application. OCIO will check for these strings in an environment variable, or they may be passed in from the application.

   Basically the intent is for the filtering to return the intersection of the app categories, encoding, and user categories. However, some fall-backs are in place to ensure that the filtering does not remove all menu items. Here is the detailed description:

   3a) The items from step 2 are filtered to generate a list of appItems containing only the ones that contain at least one of the AppCategories strings in their "categories" property and one of the encodings in their "encoding" property. If this list is empty, an attempt is made to generate a non-empty appItems list by only filtering by AppCategories. If that is empty, an attempt is made to only filter by Encodings.

   3b) The items from step 2 are filtered to generate a list of userItems containing only the ones that have at least one of the UserCategories strings in their "categories" property.

   3c) If both appItems and userItems are non-empty, a list of resultItems will be generated as the intersection of those two lists.

   3d) If the resultItems list is empty, the appList will be expanded by only filtering by AppCategories and not encodings. The resultItems will be formed again as the intersection of the appItems and userItems.

   3e) If the resultItems is still empty, it will be set to just the appItems from step 3a.

   3f) If the resultItems is still empty, it will be set to just the userItems.

   3g) If the resultItems is still empty, the items are not filtered and all items from step 2 are returned. The rationale is that if step 2 has produced any items, it is not acceptable for step 3 to remove all of them. An application usually expects to have a non-zero number of items to display in the menu. However, if step 2 produces no items (e.g. the application requests only named transforms and the config has no named transform), then no items will be returned.

   4) If IncludeRoles is true, the items from step 3 are extended by including an item for each role. The name is set to the role name, the UIName is presented as "<role name> (<color
       space name>)", and the family is set to "Roles".

   5) If AddColorSpace has been used to add any additional items, these are appended to the final list.


   .. py:method:: ColorSpaceMenuParameters.__init__(*args, **kwargs)
      :module: PyOpenColorIO

      Overloaded function.

      1. __init__(self: PyOpenColorIO.ColorSpaceMenuParameters, config: PyOpenColorIO.Config) -> None

      2. __init__(self: PyOpenColorIO.ColorSpaceMenuParameters, config: PyOpenColorIO.Config, role: str = '', includeColorSpaces: bool = True, searchReferenceSpaceType: PyOpenColorIO.SearchReferenceSpaceType = <SearchReferenceSpaceType.SEARCH_REFERENCE_SPACE_ALL: 2>, includeNamedTransforms: bool = False, appCategories: str = '', encodings: str = '', userCategories: str = '', includeRoles: bool = False) -> None


   .. py:method:: ColorSpaceMenuParameters.addColorSpace(self: PyOpenColorIO.ColorSpaceMenuParameters, colorSpace: str) -> None
      :module: PyOpenColorIO

      Add an additional color space (or named transform) to the menu.

      Note that an additional color space could be:
      - an inactive color space,
      - an active color space not having at least one of the selected categories,
      - a newly created color space. Will throw when creating the menu if color space is not part of the config. Nothing is done if it is already part of the menu. It's ok to call this multiple times with the same color space, it will only be added to the menu once. If a role name is passed in, the name in the menu will be the color space name the role points to.


   .. py:method:: ColorSpaceMenuParameters.clearAddedColorSpaces(self: PyOpenColorIO.ColorSpaceMenuParameters) -> None
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getAddedColorSpaces(self: PyOpenColorIO.ColorSpaceMenuParameters) -> PyOpenColorIO.ColorSpaceMenuParameters.AddedColorSpaceIterator
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getAppCategories(self: PyOpenColorIO.ColorSpaceMenuParameters) -> str
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getConfig(self: PyOpenColorIO.ColorSpaceMenuParameters) -> PyOpenColorIO.Config
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getEncodings(self: PyOpenColorIO.ColorSpaceMenuParameters) -> str
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getIncludeColorSpaces(self: PyOpenColorIO.ColorSpaceMenuParameters) -> bool
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getIncludeNamedTransforms(self: PyOpenColorIO.ColorSpaceMenuParameters) -> bool
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getIncludeRoles(self: PyOpenColorIO.ColorSpaceMenuParameters) -> bool
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getRole(self: PyOpenColorIO.ColorSpaceMenuParameters) -> str
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.getSearchReferenceSpaceType(self: PyOpenColorIO.ColorSpaceMenuParameters) -> PyOpenColorIO.SearchReferenceSpaceType
      :module: PyOpenColorIO

      Can be used to restrict the search using the ReferenceSpaceType of the color spaces. It has no effect on roles and named transforms.


   .. py:method:: ColorSpaceMenuParameters.getUserCategories(self: PyOpenColorIO.ColorSpaceMenuParameters) -> str
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.setAppCategories(self: PyOpenColorIO.ColorSpaceMenuParameters, appCategories: str) -> None
      :module: PyOpenColorIO

      App categories is a comma separated list of categories. If appCategories is not NULL and not empty, all color spaces that have one of the categories will be part of the menu.


   .. py:method:: ColorSpaceMenuParameters.setConfig(self: PyOpenColorIO.ColorSpaceMenuParameters, config: PyOpenColorIO.Config) -> None
      :module: PyOpenColorIO

      :ref:`Config` is required to be able to create a :ref:`ColorSpaceMenuHelper`.


   .. py:method:: ColorSpaceMenuParameters.setEncodings(self: PyOpenColorIO.ColorSpaceMenuParameters, encodings: str) -> None
      :module: PyOpenColorIO

      Encodings is a comma separated list of encodings. When not empty, is retricting the search to color spaces that are using one of the encodings.


   .. py:method:: ColorSpaceMenuParameters.setIncludeColorSpaces(self: PyOpenColorIO.ColorSpaceMenuParameters, includeColorSpaces: bool = True) -> None
      :module: PyOpenColorIO

      Include all color spaces (or not) to :ref:`ColorSpaceMenuHelper`. Default is to include color spaces.


   .. py:method:: ColorSpaceMenuParameters.setIncludeNamedTransforms(self: PyOpenColorIO.ColorSpaceMenuParameters, includeNamedTransforms: bool = True) -> None
      :module: PyOpenColorIO

      Include all named transforms (or not) to :ref:`ColorSpaceMenuHelper`. Default is not to include named transforms.


   .. py:method:: ColorSpaceMenuParameters.setIncludeRoles(self: PyOpenColorIO.ColorSpaceMenuParameters, includeRoles: bool = True) -> None
      :module: PyOpenColorIO

      Include all roles (or not) to :ref:`ColorSpaceMenuHelper`. Default is not to include roles. Roles are added after color spaces with an single hierarchy level named "Roles".


   .. py:method:: ColorSpaceMenuParameters.setRole(self: PyOpenColorIO.ColorSpaceMenuParameters, role: str) -> None
      :module: PyOpenColorIO

      If role is a valid role, other parameters are ignored and menu will contain only that role.


   .. py:method:: ColorSpaceMenuParameters.setSearchReferenceSpaceType(self: PyOpenColorIO.ColorSpaceMenuParameters, searchReferenceSpaceType: PyOpenColorIO.SearchReferenceSpaceType) -> None
      :module: PyOpenColorIO


   .. py:method:: ColorSpaceMenuParameters.setUserCategories(self: PyOpenColorIO.ColorSpaceMenuParameters, categories: str) -> None
      :module: PyOpenColorIO

      User categories is a comma separated list of categories. If OCIO_USER_CATEGORIES_ENVVAR env. variable is defined and not empty, this parameter is ignored and the value of the env. variable is used for user categories.

