Jump to content

Guidelines for Publishing Plugins


Recommended Posts

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."  

 

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.

 

 

 

  • Like 2
Link to post
Share on other sites
Guest
This topic is now closed to further replies.
×
×
  • Create New...