Class AppTheme

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.AppTheme
All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, Cloneable
public class AppTheme extends PropCnr
A custom theme: a family of the kind the shipped families are - a name, a light member and a dark member - made by an application's designer (CC-DESIGN-THEME-EDITOR DESIGN.md section 3, phase TE1).

On disk a theme is one .iiziStyle file under a module's style folder, the root tag theme, beside the paletteColor and palette files (the FontFaces precedent: one folder extension, the root tag names the type). Its children:

A theme is its base plus overrides. What a member does not set comes from the base family's member of that mode in the shipped sheet, so a theme is always complete and a theme of three edits is a valid theme. The client receives it as two rules of the app block, one per mode, each holding all 48 tokens (AppPaletteCSS).

The family name is the file name folded as a palette slug (ColorSlug): Ocean is ocean. It must start with a letter and must not be a name the platform uses (RESERVED): a shipped family, a Dojo skin name live or removed, or a mode name. Two modules of one application whose themes fold to one name are both refused by the generator, as two colliding palette slugs are.

Verification (verify(PropVerification)): an ERROR for a bad name, a missing or unknown base, an unknown modes value, a literal holding a color reference and a pointer that leads into a cycle; a WARNING for a child that is neither a role nor a token (not delivered), a token value that is not of its kind, a member the modes value leaves unused, and every contrast pair of ColorRoles.CONTRAST_PAIRS below its WCAG ratio, per mode, with the ratio in the text. Contrast is never an error: a theme below AA still ships, an application's own brand may be below AA and its designer may know it.

Author:
Christopher Mindus

  • Field Details

    • TAG

      public static final String TAG
      The root tag of a theme file, the base-properties.xml row: theme.
      See Also:

    • VERIFY_ID

      public static final String VERIFY_ID
      The ID prefix of the verification errors this class adds.
      See Also:

    • BASE

      public static final Atom BASE
      The base family child: base.

    • MODES

      public static final Atom MODES
      The members child: modes.

    • MODES_BOTH

      public static final int MODES_BOTH
      The theme has a light and a dark member: the default.
      See Also:

    • MODES_LIGHT

      public static final int MODES_LIGHT
      The theme has a light member only, which serves both modes.
      See Also:

    • MODES_DARK

      public static final int MODES_DARK
      The theme has a dark member only, which serves both modes.
      See Also:

    • LIGHT

      public static final String LIGHT
      The light member: light.
      See Also:

    • DARK

      public static final String DARK
      The dark member: dark.
      See Also:

    • MODE_NAMES

      public static final List<String> MODE_NAMES
      The modes, in the order the generator writes them.

    • RESERVED

      public static final Set<String> RESERVED
      The family names a theme must not fold to, sorted: the shipped families (UISchemes.Family), the modes (UISchemes.Mode), the live Dojo skins (UIThemes.Name), the names an old launcher sends (UISchemesOldNames), and the removed skins and mode names no catalogue lists.

  • Constructor Details

    • AppTheme

      public AppTheme()
      Creates the theme property container without a name. The name must be set in all cases using the setPropertyAtom call.

    • AppTheme

      public AppTheme(Atom propertyAtom)
      Creates the theme property container with the specified name.
      Parameters:
      propertyAtom - the name of the theme, its file name.

  • Method Details

    • familyName

      public static String familyName(String name)
      Folds a theme name to its family name, as a palette slug is folded.
      Parameters:
      name - The theme's name, its file name without the extension.
      Returns:
      The family name: lower case, runs of other characters than a-z0-9 one dash, no dash at either end; possibly empty.

    • checkFamilyName

      public static String checkFamilyName(String family)
      Checks a family name against the name rule.
      Parameters:
      family - The folded family name.
      Returns:
      null when the name may be a theme's, otherwise the reason, phrased to follow "The family name '...'".

    • getFamilyName

      public String getFamilyName()
      Gets the family name of this theme: its name folded.
      Returns:
      The family name, possibly invalid (checkFamilyName(String)).

    • getBase

      public String getBase()
      Gets the base family's name as written.
      Returns:
      The name, or null when the theme has none.

    • getBaseFamily

      public UISchemes.Family getBaseFamily()
      Gets the base family.
      Returns:
      The shipped family, or null when the base is missing or unknown.

    • getModes

      public int getModes()
      Gets the members value.
      Returns:
      MODES_BOTH, MODES_LIGHT, MODES_DARK, or another value as written, which verification reports.

    • memberFor

      public String memberFor(String mode)
      Gets the member that serves a mode: the mode's own, or for a theme with one member that member.
      Parameters:
      mode - LIGHT or DARK.
      Returns:
      The member's name, LIGHT or DARK.

    • hasMember

      public boolean hasMember(String member)
      Checks if the theme has a member, by its modes value.
      Parameters:
      member - LIGHT or DARK.
      Returns:
      true when the member is one the theme has.

    • getMember

      public PropCnr getMember(String member)
      Gets a member's container.
      Parameters:
      member - LIGHT or DARK.
      Returns:
      The container, or null when the file has none.

    • getRoleValue

      public GProp<?> getRoleValue(String member, ColorRoles.Role role)
      Gets the value a member sets for a role.
      Parameters:
      member - LIGHT or DARK.
      role - The role.
      Returns:
      The ColorProp or ColorReference, or null when the member does not set the role (or sets it as something else, which verification reports).

    • getTokenValue

      public String getTokenValue(String member, ThemeTokens.Token token)
      Gets the value a member sets for a token.
      Parameters:
      member - LIGHT or DARK.
      token - The token.
      Returns:
      The CSS text, or null when the member does not set the token.

    • composeColors

      public Map<String,Integer> composeColors(String mode, ThemeSheetPalette.Sheet sheet, PropCnr basePalette)
      Gets the colors a member composes to, for the contrast check of the Designer and of verify(PropVerification): per role, the base family's value from the sheet, then the role override of this theme's module (a palette color named by the role at the top of its style folder, B2), then the theme's own value - a pointer resolved for the mode by ColorResolver.
      Parameters:
      mode - LIGHT or DARK: the mode served.
      sheet - The family members of the shipped sheet.
      basePalette - The platform base palette for the resolver, or null.
      Returns:
      The ARGB colors by role name; a role whose value does not resolve is absent. Empty when the base is unknown or the sheet has no member for it.

    • verify

      public boolean verify(PropVerification verification)
      Verifies this theme: the name, the base, the members value, every member's children, and the contrast of every pair per mode (pattern: ThemesProp.verify).
      Specified by:
      verify in interface IGProp<GProp<?>[]>
      Overrides:
      verify in class PropCnr
      Parameters:
      verification - The property verification class.
      Returns:
      true if verification should proceed, false if disposed of and verification should not take place.

    • collect

      public static List<AppTheme> collect(PropCnr folder)
      Collects the themes under a folder, recursively, in tree order.
      Parameters:
      folder - A module's style folder, or any folder under it.
      Returns:
      The themes, possibly empty, never null.