THOPluginProtocol Protocol Reference

Conforms to NSObject
Declared in THOPluginProtocol.h

Overview

The THOPluginProtocol protocol defines methods and properties that the primary class of a plugin can inherit from.

Initialization

– pluginLoadedIntoMemory

Method invoked during initialization of a plugin.

- (void)pluginLoadedIntoMemory

Discussion

This method is invoked very early on. It occurs once the principal class of the plugin has been allocated and is guaranteed to be the first call home that a plugin will receive.

Declared In

THOPluginProtocol.h

– pluginWillBeUnloadedFromMemory

Method invoked prior to deallocation of a plugin.

- (void)pluginWillBeUnloadedFromMemory

Declared In

THOPluginProtocol.h

Input Manipulation

– receivedText:authoredBy:destinedFor:asLineType:onClient:receivedAt:wasEncrypted:

Method invoked to inform the plugin that a plain text message was received (PRIVMSG, ACTION, or NOTICE)

- (BOOL)receivedText:(NSString *)text authoredBy:(IRCPrefix *)textAuthor destinedFor:(nullable IRCChannel *)textDestination asLineType:(TVCLogLineType)lineType onClient:(IRCClient *)client receivedAt:(NSDate *)receivedAt wasEncrypted:(BOOL)wasEncrypted

Parameters

text

The message contents
textAuthor

The author (sender) of the message
textDestination

The channel that the message is destined for
lineType

The line type of the message

Possible values: TVCLogLinePrivateMessageType, TVCLogLineActionType, TVCLogLineNoticeType
client

The client the message was received on
receivedAt

The date & time of the message. Depending on whether a custom value was specified using the server-time IRCv3 capacity, this NSDate object may be very far in the past, or even possibly in the future.
wasEncrypted

Whether or not the message was encrypted

Return Value

YES to display the contents of the message to the user, NO otherwise.

Discussion

This method is invoked on the main thread which means that slow code can lockup the user interface of Textual. If you have no intent to ignore content, then do work in the background and immediately return YES.

Declared In

THOPluginProtocol.h

– interceptServerInput:for:

Method used to modify and/or completely ignore incoming data from the server.

- (nullable IRCMessage *)interceptServerInput:(IRCMessage *)input for:(IRCClient *)client

Parameters

input

An instance of IRCMessage
client

The client responsible for the event

Return Value

The original and/or modified copy of IRCMessage or nil to prevent the data from being processed altogether.

Discussion

Warning: This method is invoked on each plugin in the order loaded. This method does not stop for the first result returned which means that value being passed may have been modified by a plugin above the one being talked to.

Warning: Textual does not perform validation against the instance of IRCMessage that is returned which means that if Textual tries to access specific information which has been improperly modified or removed, then the entire application may crash.

Declared In

THOPluginProtocol.h

– interceptUserInput:command:

Method used to modify and/or completely ignore text entered into the main text field of Textual.

- (nullable id)interceptUserInput:(id)input command:(IRCPrivateCommand)command

Parameters

input

The value of the text field as either an instance of NSString or NSAttributedString.
command

Textual allows the end user to send text entered into the text field as an action without using the /me command. When this occurs, Textual informs lower-level APIs of this intent by changing the value of this parameter from “privmsg” to “action” — In most cases a plugin should disregard this parameter and pass it untouched.

Return Value

The original and/or modified copy of input or nil to prevent the data from being processed altogether.

Discussion

Warning: This method is invoked on each plugin in the order loaded. This method does not stop for the first result returned which means that value being passed may have been modified by a plugin above the one being talked to.

Declared In

THOPluginProtocol.h

Preferences

  pluginPreferencesPaneView

Defines an NSView used by the Preferences window of Textual to allow user-interactive configuration of the plugin.

@property (nonatomic, readonly, strong) NSView *pluginPreferencesPaneView

Return Value

An instance of NSView with a width of at least 590.

Declared In

THOPluginProtocol.h

  pluginPreferencesPaneMenuItemName

Defines an NSString which is used by the Preferences window of Textual to create a new entry in its navigation list.

@property (nonatomic, readonly, copy) NSString *pluginPreferencesPaneMenuItemName

Declared In

THOPluginProtocol.h

Renderer Events

– willRenderMessage:forViewController:lineType:memberType:

Method invoked prior to a message being converted to its HTML equivalent.

- (NSString *)willRenderMessage:(NSString *)newMessage forViewController:(TVCLogController *)viewController lineType:(TVCLogLineType)lineType memberType:(TVCLogLineMemberType)memberType

Parameters

newMessage

An unedited copy of the message being rendered
viewController

The view responsible for the event
lineType

The line type of newMessage
memberType

The member type of newMessage

Return Value

The original and/or modified copy of newMessage

Discussion

This methods can be used to modify the text that will be displayed for a certain message by replacing one or more segments of it.

Considerations:

  1. nil or a string with zero length indicates that there is no interest in modifying newMessage
  2. There is no way to inform the renderer that you do not want a specific value of newMessage shown to the end user. Use the various other methods provided by the THOPluginProtocol to accomplish that task.

Warning: This method is invoked on each plugin in the order loaded. This method does not stop for the first result returned which means that value being passed may have been modified by a plugin above the one being talked to.

Warning: Under no circumstances should you insert HTML at this point. Doing so will result in undefined behavior.

Declared In

THOPluginProtocol.h

– processInlineMediaContentURL:

Given a URL, returns the same URL or another that can be shown as an image inline with chat.

- (nullable NSString *)processInlineMediaContentURL:(NSString *)resource

Parameters

resource

A URL that was detected in a message being rendered.

Return Value

A URL that can be shown as an inline image in relation to resource or nil if there is no interest in the URL.

Discussion

Considerations:

  1. The return value must be a valid URL for an image file if non-nil
  2. Textual uses the first non-nil, valid URL returned by any plugin. It does not chain the responses similar to other methods defined by the THOPluginProtocol protocol.

Declared In

THOPluginProtocol.h

Subscribed Events

  subscribedUserInputCommands

Defines a list of commands that the plugin will support as user input from the main text field.

@property (nonatomic, readonly, copy) NSArray<NSString*> *subscribedUserInputCommands

Return Value

An NSArray containing a lowercase list of commands that the plugin will support as user input from the main text field.

Discussion

Considerations:

  1. If a command is a number, then insert it into the array as an NSString
  2. If a plugin tries to add a command already built into Textual onto this list, it will not work.
  3. It is possible, but unlikely, that another plugin the end user has loaded is subscribed to the same command. When that occurs, all plugins subscribed to the command will be informed of when the command is performed.
  4. To avoid conflicts, a plugin cannot subscribe to a command already defined by a script. If a script and a plugin both share the same command, then neither will be executed and an error will be printed to the console.

Declared In

THOPluginProtocol.h

– userInputCommandInvokedOnClient:commandString:messageString:

Method invoked when a subscribed user input command requires processing.

- (void)userInputCommandInvokedOnClient:(IRCClient *)client commandString:(NSString *)commandString messageString:(NSString *)messageString

Parameters

client

The client responsible for the event
commandString

The name of the command
messageString

Data that follows commandString

Declared In

THOPluginProtocol.h

  subscribedServerInputCommands

Defines a list of commands that the plugin will support as server input.

@property (nonatomic, readonly, copy) NSArray<NSString*> *subscribedServerInputCommands

Return Value

An NSArray containing a lowercase list of commands that the plugin will support as server input.

Discussion

If a command is a number, then insert it into the array as an NSString

Declared In

THOPluginProtocol.h

– didReceiveServerInput:onClient:

Method invoked when a subscribed server input command requires processing.

- (void)didReceiveServerInput:(THOPluginDidReceiveServerInputConcreteObject *)inputObject onClient:(IRCClient *)client

Parameters

inputObject

An instance of THOPluginDidReceiveServerInputConcreteObject
client

The client responsible for the event

See Also

Declared In

THOPluginProtocol.h

WebView Events

– didPostNewMessage:forViewController:

Method invoked when the Document Object Model (DOM) of a view has been modified.

- (void)didPostNewMessage:(THOPluginDidPostNewMessageConcreteObject *)messageObject forViewController:(TVCLogController *)viewController

Parameters

messageObject

An instance of THOPluginDidPostNewMessageConcreteObject
viewController

The view responsible for the event

Discussion

This method is invoked when a message has been added to the Document Object Model (DOM) of viewController

Warning: Do not do any heavy work when the isProcessedInBulk property of messageObject is set to YES because thousand of other messages may be processing at the same time.

Warning: This method is invoked on an asynchronous background dispatch queue. Not the main thread. If you interact with WebKit when this method is invoked, then make sure that you do so on the main thread. If you don’t, WebKit will throw an exception.

See Also

Declared In

THOPluginProtocol.h

– didReceiveJavaScriptPayload:fromViewController:

Method invoked when the JavaScript function app.sendPluginPayload() is executed.

- (void)didReceiveJavaScriptPayload:(THOPluginWebViewJavaScriptPayloadConcreteObject *)payloadObject fromViewController:(TVCLogController *)viewController

Parameters

payloadObject

An instance of THOPluginWebViewJavaScriptPayloadConcreteObject
viewController

The view responsible for the event

Discussion

A plugin that injects JavaScript into Textual’s WebView can use this method to send data back to the plugin.

A payload can be passed by invoking the JavaScript function app.sendPluginPayload(payloadLabel, payloadContent)

Warning: This method is invoked on an asynchronous background dispatch queue. Not the main thread. If you interact with WebKit when this method is invoked, then make sure that you do so on the main thread. If you don’t, WebKit will throw an exception.

See Also

Declared In

THOPluginProtocol.h