RealTimeStylus.SetDesiredPacketDescription メソッド

2008-10-28

タブレットコンテキストで収集されるパケットのさまざまな面への、RealTimeStylus オブジェクトの関連を設定します。

名前空間 : Microsoft.StylusInput
アセンブリ : Microsoft.Ink (Microsoft.Ink.dll 内)

構文

'宣言
Public Sub SetDesiredPacketDescription ( _
    value As Guid() _
)
'使用
Dim instance As RealTimeStylus
Dim value As Guid()

instance.SetDesiredPacketDescription(value)

public void SetDesiredPacketDescription(
    Guid[] value
)

public:
void SetDesiredPacketDescription(
    array<Guid>^ value
)

public void SetDesiredPacketDescription(
    Guid[] value
)

public function SetDesiredPacketDescription(
    value : Guid[]
)

パラメータ

value
型 : array<System.Guid[]
RealTimeStylus オブジェクトが関連するパケットプロパティのグローバル一意識別子 (GUID) 。

解説

このメソッドを使用して、一連のパケットプロパティに RealTimeStylus オブジェクトの関連を設定します。パケットプロパティは GUID の配列によって表されます。PacketProperty オブジェクトは標準のパケットプロパティ GUID を定義しますが、他の GUID を使用することもできます。

RealTimeStylus オブジェクトが Tablet オブジェクトからインクを収集する場合、RealTimeStylus オブジェクトは、関連を設定していて (GetDesiredPacketDescription メソッドの戻り値として表されます)、インクを収集しているタブレットによってサポートされるパケットプロパティについてのみパケットデータを返します。RealTimeStylus オブジェクトを使用してインクを収集する方法の詳細については、「Accessing and Manipulating Stylus Input」を参照してください。

SetDesiredPacketDescription メソッドを呼び出すことができるのは、RealTimeStylus オブジェクトが無効なときだけです。ただし、SetDesiredPacketDescription メソッドの呼び出しは、GetDesiredPacketDescription メソッドの戻り値に直ちに反映されます。

RealTimeStylus オブジェクトがパケットプロパティ GUID を並べる方法を次に示します。

PacketProperty.X GUID と PacketProperty.Y GUID は、SetDesiredPacketDescription メソッドの前の呼び出しで指定されていたかどうかに関係なく、GetDesiredPacketDescription メソッドによって常に配列の最初の 2 つの位置で返されます。
PacketProperty.PacketStatus GUID が SetDesiredPacketDescription メソッドの呼び出しで指定されている場合、PacketProperty.PacketStatus GUID は GetDesiredPacketDescription メソッドによって常に配列の最後の位置で返されます。
SetDesiredPacketDescription メソッドの呼び出しで複数回指定されている GUID があっても、各 GUID は GetDesiredPacketDescription メソッドによって返される配列に 1 回しか出現しません。
既定では、GetDesiredPacketDescription メソッドは PacketProperty.X、PacketProperty.Y、および PacketProperty.NormalPressure GUID を返します。

たとえば、SetDesiredPacketDescription メソッドで (a, b, a, PacketStatus, b, c, d) を指定して呼び出すと、GetDesiredPacketDescription メソッド呼び出しは (X, Y, a, b, c, d, PacketStatus) を返します。

このメソッドは、次の条件において例外をスローします。

RealTimeStylus オブジェクトが破棄されている。
RealTimeStylus オブジェクトが RealTimeStylus() コンストラクタで作成された。
RealTimeStylus オブジェクトが有効である。
value パラメータが nullnull 参照 (Visual Basic では Nothing) (Visual Basic .NET の場合は Nothing) か、空の配列が含まれる。

例

この Microsoft Visual C# .NET の例は、メニュー項目の Click イベントハンドラのスニペットです。このメニューは、TextBox オブジェクト theTextBox が定義されているフォームの一部です。RealTimeStylus オブジェクトが有効な場合、またはフォーム上でチェックされるパケットプロパティ GUID がない場合、イベントハンドラは終了します。それ以外の場合、イベントハンドラは RealTimeStylus オブジェクトの SetDesiredPacketDescription メソッドを呼び出します。

using Microsoft.Ink;
using Microsoft.StylusInput;
using Microsoft.StylusInput.PluginData;

// ...

// Declare the RealTimeStylus objects, the GestureRecognizer plugin,
// and the DynamicRenderer plug-in.
private Microsoft.StylusInput.RealTimeStylus thePrimaryRealTimeStylus = null;
private Microsoft.StylusInput.RealTimeStylus theSecondaryRealTimeStylus = null;
private Microsoft.StylusInput.GestureRecognizer theGestureRecognizer = null;
private Microsoft.StylusInput.DynamicRenderer theDynamicRenderer = null;

// ...

// The SetDesiredPacketDescription menu item's Click event handler
private void theMenuItemSetDesiredPacketDescription_Click(object sender,
    System.EventArgs e)
{
    // Can not call this method while the RealTimeStylus is enabled.
    if (this.thePrimaryRealTimeStylus.Enabled)
    {
        MessageBox.Show("The SetDesiredPacketDescription method of the RealTimeStylus can only be called while the RealTimeStylus is disabled.");
        return;
    }

    // Create an array of GUIDs from the checked packet properties.
    ArrayList result = new ArrayList();

    // ...

    // Can not pass an empty array to the SetDesiredPacketDescription method.
    if (0 == result.Count)
    {
        this.theTextBox.Text = "No PacketProperty GUID's checked. The desired packet property's of the RealTimeStylus have not been changed.";
        return;
    }

    // Set the desired packet properties.
    Guid[] theGuids = (Guid[])result.ToArray(typeof(Guid));
    this.thePrimaryRealTimeStylus.SetDesiredPacketDescription(theGuids);
    this.theTextBox.Text = "The desired packet property's of the RealTimeStylus have been changed.";
}