Parameters controlling which color spaces appear in menus.
The ColorSpaceMenuHelper class is intended to be used by applications to get the list of items to show in color space menus.
The 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.
Definition at line 99 of file OpenColorAppHelpers.h.
1.8.6 
