Unreal UI Overlay Widgets

Document Summary: Description of overlay widgets such as tooltips and context menus.

Document Changelog: Preston Thorne adding UI Overlay Widgets info.

Tooltips

UIObject now has a ToolTip data store binding. This binding controls what will appear in the widget's tooltip if you hover over the widget (usually just bind it to a localized string). The default behavior is that there is a single tooltip widget for each scene (since only one tooltip should ever be shown at a time). When you mouse over a widget, the widget copies its ToolTip data store binding to the scene's global tooltip object and start the tooltip's delay timer. You can provide a custom tooltip object by handling the OnQueryTooltip delegate, but if you do, you'll need to perform all the steps inside UIObject::ActivateToolTip yourself.

Related Methods:

• GameUISceneClient.CanShowToolTips - if this returns false, no tooltips will ever be shown.
• UIObject::ActivateToolTip - propagates the widget's ToolTip binding to the scene's default tooltip
• UIObject.delegateOnQueryToolTip - allows you to provide a custom tooltip object for you widget.
• UIToolTip.delegateActivateToolTip() - called as soon as the mouse enters the bounds for a widget. Allows you to prevent the tooltip from appearing if you want. Default behavior is to start the timer for showing the tooltip after a small delay. This is where you'd set the tooltip's data binding dynamically if you wanted.
• UIToolTip.delegateDeactivateToolTip() - called when the scene's ActiveControl changes. Allows you to prevent the tooltip from being hidden if you want. Default behavior is to hide the tooltip.

Related Variables

• GameUISceneClient.bDisableToolTips - globally disables tooltips. This value is checked by CanShowToolTips.
• UIInteraction.ToolTipInitialDealySeconds - controls how many seconds pass after the mouse enters a widget's bound before the tooltip appears.
• UIInteraction.ToolTipExpirationSeconds - controls how many seconds before the tooltip disappears on its own (i.e. if you don't move the mouse after moving over a widget).

Flow

When the scene's ActiveControl is changed in SetActiveControl(), ActivateToolTip is called on the new ActiveControl. UIObject.ActivateToolTip() first calls the OnQueryToolTip delegate to allow script the chance to override the default behavior. If OnQueryToolTip returns FALSE and the widget's ToolTip binding is valid, the scene's global tooltip widget is activated (i.e. its initial delay seconds timer is activated), and UIToolTip::LinkBinding is called to link the ActiveControl='s =ToolTip binding to the scene's default tooltip widget. Each frame, the tooltip widget is ticked by UGameUISceneClient::Tick(). Once the ToolTipInitialDelaySeconds have passed, the tooltip formats, positions, and shows itself. The scene client continues to tick the tooltip each frame. Once ToolTipExpirationSeconds have passed, the tooltip hides itself.

Context Menus

UIObject now has a context menu data binding. This binding defines where a context menu's items come from. You can also manually add and remove items to the context menu via UnrealScript before a context menu is shown. If the active control doesn't support context menus, each widget in its parent chain will be given the chance to provide one.

Related Methods

• UIObject::ActivateContextMenu - propagates the widget's ContextMenu data binding to the scene's global context menu widget and opens the context menu.
• UIObject.delegateOnOpenContextMenu - allows you to provide a custom context menu for the widget. This is also where you'd add/remove/etc. items in UnrealScript.
• UIObject.delegateOnCloseContextMenu - called when the UI system wants to close the currently active context menu. Allows you to override and prevent the context menu from being closed.
• UIObject.delegateOnContextMenuSelected - called when the user clicks or selects an item in the context menu. Here's where you perform the logic for the action chosen.
• UIContextMenu::Open - performs all the steps needed to display the context menu (calculating the position where the context menu should appear, populating the context menu's list, setting focus to the menu, etc.).
• UIContextMenu::Close - performs all the steps needed to close the context menu and return the scene to normal mode (restoring focus to the previously focused control, hiding the context menu, etc.). * UIContextMenu script methods - methods which allow manually adding, removing, and getting context menu items from UnrealScript or C++.

Related Variables

• UIObject.ContextMenu - a data binding property which provides the context menu's items. No need to fill in if you're going to build the context menu items dynamically from script.

Flow

When UIObject::ProcessInputKey receives a right mouse button release event, it calls ActivateContextMenu to get a valid context menu reference. If the widget doesn't support a context menu, the call is passed up the parent hierarchy to allow parent widgets to provide a context menu. ActivateContextMenu first calls the OnOpenContextMenu delegate to allow script to provide one (script also has the option to use the scene's default context menu but manually add items to it in script - see UIButton for an example). If a valid context menu is returned, ActivateContextMenu then calls Open on the context menu. UIContextMenu::Open gets the current mouse position and positions the context menu at that point, then populates the list and manually resolves the list's render bounds to ensure that the context menu doesn't pop into a different position the second render frame. When the user chooses a selection, the OnContextMenuSelected delegate is called to notify UnrealScript, then Close() is called to hide the context menu and return focus/input control to normal.