ResourceContext ResourceContext ResourceContext ResourceContext Class

Definition

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

public sealed class ResourceContextpublic sealed class ResourceContextPublic NotInheritable Class ResourceContextpublic sealed class ResourceContext
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() 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 New()Public Sub New()public ResourceContext()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 @Windows.ApplicationModel.Resources.Core.ResourceContext.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 IVectorView<string> Languages { get; set; }Public ReadWrite Property Languages As IVectorView<string>public IVectorView<string> Languages { get; set; }
Value

A collection of BCP-47 language tags.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

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>public IObservableMap<string, string> QualifierValues { get; }
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
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Methods

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

Creates a clone of this ResourceContext, with identical qualifiers.

public ResourceContext Clone()public ResourceContext Clone()Public Function Clone() As ResourceContextpublic ResourceContext Clone()
Returns
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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

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 ResourceContextpublic static ResourceContext CreateMatchingContext(IIterable<ResourceQualifier> result)
Parameters
result

The list of qualifiers to be matched.

Returns
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 ResourceContextpublic static ResourceContext GetForCurrentView()
Returns

The default context associated with the current view.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 ResourceContextpublic static ResourceContext GetForViewIndependentUse()
Returns
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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(IIterable<ResourceQualifier> result)Public Function OverrideToMatch(result As IIterable<ResourceQualifier>) As voidpublic void OverrideToMatch(IIterable<ResourceQualifier> result)
Parameters
result

The ResourceQualifier s to be applied to the context.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 voidpublic void Reset()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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<String> qualifierNames)public void Reset(IIterable<String> qualifierNames)Public Function Reset(qualifierNames As IIterable<String>) As voidpublic void Reset(IIterable<String> qualifierNames)
Parameters
qualifierNames

The names of the qualifiers to be reset.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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 voidpublic static void ResetGlobalQualifierValues()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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<String> qualifierNames)public static void ResetGlobalQualifierValues(IIterable<String> qualifierNames)Public Static Function ResetGlobalQualifierValues(qualifierNames As IIterable<String>) As voidpublic static void ResetGlobalQualifierValues(IIterable<String> qualifierNames)
Parameters
qualifierNames

The names of the qualifiers to be reset.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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) 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 voidpublic static void SetGlobalQualifierValue(String key, String value)
Parameters
key
System.String System.String System.String System.String

The name of the qualifier to override.

value
System.String System.String System.String System.String

The override value to set.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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) 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 voidpublic static void SetGlobalQualifierValue(String key, String value, ResourceQualifierPersistence persistence)
Parameters
key
System.String System.String System.String System.String

The name of the qualifier to override.

value
System.String System.String System.String System.String

The override value to set.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

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