컨트롤 템플릿 (ControlTemplate)
ControlTemplate은 컨트롤의 시각 트리를 교체 가능한 정의(definition)로 분리하는 장치입니다.- 컨트롤은 public 속성(logical 상태:
Content,Header등)을 유지한 채, 실제로 그려지고 배치되는 트리(visual)를 템플릿이 소유합니다. - 템플릿은 opt-in입니다.
Template이 null이면(기본값) 컨트롤은 기존의 자체 렌더링 경로를 그대로 사용하며, 성능 특성도 변하지 않습니다. 템플릿을 설정한 컨트롤만 템플릿 경로로 동작합니다. - 단, 일부 조합 컨트롤(현재
NumericUpDown,DropDownButton,SplitButton)은 테마 기본 스타일이 템플릿을 공급하는 기본 템플릿 컨트롤입니다. 이 경우 로컬Template없이도 항상 템플릿 경로로 동작합니다(아래 “기본 템플릿” 절).
// 정의: 시각 트리의 청사진. 여러 컨트롤 인스턴스에 재사용 가능.var template = new DelegateControlTemplate<ContentControl>((owner, ctx) =>{ var presenter = new ContentPresenter(); var chrome = new Border { Child = presenter }; ctx.Bind(chrome, Control.BackgroundProperty); return chrome; // 반환값이 visual root});
host.Template = template; // 적용. 빌드는 다음 measure에서 lazy로 일어남상세 설명
섹션 제목: “상세 설명”정의와 인스턴스
섹션 제목: “정의와 인스턴스”ControlTemplate(정의)은 상태를 갖지 않는 청사진입니다. 하나의 정의를 컨트롤 100개에 적용하면Build가 100번 호출되어 서로 독립된 트리 100벌이 만들어집니다.- 빌드 산출물(visual root, 파트 명부)은 컨트롤 인스턴스가 소유합니다. 정의 객체에 요소를 저장하면 여러 컨트롤이 한 요소를 공유하는 사고가 나므로 금지합니다.
- 예외적으로, 창 하나에만 쓰는 템플릿이라면 필드 요소를 델리게이트로 캡처하는 인스턴스 전용 템플릿 패턴을 쓸 수 있습니다(아래 커스텀 chrome 예 참고). 이 경우 그 정의는 다른 컨트롤에 재사용할 수 없습니다.
적용 수명주기
섹션 제목: “적용 수명주기”- 파트는
OnApplyTemplate부터 존재합니다.Template대입은 빌드를 예약할 뿐이고 (다음 measure에서 lazy 빌드), 생성자나 대입 직후의GetTemplateChild는 null입니다. Build는 컨트롤이 트리에 붙고 스타일이 해석된 뒤에 불립니다.Build안에서 테마/DPI 값을 읽을 수는 있지만, 테마나 DPI가 바뀌어도 트리는 유지되므로 거기서 읽은 값은 빌드 당시 그대로 남습니다. 색과 치수는 스타일과ctx.Bind로 파트에 전달하십시오. 빌드가 그 값을 트리에 계산해 넣어야 하는 템플릿은 재빌드를 요청합니다:new DelegateControlTemplate<T>(Build) { RebuildOnThemeChange = true, RebuildOnDpiChange = true }.- 교체와 요청된 재빌드는 트리의 소멸 이벤트입니다. 이전 트리는 detach되고(내부 포커스는 안전하게 해제) 다음 measure에서 새 트리가 빌드됩니다. 파트의 일시 상태(입력 중 텍스트, 스크롤 위치 등)는 이때 사라지므로, 유지가 필요한 상태는 파트가 아니라 컨트롤의 속성(logical)에 있어야 합니다.
적용 후에는 measure, arrange, render, hit test, 트리 순회가 전부 템플릿 루트 하나를 통해 흐르고, 컨트롤의 기존 자체 시각 구현은 실행되지 않습니다.
이름 있는 파트
섹션 제목: “이름 있는 파트”빌드 중 ctx.Register(name, element)로 파트에 이름을 붙이고, 컨트롤 구현부는
OnApplyTemplate에서 캐시합니다.
public class Badge : Control{ private TextBlock? _label;
protected override void OnApplyTemplate() { _label = GetTemplateChild<TextBlock>("Label"); // 템플릿에 없으면 null }}ctx.Get<T>(name)은 템플릿 저자용(없으면 예외),GetTemplateChild<T>는 컨트롤용 (없으면 null - 템플릿이 그 파트를 생략하는 것을 허용)입니다.- 같은 이름을 두 번 등록하면 빌드 시점에 예외가 납니다.
파트 상호작용 계약 (PART_*)
섹션 제목: “파트 상호작용 계약 (PART_*)”단순 조회를 넘어, 컨트롤이 약속된 이름의 파트에 자기 동작을 배선하는 계약이
있습니다. 첫 사례가 NumericUpDown.PART_TEXT_BOX입니다: 템플릿이 이 이름으로
TextBox를 등록하면 컨트롤이 편집 파이프라인 전체를 인계합니다 - 값 <-> 텍스트 동기화,
Enter/Escape 커밋/취소, 파트 포커스 진입 시 편집 시작, 포커스 이탈 시 커밋.
nud.Template = new DelegateControlTemplate<NumericUpDown>((owner, ctx) =>{ var editBox = new TextBox(); ctx.Register(NumericUpDown.PART_TEXT_BOX, editBox); // 편집 파이프라인 인계
var display = new TextBlock(); ctx.Bind(display, TextBlock.TextProperty, NumericUpDown.DisplayTextProperty); ctx.Bind(editBox, TextBox.IsVisibleProperty, NumericUpDown.IsEditingProperty); // ...배치 생략...});- 비편집 표시는
DisplayText읽기 전용 속성(포맷 적용된 값 문자열)을 바인딩합니다. - 역방향 데이터 흐름(파트 -> 컨트롤)이 필요한 파트가 이 계약의 대상입니다. 단방향
시각 반영이면
ctx.Bind로 충분하고 계약이 필요 없습니다. - 파트가 등록되지 않으면 해당 기능이 비활성화될 뿐 예외는 없습니다
(
BeginEdit가 no-op이 되는 식).
Expander.PART_HEADER_TOGGLE도 같은 계약입니다. 이 이름으로 ToggleButton을 등록하면 그 IsChecked와 확장기의 IsExpanded가 양방향으로 따라갑니다. 파트가 없으면 템플릿을 적용한 확장기는 코드나 키보드로만 IsExpanded가 바뀝니다.
ProgressBar.PART_TRACK과 ProgressBar.PART_INDICATOR는 템플릿이 값 로직을 그대로 쓰게 합니다. 템플릿이 트리를 배치한 뒤 컨트롤이 표시 막대를 트랙 폭 안에서 값(미확정이면 이동 구간)의 가로 범위로 한 번 더 배치하고, 세로는 템플릿이 배치한 그대로 둡니다. 표시 막대의 가로 정렬은 Stretch로, Width는 비워 두어야 그 범위가 적용되며, 템플릿은 표시 막대를 트랙 안에 두고 색만 주면 됩니다. 채움 색은 막대의 Fill이므로 보통 ctx.Bind(indicator, Control.BackgroundProperty, ProgressBar.FillProperty)로 표시 막대의 Background를 묶습니다.
ScrollBar.PART_TRACK은 Track을 받습니다. 컨트롤이 범위·값·뷰포트·방향을 트랙에 밀어 넣고, 트랙의 Thumb이 끌리면 값으로 바꾸며, 트랙의 감소·증가 요소를 누르면(그 요소가 RepeatButton이면 그 Click으로) LargeChange만큼 이동합니다. 트랙은 Thumb, DecreaseElement, IncreaseElement를 배치만 하고 아무것도 그리지 않으므로 모양은 템플릿이 그 요소들에 줍니다. 파트가 없으면 템플릿을 적용한 스크롤바는 휠과 코드로만 움직입니다.
Slider.PART_TRACK도 Track을 받습니다. 컨트롤이 범위·값·방향을 트랙에 밀어 넣고(세로 슬라이더는 IsDirectionReversed를 켜서 최소값이 아래에 옵니다), 트랙의 Thumb이 끌리면 값으로 바꾸며, 트랙의 다른 곳을 누르면 값을 그 지점으로 옮기고 놓을 때까지 포인터를 따라갑니다. 채움 색은 슬라이더의 Fill이므로 보통 ctx.Bind(decrease, Control.BackgroundProperty, Slider.FillProperty)로 감소 요소의 Background를 묶습니다. 파트가 없으면 템플릿을 적용한 슬라이더는 키, 휠, 코드로만 값이 바뀝니다.
SegmentedControl과 ButtonGroup은 SegmentedBase.PART_ITEMS_HOST로 등록한 Border가 필요합니다. 컨트롤이 세그먼트 띠를 그 호스트의 Child에 넣고 세그먼트의 생성과 선택은 계속 컨트롤이 맡으며, 띠가 구분선을 직접 그리고 양 끝 세그먼트를 호스트 가장자리에 붙입니다. 띠가 컨트롤 내용의 전부라서 이 파트 없이 템플릿을 적용하면 예외가 납니다.
TabControl은 TabControl.PART_HEADERS_HOST로 등록한 Border가 필요하며, 이 호스트가 탭 헤더 줄과 넘침 버튼을 받습니다. 헤더의 측정·배치·선택은 계속 컨트롤이 맡습니다. 템플릿 어디에든 둔 ContentPresenter는 원본을 지정하지 않아도 선택된 탭의 내용을 보여 주고, 탭 내용의 논리 소유자는 계속 TabControl입니다.
ContentPresenter: logical 슬롯의 투영
섹션 제목: “ContentPresenter: logical 슬롯의 투영”ContentPresenter는 템플릿 트리 안에서 “여기에 컨트롤의 콘텐츠가 나타난다”를
표시하는 자리입니다.
new DelegateControlTemplate<ContentControl>((owner, ctx) => new Border { Child = new ContentPresenter() });- 컨트롤의
Content는 계속 컨트롤의 logical 소유로 남고, presenter가 그 요소의 visual 위치를 제공합니다. 즉host.Content는 템플릿과 무관하게 항상 진짜 사용자 콘텐츠를 돌려줍니다. - 템플릿에 presenter가 없으면 콘텐츠는 화면에 나타나지 않습니다. 프레임워크는 콘텐츠를 임의 위치로 대신 붙여주지 않습니다. 이때도 logical 소유는 유지되므로 presenter가 있는 템플릿으로 교체하면 다시 나타납니다.
슬롯 매핑 메커니즘
섹션 제목: “슬롯 매핑 메커니즘”presenter와 컨트롤 속성의 연결은 다음 순서로 일어납니다.
1. 템플릿 빌드가 반환한 트리를 컨트롤에 attach2. 프레임워크가 그 서브트리를 순회하며 아직 배선되지 않은 모든 ContentPresenter를 찾아 주인 컨트롤에 연결 (이름 매칭이 아니라 "이 빌드에서 만들어진 presenter" 기준)3. 각 presenter가 자기 ContentSource가 가리키는 주인 속성 값을 읽어 visual child로 attach (pull 방식)ContentSource는 문자열 이름이 아니라 속성 디스크립터(MewProperty<Element?>)
참조입니다. 어느 슬롯을 투영할지 형식적으로 지정합니다.
var headerPresenter = new ContentPresenter { ContentSource = HeaderedContentControl.HeaderProperty };var contentPresenter = new ContentPresenter(); // 기본값: ContentControl.ContentProperty이후 주인 컨트롤의 슬롯 속성이 바뀌면(host.Content = other 등), 컨트롤이 해당
속성을 ContentSource로 갖는 presenter만 골라 재투영합니다. Header 변경이 Content
presenter를 건드리지 않습니다.
- 슬롯이 다른 presenter 여러 개는 정상 조합입니다(Header + Content 등). 같은 슬롯을 두 presenter가 가리키는 구성은 지원하지 않습니다 - 요소는 한 곳에만 존재할 수 있습니다.
- 투영된 콘텐츠의 정렬은 MewUI의 일반 규칙을 따릅니다: 콘텐츠 요소 자신의
HorizontalAlignment/VerticalAlignment가 presenter 슬롯 안에서 적용되고, 템플릿 저자가 정렬을 지시하려면 presenter 자체에 alignment를 지정합니다.
템플릿 바인딩 (ctx.Bind)
섹션 제목: “템플릿 바인딩 (ctx.Bind)”템플릿 파트는 대개 주인 컨트롤의 속성을 시각적으로 반영해야 합니다. ctx.Bind가
그 연결입니다: 파트의 속성이 주인 컨트롤의 속성을 따라가는 단방향 바인딩으로,
WPF의 TemplateBinding에 대응하는 개념입니다.
ctx.Bind(part, targetProperty, sourceProperty); // 소스는 항상 템플릿의 주인 컨트롤ctx.Bind(part, property); // 양쪽이 같은 속성일 때의 축약형ctx.Bind(part, targetProperty, sourceProperty, value => /* ... */); // 파트가 변환된 값을 받음- 연결 시점에 현재 값을 즉시 적용하고, 이후 변경을 계속 전달합니다.
- 단방향(주인 -> 파트)입니다. 파트가 주인 컨트롤이 노출한 상태의 반영이라는 의미론이므로,
역방향이 필요한 파트(예: 편집 텍스트)는 컨트롤 코드가
OnApplyTemplate에서 파트 이벤트를 구독하는 쪽이 맞습니다. - 변환 오버로드는 주인 속성 하나로 파트들을 서로 다르게 움직입니다. 예를 들어
IsEditing하나로 한 파트는 보이고 다른 파트는 투명하게 합니다. - 템플릿 해체 시 자동 해제됩니다.
- 스타일 트리거와 트랜지션도 그대로 동작합니다. 트리거는 주인 컨트롤의 속성에 쓰고, 바인딩이 매 애니메이션 틱을 파트로 전달하므로 색 전환 등이 끊기지 않습니다.
전형적인 사용처가 chrome입니다. 템플릿이 적용된 컨트롤은 기본 Background/Border를
그리지 않으므로(시각 전체를 템플릿이 소유해야 재템플릿이 성립), 배경과 테두리는
템플릿 안의 파트가 담당하고 컨트롤 속성에 바인딩합니다. 이 4종 묶음(Background,
BorderBrush, BorderThickness, CornerRadius)은 ctx.BindChrome 한 줄로 선언합니다 -
“억제된 chrome을 이 파트가 인수한다”는 뜻입니다:
_pathHost.Template = new DelegateControlTemplate<ContentControl>((host, ctx) =>{ var chrome = new Border { Child = /* ... */ }; ctx.BindChrome(chrome); return chrome;});기본 템플릿: 스타일이 공급하는 템플릿
섹션 제목: “기본 템플릿: 스타일이 공급하는 템플릿”Template은 일반 속성이므로 테마 기본 스타일의 setter로도 공급할 수 있습니다.
파트들이 실제 컨트롤로 상호작용을 소유하는 조합 컨트롤이 이 방식을 씁니다. 예를 들면
NumericUpDown의 편집/스피너 파트, DropDownButton의 popup trigger,
SplitButton의 분리된 primary/drop-down 동작이 있습니다.
// 테마 기본 스타일 안 (프레임워크 내부)Setter.Create(Control.TemplateProperty, (ControlTemplate?)NumericUpDownTemplate.Instance)- 우선순위는 값 저장소 규칙 그대로입니다: 로컬
Template이 스타일 템플릿을 이깁니다. 앱은 로컬 대입만으로 기본 룩을 통째로 교체할 수 있습니다. - 로컬
Template = null명시는 “스타일 템플릿 거부”입니다. 기본 템플릿 컨트롤은 자체 그리기 경로가 없으므로 빈 컨트롤이 됩니다(룩리스 컨트롤의 표준 의미론). StyleName이나 서브트리StyleSheet타입 규칙으로도 템플릿을 갖는 스타일을 공급할 수 있으므로, 앱/화면 단위의 룩 변형이 스타일 체계 안에서 성립합니다.- 부분 이름 스타일이나 타입 규칙은 런타임 타입의 프레임워크 기본 스타일 위에 쌓이므로,
별도로 지정하지 않은 기본
Template은 유지됩니다. 완전 교체할 때만 스타일에OverridesDefaultStyle = true를 지정하고, 이 컨트롤들에는 새Template도 제공해야 합니다. - 어느 컨트롤이 기본 드로잉이고 어느 컨트롤이 기본 템플릿인지의 기준: 파트가 실제 컨트롤로 존재해야 상호작용이 성립하는가. 프리미티브(TextBox, Button, CheckBox 등)는 드로잉이 본질이라 기본 템플릿을 갖지 않습니다.
상태 파트 패턴: 여러 표현 상태의 전환
섹션 제목: “상태 파트 패턴: 여러 표현 상태의 전환”상태에 따라 다른 트리를 보여야 하는 컨트롤은 콘텐츠 교체가 아니라 템플릿 파트의 가시성 토글로 표현합니다. 파일 다이얼로그 주소창(브레드크럼 <-> 경로 입력)이 실례입니다.
// 두 상태가 템플릿 파트로 상주하고, 상태 플래그가 가시성만 토글한다._pathHost.Template = new DelegateControlTemplate<ContentControl>((host, ctx) =>{ var chrome = new Border { Child = new Grid().Children(_breadcrumb.CenterVertical(), _pathBox), }; // ...chrome 바인딩 생략... return chrome;});
// 진입: _breadcrumb.IsVisible = false; _pathBox.IsVisible = true; _pathBox.Focus();// 이탈: 역토글 + 포커스 이동 (숨김은 포커스를 해제하지 않으므로 명시적으로 옮긴다)이 패턴의 이점:
- 전환이 detach를 유발하지 않아 파트 상태(텍스트, 캐럿 등)가 왕복 간 보존됩니다.
- 표현 상태(기계류)가
Content슬롯을 점거하지 않습니다.Content는 사용자 콘텐츠의 자리이지 컨트롤 자신의 표현을 담는 곳이 아닙니다.
주의: 숨김(IsVisible = false)은 포커스를 해제하지 않습니다. 포커스를 가진 파트를
숨길 때는 반드시 포커스를 명시적으로 옮기거나 해제해야 합니다.
Window 템플릿: 커스텀 chrome
섹션 제목: “Window 템플릿: 커스텀 chrome”Window도 ContentControl이므로 같은 방식으로 템플릿을 갖습니다. 자체 타이틀바를
그리는 창이 대표 사례입니다: chrome(타이틀바, 테두리)은 템플릿이 소유하고, 앱
콘텐츠는 ContentPresenter 자리로 투영됩니다.
public class ChromeWindow : Window{ public ChromeWindow() { Template = new DelegateControlTemplate<ChromeWindow>((window, ctx) => { var titleText = new TextBlock().CenterVertical().Margin(8, 0); titleText.SetBinding(TextBlock.TextProperty, window, TitleProperty);
var titleBar = new Border { MinHeight = 32, Child = titleText }; titleBar.OnMouseDown(e => { if (e.Button == MouseButton.Left) { window.DragMove(); e.Handled = true; } });
var chrome = new Border { BorderThickness = 1, Child = new DockPanel().Children( titleBar.DockTop(), new ContentPresenter()), }; ctx.Bind(chrome, Control.BorderBrushProperty); return chrome; }); }}
// 사용하는 쪽은 일반 창과 똑같다: Content는 chrome과 무관하게 앱 콘텐츠의 자리.var window = new ChromeWindow { Content = appRoot };Window.Content는 어떤 chrome 아래서든 항상 앱 콘텐츠입니다. chrome 트리를 Content에 밀어 넣고 진짜 콘텐츠를 다른 속성으로 우회시키는 구조가 필요 없습니다.- 최소화/최대화 버튼처럼 창 코드가 레이아웃 전에 만져야 하는 파트가 있다면, 파트를 생성자에서 필드로 만들고 델리게이트가 캡처하는 인스턴스 전용 템플릿 패턴을 씁니다(“정의와 인스턴스” 절 참고).
- 템플릿 없는 창(기본)은 네이티브 프레임 그대로입니다. WPF와 같은 구도입니다: 표준 창은 OS chrome, 커스텀 chrome 창만 템플릿이 시각을 소유합니다.
logical과 visual: 무엇이 어디에 남는가
섹션 제목: “logical과 visual: 무엇이 어디에 남는가”| 관계 | 템플릿 없음 | 템플릿 적용 |
|---|---|---|
content.LogicalParent |
컨트롤 | 컨트롤 (불변) |
content.Parent (visual) |
컨트롤 | 템플릿 안의 ContentPresenter |
| chrome (배경, 테두리) | 컨트롤이 직접 그림 | 템플릿 파트가 담당 |
- 개발자 도구(
Ctrl/Cmd+Shift+T)의 Logical Tree 모드는 사용자 소유 구조만 보여주고, visual 모드는 logical 소유가 없는 요소(템플릿 파트, presenter 등 기계류)를[TypeName]으로 표기합니다.
주의 사항
섹션 제목: “주의 사항”- 정의에 요소를 저장하지 마십시오.
Build가 매번 새 트리를 만들어야 합니다. (인스턴스 전용 템플릿은 예외 패턴이며 재사용 불가를 감수하는 선택입니다.) - 기계류를
Content에 넣지 마십시오. 컨트롤 자신의 표현(chrome, 상태별 트리)은 템플릿 소유입니다.Content는 밖에서 주입되는 사용자 콘텐츠의 자리입니다. - chrome 억제를 기억하십시오. 템플릿을 붙였는데 배경/테두리가 사라졌다면, 그
시각을 템플릿 파트로 옮기고
ctx.Bind로 연결해야 한다는 신호입니다. - 파트 조회는
OnApplyTemplate이후에만 유효합니다. 빌드는 lazy이므로 생성자 시점에는 파트가 없습니다. - visual root는 하나입니다. 템플릿 밖의 요소를 별도 경로로 그리거나 순회하는 구현은 만들지 마십시오.