WPF 標準コントロールデモアプリ › GroupBox
GroupBox Display
GroupBox は、フォームの 1 つの区切りの入力欄など、関連するコントロールを見出し付きの枠で囲むコントロールです。
見出しはキーボードとスクリーンリーダーにとってのグループの名前
GroupBox は HeaderedContentControl を継承しています。UI オートメーションからは、見出しを名前とする Group に見えます。「Personal information」という見出しの GroupBox は、その名前で報告されました。スクリーンリーダーはこれをグループの名前として読み上げるので、見出しだけで意味の分かるものにします。
見出しはキーボード操作にも関わります。文字列の見出しはアクセスキーを認識して表示されるので、Header="_Name" では N がアクセスキーになりました。このアクセスキーを AccessKeyManager.ProcessKey で処理させると、フォーカスは見出しではなくグループの中の最初の TextBox へ移りました。実際のキーボードでの Alt+N は測っていません。見出しにアクセスキーを付けると、キーボードからグループの中へ移れます。
見出しに表示できるもの
見出しが null のとき、読み取り専用の HasHeader は False になり、見出しの領域の高さは 0 でした。改行を含む文字列は 2 行で表示され、見出しの高さは 1 行で 15.96、2 行で 31.92 でした。そのために TextBlock を使う必要はありません。
HeaderStringFormat は見出しの書式で、件数から「Items (12)」のような見出しを作るときに使えます。"Header={0}." では、見出し HEADER は Header=HEADER. と表示されました。効くのは要素でない見出しだけで、TextBlock を見出しにすると HEADER のままでした。
枠、余白、内容に届くもの
既定の枠（BorderBrush と BorderThickness）は #FFD5DFE5 の幅 1 で、Padding は 0 です。Padding は既定のテンプレートでも効き、Padding="20" では内容が 20 下へ移りました。Content は枠の中に置く 1 つの子なので、複数のコントロールをまとめるときは、パネルを内容にします。
フォントの各プロパティと Foreground は、見出しと内容の両方の文字に届きます。GroupBox に FontSize="20" を設定すると、見出しの文字も内容の TextBlock も 20 になりました。Background は、見出しの中ほどから下の、枠の内側を塗ります。見出しが上から 1〜27.6 にある GroupBox で、塗られた範囲は 13.8 から始まりました。見出しの上半分は塗られる範囲の外に出ます。内容はこの範囲の中にあるので、内容の後ろにも背景が見えます。
| 条件 | 計測値 |
|---|---|
| 基底クラス / BorderBrush、BorderThickness、Padding の既定値 | HeaderedContentControl / #FFD5DFE5, 1,1,1,1, 0,0,0,0 |
| Header=GroupBox: HasHeader / 見出しの領域の高さ | True / 15.96 |
| Header=null: HasHeader / 見出しの領域の高さ | False / 0 |
| HeaderStringFormat="Header={0}."、String の見出し: 文字列 | Header=HEADER. |
| HeaderStringFormat="Header={0}."、TextBlock の見出し: 文字列 | HEADER |
| 文字列の Header（1 行）: 見出しの高さ | 15.96 |
| 文字列の Header（改行あり）: 見出しの高さ | 31.92 |
| Padding=0: 内容の位置 | x=60 y=16.96 w=80 h=30 |
| Padding=20: 内容の位置 | x=60 y=36.96 w=80 h=30 |
| FontSize=20、Foreground=Red: 見出しの文字 / 内容の文字 | 20, #FFFF0000 / 20, #FFFF0000 |
| Background: 塗られる領域 / 見出しの領域 / 内容が塗られる領域の中にあるか | x=0 y=13.8 w=200 h=46.4 / x=9 y=1 w=87.83 h=26.6 / True |
| UI オートメーション: コントロールの種類 / 名前 | Group / Personal information |
| Header="_Name": アクセスキーを認識するか / アクセスキー N の後のフォーカス | True / 内容の最初の TextBox |
見出し、余白、引き継がれるプロパティ、アクセスキー。.NET 10 / Windows 11 で計測。
デモアプリで試す
デモアプリの GroupBox のページには、見出し、HeaderStringFormat、内容と、Control のプロパティ（Padding、フォントの各プロパティ、Background、Foreground、枠）の欄があります。見出しの欄は、空のテキストボックスを null に変換します。各欄の下の「Show Code」リンクで、その欄の XAML を表示できます。次の XAML は、HeaderStringFormat の欄（GroupBoxUsageControl.xaml）から、スタイルと周囲の GroupBox を省き、名前空間の宣言を加えたものです。
<StackPanel xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<TextBox x:Name="HeaderForHeaderStringFormatTextBox" Text="HEADER" />
<GroupBox x:Name="HeaderStringFormatGroupBox"
Header="{Binding Text, ElementName=HeaderForHeaderStringFormatTextBox}"
HeaderStringFormat="Header={0}." />
</StackPanel>
関連するコントロールと記事
ソースコードと計測の方法
このページの挙動の記述は、すべて .NET 10 / Windows 11 で実際に動かして確かめたものです。計測には、このサイトのスクリーンショット生成ツールの GroupBoxDemoScene を使いました。見出しは、テンプレートの見出しの ContentPresenter の中の文字の要素から読みました。アクセスキーは、指定したアクセスキーを、そのキーのキーダウンがアクセスキーの管理に渡された場合と同じように処理する AccessKeyManager.ProcessKey を呼んで処理させました。実際の Alt+キーの入力ではなく、API の呼び出しです。位置は GroupBox の左上からのもので、大きさは計測したマシンでの値です。