Editing ShowMessage

{{Function
 |origin = GECK1
 |summary = [[ShowMessage]] is used to display [[message|messages]] to the player.  The message itself is an editor object that contains all the data: display text, type of message, and buttons (if the message is a message box).
 |arguments = {{FunctionArgument
  |Name = MessageID
  |Type = ref
 }}{{FunctionArgument
  |Name = var1
  |Type = var
 }}{{FunctionArgument
  |Name = var2
  |Type = var
 }}{{FunctionArgument
  |Name = ...
 }}{{FunctionArgument
  |Name = var9
  |Type = var
 }}{{FunctionArgument
  |Name = Duration
  |Type = int
  |Optional = true
 }}
The number of ''var'' parameters required is equal to the number of [[ShowMessage#Formatting_messages|format specifiers]] in the specified message's content, up to a maximum of 9.
 |example = ShowMessage MyMessage
Shows ''MyMessage''.
 ShowMessage TimeScaleMessage TimeScale
Shows ''TimeScaleMessage'', and inserts the value stored in ''TimeScale'' into it.  In order for this to work, ''TimeScaleMessage'' must have the appropriate [[ShowMessage#Formatting_messages|format specifier]] to display a floating point value.
}}

==Notes==
* This command replaces the "Message" and "MessageBox" functions of Oblivion and Morrowind.
* Buttons are part of the Message form. If no buttons are specified on a MessageBox type message, a default "OK" button will be displayed.
* Message Type on the Message determines whether we are displaying a "message" (upper right corner, single line of text, doesn't interrupt the game) or a "message box" (center of the screen, game stops until the player presses one of the buttons).
* Variables can be inserted into the displayed text (see below). The message will fail to display if the wrong number of variables are passed into the ShowMessage call.
* Variables cannot be inserted into a message box's buttons.
* The "Duration" parameter doesn't actually do anything

==Formatting messages==
Variable parameters can be used in conjunction with a Message in order to insert variables into the displayed text.
* Use the formatting notation below in the text of the Message.
* The number of parameters called by ShowMessage must match the number of variables the message is expecting.

====Formatting notation====

'''%.2f''' - This means format the variable with 2 decimal places. 

'''%.0f''' - This will format the variable with 0 decimal places, so is the normal choice for integers. 

'''%5.0f''' - The number in front of the point specifies the minimum width of the number. In this case, there will always be enough space in front of the number for 5 digits:
 Number    12 wins
 Number  1234 wins

====Formatting switches====

The following formatting switches can be used in Messages. Put them in any sequence right after the '%' 
{|border="1" cellpadding="5" cellspacing="0" 
|-
! style="background:#efefef;" | Switch
! style="background:#efefef;" | Function
|-
|<nowiki>+</nowiki>
|Display + in front of positive numbers 
|-
|<nowiki><Space></nowiki>
|Leave a leading space in front of positive numbers
|-
|<nowiki>-</nowiki>
|Use left-aligned formation instead of right alligned.
|-
|<nowiki>0</nowiki>
|The filling-char used for formatting is '0' instead of ' '
|}

====Other Functions====

'''%g''' - This usually works just like "%.0f", displaying 0 decimal places. When the number is 1000000 or larger, though, the game diplays it in scientific notation (1E+006)

'''%.3e''' - Shows numbers in scientific notation (123000 = 1.23E+005)

'''%%''' - Use this to display a percent-sign in the message

'''[[sUActn|&sUActn...]]''' - Allows you to insert the key used for a given control, such as the Activate button, the Always Run button, or the Block button.  See the '''[[sUActn]]''' article for the list of control codes.

====FOSE Switches====

'''%r''' - Prints a carriage return, ending the current line and starting at the next.

'''%n''' - Prints the name of the specified reference or object.

'''%i''' - Prints the formID of the specified reference or object. GOTCHA : if a refVar is passed which points to a ref not loaded in memory %i will print 00000000 ''even if the refVar is not empty''.

'''%k''' - Prints the name of the key for the specified DirectInput scancode.

'''%c''' - Prints the specified component of the specified reference or object. Takes two arguments - a reference variable set to the spell or faction, and an index. Behaves differently depending on the passed reference:
:* Faction: Prints the ''n''th male rank title
:* Magic Item: Prints the ''n''th Magic Effect

'''%p''' - Displays a pronoun based on the gender of the object parameter:
:* %po - objective  (him, her, it)
:* %pp - possessive (his, her, its)
:* %ps - subjective (he, she, it)

'''%q''' - Prints a double quote character.

'''%a''' - Prints the character corresponding to the specified ASCII code. Passing codes for unprintable characters (such as 0) may have unpredictable (though occasionally useful) results. Passing the code for a percent sign will most likely crash the game as literal percent signs must come in pairs.

'''%v''' - Prints the actor value (i.e. an attribute or skill) associated with the passed actor value code.

'''%e''' - Provides a workaround for the script compiler's refusal to accept an empty string as a command argument.
* Example:
 SetName "" object    ; attempts to remove an object's name, but won't compile
 SetName "%e" object  ; sets the name to an empty string

'''%{...%}''' - Conditionally displays or omits the bracketed portion of the format string based on a boolean value. Accepts a variable - if the value of the variable is zero, all text and parameters up to the matching right bracket will be ignored. Otherwise the bracketed text will be displayed.
* Example (should be single-line, line-breaks added for Wiki)
 MBoxEX "Doom comes%{ for you%}. What will you do?
 |Dig a hole, hide
 %{|Find someone, offer as sacrifice|Find someone, use as shield%}
 |Enjoy your final 15 minutes" bDisplay bDisplay
If bDisplay is 0 this will print out
    Doom comes. What will you do?
    [Dig a hole, hide]
    [Enjoy your final 15 minutes]
If bDisplay is 1 this will print out
    Doom comes for you. What will you do?
    [Dig a hole, hide]
    [Find someone, offer as sacrifice]
    [Find someone, use as shield]
    [Enjoy your final 15 minutes]

=='''See Also'''==
*[[ShowWarning]]
*[[Message]]
*[[Adding an Options Menu]]

[[Category: Functions]]
[[Category: Functions (GECK 1.1)]]
[[Category: Miscellaneous Functions]]
[[Category: Miscellaneous Functions (GECK 1.1)]]