WoWInterface - Eisa's Portal : (Technical) What are AudioX mini-API functions?

		Eisa's Portal » FAQ
(Technical) What are AudioX mini-API functions?

AudioX II

(Technical) What are AudioX mini-API functions?

AudioX II API 3.2.27

The AudioX II API is designed to allow other mod developers access to some of AudioX's features. This means that 3rd party UIs should be possible.

If you are a mods (aka add-on) developer and are interested in utilizing this mini-API then read on. If you aren't, then you may want to skip the details.

These functions will only be available once AudioX_Search has loaded.
You can force AudioX_Search to load by calling AX:Load_AudioXSearch(AX.CMD_API) .
AX.CMD_API contains the localized slash command for enabling API output. Default is "api".
If AX.apiout is true then AX:API_LineOut and AX:API_PageFooter are used for output. Please set AX.apiout to false when closing your mod's frame.
Be aware that AX.apiout toggles true/false with searches started by /ax commands and AX:API_Search.
AX.searchmode is used to store which table AudioX_Search and AudioX_UI are currently using. AudioX uses this variable extensively to point to the table by using _G[AX.searchmode] as a substitute for SoundLib and AUDIOX_FAVS. 3rd party UIs will probably need to adopt the same technique to continue working beyond AudioX II 3.2.21.
function AX:API_ChatOutput(notice_to_chat)
- Description:
  - Sets AX.apiout to false, redirecting output to the chatframe. Notification always sent to the UI notice field.
- Param:
  - notice_to_chat = true if player notification should appear in the chatframe, such as when the UI is closed.
- Note:
  - This function should be used instead of AX.apiout = false.
- Example:
  - AX:API_ChatOutput(false)
function AX:API_UIOutput()
- Description:
  - Sets AX.apiout to true, redirecting output to the UI. Notification always sent to the chatframe.
- Note:
  - This function should be used instead of AX.apiout = true.
- Example:
  - AX:API_UIOutput()
function AX:API_PageSize(resultsperpage)
- Description:
  - Sets the number of results returned each time AX:API_Search is called.
- Parameters:
  - resultsperpage = the number of results you want per page.
- Example:
  - AX:API_PageSize(10)
function AX:API_Search(cmd,param)
- Description:
  - Initiates a search of the soundlib (i.e. /ax s keyword).
- Parameters:
  - cmd = AX.CMD_SEARCH, AX.CMD_PGDN, AX.CMD_PGUP, AX.CMD_MATCH, AX.CMD_REFRESH or AX.CMD_BEGIN (i.e. respective /ax s, /ax d, /ax u, /ax m, /ax r, /ax b equivalents)
    - If cmd is AX.CMD_SEARCH, param defines the search keyword.
    - If cmd is AX.CMD_MATCH, param defines which search result to display first.
    - If cmd is AX.CMD_BEGIN, param defines which sound index to display results from.
  - param = Only relevant when cmd is AX.CMD_SEARCH, AX.CMD_MATCH or AX.CMD_BEGIN. Assign it "" the rest of the time.
    - if param starts with "#" the rest of keyword is assumed to be a sound index number, so AX:API_Search(anything,"#512") will return one result (i.e. same as /ax i 512)
- Returns:
  - true if the search is carried out.
  - false if the search can not be carried out (i.e. searching out of bounds with next/prev).
- Note:
  - AX.CMD_* variables (e.g. AX.CMD_SEARCH, AX.CMD_PGDN) are store the appropriate localized command for each action. As these may change between localized language, it is highly recommended that you use them. So instead of AX:API_Search("s","brew") use AX:API_Search(AX.CMD_SEARCH,"brew").
- Examples:
  - success = AX:API_Search(AX.CMD_SEARCH,"brew") -- Start searching for "brew" (i.e. /ax s brew)
  - success = AX:API_Search(AX.CMD_PGDN,"") -- Get next page of results (i.e. /ax d)
  - success = AX:API_Search(AX.CMD_PGUP,"") -- Get prev page of results (i.e. /ax u)
  - success = AX:API_Search(AX.CMD_REFRESH,"") -- Refresh current page of results (i.e. /ax r)
  - success = AX:API_Search(AX.CMD_MATCH,"15") -- Get next page of results (i.e. /ax m 15)
  - success = AX:API_Search(AX.CMD_BEGIN,"3000") -- Get prev page of results (i.e. /ax b 3000)
function AX:API_LinkSlashCmd(soundpath)
- Description:
  - Inserts soundpath into the ChatframeEditbox as /script PlaySoundFile(<soundpath>).
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
- Notes:
  - Opens ChatFrameEditBox if it isn't already open.
  - Does not send the link. Add ChatEdit_SendText(ChatFrameEditBox,1) to your mod for that.
- Examples:
  - AX:API_LinkSlashCmd("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_LinkSlashCmd(512)
function AX:API_LinkSoundPath(soundpath)
- Description:
  - Inserts soundpath into the ChatframeEditbox as an AudioX2 formatted hyperlink.
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
- Notes:
  - Opens ChatFrameEditBox if it isn't already open.
  - Ensures output channel is valid.
  - Does not send the link. Add ChatEdit_SendText(ChatFrameEditBox,1) to your mod for that.
- Examples:
  - AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_LinkSoundPath(512)
function AX:API_Play(sound)
- Description:
  - Plays a soundpath or index with double click prevention.
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1). E.g. 512
- Examples:
  - AX:API_Play("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_Play(512)
function AX:API_Quiet()
- Description:
  - Stops all sound playback.
- Example:
  - AX:API_Quiet()
function AX:API_ToggleFavSample(sound)
- Description:
  - Adds/removes favourites from favourites table.
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
- Returns:
  - false if the sound is removed from the favourites table.
  - true if the sound is added to the favourites table.
- Examples:
  - AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_LinkSoundPath(512)
function AX:API_ToggleFavMode(bool)
- Description:
  - Is used to specify whether AudioX is searching the SoundLib or AUDIOX_FAVS.
- Parameters:
  - bool = true if you want to search AUDIOX_FAVS favourites table.
  - bool = false if you want to search the main SoundLib.
  - Any other value will toggle the value of bool between true and false.
- Examples:
  - AX:API_ToggleFavMode(true) -- Search AUDIOX_FAVS
  - AX:API_ToggleFavMode(false) -- Search SoundLib
  - AX:API_ToggleFavMode("") -- Toggle true/false
- Important:
  - Sets AX.searchmode to the variable name of the table in use. It is highly recommended that all references to "SoundLib" is changed to _G[AX.searchmode] in you AudioX plugins.
function AX:API_IsFav(sound)
- Description:
  - Is used to determine if a sound is in the favourites table.
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
- Returns:
  - If value is greater than 0 then sound is in AUDIOX_FAVS array. The positive return value indicates the location of sound in AUDIOX_FAVS.
  - If value is less than 0 then sound is not in AUDIOX_FAVS array. The negative return value * -1 can be used to establish where the sound sound be inserted into AUDIOX_FAVS. However, save youself the effort and AX:API_ToggleFavSample(sound) instead!
- Examples:
  - AX:API_LinkSoundPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_LinkSoundPath(512)
function AX:API_FilterPathAndExt(sound)
- Description:
  - Removed the path and file extension from soundpath (or that associated with a given soundindex).
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - soundpath (integer 1 to #SoundLib) = sound index number (invalid index set to 1) E.g. 512
- Returns:
  - The main part of the filename. E.g. BloodElfMaleHello02
- Examples:
  - AX:API_FilterPathAndExt("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav")
  - AX:API_FilterPathAndExt(512)
function AX:API_IndexFromPath(soundpath,usingsoundlib)
- Description:
  - Attempt to discover the index number of a given soundpath.
- Parameters:
  - soundpath (string) = valid sound path name. E.g. Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav.
  - usingsoundlib = true --return values from the SoundLib only.
  - usingsoundlib = false --return value for the _G[AX.searchmode] (i.e. SoundLib or AUDIOX_FAVS).
- Returns:
  - If soundpath is found then true,idx is returned. E.g. true,512
  - If soundpath is not found then false,0 is returned. E.g. false,0
- Example:
  - found,index = AX:API_IndexFromPath("Sound\\Character\\BloodElf\\BloodElfMaleHello02.wav",true)

function AX:API_LineOut(key,path)

IMPORTANT:
- This function should be hooked in your AudioX plugin.
Description:
- AudioX outputs to API_LineOut everytime a search match is found for the current page size (set with API_PageSize).
Parameters:
- key = Sound index number.
- path = Sound path name.

Example Hook:

Code:

local AX_API_LineOut_orig = AX.API_LineOut
        local function Example_LineOut(self,...)
          local key,path = ...
          if myaddon_active then -- If your mod is enabled
            -- your search results line output code starts here E.g.
            print(key,path)
            -- your search results line output code ends here
          else
            AX_API_LineOut_orig(self,key,path)
          end
        end
        AX.API_LineOut = Example_LineOut

function AX:API_PageFooter(first,last,total,search)

IMPORTANT:
- This function should be hooked in your AudioX plugin.
Description:
- AudioX outputs to AX:API_PageFooter at the end of each page of results.
Parameters:
- first = result number of the first result in the current page.
- last = result number of the last result in the current page.
- total = total number of search matches found in the SoundLib.
- search = keyword search was for (useful for sanity checking).

Example Hook:

Code:

local AX_API_PageFooter_orig = AX.API_PageFooter
        local function Example_PageFooter(self,...)
          local first,last,total,search = ...
          if myaddon_active then  -- If your mod is enabled
            -- your footer code starts here E.g.
            print(first,last,total,search)
            -- your footer code ends here
          else
            AX_API_PageFooter_orig(self,first,last,total,search)
          end
        end
        AX.API_PageFooter = Example_PageFooter

function AX:API_Notice(msg)

IMPORTANT:
- This function should be hooked in your AudioX plugin.
Description:
- AudioX outputs to AX:API_Notice whenever an error or verbose notice would be displayed.
Parameters:
- msg = Error message text (less "AudioX> ")

Example Hook:

Code:

local AX_API_Notice_orig = AX.API_Notice
        local function Example_API_Notice(self,...)
          local msg = ...
          if myaddon_active then -- If your mod is enabled
            -- your search results line output code starts here E.g.
            print(msg)
            -- your search results line output code ends here
          else
            AX_API_Notice_orig(self,msg)
          end
        end
        AX.API_Notice = Example_Notice

Menu

» Home

» News Archive

» F.A.Q.

» Bug Reports

» Feature Request

» Interface List

Stats

Files: 1

Downloads: 855

Favorites:

New & Updated

» AudioX II

View All

WOWInterface