Properties Editor 좋은 자료.
Unity3D 2015. 7. 1. 21:15http://catlikecoding.com/unity/tutorials/editor/custom-list/
Custom List, displaying data your way
- create a custom editor
- use
SerializedObject
- manipulate a
SerializedProperty
that represents an array or list - use an enumeration for option flags
- use GUI buttons
This tutorial comes after the Custom Data tutorial.
This tutorial is for Unity version 4.3 and above. The older version can still be found here.
Creating Test Data
We start with the finished Custom Data tutorial project, or by creating a new empty project and importing custom-data.unitypackage.
Then we create a new test script named ListTester with some test arrays, and make a new prefab and prefab instance with it, so we can see it all works as expected.
using UnityEngine; public class ListTester : MonoBehaviour { public int[] integers; public Vector3[] vectors; public ColorPoint[] colorPoints; public Transform[] objects; }
Creating a Custom Inspector
UnityEditor.Editor
, and apply the UnityEditor.CustomEditor
attribute to tell Unity that we want it to do the drawing for our component.using UnityEditor; using UnityEngine; [CustomEditor(typeof(ListTester))] public class ListTesterInspector : Editor { }
OnInspectorGUI
method of the Editor
class. Leaving the method empty will result in an empty inspector as well.public override void OnInspectorGUI () { }
SerializedObject
instead of a single SerializedProperty
. Secondly, an instance of the editor exists as long as the object stays selected, keeping a reference to its data instead of getting it via a method parameter. Finally, we can use EditorGUILayout
, which takes care of positioning for us.We can get to the serialized object via the serializedObject
property. To prepare it for editing, we must first synchronize it with the component it represents, by calling its Update
method. Then we can show the properties. And after we are done, we have to commit any changes via its ApplyModifiedProperties
method. This also takes care of Unity's undo history. In between these two is where we'll draw our properties.
public override void OnInspectorGUI () { serializedObject.Update(); EditorGUILayout.PropertyField(serializedObject.FindProperty("integers")); EditorGUILayout.PropertyField(serializedObject.FindProperty("vectors")); EditorGUILayout.PropertyField(serializedObject.FindProperty("colorPoints")); EditorGUILayout.PropertyField(serializedObject.FindProperty("objects")); serializedObject.ApplyModifiedProperties(); }
PropertyField
doesn't show any children – like array elements – unless we tell it to do so.public override void OnInspectorGUI () { serializedObject.Update(); EditorGUILayout.PropertyField(serializedObject.FindProperty("integers"), true); EditorGUILayout.PropertyField(serializedObject.FindProperty("vectors"), true); EditorGUILayout.PropertyField(serializedObject.FindProperty("colorPoints"), true); EditorGUILayout.PropertyField(serializedObject.FindProperty("objects"), true); serializedObject.ApplyModifiedProperties(); }
Creating an Editor List
PropertyField
method. We will name this method Show and put it in its own static utility class, so we can use it wherever we want. We'll name this class EditorList and place it in the Editor folder.using UnityEditor; using UnityEngine; public static class EditorList { public static void Show (SerializedProperty list) { } }
public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers")); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints")); EditorList.Show(serializedObject.FindProperty("objects")); serializedObject.ApplyModifiedProperties(); }
EditorGUILayout.PropertyField
without having it show the children of the list. Then we can show the list elements ourselves with help of the arraySize
property and the GetArrayElementAtIndex
method of SerializedProperty
. We'll leave the size for later.public static void Show (SerializedProperty list) { EditorGUILayout.PropertyField(list); for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } }
Properly Indenting
public static void Show (SerializedProperty list) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } EditorGUI.indentLevel -= 1; }
ColorPointDrawer
behaves well.public override void OnGUI (Rect position, SerializedProperty property, GUIContent label) { int oldIndentLevel = EditorGUI.indentLevel; label = EditorGUI.BeginProperty(position, label, property); Rect contentPosition = EditorGUI.PrefixLabel(position, label); if (position.height > 16f) { position.height = 16f; EditorGUI.indentLevel += 1; contentPosition = EditorGUI.IndentedRect(position); contentPosition.y += 18f; } contentPosition.width *= 0.75f; EditorGUI.indentLevel = 0; EditorGUI.PropertyField(contentPosition, property.FindPropertyRelative("position"), GUIContent.none); contentPosition.x += contentPosition.width; contentPosition.width /= 3f; EditorGUIUtility.labelWidth = 14f; EditorGUI.PropertyField(contentPosition, property.FindPropertyRelative("color"), new GUIContent("C")); EditorGUI.EndProperty(); EditorGUI.indentLevel = oldIndentLevel; }
Collapsing Lists
isExpanded
property of our list.public static void Show (SerializedProperty list) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; if (list.isExpanded) { for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } } EditorGUI.indentLevel -= 1; }
Showing the Size
public static void Show (SerializedProperty list) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; if (list.isExpanded) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } } EditorGUI.indentLevel -= 1; }
Customizing the List
public static void Show (SerializedProperty list, bool showListSize = true) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; if (list.isExpanded) { if (showListSize) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); } for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } } EditorGUI.indentLevel -= 1; }
public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers")); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints"), false); EditorList.Show(serializedObject.FindProperty("objects"), false); serializedObject.ApplyModifiedProperties(); }
public static void Show (SerializedProperty list, bool showListSize = true, bool showListLabel = true) { if (showListLabel) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; } if (!showListLabel || list.isExpanded) { if (showListSize) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); } for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } } if (showListLabel) { EditorGUI.indentLevel -= 1; } }
public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers"), true, false); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints"), false, false); EditorList.Show(serializedObject.FindProperty("objects"), false); serializedObject.ApplyModifiedProperties(); }
Using Flags
The first thing we need to do is create an enumeration of all our options. We name itEditorListOption and give it the System.Flags
attribute. We place it in its own script file or in the same script as EditorList
, but outside of the class.
using UnityEditor; using UnityEngine; using System; [Flags] public enum EditorListOption { }
|
.[Flags] public enum EditorListOption { None = 0, ListSize = 1, ListLabel = 2, Default = ListSize | ListLabel }
Show
method can now be replaced with a single options parameter. Then we'll extract the individual options with the help of the bitwise AND operator &
and store them in local variables to keep things clear.public static void Show (SerializedProperty list, EditorListOption options = EditorListOption.Default) { bool showListLabel = (options & EditorListOption.ListLabel) != 0, showListSize = (options & EditorListOption.ListSize) != 0; if (showListLabel) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; } if (!showListLabel || list.isExpanded) { if (showListSize) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); } for (int i = 0; i < list.arraySize; i++) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } } if (showListLabel) { EditorGUI.indentLevel -= 1; } }
public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers"), EditorListOption.ListSize); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints"), EditorListOption.None); EditorList.Show(serializedObject.FindProperty("objects"), EditorListOption.ListLabel); serializedObject.ApplyModifiedProperties(); }
Hiding the Element Labels
[Flags] public enum EditorListOption { None = 0, ListSize = 1, ListLabel = 2, ElementLabels = 4, Default = ListSize | ListLabel | ElementLabels, NoElementLabels = ListSize | ListLabel }
Show
method is extract this option and perform a simple check. Let's also move the element loop to its own private method, for clarity.public static void Show (SerializedProperty list, EditorListOption options = EditorListOption.Default) { bool showListLabel = (options & EditorListOption.ListLabel) != 0, showListSize = (options & EditorListOption.ListSize) != 0; if (showListLabel) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; } if (!showListLabel || list.isExpanded) { if (showListSize) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); } ShowElements(list, options); } if (showListLabel) { EditorGUI.indentLevel -= 1; } } private static void ShowElements (SerializedProperty list, EditorListOption options) { bool showElementLabels = (options & EditorListOption.ElementLabels) != 0; for (int i = 0; i < list.arraySize; i++) { if (showElementLabels) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } else { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i), GUIContent.none); } } }
ColorPointDrawer
does not claim an extra line when it does not receive a label.public override float GetPropertyHeight (SerializedProperty property, GUIContent label) { return label != GUIContent.none && Screen.width < 333 ? (16f + 18f) : 16f; }
Adding Buttons
First we'll add an option for buttons, and also a convenient option to activate everything.
[Flags] public enum EditorListOption { None = 0, ListSize = 1, ListLabel = 2, ElementLabels = 4, Buttons = 8, Default = ListSize | ListLabel | ElementLabels, NoElementLabels = ListSize | ListLabel, All = Default | Buttons }
We predefine static GUIContent
for these buttons and include handy tooltips as well. We also add a separate method for showing the buttons and call it after each element, if desired.
private static GUIContent moveButtonContent = new GUIContent("\u21b4", "move down"), duplicateButtonContent = new GUIContent("+", "duplicate"), deleteButtonContent = new GUIContent("-", "delete"); private static void ShowElements (SerializedProperty list, EditorListOption options) { bool showElementLabels = (options & EditorListOption.ElementLabels) != 0, showButtons = (options & EditorListOption.Buttons) != 0; for (int i = 0; i < list.arraySize; i++) { if (showElementLabels) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } else { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i), GUIContent.none); } if (showButtons) { ShowButtons(); } } } private static void ShowButtons () { GUILayout.Button(moveButtonContent); GUILayout.Button(duplicateButtonContent); GUILayout.Button(deleteButtonContent); }
public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers"), EditorListOption.ListSize); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints"), EditorListOption.Buttons); EditorList.Show( serializedObject.FindProperty("objects"), EditorListOption.ListLabel | EditorListOption.Buttons); serializedObject.ApplyModifiedProperties(); }
EditorGUILayout.BeginHorizontal
andEditorGUILayout.EndHorizontal
.private static void ShowElements (SerializedProperty list, EditorListOption options) { bool showElementLabels = (options & EditorListOption.ElementLabels) != 0, showButtons = (options & EditorListOption.Buttons) != 0; for (int i = 0; i < list.arraySize; i++) { if (showButtons) { EditorGUILayout.BeginHorizontal(); } if (showElementLabels) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } else { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i), GUIContent.none); } if (showButtons) { ShowButtons(); EditorGUILayout.EndHorizontal(); } } }
private static GUILayoutOption miniButtonWidth = GUILayout.Width(20f); private static void ShowButtons () { GUILayout.Button(moveButtonContent, EditorStyles.miniButtonLeft, miniButtonWidth); GUILayout.Button(duplicateButtonContent, EditorStyles.miniButtonMid, miniButtonWidth); GUILayout.Button(deleteButtonContent, EditorStyles.miniButtonRight, miniButtonWidth); }
Fortunately, adding functionality to the buttons is very simple, as we can directly use the methods for array manipulation provided by SerializedProperty
. We need the list and the current element index for this to work, so we add them as parameters to our ShowButtons
method and pass them along inside the loop of ShowElements
.
private static void ShowElements (SerializedProperty list, EditorListOption options) { bool showElementLabels = (options & EditorListOption.ElementLabels) != 0, showButtons = (options & EditorListOption.Buttons) != 0; for (int i = 0; i < list.arraySize; i++) { if (showButtons) { EditorGUILayout.BeginHorizontal(); } if (showElementLabels) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } else { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i), GUIContent.none); } if (showButtons) { ShowButtons(list, i); EditorGUILayout.EndHorizontal(); } } } private static void ShowButtons (SerializedProperty list, int index) { if (GUILayout.Button(moveButtonContent, EditorStyles.miniButtonLeft, miniButtonWidth)) { list.MoveArrayElement(index, index + 1); } if (GUILayout.Button(duplicateButtonContent, EditorStyles.miniButtonMid, miniButtonWidth)) { list.InsertArrayElementAtIndex(index); } if (GUILayout.Button(deleteButtonContent, EditorStyles.miniButtonRight, miniButtonWidth)) { list.DeleteArrayElementAtIndex(index); } }
While this is how Unity handles deletion in this case, it is weird. Instead, we want the element to always be removed, not sometimes cleared. We can enforce this by checking whether the list's size has remained the same after deleting the element. If so, it has only been cleared and we should delete it again, for real this time.
private static void ShowButtons (SerializedProperty list, int index) { if (GUILayout.Button(moveButtonContent, EditorStyles.miniButtonLeft, miniButtonWidth)) { list.MoveArrayElement(index, index + 1); } if (GUILayout.Button(duplicateButtonContent, EditorStyles.miniButtonMid, miniButtonWidth)) { list.InsertArrayElementAtIndex(index); } if (GUILayout.Button(deleteButtonContent, EditorStyles.miniButtonRight, miniButtonWidth)) { int oldSize = list.arraySize; list.DeleteArrayElementAtIndex(index); if (list.arraySize == oldSize) { list.DeleteArrayElementAtIndex(index); } } }
private static GUIContent moveButtonContent = new GUIContent("\u21b4", "move down"), duplicateButtonContent = new GUIContent("+", "duplicate"), deleteButtonContent = new GUIContent("-", "delete"), addButtonContent = new GUIContent("+", "add element"); private static void ShowElements (SerializedProperty list, EditorListOption options) { bool showElementLabels = (options & EditorListOption.ElementLabels) != 0, showButtons = (options & EditorListOption.Buttons) != 0; for (int i = 0; i < list.arraySize; i++) { if (showButtons) { EditorGUILayout.BeginHorizontal(); } if (showElementLabels) { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i)); } else { EditorGUILayout.PropertyField(list.GetArrayElementAtIndex(i), GUIContent.none); } if (showButtons) { ShowButtons(list, i); EditorGUILayout.EndHorizontal(); } } if (showButtons && list.arraySize == 0 && GUILayout.Button(addButtonContent, EditorStyles.miniButton)) { list.arraySize += 1; } }
Only Allowing Lists
ListTester
that is not a list.public int notAList;
ListTestInspector
.public override void OnInspectorGUI () { serializedObject.Update(); EditorList.Show(serializedObject.FindProperty("integers"), EditorListOption.ListSize); EditorList.Show(serializedObject.FindProperty("vectors")); EditorList.Show(serializedObject.FindProperty("colorPoints"), EditorListOption.Buttons); EditorList.Show( serializedObject.FindProperty("objects"), EditorListOption.ListLabel | EditorListOption.Buttons); EditorList.Show(serializedObject.FindProperty("notAList")); serializedObject.ApplyModifiedProperties(); }
public static void Show (SerializedProperty list, EditorListOption options = EditorListOption.Default) { if (!list.isArray) { EditorGUILayout.HelpBox(list.name + " is neither an array nor a list!", MessageType.Error); return; } bool showListLabel = (options & EditorListOption.ListLabel) != 0, showListSize = (options & EditorListOption.ListSize) != 0; if (showListLabel) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; } if (!showListLabel || list.isExpanded) { if (showListSize) { EditorGUILayout.PropertyField(list.FindPropertyRelative("Array.size")); } ShowElements(list, options); } if (showListLabel) { EditorGUI.indentLevel -= 1; } }
Multi-object Editing
CanEditMultipleObjects
attribute to our ListTesterInspector
.[CustomEditor(typeof(ListTester)), CanEditMultipleObjects]
public static void Show (SerializedProperty list, EditorListOption options = EditorListOption.Default) { if (!list.isArray) { EditorGUILayout.HelpBox(list.name + " is neither an array nor a list!", MessageType.Error); return; } bool showListLabel = (options & EditorListOption.ListLabel) != 0, showListSize = (options & EditorListOption.ListSize) != 0; if (showListLabel) { EditorGUILayout.PropertyField(list); EditorGUI.indentLevel += 1; } if (!showListLabel || list.isExpanded) { SerializedProperty size = list.FindPropertyRelative("Array.size"); if (showListSize) { EditorGUILayout.PropertyField(size); } if (size.hasMultipleDifferentValues) { EditorGUILayout.HelpBox("Not showing lists with different sizes.", MessageType.Info); } else { ShowElements(list, options); } } if (showListLabel) { EditorGUI.indentLevel -= 1; } }
Downloads
- custom-list.unitypackage
- The finished project.
Questions & Answers
- Why not use
arraySize
here? SerializedProperty
has anarraySize
property, which is a convenient way to get the size of the array or list represented by the property. Why not use it here?At this point we don't want a simple integer, we want the size as a
SerializedProperty
so it's easy to edit. Fortunately, we can extract the size as a property via the special relative path Array.size. We will usearraySize
in all other cases.- How does
showListSize
work? - We define
showListSize
as an optional parameter by assigning a constant value to it. This is equivalent to adding a second method declaration without the argument, then calling the original method with the constant value as an argument.void DoWork (bool fast = true) {}
is the same as
void DoWork (bool fast) {} void DoWork () { DoWork(true); }
Be advised that using optional parameters can lead to weird errors on some platform builds. I only use them in editor scripts, which won't be included in builds.
- Is the
Flags
attribute required? - You do not need to apply the
Flags
attribute, it will work fine without. What the attribute does is signify that you are using the enumeration for flags that can be combined together, which will affect how such values are converted to strings, among other things. - How do bitwise flags work?
- You can use the individual digits of a number to represent a sequence of boolean values, commonly named flags. For example, 01 would mean that the fist option is on, 10 would mean that the second option is on, 11 would mean that both are on, and 00 would mean that neither are on.
As each option gets its own digit, their values must be set to 1, 10, 100, 1000, 10000, and so on. However, we are dealing with binary numbers here, while in our scripts we write decimal numbers. So we have to use powers of two instead of powers of ten, writing 1, 2, 4, 8, 16, etcetera.
- Why
static
instead ofconst
? - Objects cannot be constants, only simple values can. So we make our content static instead, which means that it will be created the first time that any
EditorList
code is accessed, and then stay as they are as long as we don't mess with them. - How does
Button
work? - The method
GUI.Button
both shows a button and returns whether it was clicked. So you typically call it inside anif
statement and perform the necessary work in the corresponding code block.What actually happens is that your own GUI method, in this case
OnInspectorGUI
, gets called far more often than just once. It gets called when performing layout, when repainting, and whenever a significant GUI event happens, which is quite often. Only when a mouse click event comes along that is consumed by the button, will it returntrue
.To get an idea of how often the GUI methods get called, put
Debug.Log(Event.current);
at the start of yourOnInspectorGUI
method, then fool around a bit in the editor and watch the console.Usually you need not worry about this, but be aware of it when performing heavy work like generating textures. You don't want to do that dozens of times per second if you don't need to.
- What happens when we move the bottom element?
- When trying to move the bottom element even lower, nothing will happen. Nothing gets screwed up, the action simply changes nothing.
- What are the contents of a new item?
- If you insert a new array element via a
SerializedProperty
, the new element will be a duplicate of the element just above it. If there's no other element, it gets default values.
'Unity3D' 카테고리의 다른 글
Unity MenuItem (0) | 2015.08.04 |
---|---|
UNITY EDITOR EXTENSIONS – MENU ITEMS (0) | 2015.08.04 |
What is the difference between AndroidJavaClass.Call and AndroidJavaObject.Call (0) | 2015.06.17 |
unity android plugin (0) | 2015.06.17 |
한방에 모아보는 Unity Shader 레퍼런스 Properties (0) | 2015.06.15 |