LogDisplay

The LogDisplay provides a scrolling display to view any number of TextLogs.

Summary

LogDisplay	The LogDisplay provides a scrolling display to view any number of TextLogs.
Implementation Details	The LogDisplay works in conjuction with the TextLog element to provide the an in-game visual display for the log entries.
XML Definition	This is the LogDisplay XML definition.
XML Tag
Required Attributes	You need to specify valid values for all of these elements to get the LogDisplay to create properly.
font	The name of the Font definition to use.
Optional Attributes	These are optional.
scrollbar	The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .
background	The name of a FullResizeImage to use as a background.
linespacing	An override value for the font line spacing.
maxchars	The maximum number of characters allowed to be displayed.
maxentries	The maximum number of entry lines to be displayed for each text log shown.
textFadeTime	The amount time the text should remain on the screen after a new entry is added.
autoHideScrollBar	Auto-hides the scroll bar when the window the contents current LogDisplay contents fill less than one page.
Functions
Functions
LogDisplayAddLog()	Adds the specified TextLog to the LogDisplay
LogDisplayRemoveLog()	Removes the specified TextLog to the LogDisplay
Functions
Functions
LogSetLimit()	Sets the maximum number of entries to display in the LogDisplay.
LogDisplaySetShowTimestamp()	Sets if the timestamps should be display at the beginning of each entry.
LogDisplayGetShowTimestamp()	Return if the timestamps is currently displayed at the beginning of each entry.
LogDisplaySetShowLogName()	Sets if the TextLog name should be display at the beginning of each entry.
LogDisplayGetShowLogName()	Returns if the TextLog name is currently displayed at the beginning of each entry.
LogDisplaySetShowFilterName()	Sets if the Filter Type name should be display at the beginning of each entry.
LogDisplayGetShowFilterName()	Returns if the Filter Type name is currently displayed at the beginning of each entry.
LogDisplaySetFilterColor()	Sets the text color to use for the specified TextLog and Filter Type.
LogDisplayGetFilterColor()	Returns the color currently used for the specified TextLog and Filter Type.
LogDisplaySetFilterState()	Sets the specified Filter Type for the specified TextLog should be displayed.
LogDisplayGetFilterState()	Returns if the specified Filter Type for the specified TextLog is currentlydisplayed.
LogDisplayHideFilterSubType()	Sets if a filter sub type should be shown.
LogDisplaySetTextFadeTime()	Sets the amount of time the text should be displayed before fading out.
LogDisplayGetTextFadeTime()	Returns the current the amount of time the text is displayed before fading out.
LogDisplayIsScrollbarActive()	Returns whether a Scrollbar is needed for this display.
LogDisplaySetFont()	Sets the Font for the text display
LogDisplayGetFont()	Returns the the name of the Font for the text display.
LogDisplayScrollToBottom()	Scrolls the display all the way to the bottom.
LogDisplayIsScrolledToBottom()	Returns if the display is scrolled all the way to the bottom.
LogDisplayResetLineFadeTime()	Resets the fade time for all of the text lines.
LogDisplayShowScrollbar()	Sets if the scrollbar should be shown or hidden.
LogDisplayScrollToTop()	Scrolls the display all the way to the top.
LogDisplayIsScrolledToTop()	Returns if the display is scrolled all the way to the top.

Implementation Details

The LogDisplay works in conjuction with the TextLog element to provide the an in-game visual display for the log entries.

Standard Features

Through the text log display you can do the following...

Specify a Unique Text Color for each Entry type.
Select which filter types you wish to display or hide.
Show multiple TextLogs in one window. Entries will be ordered by timestamp.

Unlike the ScrollWindow or PageWindow controls, which create rendered version of all the text, the TextLogDisplay only renders the section of text that you actively see on the window. Internally, the TextLog display parse out the lines for each entry according to the window’s font size and dimenions.

(see ..\docs\images\LogDisplay_Example1.jpg)

Specialized Features

A scrollbar is automatically created and updated to fit the number of entries. The LogDisplay also has a number of special features that cater to use for an incoming-chat text window. These include..

Automatic scrolling to the bottom of the log when new entries are added.
Automatic fading of of the text lines, after they have been visible for a specifed period of time.

XML Definition

This is the LogDisplay XML definition.

Summary

XML Tag
Required Attributes	You need to specify valid values for all of these elements to get the LogDisplay to create properly.
font	The name of the Font definition to use.
Optional Attributes	These are optional.
scrollbar	The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .
background	The name of a FullResizeImage to use as a background.
linespacing	An override value for the font line spacing.
maxchars	The maximum number of characters allowed to be displayed.
maxentries	The maximum number of entry lines to be displayed for each text log shown.
textFadeTime	The amount time the text should remain on the screen after a new entry is added.
autoHideScrollBar	Auto-hides the scroll bar when the window the contents current LogDisplay contents fill less than one page.

XML Tag

<LogDisplay>
....
</LogDisplay>

Required Attributes

You need to specify valid values for all of these elements to get the LogDisplay to create properly.

font

The name of the Font definition to use.

Expects

A string value of a valid Font.

Optional Attributes

These are optional. You can use whichever apply to the EditBox you are creating.

scrollbar

The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .

Expects

A string value, which is the name of a valid Button.

Default Value

””

Notes

Scrollbars are currently broken for edit boxes

background

The name of a FullResizeImage to use as a background.

Expects

A string value, which is the name of a valid FullResizeImage.

Default Value

””

Notes

none

linespacing

An override value for the font line spacing.

Expects

A number. If 0, the font height is used.

Default Value

maxchars

The maximum number of characters allowed to be displayed.

Expects

A number greater than 0.

Default Value

maxentries

The maximum number of entry lines to be displayed for each text log shown.

Expects

A number greater than 0.

Default Value

Notes

Can be adjusted later with LogSetLimit.

textFadeTime

The amount time the text should remain on the screen after a new entry is added.

Expects

A number. If 0, the text should not fade.

Default Value

Notes

Text will only fade when the LogDisplay is scrolled all the way to the bottom.

autoHideScrollBar

Auto-hides the scroll bar when the window the contents current LogDisplay contents fill less than one page.

Expects

A boolean value.

Default Value

false

Functions

Summary

Functions
LogDisplayAddLog()	Adds the specified TextLog to the LogDisplay
LogDisplayRemoveLog()	Removes the specified TextLog to the LogDisplay

Functions

LogDisplayAddLog()

Adds the specified TextLog to the LogDisplay

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) Name of the TextLog to add.
addEntries	(boolean) Should entries already in the log be added to the display?

Returns

nil	no return value

Notes

If call this function with addEntries = false, then only new entires to the TextLog will be displayed.

Example

LogDisplayAddLog("ChatWindowChatLogDisplay", "Chat", true)

LogDisplayRemoveLog()

Removes the specified TextLog to the LogDisplay

Parameters

logDisplayName	(string) The name of the LogDisplay.
logName	(string) The name of the TextLog.

Returns

nil	no return value

Notes

none

Example

LogDisplayRemoveLog("ChatWindowChatLogDisplay", "Chat" )

Functions

Summary

Functions
LogSetLimit()	Sets the maximum number of entries to display in the LogDisplay.
LogDisplaySetShowTimestamp()	Sets if the timestamps should be display at the beginning of each entry.
LogDisplayGetShowTimestamp()	Return if the timestamps is currently displayed at the beginning of each entry.
LogDisplaySetShowLogName()	Sets if the TextLog name should be display at the beginning of each entry.
LogDisplayGetShowLogName()	Returns if the TextLog name is currently displayed at the beginning of each entry.
LogDisplaySetShowFilterName()	Sets if the Filter Type name should be display at the beginning of each entry.
LogDisplayGetShowFilterName()	Returns if the Filter Type name is currently displayed at the beginning of each entry.
LogDisplaySetFilterColor()	Sets the text color to use for the specified TextLog and Filter Type.
LogDisplayGetFilterColor()	Returns the color currently used for the specified TextLog and Filter Type.
LogDisplaySetFilterState()	Sets the specified Filter Type for the specified TextLog should be displayed.
LogDisplayGetFilterState()	Returns if the specified Filter Type for the specified TextLog is currentlydisplayed.
LogDisplayHideFilterSubType()	Sets if a filter sub type should be shown.
LogDisplaySetTextFadeTime()	Sets the amount of time the text should be displayed before fading out.
LogDisplayGetTextFadeTime()	Returns the current the amount of time the text is displayed before fading out.
LogDisplayIsScrollbarActive()	Returns whether a Scrollbar is needed for this display.
LogDisplaySetFont()	Sets the Font for the text display
LogDisplayGetFont()	Returns the the name of the Font for the text display.
LogDisplayScrollToBottom()	Scrolls the display all the way to the bottom.
LogDisplayIsScrolledToBottom()	Returns if the display is scrolled all the way to the bottom.
LogDisplayResetLineFadeTime()	Resets the fade time for all of the text lines.
LogDisplayShowScrollbar()	Sets if the scrollbar should be shown or hidden.
LogDisplayScrollToTop()	Scrolls the display all the way to the top.
LogDisplayIsScrolledToTop()	Returns if the display is scrolled all the way to the top.

Functions

LogSetLimit()

Sets the maximum number of entries to display in the LogDisplay.

Parameters

logDisplayName	(string) The name of the LogDisplay.
limit	(number) Maximum number of entries to display. A negative value specifies unlimited.

Returns

nil	no return value

Example

LogSetLimit("ChatWindowChatLogDisplay", 1000)

LogDisplaySetShowTimestamp()

Sets if the timestamps should be display at the beginning of each entry.

Parameters

logDisplayName	(string) The name of the LogDisplay.
showTimestamp	(boolean) Should the timestamp be displayed?

Returns

nil	no return value

Notes

none

Example

LogDisplaySetShowTimestamp("ChatWindowChatLogDisplay", false )

LogDisplayGetShowTimestamp()

Return if the timestamps is currently displayed at the beginning of each entry.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

showTimestamp

(boolean) is the timestamp currently displayed?

Notes

none

Example

local showTimestamp = LogDisplayGetShowTimestamp("ChatWindowChatLogDisplay"  )

LogDisplaySetShowLogName()

Sets if the TextLog name should be display at the beginning of each entry.

Parameters

logDisplayName	(string) The name of the LogDisplay.
showLogName	(boolean) Should the TextLog name be displayed?

Returns

nil	no return value

Notes

none

Example

LogDisplaySetShowLogName("ChatWindowChatLogDisplay", false )

LogDisplayGetShowLogName()

Returns if the TextLog name is currently displayed at the beginning of each entry.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

showLogName

(boolean) Is the TextLog name currently displayed?

Notes

none

Example

local showLogName = LogDisplayGetShowLogName("ChatWindowChatLogDisplay" )

LogDisplaySetShowFilterName()

Sets if the Filter Type name should be display at the beginning of each entry.

Parameters

logDisplayName	(string) The name of the LogDisplay.
showFilterName	(boolean) Should the Filter Type name be displayed?

Returns

nil	no return value

Notes

none

Example

LogDisplaySetShowFilterName("ChatWindowChatLogDisplay", true )

LogDisplayGetShowFilterName()

Returns if the Filter Type name is currently displayed at the beginning of each entry.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

showFilterName

(boolean) Is the Filter Type currently displayed?

Notes

none

Example

local showFilterName = LogDisplayGetShowFilterName("ChatWindowChatLogDisplay" )

LogDisplaySetFilterColor()

Sets the text color to use for the specified TextLog and Filter Type.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) The of the TextLog.
filterId	(number) The filter id within the TextLog.
red	(number) The red value for the text color (0-255)
green	(number) The green value for the text color (0-255)
blue	(number) The blue value for the text color (0-255)

Returns

nil	no return value

Notes

none

Example

LogDisplaySetFilterColor("ChatWindowChatLogDisplay", SystemData.ChatLogFilters.SAY, 255, 255, 255 )

LogDisplayGetFilterColor()

Returns the color currently used for the specified TextLog and Filter Type.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) The of the TextLog.
filterId	(number) The filter id within the TextLog.

Returns

red	(number) The red value for the text color (0-255)
green	(number) The green value for the text color (0-255)
blue	(number) The blue value for the text color (0-255)

Notes

none

Example

LogDisplayGetFilterColor("ChatWindowChatLogDisplay", SystemData.ChatLogFilters.SAY, 255, 255, 255 )

LogDisplaySetFilterState()

Sets the specified Filter Type for the specified TextLog should be displayed.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) The of the TextLog.
filterId	(number) The filter id within the TextLog.
showFilterType	(boolean) Should the filter type be displayed?

Returns

nil	no return value

Notes

none

Example

LogDisplaySetFilterState("ChatWindowChatLogDisplay", SystemData.ChatLogFilters.SAY, true )

LogDisplayGetFilterState()

Returns if the specified Filter Type for the specified TextLog is currentlydisplayed.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) The of the TextLog.
filterId	(number) The filter id within the TextLog.

Returns

showFilterType

(boolean) Is the the filter type currently displayed?

Notes

none

Example

local isDisplayed = LogDisplayGetFilterState("ChatWindowChatLogDisplay", SystemData.ChatLogFilters.SAY )

LogDisplayHideFilterSubType()

Sets if a filter sub type should be shown.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textLogName	(string) The of the TextLog.
filterId	(number) The filter id within the TextLog.
showFilterType	(boolean) Should the filter type be displayed?
filterSubTypeName	(string) The name of the filter sub type.
hideSubType	(string) Should the sub type be hidden?

Returns

nil	no return value

Notes

Currently the game can internally set a filter sub type for each entry. Typically when a TextLog is used for a chat log, the ‘sub type name’ refers to the name of the person the text is associated with.

Example

LogDisplayHideFilterSubType( "ChatWindowChatLogDisplay", "Chat", SystemData.ChatLogFilters.TELL_RECEIVE, name, true )

LogDisplaySetTextFadeTime()

Sets the amount of time the text should be displayed before fading out. A fade time of 0 means that the text will not fade at all.

Parameters

logDisplayName	(string) The name of the LogDisplay.
textDisplayTime	(number) How long the text should be displayed before fading.

Returns

nil	no return value

Related XML

textFadeTime

Notes

none

Example

LogDisplaySetTextFadeTime( "ChatWindowChatLogDisplay", visibleTime )

LogDisplayGetTextFadeTime()

Returns the current the amount of time the text is displayed before fading out.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

textDisplayTime

(number) The time the text is currently displayed before fading.

Related XML

textFadeTime

Notes

none

Example

local fadeTime = LogDisplayGetTextFadeTime( "ChatWindowChatLogDisplay" )

LogDisplayIsScrollbarActive()

Returns whether a Scrollbar is needed for this display. Checks the bounds of the scroll to see if it should be active

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

(bool) Returns whether a Scrollbar is needed for this display.

Related XML

none

Notes

none

Example

local bScrollbarNeeded = LogDisplayIsScrollbarActive( "ChatWindowChatLogDisplay" )

LogDisplaySetFont()

Sets the Font for the text display

Parameters

logDisplayName	(string) The name of the LogDisplay.
fontName	(number) The name of the Font to use.

Returns

nil = no return value

Related XML

font

Notes

none

Example

LogDisplaySetFont( "ChatWindowChatLogDisplay", "font_default_text" )

LogDisplayGetFont()

Returns the the name of the Font for the text display.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

fontName

(string) The name of the Font to use.

Related XML

font

Notes

none

Example

local font = LogDisplayGetFont( "ChatWindowChatLogDisplay" )

LogDisplayScrollToBottom()

Scrolls the display all the way to the bottom.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

nil	no return values

Notes

none

Example

LogDisplayScrollToBottom( "ChatWindowChatLogDisplay" )

LogDisplayIsScrolledToBottom()

Returns if the display is scrolled all the way to the bottom.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

atBottom

(boolean) Is the display scroll to the bottom?

Notes

none

Example

local scrolledDown =  LogDisplayIsScrolledToBottom( "ChatWindowChatLogDisplay" )

LogDisplayResetLineFadeTime()

Resets the fade time for all of the text lines.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

nil	no return values

Notes

none

Example

LogDisplayResetLineFadeTime( "ChatWindowChatLogDisplay" )

LogDisplayShowScrollbar()

Sets if the scrollbar should be shown or hidden.

Parameters

logDisplayName	(string) The name of the LogDisplay.
showBar	(boolean) Should the scrollbar be shown?

Returns

nil	no return values

Notes

none

Example

LogDisplayShowScrollbar( "ChatWindowChatLogDisplay", true )

LogDisplayScrollToTop()

Scrolls the display all the way to the top.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

nil	no return values

Notes

none

Example

LogDisplayScrollToTop( "ChatWindowChatLogDisplay" )

LogDisplayIsScrolledToTop()

Returns if the display is scrolled all the way to the top.

Parameters

logDisplayName

(string) The name of the LogDisplay.

Returns

atTop

(boolean) Is the display scroll to the top?

Notes

none

Example

local scrolledDown =  LogDisplayIsScrolledToTop( "ChatWindowChatLogDisplay" )