Plugin Development


  1. Introduction
  2. The filename
  3. Plugin parameters
  4. Script/Function parameters
  5. Conventions
  6. Plugin Classes
  7. Things to Note
  8. Libs
  9. Developers Complete List


Introduction

Plugins are AutoHotkey scripts that are run by the Clipjump.exe which is nothing but AutoHotkey.exe in disguise.
Some plugins are included in the program at runtime, some are not (external class). There is no limit on the number of plugins and they can be always accessed from the Plugin Manager (ActionMode = M)


The Filename

The filename of the plugin symbolizes the function it is supposed to contain.
If filename is myplugin.ahk , it means the plugin file contains a plugin_myplugin() that is run by the Plugin Manager or API.runPlugin(). If the filename is pformat.noformatting.ahk , the main function the file has is plugin_pformat_noformatting().


Plugin Parameters

If you open any of the officially distributed plugins in Notepad, you will see lines starting with ;@Plugin-. These hold the key-value pairs that have information about the Plugins.
So ;@Plugin-Name myplugin gives the key name for the plugin the value myplugin. As you may have guessed this is the same thing you see when you click on Properties in the Plugin Manager.
There is no limit on what can be the 'key' here. Even ;@Plugin-authorSite http://mysite.com also works and is shown in the Properties window.


Script/Function parameters

The Plugin parameters like ;@Plugin-param(N) where N is a natural number are the Function parameters (like ;@Plugin-Param1). They hold information about the Nth parameter of the main function in the plugin file. When you run a plugin with API.runPlugin( plugin_filename , param1, param2 ....) without any 'param's , the function auto-asks you the parameters showing these informations if they are present. You can provide a parameter as ;@Plugin-Silent 1 to force API.runPlugin() to not ask the user for parameters even if no parameter is passed to it.
Function parameters are not Mandatory but it is recommended to provide them.


Conventions

  1. Variable Names in plugin files that are included (not external) should start with z. This is because Clipjump doesn't uses any variable starting with 'z' and so this is the best option to avoid variable conflicts.
  2. The parameter names in the function definition ( plugin_myplugin(zParam1, zParam2) ) should also start with 'z'.
TIP- You can use the STORE object to also store variables. It is a global object and is totally meant for storing by plugins and through ClipjumpCustom.ini. Eg> STORE.myvar := "text" and zVar := STORE.myvar


Plugin Classes

'Classes' is a way to distinguish certain plugins from normal plugins. All the plugins whose name is like a.b.ahk and not b.ahk mean they belong to a class (here a).
As already said, these files have main function like plugin_a_b(). Currently Clipjump has 2 defined classes. User is not allowed to create them. (i.e. create a file like xyzPlugin.coreScript.ahk)

pformat

The plugins in this class are used in the paste-format option in Paste mode (key = Z). Officially distributed plugins like pformat.sentencecase.ahk and pformat.noformatting.ahk belong to this class.
  1. These plugins also have a custom mandatory parameter ;@Plugin-Previewable which should hold 1 if the paste format is previewable in Paste Mode. It is 1 for SentenceCase.
  2. These Plugins should make STORE.ClipboardChanged true if they have successfully changed the input variable and thus what is going to be pasted.
    For example STORE.ClipboardChanged := true
  3. It should be noted that these plugins (should) have 1 input parameter. See the file 'pformat.sentencecase.ahk' for example.
  4. When toggling and when pasting, Clipjump inputs the Clipboard variable and not the ClipboardAll variable as the first parameter. If the plugin needs the ClipboardAll variable, it can consult it anytime as it will be the same as what current active

external

Plugins whose name starts with external. belong to the 'external' class. They are not included in Clipjump at runtime and solely run through the AutoHotkey.exe (i.e. Clipjump.exe) when needed.
The Parameters in external plugins ? Like Function parameters , the external script file can contain -Param1, -Param2 and so.. for the API.runPlugin() to take them as Script parameters and thus ask the user if they pass no paramter.
For example try running the external.controller.ahk and then seeing its source code.


Things to Note

  1. Use ;@Plugin-Silent 1 to make API.runPlugin() not ask the user for parameters even if user doesn't enters them.
  2. It will be a good idea to use API.showTip() and API.removeTip() (Link)
  3. While testing keep in mind that your plugin will be included in Clipjump.ahk and thus run from the directory of Clipjump.ahk. So be careful with the WorkingDir factor.
  4. There will be no auto-execution of any plugin as a non-external plugin will be included at the bottom of Clipjump.ahk
  5. Please reload Clipjump when you change/add a plugin file to load it into Clipjump.
  6. Make sure to have a look at The Complete Developer List and the public API


Libs

If your plugin file requires more files as #Includes, consider keeping them in (file_name).lib directory. So for the plugin external.controller.ahk we have external.controller.lib as the lib directory. This makes the Delete Plugin option in Plugin Manager work.




Translate