WoW:API UnitName: Difference between revisions

← Older edit

WoW:API UnitName (source)

Revision as of 04:47, 15 August 2023

2,097 bytes added , 15 August 2023

m

Move page script moved page API UnitName to WoW:API UnitName without leaving a redirect

Anonymous user

Move page script

@@ Line 1: / Line 1: @@
-<center>'''UnitName''' ''-Documentation by [[User:Octon|octon]]-''</center>
+{{wowapi}} __NOTOC__
-Returns the name of the specified unit.
-----
+<!-- Describe the purpose of the function, exhausting detail can be saved for a later section -->
-;''Arguments''
+Returns the name and realm of the specified unit.
-:(String unit)
+<!-- List return values and arguments as well as function name, follow Blizzard usage convention for args -->
+ name, realm = UnitName("unit")
-:;arg1 : The unit to query (e.g. "player", "party2", "pet", "target" etc.)
+== Parameters ==
+=== Arguments ===
+<!-- List each argument, together with its type -->
+:("unit")
-----
+:;unit : String - The [[API TYPE UnitId|UnitId]] to query (e.g. "player", "party2", "pet", "target" etc.)
-;''Returns''
-:name
+=== Returns ===
-:;name : The name of the specified unit as a string.
+<!-- List each return value, together with its type -->
+:;name
+:: String - The name of the specified unit, "nil" if not applicable (e.g., if the specified unit is "target" but the player has no target selected).
+:;realm
+:: String - The realm the specified unit is from. For "player" returns nil, for any other character on your own realm returns an empty string. This is as of 1.12
-----
+== Example ==
-;''Example''
+<!-- If it helps, include an example here, though it's not required if the usage is self-explanatory -->
+<!-- begin code -->
   local playerName = UnitName("player");
   ChatFrame1:AddMessage('Hi my name is: ' .. playerName);
+<!-- end code -->
-;''Result''
+====Result====
- Prints the player's name to the chat frame as
+<!-- If it helps, include example results here, though they are not required. You're allowed to cheat liberally since WoW isn't a command line language. -->
-  'Hi my name is: Octon'.
+:Prints the player's name to the chat frame. e.g.
+<!-- begin code -->
+  Hi my name is: Octon
+<!-- end code -->
-----
-;''Description''
-: Returns the name of the specified unit.
+==Details==
+<!-- Details not appropriate for the main description can go here.
+     REMOVE the section if you're just going to restate the intro line! -->
-----
+* UnitName("unit") (or any other unit) will return "Unknown Entity" (Actually the value of the UNKNOWNOBJECT global) if called before the unit in question has been fully loaded into the world.
-{{Template:WoW API}}
+* The '''realm''' return will be nil even if the player is from a different realm, if it is out of visible range.
+* Realm name will not include server type
+* Note that this function always returns two values even though the latter may be nil. The difference is usually moot, but there are some cases where it matters, e.g. <span style="white-space: nowrap;"><tt>tinsert(myTable, UnitName("player"))</tt></span>, which would previously work, but will now cause errors. The fix is to put the expression in parenthesis: <span style="white-space: nowrap;" ><tt>tinsert(myTable, (UnitName("player")) )</tt></span>.
+* The default Blizzard UI defines [[API_GetUnitName|GetUnitName]](unit, showServerName) which only returns the unit name, but for characters from another server appends the server name (showServerName==true) or "(*)" (if showServerName==false).
+[[Category:World of Warcraft API]]