# Plugin API reference (2016)

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

## Textual Plugin Protocol Reference


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Hierarchy](<https://www.textualapp.com/docs/legacy/developers/plugin-api#hierarchy>)



## Textual Plugin Protocol Reference

### Class References

- [THOPluginDidPostNewMessageConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidpostnewmessageconcreteobject>)

- [THOPluginDidReceiveServerInputConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject>)

- [THOPluginWebViewJavaScriptPayloadConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginwebviewjavascriptpayloadconcreteobject>)

### Protocol References

- [THOPluginProtocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginprotocol>)

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).





## THOPluginDidPostNewMessageConcreteObject Class Reference


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Index](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Hierarchy](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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:\]](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginprotocol-//api/name/didPostNewMessage%3AforViewController%3A>)



#### `  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 &amp; 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`

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).





## THOPluginDidReceiveServerInputConcreteObject Class Reference


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Index](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Hierarchy](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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:\]](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginprotocol-//api/name/didReceiveServerInput%3AonClient%3A>)



#### `  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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject-//api/name/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 &amp; 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 &amp; 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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject-//api/name/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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject-//api/name/senderIsServer>) is `YES`

##### Declared In

`THOPluginProtocol.h`


#### `  networkName`

The name of the IRC network

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

##### Declared In

`THOPluginProtocol.h`

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).





## THOPluginWebViewJavaScriptPayloadConcreteObject Class Reference


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Index](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Hierarchy](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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:\]](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginprotocol-//api/name/didReceiveJavaScriptPayload%3AfromViewController%3A>)



#### `  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`

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).





## THOPluginProtocol Protocol Reference


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Index](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Hierarchy](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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 &amp; 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:

- `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:** 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:

- 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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject>) |
| --- | --- |
| `client` | The client responsible for the event |

##### See Also

- `THOPluginDidReceiveServerInputConcreteObject`

##### 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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidpostnewmessageconcreteobject-//api/name/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

- `THOPluginDidPostNewMessageConcreteObject`

##### 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](<https://www.textualapp.com/docs/legacy/developers/plugin-api#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

- `THOPluginWebViewJavaScriptPayloadConcreteObject`

##### Declared In

`THOPluginProtocol.h`

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).





## Textual Plugin Protocol Hierarchy


## [Textual Plugin Protocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)


[Codeux Software, LLC](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)

- [Home](<https://www.textualapp.com/docs/legacy/developers/plugin-api#index>)



## Textual Plugin Protocol Hierarchy

### Class Hierarchy

- NSObject

  - [THOPluginDidPostNewMessageConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidpostnewmessageconcreteobject>)

  - [THOPluginDidReceiveServerInputConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thoplugindidreceiveserverinputconcreteobject>)

  - [THOPluginWebViewJavaScriptPayloadConcreteObject](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginwebviewjavascriptpayloadconcreteobject>)

### Protocol References

- [THOPluginProtocol](<https://www.textualapp.com/docs/legacy/developers/plugin-api#thopluginprotocol>)

Copyright © 2016 Codeux Software, LLC. All rights reserved. Updated: 2016-08-06

Generated by [appledoc 2.2.1 (build 1334)](<http://appledoc.gentlebytes.com>).
