ResourceContext 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// 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, which you use to map a qualifier name to a qualifier value. The qualifier value returned represents the current setting. Here is a reference table of all the possible qualifier values that can be returned. See How to name resources by using qualifiers for an explanation of the general concept of qualifiers, how to use them, and the purpose of each of the qualifier names.

Qualifier name Qualifier values
alternateform, or altform A string, between 1 and 16 chars in length, representing an alternate form of a resource.
configuration, or config A string. Matches the value of the MS_CONFIGURATION_ATTRIBUTE_VALUE environment variable. It’s unlikely that you’ll need to use this qualifier name (see the Configuration section of How to name resources by using qualifiers).
contrast Either standard (the default; matches high contrast off), high (matches any high contrast setting), black (matches High Contrast Black, High Contrast #1, and High Contrast #2), or white (matches High Contrast White).
custom A custom value.
devicefamily It’s unlikely that you’ll need to use this qualifier name (see the DeviceFamily section of How to name resources by using qualifiers). If you do need to use it, then execute ResourceContext.GetForCurrentView().QualifierValues["devicefamily"] on each of the devices that you want to support and name your resources for the values that are returned.
dxfeaturelevel, or dxfl Either DX9, DX10, DX11, or DX12. It’s unlikely that you’ll need to use this qualifier name (see the DXFeatureLevel section of How to name resources by using qualifiers).
homeregion Any valid BCP-47 region tag (such as us, or 840). That is, any ISO 3166-1 alpha-2 two-letter region code, plus the set of ISO 3166-1 numeric three-digit geographic codes for composed regions (see United Nations Statistic Division M49 composition of region codes). Matches the country or region setting.
language, or lang Any valid BCP-47 language tag (such as en, or en-us). Matches the display language setting. For a list of languages, see the IANA language subtag registry.
layoutdirection, or layoutdir Either LTR (left-to-right), RTL (right-to-left), TTBLTR (top-to-bottom, left-to-right), or TTBRTL (top-to-bottom, right-to-left). Matches the layout direction of the display language setting.
scale Either 80, 100 (default), 120, 125, 140, 150, 160, 175, 180, 200, 225, 250, 300, 350, 400, or 450. Matches the display scale setting. The values 125, 150, 175, 225, 250, 300, 350, 400, and 450 were introduced in Windows 10.
targetsize A positive integer that represents the side length of a square image in raw (physical) pixels. Matches the View setting in File Explorer.
theme Either dark or light. Matches the default or overridden app mode setting.

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) CreateMatchingContext(IIterable) CreateMatchingContext(IIterable) CreateMatchingContext(IIterable)

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) OverrideToMatch(IIterable) OverrideToMatch(IIterable) OverrideToMatch(IIterable)

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) Reset(IIterable) Reset(IIterable) Reset(IIterable)

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) ResetGlobalQualifierValues(IIterable) ResetGlobalQualifierValues(IIterable) ResetGlobalQualifierValues(IIterable)

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