WIM:API

From WIM

elracvar

This page is dedicated to addon authors who would like to interface their addons with WIM.

As of now the following API/Hook instructions are available. If the tools here are insufficient for what you are trying to accomplish, you may start a discussion at Forums:WIM Addon Compatibilty and we can work together to see what can be done.

[edit] Making Your Addon Load After WIM

In some cases, you may need to have your addon load after WIM has already been loaded in order to properly hook the functions listed later in this document. To do so, add the following to your addon's TOC file.

## OptionalDeps: WIM

If you are already using the OptionalDeps parameter in your toc, you can append WIM to the list like so:

## OptionalDeps: Titan, WIM

[edit] Linking Items In WIM - [OUT DATED]

******Continue Linking as you would normally link to the chat frame****** WIM no longer needs a special accomodation for linking. WIM ties it self into the DEFAULT_CHAT_FRAME's editBox and shares its same properties. Therefore, it is no longer required to send text specifically to WIM's edit box.

If you would like to send item links to an open WIM window similar to how you send links to the default chat frame from within your addon, you may use the following command:

[edit] WIM_API_InsertText(theText)

Inserts text into the current focused message window. If a window is currently out of focus, the function will return false.

Parameters

• theText - the text that you would like to have inserted into the window.

Returns

• true - if message was inserted
• false - if message was not inserted due to the fact that no window was in focus

Example

local myTextToInsert = GetContainerItemLink(bag, slot);

if( type(WIM_API_InsertText) == "function" ) then
   WIM_API_InsertText( myTextToInsert );
end

We first want to see if WIM 2.0 is loaded by checking that the function WIM_API_InsertText exists. If it does, then we call the function with the text to insert.

[edit] Object:WIM_EditBoxInFocus

WIM_EditBoxInFocus is a refrence to the current WIM message box in focus. If no messages are in focus, WIM_EditBoxInFocus = nil. Using this object instead of WIM:API_InsertText may require more code and checks, but also gives you more control over the focused edit box.

Example

local myTextToInsert = GetContainerItemLink(bag, slot);

if ( WIM_EditBoxInFocus ) then
     WIM_EditBoxInFocus:Insert( myTextToInsert );
end

[edit] Controling WIM Window Messages

Below are the current functions available for you to hook if you would like to change the behavior of message posting. This would be useful if you want to run your own conditions prior to a message being displayed.

[edit] WIM_PostMessage(user, msg, type, from, raw)

This function handles the creation and showing of message windows. This function is called after an event has been thrown and processed.

Parameters

• user - the user to whom the conversation belongs.
• msg - the pre-formatted message that will be added to the window's scrolling message frame. This string already includes timestamps and links.
• type - how the message is going to be processed.
  • Values:
    • 1 - Message received.
    • 2 - Message sent.
    • 3 - System message.
    • 4 - Error message.
    • 5 - Show message window.
• from - the user who sent the message.
• raw - the raw message received, not formatted. This is the string recorded in history for post formatting.

Returns

• nil

Example Hook

WIM_PostMessage_orig = WIM_PostMessage;
WIM_PostMessage = HOOKED_WIM_PostMessage;

function HOOKED_WIM_PostMessage(user, msg, type, from, raw)
     -- my own code and actions
    WIM_PostMessage_orig(user, msg, type, from, raw);
end

If you have worked with lua hooking before, this should look quite familiar to you. Within HOOKED_WIM_PostMessage you can decide whether a message is posted or not. Note: this is a post-event hook. This method will not block events from being sent. It will simply control whether or not WIM sees the messages.

[edit] Filtering Hooks

If you would like to include your own filtering instructions within WIM, the following interface is available to hook.

[edit] WIM_API_Filter(theMsg, theUser)

Parameters

• theMsg - the raw message to be filtered.
• theUser - the user that has sent the message (including yourself).

Returns

• 0 - if message is ok.
• 1 - if message is to be ignored, do not suppress and do not display in WIM.
• 2 - if massage should be blocked. Suppress from chat frame and do not display in WIM.

Example The following hooking convention should be used. doing otherwise may prevent WIM from doing its own internal filter processing.

MyAddonName_WIM_API_Filter_orig = WIM_API_Filter;
WIM_API_Filter = MyAddonName_WIM_API_Filter;

function MyAddonName_WIM_API_Filter(theMsg, theUser)
     if( <check if should ignore> ) then
          return 1;
     elseif( <check if should block> ) then
          return 2;
     else
          return MyAddonName_WIM_API_Filter_orig(theMsg, theUser);
     end
end

It is important that you return the value of the original function, otherwise it will bypass any other hooks to this function as well as blocking WIM from doing any further processing.