Class Index | File Index

Classes


Class com.jiffeegames.Display

A Display object manages the output to the display. It accepts output from the rest of the program (usually in units of complete sentences), translates them as needed, sanitizes any user-input that is being re-displayed, and accumulates all the output in a buffer until it is needed.
Defined in: jiffee-display.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Create a Display object.
Method Summary
Method Attributes Method Name and Description
 
Compare two translation tables for consistency.
 
Erase the last thing shown.
 
Get the entire string which should be displayed to the user.
 
Return the current change sequence number.
 
init(locate, language)
<private>  
sanitize_(str)
Sanitize a string to make it safe for output by removing any HTML markup.
 
Define the desired action if a string has no translation specified.
 
show(template, args)
Display a formatted string to the user.
<private>  
translate_(from)
Translate a single string from internal/canonical form into the target language.
 
translateTo(from, to)
Define an output translation.
Class Detail
com.jiffeegames.Display()
Create a Display object. The normal call is
var display = com.jiffeegames.Display();
Method Detail
{void} compareTranslations(other)
Compare two translation tables for consistency. Assume the translation table in this Display object is correct, and compare it to the translation table in the "other" Display object. Throw an exception if they don't have exactly the same keys (i.e. "from" values), otherwise return silently.

This is intended to be used by game translators. If you have one translation (e.g. English) that has been thoroughly tested to make sure it includes all the needed strings, you can use this function to quickly compare it to a different version of your game (e.g. Spanish) without having to repeat all the tests just to find missing entries in the other table.

Parameters:
{Display} other
Another display object.

{void} erase()
Erase the last thing shown.

{String} getAndClearOutput()
Get the entire string which should be displayed to the user. This is the concatenation of everything which has been passed to "show()".
Returns:
Everything that should be displayed, as one long string.

{int} getSeq()
Return the current change sequence number.

init(locate, language)
Parameters:
locate
language

<private> {String} sanitize_(str)
Sanitize a string to make it safe for output by removing any HTML markup. This needs to be called whenever user input is displayed on the screen, so that the user cannot accidentally or deliberately mess up the display formatting by typing in HTML.
Parameters:
{String} str
The string to be sanitized.
Returns:
The santized version of the input string.

{void} setStrictTranslation(strict)
Define the desired action if a string has no translation specified. The default is strict=false, because even though displaying an untranslated string to the player is very bad form, it's still a lot better than having the game crash.

This setting is intended for use by game authors during testing: When you write a game that is intended to be friendly to translators, you should set strict=true, so that you will get an error whenever you try to output a string which has no translation. If you only speak English it's perfectly fine to translate English-to-English; the idea is just to ensure that there is a translateTo() call for every output string.

This will then make it much easier for somebody else, who is perhaps not a good programmer but who is fluent in the languages involved, to actually do the translation in a straightforward and reliable way.

Parameters:
{Boolean} strict
true if undefined translations should cause an error.

{void} show(template, args)
Display a formatted string to the user. Consecutive calls to this method will be handled efficiently, because the final string concatenation is not done until you actually retrieve the entire results. Example:
display.show('The ${1} has no effect on the ${2}.', 'wand', 'mouse');
which will output
The wand has no effect on the mouse.
It is important to use this function, rather than building up strings "by hand" using concatenation, since this method allows much easier translation into other languages.
Parameters:
{String} template
The basic form of the string to be displayed.
{String} args
Zero through nine arguments, which will be substituted for ${1} through ${9} in the template.

<private> {String} translate_(from)
Translate a single string from internal/canonical form into the target language. If no translation is defined, it returns the input unchanged.
Parameters:
{String} from
The desired output in internal form. If the argument is of the form {literal:somestring}, then no translation is performed, but the string will be sanitized.
Throws:
Error with a jiffeeCode if the args are bad.
Returns:
The translation of the output into the target language.

{void} translateTo(from, to)
Define an output translation.
Parameters:
{String} from
The output in internal/canonical form.
{String} to
The translation of the output into the target language. If "null", then translation does not alter this string.
Throws:
Error with a jiffeeCode if the args are bad.

Documentation generated by JsDoc Toolkit 2.3.2 on Sun Jul 25 2010 13:49:30 GMT-0700 (PDT)