Adding UI Hints

Simple Hint

Step 1: Make sure you have the necessary include file.

#include "llnotifications.h"

Step 2: add a notification to notifications.xml using the following template.

<notification
name="HintName"
label="Hint text that appears on top"
type="hint"
unique="true">
  Hint contents here.
</notification>

unique="true" limits the number of instances of this hint to 1...if you want to spawn the same hint in multiple locations simultaneously, remove this line.

Step 3: Trigger the hint using the notifications system.

LLNotifications::instance().add(LLNotification::Params("HintName"));

That handles the simple case.

Customizing the Hint

If you want to customize the appearance/contents of the hint...

Step 1: You can modify the hint parameters via the notification "payload". The hint parameters can be found in llhint.h.

LLSD hint_payload;
hint_payload["fade_in_time"] = 2.f;
hint_payload["fade_out_time"] = 1.f;

Step 2: You can add string substitutions in the substitutions parameter.

LLSD substitutions;
substitutions["USER_NAME"] = "Richard Linden";

Step 3: Then trigger the hint with the expanded add function.

LLNotifications::instance().add(LLNotification::Params().
  name("HintName").
  substitutions(string_substitutions).
  payload(hint_payload)));

Attaching Hints

If you want to attach the hint to an existing UI element:

Step 1: Register the UI element with a unique name in the setup code associated with that particular UI.

BOOL LLMyFloater::postBuild()
{
  LLHints::registerHintTarget("my_hint_target", getChild<LLButton>("my_button")->getHandle());
  return TRUE;
}

Step 2: Trigger the notification with the target parameter set.

LLSD hint_payload;
hint_payload["target"] = "my_hint_target";
hint_payload["direction"] = "left"; // hint will appear to the left of the target

LLNotifications::instance().add(
  ...
  payload(hint_payload)));

First Use Only

If you want to trigger the hint only the first time a certain condition is met, use LLFirstUse.

Step 1: Add a setting to ignorable_dialogs.xml so we can remember when a condition has already been triggered, like this:

<key>FirstJump</key>
<map>
  <key>Comment</key>
  <string>Shows hint when resident jumps for the first time</string>
  <key>Persist</key>
  <integer>1</integer>
  <key>Type</key>
  <string>Boolean</string>
  <key>Value</key>
  <integer>1</integer>
</map>

Step 2: Add a method to LLFirstUse to trigger the hint.

void jumping(bool enable=true);

// static
void LLFirstUse::jumping(bool enable)
{
  LLSD substitutions;
  ...
  LLSD hint_payload;
  ...
  firstUseNotification("FirstJump", enable, "HintJump", substitutions, hint_payload);
}

Step 3: Call the first use function when the behavior is triggered.

void LLAgent::jump()
{
  ...
  LLFirstUse::jumping(true);
}

Step 4: Call the first use function with false to immediately disable the hint.

// after 10 minutes, we assume you know how to jump
LLFirstUse::jumping(false);

That's it!