IXRGradientStopCollection (Compact 2013)

Article
04/19/2017

3/28/2014

This class represents a collection of IXRGradientStop objects that can be accessed individually by index.

Syntax

class IXRGradientStopCollection : public IXRDependencyObject

Inheritance Hierarchy

IXRDependencyObject

IXRGradientStopCollection

Methods

Method	Description
IXRGradientStopCollection::Add	Adds an item to the end of this collection and retrieves the index of where it was added.
IXRGradientStopCollection::Clear	Removes all items from this collection.
IXRGradientStopCollection::Contains	Determines whether an item is in this collection.
IXRGradientStopCollection::GetCount	Retrieves the number of items in this collection.
IXRGradientStopCollection::GetItem	Retrieves the item at the specified index in this collection.
IXRGradientStopCollection::IndexOf	Searches for the specified item and retrieves the zero-based index of its occurrence within this collection.
IXRGradientStopCollection::Insert	Inserts an item into this collection at the location that has the specified index value.
IXRGradientStopCollection::Remove	Removes a specific item from this collection.
IXRGradientStopCollection::RemoveAt	Removes the item at the specified index from this collection.

Thread Safety

Members of this class are thread safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true. Allowing multiple-thread access can have a significant impact on application performance because this option serializes data for all objects in the collection across threads. If you have control over the lifetimes of these objects, it is recommended that you serialize only what is needed to achieve optimal performance.

Remarks

The IXRGradientStop information stored by IXRGradientBrush classes in the IXRGradientStopCollection describes the set of coordinates along an axis where the blend effect between two colors ends. This information determines the visual appearance of the blend effect achieved with a specific IXRGradientBrush.

You can obtain a pointer to this collection by calling IXRGradientBrush::GetGradientStops. Then, you can use the methods of this class to add, remove, or retrieve items. You can also clear the complete collection by calling the IXRGradientStopCollection::Clear method.

When you create a class instance, use an IXRGradientStopCollectionPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

To create a new collection, use the IXRApplication::CreateObject(IID,Object) method to create an empty IXRGradientStopCollection object. Then, use CreateObject to create multiple IXRGradientStop objects that each define the location and color of a transition point for a blend effect. Next, add each IXRGradientStop object to the IXRGradientStopCollection collection by calling the IXRGradientStopCollection::Add method. Finally, set the new collection for an IXRGradientBrush by calling IXRGradientBrush::SetGradientStops.

You can also define a gradient-stop collection in Microsoft Silverlight 3 XAML. For information about the differences between XAML in XAML for Windows Embedded and Silverlight 3, see Differences Between Microsoft Silverlight 3 and XAML for Windows Embedded. For more information about how to define this collection in the source XAML for your application, see the GradientBrush.GradientStops Property on MSDN.

Example

The following code example shows how to create an IXRGradientStopCollection that defines a simple gradient from red to blue, set it as the value of an IXRLinearGradientBrush, and set it to the background of a canvas in the visual tree.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

#include <windows.h>
#include <XamlRuntime.h>
#include <XRPtr.h>


void DefineGradientBrush(IXRApplication* pApplication, IXRFrameworkElement* pRootElement, IXRLinearGradientBrush* pMyBrush)
{
  // Create two gradient stops for red and blue color values
  IXRGradientStopPtr pRedGradientStop;
  IXRGradientStopPtr pBlueGradientStop;

  pApplication->CreateObject(IID_IXRGradientStop, &pRedGradientStop);
  pApplication->CreateObject(IID_IXRGradientStop, &pBlueGradientStop);

  COLORREF Red  = RGB(255,0,0);
  COLORREF Blue = RGB(0,0,255);

  float redOffset = 0;
  float blueOffset = 1;

  pRedGradientStop->SetColor(Red);
  pRedGradientStop->SetOffset(redOffset);

  pBlueGradientStop->SetColor(Blue);
  pBlueGradientStop->SetOffset(blueOffset);

  // Create a collection that stores both new gradient stops
  IXRGradientStopCollection* pRBgradient;
  int indexRed;
  int indexBlue;
  pApplication->CreateObject(&pRBgradient);

  pRBgradient->Add(pRedGradientStop, &indexRed);
  pRBgradient->Add(pBlueGradientStop, &indexBlue);

  // Add the collection to the provided linear-gradient brush
  
  pApplication->CreateObject(&pMyBrush);

  pMyBrush->SetGradientStops(pRBgradient);

  // Paint the background of a canvas in the visual tree with the new brush
  IXRCanvasPtr pCanvas;
  pRootElement->FindName(L"MyCanvas", &pCanvas);
  pCanvas->SetBackground(pMyBrush);
}

To run the previous code example, you must have already created an application instance, parsed the XAML markup into an element tree, and obtained a pointer (pVisualHost) to the visual host. For more information on the programming elements used in this example, see IXRApplication, IXRButton, IXRVisualHost, and IXRCanvas.

.NET Framework Equivalent

System.Windows.Media.GradientStopCollection

Requirements

Header	XamlRuntime.h
sysgen	SYSGEN_XAML_RUNTIME