How to Write an Effect Plugin (Part 6 - Adding Help)

[BoltBait]

This tutorial explains how to add help to your plugins.*

http://boltbait.com/pdn/CodeLab/help/tutorial6.php

___________________

*This tutorial requires paint.net v4.0.6+ and CodeLab v2.6+

[BoltBait]

I haven't seen any plugins updated with help yet (other than my own plugin pack, of course).

I thought this feature would be more popular.

Is anyone considering using this?

[MJW]

I like the new Help feature very much, and I'll use it soon. I've just been busy with some other things.

Edited August 6, 2015 by MJW

[Ego Eram Reputo]

I haven't time to add help to existing plugins (many of my larger project already have some sort of help built in).

New plugins will definitely have help added

[BoltBait]

BTW, to stay safe for high contrast screen modes, don't use any of the color tags in the [v] drop down list. Stick with all the other codes and you'll be fine.

[MJW]

I successfully added a Help menu to Texture Shader, and will update the published plugin as soon as I decide there are no further changes I want to make to Help.

 

I found a useful trick. If you paste formatted text into this edit window, then click the little Show BB Code switch, it will display the control codes for the the formatted text. That's quite handy for me, since I've usually included a proto-Help menu in the description of the plugins.
 
 

[MJW]

I have a question, which is mostly just out of curiosity, though it may be helpful to know for something I'm working on. I notice the CodeLab Help menu code includes:

 protected override void OnCustomizeConfigUIWindowProperties(PropertyCollection props)
{
     // Change the effect's window title
     props[ControlInfoPropertyNames.WindowTitle].Value = "HSV Eraser";
     // Add help button to effect UI
     props[ControlInfoPropertyNames.WindowHelpContentType].Value = WindowHelpContentType.CustomViaCallback;
     props[ControlInfoPropertyNames.WindowHelpContent].Value = Properties.Resources.Help;
     base.OnCustomizeConfigUIWindowProperties(props);
}

Is assigning the title necessary, and if so, can it be changed to:
 

props[ControlInfoPropertyNames.WindowTitle].Value = StaticName;

 

 

 

As an experiment, I tried removing the line in a CodeLab-based VS project, and for that specific case, the title still seemed to be correct in both the main menu and the Help menu.

Edited October 29, 2015 by MJW

[BoltBait]

These lines are there to set the effect window's title:

     // Change the effect's window title
     props[ControlInfoPropertyNames.WindowTitle].Value = "HSV Eraser";

Usually, they are only included if you specify:

// Title: HSV Eraser

in your script.

If you leave that line out, paint.net generates a title for your window automatically.

[MJW]

I think maybe I'm confused. I thought the window's title was determined by the StaticName property, which is defined whether or not the plugin has the Help feature. Plugins that don't have Help don't get the additional OnCustomizeConfigUIWindowProperties call added, but their windows have the correct titles.

[MJW]

Another question: I believe I know how the Help menu is enabled in IndirectUI plugins, but I was wondering if it could also be enabled in non-IndirectUI plugins, and if so, how.

 

The statements in IndirectUI are:

protected override void OnCustomizeConfigUIWindowProperties(PropertyCollection props)
{
    props[ControlInfoPropertyNames.WindowTitle].Value = "HSV Eraser";
    props[ControlInfoPropertyNames.WindowHelpContentType].Value = WindowHelpContentType.CustomViaCallback;
    props[ControlInfoPropertyNames.WindowHelpContent].Value = helpText;
    base.OnCustomizeConfigUIWindowProperties(props);
}

I don't really understand what the ControlInfoPropertyNames stuff does, but I know it's defined as part of IndirectUI, so I'm not sure what the equivalent thing is for non-IndirectUI plugins.

 

EDIT: On second thought, I don't think this even makes sense to ask, since the a non-IndirectUI plugin can enable the little question mark, and can display a Help Menu the same way it can display any other dialog. Since I've yet to write a non-IndirectUI plugin, I tent to forget such things.

Edited October 30, 2015 by MJW

[Ego Eram Reputo]

I think maybe I'm confused. I thought the window's title was determined by the StaticName property,

 

I'm pretty sure StaticName refers to the plugin name in paint.net's menu system. For a dialog title you might put "PornoErotica plugin - by EER © 2015", however the menu title would just be more concise like "PornoErotica". Having two entries allows a more verbose dialog title = more information.

[null54]

I'm pretty sure StaticName refers to the plugin name in paint.net's menu system. For a dialog title you might put "PornoErotica plugin - by EER © 2015", however the menu title would just be more concise like "PornoErotica". Having two entries allows a more verbose dialog title = more information.

 

Interesting choice of plugin name, I thought this was supposed to be a family friendly forum. 

[MJW]

Thank you very much, Ego Eram Reputo. That's exactly what it is. I guess the reason I haven't seen the OnCustomizeConfigUIWindowProperties routine before in compiled CodeLab source is that in the past, before the blank header comments were automatically added in CodeLab, I just specified the Name and let it be inherited as the Title. In that case, prior to the Help menu stuff, no code for OnCustomizeConfigUIWindowProperties was generated. Eliminating the assignment didn't change the results for me, since the Title matched the Name in my plugin.

 

The real question I had was whether that assignment was somehow tied into the Help menu or was something unrelated.

Edited October 30, 2015 by MJW

[Ego Eram Reputo]

Interesting choice of plugin name, I thought this was supposed to be a family friendly forum. 

I used that name in the unpublished guide. I was merely being......consistent.

[Red ochre]

^Smutty Dwarf!

( a very useful guide though )

[Ego Eram Reputo]

No one forgets that plugin name

Another question: I believe I know how the Help menu is enabled in IndirectUI plugins, but I was wondering if it could also be enabled in non-IndirectUI plugins, and if so, how.

 

....

...a non-IndirectUI plugin can enable the little question mark, and can display a Help Menu the same way it can display any other dialog. Since I've yet to write a non-IndirectUI plugin, I tent to forget such things.

Help button is given as an example in the guide. Create the button, tie its click event to messagebox.show and you have a very easy help dialog.

[MJW]

Adding the little question-mark Help button at the top of the window's frame is done a bit differently than adding a standard button. Something like:

form.HelpButton = true;
form.HelpButtonClicked += new System.ComponentModel.CancelEventHandler(HelpButtonClicked);

The event handler is standard, except it must cancel the Help event.

public void HelpButtonClicked(Object sender, System.ComponentModel.CancelEventArgs e)
{
     e.Cancel = true;
     System.Windows.Forms.MessageBox.Show("This is the help text");
}

Edited October 31, 2015 by MJW

[Ego Eram Reputo]

Much more elegant! I might add that to the guide. Thanks for the tip.

[midora]

OK, I can activate the help button in PropertyBased plugins

 

protected override void OnCustomizeConfigUIWindowProperties(PropertyCollection props)
{
    props[ControlInfoPropertyNames.WindowHelpContentType].Value = WindowHelpContentType.CustomViaCallback;
    base.OnCustomizeConfigUIWindowProperties(props);
}

 

and provide the method

 

private void OnWindowHelpButtonClicked(IWin32Window owner, string helpContent)
{
}

 

this works, but how?

 

The method is private and doesn't use override. Is it handled via Reflection?

 

[toe_head2001]

4 hours ago, midora said:

this works, but how?

 

The method is private and doesn't use override. Is it handled via Reflection?

 

Correct, the method is invoked via Reflection.