Kanzi Studio ウィンドウプラグインの作成¶

Kanzi Studio プラグインは Kanzi Studio の機能を拡張し、Kanzi Studio で実行されます。

たとえば、Kanzi Studio の機能を拡張して、次のことができます:

Kanzi Studio で手動で行うと時間がかかる、またはエラーが発生しやすいタスクを自動化します。
Kanzi Studio からコンテンツをインポートおよびエクスポートし、Kanzi Studio がサポートしていない形式のローカライゼーションテーブルなどを使用します。
Kanzi Studio でのプロジェクト作業をサポートするビジュアライゼーションツールなど、詳細を抽象化しワークフローをスピードアップするエディターを作成します。

Kanzi Studio プラグインを次のいずれかの方法で提示できます。

プラグインユーザーインターフェースを含む Kanzi Studio ウィンドウ内で。
ユーザーが Kanzi Studio メインメニューまたはコンテキストメニューから実行できるコマンドとして、ユーザーインターフェースなしでプラグインを実行します。

このトピックでは、Kanzi Studio ウィンドウプラグインの作成方法について説明します。Kanzi Studio コマンドプラグインの作成方法については、Kanzi Studio コマンドプラグインの作成を参照してください。

Kanzi Studio ウィンドウプラグインを作成するためのデフォルトのUIフレームワークはWPFです。しかし、WPFのWebブラウザコントロールを使用してHTML上で動作するフレームワークを使用したり、WPFのHwndHostコントロールを使用してWin32ウィンドウをWPFコンテンツの要素として埋め込むことで、他のフレームワークを使用することもできます。

Kanzi Studio プラグインAPIは、.NETフレームワークアセンブリとして提供されます。<KanziInstallation>/Studio/Bin/PluginInterface.dll で見つけることができます。Kanzi Studio プラグインAPIは、Kanzi Studio のデータとコマンドへのアクセスを提供します。異なるバージョンの Kanzi Studio で Kanzi Studio プラグインを使用したい場合は、そのプラグインを使用したい各バージョンの Kanzi Studio から PluginInterface.dll を使用してプラグインをビルドしてください。

Kanzi Studio ウィンドウプラグインを開発するには、

Kanzi Studio ウィンドウプラグインのベースを作成します。Kanzi Studio ウィンドウプラグインのベースを作成するを参照してください。
Kanzi Studio プラグインをビルドして実行します。Kanzi Studio プラグインのビルドと実行を参照してください。
Kanzi Studio プラグインに機能を追加します。Kanzi Studio ウィンドウプラグインに機能を追加するを参照してください。
Kanzi Studio ウィンドウプラグインでのプロジェクトの変更をグループ化して、元に戻すややり直しを行います。Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化するを参照してください。
Kanzi Studio プラグインをデバッグします。Kanzi Studio プラグインのデバッグを参照してください。

Kanzi Studio プラグイン API の詳細情報については、次を参照してください。

Kanzi Studio ウィンドウプラグインのベースを作成する¶

Kanzi Studio ウィンドウプラグインは、Kanzi Studio ウィンドウで使用し、ユーザーインターフェースを持つプラグインです。たとえば、ウィンドウプラグインを使用してエディターを作成したり、プロジェクト内のコンテンツを視覚化したりします。

ここでは、Kanzi Studio ウィンドウプラグインの基盤を作成し、その後 Kanzi Studio の機能を拡張する機能を追加します。

Kanzi Studio ウィンドウプラグインを作成するには：

Visual Studioで、File > New > Projectを選択し、Visual C# Class Libraryを作成します。
ソリューションエクスプローラーでプロジェクト名を右クリックし、追加 > 参照を選択し、次のファイルへの参照を追加します:
1. アセンブリを選択 > .NET Framework をターゲットとするフレームワークを選択し、次の参照を追加します:
  - System.ComponentModel.Composition
  - System.XAML
2. Browse... をクリックし、<KanziInstallation>/Studio/Bin/PluginInterface.dll ファイルへの参照を追加します。
Solution Explorer でプロジェクト名を右クリックし、Properties を選択し、次の操作を行います。
- Application タブで、Target framework を .NET Framework 4.8 に設定します。
- Build タブで Platform target を x64 に設定します。
ソリューションエクスプローラーでプロジェクト名を右クリックし、[追加] > [ユーザーコントロール] を選択して、ユーザーコントロール (WPF) アイテムを追加します。
UserControl1.xaml.cs ファイルを開き、Kanzi Studio プラグイン API の using ディレクティブを追加します。
```
using Rightware.Kanzi.Studio.PluginInterface;
```
UserControl1 クラスを PluginWindow インターフェースを実装するように設定します。
1. 以下の文字列を見つけます。
```
public partial class UserControl1 : UserControl
```
  終点
```
public partial class UserControl1 : UserControl, PluginWindow
```
2. PluginWindow インターフェースを実装します。
  
  例えば、PluginWindow にカーソルを合わせ、をクリックし、インターフェイスを実装を選択します。
3. KanziStudio インターフェースを UserControl1 クラスに追加します。KanziStudio インターフェースは、Kanzi Studio プラグイン API を操作するためのエントリーポイントです。
```
private KanziStudio studio;
```
すべての関数で、この行を実行したいコードに置き換えてください。
```
throw new NotImplementedException();
```
プラグインがすべての内部例外を処理し、それらが Kanzi Studio インターフェースに到達しないようにしてください。

たとえば、UserControl1 クラスで関数を設定します。
- UserControl1 に studio パラメータを追加します。これにより、UserControl1 をインスタンス化し、studio を Class1.cs ファイルの引数として提供することができます。
```
public UserControl1(KanziStudio studio)
{
    this.studio = studio;
    InitializeComponent();
}
```
- Icon 関数を使用して、プラグインウィンドウの左上隅に表示されるプラグインウィンドウアイコンを設定します。
  - Kanzi Studio のデフォルトプラグインアイコンを使用するには、空の文字列を返します。
```
public string Icon
{
    get
    {
        return "";
    }
}
```
- SerializeState 関数を使用して、プラグインウィンドウの状態を保存します。プラグインウィンドウを閉じると、Kanzi Studio がこの関数を呼び出します。プラグインウィンドウを再度開くと、Kanzi Studio がプラグインウィンドウを作成する際に同じ状態をパラメータとして渡します。
  
  null に設定すると、Kanzi Studio はウィンドウの状態を記憶しません。
```
public PluginWindowState SerializeState()
{
    return null;
}
```
- Title 関数を使用して、プラグインウィンドウのタイトルとして表示したいテキストを設定します。例えば、次のように設定します:
```
public string Title
{
    get
    {
        return "Plugin title";
    }
}
```
- Dispose 関数を使用して、プラグインウィンドウを閉じる際にクリーンアップを行います。例えば、ここでプラグインで使用しているすべてのリソースを解放し、プラグインがイベントにサブスクライブしている場合は、ここでそれらのイベントのサブスクライブを解除します。ユーザーがプラグインウィンドウを閉じると、Kanzi Studio がこの関数を呼び出します。
  
  この例ではクリーンアップするものがないため、この関数を空のままにしておくことができます。
Class1.cs ファイルを開き、System.ComponentModel.Composition と Kanzi Studio プラグイン API の using ディレクティブを追加します。
```
using System.ComponentModel.Composition;
using Rightware.Kanzi.Studio.PluginInterface;
```
Class1 クラスを PluginWindowFactory インターフェースを実装するように設定し、Class1 クラスで実装します。Kanzi はこのクラスを使用してプラグインを作成します。Kanzi Studio は最初にファクトリを取得し、プラグインの名前、ウィンドウのサイズ、プラグインにウィンドウがあるかどうか、そして Kanzi Studio からユーザーがプラグインを起動できる場所を定義します。
1. 以下の文字列を見つけます。
```
public class Class1
```
  終点
```
public class Class1 : PluginWindowFactory
```
2. PluginWindowFactory インターフェースを実装します。
  
  例えば、PluginWindowFactory にカーソルを合わせ、をクリックし、インターフェイスを実装を選択します。
プラグインを作成するクラスの定義の前に、PluginWindowFactory インターフェースを実装するファクトリークラスを Kanzi Studio のプラグインコンテンツとしてマークします。これにより、Kanzi Studio は .dll がプラグインであることを認識します。
```
[Export(typeof(PluginContent))]
```
すべての関数で、この行を実行したいコードに置き換えてください。
```
throw new NotImplementedException();
```
プラグインがすべての内部例外を処理し、それらが Kanzi Studio インターフェースに到達しないようにしてください。

たとえば、Class1 クラスの関数を次のように設定します。
- CreateWindow 関数を使用して UserControl1 をインスタンス化し、studio を引数として渡します。UserControl1.xaml.cs ファイルの UserControl1 に studio パラメータを追加しました。
```
public PluginWindow CreateWindow(PluginWindowState state)
{
    return new UserControl1(studio);
}
```
- DefaultHeight 関数と DefaultWidth 関数を使用して、プラグインのウィンドウの高さと幅を設定します。例えば、400x400ピクセルのプラグインウィンドウを作成するには、次のようにします。
```
get
{
    return 400;
}
```
- CanExecute 関数を使用して、ユーザーがプラグインを起動できるかどうか、またどこでプラグインを起動できるかを設定します。
  - false に設定すると、Kanzi Studio はメインメニューとコンテキストメニューにプラグインを表示しますが、ユーザーはプラグインを起動できません。
  - true に設定すると、ユーザーはプラグインを起動できます。
  Kanzi Studio は、プラグインに KanziStudio オブジェクトを提供します。KanziStudio オブジェクトはデータアクセスのルートオブジェクトであり、現在のプロジェクト、利用可能なコマンド、グローバルなアンドゥとリドゥ、プロジェクトのオープンとクローズに関連するイベントを提供します。
  
  例えば、Kanzi Studio プロジェクトが開いているときにのみコマンドを有効にするには、これを使用します。
```
private KanziStudio studio;
public bool CanExecute(PluginCommandParameter parameter)
{
    return this.studio != null && this.studio.ActiveProject != null;
}
```
- CommandPlacement 関数を使用して、プラグインのメニュー名を設定し、プラグインを起動するコマンドを表示したい場所を指定します。
  - プラグインをメインメニューに表示するには、ContextMenuPlacement.NONE を使用します。
  - ノードやリソースから呼び出されるコンテキストメニュー、およびメインメニューにプラグインを表示するには、ContextMenuPlacement.PROJECT_ITEM を使用します。
```
public CommandPlacement CommandPlacement
{
    get
    {
        return new CommandPlacement("myPluginMenu", ContextMenuPlacement.NONE, false, null);
    }
}
```
- PluginContent.Description 関数を使用して、Kanzi Studio プラグインが何をするのかの簡単な説明を設定します。Kanzi Studio は、ユーザーがメニュー内のプラグイン名にマウスポインタを重ねたときに、この説明をツールチップとして表示します。
```
public string Description
{
    get
    {
        return "A tooltip with short description of what the plugin does.";
    }
}
```
- PluginContent.DisplayName 関数を使用して、プラグインを起動できる Kanzi Studio メニューにプラグイン名を表示します。
```
public string DisplayName
{
    get
    {
        return "Plugin display name";
    }
}
```
- PluginContent.Name 関数を使用して、プラグインの内部名を設定します。Kanzi はプラグインの内部名を使用するため、プラグインの表示名を追加の変更なしで変更できます。
```
public string Name
{
    get
    {
        return "Internal plugin name";
    }
}
```
- PluginContent.Initialize 関数を使用して、studio をメンバー変数に配置します。
```
public void Initialize(KanziStudio studio)
{
    this.studio = studio;
}
```
プラグインをビルドして実行します。Kanzi Studio プラグインのビルドと実行を参照してください。

ここでは、Kanzi Studio ウィンドウプラグインの基本構造のみを作成しましたが、これは空のウィンドウを開くだけです。プラグインにそれ以上の機能を持たせるには、ウィンドウに機能を追加してください。Kanzi Studio ウィンドウプラグインに機能を追加すると Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化するを参照してください。

Kanzi Studio プラグインをさらに開発するには、Kanzi Studio プラグイン API の概要と Kanzi Studio プラグインAPIリファレンスを参照してください。

Kanzi Studio プラグインのビルドと実行¶

Kanzi Studio プラグインをビルドして実行するには、

Visual Studio で、Build > Build Solution を選択して、プラグイン .dll をビルドします。
Kanzi Studio プラグインの DLL ファイルを %ProgramData%\Rightware\<KanziVersion>\plugins ディレクトリにコピーします。

%ProgramData%\Rightware\<KanziVersion> に plugins ディレクトリが存在しない場合は、作成してください。
Kanzi Studio を開く。

Kanzi Studio は plugins ディレクトリ内のプラグインをロードし、それらをメインメニューまたはノードやリソースから呼び出されるコンテキストメニューに追加します。
Kanzi Studio でプラグインメインメニューを選択し、プラグインを選択するか、Node Tree のノードを右クリックしてプラグインの名前を選択し、プラグインを実行します。

Kanzi Studio ウィンドウプラグインに機能を追加する¶

Kanzi Studio ウィンドウプラグインのベースを作成した後、プラグインに機能を追加して有用な動作をさせます。ここでは、現在選択されているノードまたはリソースのkzbファイルURLを表示するプラグインを作成します。

Kanzi Studio ウィンドウプラグインに機能を追加するには、

Kanzi Studio ウィンドウプラグインのベースを作成します。Kanzi Studio ウィンドウプラグインのベースを作成するを参照してください。
Visual Studioで、プラグインのVisual Studioソリューションを開き、PluginWindow インターフェースを実装しているクラスファイルを開きます。

例えば、UserControl1.xaml.cs クラスファイルを開きます。

PluginWindow インターフェースを実装するクラスに、プラグインウィンドウでプラグインと対話する際にプラグインが実行するコードを追加します。

例えば、現在選択されているプロジェクトアイテムのkzbファイルURLを表示するプラグインを作成するには、次のようにします。

public partial class UserControl1 : UserControl, PluginWindow
{
    private KanziStudio studio;

    public UserControl1(KanziStudio studio)
    {
        this.studio = studio;
        InitializeComponent();
        // Subscribe to the SelectionChanged event to find out when the selection of a node or a resource changes.
        studio.SelectionChanged += Studio_SelectionChanged;
        // Set the contents of the plugin window.
        Populate();
    }

    // When the currently selected project item changes, set the contents of the plugin window.
    private void Studio_SelectionChanged(object sender, EventArgs e)
    {
        Populate();
    }

    // Set the text in the controls that show the name and kzb file URL of the currently selected project item.
    public void Populate()
    {
        var currentSelection = studio.SelectedItems.FirstOrDefault();
        this.selectionTextBlock.Text = (currentSelection != null) ? currentSelection.Name : "< no project item selected >";
        this.kzbUrlTextBox.Text = (currentSelection != null) ? currentSelection.KzbUrl : " ";
    }

    ...

    // Set the title of the plugin window.
    public string Title
    {
        get
        {
            return "Project item kzb file URL";
        }
    }

    ...

    // Dispose of the resources used by the window.
    public void Dispose()
    {
        if (studio != null)
        {
            this.studio.SelectionChanged -= Studio_SelectionChanged;
        }
    }

    ...

}

Visual Studioでウィンドウプラグインのレイアウトを実装するXAMLファイルを開き、ウィンドウに表示したいコンテンツを追加します。

例えば、UserControl1.xaml ファイルを開いて置き換えます。

<Grid>

</Grid>

以下に置き換えます。

<StackPanel Margin="5">
    <Label Content="Project Item" />
    <TextBlock x:Name="selectionTextBlock" Margin="10,5" />
    <Label Content="kzb file URL" />
    <TextBox x:Name="kzbUrlTextBox" Margin="10,5" IsReadOnly="True" />
</StackPanel>

プラグインをビルドして実行します。Kanzi Studio プラグインのビルドと実行を参照してください。
Node Tree でノードを選択するか、Library でリソースを選択します。プラグインウィンドウには、選択したプロジェクトアイテムのkzb URLが表示されます。

Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化する¶

Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化し、Kanzi Studio ユーザーに対して変更が1つのコマンドとして表示されるようにします。これにより、個々の変更ではなく、変更の全体を影響させるようにアンドゥとリドゥのコマンドを設定します。例えば、Kanzi Studio ウィンドウプラグインがユーザーがボタンをクリックしたときにプロジェクトに一連の変更を適用する場合、Kanzi Studio がユーザーが Edit > Undo を選択したときにそれらの変更を一度にすべてアンドゥするようにしたいときに、プロジェクトの変更をグループ化します。

バッチ修正を使用して、Kanzi Studio ウィンドウプラグインがプロジェクトに適用する一連の変更をグループ化します。バッチ修正を使用すると、修正されたイベントをリッスンするオブジェクトは、バッチ修正中に発生するイベントをスキップし、バッチ修正が終了したときにすべての変更を適用できます。

Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化するには：

Kanzi Studio ウィンドウプラグインのベースを作成します。Kanzi Studio ウィンドウプラグインのベースを作成するを参照してください。
Visual Studioで、プラグインのVisual Studioソリューションを開き、PluginWindow インターフェースを実装しているクラスファイルを開きます。

例えば、UserControl1.xaml.cs クラスファイルを開きます。

PluginWindow インターフェースを実装するクラスに、プラグインウィンドウでプラグインと対話する際にプラグインが実行するコードを追加します。

例えば、水平および垂直ガイドのグリッドを作成するプラグインを作成するには：

// This function returns true if a guide with a given name already exists.
private bool GuideExists(string guideName)
{
    bool exists = false;
    var guides = studio.ActiveProject.Guides;

    foreach (var guide in guides)
    {
        var name = guide.Get(Properties.Name);
        if (name == guideName)
        {
            exists = true;
        }
    }

    return exists;
}

// This function creates the guides.
private void CreateGuides(int step, int count, bool isVertical)
{
    var guides = studio.ActiveProject.Guides;

    for (int i = 1; i <= count; i++)
    {
        String guideName;
        Vector guidePosition;
        var coordinate = i * step;

        // Set guide position and name.
        if (isVertical)
        {
            guidePosition = new Vector(coordinate, 0);
            guideName = "Guide_V" + Convert.ToString(coordinate);
        }
        else
        {
            guidePosition = new Vector(0, coordinate);
            guideName = "Guide_H" + Convert.ToString(coordinate);
        }

        // Check if a guide with the same name already exists
        bool exists = GuideExists(guideName);
        if (!exists)
        {
            // Create a new guide.
            var guide = studio.ActiveProject.CreateProjectItem<Guide>(guideName, null);
            // Set the position of the guide.
            guide.Set(Properties.GuidePosition, guidePosition);
            // For vertical guides, set the Rotation property.
            if (isVertical)
            {
                guide.Set(Properties.GuideRotation, (float)Math.PI/2);
            }
        }
    }
}

前のステップで作成した関数を呼び出すコードを追加し、それを BeginBatchModification と CommitBatchModification 関数で囲んでください。

例えば、ユーザーがボタンをクリックしたときに水平および垂直ガイドのセットを作成するには、次のように使用します。

private void Button_Click(object sender, RoutedEventArgs e)
{
    // Distance between horizontal guides
    var horizontalStep = Convert.ToUInt16(hStepInput.Text);
    // Number of horizontal guides
    int horizontalCount = Convert.ToUInt16(hCountInput.Text);

    // Distance between vertical guides
    var verticalStep = Convert.ToUInt16(vStepInput.Text);
    // Number of vertical guides
    int verticalCount = Convert.ToUInt16(vCountInput.Text);

    // Begin a batch modification named Create Guides
    studio.ActiveProject.BeginBatchModification("Create Guides");
    // Call the functions for the code you want to execute inside the batch.
    CreateGuides(horizontalStep, horizontalCount, false);
    CreateGuides(verticalStep, verticalCount, true);
    // Finish the batch modification
    studio.ActiveProject.CommitBatchModification();
}

Visual Studioでウィンドウプラグインのレイアウトを実装するXAMLファイルを開き、ウィンドウに表示したいコンテンツとコントロールを追加します。

例えば、UserControl1.xaml ファイルを開いて置き換えます。

<Grid>

</Grid>

以下に置き換えます。

<StackPanel HorizontalAlignment="Center">
    <Grid Margin="0,10">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="150" />
            <ColumnDefinition Width="45" />
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition />
            <RowDefinition />
            <RowDefinition />
            <RowDefinition />
            <RowDefinition />
            <RowDefinition />
        </Grid.RowDefinitions>
        <Label Margin="0,0,0,2" Grid.Column="0" Grid.Row="0" FontWeight="Bold">Horizontal Guides</Label>
        <Label Margin="5,2,0,2" Grid.Column="0" Grid.Row="1">Number of guides</Label>
        <TextBox Margin="0,2" Grid.Column="1" Grid.Row="1" Name="hCountInput" Text="10" />
        <Label Margin="5,2,0,2" Grid.Column="0" Grid.Row="2">Distance between guides</Label>
        <TextBox Margin="0,2" Grid.Column="1" Grid.Row="2" Name="hStepInput" Text="100" />
        <Label Margin="0,10,0,2" Grid.Column="0" Grid.Row="3" FontWeight="Bold">Vertical Guides</Label>
        <Label Margin="5,2,0,2" Grid.Column="0" Grid.Row="4">Number of guides</Label>
        <TextBox Margin="0,2" Grid.Column="1" Grid.Row="4" Name="vCountInput" Text="10" />
        <Label Margin="5,2,2,2" Grid.Column="0" Grid.Row="5">Distance between guides</Label>
        <TextBox Margin="0,2" Grid.Column="1" Grid.Row="5" Name="vStepInput" Text="100" />
    </Grid>

    <Button Padding="5,3" Content="Create Guides" Click="Button_Click" />
</StackPanel>

プラグインをビルドして実行します。Kanzi Studio プラグインのビルドと実行を参照してください。
プラグインウィンドウで、作成したい水平および垂直ガイドの数と距離を決定するプロパティを設定し、Create Guides ボタンをクリックします。

Kanzi Studio は Preview ウィンドウで水平および垂直ガイドを作成します。

ヒント

ガイドを Kanzi Studio プロジェクトで確認するには、Preview でをクリックして Analyze モードに入り、を右クリックして Rulers and guides を選択します。
バッチ修正が機能することを確認するには、Kanzi Studio Command History を使用します。Kanzi Studio Command History を使用するを参照してください。

Kanzi Studio ウィンドウプラグインの作成¶

Kanzi Studio ウィンドウプラグインのベースを作成する¶

Kanzi Studio プラグインのビルドと実行¶

Kanzi Studio ウィンドウプラグインに機能を追加する¶

Kanzi Studio ウィンドウプラグインでプロジェクトの変更をグループ化する¶

関連項目¶