Modular Button Component Tutorial – Arma Reforger
The Modular button component is a system which consists of a button component itself and various effects attached to it. The aim of the system is to separate the effect types (animation, opacity, color, text, image, ...) from when they can happen (on click, or hover, on toggle, on focus, ...).
Usage
- Create a layout containing a Button widget
- Add the SCR_ModularButtonComponent to the button - it is also possible to drag and drop a config of SCR_ModularButtonComponent type
- Add Effects to the Effects array the component provides. Effects represent the properties of widgets under the button that you want to change, and the events on which you want to change them
- Specify the name of the widget whose properties are to be changed, and what the new value for each state change or event should be
- Different Effects offer different attributes, based on the type of property that will be modified.
- Keep in mind that there is not really an underlying state machine for the button: when an event triggers, the Effect will apply the new value to the property, and that's it.
- By using tags, you can give a custom identifier to the effects. The SCR_ModularButtonComponent API then allows you to find effects through their tags and thus control which effects should be active at a time.
- Define the button's behaviour
- These settings provide useful functionalities about how the button should behave in the UI hierarchy, from flagging itself as toggled when clicked, to moving focus to itself when hovered for consistent menu navigation between keyboard, mouse and gamepad.
- A notable attribute is the Event Return Value one, which controls how interaction events from widgets are propagated up the hierarchy: flagging an interaction will prevent the event from being propagated, which is useful, for example, when nesting multiple interactable widgets inside each other so that the ones higher in the hierarchy do not receive the events generated by the lower ones.
- Use the hierarchy Prefab in other layouts
SCR_ModularButtonComponent
The component itself is simple, it also has all the common usual ScriptInvokers for a button, such as Clicked, Toggled, Focused, Hovered, etc.
Effect Attributes
| Class | Description |
|---|---|
| SCR_ButtonEffectColor | Animates color |
| SCR_ButtonEffectImage | Sets image texture for an image widget. Supports imageset too. |
| SCR_ButtonEffectOpacity | Animates opacity |
| SCR_ButtonEffectPadding | Animates padding |
| SCR_ButtonEffectPosition | Animate/set position of a widget |
| SCR_ButtonEffectSize | Animate/set size of a widget |
| SCR_ButtonEffectText | Sets text of a text widget |
| SCR_ButtonEffectSound | Plays a sound |
| SCR_ButtonEffectVisibility | Sets a widget visible/invisible |
| SCR_ButtonEffectSlaveButton | Passes events to another button within this button |
Enabled
Effect is enabled or disabled. When disabled, it ignores events.
Events
Events to which this effect listens.
- STATE - events are always mutually exclusive. All buttons can be in one of these states: DEFAULT, HOVERED, DISABLED. Toggle-buttons additionally have these states: ACTIVATED, ACTIVATED_HOVERED.
- EVENT - events are not exclusive and can happen in any combinations: CLICKED, FOCUS_GAINED, FOCUS_LOST, TOGGLED_ON, TOGGLED_OFF.
Input Devices
Input devices which this effect listens to. This is useful to implement different behaviour for gamepad and mouse control schemes.
Widget Name
The name of widget which will be affected by this effect. Not all effects are required to have it. For instance, a Play Sound effect doesn't interact with any widgets.
Tags
An effect can have many string tags. You can enable/disable/find effects by their tags. It is useful for more complex behaviours, for instance if a button must operate in multiple modes.
Event-Specific Attributes
Typically effects should have an attribute per each event type. For instance, Color Effect will have 10 color attributes - one for each event type.
Effect Title
The effect's title sums up its properties, generated based on its settings, e.g:
Runtime API
Tags are very powerful when you need to implement many operation modes on the same button. You can just predefine different effects in layout and enable or disable them at runtime:
You might need to change button effect's values to something that cannot be predefined. In this case, call ceffect.PropertiesChanged() after modifying properties, they will be re-applied according to the current state.