AceTab-2.0

From WowAce Wiki
Jump to: navigation, search


AceTab-2.0 is a library to provide tab completion capabilities. It handles the functionality and logic for tab completion, only requiring a regex to determine when to use a completion set and a function providing potential values. It also helps with the printing of usage statements, and can even generate simple ones, itself.

See also: AceTab-2.0 Quickies

Example

AceLibrary("AceTab-2.0"):RegisterTabCompletion("Equipment", "held=", function(t)
       table.insert(t, "ball")
       table.insert(t, "bat")
       table.insert(t, "glove")
   end, function(u)
         u["ball"]  = "You hit, catch, and throw this.",
         u["bat"]   = "You hit with this.",
         u["glove"] = "You catch with this."
  end, EquipmentEditBox
) --RegisterTabCompletion takes a description, a regex, a wordlist function, an optional usage flag or function, and an optional frame

Typing 'pick up the b<TAB>' in EquipmentEditBox would then complete up to 'pick up the ba' and print the following:

Equipment
ball - You hit, catch, and throw this.
bat - You hit with this

Be sure to check AceTab-2.0 Quickies for some excellent examples to use in-game!


API Documentation

:RegisterTabCompletion("desc", "regex" or {"regexes"}, wordlistFunc, [usage], ["Frame" or Frame or {"Frames"} or {Frames}])

Registers a tab completion set.

Args

"desc" 
string - A short description of this set. Acts as the default header for usage printouts.
"regex" or {"regexes"}
string - the regex after which this set will be considered (use "" for always consider). The string passed into the regex is the substring leading up to the word being completed.
table - table of regex strings after which this set will be considered
wordlistFunc
function - A function which fills a table (passed as the first argument) with all possible completions in the set. The full text of the current edit box (minus the word being completed) and the cursor position corresponding to the beginning of the word are also passed as second and third arguments, respectively. A wordlist function might look as follows:
function(t, text, pos)
    -- insert all possible completions into t
end

Note: If the wordlist function returns a boolean false, then nothing is considered and no usage feedback is given. This allows you to use this function to further narrow down the conditions for which completions will be considered if the initial simple regex is insufficient. You can test with more complex logic here, and then return false if it fails and it will act just as if it was never reached.

[usage]
function - A function which handles usage feedback in the main chat frame. This receives as arguments a blank table, a table of un-disqualified candidates, the greatest common starting substring of those candidates, and all text preceding the word being completed. It can return a string or fill the table provided by the first passed value with usage statements in the form u["completion"] = "usage". A usage function might look as follows:
function(u, cands, gcs, text)
    -- print usage statements for cands
    -- or fill u with cand-usage pairs
end
boolean - True: Squelch the output; False: Use default output (header, followed by simple list of remaining undisqualified candidates). [Default: false]
["Frame" or Frame or {"Frames"} or {Frames}]
string - The frame which should be hooked for this tab completion set. [Default: ChatFrameEditBox]
table - Table of frames indicating which frames should be hooked for this tab completion set. Can be a table of strings or frames.

Remarks

This registers a tab completion set, providing a description, regexes to indicate when it should be performed, a wordlist of possible completions, an optional function to modify the default feedback, and an optional list of frames for which it should be considered. Example

Teknicolor is a small AddOn that formats player names in chat windows with their class color. It holds a table of the name-class pairs that it knows in the table Teknicolor.nametable, the elements of which are Teknicolor["name"] = "coloredname", where the value "coloredname" is a class-color-formatted square-bracket-enclosed string corresponding to the key "name" (e.g. Mynithrosil -> "|cffaad372[Mynithrosil]|r"). The following example registers a completion based on this table. The candidate words are the names in the table, and the usage statement is a line of possible completions, formatted according to the table values. Additionally, it appends a colon (:) to the name if it is the first word on the line.

AceLibrary("AceTab-2.0"):RegisterTabCompletion("Teknicolor", "",  -- Description, regex ("" -> always test)
   function(t, text, pos)                                         -- wordlist function
       for name in pairs(Teknicolor.nametable) do
           table.insert(t, pos == 0 and name..":" or name)
       end
   end, function(u, cands)                                        -- Usage function
       for _, cand in ipairs(cands) do
           print((string.gsub(Teknicolor.nametable[string.gsub(cand, ":", "")], "[%[%]]+", "")))
       end
   end)

See AceTab-2.0 Quickies for more excellent examples.

:IsTabCompletionRegistered("desc")

Returns whether a tab completion of the given description is registered by this addon.

Args

"desc"
string - Description under which the completion would have been registered (first arg of RegisterTabCompletion).

Returns

isRegistered
boolean - whether the tab completion of the given description is registered by this addon.

Example

if AceLibrary("AceTab-2.0"):IsTabCompletionRegistered("TinyPad") then
    --do something
end

:UnregisterTabCompletion("desc")

Unregister a tab completion.

Args

"desc"
string - Description under which the completion would have been registered (first arg of RegisterTabCompletion).

Remarks

This will error if you have not registered the tab completion.

Example

AceLibrary("AceTab-2.0"):UnregisterTabCompletion("TinyPad")