Struct ResourceDictionary

pub struct ResourceDictionary(/* private fields */);

Expand description

A resource dictionary is a container that maps resource IDs to resources. A node can refer to resources by setting resource IDs to resource ID properties. You can set a resource dictionary to the node or to any of its parent nodes to define which resources the node uses. You can use a resource dictionary to group similar resources to logical entity, such as themes or locales, and change a resource dictionary of a node to change multiple resources at the same time.

Use Node::acquireResource to get the resource from the resource dictionary of a node or from the resource dictionaries of its parent nodes.

A resource dictionary can map resource IDs to resources in these ways:

Directly to a resource pointer
Indirectly to a resource with a resource URL

Use acquire and tryAcquire functions to get a mapped resource regardless of the way how a resource ID is mapped to a resource.

You can store nested resource dictionaries in a resource dictionary. When you are getting a resource from a resource dictionary and the resource dictionary cannot find the resource ID you specify, the resource dictionary looks for the resource ID recursively in the nested resource dictionaries.

In a resource dictionary you can store resources without mapping a resource ID to them. In Kanzi Engine such resources are called anonymous resources. You can get anonymous resources with beginAnonymousResources and endAnonymousResources.

§Examples

To create a resource dictionary:

To add content to a resource dictionary:

To get resources from a resource dictionary:

To change the resource dictionary of a node:

To extend the existing resource dictionary of a node:

Implementations§

§

impl ResourceDictionary

pub fn create( domain: &Domain, name: impl AsRef<KanziStr>, ) -> Result<ResourceDictionary, Error>

Creates a resource dictionary.

§Arguments

domain - The domain to which the resource dictionary belongs.
name - The name of the resource dictionary.

§Returns

The pointer to the resource dictionary.

§

impl ResourceDictionary

pub fn add_resource_id_url_mapping( &self, key: &ResourceId, url: impl AsRef<KanziStr>, ) -> Result<(), Error>

Adds a resource ID to a resource URL mapping to a resource dictionary.

§Arguments

key - The resource ID to add.
url - The URL that points to the resource to map to the resource ID.

pub fn add_resource_id_resource_mapping( &self, key: &ResourceId, resource: &Resource, ) -> Result<(), Error>

Adds a resource ID to a resource pointer mapping to a resource dictionary.

§Arguments

key - The resource ID to add.
resource - The resource pointer to map to the resource ID..

pub fn remove(&self, key: &ResourceId) -> Result<(), Error>

Removes a resource ID mapping from a resource dictionary.

§Arguments

key - The resource ID that you want to remove.

pub fn contains(&self, key: &ResourceId) -> Result<bool, Error>

Returns whether a resource dictionary contains a mapping for the resource ID that you pass to the function.

§Arguments

key - The resource ID for which you want to check whether there is a mapping in the resource dictionary.

§Returns

If the resource dictionary or a nested resource dictionary contains a mapping for the resource ID that you passed to the function, true, otherwise false.

pub fn find(&self, key: &ResourceId) -> Result<Option<KanziString>, Error>

Resolves the mapping from the resource ID that you pass to the function to the URL of the resource. This function ignores the direct resource ID to resource mappings.

§Arguments

key - The resource ID of the resource for which you want to get the URL.

§Returns

Dictionary or a nested resource dictionary contains a resource URL, a resource ID that you passed. If None is returned, no resource URL match provided resource ID.

pub fn iterate_urls(&self) -> Result<UrlsIterator, Error>

Returns an iterator pointing to the first element of the URL mappings container.

§Returns

An iterator pointing to the first element of the container.

pub fn get_urls(&self) -> Result<Vec<(ResourceId, KanziString)>, Error>

Returns a vector containing all URL mappings.

pub fn get_anonymous_resource_iterator( &self, ) -> Result<AnonymousResourceIterator, Error>

Returns an iterator pointing to the first element of the anonymous resources container.

§Returns

An iterator pointing to the first element of the anonymous resources container.

pub fn get_anonymous_resources(&self) -> Result<Vec<Weak<Resource>>, Error>

Returns a vector containing all anonymous resources of the anonymous resource container.

pub fn add_anonymous_resource(&self, resource: &Resource) -> Result<(), Error>

Adds an anonymous resource to a resource dictionary.

§Arguments

resource - The anonymous resource that you want to add to the resource dictionary.

pub fn remove_anonymous_resource( &self, resource: &Resource, ) -> Result<(), Error>

Removes an anonymous resource from the resource dictionary. If the resource does not exist in the resource dictionary, the function does not do anything.

§Arguments

resource - The anonymous resource you want to remove from the resource dictionary.

pub fn get_nested_dictionaries_reverse_iterator( &self, ) -> Result<NestedDictionariesReverseIterator, Error>

Returns a reverse iterator from the first element of the reversed nested resource dictionary container.

pub fn get_nested_dictionaries_reversed( &self, ) -> Result<Vec<Weak<ResourceDictionary>>, Error>

Returns a vector containing all nested dictionaried of the reversed nested dictionary container.

pub fn add(&self, resource_dictionary: &ResourceDictionary) -> Result<(), Error>

Adds a nested resource dictionary to a resource dictionary. You can add to multiple resource dictionaries the same resource dictionary as a nested resource dictionary. Do not form cycles with the nested resource dictionaries.

§Arguments

resource_dictionary - The nested resource dictionary that you want to add to the resource dictionary.

pub fn get_dictionary_count(&self) -> Result<u64, Error>

Gets the number of nested resource dictionaries in a resource dictionary.

§Returns

The number of nested resource dictionaries in the resource dictionary.

pub fn remove_dictionary(&self, index: u64) -> Result<(), Error>

Removes a nested resource dictionary from a resource dictionary.

§Arguments

index - The index of the nested resource dictionary that you want to remove.

§Errors

Returns an INDEX_OUT_OF_BOUNDS error if the index is out of bounds.

pub unsafe fn remove_dictionary_unchecked( &self, index: u64, ) -> Result<(), Error>

§Safety

The caller must ensure that index < self.get_dictionary_count().

pub fn find_dictionary( &self, name: impl AsRef<KanziStr>, ) -> Result<Option<Weak<ResourceDictionary>>, Error>

Searches for a nested dictionary with the specified name and returns a pointer to it.

§Arguments

name - The name of the dictionary to find.

§Returns

A child dictionary with the specified name. If None is returned, a dictionary with the specified name does not exist.

pub fn find_stored_resource( &self, key: &ResourceId, ) -> Result<Option<Weak<Resource>>, Error>

Finds an explicitly stored resource pointer from a dictionary. Does not try to acquire a resource from the resource manager. To acquire a resource, use ResourceDictionary::acquire.

§Arguments

key - The resource ID of the resource that you want to get.

§Returns

The resource to which the resource ID is mapped. If None is returned, no resources were mapped to provided resource ID.

pub fn acquire(&self, key: &ResourceId) -> Result<Resource, Error>

Gets from the resource dictionary the resource with the resource ID that you pass to the function. The function forwards the resource URL mappings to ResourceManager::acquire_resource.

§Arguments

key - The resource ID of the resource that you want to get.

§Returns

The resource to which the resource ID is mapped.

If the resource ID is mapped to a resource pointer, the function returns the resource pointer.
If the resource ID is mapped to a resource URL, the function uses the URL to query the resource from ResourceManager::acquireResource.
If the resource dictionary has nested resource dictionaries, the function forwards the query to the nested dictionaries: the last nested resource dictionary is searched first, and the first nested resource dictionary is searched last.
If the resource ID is not mapped to anything in this resource dictionary or any of the nested dictionaries, the function returns nullptr.

pub fn acquire_async( &self, key: &ResourceId, closure: impl AcquireFinishedCallback, ) -> Result<Option<ResourceAcquireTask>, Error>

Asynchronously acquires a resource. If the function cannot find a resource URL mapping, it does not launch an asynchronous task. Kanzi executes the callback only the next time when it executes callbacks, if there are no asynchronous task to launch.

§Arguments

key - The resource ID of the resource that you want to get.
func - The callback to execute when loading is complete.

§Returns

The launched asynchronous task.

pub fn merge( &self, preferred_dictionary: &ResourceDictionary, ) -> Result<(), Error>

Copies into this resource dictionary the contents of the resource dictionary that you pass to the function. The function adds to this resource dictionary:

Resource ID mappings
Pointers to the nested resource directories
Anonymous resources from the given resource directory

If there are duplicate values for the resource ID mappings, prefers the values from the resource directory that you pass to the function.

§Arguments

preferred_dictionary - The resource dictionary that you want to merge to this resource dictionary.

pub fn duplicate(&self) -> Result<ResourceDictionary, Error>

Duplicates a resource dictionary. When you duplicate a resource dictionary that contains nested resource dictionaries, the function creates a shallow copy: it copies the pointers to the nested resource dictionaries, not the contents of the nested resource dictionaries.

§Returns

The pointer to the duplicated resource dictionary.

Methods from Deref<Target = Resource>§

pub fn get_name(&self) -> Result<KanziString, Error>

Gets the resource name.

pub fn get_url(&self) -> Result<KanziString, Error>

Gets the resource URL. Note that the URL is not necessarily in URL form if resource has been just created.

§Returns

URL string.

pub fn set_keep_alive(&self, keep_alive: bool) -> Result<(), Error>

Sets the keep alive flag. Can be set only before the resource is registered to the resource manager. Normally set by loadFromKZB.

§Arguments

keep_alive - Value for the keep alive flag.

Methods from Deref<Target = Object>§

pub fn as_ptr(&self) -> *mut ObjectWrapper

pub fn as_wrapper(&self) -> &ObjectWrapper

pub fn as_object(&self) -> &Object

Represents any type inheriting from Object as &Object. This is useful for comparisions when PartialEq traits failed to compare objects of different types.

let child = screen.get_child(0)?;
let parent = child.get_parent()?.into_error(ErrorKind::ObjectNotFound)?;
// assert_eq!(screen, parent); // <- Fails to compile!
assert_eq!(screen.as_object(), parent.as_object());

pub fn get_native(&self) -> Result<NonNull<c_void>, Error>

Gets a pointer to the backing C++ instance.

pub fn is_stale(&self) -> bool

Checks whether the weak reference has expired.

pub fn get_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<<T as VariantConstraint>::RetArg, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers.

Base value is affected by the following inputs where the highest entry in the list determines the base value:

Local value set with setProperty or loaded from kzb
Value set by a style affecting the property.
Value defined by class metadata.

Modifiers are not applied, the highest-priority base value is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.

§Arguments

property_type - The property type identifying the property to retrieve.

§Returns

The evaluated property value.

pub fn get_optional_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<Option<<T as VariantConstraint>::RetArg>, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers, but does not default to the value in property metadata if there are no inputs to the property value.

If there is no value sources, None is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.