ChatBlade SDK Documentation

Class   CBEditFieldData
Header   CBEditFieldData.h

Data    Member Summary    Member Details

Information:  

CBEditFieldData is a class that keeps track of previously entered Chat and stores the default Slash Command for a UI Edit Field.  
It is designed to supply Chat History (repeat Chat) and Default Slash Command functionality to a UI Edit Field.  
 
Each GUI Edit Field that is related to Chat should have 1 matching instance of CBEditFieldData in order to keep track of the data for that GUI Edit Field.  
Developers should create this instance by calling CBData::AddEditFieldData() once per GUI Edit Field and passing to it the ID of each Edit Field.  
CBData::AddEditFieldData() creates and adds an instance that is stored in CBData::mEditFieldDataMap.  This map is Keyed via the ID of the Edit Field.  
 
ChatBlade keeps track of any text a Player types into the Edit Field, and stores that text in the appropriate instance of this Class.  When a Player wants to repeat a line of text they have previously typed, ChatBlade can retrieve this text.  This functionality is known as Chat History, or Chat Repeat.  
Typically if a Player hits the Up-Arrow, or Shift+Up-Arrow when the Edit Field has focus the Game should replace the text in the Edit Field with that retrieved from the Chat History.  
CBEditFieldData::OnUpArrow() returns a line that the Player had previously typed.  Calling it multiple times shall cycle backwards through the Chat History.  CBEditFieldData::OnDownArrow() cycles the opposite direction.  
ChatBlade keeps track internally of where a Player is in the Chat History.  Once they actually enter a new line of Text this internal counter is reset.  
 
If the line of text a Player enters in is the exact same as the latest line of text in the Chat History, the new line is not added into the Chat History.  This prevents the Chat History from filling up with the same line.  
 
In addition to keeping track of the Chat History, CBEditFieldData also keeps track of the Default Slash Command for its related UI Edit Field.  
 
ChatBlade allows each Edit Field to have a different Default Slash Command.  One UI Edit Field may default to "/group", while another may default to "/say", and a third can default to "/tell Irridia,".  
If a Player enters in a line of text that does not start with a Slash Command Character ('/'), ChatBlade shall prepend the Default Slash Command to that line of text.  
 
Examples of when a Default Slash Command shall be added:  
    If a UI Edit Field has a Default Slash Command of "/group":
    Player Types "Hello Guys" and ChatBlade changes this to "/group Hello Guys"
    Player Types "/auction Anyone selling Enhanced Armor?" and ChatBlade leaves this the same since it already starts with a Slash Command.  
    Player Types "/say I do" and ChatBlade leaves this the same since it already starts with a Slash Command.  
 
If multiple UI Chat Tabs share the same physical Edit Field but it is desired that each Chat Tab have a different Default Slash Command, then CBData::AddEditFieldData() should get called once for each Chat Tab, using a unique ID for each.  
In this case each Chat Tab shall have a separate Chat History, unless one CBEditFieldData is used and the Default Slash Command is changed each time the Player selects a different Tab.   
 
This class provides 4 Static functions to enable the Game Developers to easily access the Default Slash Command and the Chat History, without having to go through the CBData Map of CBEditFieldData instances.  
These 4 static functions take the Edit Field ID as an initial parameter.  
 

Game Developer Implementation:  

For Each UI Edit Field that is related to Chat, call CBData::AddEditFieldData() passing it the ID of that Edit Field.  This creates a related CBEditFieldData instance to store the Chat History and Default Slash Command for that Edit Field.  
The CBEditFieldData instance can be retrieved by accessing CBData::mEditFieldDataMap[nEditFieldID].  
See How To Hook Up an Edit Field to ChatBlade.  
If an Edit Field has focus and the Player hits Up-Arrow or Down-Arrow, Developers should retrieve the text from the Chat History and replace the text in the Edit Field with the Chat History Text.  
Developers can call CBEditFieldData::OnUpArrow(nEditFieldID) and CBEditFieldData::OnDownArrow(nEditFieldID) to get the previously entered lines of text.  
To set the Default Slash Command for an Edit Field, Developers might call CBData::mEditFieldDataMap[nEditFieldID].SetDefaultSlashCommmand() or use the static version and call CBEditFieldData::SetDefaultSlashCommmand(nEditFieldID, sSlashCommand).
 

Source File Comments:  

// Source file for the CBEditFieldData class which holds information related to a single UI edit field
// Contains the default Slash Command for the edit field as well as a list of previously entered lines for use in Repeating Chat
 
// If a user enters a line without a Slash Command the default Slash Command for this edit field shall be prepended
// Each CBEditFieldData can have a different default Slash Command
// This allows an edit field to default to /group or /say or any other Slash Command
 
// In addition the CBEditFieldData class holds a history of previously entered lines for chat Repeat functionality
// Typically if the user hits up arrow while focus is on the edit field the text of the edit field text shall change to the last entered line
// Multiple up arrows allow the user to scroll through and Repeat text they have typed before
 
// Each typical UI edit field used should have a related CBEditFieldData class if default / Command and Chat History are desired
// TODO: Call CBData::AddEditFieldData() for each UI Edit Field in the game GUI
 
// A map of all the CBEditFieldData instances is stored in CBData::mEditFieldDataMap keyed via the ID of the associated edit field
 

Data:  

CBSTRING m_sDefaultSlashCommand
        Our default Slash Command for the related Edit Field when no Slash Command is typed in.  
int m_nUIEditFieldID
        The ID of the UI Edit Field this CBEditFieldData instance is helping.  
int m_nMaxChatHistorySize
        The amount of lines to keep in the Chat Repeat History.  
int m_nChatHistoryIndex
        Used internally to determine where we are in the Chat History.  
std::deque<CBSTRING> m_ChatHistoryArray
        A deque of our previously entered lines.  
 

Member Function Summary:  

                 CBEditFieldData()
        Constructor.  
                 CBEditFieldData(int nEditFieldID)
        Constructor supplying the ID of the UI Edit Field this instance is related to.  
int              StoreUIEditFieldID(int nEditFieldID)
        Sets the stored ID of the related UI Chat Edit Field.  
int              SetDefaultSlashCommmand(CBSTRING sSlashCommand = CB_DEFAULT_SLASH_COMMAND)
        Sets the Default Slash Command to use for any lines entered into the related UI Edit Field.  
static int        SetDefaultSlashCommmand(int nEditFieldID, CBSTRING sSlashCommand = CB_DEFAULT_SLASH_COMMAND)
        Static helper function which sets the Default Slash Command to use for any lines entered into the related UI Edit Field.  
CBSTRING         GetDefaultSlashCommand()
        Gets the stored Default Slash Command for the related UI Edit Field.  
static CBSTRING  GetDefaultSlashCommand(int nEditFieldID)
        Static helper function which gets the stored Default Slash Command for the related UI Edit Field.  
int              SetChatHistorySize(int nAmountOfLines = CB_MAX_CHAT_REPEAT_LINES)
        Sets the amount of lines to store in the Chat Repeat deque.  
int              AddLineToChatHistory(CBSTRING sLineToAdd)
        Adds a line to the Chat Repeat History.  
CBSTRING         OnUpArrow()
        Called when the user wants to get the previous line of text they entered.  
CBSTRING         OnDownArrow()
        Called when the user was scrolling back through their previously entered lines and now wants to scroll forward.  
static CBSTRING  OnUpArrow(int nEditFieldID)
        Static helper function which gets called when the user wants to get the previous line of text they entered.  
static  CBSTRING  OnDownArrow(int nEditFieldID)
        Static helper function which gets called when the user was scrolling back through their previously entered lines and now wants to scroll forward.  
 

Member Function Detail:  

               CBEditFieldData::CBEditFieldData()
Comments:
Constructor which sets our default Maximum Chat History size and starting Default Slash Command.  
Parameters:
None
Returns:
None
 
                CBEditFieldData::CBEditFieldData( int nEditFieldID)
Comments:
Constructor which sets our default Maximum Chat History size and starting Default Slash Command as well as the ID of the related GUI Edit Field.  
Parameters:
nEditFieldID
    The ID of the related GUI Edit Field this CBEditFieldData instance should assist.  
Returns:
None
 
int              CBEditFieldData::StoreUIEditFieldID( int nEditFieldID)
Comments:
Sets the stored ID of the related UI Chat Edit Field.  
Each CBEditFieldData instance should have a Unique ID.  
Parameters:
nEditFieldID
    The ID of the related GUI Edit Field this CBEditFieldData instance should assist.  
Returns:
CB_SUCCESS
 
int               CBEditFieldData::SetDefaultSlashCommmand( CBSTRING sSlashCommand = CB_DEFAULT_SLASH_COMMAND)
Comments:
Sets the Default Slash Command that shall be prepended to any lines of text entered into the related UI Edit Field that do not already start with a Slash Command.  
Valid parameters might be:  /group or /say or /auction or /tell Xynelle Delfin, or /guild etc.  
If a Player types a Chat line that does not already start with a Slash Command, this Default Slash Command shall get prepended to the Line before processing.  
If the Player types a Chat Line that already starts with a Slash Command the line remains unchanged.  
The supplied parameter must start with a '/' character.  
Parameters:
sSlashCommand 
    The Slash Command that should be added onto any Chat the Player enters, which does not already start with a Slash Command.  Defaults to /say equivalent (/CBSAY).  
Returns:
CB_ERROR_BAD_CHAT_COMMAND if sSlashCommand does not start with a '/'.  
CB_SUCCESS if the Slash Command was successfully added as the Default for this CBEditFieldData instance.  
 
static int  CBEditFieldData::SetDefaultSlashCommmand( int nEditFieldID,
               CBSTRING sSlashCommand = CB_DEFAULT_SLASH_COMMAND)
Comments:
This is a Static version of SetDefaultSlashCommmand() which takes an Edit Field ID as its first parameter.  
Sets the Default Slash Command that shall be prepended to any lines of text entered into the related UI Edit Field that do not already start with a Slash Command.  
Valid parameters might be:  /group or /say or /auction or /tell Xynelle Delfin, or /guild etc.  
If a Player types a Chat line that does not already start with a Slash Command, this Default Slash Command shall get prepended to the Line before processing.  
If the Player types a Chat Line that already starts with a Slash Command the line remains unchanged.  
The supplied parameter must start with a '/' character.  
Parameters:
nEditFieldID
    The Edit Field ID of the Edit Field we want to set the Default Slash Command of.  
sSlashCommand 
    The Slash Command that should be added onto any Chat the Player enters, which does not already start with a Slash Command.  Defaults to /say equivalent (/CBSAY).  
Returns:
CB_ERROR_BAD_CHAT_COMMAND if sSlashCommand does not start with a '/'.  
CB_SUCCESS if the Slash Command was successfully added as the Default for the specified CBEditFieldData instance.  
 
CBSTRING  CBEditFieldData::GetDefaultSlashCommand()
Comments:
Returns the stored Default Slash Command for the related UI Edit Field.  
Called by CBChatHandler::AddDefaultSlashCommand().  
Parameters:
None
Returns:
Returns m_sDefaultSlashCommand.  
 
CBSTRING  CBEditFieldData::GetDefaultSlashCommand( int nEditFieldID)
Comments:
This is a Static version of GetDefaultSlashCommand() which takes an Edit Field ID as its first parameter.  
Returns the stored Default Slash Command for the related UI Edit Field.  
Parameters:
nEditFieldID
    The Edit Field ID of the Edit Field we want to get the Default Slash Command from.  
Returns:
Returns m_sDefaultSlashCommand of the CBEditFieldData instance matching the specified Edit Field ID.  
 
int              CBEditFieldData::SetChatHistorySize( int nAmountOfLines = CB_MAX_CHAT_REPEAT_LINES)
Comments:
Sets the amount of lines to store in the Chat History.  
If more than this amount of lines are added, then the oldest lines are removed.  
Setting the Chat History size to 0 effectively disables the Chat History.  
Parameters:
nAmountOfLines 
    The amount of lines to keep in the Chat History.  Defaults to CB_MAX_CHAT_REPEAT_LINES (25).  
Returns:
CB_SUCCESS
 
int              CBEditFieldData::AddLineToChatHistory( CBSTRING sLineToAdd)
Comments:
Adds a line to the stored Chat History so that it may later be retrieved if the Player desires.  
This function gets called by ChatBlade each time a Player enters a line of Chat.  
If sLineToAdd is the exact same as the last line entered into the Chat History, then it is not added.  This prevents the Chat History from filling up with the same line.  
Lines added to the Chat History can be retrieved via the OnUpArrow() and OnDownArrow() functions.  
AddLineToChatHistory() resets the internal counter that keeps track of where a Player might be in the Chat History if they had been using multiple Up and Down Arrows to cycle though the Chat History.  
Called by CBChatHandler::OnLineEntered().  
Parameters:
sLineToAdd
    A line of text entered in by the Player.  ChatBlade shall remember this line for later use by storing it in this CBEditFieldData instance.  
Returns:
CB_ERROR_EMPTY_STRING if sLineToAdd is empty.  
CB_SUCCESS
 
CBSTRING  CBEditFieldData::OnUpArrow()
Comments:
Called when the user wants to get the previous line of text they entered.  Retrieves a previously entered line of text.  
Can be called repeatedly to scroll back farther into the Chat History.  
Developers should take the return value and set the text of the related GUI Edit Field to be the text that is returned from this function.  
Parameters:
None
Returns:
CB_EMPTY_STRING if there is no information in the Chat History.  
A line of text from the Chat History stored in this CBEditFieldData instance.  
 
CBSTRING  CBEditFieldData::OnDownArrow()
Comments:
Called when the user wants to get the previous line of text they entered.  Retrieves a previously entered line of text.  
Can be called repeatedly to scroll forward through the Chat History.  
Typically this function is called after the Player had been calling OnUpArrow() and wants to reverse directions.  
Developers should take the return value and set the text of the related GUI Edit Field to be the text that is returned from this function.  
Parameters:
None
Returns:
CB_EMPTY_STRING if there is no information in the Chat History.  
A line of text from the Chat History stored in this CBEditFieldData instance.  
 
static CBSTRING  CBEditFieldData::OnUpArrow(int nEditFieldID)
Comments:
This is a Static version of OnUpArrow() which takes an Edit Field ID as its first parameter.  
Called when the user wants to get the previous line of text they entered.  Retrieves a previously entered line of text.  
Can be called repeatedly to scroll back farther into the Chat History.  
Developers should take the return value and set the text of the related GUI Edit Field to be the text that is returned from this function.  
Developers may call this to retrieve the Chat History.  
Parameters:
nEditFieldID
    The Edit Field ID of the Edit Field we want to get the Chat History of.  
Returns:
CB_EMPTY_STRING if there is no information in the Chat History.  
A line of text from the Chat History stored in the CBEditFieldData instance specified by nEditFieldID.  
 
static CBSTRING  CBEditFieldData::OnDownArrow(int nEditFieldID)
Comments:
This is a Static version of OnDownArrow() which takes an Edit Field ID as its first parameter.  
Called when the user wants to get the previous line of text they entered.  Retrieves a previously entered line of text.  
Can be called repeatedly to scroll forward through the Chat History.  
Typically this function is called after the Player had been calling OnUpArrow() and wants to reverse directions.  
Developers should take the return value and set the text of the related GUI Edit Field to be the text that is returned from this function.  
Developers may call this to retrieve the Chat History.  
Parameters:
nEditFieldID
    The Edit Field ID of the Edit Field we want to get the Chat History of.  
Returns:
CB_EMPTY_STRING if there is no information in the Chat History.  
A line of text from the Chat History stored in the CBEditFieldData instance specified by nEditFieldID.  
 
 

 

 

 

ChatBlade Copyright © Flex Dolphynn