Button Events: Difference between revisions

Button events are a generalized event system for all button interactions.
VisualWikitext
Added initial version of Button Events page, this isn't final yet, I'll refine this tomorrow.
 
add line breaks to make intro more readable
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Button events provide a generalized system for '''''buttons''''' and '''''actions triggered by buttons''''' within [[Resonite]]. This abstraction allows components to define behaviors as responses to common button interactions without having to rely on knowing which specific button was the source of the interaction. When a button event source component triggers an event, it will call all corresponding button event handler components on a single target [[Slot]], which is usually the same one it is attached to. Button events '''do not''' traverse hierarchies in the same way [[Dynamic Impulses]] do.
{{SHORTDESC:Button events are a generalized event system for all button interactions.}}
Button events provide a generalized system for '''''buttons''''' and '''''actions triggered by buttons''''' within [[Resonite]].


{{warning|1=
This abstraction allows components to define behaviors as responses to common button interactions without having to know the specific button the interaction originates from.
The order in which multiple button event handler components on the same slot are executed is not defined, as the order of components on a slot themselves isn't defined and may change. If order of execution is important, consider using ProtoFlux instead!
}}


When a '''button event sender component''' triggers an event, it will call all corresponding '''button event receiver components''' on a single target [[Slot|slot]], which is usually the same one it is attached to. Button events '''do not''' traverse hierarchies in the same way [[Dynamic Impulses]] do.
You can use button events in [[ProtoFlux]] by using the [[Button Events (ProtoFlux)|Button Events node]].
{{Note|The order in which multiple button event receiver components on the same slot are executed is not defined, as the order of components on a slot itself isn't defined and may change. If order of execution is important, consider using ProtoFlux instead!|danger}}
== Event Types ==
Button events are separated into two categories, each defining 3 event types:
Button events are separated into two categories, each defining 3 event types:
;Hover Events
;Hover Events
Line 15: Line 21:
: Released
: Released


Components that act as receivers for either or both of those event categories implement the C# interfaces [[IButtonPressReceiver]] and [[IButtonHoverReceiver]] respectively.
Components that act as receivers for either or both of those event categories implement [[Type:IButtonPressReceiver|IButtonPressReceiver]] and [[Type:IButtonHoverReceiver|IButtonHoverReceiver]] respectively.
 
You can create [[ProtoFlux]] [[Impulses]] for the different event types by using the [[Button Events (ProtoFlux)]] node.


== Button Event Data ==
== Button Event Data ==
Each button event carries event data with information about the interaction that resulted in the event.
Each button event carries event data with information about the interaction the event originates from.
{| class="wikitable" style="margin:left"
{| class="wikitable" style="margin:left"
|-
|-
! Property Name !! Property Type
! Property Name !! Property Type
|-
|-
| Source || [[Type:Component]]
| Source || [[Type:Component|Component]]
|-
|-
| Global Press Point || [[Type:Float3]]
| Global Press Point || [[Type:Float3|Float3]]
|-
|-
| Local Press Point || [[Type:Float2]]
| Local Press Point || [[Type:Float2|Float2]]
|-
|-
| Normalized Press Point || [[Type:Float2]]
| Normalized Press Point || [[Type:Float2|Float2]]
|}
|}


== Button Event Sources ==
== Button Event Senders ==
{| class="wikitable" style="margin:left"
{| class="wikitable" style="margin:left"
|-
|-
! Component !! Hover Events !! Press Events !! Notes
! Component !! Hover Events !! Press Events !! Notes
|-
|-
| [[Button (Component)]] || Yes || Yes ||
| [[Component:Button|Button]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonHoverEventRelay (Component)]] || Yes || No || Relays button hover events to a specifiable slot instead of its own slot
| [[Component:ButtonHoverEventRelay|ButtonHoverEventRelay]] || {{Yes}} || {{No}} || Relays button hover events to a specifiable slot instead of its own.
|-
|-
| [[ButtonPressEventRelay (Component)]] || No || Yes || Relays button press events to a specifiable slot instead of its own slot
| [[Component:ButtonPressEventRelay|ButtonPressEventRelay]] || {{No}} || {{Yes}} || Relays button press events to a specifiable slot instead of its own.
|-
|-
| [[LegacyButton (Component)]] || No || Yes || Only supports '''Pressed''' and '''Released''', not '''Pressing'''
| [[Component:LegacyButton|LegacyButton]] || {{No}} || {{Yes}} || Only supports '''Pressed''' and '''Released''', not '''Pressing'''.
|-
|-
| [[PhysicalButton (Component)]] || No || Yes ||
| [[Component:PhysicalButton|PhysicalButton]] || {{No}} || {{Yes}} ||
|-
|-
| [[TouchButton (Component)]] || No || Yes ||
| [[Component:TouchButton|TouchButton]] || {{No}} || {{Yes}} ||
|}
|}


== Button Event Handlers ==
== Button Event Receivers ==
{| class="wikitable" style="margin:left"
{| class="wikitable" style="margin:left"
|-
|-
! Component !! Hover Events !! Press Events !! Notes
! Component !! Hover Events !! Press Events !! Notes
|-
|-
| [[AudioStreamSpawner (Component)]] || No || Yes ||
| [[Component:AudioStreamSpawner|AudioStreamSpawner]] || {{No}} || {{Yes}} ||
|-
|-
| [[AvatarCreatorSpawner (Component)]] || No || Yes ||
| [[Component:AvatarCreatorSpawner|AvatarCreatorSpawner]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonActionTrigger (Component)]] || No || Yes ||
| [[Component:ButtonActionTrigger|ButtonActionTrigger]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonAudioClipPlayer (Component)]] || Yes || Yes ||
| [[Component:ButtonAudioClipPlayer|ButtonAudioClipPlayer]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonAudioDeviceSet (Component)]] || No || Yes ||
| [[Component:ButtonAudioDeviceSet|ButtonAudioDeviceSet]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonClipboardCopyText (Component)]] || No || Yes ||
| [[Component:ButtonClipboardCopyText|ButtonClipboardCopyText]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonDelegateRelay´1 (Component)]] || No || Yes
| [[Component:ButtonDelegateRelay´1|ButtonDelegateRelay´1]] || {{No}} || {{Yes}}
|-
|-
| [[ButtonDestroy (Component)]] || No || Yes ||
| [[Component:ButtonDestroy|ButtonDestroy]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonDynamicImpulseTrigger (Component)]] || Yes || Yes ||
| [[Component:ButtonDynamicImpulseTrigger|ButtonDynamicImpulseTrigger]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonDynamicImpulseTriggerWithReference´1 (Component)]] || Yes || Yes ||
| [[Component:ButtonDynamicImpulseTriggerWithReference´1|ButtonDynamicImpulseTriggerWithReference´1]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonDynamicImpulseTriggerWithValue´1 (Component)]] || Yes || Yes ||
| [[Component:ButtonDynamicImpulseTriggerWithValue´1|ButtonDynamicImpulseTriggerWithValue´1]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonEditColorX (Component)]] || No || Yes ||
| [[Component:ButtonEditColorX|ButtonEditColorX]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonEnumShift´1 (Component)]] || No || Yes ||
| [[Component:ButtonEnumShift´1|ButtonEnumShift´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonHoverEventRelay (Component)]] || Yes || No ||
| [[Component:ButtonHoverEventRelay|ButtonHoverEventRelay]] || {{Yes}} || {{No}} ||
|-
|-
| [[ButtonHoverRelay (Component)]] || Yes || No ||
| [[Component:ButtonHoverRelay|ButtonHoverRelay]] || {{Yes}} || {{No}} ||
|-
|-
| [[ButtonLoopSet (Component)]] || Yes || Yes ||
| [[Component:ButtonLoopSet|ButtonLoopSet]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonOpenHome (Component)]] || No || Yes ||
| [[Component:ButtonOpenHome|ButtonOpenHome]] || {{No}}  || {{Yes}} ||
|-
|-
| [[ButtonParentUnderUser (Component)]] || No || Yes ||
| [[Component:ButtonParentUnderUser|ButtonParentUnderUser]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonPlaybackAction (Component)]] || Yes || Yes ||
| [[Component:ButtonPlaybackAction|ButtonPlaybackAction]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ButtonPlaybackSeeker (Component)]] || No || Yes ||
| [[Component:ButtonPlaybackSeeker|ButtonPlaybackSeeker]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonPressEventRelay (Component)]] || No || Yes ||
| [[Component:ButtonPressEventRelay|ButtonPressEventRelay]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonReferenceCycle´1 (Component)]] || No || Yes ||
| [[Component:ButtonReferenceCycle´1|ButtonReferenceCycle´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonReferenceSet´1 (Component)]] || No || Yes ||
| [[Component:ButtonReferenceSet´1|ButtonReferenceSet´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonRefRelay´1 (Component)]] || No || Yes ||
| [[Component:ButtonRefRelay´1|ButtonRefRelay´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonRelay´1 (Component)]] || No || Yes ||
| [[Component:ButtonRelay´1|ButtonRelay´1]] || {{No}} || {{Yes}}  ||
|-
|-
| [[ButtonRelay (Component)]] || No || Yes ||
| [[Component:ButtonRelay|ButtonRelay]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonStringAppend (Component)]] || No || Yes ||
| [[Component:ButtonStringAppend|ButtonStringAppend]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonStringErase (Component)]] || No || Yes ||
| [[Component:ButtonStringErase|ButtonStringErase]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonToggle (Component)]] || No || Yes ||
| [[Component:ButtonToggle|ButtonToggle]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonUserProfileIconSet (Component)]] || No || Yes ||
| [[Component:ButtonUserProfileIconSet|ButtonUserProfileIconSet]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonValueCycle´1 (Component)]] || No || Yes ||
| [[Component:ButtonValueCycle´1|ButtonValueCycle´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonValueSet´1 (Component)]] || No || Yes ||
| [[Component:ButtonValueSet´1|ButtonValueSet´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonValueShift´1 (Component)]] || No || Yes ||
| [[Component:ButtonValueShift´1|ButtonValueShift´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[ButtonWorldLink (Component)]] || No || Yes ||
| [[Component:ButtonWorldLink|ButtonWorldLink]] || {{No}} || {{Yes}} ||
|-
|-
| [[ContactLink (Component)]] || No || Yes ||
| [[Component:ContactLink|ContactLink]] || {{No}} || {{Yes}} ||
|-
|-
| [[ContextMenuItem (Component)]] || Yes || Yes ||
| [[Component:ContextMenuItem|ContextMenuItem]] || {{Yes}} || {{Yes}} ||
|-
|-
| [[ContextMenuItemSource (Component)]] || Yes || Yes || Despite not being a button event source itself, it implements the C# interface [[Type:IButton]] and can therefore be used with [[Button Events (ProtoFlux)]]. (It will proxy all button events it receives.)
| [[Component:ContextMenuItemSource|ContextMenuItemSource]] || {{Yes}} || {{Yes}} || Despite not being a button event sender itself, it implements [[Type:IButton|IButton]] and can therefore be used with [[Button Events (ProtoFlux)|the Button Events ProtoFlux node]]. (It will proxy all button events it receives.)
|-
|-
| [[ContextMenuSubmenu (Component)]] || No || Yes ||
| [[Component:ContextMenuSubmenu|ContextMenuSubmenu]] || {{No}} || {{Yes}} ||
|-
|-
| [[DataPreset (Component)]] || No || Yes ||
| [[Component:DataPreset|DataPreset]] || {{No}} || {{Yes}}  ||
|-
|-
| [[FileSystemItem (Component)]] || No || Yes ||
| [[Component:FileSystemItem|FileSystemItem]] || {{No}} || {{Yes}} ||
|-
|-
| [[FullBodyCalibratorSpawner (Component)]] || No || Yes ||
| [[Component:FullBodyCalibratorSpawner|FullBodyCalibratorSpawner]] || {{No}} || {{Yes}} ||
|-
|-
| [[GenericModalDialogSpawner´1 (Component)]] || No || Yes ||
| [[Component:GenericModalDialogSpawner´1|GenericModalDialogSpawner´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[GenericUserspaceDialogSpawner´1 (Component)]] || No || Yes ||
| [[Component:GenericUserspaceDialogSpawner´1|GenericUserspaceDialogSpawner´1]] || {{No}} || {{Yes}} ||
|-
|-
| [[Hyperlink (Component)]] || No || Yes ||
| [[Component:Hyperlink|Hyperlink]] || {{No}} || {{Yes}} ||
|-
|-
| [[InspectorMemberActions (Component)]] || No || Yes ||
| [[Component:InspectorMemberActions|InspectorMemberActions]] || {{No}} || {{Yes}} ||
|-
|-
| [[InteractiveCameraSpawner (Component)]] || No || Yes ||
| [[Component:InteractiveCameraSpawner|InteractiveCameraSpawner]] || {{No}} || {{Yes}} ||
|-
|-
| [[InventoryItemUI (Component)]] || No || Yes ||
| [[Component:InventoryItemUI|InventoryItemUI]] || {{No}} || {{Yes}} ||
|-
|-
| [[RadiantDashButton (Component)]] || No || Yes ||
| [[Component:RadiantDashButton|RadiantDashButton]] || {{No}} || {{Yes}} ||
|-
|-
| [[SlotRecord (Component)]] || No || Yes ||
| [[Component:SlotRecord|SlotRecord]] || {{No}} || {{Yes}} ||
|-
|-
| [[Checkbox (Component)]] || No || Yes ||
| [[Component:Checkbox|Checkbox]] || {{No}} || {{Yes}} ||
|-
|-
| [[Expander (Component)]] || No || Yes ||
| [[Component:Expander|Expander]] || {{No}} || {{Yes}} ||
|-
|-
| [[Perspective360Panner (Component)]] || Yes || No
| [[Component:Perspective360Panner|Perspective360Panner]] || {{Yes}} || {{No}}
|-
|-
| [[Radio (Component)]] || No || Yes ||
| [[Component:Radio|Radio]] || {{No}} || {{Yes}} ||
|-
|-
| [[TextField (Component)]] || No || Yes ||
| [[Component:TextField|TextField]] || {{No}} || {{Yes}} ||
|-
|-
| [[VirtualCloseKey (Component)]] || No || Yes ||
| [[Component:VirtualCloseKey|VirtualCloseKey]] || {{No}} || {{Yes}} ||
|-
|-
| [[VirtualKey (Component)]] || No || Yes ||
| [[Component:VirtualKey|VirtualKey]] || {{No}} || {{Yes}} ||
|-
|-
| [[VirtualModifierKey (Component)]] || No || Yes ||
| [[Component:VirtualModifierKey|VirtualModifierKey]] || {{No}} || {{Yes}} ||
|-
|-
| [[VirtualMultiKey (Component)]] || No || Yes ||
| [[Component:VirtualMultiKey|VirtualMultiKey]] || {{No}} || {{Yes}} ||
|-
|-
| [[VirtualShift (Component)]] || No || Yes ||
| [[Component:VirtualShift|VirtualShift]] || {{No}} || {{Yes}} ||
|-
|-
| [[WorldCloseAction (Component)]] || No || Yes ||
| [[Component:WorldCloseAction|WorldCloseAction]] || {{No}} || {{Yes}} ||
|-
|-
| [[WorldThumbnailItem (Component)]] || Yes || Yes ||
| [[Component:WorldThumbnailItem|WorldThumbnailItem]] || {{Yes}} || {{Yes}} ||
|}
|}

Latest revision as of 23:59, 4 June 2024

Button events provide a generalized system for buttons and actions triggered by buttons within Resonite.

This abstraction allows components to define behaviors as responses to common button interactions without having to know the specific button the interaction originates from.

When a button event sender component triggers an event, it will call all corresponding button event receiver components on a single target slot, which is usually the same one it is attached to. Button events do not traverse hierarchies in the same way Dynamic Impulses do.

You can use button events in ProtoFlux by using the Button Events node.

The order in which multiple button event receiver components on the same slot are executed is not defined, as the order of components on a slot itself isn't defined and may change. If order of execution is important, consider using ProtoFlux instead!

Event Types

Button events are separated into two categories, each defining 3 event types:

Hover Events
Hover Enter
Hover Stay
Hover Leave
Press Events
Pressed
Pressing
Released

Components that act as receivers for either or both of those event categories implement IButtonPressReceiver and IButtonHoverReceiver respectively.

Button Event Data

Each button event carries event data with information about the interaction the event originates from.

Property Name Property Type
Source Component
Global Press Point Float3
Local Press Point Float2
Normalized Press Point Float2

Button Event Senders

Component Hover Events Press Events Notes
Button Yes Yes
ButtonHoverEventRelay Yes No Relays button hover events to a specifiable slot instead of its own.
ButtonPressEventRelay No Yes Relays button press events to a specifiable slot instead of its own.
LegacyButton No Yes Only supports Pressed and Released, not Pressing.
PhysicalButton No Yes
TouchButton No Yes

Button Event Receivers

Component Hover Events Press Events Notes
AudioStreamSpawner No Yes
AvatarCreatorSpawner No Yes
ButtonActionTrigger No Yes
ButtonAudioClipPlayer Yes Yes
ButtonAudioDeviceSet No Yes
ButtonClipboardCopyText No Yes
ButtonDelegateRelay´1 No Yes
ButtonDestroy No Yes
ButtonDynamicImpulseTrigger Yes Yes
ButtonDynamicImpulseTriggerWithReference´1 Yes Yes
ButtonDynamicImpulseTriggerWithValue´1 Yes Yes
ButtonEditColorX No Yes
ButtonEnumShift´1 No Yes
ButtonHoverEventRelay Yes No
ButtonHoverRelay Yes No
ButtonLoopSet Yes Yes
ButtonOpenHome No Yes
ButtonParentUnderUser No Yes
ButtonPlaybackAction Yes Yes
ButtonPlaybackSeeker No Yes
ButtonPressEventRelay No Yes
ButtonReferenceCycle´1 No Yes
ButtonReferenceSet´1 No Yes
ButtonRefRelay´1 No Yes
ButtonRelay´1 No Yes
ButtonRelay No Yes
ButtonStringAppend No Yes
ButtonStringErase No Yes
ButtonToggle No Yes
ButtonUserProfileIconSet No Yes
ButtonValueCycle´1 No Yes
ButtonValueSet´1 No Yes
ButtonValueShift´1 No Yes
ButtonWorldLink No Yes
ContactLink No Yes
ContextMenuItem Yes Yes
ContextMenuItemSource Yes Yes Despite not being a button event sender itself, it implements IButton and can therefore be used with the Button Events ProtoFlux node. (It will proxy all button events it receives.)
ContextMenuSubmenu No Yes
DataPreset No Yes
FileSystemItem No Yes
FullBodyCalibratorSpawner No Yes
GenericModalDialogSpawner´1 No Yes
GenericUserspaceDialogSpawner´1 No Yes
Hyperlink No Yes
InspectorMemberActions No Yes
InteractiveCameraSpawner No Yes
InventoryItemUI No Yes
RadiantDashButton No Yes
SlotRecord No Yes
Checkbox No Yes
Expander No Yes
Perspective360Panner Yes No
Radio No Yes
TextField No Yes
VirtualCloseKey No Yes
VirtualKey No Yes
VirtualModifierKey No Yes
VirtualMultiKey No Yes
VirtualShift No Yes
WorldCloseAction No Yes
WorldThumbnailItem Yes Yes
Retrieved from "https://wiki.resonite.com/index.php?title=Button_Events&oldid=85827"