syncfusion-winforms-docking-manager

Syncfusion WinForms Docking Manager の実装

DockingManager コントロールは、フォームの任意の位置にパネルをドッキングし、Visual Studio スタイルのドッキング可能なウィンドウを作成できるアーキテクチャを実装しています。ドックパネルは実行時に、対話的にドラッグ、サイズ変更、フローティング、自動非表示、タブ化、および複雑なレイアウトへの配置が可能です。

このスキルを使用するタイミング

次のような場合に、このスキルを使用してください。

• ドッキング可能なパネルやウィンドウを使って、Visual Studio スタイルのドッキングレイアウトを作成する
• 複数のドッキング状態を実装する：ドッキング、フローティング、自動非表示、タブ化、MDI、または TDI ウィンドウ
• TDI（Tabbed Document Interface）または MDI（Multiple Document Interface）を使用して、ドキュメントベースのアプリケーションを構築する
• ドッキングされたウィンドウにキャプションボタン（閉じる、ピン留め、メニュー、最大化）を追加する
• シリアル化を使用して、アプリケーションのセッションをまたいでドッキングレイアウトを保持する
• アクティブ化、状態変更、ユーザー操作のためのドックイベントを処理する
• ビジュアルスタイル、テーマ、色を使って外観をカスタマイズする
• 複雑なレイアウト向けに、ネストされた、またはリンクされたドッキングマネージャーを管理する
• 視覚的なフィードバックとヒントを使って、ドラッグアンドドロップによるドッキングを実装する

コンポーネントの概要

DockingManager を使用すると、任意のコントロールを次の機能を備えたドッキングウィンドウに変換できます。

• ドッキング状態：ドッキング（左、右、上、下）、フローティング、自動非表示、タブ化、塗りつぶし
• ドキュメントウィンドウ：TDI（タブ付きドキュメント）および MDI（複数ドキュメント）
• キャプションボタン：閉じる、ピン留め（自動非表示）、メニュー、最大化、元に戻す、およびカスタムボタン
• ビジュアルスタイル：Metro、Office2016（Colorful、White、DarkGray、Black）、VS2010、Office2007/2010
• シリアル化：ドッキング状態を XML、バイナリ、メモリストリーム、または分離ストレージに保存／読み込み
• イベント：ドッキング状態の変更、アクティブ化、ドラッグ、コンテキストメニューに関する 25 種類以上のイベント
• 高度な機能：ネストされたマネージャー、リンクされたマネージャー、ドッキング制限、タブグループ

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールとアセンブリの配置
• DockingManager インスタンスの作成
• SetEnableDocking を使用したドック子ウィンドウの追加
• ドックラベルとアイコンの設定
• 基本的なドッキングの設定と構成

ドッキング状態とレイアウト

📄 参照： references/dock-states.md

• ドッキング状態の概要（ドッキング、フロート、自動非表示、タブ化、塗りつぶし）
• 状態をプログラムから変更する DockControl 関数
• ドック位置（左、右、上、下、タブ化）の設定
• ドッキング状態の検出と管理
• ドッキング機能の制限

ドキュメントウィンドウ（TDI/MDI）

📄 参照： references/document-windows.md

• TDI（Tabbed Document Interface）の実装
• MDI（Multiple Document Interface）の設定
• EnableDocumentMode プロパティ
• ドキュメントタブを追加する DockAsDocument 関数
• ウィンドウモード（ツールとドキュメントの動作）
• ドキュメントタブグループの作成と管理
• ドキュメント状態の固定

キャプションボタンとカスタマイズ

📄 参照： references/caption-buttons.md

• デフォルトのキャプションボタン（閉じる、ピン留め、メニュー、最大化、元に戻す）
• Set/Get 関数を使用した特定のボタンの表示／非表示
• CaptionButtons コレクションへのカスタムキャプションボタンの追加
• ボタンクリックの処理とイベント
• ボタンの外観と色のカスタマイズ
• ボタンのツールチップと SuperTooltips

フローティングウィンドウ

📄 参照： references/floating-windows.md

• FloatControl を使用したフローティングウィンドウの作成
• ユーザーのドラッグ操作によるフローティング化
• フローティング機能の有効化／無効化
• フローティングウィンドウのプロパティ（枠線、サイズ、位置）
• フローティングウィンドウの最大化
• フロート専用ウィンドウ（再ドッキングを防止）
• フローティング状態でのカスタムボタンの表示

自動非表示ウィンドウ

📄 参照： references/auto-hide-windows.md

• 自動非表示機能の概要
• SetAutoHideMode 関数
• プログラムまたはユーザーのピンボタンによる自動非表示
• DockControlInAutoHideMode による自動非表示の位置の変更
• SetAutoHideOnLoad による読み込み時の自動非表示
• アニメーションの設定と速度
• 自動非表示タブのカスタマイズ
• 自動非表示の選択スタイル（MouseHover または Click）

タブ付きウィンドウ

📄 参照： references/tabbed-windows.md

• Tabbed ドッキングスタイルでウィンドウをタブ化
• デザイン時および実行時のタブグループの作成
• タブの配置オプション（Top、Bottom、Left、Right）
• AllowTabsMoving によるタブの並べ替え
• DockAbility によるタブ化の防止
• Set/GetTabPosition によるタブ位置の管理
• タブのスクロールボタン

外観とビジュアルスタイル

📄 参照： references/appearance-customization.md

• ビジュアルスタイル（Default、Metro、Office2016、VS2010、Office2007/2010）
• Office のカラースキーム（Blue、Silver、Black、Managed）
• Office2007/2010 のカスタムカラー
• キャプションのカスタマイズ（背景、前景、フォント）
• 境界線の色とスプリッターのカスタマイズ
• ドッキングタブの外観（色、フォント、高さ）
• ドキュメントタブのスタイル設定
• 自動非表示タブのスタイル設定
• ドラッグプロバイダースタイル（VS2005、VS2008、VS2010、VS2012、Office2016）
• 右から左への表示のサポート

シリアル化と状態の永続化

📄 参照： references/serialization.md

• PersistState プロパティによる自動シリアル化
• SaveDockState および LoadDockState 関数
• XML ファイルへのシリアル化
• バイナリファイルへのシリアル化
• データベース保存用のメモリストリームへのシリアル化
• 分離ストレージへのシリアル化
• 特定のコントロールのみをシリアル化
• デザイナーの初期状態への復元

ドッキングイベント

📄 参照： references/docking-events.md

• DockControlActivated および DockControlDeactivated
• DockStateChanged および DockStateChanging
• AutoHideAnimationStart および AutoHideAnimationStop
• DragAllow、DragFeedbackStart、DragFeedbackStop
• DockContextMenu および AutoHideTabContextMenu
• ControlMaximizing、Maximized、Restored、Minimized
• DockVisibilityChanged および DockVisibilityChanging
• NewDockStateBeginLoad および NewDockStateEndLoad
• ドッキング位置を制限する PreviewDockHints
• TabGroupCreating および TabGroupCreated
• TransferredToManager および TransferringFromManager

高度な機能

📄 参照： references/advanced-features.md

• ネストされたドッキングマネージャー（親マネージャー内の子マネージャー）
• リンクされたマネージャー（マネージャー間のドラッグ）
• ドッキング機能の制限（SetDockAbility、SetOuterDockAbility）
• サイズ制約（最小サイズ、サイズ変更の固定）
• 閉じる操作とドッキング操作の防止
• コンテキストメニューのカスタマイズ（項目の追加／削除）
• スプリッターの幅と色のカスタマイズ
• デザイン時のドッキング機能
• ローカライズのサポート

クイックスタートの例

基本的なドッキングの設定

using Syncfusion.Windows.Forms.Tools;

public partial class Form1 : Form
{
    private DockingManager dockingManager1;
    private Panel solutionExplorer;
    private Panel toolbox;
    private Panel properties;
    private Panel output;

    public Form1()
    {
        InitializeComponent();
        
        // Create DockingManager
        this.dockingManager1 = new DockingManager(this.components);
        this.dockingManager1.HostControl = this;
        
        // Create dock panels
        this.solutionExplorer = new Panel();
        this.toolbox = new Panel();
        this.properties = new Panel();
        this.output = new Panel();
        
        // Add panels to form
        this.Controls.AddRange(new Control[] { 
            solutionExplorer, toolbox, properties, output 
        });
        
        // Enable docking for all panels
        this.dockingManager1.SetEnableDocking(solutionExplorer, true);
        this.dockingManager1.SetEnableDocking(toolbox, true);
        this.dockingManager1.SetEnableDocking(properties, true);
        this.dockingManager1.SetEnableDocking(output, true);
        
        // Set dock labels
        this.dockingManager1.SetDockLabel(solutionExplorer, "Solution Explorer");
        this.dockingManager1.SetDockLabel(toolbox, "Toolbox");
        this.dockingManager1.SetDockLabel(properties, "Properties");
        this.dockingManager1.SetDockLabel(output, "Output");
        
        // Arrange dock positions
        this.dockingManager1.DockControl(solutionExplorer, this, DockingStyle.Right, 250);
        this.dockingManager1.DockControl(toolbox, this, DockingStyle.Left, 200);
        this.dockingManager1.DockControl(properties, solutionExplorer, DockingStyle.Tabbed, 200);
        this.dockingManager1.DockControl(output, this, DockingStyle.Bottom, 150);
        
        // Apply visual style
        this.dockingManager1.VisualStyle = VisualStyle.Office2016Colorful;
    }
}

よくあるパターン

ドキュメントウィンドウの作成（TDI）

// Enable document mode
this.dockingManager1.EnableDocumentMode = true;

// Add document tabs in NewDockStateEndLoad event
this.dockingManager1.NewDockStateEndLoad += (s, e) =>
{
    this.dockingManager1.DockAsDocument(document1);
    this.dockingManager1.DockAsDocument(document2);
};

// Set window mode (Tool allows dock/float, Document allows float only)
this.dockingManager1.SetWindowMode(document1, WindowMode.Document);

ドッキング状態のプログラムによる変更

// Dock a control to specific side
this.dockingManager1.DockControl(panel1, this, DockingStyle.Left, 200);

// Float a control at specific location
Rectangle bounds = new Rectangle(100, 100, 300, 400);
this.dockingManager1.FloatControl(panel1, bounds);

// Auto-hide a control
this.dockingManager1.SetAutoHideMode(panel1, true);

// Tab control with another
this.dockingManager1.DockControl(panel2, panel1, DockingStyle.Tabbed, 200);

キャプションボタンのカスタマイズ

// Hide close button for specific control
this.dockingManager1.SetCloseButtonVisibility(panel1, false);

// Hide pin (auto-hide) button
this.dockingManager1.SetAutoHideButtonVisibility(panel1, false);

// Add custom caption button
CaptionButton customBtn = new CaptionButton();
customBtn.Name = "CustomButton";
customBtn.ImageIndex = 3; // From ImageList
customBtn.Type = CaptionButtonType.Custom;
this.dockingManager1.CaptionButtons.Add(customBtn);

// Customize button colors
this.dockingManager1.ActiveCaptionButtonForeColor = Color.Red;
this.dockingManager1.InActiveCaptionButtonForeColor = Color.Gray;

シリアル化（レイアウトの保存／読み込み）

using Syncfusion.Runtime.Serialization;

// Enable auto-save on close
this.dockingManager1.PersistState = true;

// Save to XML file manually
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.XMLFile, "DockLayout");
this.dockingManager1.SaveDockState(serializer);
serializer.PersistNow();

// Load from XML file
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.XMLFile, "DockLayout");
this.dockingManager1.LoadDockState(serializer);

// Save to memory stream (for database)
MemoryStream ms = new MemoryStream();
AppStateSerializer serializer = new AppStateSerializer(
    SerializeMode.BinaryFmtStream, ms);
this.dockingManager1.SaveDockState(serializer);
serializer.PersistNow();
// Store ms.ToArray() in database

ドッキングイベントの処理

// Track dock state changes
this.dockingManager1.DockStateChanged += (s, e) =>
{
    foreach (Control ctrl in e.Controls)
    {
        Console.WriteLine($"{ctrl.Name} state changed");
    }
};

// Prevent specific dock operations
this.dockingManager1.DockStateChanging += (s, e) =>
{
    if (e.NewState == DockState.Float && e.Controls[0] == panel1)
    {
        e.Cancel = true; // Prevent panel1 from floating
    }
};

// Handle control activation
this.dockingManager1.DockControlActivated += (s, e) =>
{
    Console.WriteLine($"{e.Control.Name} activated");
};

// Restrict dock sides dynamically
this.dockingManager1.PreviewDockHints += (s, e) =>
{
    if (e.DraggingTarget == panel2)
    {
        // Only allow right docking on panel2
        e.DockAbility = DockAbility.Right;
    }
};

ドッキング機能の制限

// Restrict where control can dock (inner docking)
this.dockingManager1.SetDockAbility(panel1, DockAbility.Top | DockAbility.Bottom);

// Restrict where control can dock in client area (outer docking)
this.dockingManager1.SetOuterDockAbility(panel1, 
    DockAbility.Left | DockAbility.Right);

// Make control float-only (cannot re-dock)
this.dockingManager1.SetFloatOnly(panel1, true);

// Disable floating for specific control
this.dockingManager1.SetAllowFloating(panel1, false);

外観のカスタマイズ

// Set visual style
this.dockingManager1.VisualStyle = VisualStyle.Office2016Colorful;

// Customize active caption colors
this.dockingManager1.ActiveCaptionBackground = new BrushInfo(
    GradientStyle.Horizontal, Color.DarkBlue, Color.LightBlue);
this.dockingManager1.ActiveCaptionForeGround = Color.White;

// Customize dock tab colors
this.dockingManager1.DockTabBackColor = Color.LightGray;
this.dockingManager1.ActiveDockTabBackColor = Color.White;
this.dockingManager1.DockTabForeColor = Color.Black;

// Customize document tab colors
this.dockingManager1.DocumentWindowSettings.TabBackColor = Color.SteelBlue;
this.dockingManager1.DocumentWindowSettings.ActiveTabBackColor = Color.Green;
this.dockingManager1.DocumentWindowSettings.TabHeight = 38;

// Set drag provider style
this.dockingManager1.DragProviderStyle = DragProviderStyle.VS2012;

主なプロパティとメソッド

基本的なプロパティ

• HostControl：ドッキングレイアウトをホストする親コントロールを取得／設定します
• EnableDocumentMode：TDI（Tabbed Document Interface）モードを有効にします
• PersistState：ドッキング状態の自動保存／読み込みを有効にします
• VisualStyle：外観のテーマを設定します（Metro、Office2016、VS2010 など）
• DragProviderStyle：ドラッグヒントのスタイルを設定します（VS2005、VS2008、VS2010、VS2012）
• AutoHideEnabled：自動非表示（ピン）機能を有効／無効にします
• AllowTabsMoving：ドラッグ＆ドロップによるタブの並べ替えを有効にします
• ShowCaption：すべてのドッキングウィンドウのキャプションバーを表示／非表示にします
• CaptionButtons：キャプションボタン（閉じる、ピン、メニューなど）のコレクションです

重要なメソッド

ドック可能な子コントロールの追加：

• SetEnableDocking(Control, bool): コントロールのドッキングを有効にします
• SetDockLabel(Control, string): キャプションラベルのテキストを設定します
• SetDockIcon(Control, Icon): キャプションアイコンを設定します

ドック状態の変更：

• DockControl(Control, Control, DockingStyle, int): 指定した側にコントロールをドッキングします
• FloatControl(Control, Rectangle): 指定した位置にコントロールをフローティング表示します
• SetAutoHideMode(Control, bool): 自動非表示状態を設定します
• SetAsMDIChild(Control, bool): MDI 子ウィンドウに変換します
• DockAsDocument(Control): TDI ドキュメントタブとして追加します

状態管理：

• GetDockStyle(Control): 現在のドックスタイルを取得します
• IsFloating(Control): コントロールがフローティング表示かどうかを確認します
• GetAutoHideMode(Control): コントロールが自動非表示かどうかを確認します
• IsMDIMode(Control): コントロールが MDI 子ウィンドウかどうかを確認します
• IsTabbed(Control): コントロールがタブ表示かどうかを確認します

シリアル化：

• SaveDockState(): 分離ストレージに保存します
• SaveDockState(AppStateSerializer): ファイルまたはストリームに保存します
• LoadDockState(): 分離ストレージから読み込みます
• LoadDockState(AppStateSerializer): ファイルまたはストリームから読み込みます

キャプションボタン：

• SetCloseButtonVisibility(Control, bool): 閉じるボタンを表示または非表示にします
• SetAutoHideButtonVisibility(Control, bool): ピンボタンを表示または非表示にします
• SetMenuButtonVisibility(Control, bool): メニューボタンを表示または非表示にします

制限：

• SetDockAbility(Control, DockAbility): 内側へのドッキングが可能な側を制限します
• SetOuterDockAbility(Control, DockAbility): 外側へのドッキングが可能な側を制限します
• SetFloatOnly(Control, bool): コントロールをフローティング表示専用にします
• SetAllowFloating(Control, bool): フローティング表示を有効または無効にします

一般的なユースケース

1. Visual Studio スタイルの IDE レイアウト

ドッキング、フローティング表示、自動非表示に対応したソリューションエクスプローラー、ツールボックス、プロパティ、出力ウィンドウを作成します。

2. ドキュメント編集アプリケーション

複数のドキュメントを編集するためのタブ付きドキュメントインターフェース（TDI）を実装し、画面の端にはツールウィンドウを配置します。

3. ダッシュボードレイアウトマネージャー

ユーザーが配置を変更して保存できる、ドッキング可能なウィジェットパネルを備えたカスタマイズ可能なダッシュボードを構築します。

4. マルチパネルデータビューアー

柔軟なドッキングとタブ表示に対応した、複数のデータグリッド、チャート、詳細パネルを表示します。

5. レイアウトを保持するアプリケーション

シリアル化を使用して、ユーザーが設定したウィンドウ配置をセッション間で保存および復元します。

6. MDI アプリケーションのモダナイズ

従来の MDI アプリケーションを、フローティング表示とタブ付きドキュメントに対応した最新のドッキングインターフェースに変換します。

7. カスタム開発ツール

Visual Studio と同様のドッキング可能なウィンドウを備えた、コードエディター、デバッガー、デザインツールを構築します。