Plugin API reference (2016)

The original protocol and class reference, including method signatures and ownership notes.

A reference from an earlier chapter

This material preserves the original Textual documentation and may describe older versions, former services, or superseded policies. It is not a statement of current availability or new Blendbyte commitments.

On this page

Textual Plugin Protocol Reference

Textual Plugin Protocol

Codeux Software, LLC

Hierarchy

Textual Plugin Protocol Reference

Class References

Protocol References

THOPluginProtocol

Generated by appledoc 2.2.1 (build 1334).

THOPluginDidPostNewMessageConcreteObject Class Reference

Textual Plugin Protocol

Codeux Software, LLC

Index
Hierarchy
On This Page

THOPluginDidPostNewMessageConcreteObject Class Reference

Inherits from	NSObject
Declared in	THOPluginProtocol.h

Overview

This object is a container for values related to [THOPluginProtocol didPostNewMessage:forViewController:]

`isProcessedInBulk`

Whether the message was posted as a result of a bulk operation

@property (readonly) BOOL isProcessedInBulk

Declared In

THOPluginProtocol.h

`messageContents`

The contents of the message visible to the end user

@property (readonly, copy) NSString *messageContents

Declared In

THOPluginProtocol.h

`lineNumber`

The ID of the message that can be used to access it using getElementByID()

@property (readonly, copy) NSString *lineNumber

Declared In

THOPluginProtocol.h

`senderNickname`

The nickname of the person and/or server responsible for producing the message.

@property (readonly, copy, nullable) NSString *senderNickname

Discussion

This value may be empty.

Declared In

THOPluginProtocol.h

`lineType`

The line type of the message

@property (readonly) TVCLogLineType lineType

Declared In

THOPluginProtocol.h

`memberType`

The member type of the message

@property (readonly) TVCLogLineMemberType memberType

Declared In

THOPluginProtocol.h

`receivedAt`

The date & time displayed left of the message in the WebView

@property (readonly, copy) NSDate *receivedAt

Declared In

THOPluginProtocol.h

`listOfHyperlinks`

Array of URLs found in the message body

@property (readonly, copy) NSArray<AHHyperlinkScannerResult*> *listOfHyperlinks

Declared In

THOPluginProtocol.h

`listOfUsers`

List of users from the channel that appear in the message

@property (readonly, copy) NSSet<IRCUser*> *listOfUsers

Declared In

THOPluginProtocol.h

`keywordMatchFound`

Whether or not a highlight word was matched

@property (readonly) BOOL keywordMatchFound

Declared In

THOPluginProtocol.h

Generated by appledoc 2.2.1 (build 1334).

THOPluginDidReceiveServerInputConcreteObject Class Reference

Textual Plugin Protocol

Codeux Software, LLC

Index
Hierarchy
On This Page

THOPluginDidReceiveServerInputConcreteObject Class Reference

Inherits from	NSObject
Declared in	THOPluginProtocol.h

Overview

This object is a container for values related to [THOPluginProtocol didReceiveServerInput:onClient:]

`senderIsServer`

Whether the input was from a regular user or from a server

@property (readonly) BOOL senderIsServer

Declared In

THOPluginProtocol.h

`senderNickname`

The nickname section of the sender’s hostmask

@property (readonly, copy) NSString *senderNickname

Discussion

The value of this property is the server address if senderIsServer is YES

Declared In

THOPluginProtocol.h

`senderUsername`

The username (ident) section of the sender’s hostmask

@property (readonly, copy, nullable) NSString *senderUsername

Declared In

THOPluginProtocol.h

`senderAddress`

The address section of the sender’s hostmask

@property (readonly, copy, nullable) NSString *senderAddress

Declared In

THOPluginProtocol.h

`senderHostmask`

The combined hostmask of the sender

@property (readonly, copy) NSString *senderHostmask

Declared In

THOPluginProtocol.h

`receivedAt`

The date & time during which the input was received

@property (readonly, copy) NSDate *receivedAt

Discussion

If the original message specifies a custom value using the server-time capacity, then the value of this property will reflect the value defined by the server-time capacity; not the exact date & time it was received on the socket.

Declared In

THOPluginProtocol.h

`messageSequence`

The input itself

@property (readonly, copy) NSString *messageSequence

Declared In

THOPluginProtocol.h

`messageParamaters`

The input, split up into sections

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

Declared In

THOPluginProtocol.h

`messageCommand`

The input’s command

@property (readonly, copy) NSString *messageCommand

Declared In

THOPluginProtocol.h

`messageCommandNumeric`

The value of messageCommand as an integer

@property (readonly) NSUInteger messageCommandNumeric

Declared In

THOPluginProtocol.h

`networkAddress`

The server address of the IRC network

@property (readonly, copy, nullable) NSString *networkAddress

Discussion

The value of this attribute is the address of the server that Textual is currently connected to and may differ from senderNickanme even if senderIsServer is YES

Declared In

THOPluginProtocol.h

`networkName`

The name of the IRC network

@property (readonly, copy, nullable) NSString *networkName

Declared In

THOPluginProtocol.h

Generated by appledoc 2.2.1 (build 1334).

THOPluginWebViewJavaScriptPayloadConcreteObject Class Reference

Textual Plugin Protocol

Codeux Software, LLC

Index
Hierarchy
On This Page

THOPluginWebViewJavaScriptPayloadConcreteObject Class Reference

Inherits from	NSObject
Declared in	THOPluginProtocol.h

Overview

This object is a container for values related to [THOPluginProtocol didReceiveJavaScriptPayload:fromViewController:]

`payloadLabel`

A description of the payload

@property (readonly, copy) NSString *payloadLabel

Declared In

THOPluginProtocol.h

`payloadContents`

The payload contents

@property (readonly, copy, nullable) id<NSCopying> payloadContents

Declared In

THOPluginProtocol.h

Generated by appledoc 2.2.1 (build 1334).

THOPluginProtocol Protocol Reference

Textual Plugin Protocol

Codeux Software, LLC

Index
Hierarchy
On This Page

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

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:

nil or a string with zero length indicates that there is no interest in modifying newMessage
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: 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:

The return value must be a valid URL for an image file if non-nil
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:

If a command is a number, then insert it into the array as an NSString
If a plugin tries to add a command already built into Textual onto this list, it will not work.
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.
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

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.

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)

Declared In

THOPluginProtocol.h

Generated by appledoc 2.2.1 (build 1334).

Textual Plugin Protocol Hierarchy

Textual Plugin Protocol

Codeux Software, LLC

Home

Textual Plugin Protocol Hierarchy

Class Hierarchy

NSObject

Protocol References

THOPluginProtocol

Generated by appledoc 2.2.1 (build 1334).

Source material

Original Codeux material preserved from the knowledgebase snapshot of 9 September 2026. Formatting and internal links have been adapted for this site.

Need a hand? Contact us about this guide.