UIButton

[ArenMook]

Overview

Button is a simple component designed to receive hover, pressed and click events, and change the color of a remote sprite. You can also optionally attach an Image Button component to the same game object to get sprite swapping functionality as well.



A button can be anything. It doesn't have to be a widget. You can put a Button component on anything that has a collider. Regardless, you will most commonly be using the Button component in your UI hierarchy -- generally alongside a UI Sprite or on the game object directly above it.

In order for the button to work, the camera that's drawing the object where you place the Button component must have a UICamera script attached, as that's what sends out events. You must also have "Raycast Hit Triggers" turned on in the Physics Settings in your project.

Button works by receiving mouse over, press and click events, and translates them into appropriate color-changing actions on your the object specified in your Target field. This will most commonly be a widget (sprite, label, or texture), but can also be an object with a Light, or even a Renderer.

If you want to trigger a remote function when you click on the button, drag & drop the target game object into the "Notify" field, then choose the function from the drop-down list. Note that in order for the function to show up, it must be of "public void FuncName (void)" type. For example:

1. public void MyClickFunction()
2. {
3.     Debug.Log("I was clicked!");
4. }

Built-in components, such as tweens, have an assortment of pre-made functions for you to choose from (for example: PlayForward).

Pro-Tip #1

It's generally a good idea to put the Button component on the same game object as the button's background sprite. Hit ALT+SHIFT+C to quickly create a collider, and check the "Box Collider" option on the sprite so that the box collider auto-updates as you resize the sprite.

Pro-Tip #2

UIButton comes with only an OnClick notification. If you want OnPress, OnHover, OnSelect, OnDoubleClick, and/or others -- attach UIEventTrigger script to your button (or any other object for that matter).

Class Documentation

http://tasharen.com/ngui/docs/class_u_i_button.html

If you have a question regarding this component or would like me to clarify something, just post a reply here.

[christianschulze]

The new On Click Box is awesome! Is it possible to get an On Press, too? It would be nice to have for touch input because buttons seem more responsive with OnPress events. I know there's still the Button Message script, but with that a function name has to be provided and can't be chosen from a dropdown. So this is just a comfort question Thanks!

[christianschulze]

Never mind! I extended the UIButton Message script and have the following:

UIButtonMessageExtended.cs

1. //----------------------------------------------
2. //            NGUI: Next-Gen UI kit
3. // Copyright © 2011-2014 Tasharen Entertainment
4. //----------------------------------------------
5.  
6. using UnityEngine;
7. using System.Collections.Generic;
8.  
9. /// <summary>
10. /// Sends a message to the remote object when something happens.
11. /// </summary>
12.  
13. [AddComponentMenu("NGUI/Interaction/Button Message Extended")]
14. public class UIButtonMessageExtended : MonoBehaviour
15. {
16.         public enum Trigger
17.         {
18.                 OnClick,
19.                 OnMouseOver,
20.                 OnMouseOut,
21.                 OnPress,
22.                 OnRelease,
23.                 OnDoubleClick,
24.         }
25.  
26.         //public GameObject target;
27.         //public string functionName;
28.         public Trigger trigger = Trigger.OnPress;
29.         //public bool includeChildren = false;
30.  
31.         static public UIButtonMessageExtended current;
32.         public List<EventDelegate> eventDelegates = new List<EventDelegate>();
33.  
34.         bool mStarted = false;
35.  
36.         void Start () { mStarted = true; }
37.  
38.         void OnEnable () { if (mStarted) OnHover(UICamera.IsHighlighted(gameObject)); }
39.  
40.         void OnHover (bool isOver)
41.         {
42.                 if (enabled)
43.                 {
44.                         if (((isOver && trigger == Trigger.OnMouseOver) ||
45.                                 (!isOver && trigger == Trigger.OnMouseOut))) {
46.                                 //Send();
47.                                 current = this;
48.                                 EventDelegate.Execute(eventDelegates);
49.                                 current = null;
50.                         }
51.                 }
52.         }
53.  
54.         void OnPress (bool isPressed)
55.         {
56.                 if (enabled)
57.                 {
58.                         if (((isPressed && trigger == Trigger.OnPress) ||
59.                                 (!isPressed && trigger == Trigger.OnRelease))) {
60.                                 //Send();
61.                                 current = this;
62.                                 EventDelegate.Execute(eventDelegates);
63.                                 current = null;
64.                         }
65.                 }
66.         }
67.  
68.         void OnSelect (bool isSelected)
69.         {
70.                 if (enabled && (!isSelected || UICamera.currentScheme == UICamera.ControlScheme.Controller))
71.                         OnHover(isSelected);
72.         }
73.  
74.         void OnClick () {
75.                 if (enabled && trigger == Trigger.OnClick) {
76.                         //Send();
77.                         current = this;
78.                         EventDelegate.Execute(eventDelegates);
79.                         current = null;
80.                 }
81.         }
82.  
83.         void OnDoubleClick () {
84.                 if (enabled && trigger == Trigger.OnDoubleClick) {
85.                         //Send();
86.                         current = this;
87.                         EventDelegate.Execute(eventDelegates);
88.                         current = null;
89.                 }
90.         }
91.         /*
92.         void Send ()
93.         {
94.                 if (string.IsNullOrEmpty(functionName)) return;
95.                 if (target == null) target = gameObject;
96.  
97.                 if (includeChildren)
98.                 {
99.                         Transform[] transforms = target.GetComponentsInChildren<Transform>();
100.  
101.                         for (int i = 0, imax = transforms.Length; i < imax; ++i)
102.                         {
103.                                 Transform t = transforms[i];
104.                                 t.gameObject.SendMessage(functionName, gameObject, SendMessageOptions.DontRequireReceiver);
105.                         }
106.                 }
107.                 else
108.                 {
109.                         target.SendMessage(functionName, gameObject, SendMessageOptions.DontRequireReceiver);
110.                 }
111.         }
112.         */
113. }
114.  

UIButtonMessageExtendedEditor.cs (needs to be placed in a Folder named "Editor")

1. //----------------------------------------------
2. //            NGUI: Next-Gen UI kit
3. // Copyright © 2011-2014 Tasharen Entertainment
4. //----------------------------------------------
5.  
6. using UnityEngine;
7. using UnityEditor;
8.  
9. [CanEditMultipleObjects]
10. [CustomEditor(typeof(UIButtonMessageExtended))]
11. public class UIButtonMessageExtendedEditor : UIWidgetContainerEditor
12. {
13.  
14.         private bool argFoldout = true;
15.  
16.         public override void OnInspectorGUI ()
17.         {
18.                 NGUIEditorTools.SetLabelWidth(80f);
19.                 UIButtonMessageExtended buttonMessage = target as UIButtonMessageExtended;
20.  
21.                 GUILayout.Space(6f);
22.  
23.                 buttonMessage.trigger = (UIButtonMessageExtended.Trigger)EditorGUILayout.EnumPopup("Trigger", buttonMessage.trigger);
24.  
25.                 GUILayout.Space(3f);
26.  
27.                 NGUIEditorTools.DrawEvents(buttonMessage.trigger.ToString(), buttonMessage, buttonMessage.eventDelegates);
28.  
29.                 argFoldout = EditorGUILayout.Foldout(argFoldout, "Arguments");
30.                 if(argFoldout) {
31.                         buttonMessage.intArg = EditorGUILayout.IntField("Integer", buttonMessage.intArg);
32.                         buttonMessage.floatArg = EditorGUILayout.FloatField("Float", buttonMessage.floatArg);
33.                         buttonMessage.strArg = EditorGUILayout.TextField("String", buttonMessage.strArg);
34.                 }
35.  
36.                 if(GUI.changed) {
37.                         UnityEditor.EditorUtility.SetDirty(buttonMessage);
38.                 }
39.         }
40. }
41.  

Seems to work

[ArenMook]

Yup, nice job.

[dyego_s]

Never mind! I extended the UIButton Message script and have the following:

Your script doesn't work with new NGUI

[christianschulze]

I'm using version 3.0.8 f7. What error message do you get? Have you tried to put the Editor script UIButtonMessageExtendedEditor.cs into a Folder named "Editor"?

[dyego_s]

I'm using version 3.0.8 f7. What error message do you get? Have you tried to put the Editor script UIButtonMessageExtendedEditor.cs into a Folder named "Editor"?

Sorry, I didn't know that. I put it in the right place and...your script works fine. if you want to support, when I try to call UIButton.current.name with your script I get null exception.

[christianschulze]

I updated the script above to the current state, but you're right. current is null and not set. I copied the code for this from UIButton where current is set to null after the event execution "EventDelegate.Execute(...);" and I don't have a solution, yet.

[AbsurdInteractive]

If you want to make a UIImageButton, do you attach a UIButton script and UIImageButton script to the same gameobject? Or do you just attach the UIImageButton script?

[ArenMook]

Just UIImageButton. UIButton will do the coloring, UIImageButton will do the sprite swap. Up to you what you want.

[sintua]

What determines if the button should be set to the Disabled color?
Also, is the event system that needed "void MethodName(gameObject ClickedButton)" no longer being used?

[ArenMook]

If the collider is disabled, so is the button.

Button OnClick notification is an NGUI EventDelegate, which has a "void FuncName()" signature. To get the button that was clicked, use UIButton.current.

[PoN]

How to set Notify field by code ? And why UIButton component being disabled after Play Unity ? I would like set Notify field to instantiated GameObject with UIButton component.

[sintua]

If the collider is disabled, so is the button.

Button OnClick notification is an NGUI EventDelegate, which has a "void FuncName()" signature. To get the button that was clicked, use UIButton.current.

Hm, I've tried disabling the collider, and while the button was disabled in functionality, the color did not change to disabled unless I directly changed the "isEnabled" property on UIButton.

And I meant the UIEventListener.Get(btn).OnClick still uses the void method(Gameobject obj) format, while the *other* onclick on the button is the void method() with UIButton.current. Is there a reason these use different calls? is UIEventListener going to be updated to use the parameterless void method and UIButton.current as well, or is there a reason it still has the gameobject parameter?

[ArenMook]

@PoN: Button script will disable itself if there is nothing for it to color. You get a warning about it in the console log. You must give it something to work with.

@sintua: EventListener is different from UIButton. EventListener uses system delegates, while everything else uses NGUI delegates (which can be set via inspector). System delegates are a tiny bit faster, and UIEventListener was created long before NGUI delegate system was added, so it wouldn't make sense for me to break backwards compatibility to modify the UIEventListener to use NGUI calls.