ResourceContext ResourceContext ResourceContext ResourceContext Class

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

Syntax

Declaration

public sealed class ResourceContextpublic sealed class ResourceContextPublic NotInheritable Class ResourceContext

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 summary

Note

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

Creates a cloned ResourceContext object.

Properties summary

Gets or sets the language qualifier for this context.

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

Methods summary

Creates a clone of this ResourceContext, with identical qualifiers.

Note

CreateMatchingContext may be altered or unavailable for releases after Windows 8.1. Instead, use OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier}).

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

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

Gets a default ResourceContext not associated with any view.

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.

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

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

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

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

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

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

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 Function ResourceContext() As

    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>

    Property Value

    • 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.

  • 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>

    Property 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.

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

    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(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    CreateMatchingContext(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    CreateMatchingContext(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    CreateMatchingContext(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    Note

    CreateMatchingContext may be altered or unavailable for releases after Windows 8.1. Instead, use OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier}).

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

    public static ResourceContext CreateMatchingContext(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier} result)public static ResourceContext CreateMatchingContext(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier} result)Public Static Function CreateMatchingContext(result As Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier}) As ResourceContext

    Parameters

    • result

      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

    Returns

    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

    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(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier})
    OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.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(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier} result)public void OverrideToMatch(Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier} result)Public Function OverrideToMatch(result As Windows.Foundation.Collections.IIterable{Windows.ApplicationModel.Resources.Core.ResourceQualifier}) As void

    Parameters

  • 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
  • Reset(Windows.Foundation.Collections.IIterable{System.String})
    Reset(Windows.Foundation.Collections.IIterable{System.String})
    Reset(Windows.Foundation.Collections.IIterable{System.String})
    Reset(Windows.Foundation.Collections.IIterable{System.String})

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

    public void Reset(Windows.Foundation.Collections.IIterable{System.String} qualifierNames)public void Reset(Windows.Foundation.Collections.IIterable{System.String} qualifierNames)Public Function Reset(qualifierNames As Windows.Foundation.Collections.IIterable{System.String}) As void

    Parameters

    • qualifierNames

      The names of the qualifiers to be reset.

  • 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
  • ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String})
    ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String})
    ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String})
    ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String})

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

    public static void ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String} qualifierNames)public static void ResetGlobalQualifierValues(Windows.Foundation.Collections.IIterable{System.String} qualifierNames)Public Static Function ResetGlobalQualifierValues(qualifierNames As Windows.Foundation.Collections.IIterable{System.String}) As void

    Parameters

    • qualifierNames

      The names of the qualifiers to be reset.

    Remarks

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

  • SetGlobalQualifierValue(System.String,System.String)
    SetGlobalQualifierValue(System.String,System.String)
    SetGlobalQualifierValue(System.String,System.String)
    SetGlobalQualifierValue(System.String,System.String)

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

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

    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.

    Remarks

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

  • SetGlobalQualifierValue(System.String,System.String,Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence)
    SetGlobalQualifierValue(System.String,System.String,Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence)
    SetGlobalQualifierValue(System.String,System.String,Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence)
    SetGlobalQualifierValue(System.String,System.String,Windows.ApplicationModel.Resources.Core.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(System.String key,System.String value,Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence persistence)public static void SetGlobalQualifierValue(System.String key,System.String value,Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence persistence)Public Static Function SetGlobalQualifierValue(key As System.String,value As System.String,persistence As Windows.ApplicationModel.Resources.Core.ResourceQualifierPersistence) As void

    Parameters

    Remarks

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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.ApplicationModel.Resources.Core.dll