EUI Tooltips - SevenDayCandle/STS-EUI GitHub Wiki

Introduction

EUITooltip is an alternative to the base game's PowerTip class for rendering tooltips. It offers a number of benefits over the original tip class:

Types of EUITooltip

There are a number of flavors of EUITooltip for more specialized needs

  • EUIHeaderlessTooltip: Tooltip that has no title
  • EUIKeywordTooltip: Tooltip that represents a basegame keyword. These can have icons next to their names, as well as headers from the mods that they originate from.
  • EUIPaginatedTooltip: Tooltip with multiple pages of descriptions, which can be cycled through by pressing Ctrl (this key can be configured).
  • EUITourTooltip: Tooltip used in interactive tutorials

Rendering Tooltips

To render EUITooltips on the screen, you should call one of the various tooltip queueing methods on EUITooltip in an update or render method. There are a number of variants available depending on your particular use case

Name Parameters Description
queueTooltip tooltip (EUITooltip) Queue the given tip for rendering at your mouse cursor's position
queueTooltip tooltip (EUITooltip), x (float), y (float) Queue the given tip for rendering at the given x/y coordinates
queueTooltips tooltips (Collection<? extends EUITooltip>) Queue the given tip collection for rendering at your mouse cursor's position
queueTooltips tooltips (Collection<? extends EUITooltip>), x (float), y (float) Queue the given tip collection for rendering at the given x/y coordinatesposition
queueTooltips creature (AbstractCreature) Queue tips derived from the target creature's intent and powers at that creature's position
queueTooltips card (AbstractCard) Queue tips derived from the target card at that card's position
queueTooltips blight (AbstractBlight) Queue tips derived from the target blight
queueTooltips potion (AbstractPotion) Queue tips derived from the target potion
queueTooltips relic (AbstractRelic) Queue tips derived from the target relic

Note that only the first call to queueTooltips in an update/render cycle will get rendered. Tooltip rendering will occur AFTER CardCrawlGame's normal rendering cycle (i.e. it will always appear above other rendered elements unless that rendered element was rendered with EUI's priority or post-priority rendering methods).

TooltipProvider

TooltipProvider is an interface that lets a AbstractCreature/AbstractCard/AbstractBlight/AbstractPotion/AbstractRelic control what tips are queued in their respective queueTooltips methods. It has the following methods:

Name Parameters Return Value Description
getTips List<? extends EUITooltip> List of EUITooltips associated with this object. To maximize performance, this list should be cached. You are required to implement this.
getTipsForRender List<? extends EUITooltip> List of EUITooltips that should be rendered with queueTooltips. This defaults to getTips, but this may be customized if you wish to render additional tips in queueTooltips.

KeywordProvider

KeywordProvider is a variant of TooltipProvider whose tooltips are guaranteed to be EUIKeywordTooltips.

Name Parameters Return Value Description
getTips List<? extends EUIKeywordTooltip> List of EUIKeywordTooltips associated with this object. To maximize performance, this list should be cached. You are required to implement this.
getTipsForRender List<? extends EUIKeywordTooltip> List of EUIKeywordTooltips that should be rendered with queueTooltips. This defaults to getTips, but this may be customized if you wish to render additional tips in queueTooltips.
getTipsForFilters List<? extends EUIKeywordTooltip> Used to determine what keywords are present on the object when filtering them with compendium filters. This defaults to getTips, but this may be customized if you wish to add or remove keywords from this object in the filter (e.g. removing the leading name tooltip from relics and potions)

EUIKeywordTooltip

An EUIKeywordTooltip is generated for every keyword that gets registered through BaseMod. Every EUIKeywordTooltip is given an ID that matches the identifier that would be used in a card description to reference that keyword. For example, if your mod was called mymod and it introduced a keyword called Help Me, the ID of the generated EUIKeywordTooltip would be mymod:Help_Me. Base game keywords do not have prefixes (e.g. the ID for Vulnerable would simply be Vulnerable).

To find a particular EUIKeywordTooltip, you can use one of two methods:

Name Parameters Return Value Description
EUIKeywordTooltip.findByID id (String) EUIKeywordTooltip Returns the EUIKeywordTooltip with the given id
EUIKeywordTooltip.findByName name (String) EUIKeywordTooltip Returns the EUIKeywordTooltip matching the given name. These names are pulled from the NAMES property of the keyword that was used to create this tooltip, and should be in lowercase.

Manually Registering Tooltips

If you only plan to have your keywords rendered with EUI (i.e. via cards made with Fabricate), you can also directly register keywords with EUI in lieu of registering them with Basemod via the following command:

Name Parameters Return Value Description
EUI.registerKeywords keywords (Map<String, EUIKeyword>) ArrayList Registers a collection of keywords with EUI. Each entry in the map is given the ID specified by its key, and its value (an EUIKeyword object) contains the text that will be shown to the user.
EUI.registerKeywords handle (FileHandle) ArrayList Calls the above method with a map read from an external file. This must be a JSON file with object keys that match that of the IDs that you wish to register each keyword with.

EUIKeyword objects contain the following fields (all Strings):

  • NAME: (Required) The title of the keyword that is shown to the user
  • DESCRIPTION: (Required) The description of the keyword that is shown to the user
  • PAST: If this keyword represents a verb, this should hold the past tense version of its name
  • PLURAL: If this keyword represents a noun, this should hold an EUISmartText dynamic text block with conditions for both the singular and plural forms of this word. Note that a keyword may have both PAST/PRESENT/PROGRESSIVE fields and a PLURAL field
  • PRESENT: If this keyword represents a verb, this should hold the present tense version of its name
  • PROGRESSIVE: If this keyword represents a verb, this should hold the present progressive tense version of its name. If omitted, this will fall back on the PRESENT field

For examples of EUIKeywords, see https://github.com/SevenDayCandle/STS-EUI/blob/master/src/main/resources/localization/extendedui/eng/KeywordStrings.json

EUITourTooltip

EUITourTooltip can be used to implement steps in "tour"-styled tutorials, where various UI elements are highlighted and explained in succession. Each "step" of the tutorial is configured to progress with a specific event defined in that step's constructor:

Name Parameters Description
EUITourTooltip waitOnHitbox (Hitbox), title (String), description (String) Creates a EUITourTooltip with the given title and description, which progresses when clicking on the specified Hitbox.
EUITourTooltip waitOnAction (Class<? extends AbstractGameAction>), title (String), description (String) Creates a EUITourTooltip with the given title and description, which progresses when AbstractDungeon.actionManager.currentAction's type matches that of waitOnAction.
EUITourTooltip provider (TourProvider), title (String), description (String) Creates a EUITourTooltip with the given title and description, which progresses through a custom condition specified by provider.

EUITourTooltip has additional fields to customize its appearance and behavior

Name | Type | Description canDismiss | boolean | If true, you can also progress this tooltip simply by clicking anywhere on the screen linkedImage | EUIImage | If set, this image component will flash when this tooltip is

Rendering Tutorials

EUITourTooltips are queued with their own class's queueTutorial methods instead of EUITooltip's queueTooltip methods.

Name Parameters Description
queueTutorial tooltip (EUITourTooltip) Adds this tooltip to the back of the tour queue.
queueTutorial tooltip (EUITourTooltip[]) Adds the specified tooltips to the back of the tour queue in the order of the original array.
queueTutorial tooltips (Iterable<? extends EUITourTooltip>) Adds the specified tooltips to the back of the tour queue in the order that the iterator spits them out in.
queueTutorial screen AbstractDungeon.CurrentScreen, tooltip (EUITourTooltip) Adds this tooltip to the back of the tour queue, to be rendered and progressed only if the specified run screen is active
queueTutorial screen AbstractDungeon.CurrentScreen, tooltip (EUITourTooltip[]) Adds the specified tooltips to the back of the tour queue in the order of the original array, to be rendered and progressed only if the specified run screen is active
queueTutorial screen AbstractDungeon.CurrentScreen, tooltips (Iterable<? extends EUITourTooltip>) Adds the specified tooltips to the back of the tour queue in the order that the iterator spits them out in, to be rendered and progressed only if the specified run screen is active
queueTutorial screen MainMenuScreen.CurScreen, tooltip (EUITourTooltip) Variant of the run screen method for main menu screens
queueTutorial screen MainMenuScreen.CurScreen, tooltip (EUITourTooltip[]) Variant of the run screen method for main menu screens
queueTutorial screen MainMenuScreen.CurScreen, tooltips (Iterable<? extends EUITourTooltip>) Variant of the run screen method for main menu screens

EUITourTooltips are rendered on a first-come, first-serve basis.

Utility Methods

Name Parameters Return Value Description
clearTutorialQueue void Remove all queued tour steps
getNext EUITourTooltip Get the current EUITourTooltip to be rendered
hasTutorial tip (EUITourTooltip) boolean Returns true if the given tip is queued for rendering
isQueueEmpty boolean Returns true if are no tutorials being rendered

TourProvider

TourProvider allows you to set up a custom event to determine when a EUITourTooltip should progress or not. It should implement the following method:

Name Parameters Return Value Description
isComplete boolean Whether the EUITourTooltip attached to this provider can progress or not.

Notes

  • EUITooltips do NOT extend PowerTip. This means that you cannot store EUITooltips in existing lists that check for PowerTip or use them with base game tip rendering methods.
  • EUIKeyword do NOT extend the existing keyword objects from the base game or StsLib
  • While the IDs of basegame keyword and keywords directly registered with EUI are language-agnostic (i.e. Vulnerable will always have the same ID regardless what the game's language is set to), the IDs of custom keywords picked up from BaseMod DO vary with language. As such, if you need to reference a specific keyword from a mod that was not registered with EUI, you will need to have multiple checks for each language that mod supports.