ResourceContext ResourceContext ResourceContext Class

Definition

Encapsulates all of the factors (ResourceQualifier s) that might affect resource selection.

public sealed class ResourceContext : IResourceContextpublic sealed class ResourceContext : IResourceContextPublic NotInheritable Class ResourceContext Implements IResourceContext
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Resources can be sensitive to scale, and different views owned by an app are able to display simultaneously on different display devices, which might use different scales. For that reason, a ResourceContext is generally associated with a specific view, and should be obtained using GetForCurrentView. (A view-independent ResourceContext can be obtained using GetForViewIndependentUse, but note that scale-dependent functionality will fail if invoked on a ResourceContext that is not associated with a view.)

Do not create an instance of ResourceContext using the constructor, as it is deprecated and subject to removal in a future release.

Except where otherwise noted, methods of this class can be called on any thread.

Examples

This example is based on scenario 13 of the Application resources and localization sample. See the sample for the more complete solution.

// Create a ResourceContext.
var resourceContext = new Windows.ApplicationModel.Resources.Core.ResourceContext.getForCurrentView().clone();

// Set the specific context for lookup of resources.
var qualifierValues = resourceContext.qualifierValues;
qualifierValues["language"] = "en-US";
qualifierValues["contrast"] = "standard";
qualifierValues["scale"] = "140";
qualifierValues["homeregion"] = "021"; // Northern America

// Resources actually reside within Scenario13 Resource Map.
var resourceIds = [
    '/Scenario13/languageOnly',
    '/Scenario13/scaleOnly',
    '/Scenario13/contrastOnly',
    '/Scenario13/homeregionOnly',
    '/Scenario13/multiDimensional',
];

var output = { str: "" };
resourceIds.forEach(function (resourceId) {
    renderNamedResource(resourceId, resourceContext, output);
});

function renderNamedResource(resourceId, resourceContext, output) {
    output.str += "Resource ID " + resourceId + ":\n";
    // Lookup the resource in the mainResourceMap (the one for this package).
    var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.current.mainResourceMap.lookup(resourceId);

    // Return a ResourceCandidateVectorView of all possible resources candidates
    // resolved against the context in order of appropriateness.
    var resourceCandidates = namedResource.resolveAll(resourceContext);

    resourceCandidates.forEach(function (candidate, index) {
        renderCandidate(candidate, index, output);
    });
    output.str += "\n";
}

function renderCandidate(candidate, index, output) {
    // Get all the various qualifiers for the candidate (such as language, scale, contrast).
    candidate.qualifiers.forEach(function (qualifier) {
        output.str += "qualifierName: " + qualifier.qualifierName + "\n";
        output.str += "qualifierValue: " + qualifier.qualifierValue + "\n";
        output.str += "isDefault: ";
        output.str += (qualifier.isDefault) ? "true\n" : "false\n";
        output.str += "isMatch: ";
        output.str += (qualifier.isMatch) ? "true\n" : "false\n";
        output.str += "score: " + qualifier.score + "\n";
        output.str += "\n";
    });
}

Constructors

ResourceContext() ResourceContext() ResourceContext()

Note

ResourceContext constructor may be altered or unavailable for releases after Windows 8.1. Instead, use GetForCurrentView.

Creates a cloned ResourceContext object.

public ResourceContext()public ResourceContext()Public Sub New()
Attributes

Remarks

In general, resources can be sensitive to scale. For that reason, a ResourceContext is generally associated with a specific view, and should be obtained using GetForCurrentView. (A view-independent ResourceContext can also be obtained using GetForViewIndependentUse.) If a ResourceContext is obtained using this constructor, it will be have scale associated with an arbitrary view. Do not make any assumptions in your app regarding this behavior.

Properties

Languages Languages Languages

Gets or sets the language qualifier for this context.

public IVectorView<string> Languages { get; set; }public IVectorView<string> Languages { get; set; }Public ReadWrite Property Languages As IVectorView<string>
Value

A collection of BCP-47 language tags.

Attributes

Remarks

The language qualifier is a list of valid BCP-47 tags. The default value for the language qualifier is drawn from the app-specific language setting and the user language profile.

The language qualifier value is represented as a string containing a semicolon-delimited list. The Languages property wraps it in a container for convenience.

See Also

QualifierValues QualifierValues QualifierValues

Gets a writable, observable map of all supported qualifiers, indexed by name.

public IObservableMap<string, string> QualifierValues { get; }public IObservableMap<string, string> QualifierValues { get; }Public ReadOnly Property QualifierValues As IObservableMap<string, string>
Value

The map of qualifiers. Here are the possible string qualifier names that you can map to string qualifier values. "Language"This qualifier name can be mapped to a string value that represents the language, such as, "en-us" for United States English."Contrast"This qualifier name can be mapped to one of these values:"standard""high""black""white""Scale"This qualifier name can be mapped to one of these values for scale of the display as a percentage:"80""100""120""125" (Windows 10 only)"140""150" (Windows 10 only)"160""175" (Windows 10 only)"180""200""225" (Windows 10 only)"250" (Windows 10 only)"300" (Windows 10 only)"350" (Windows 10 only)"400" (Windows 10 only)"450" (Windows 10 only)"DeviceFamily"This qualifier name can be mapped to a string value that represents the device family of the device that your app is currently running on, such as, "Desktop", "Mobile", and the names of the other device families. You can use the "DeviceFamily" qualifier name in your markup or Resource.resw filenames. For example, when your app is running on the mobile device family device family, the UI element <TextBlock x:Uid="DeviceFriendlyName"/> will use the text and foreground resources defined in your Resources.DeviceFamily-Mobile.resw file if it contains: <data name="DeviceFriendlyName.Foreground" xml:space="preserve"><value>Red</value></data><data name="DeviceFriendlyName.Text" xml:space="preserve"><value>Mobile device</value></data>."HomeRegion"This qualifier name can be mapped to a string value that represents the region, such as, "021" for North America."TargetSize"This qualifier name can be mapped to a string value that represents the size of the target, such as, "256"."LayoutDirection"This qualifier name can be mapped to one of these values:"LTR"Layout direction is left to right."RTL"Layout direction is right to left."TTBLTR"Layout direction is top to bottom and left to right."TTBRTL"Layout direction is top to bottom and right to left."Configuration"This qualifier name can be mapped to a string value that represents the configuration."AlternateForm"This qualifier name can be mapped to a string value that represents the alternate form."DXFeatureLevel"This qualifier name can be mapped to one of these values for the DirectX feature level:"DX9"Targets features supported by Direct3D 9.x."DX10"Targets features supported by Direct3D 10.x."DX11"Targets features supported by Direct3D 11.x.

Attributes

Methods

Clone() Clone() Clone()

Creates a clone of this ResourceContext, with identical qualifiers.

public ResourceContext Clone()public ResourceContext Clone()Public Function Clone() As ResourceContext
Returns
Attributes

Remarks

By default, a cloned context has the same qualifier values as the default context from which it was derived. If a qualifier value in the default context changes, the changes are reflected in the cloned context as well. However, if a qualifier value is programmatically overridden on the cloned context, the linkage to the default context for that qualifier is removed— changes to that qualifier value in the cloned context do not affect the default context, and vice versa. This linkage can be restored using the Reset method.

CreateMatchingContext(IIterable<ResourceQualifier>) CreateMatchingContext(IIterable<ResourceQualifier>) CreateMatchingContext(IIterable<ResourceQualifier>)

Note

CreateMatchingContext may be altered or unavailable for releases after Windows 8.1. Instead, use ResourceContext.GetForCurrentView.OverrideToMatch.

Creates a new ResourceContext that matches a supplied set of qualifiers.

public static ResourceContext CreateMatchingContext(IIterable<ResourceQualifier> result)public static ResourceContext CreateMatchingContext(IIterable<ResourceQualifier> result)Public Static Function CreateMatchingContext(result As IIterable<ResourceQualifier>) As ResourceContext
Parameters
result

The list of qualifiers to be matched.

Returns
Attributes

GetForCurrentView() GetForCurrentView() GetForCurrentView()

Gets a default ResourceContext associated with the current view for the currently running application.

public static ResourceContext GetForCurrentView()public static ResourceContext GetForCurrentView()Public Static Function GetForCurrentView() As ResourceContext
Returns

The default context associated with the current view.

Attributes

Remarks

This method fails if it is called in a windowless thread.

GetForViewIndependentUse() GetForViewIndependentUse() GetForViewIndependentUse()

Gets a default ResourceContext not associated with any view.

public static ResourceContext GetForViewIndependentUse()public static ResourceContext GetForViewIndependentUse()Public Static Function GetForViewIndependentUse() As ResourceContext
Returns

A default ResourceContext not associated with any view.

Attributes

Remarks

By default, no scale qualifier value is set in the ResourceContext returned by this method. Unless and until a scale qualifier value is set programmatically, the returned ResourceContext does not support any operations that involve the scale qualifier, including reading the scale qualifier value or resolving resource candidates that are qualified for scale.

This method fails if it is called in a windowless thread.

OverrideToMatch(IIterable<ResourceQualifier>) OverrideToMatch(IIterable<ResourceQualifier>) OverrideToMatch(IIterable<ResourceQualifier>)

Overrides the qualifier values supplied by this context to match a specified list of resolved ResourceQualifier s. Typically the resolved ResourceQualifier s are associated with a resource that was looked up earlier.

public void OverrideToMatch(IIterable<ResourceQualifier> result)public void OverrideToMatch(IIterable<ResourceQualifier> result)Public Function OverrideToMatch(result As IIterable<ResourceQualifier>) As void
Parameters
result

The ResourceQualifier s to be applied to the context.

Attributes

Reset() Reset() Reset()

Resets the overridden values for all qualifiers on the given ResourceContext instance.

public void Reset()public void Reset()Public Function Reset() As void
Attributes

Reset(IIterable<String>) Reset(IIterable<String>) Reset(IIterable<String>)

Resets the overridden values for the specified qualifiers on the given ResourceContext instance.

public void Reset(IIterable<String> qualifierNames)public void Reset(IIterable<String> qualifierNames)Public Function Reset(qualifierNames As IIterable<String>) As void
Parameters
qualifierNames

The names of the qualifiers to be reset.

Attributes

ResetGlobalQualifierValues() ResetGlobalQualifierValues() ResetGlobalQualifierValues()

Removes any qualifier overrides from default contexts of all views across the app.

public static void ResetGlobalQualifierValues()public static void ResetGlobalQualifierValues()Public Static Function ResetGlobalQualifierValues() As void
Attributes

ResetGlobalQualifierValues(IIterable<String>) ResetGlobalQualifierValues(IIterable<String>) ResetGlobalQualifierValues(IIterable<String>)

Removes qualifier overrides for the specified qualifiers from default contexts of all views across the app.

public static void ResetGlobalQualifierValues(IIterable<String> qualifierNames)public static void ResetGlobalQualifierValues(IIterable<String> qualifierNames)Public Static Function ResetGlobalQualifierValues(qualifierNames As IIterable<String>) As void
Parameters
qualifierNames

The names of the qualifiers to be reset.

Attributes

Remarks

This method fails with an exception if any of the qualifier names specified are invalid.

SetGlobalQualifierValue(String, String) SetGlobalQualifierValue(String, String) SetGlobalQualifierValue(String, String)

Applies a single qualifier value override to default contexts of all views for the current app.

public static void SetGlobalQualifierValue(String key, String value)public static void SetGlobalQualifierValue(String key, String value)Public Static Function SetGlobalQualifierValue(key As String, value As String) As void
Parameters
key
System.String System.String System.String

The name of the qualifier to override.

value
System.String System.String System.String

The override value to set.

Attributes

Remarks

This method fails with an exception if key or value are invalid.

SetGlobalQualifierValue(String, String, ResourceQualifierPersistence) SetGlobalQualifierValue(String, String, ResourceQualifierPersistence) SetGlobalQualifierValue(String, String, ResourceQualifierPersistence)

Applies a single qualifier value override to default contexts of all views for the current app, and specifies the persistence of the override.

public static void SetGlobalQualifierValue(String key, String value, ResourceQualifierPersistence persistence)public static void SetGlobalQualifierValue(String key, String value, ResourceQualifierPersistence persistence)Public Static Function SetGlobalQualifierValue(key As String, value As String, persistence As ResourceQualifierPersistence) As void
Parameters
key
System.String System.String System.String

The name of the qualifier to override.

value
System.String System.String System.String

The override value to set.

Attributes

Remarks

This method fails with an exception if key or value are invalid.

See Also