diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml index 46bc099e..8423b54a 100644 --- a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml +++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-theme.xml @@ -7,7 +7,8 @@ A theme is an entity responsible for deciding the visual appearance of - windows and + windows + and components. Primarily, themes can be considered to be functions from components to sets of render nodes, although they do have some other responsibilities with regard to @@ -18,18 +19,70 @@ - Windows come with a set of predefined - decoration - components. Themes are responsible for deciding, - given a set of - layout constraints, where each of these components - are to be placed within the constraints. + Windows + come with a set of predefined decoration + components. Themes are responsible for deciding, given + a set of + layout constraints, where each of these components are + to be placed within the constraints. - + - Components... + A theme contains a set of theme component functions that, given a component + c, will return a set of + render nodes + that describe how + c + should be rendered. The actual theme component function evaluated for any given component is chosen based on + the + theme classes + defined for the component. + + + + + + A theme class is a textual string that is used by themes to locate theme information for + specific components. The process is as follows for a given theme T: + + + + + For a given component c, request the non-empty list + S + of style classes held by c: + + + For each style class k in S: + + + If the theme T contains a theme component function for + k, then evaluate the component function, passing it + c, and halt execution. + + + Otherwise, continue iterating over k. + + + + + If there were no theme component functions for any style class in S, then + evaluate the fallback component function defined by the theme. + + + + + + + The fallback component function is a function that will yield render nodes if no other + component function can handle the given component and style classes. The fallback function is defined internally + to the theme, and will typically return render nodes that unambiguously indicate that something is wrong; the + fallback function should not be evaluated unless something is wrong with the theme or the component is defined in + a manner that makes it incompatible with the theme.