Module style 

Style

Traits and functions that allow for styling Views.

The Floem Style System

The Style struct

The style system is centered around a Style struct. Style internally is just a hashmap (although one from the im crate so it is cheap to clone). It maps from a StyleKey to Rc<dyn Any>.

The StyleKey

StyleKey holds a static reference (that is used as the hash value) to a StyleKeyInfo enum which enumerates the different kinds of values that can be in the map. Which value is in the StyleKeyInfo enum is used to know how to downcast the Rc<dyn Any.

The key types from the StyleKeyInfo are: (these are all of the different things that can be added to a Style).

• Transition,
• Prop(StylePropInfo),
• Selector(StyleSelectors),
• Class(StyleClassInfo),
• ContextMappings,

Transitions and context mappings don’t hold any extra information, they are just used to know how to downcast the Rc<dyn Any>.

StyleSelectors is a bit mask of which selectors are active.

StyleClassInfo holds a function pointer that returns the name of the class as a String. The function pointer is basically used as a vtable for the class. If classes needed more methods other than name, those methods would be added to StyleClassInfo.

StylePropInfo is another vtable, similar to StyleClassInfo and holds function pointers for getting the name of a prop, the props interpolation function from the StylePropValue trait, the associated transition key for the prop, and others.

Props store props. Transitions store transition values. Classes, context mappings, and selectors store nested Style maps.

Applying Styles to Views

A style can be applied to a view in two different ways. A single Style can be added to the view_style method of the view trait or multiple Styles can be added by calling style on an IntoView from the Decorators trait.

Calls to style from the decorators trait have a higher precedence than the view_style method, meaning calls to style will override any matching StyleKeyInfo that came from the view_style method.

If you make repeated calls to style from the decorators trait, each will be added separately to the ViewState that is managed by Floem and associated with the ViewId of the view that style was called on. The ViewState stores a Stack of styles and later calls to style (and thus larger indicies in the style stack) will take precedence over earlier calls.

style from the deocrators trait is reactive and the function that returns the style map with be re-run in response to any reactive updates that it depends on. If it gets a reactive update, it will have tracked which index into the style stack it had when it was first called and will overrite that index and only that index so that other calls to style are not affected.

Style Resolution

A final computed_style is resolved in the style_pass of the View trait.

Context

It first received a Style map that is used as context. The context is passed down the view tree and carries the inherited properties that were applied to any parent. Inherited properties include all classes and any prop that has been marked as inherited.

View Style

The style first gets the Style (if any) from the view_style method.

Style

Then it gets the style from any calls to style from the decorators trait. It starts with the first index in the style Stack and applies each successive Style over the combination of any previous ones.

Then the style from the Decorators / ViewState is applied over (overriding any matching props) the style from view_style.

Nested map resolution

Then any classes that have been applied to the view, and the active selector set are used to resolve nested maps.

Nested maps such as classes and selectors are recursively applied, breadth first. So, deeper / more nested style maps take precendence.

This style map is the combined style of the View.

Updated context

Finally, the context style is updated using the combined style, applying any style key that is inherited to the context so that the children will have acces to them.

Prop Extraction

The final computed style of a view will be passed to the style_pass method from the View trait.

Views will store fields that are struct that are prop extractors. These structs are created using the prop_extractor! macro.

These structs can then be used from in the style_pass to extract props using the read (or read_exact) methods that are created by the prop_extractor macro.

The read methods will take in the combined style for that View and will automatically extract any matching prop values and transitions for those props.

Transition interpolation

If there is a transition for a prop, the extractor will keep track of the current time and transition state and will set the final extracted value to a properly interpolated value using the state and current time.

Custom Style Props, Classes, and Extractors.

You can create custom style props with the prop! macro, classes with the [style_class!] macro, and extractors with the prop_extractor! macro.

Custom Props

You can create custom props.

Doing this allows you to store arbitrary values in the style system.

You can use these to style the view, change it’s behavior, update it’s state, or anything else.

By implementing the StylePropValue trait for your prop (which you must do) you can

• optionally set how the prop should be interpolated (allowing you to customize what interpolating means in the context of your prop)

• optionally provide a debug_view for your prop, which debug view will be used in the Floem inspector. This means that you can customize a complex debug experience for your prop with very little effort (and it really can be any arbitrary view. no restrictions.)

• optionally add a custom implementation of how a prop should be combined with another prop. This is different from interpolation and is useful when you want to specify how properties should override each other. The default implementation just replaces the old value with a new value, but if you have a prop with multiple optional fields, you might want to only replace the fields that have a Some value.

Custom Classes

If you create a custom class, you can apply that class to any view, and when the final style for that view is being resolved, if the style has that class as a nested map, it will be applied, overriding any prviously set values.

Custom Extractors

You can create custom extractors and embed them in your custom views so that you can get out any built in prop, or any of your custom props from the final combined style that is applied to your View.

Re-exports

pub use theme::DesignSystem;

pub use theme::StyleThemeExt;

pub use unit::AnchorAbout;

pub use unit::Angle;

pub use unit::Auto;

pub use unit::DurationUnitExt;

pub use unit::Pct;

pub use unit::Px;

pub use unit::PxPct;

pub use unit::PxPctAuto;

pub use unit::UnitExt;

pub use recalc::InheritedChanges;

pub use recalc::InheritedGroups;

pub use recalc::Propagate;

pub use recalc::RecalcFlags;

pub use recalc::StyleRecalcChange;

Modules

recalc

Style recalculation change tracking.

theme

unit

Structs

AlignContentProp

Controls alignment of wrapped flex lines.

AlignItemsProp

Controls alignment of flex items along the cross axis.

AlignSelf

Controls individual alignment along the cross axis.

AspectRatio

Sets the preferred aspect ratio for the view.

Background

Sets the background color or image.

Border

Structure holding border widths for all four sides

BorderColor

Structure holding border colors for all four sides

BorderColorProp

Sets the border color for all sides.

BorderProgress

Controls the progress/completion of the border animation.

BorderProp

Sets the border properties for all sides.

BorderRadius

Structure holding border radius for all four corners

BorderRadiusProp

Sets the border radius for all corners.

BoxShadow

Structure holding data about the shadow.

BoxShadowProp

Adds one or more drop shadows to the view.

BoxSizingProp

Controls how the total width and height are calculated.

BoxTreeProps

BuiltinStyle

ColGap

Sets the gap between columns in grid or flex layouts.

Cursor

Sets the cursor style when hovering over the view.

CursorColor

Sets the color of the text cursor.

Dimension

A unit of linear measurement

DirectTransition

Direct transition controller using TransitionState without the Style system.

Disabled

Controls the disabled state of the view.

DisplayProp

Controls the display type of the view.

Draggable

Controls whether the view can be dragged.

ExtractorField

FlexBasis

Sets the initial main size of a flex item.

FlexDirectionProp

Sets the direction of the main axis for flex items.

FlexGrow

Sets the flex grow factor for the flex item.

FlexShrink

Sets the flex shrink factor for the flex item.

FlexWrapProp

Controls whether flex items wrap to new lines.

Focusable

Controls whether the view can receive focus.

FontFamily

Sets the font family for text content.

FontProps

FontSize

Sets the font size for text content.

FontStyle

Sets the font style (italic, normal) for text content.

FontWeight

Sets the font weight (boldness) for text content.

Foreground

Sets the foreground color or pattern.

GridAutoColumns

Specifies the size of implicitly-created grid columns.

GridAutoFlow

Controls how auto-placed items get flowed into the grid.

GridAutoRows

Specifies the size of implicitly-created grid rows.

GridColumn

Specifies a grid item’s location within the grid column.

GridRow

Specifies a grid item’s location within the grid row.

GridTemplateColumns

Defines the line names and track sizing functions of the grid columns.

GridTemplateRows

Defines the line names and track sizing functions of the grid rows.

Height

Sets the height of the view.

InheritedInteractionCx

Inherited interaction context that is propagated from parent to children.

InsetBottom

Sets the bottom offset for positioned views.

InsetLeft

Sets the left offset for positioned views.

InsetRight

Sets the right offset for positioned views.

InsetTop

Sets the top offset for positioned views.

InteractionState

The interaction state of a view, used to determine which style selectors apply.

IsFixed

Enables fixed positioning relative to the viewport.

JustifyContentProp

Controls alignment of flex items along the main axis.

JustifyItemsProp

Controls default alignment of grid items along the inline axis.

JustifySelf

Controls individual alignment along the inline axis.

LineHeight

Sets the line height for text content.

Margin

Structure holding margin values for all four sides

MarginProp

Sets the margin for all sides.

MaxHeight

Sets the maximum height of the view.

MaxWidth

Sets the maximum width of the view.

MinHeight

Sets the minimum height of the view.

MinWidth

Sets the minimum width of the view.

Opacity

Sets the opacity of the view.

Outline

Sets the outline stroke properties.

OutlineColor

Sets the color of the view’s outline.

OutlineProgress

Controls the progress/completion of the outline animation.

OverflowX

How children overflowing their container in Y axis should affect layout

OverflowY

How children overflowing their container in X axis should affect layout

Padding

Structure holding padding values for all four sides

PaddingProp

Sets the padding for all sides.

PointerEventsProp

Controls whether the view can be the target of mouse events.

PositionProp

Sets the positioning scheme for the view.

RotateAbout

Sets the anchor point for rotation transformations.

Rotation

Sets the rotation transform angle.

RowGap

Sets the gap between rows in grid or flex layouts.

ScaleAbout

Sets the anchor point for scaling transformations.

ScaleX

Sets the horizontal scale transform.

ScaleY

Sets the vertical scale transform.

Selectable

Controls whether the view’s text can be selected.

Selected

Sets the selected state of the view.

SelectionCornerRadius

Sets the corner radius of text selections.

SelectionStyle

StrokeWrap

Style

StyleCache

Cache for style resolution results.

StyleCacheKey

A cache key for style resolution results.

StyleClassInfo

StyleClassRef

StyleCx

StyleKey

StylePropInfo

StylePropRef

StyleSelectors

Bitmask of active style selectors

TextAlignProp

Sets text alignment within the view.

TextColor

Sets the text color.

TextOverflowProp

Controls how overflowed text content is handled.

TransformProps

Transition

TransitionState

TranslateX

Sets the horizontal translation transform.

TranslateY

Sets the vertical translation transform.

Width

Sets the width of the view.

ZIndex

Controls the stack order of positioned views.

Enums

AlignContent

Sets the distribution of space between and around content items For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis

AlignItems

Used to control how child nodes are aligned. For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis

BoxSizing

Specifies whether size styles for this node are assigned to the node’s “content box” or “border box”

CombineResult

CursorStyle

Cursor style

Display

Sets the layout used for the children of this node

FlexDirection

The direction of the flexbox layout main axis.

FlexWrap

Controls whether flex items are forced onto one line or can wrap onto multiple lines.

PointerEvents

Pointer event handling mode

Position

The positioning strategy for this item.

StyleKeyInfo

StyleMapValue

Internal storage for style property values in the style map.

StyleSelector

Pseudo-class selectors for conditional styling

StyleValue

The value for a [Style] property in the public API.

TextOverflow

Text overflow behavior

Traits

CustomStylable

A trait that enables views to accept custom styling beyond the standard Style properties.

CustomStyle

A trait for custom styling of specific view types.

StyleClass

StyleProp

StylePropReader

StylePropValue

Functions

resolve_nested_maps

the bool in the return is a classes_applied flag. if a new class has been applied, we need to do a request_style_recursive

Type Aliases

JustifyContent

Sets the distribution of space between and around content items For Flexbox it controls alignment in the main axis For Grid it controls alignment in the inline axis

JustifyItems

Used to control how child nodes are aligned. Does not apply to Flexbox, and will be ignored if specified on a flex container For Grid it controls alignment in the inline axis