<div align="left"> <img src="images/UBind_Logo.png" width = "196" height = "196"/> </div>

UBind [Preview]

UBind is a value binding component for Unity, which is used to quickly realize the association binding between UI and logical data.

[中文文档]

Official QQ Group：1070645638

<!-- vscode-markdown-toc -->

• 1. Features
• 2. How to use
  • 2.1. Component
    • 2.1.1. Common Component Binder
    • 2.1.2. Property Binder
    • 2.1.3. Type Binder
  • 2.2. Programming
    • 2.2.1. MonoBehaviour automatic binding
    • 2.2.2. MonoBehaviour manual binding
    • 2.2.3. Manually bind any objects
• 3. Work mode
  • 3.1. Passive callback mode
  • 3.2. Active update mode
• 4. Built-in type
  • 4.1. Attribute
    • 4.1.1. Bind Value Attribute
    • 4.1.2. Bind Type Attribute
  • 4.2. Data Container
  • 4.3. Data Binder
  • 4.4. Data Converter
  • 4.5. Component Binder
  • 4.6. Bind Updater
  • 4.7. Bind Map
• 5. Built-in components
• 6. Custom extension
  • 6.1. Custom Data Binder
  • 6.2. Custom Component Binder
  • 6.3. Custom Binder Editor
  • 6.4. Custom Data Converter
• 7. Notes
• 8. Extension -- TextMeshPro

<!-- vscode-markdown-toc-config numbering=true autoSave=true /vscode-markdown-toc-config --> <!-- /vscode-markdown-toc -->

---

1. <a name='Features'></a> Features

• Support two-way binding
• Support multiple data sources and multiple target objects
• Support any property and field binding of any component
• Support automatic type conversion when the data source and target data type are different
• Provide a large number of commonly used property binders for built-in components
• Binding of properties and fields of any runtime object
• Provide data containers to divide data usage domains by groups
• Extensible custom data binder, custom type converter

---

2. <a name='Howtouse'></a>How to use

2.1. <a name='Component'></a> Component

2.1.1. <a name='CommonComponentBinder'></a>Common Component Binder

You can use the built-in binder component to directly set the properties of common UI components as data sources or data targets:

2.1.2. <a name='PropertyBinder'></a>Property Binder

If you need to operate a custom component, or a component that does not provide a dedicated binder, you can use the more general PropertyBinder, and you can bind any property field of any component with a simple setting:

2.1.3. <a name='TypeBinder'></a>Type Binder

If you need to bind a data class to the corresponding UI, you only need to use TypeBinder, specify the assembly and class name of the data class, and then bind the corresponding properties and fields to the UI in turn, and then provide the data logic In the code, the code binds the data source:

public class UBindSamplePlayerData
{
    public string Name;
    public int Exp;
    public float Stat;
    public float PlayTime;
}

public class UBindSampleGameManager
{
    public UBindSamplePlayerData Player;

    public void Awake()
    {
        Player = new UBindSamplePlayerData() {Name = "Player",};
        UBind.BindSource("PlayerData", Player);
    }
}

2.2. <a name='Programming'></a>Programming

2.2.1. <a name='MonoBehaviourautomaticbinding'></a>MonoBehaviour automatic binding

By inheriting BindableMonoBehaviour, the ability to automatically handle the binding and unbinding of properties and fields is obtained.

Use BindValue Attribute to mark the need to bind basic type data:

public class ExampleMonoBehaviour : BindableMonoBehaviour
{
	[BindValueSource("ValueKey")]
	public string ValueSource;

	[BindValueTarget("ValueKey")]
	public string ValueTarget;
}

Use BindType Attribute to mark the need to bind class and structure data:

public class ExampleData
{
	public string Value;
}

public class ExanokeMonoBehaviour : BindableMonoBehaviour
{
	[BindTypeSource("TypeKey")]
	public ExampleData DataSource;

	[BindTypeTarget("TypeKey")]
	public ExampleData DataTarget;
}

2.2.2. <a name='MonoBehaviourmanualbinding'></a>MonoBehaviour manual binding

For custom MonoBehaviour objects that cannot be inherited, you can add the following code in the OnEnable / OnDisable method to manually call the binding and unbinding interfaces of BindMap, and you can get the same as automatic binding effect:

public class ExanokeMonoBehaviour : MonoBehaviour
{
	[BindValueSource("ValueKey")]
	public string ValueSource;

	[BindValueTarget("ValueKey")]
	public string ValueTarget;

	public void OnEnable()
	{
		UBind.RegisterMap(this);
	}

	public void OnDisable()
	{
		UBind.DeRegisterMap(this);
	}
}

2.2.3. <a name='Manuallybindanyobjects'></a>Manually bind any objects

By calling various overloaded interfaces of UBind, you can bind values, attributes, fields, class objects, and structure objects at runtime. If you need to bind and unbind at a specific time, you need Cache the returned DataBinder object by itself:

public class ExampleData
{
	public string Value;
}

public class ExampleClass
{
	public string ValueSource;
	public string ValueTarget;

	public ExampleData TypeSource;
	public ExampleData TypeTarget;

	private DataBinder _runtimeValueSourceBinder;
	private DataBinder _runtimeValueTargetBinder;

	private DataBinder _runtimeTypeSourceBinder;
	private DataBinder _runtimeTypeTargetBinder;

	public void BindTest()
	{
		_runtimeValueSourceBinder = UBind.BindSource<string>("ValueKey", () => ValueSource);
		_runtimeValueTargetBinder = UBind.BindTarget<string>("ValueKey", value => ValueTarget = value);

		_runtimeTypeSourceBinder = UBind.BindSource("TypeKey", TypeSource);
		_runtimeTypeTargetBinder = UBind.BindTarget("TypeKey", TypeTarget);
	}

	public void UnBindTest()
	{
		_runtimeValueSourceBinder.UnBind();
		_runtimeValueTargetBinder.UnBind();

		_runtimeTypeSourceBinder.UnBind();
		_runtimeTypeTargetBinder.UnBind();
	}
}

It should be noted that in the above example, the data source and the data target each generate a binder, which is the default and recommended way to use it in order to support multiple data sources and multiple data targets. However, the binding of the value class (RuntimeValueBinder<T>) can also be used to simplify the call in the following way, which will return the data source binder and data target binder at the same time:

public class ExampleClass
{
	public string Source;
	public string Target;

	private DataBinder _sourceBinder;
	private DataBinder _targetBinder;

	public void BindTest()
	{
		(_sourceBinder, _targetBinder) = UBind.Bind<string>("Key", () => Source, value => Target = value);
	}

	public void UnBindTest()
	{
		_sourceBinder.UnBind();
		_targetBinder.UnBind();
	}
}

---

3. <a name='Workmode'></a> Work mode

3.1. <a name='Passivecallbackmode'></a> Passive callback mode

OnValueChangedTrigger -> DataBinder(Source) --> DataConverter --> DataBinder(Target)

The default recommended mode, at this time the NeedUpdate property of DataBinder is false, the data is refreshed by the value change callback provided by the data source, notified to the data source binder, and broadcast to all The data target binder is then converted into target data bears through the data converter.

3.2. <a name='Activeupdatemode'></a>Active update mode

BindUpdater -> DataBinder(Source) --> DataConverter --> DataBinder(Target)

When the data source does not have the ability to actively trigger data changes, the framework provides a unified update cycle to actively detect the value changes, but this mode will inevitably cause performance loss. It should be used as little as possible, which is more suitable for rapid prototyping. In this mode, the NeedUpdate property of DataBinder is true, and the AddListener() and RemoveListener() methods need to be implemented to achieve specific callback registration and cancellation . The framework triggers the UpdateSource() method of all data sources in the BindUpdater component on a periodic basis to achieve data change detection and data update broadcasting.

---