Resource​Context Resource​Context Resource​Context Resource​Context 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// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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";
    });
}

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.

Constructors

ResourceContext() 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()// You can use this method in JavaScript.

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 Languages

Gets or sets the language qualifier for this context.

public : IVectorView<string> Languages { get; set; }public IReadOnlyList<string> Languages { get; set; }Public ReadWrite Property Languages As IReadOnlyList<string>// You can use this property in JavaScript.
Value
IVectorView<PlatForm::String> IReadOnlyList<string> IReadOnlyList<string> IReadOnlyList<string>

A collection of BCP-47 language tags.

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 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>// You can use this property in JavaScript.
Value
IObservableMap<PlatForm::String, PlatForm::String> IObservableMap<string, string> IObservableMap<string, string> IObservableMap<string, string>

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.

Methods

Clone() Clone() Clone() Clone()

Creates a clone of this ResourceContext, with identical qualifiers.

public : ResourceContext Clone()public ResourceContext Clone()Public Function Clone() As ResourceContext// You can use this method in JavaScript.
Returns

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>) 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(IEnumerable<ResourceQualifier> result)Public Static Function CreateMatchingContext(result As IEnumerable<ResourceQualifier>) As ResourceContext// You can use this method in JavaScript.
Parameters
result
IIterable<ResourceQualifier> IEnumerable<ResourceQualifier> IEnumerable<ResourceQualifier> IEnumerable<ResourceQualifier>

The list of qualifiers to be matched.

Returns

GetForCurrentView() 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// You can use this method in JavaScript.
Returns

The default context associated with the current view.

Remarks

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

GetForViewIndependentUse() 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// You can use this method in JavaScript.
Returns

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>) 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(IEnumerable<ResourceQualifier> result)Public Function OverrideToMatch(result As IEnumerable<ResourceQualifier>) As void// You can use this method in JavaScript.
Parameters
result
IIterable<ResourceQualifier> IEnumerable<ResourceQualifier> IEnumerable<ResourceQualifier> IEnumerable<ResourceQualifier>

The ResourceQualifier s to be applied to the context.

Reset() 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// You can use this method in JavaScript.
See Also

Reset(IIterable<String>) 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<PlatForm::String> qualifierNames)public void Reset(IEnumerable<String> qualifierNames)Public Function Reset(qualifierNames As IEnumerable<String>) As void// You can use this method in JavaScript.
Parameters
qualifierNames
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

The names of the qualifiers to be reset.

See Also

ResetGlobalQualifierValues() 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// You can use this method in JavaScript.
See Also

ResetGlobalQualifierValues(IIterable<String>) 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<PlatForm::String> qualifierNames)public static void ResetGlobalQualifierValues(IEnumerable<String> qualifierNames)Public Static Function ResetGlobalQualifierValues(qualifierNames As IEnumerable<String>) As void// You can use this method in JavaScript.
Parameters
qualifierNames
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

The names of the qualifiers to be reset.

Remarks

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

See Also

SetGlobalQualifierValue(String, String) 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(PlatForm::String key, PlatForm::String value)public static void SetGlobalQualifierValue(String key, String value)Public Static Function SetGlobalQualifierValue(key As String, value As String) As void// You can use this method in JavaScript.
Parameters
key
PlatForm::String String String String

The name of the qualifier to override.

value
PlatForm::String String String String

The override value to set.

Remarks

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

See Also

SetGlobalQualifierValue(String, String, ResourceQualifierPersistence) 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(PlatForm::String key, PlatForm::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// You can use this method in JavaScript.
Parameters
key
PlatForm::String String String String

The name of the qualifier to override.

value
PlatForm::String String String String

The override value to set.

Remarks

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

See Also

See Also