Guidelines for Publishing Plugins

[Ego Eram Reputo]

Plugin Guidelines

 

Plugins can do many things, especially given the creativity of some of our authors here. However, there are some things that plugins should not do. 

 

For some of these rules, if you break them then you are simply not guaranteed that your plugin will work in any future version of Paint.NET. For others, your plugin may be removed from the forum if you break the rule. Just because something is possible does not mean it is okay.

 

This list may be amended in the future as we find and/or document other best practices, guidelines, and rules. Some rules will become moot for various reasons: new plugin types will be introduced, or runtime measures will block certain "bad" behavior.

 

If a rule uses the word "must", then your plugin will be removed for breaking the rule. If you are just developing something for your own personal use, feel free to break whatever "rules" you want.

 

If a rule uses the word "should", then your plugin may break in future versions of Paint.NET. No attempt at compatibility will be maintained, even for very popular plugins. You have been warned!

 

1       Effect plugins must follow "the rules." This means it…

1.1.    Must not write to the source surface.

1.2.    Should not write to the destination surface except where indicated by "rois" (region of interest).

1.3.    Rendering must only happen in the Effect's Render/OnRender methods, and should not occur in the EffectConfigDialog or EffectConfigToken implementations. Do not render to the DstArgs except in OnRender.

 

2.       Plugins must not require the installation of any "beta" software components.

This includes beta or "CTP" versions of the .NET Framework, and even Paint.NET itself. However, feel free to publish these in the "Plugin Developer's Central" section.

 

3.       FileType plugins must not masquerade as "export" plugins. Nor must they have other "side effects."

A plugin which "exports to photobucket" would be completely inappropriate because the user would asked to choose a file, and then your UI would upload the file somewhere, and then the user would have a 0-byte file on their disk because you ignored the Stream object that Paint.NET handed to you (see 4). These types of plugins will be deleted.

 

4.       FileType plugins must always use the Stream they are given.

You must not assume the Stream is any particular type (e.g. a FileStream, which might give you additional information such as the file name or path). It may be a FileStream, MemoryStream, SiphonStream, GuardedStream or a SodaStream. It might even be something determined at runtime.

 

5.       Plugins must not use "reflection" to try and "hack" Paint.NET. For example, using some of the stuff in System.Reflection, you could potentially add stuff to the File menu, or create new toolbar items. Or even new tools. Don't do this.

 

6.       Plugins must not use reflection to reach into Paint.NET's internals.

 

The text and images that Paint.NET uses for its own user interface are not for plugins. Strings are not guaranteed to have the same text between versions, or to even exist. Same with images. If you want to take advantage of the localized text for effect submenus such as Artistic, Blurs, Distort, etc. then please use the static SubmenuNames class.

 

In 4.0, many classes have been marked as 'internal'. If something is private or internal, then it's off-limits. Do not use reflection to reach in to get access. This includes instantiating classes, accessing private fields, etc. NOTE: Just because something is "public" does not mean it is okay to use.

 

If your plugin has been using these, please make sure that your next update does not. If you need functionality from the PaintDotNet.Resources DLL, please ask. Rick will decide if it is worth making something available in one of the other DLLs (Base, Core, Data, Effects).

 

7.       Plugins must not modify the Paint.NET user interface.

Plugins are not allowed to modify Paint.NET's UI in any way such as by adding menu commands, etc.

  

8.       Plugins must not use UI controls from PaintDotNet.Core.dll, PaintDotNet.Data.dll, or PaintDotNet.Framework.dll.

This includes classes such as DocumentView, ImageListMenu, SurfaceBox, and TaskDialog. These should be treated as "internal" to Paint.NET. There have been many changes in 4.0 as to how these are organized, and any plugins which are using these controls will likely not work. Please make sure your next plugin update takes that into account. If there is a control that you are using that you need, please ask.

 

9.      Plugins must not use the built-in FileTypes in PaintDotNet.Data.dll

In 4.0, these have been moved into PaintDotNet.exe and are 'internal'. So, your plugin will break.

 

10.    Plugins must not require replacing any of the Paint.NET DLL or EXE files.

In other words, a user should not have to install a modified version of Paint.NET in order to use your plugin. This will really put the user in a bad situation when they go to install the next update.

 

11.    Plugins should not use anything from the SystemLayer DLL.

This DLL is very much subject to change for all sorts of reasons. It is not a utility library for plugins to use. If there is functionality on SystemLayer that your plugin would benefit from, or even require, then please ask for it and I will see about making something available in PaintDotNet.Base, Core, Data, or Effects.

 

12.   Don't publish Plugins that are simply compilations of effects.

By all means make them for your own use, but do not publish them here unless you're sure a Mod will go "Wow". Even then, another Mod may go "Meh" and delete it.

 

13.   Please don't be in a rush to publish Plugins.

As a rule of thumb, if you have little experience writing C# apps, then think twice before posting a plugin. As BoltBait said, "Noobs should be using plugins, not publishing them."  

 

14. No publishing plugins written by AI

 

15. When distributing a plugin, don't assume users will know what to do with your dll file.  Be sure to include some type of installer with your plugin.  CodeLab will build an Install.bat file for you which is fine--it can even install to the store version.  So, use it.

  

 

Specifically, your plugin may NOT….

 

Read the recent files list

Read the PDN window title

Send Ctrl-S or any other shortcut

Parse installed FileTypes or the like

Modify the input in OnSave()

 

All that said, if you are just playing with plugins for your own private use, then feel free to do whatever you want!

 

Things which are allowed

 

Effect plugins may use the built-in Effects in PaintDotNet.Effects.dll

I've decided to officially keep the programmatic interface for these backwards-compatible. If there are changes that I must make, and there are plugins using what is changing, then I will find a way to preserve backwards compatibility.  

 

Your FileType plugin can embed whatever you want for the file type that you're saving as.    

 

Limitations of the Plugin model:

Effects

·         Effects can only access the current layer.

·         Effects can only access the current image.

·         Effects cannot know or change the blend mode or transparency of a layer.

·         Effects can blend two images using transparency and blend modes.

·         Effects can read the whole layer, even if part of it is selected.

·         If part of a layer is selected, effects can only change that part.

·         Although effects can't be tools or anything, they can show a new dialog to draw on.

·         Effects can save files, but only with the information they have (see above) and they can't make the file they save the current FileName.

·         Effects have no control over the UI other than the ability to add items and categories to the effects and adjustments menus.

·         Effects can not change the shape of the selection or which pixels are selected.

·         Most effects need to be heavily modified before they can run outside Paint.NET.

·         Effects can open files and read them from your harddrive or Internet URL.

·         Effects can read the Windows clipboard.

·         Effects can read all of the color values in the current and default palette.

·         Effects can add a [?] button to the effect's IndirectUI for adding a help file.

FileTypes (Opening)

·         FileTypes don't know the location of the image they're opening.

·         FileTypes can create as many layers as they want and change opacity and blend modes.

·         FileTypes must open some image.

·         FileTypes have no control over the open dialog.

FileTypes (Saving)

·         FileTypes don't know the location of the image they're saving to.

·         FileTypes can read all layers, opacity and blend modes.

·         FileTypes have to save a file unless the user clicks "cancel," even if it is empty - this is frowned upon by Rick.

·         FileTypes have no control over the save dialog.

 

 

 

[Ego Eram Reputo]

Plugin authors are politely asked to consider the following when publishing new Effects, FileTypes and Adjustments.

 

P1. The thread title should include the effect name. Optional (and encouraged) include the date of the most recent update.
P2. The first post in the thread should contain the most recent/current zip of the effect .dll or a link to where it can be downloaded.
P3. Do include a brief description of what the effect/adjustment does. Ideally make the brief description a one or two sentence summary for the plugin index. A separate, more detailed description can be included for interested users.
P4. Include at least one image showing what the effect does. Before and after images are useful.

P5. Include an image showing the user interface (if there is one). This can often be combined with the demo images in 4.

P6. Do include which menu the effect can be found in for example "Effects/Render", or Effects > Render.
P7. Do mention any known issues for example if it is not compatible with certain versions of paint.net or if it may be slow for large selections.
P8. If you wish to share your code, it is best to place it in a hidden code block. State any license which applies. Example: Reptillian's  Popcorn Fractal

P9. When compiling your plugin, we encourage you to include keywords and a sample image for the Plugin Browser. A guide on how to include these in your effect can be found here.

P10. It is helpful if you also specifically include the name of the DLL (and any supporting files).

 

 

 

When updating a plugin...

 

U1. Always update the zip or link in the first thread post (see note 2 above).

U2. Add a new note in the thread to inform users that a new version has been published. It makes sense to tell users why a new version has been published.

U3. Optional: include a history of the plugin versions in the first post. Version Number, Release Date and the Reason for the update. Here's how BoltBait does it in his Meme Maker plugin thread.....

 

Quote

Versions:

-1.3 Added shadow option 

-1.2 Fixed a bug when centering in a selection

-1.1 Added separate size for each text, Added ability to use Primary/Secondary colors

-1.0 Initial Release

 

  This list was suggested by Red Ochre. Good 'innit?