Difference between revisions of "Adding UI Hints"

From Second Life Wiki
Jump to navigation Jump to search
m (fixed syntax highlighting)
(Page repair. <xml></xml>/<cpp></cpp> replaced with <syntaxhighlight lang="xml"></syntaxhighlight>/<syntaxhighlight lang="cpp"></syntaxhighlight>)
 
(One intermediate revision by one other user not shown)
Line 2: Line 2:


'''Step 1: Make sure you have the necessary include file.'''
'''Step 1: Make sure you have the necessary include file.'''
<c>
<syntaxhighlight lang="cpp">
#include "llnotifications.h"
#include "llnotifications.h"
</c>
</syntaxhighlight>


'''Step 2: add a notification to notifications.xml using the following template.'''
'''Step 2: add a notification to notifications.xml using the following template.'''
<xml>
<syntaxhighlight lang="xml">
<notification
<notification
name="HintName"
name="HintName"
Line 15: Line 15:
   Hint contents here.
   Hint contents here.
</notification>
</notification>
</xml>
</syntaxhighlight>


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.
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.
Line 21: Line 21:
'''Step 3: Trigger the hint using the notifications system.'''
'''Step 3: Trigger the hint using the notifications system.'''


<c>
<syntaxhighlight lang="cpp">
LLNotifications::instance().add(LLNotification::Params("HintName"));
LLNotifications::instance().add(LLNotification::Params("HintName"));
</c>
</syntaxhighlight>


That handles the simple case.
That handles the simple case.
Line 33: Line 33:


'''Step 1: You can modify the hint parameters via the notification "payload".  The hint parameters can be found in llhint.h.'''
'''Step 1: You can modify the hint parameters via the notification "payload".  The hint parameters can be found in llhint.h.'''
<c>
<syntaxhighlight lang="cpp">
LLSD hint_payload;
LLSD hint_payload;
hint_payload["fade_in_time"] = 2.f;
hint_payload["fade_in_time"] = 2.f;
hint_payload["fade_out_time"] = 1.f;
hint_payload["fade_out_time"] = 1.f;
</c>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
LLSD substitutions;
LLSD substitutions;
substitutions["USER_NAME"] = "Richard Linden";
substitutions["USER_NAME"] = "Richard Linden";
</c>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
LLNotifications::instance().add(LLNotification::Params().
LLNotifications::instance().add(LLNotification::Params().
   name("HintName").
   name("HintName").
   substitutions(string_substitutions).
   substitutions(string_substitutions).
   payload(hint_payload)));
   payload(hint_payload)));
</c>
</syntaxhighlight>


== Attaching Hints ==
== Attaching Hints ==
Line 61: Line 61:
'''Step 1: Register the UI element with a unique name in the setup code associated with that particular UI.'''
'''Step 1: Register the UI element with a unique name in the setup code associated with that particular UI.'''


<c>
<syntaxhighlight lang="cpp">
BOOL LLMyFloater::postBuild()
BOOL LLMyFloater::postBuild()
{
{
Line 67: Line 67:
   return TRUE;
   return TRUE;
}
}
</c>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
LLSD hint_payload;
LLSD hint_payload;
hint_payload["target"] = "my_hint_target";
hint_payload["target"] = "my_hint_target";
Line 79: Line 79:
   ...
   ...
   payload(hint_payload)));
   payload(hint_payload)));
</c>
</syntaxhighlight>


== First Use Only ==
== First Use Only ==
Line 87: Line 87:
'''Step 1: Add a setting to ignorable_dialogs.xml so we can remember when a condition has already been triggered, like this:'''
'''Step 1: Add a setting to ignorable_dialogs.xml so we can remember when a condition has already been triggered, like this:'''


<xml>
<syntaxhighlight lang="xml">
<key>FirstJump</key>
<key>FirstJump</key>
<map>
<map>
Line 99: Line 99:
   <integer>1</integer>
   <integer>1</integer>
</map>
</map>
</xml>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
void jumping(bool enable=true);
void jumping(bool enable=true);


Line 115: Line 115:
   firstUseNotification("FirstJump", enable, "HintJump", substitutions, hint_payload);
   firstUseNotification("FirstJump", enable, "HintJump", substitutions, hint_payload);
}
}
</c>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
void LLAgent::jump()
void LLAgent::jump()
{
{
Line 125: Line 125:
   LLFirstUse::jumping(true);
   LLFirstUse::jumping(true);
}
}
</c>
</syntaxhighlight>


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


<c>
<syntaxhighlight lang="cpp">
// after 10 minutes, we assume you know how to jump
// after 10 minutes, we assume you know how to jump
LLFirstUse::jumping(false);
LLFirstUse::jumping(false);
</c>
</syntaxhighlight>


That's it!
That's it!

Latest revision as of 03:58, 19 April 2016

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!

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Adding_UI_Hints&oldid=1199936"