언리얼 엔진 리플렉션 시스템은 UProperty 매크로의 정보를 사용하여 디테일 패널(Details Panel)에 프로퍼티를 표시하는 방법을 결정합니다. 대부분의 프로퍼티 노출 사용 사례에는 이 정도면 충분합니다. 하지만 디테일 패널의 정보 표시 및 편집 방식을 더 세부적으로 커스터마이징해야 할 수도 있습니다.
언리얼 엔진에서는 디테일 패널을 오버라이드하고 필요에 따라 요소를 변경하거나 제거하거나 추가할 수 있는 디테일 패널 커스터마이제이션(Details Panel Customization) 인터페이스 클래스를 제공합니다. 여기에는 특정 프로퍼티 표시, 커스텀 편집 조건 또는 복잡한 커스텀 슬레이트 위젯 구현에 대한 수정이 포함됩니다. 이 페이지에서는 디테일 패널 커스터마이제이션의 기본 사항을 간략하게 살펴보고 단계별 빌드 방법을 보여주는 튜토리얼에 대한 링크를 제공합니다.
디테일 패널 커스터마이제이션 클래스 및 메서드
디테일 패널 커스터마이제이션에 사용되는 인터페이스 클래스는 다음과 같습니다.
| 클래스 이름 | 설명 | 커스터마이제이션 메서드 |
|---|---|---|
IDetailCustomization |
UObject 및 UActor 파생 클래스에 대한 디테일 패널 커스터마이제이션입니다. | CustomizeDetails |
IPropertyTypeCustomization |
구조체에 대한 디테일 패널 커스터마이제이션입니다. | CustomizeHeader, CustomizeChildren |
이러한 클래스 중 하나를 구현할 때, 해당 커스터마이제이션 함수를 오버라이드하여 슬레이트 코드를 추가할 수 있습니다. 이 파라미터는 커스터마이징할 클래스 또는 구조체에 대한 유틸리티 클래스와 데이터를 노출합니다. 이러한 인터페이스에 대해서는 아래에 더 자세하게 요약되어 있습니다.
IDetailCustomization
IDetailCustomization 은 UObject 및 UActor 파생 클래스에 대한 디테일 패널을 커스터마이징합니다. IDetailCustomization 이 할당된 오브젝트의 인스턴스를 선택할 때마다, 디테일 커스터마이제이션의 규칙에 따라 디테일 패널이 표시됩니다.
ADocumentationActor 는 디테일 커스터마이제이션을 사용하는 클래스의 간단한 예시입니다. FDocumentationActorCustomization 은 웹 브라우저에 제공된 URL을 여는 버튼을 추가하는 디테일 커스터마이제이션입니다.
IDetailCustomization::CustomizeDetails
virtual void (IDetailLayoutBuilder& DetailBuilder) override;
IDetailCustomization::CustomizeDetails 는 UObject 및 액터 파생 클래스에 대한 디테일 패널을 오버라이드하는 슬레이트 코드를 추가할 공간을 제공합니다. 명시적으로 변경하지 않는 항목은 디테일 커스터마이제이션 없이 디폴트 디테일이 표시되므로, 추가하거나 재정렬하려는 항목에만 집중할 수 있습니다.
IPropertyTypeCustomization
IPropertyTypeCustomization 은 커스텀 프로퍼티 타입에 대한 디테일 패널 디스플레이를 커스터마이징하는 베이스 클래스입니다. 언제든 편집을 위해 EditAnywhere 또는 EditDefaultsOnly 와 같은 UPROPERTY 지정자나 블루프린트 정의 변수를 통해 프로퍼티 타입의 인스턴스를 디테일 패널에 노출할 수 있습니다.
언리얼 엔진에서 프로퍼티 타입 커스터마이제이션을 사용하는 구조체 예시는 다음과 같습니다.
| 구조체 | 커스터마이제이션 | 프로퍼티 커스터마이제이션 설명 |
|---|---|---|
FFrameRate |
FFrameRateCustomization |
유효한 프레임 레이트 값 범위를 좁히는 데 도움이 되는 커스텀 드롭다운을 추가합니다. |
FGameplayTag |
FGameplayTagCustomization |
게임플레이 태그(Gameplay Tag) 에디터를 불러오는 버튼을 표시합니다. |
IPropertyTypeCustomization::CustomizeHeader
IPropertyTypeCustomization::CustomizeHeader 는 커스텀 프로퍼티 타입 디테일 패널의 헤더 부분을 오버라이드합니다.
virtual void CustomizeHeader(TSharedRef<IPropertyHandle> PropertyHandle, FDetailWidgetRow& HeaderRow, IPropertyTypeCustomizationUtils& CustomizationUtils) override;
이 헤더는 프로퍼티 멤버 위에 표시되는 접을 수 있는 드롭다운을 포함한 프로퍼티 핸들의 디테일을 나타냅니다. 프로퍼티 타입 커스터마이제이션 인터페이스를 구현하지 않는 구조체에서는 이 섹션에 프로퍼티의 이름이 표시됩니다.
'MyStruct'라는 구조체에 대한 디테일 커스터마이제이션입니다. 여기에는 커스터마이징된 헤더(1)와 자손(2)이 포함됩니다.
아무런 파라미터 실행인자 없이 이 IPropertyTypeCustomization::CustomizeHeader 를 선언하면, 언리얼 에디터에 접을 수 있는 드롭다운이 표시되지 않고 클래스의 다른 자손 프로퍼티와 같은 계층구조 레벨에 IPropertyTypeCustomization::CustomizeChildren 함수가 표시됩니다.
또는, 헤더를 커스터마이징하되 아무것도 하지 않도록 CustomizeChildren을 오버라이드할 수도 있습니다.
IPropertyTypeCustomization::CustomizeChildren
IPropertyTypeCustomization::CustomizeChildren 은 프로퍼티의 접을 수 있는 드롭다운을 클릭하여 모든 자손 프로퍼티를 표시할 때 나타나는 섹션을 커스터마이징합니다.
virtual void CustomizeChildren(TSharedRef<IPropertyHandle> PropertyHandle, IDetailChildrenBuilder& ChildBuilder, IPropertyTypeCustomizationUtils& CustomizationUtils) override;
프로퍼티 타입 커스터마이제이션이 없는 구조체에서는 그 구조체의 일부로 정의된 모든 프로퍼티가 이 섹션에 표시됩니다.
CustomizeChildren(1)이 채워져 있지만 CustomizeHeader가 없는 커스텀 구조체의 예시입니다. 필드는 드롭다운 대신 액터의 다른 프로퍼티(2)와 함께 나란히 표시됩니다.
코드를 제공하지 않고 이 함수를 오버라이드하면, 해당 구조체의 자손 프로퍼티가 디테일 패널에 전혀 표시되지 않습니다. 자손 프로퍼티를 표시하려면 IDetailChildrenBuilder::AddProperty 를 사용해야 합니다. 프로퍼티의 전체 자손 프로퍼티 목록을 반복하여 모든 자손 프로퍼티를 표시할 수 있습니다.
void FCustomDataDetailsCustomization::CustomizeChildren(TSharedRef<IPropertyHandle> PropertyHandle, IDetailChildrenBuilder& ChildBuilder, IPropertyTypeCustomizationUtils& CustomizationUtils)
{
if (!PropertyHandle->IsValidHandle())
{
return;
}
uint32 NumChildren = 0;
PropertyHandle->GetNumChildren(NumChildren);
for (uint32 ChildIndex = 0; ChildIndex < NumChildren; ChildIndex++)
{
ChildBuilder.AddProperty(PropertyHandle->GetChildHandle(ChildIndex).ToSharedRef());
}
헬퍼 클래스
다음 클래스 인터페이스는 슬레이트 클래스 프로퍼티에 액세스하는 데 유용한 함수를 제공합니다.
| 클래스 이름 | 설명 |
|---|---|
IDetailLayoutBuilder |
UObject 또는 UActor의 프로퍼티와 카테고리 액세스 및 변경을 위한 유틸리티 함수입니다. |
IDetailChildrenBuilder |
커스텀 프로퍼티 타입의 프로퍼티와 카테고리 액세스 및 변경을 위한 유틸리티 함수입니다. |
IPropertyHandle |
디테일 시스템 내 프로퍼티에 대한 정보를 포함하는 래퍼입니다. 개별 프로퍼티 커스터마이징에 사용됩니다. |
IPropertyTypeCustomizationUtils |
프로퍼티 타입 커스터마이제이션을 위한 기타 유틸리티입니다. |
IDetailLayoutBuilder
IDetailLayoutBuilder 는 UObject 또는 UActors의 프로퍼티와 카테고리 액세스 및 변경을 위한 유틸리티 함수를 제공합니다. IDetailLayoutBuilder 는 IDetailCustomization::CustomizeDetails 에서 사용할 수 있습니다.
IDetailChildrenBuilder
IDetailChildrenBuilder 는 커스텀 프로퍼티 타입의 프로퍼티와 카테고리 액세스 및 변경을 위한 유틸리티 함수를 제공합니다. IDetailLayoutBuilder 와 비슷하게 작동하지만, 부모 IPropertyTypeCustomization 이 커스터마이징하는 프로퍼티의 자손 프로퍼티로만 제한됩니다.
IPropertyHandle
IPropertyHandle 은 변경되는 프로퍼티에 반응하는 델리게이트와 프로퍼티 자체에 대한 레퍼런스를 포함하여 디테일 시스템 내 프로퍼티에 대한 정보를 포함하는 래퍼입니다. IPropertyTypeCustomization에는 두 개의 함수가 있으며, 둘 다 커스터마이징할 프로퍼티의 IPropertyHandle에 대한 레퍼런스를 제공합니다. IDetailCustomization 과 IDetailLayoutBuilder 인터페이스는 커스터마이징할 클래스의 모든 자손 프로퍼티의 IPropertyHandle 에 대한 쉐어드 레퍼런스(TSharedRef)를 가져옵니다.
IPropertyTypeCustomizationUtils
IPropertyTypeCustomizationUtils 는 일반 폰트에 대한 레퍼런스, 섬네일 풀에 대한 액세스 및 IPropertyUtilities 인터페이스에 대한 쉐어드 레퍼런스를 제공합니다.
IPropertyUtilities 는 다양한 유틸리티 함수를 제공합니다. 여기에는 디테일 패널 새로고침을 요청하거나 강제하는 기능, 사용자의 현재 선택에 대한 정보에 액세스하는 기능 및 색 선택 툴 창을 생성할 수 있는 유틸리티 함수가 포함됩니다. IPropertyTypeCustomizationUtils 는 IPropertyTypeCustomization::CustomizeHeader 또는 IPropertyTypeCustomization::CustomizeChildren 을 통해 사용할 수 있습니다.
튜토리얼
다음 튜토리얼에서는 디테일 패널을 커스터마이징할 때의 특정 작업에 대한 자세한 내용과 예시를 살펴볼 수 있습니다.