Adding UI Hints

Simple Hint

Step 1: 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 2: Trigger the hint using the notifications system:

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

That handles the simple case.

Customizing the Hint

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

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;

You can add string substitutions in the substitutions parameter.

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

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!