Improve documentation for the native core and native core macro crates (#528)
* improve documentation for the native core and native core macro crates * fix spelling of depenency
This commit is contained in:
Demonthos authored and GitHub committed
1 parent
286cfa43b7
commit
2d08532bad
7 files changed
+312
-79
No files matched your search
@@ -7,6 +7,7 @@ use fxhash::FxHashSet;
|
||||
use crate::node_ref::{NodeMask, NodeView};
|
||||
use crate::traversable::Traversable;
|
||||
|
||||
/// Join two sorted iterators
|
||||
pub(crate) fn union_ordered_iter<T: Ord + Debug>(
|
||||
s_iter: impl Iterator<Item = T>,
|
||||
o_iter: impl Iterator<Item = T>,
|
||||
@@ -44,13 +45,45 @@ pub(crate) fn union_ordered_iter<T: Ord + Debug>(
|
||||
/// This state is derived from children. For example a node's size could be derived from the size of children.
|
||||
/// Called when the current node's node properties are modified, a child's [ChildDepState] is modified or a child is removed.
|
||||
/// Called at most once per update.
|
||||
/// ```rust
|
||||
/// #[derive(Clone, Copy, PartialEq, Default)]
|
||||
/// struct Layout {
|
||||
/// width: u32,
|
||||
/// height: u32,
|
||||
/// }
|
||||
///
|
||||
/// impl ChildDepState for Layout {
|
||||
/// type Ctx = ();
|
||||
/// // The layout depends on the layout of the children.
|
||||
/// type DepState = Layout;
|
||||
/// fn reduce<'a>(
|
||||
/// &mut self,
|
||||
/// _node: NodeView,
|
||||
/// children: impl Iterator<Item = &'a Self::DepState>,
|
||||
/// _ctx: &Self::Ctx,
|
||||
/// ) -> bool
|
||||
/// where
|
||||
/// Self::DepState: 'a{
|
||||
/// /// Children are layed out form left to right. The width of the parent is the sum of the widths and the max of the heights.
|
||||
/// let new = children.copied().reduce(|c1, c2| Layout{
|
||||
/// width: c1.width + c2.width,
|
||||
/// height: c1.height.max(c2.height)
|
||||
/// }).unwrap_or_default();
|
||||
/// let changed = new != self.combined;
|
||||
/// self = new;
|
||||
/// changed
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait ChildDepState {
|
||||
/// The context is passed to the [ChildDepState::reduce] when it is pushed down.
|
||||
/// This is sometimes nessisary for lifetime purposes.
|
||||
/// The context is passed to the [ChildDepState::reduce] when it is resolved.
|
||||
type Ctx;
|
||||
/// This must be either a [ChildDepState], or [NodeDepState]
|
||||
/// A state from each child node that this node depends on. Typically this is Self, but it could be any state that is within the state tree.
|
||||
/// This must be either a [ChildDepState], or [NodeDepState].
|
||||
type DepState;
|
||||
/// The part of a node that this state cares about. This is used to determine if the state should be updated when a node is updated.
|
||||
const NODE_MASK: NodeMask = NodeMask::NONE;
|
||||
/// Resolve the state current node's state from the state of the children, the state of the node, and some external context.
|
||||
fn reduce<'a>(
|
||||
&mut self,
|
||||
node: NodeView,
|
||||
@@ -64,13 +97,55 @@ pub trait ChildDepState {
|
||||
/// This state that is passed down to children. For example text properties (`<b>` `<i>` `<u>`) would be passed to children.
|
||||
/// Called when the current node's node properties are modified or a parrent's [ParentDepState] is modified.
|
||||
/// Called at most once per update.
|
||||
/// ```rust
|
||||
/// use dioxus_native_core::node_ref::{NodeMask, AttributeMask, NodeView};
|
||||
/// use dioxus_native_core::state::*;
|
||||
///
|
||||
/// #[derive(Clone, Copy, PartialEq)]
|
||||
/// struct FontSize(usize);
|
||||
///
|
||||
/// impl ParentDepState for FontSize {
|
||||
/// type Ctx = ();
|
||||
/// // The font size depends on the font size of the parent element.
|
||||
/// type DepState = Self;
|
||||
/// const NODE_MASK: NodeMask =
|
||||
/// NodeMask::new_with_attrs(AttributeMask::Static(&[
|
||||
/// "font-size"
|
||||
/// ]));
|
||||
/// fn reduce<'a>(
|
||||
/// &mut self,
|
||||
/// node: NodeView,
|
||||
/// parent: Option<&'a Self::DepState>,
|
||||
/// ctx: &Self::Ctx,
|
||||
/// ) -> bool{
|
||||
/// let old = *self;
|
||||
/// // If the font size was set on the parent, it is passed down to the current element
|
||||
/// if let Some(parent) = parent{
|
||||
/// *self = parent;
|
||||
/// }
|
||||
/// // If the current node overrides the font size, use that size insead.
|
||||
/// for attr in node.attributes() {
|
||||
/// match attr.name {
|
||||
/// "font-size" => {
|
||||
/// self.0 = attr.value.as_text().unwrap().parse().unwrap();
|
||||
/// }
|
||||
/// // font-size is the only attribute we specified in the mask, so it is the only one we can see
|
||||
/// _ => unreachable!(),
|
||||
/// }
|
||||
/// }
|
||||
/// old != *self
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait ParentDepState {
|
||||
/// The context is passed to the [ParentDepState::reduce] when it is pushed down.
|
||||
/// This is sometimes nessisary for lifetime purposes.
|
||||
/// The context is passed to the [ParentDepState::reduce] when it is resolved.
|
||||
type Ctx;
|
||||
/// A state from from the parent node that this node depends on. Typically this is Self, but it could be any state that is within the state tree.
|
||||
/// This must be either a [ParentDepState] or [NodeDepState]
|
||||
type DepState;
|
||||
/// The part of a node that this state cares about. This is used to determine if the state should be updated when a node is updated.
|
||||
const NODE_MASK: NodeMask = NodeMask::NONE;
|
||||
/// Resolve the state current node's state from the state of the parent node, the state of the node, and some external context.
|
||||
fn reduce<'a>(
|
||||
&mut self,
|
||||
node: NodeView,
|
||||
@@ -80,56 +155,51 @@ pub trait ParentDepState {
|
||||
}
|
||||
|
||||
/// This state that is upadated lazily. For example any propertys that do not effect other parts of the dom like bg-color.
|
||||
/// Called when the current node's node properties are modified or a sibling's [NodeDepState] is modified.
|
||||
/// Called when the current node's node properties are modified or a one of its dependanices are modified.
|
||||
/// Called at most once per update.
|
||||
/// NodeDepState is the only state that can accept multiple dependancies, but only from the current node.
|
||||
/// ```rust, ignore
|
||||
/// impl<'a, 'b> NodeDepState<(&'a TextWrap, &'b ChildLayout)> for Layout {
|
||||
/// type Ctx = LayoutCache;
|
||||
/// ```rust
|
||||
/// use dioxus_native_core::node_ref::{NodeMask, AttributeMask, NodeView};
|
||||
/// use dioxus_native_core::state::*;
|
||||
///
|
||||
/// #[derive(Clone, Copy, PartialEq)]
|
||||
/// struct TabIndex(usize);
|
||||
///
|
||||
/// impl NodeDepState for TabIndex {
|
||||
/// type Ctx = ();
|
||||
/// const NODE_MASK: NodeMask =
|
||||
/// NodeMask::new_with_attrs(AttributeMask::Static(&sorted_str_slice!([
|
||||
/// "width", "height"
|
||||
/// ])))
|
||||
/// .with_text();
|
||||
/// fn reduce<'a>(
|
||||
/// NodeMask::new_with_attrs(AttributeMask::Static(&[
|
||||
/// "tabindex"
|
||||
/// ]));
|
||||
/// fn reduce(
|
||||
/// &mut self,
|
||||
/// node: NodeView,
|
||||
/// siblings: (&'a TextWrap, &'b ChildLayout),
|
||||
/// ctx: &Self::Ctx,
|
||||
/// siblings: (),
|
||||
/// ctx: &(),
|
||||
/// ) -> bool {
|
||||
/// let old = self.clone();
|
||||
/// let (text_wrap, child_layout) = siblings;
|
||||
/// if TextWrap::Wrap == text_wrap {
|
||||
/// if let Some(text) = node.text() {
|
||||
/// let lines = text_wrap.get_lines(text);
|
||||
/// self.width = lines.max_by(|l| l.len());
|
||||
/// self.height = lines.len();
|
||||
/// return old != self;
|
||||
/// }
|
||||
/// }
|
||||
/// let mut width = child_layout.width;
|
||||
/// let mut height = child_layout.width;
|
||||
/// let old = self;
|
||||
/// for attr in node.attributes() {
|
||||
/// match attr.name {
|
||||
/// "width" => {
|
||||
/// width = attr.value.as_text().unwrap().parse().unwrap();
|
||||
/// }
|
||||
/// "height" => {
|
||||
/// height = attr.value.as_text().unwrap().parse().unwrap();
|
||||
/// "tabindex" => {
|
||||
/// self.0 = attr.value.as_text().unwrap().parse().unwrap();
|
||||
/// }
|
||||
/// // tabindex is the only attribute we specified in the mask, so it is the only one we can see
|
||||
/// _ => unreachable!(),
|
||||
/// }
|
||||
/// }
|
||||
/// self.width = width;
|
||||
/// self.height = height;
|
||||
/// old != self
|
||||
/// old != *self
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
/// The generic argument (Depstate) must be a tuple containing any number of borrowed elments that are either a [ChildDepState], [ParentDepState] or [NodeDepState].
|
||||
pub trait NodeDepState<DepState> {
|
||||
/// The generic argument (Depstate) must be a tuple containing any number of borrowed elements that are either a [ChildDepState], [ParentDepState] or [NodeDepState].
|
||||
// Todo: once GATs land we can model multable dependencies better
|
||||
|
||||
pub trait NodeDepState<DepState = ()> {
|
||||
/// The state passed to [NodeDepState::reduce] when it is resolved.
|
||||
type Ctx;
|
||||
/// The part of a node that this state cares about. This is used to determine if the state should be updated when a node is updated.
|
||||
const NODE_MASK: NodeMask = NodeMask::NONE;
|
||||
/// Resolve the state current node's state from the state of the sibling states, the state of the node, and some external context.
|
||||
fn reduce(&mut self, node: NodeView, siblings: DepState, ctx: &Self::Ctx) -> bool;
|
||||
}
|
||||
|
||||
@@ -144,7 +214,6 @@ pub trait State: Default + Clone {
|
||||
) -> FxHashSet<ElementId>;
|
||||
}
|
||||
|
||||
// Todo: once GATs land we can model multable dependencies
|
||||
impl ChildDepState for () {
|
||||
type Ctx = ();
|
||||
type DepState = ();
|
||||
|
||||
Reference in new issue
Block a user