Struct kas_core::WidgetId

pub struct WidgetId(_);

Widget identifier

All widgets are assigned an identifier which is unique within the window. This type may be tested for equality and order and may be iterated over as a “path” of “key” values.

Formatting a WidgetId via Display prints the the path, for example #1290a4. Here, # represents the root; each following hexadecimal digit represents a path component except that digits 8-f are combined with the following digit(s). Hence, the above path has components 1, 2, 90, a4. To interpret these values, first subtract 8 from each digit but the last digit, then read as base-8: [1, 2, 8, 20].

This type is small (64-bit) and non-zero: Option<WidgetId> has the same size as WidgetId. It is also very cheap to Clone: usually only one if check, and in the worst case a pointer dereference and ref-count increment. Paths up to 14 digits long (as printed) are represented internally; beyond this limit a reference-counted stack allocation is used.

WidgetId is neither Send nor Sync.

Identifiers are assigned when configured and when re-configured (via TkAction::RECONFIGURE or ConfigMgr::configure). In most cases values are persistent but this is not guaranteed (e.g. inserting or removing a child from a List widget will affect the identifiers of all following children). View-widgets assign path components based on the data key, thus possibly making identifiers persistent.

Implementations

impl WidgetId

pub fn is_valid(&self) -> bool

Is the identifier valid?

Default-constructed identifiers are invalid. Comparing invalid ids is considered a logic error and thus will panic in debug builds. This method may be used to check an identifier’s validity.

pub fn iter(&self) -> WidgetPathIter<'_>

Iterate over path components

pub fn is_ancestor_of(&self, id: &Self) -> bool

Returns true if self equals id or if id is a descendant of self

pub fn iter_keys_after(&self, id: &Self) -> WidgetPathIter<'_>

pub fn next_key_after(&self, id: &Self) -> Option<usize>

Get first key in path of self path after id

If the path of self starts with the path of id (id.is_ancestor_of(self)) then this returns the next key in self’s path (if any). Otherwise, this returns None.

pub fn parent(&self) -> Option<WidgetId>

Get the parent widget’s identifier, if not root

Note: there is no guarantee that Self::as_u64 on the result will match that of the original parent identifier.

pub fn make_child(&self, key: usize) -> Self

Make an identifier for the child with the given key

Note: this is not a getter method. Calling multiple times with the same key may or may not return the same value!

pub fn as_u64(&self) -> u64

Convert to a u64

This value should not be interpreted, except as follows:

• it is guaranteed non-zero
• it may be passed to Self::opt_from_u64
• comparing two u64 values generated this way will mostly work as an equality check of the source WidgetId, but can return false negatives (only if each id was generated through separate calls to Self::make_child)

pub fn opt_to_u64(id: Option<&WidgetId>) -> u64

Convert Option<WidgetId> to u64

This value should not be interpreted, except as follows:

• it is zero if and only if id == None
• it may be passed to Self::opt_from_u64
• comparing two u64 values generated this way will mostly work as an equality check of the source WidgetId, but can return false negatives (only if each id was generated through separate calls to Self::make_child)

pub unsafe fn opt_from_u64(n: u64) -> Option<WidgetId>

Convert u64 to Option<WidgetId>

Returns None if and only if n == 0.

Safety

This may only be called with the output of Self::as_u64, Self::opt_from_u64, or 0.

This is unsafe since Self has a heap-allocated variant. If n looks like a heap-allocated variant but is not the result of Self::as_u64, or it is but the source instance of Self and all clones have been destroyed, then some operations on the result of this method will attempt to dereference an invalid pointer.

pub fn iter_path(&self) -> impl Iterator<Item = usize> + '_

Construct an iterator, returning indices

This represents the widget’s “path” from the root (window).

Trait Implementations

impl Clone for WidgetId

fn clone(&self) -> WidgetId

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WidgetId

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for WidgetId

fn default() -> Self

Returns the “default value” for a type.

impl Display for WidgetId

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Hash for WidgetId

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,

Feeds a slice of this type into the given Hasher.

impl Ord for WidgetId

fn cmp(&self, rhs: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: PartialOrd<Self>,

Restrict a value to a certain interval.

impl<'a> PartialEq<&'a Option<WidgetId>> for WidgetId

fn eq(&self, rhs: &&Option<WidgetId>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq<&'a WidgetId> for WidgetId

fn eq(&self, rhs: &&WidgetId) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq<Option<&'a WidgetId>> for WidgetId

fn eq(&self, rhs: &Option<&'a WidgetId>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Option<WidgetId>> for WidgetId

fn eq(&self, rhs: &Option<WidgetId>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<WidgetId> for WidgetId

fn eq(&self, rhs: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<WidgetId> for WidgetId

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for WidgetId