Plugin Development - Questions about the plugin API.

Hey, all. Recent buyer of TrueLaunchBar and now am trying my hand at some plugin development.

Some questions:

1) What is the full list of supported formatting tags within the tooltip-like description? So far I've discovered <b> (bold), <i> (italics), <t> or \t (tab),
or
(line break), <hr> and <hr=100%> for a horizontal rule. Are there any others I don't know about?

2) Some plugins, like Network Monitor, display an icon within their description popup. Where is that icon set? How can I do something similar?

3) Where can I find a detailed description of what all of the BTNINFO_MASK_* mask values are for? Here is what I've determined so far:

BTNINFO_MASK_ACTIONS:
A request for what different actions should be available in the right-click context menu for the plugin. CTMS_PROPERTIES for a properties option, CTMS_RENAME for a rename option, CTMS_CHANGEICON for a change icon option and CTMS_HOVERRUN which allows user to have the plugin 'run' just by hovering the mouse.

BTNINFO_MASK_MODEFLAG:
A request for 'mode' status. What exactly are the BTN_FLAG_PLANE, BTN_FLAG_STOPDRAG and BTN_FLAG_COLAPCEONRUN different modes for? How are they used?

BTNINFO_MASK_SIZE:
BTNINFO_MASK_ACTUALSIZE:
I assume this is a size request.. so put the current size of your plugin button into btninf->szBtnSize. What is the difference between the two?

BTNINFO_MASK_ICON:
BTNINFO_MASK_SELECTEDICON:
Not sure. Example code just sets this to NULL. I've tried setting btninfo->hIcon it to a valid icon but cannot see where that icon is used. Also, what is difference between the two?

BTNINFO_MASK_DESCRIPTION:
A request for the current button description for display within the tooltip popup. How is this mask value different from the GetDescription() method? In the sample code, it seems to just duplicate the code between the two and only use the version in GetButtonInfo(). Is the GetDescription() method ever called instead of GetButtonInfo() ?

BTNINFO_MASK_TEXT:
It seems if you specify text into btninfo->strData and then select Appearance->TextLabel from the bar context menu, the text gets displayed along with your button.


4) What is InvokeCommand() used for? What are potential IDs that can occur?

5) What is Invoke() used for? I found the following comments in a .h file:
#define TBTN_INVOKE_GETTOOLTIPSCOUNT 1 // wParam ignored, (int*) lParam - tooltips count
#define TBTN_INVOKE_GETTOOLTIPRECT 2 // wParam - zero based tooltip index, (RECT*) lParam - rectangle of tooltip
#define TBTN_INVOKE_GETTOOLTIPTEXT 3 // wParam - zero based tooltip index, (char*) lParam - Text of tooltip (1024 max)
How exactly are these used? Does this somehow override the regular 'description' call?

6) What is SetLCID() ?

7) In StateChanged(), what are the possible values of 'state' ?

A lot of this would have been solved if the interface headers and .cpp files in the SDK were commented! Developing a plugin is very difficult when you have to guess at all the interfaces and how they might be used.

The examples provided did show some usage, but again without comments, so I could see it being used but didn't really understand what was happening.

Thanks! This is a really excellent program.. and I would love to see more third party plugin development get off the ground.

antidigerati

The details for tips is here for now, as it is a feature of the beta releases.

I can't answer your remaining questions, as I've had little chance to look over the SDK.

2) Some plugins, like Network Monitor, display an icon within their description popup. Where is that icon set? How can I do something similar?

Here you can download the sources of Net Monitor, Command Line and the last version of TLB PDK.

To add icon see the CNetMonBtn::Invoke with id == TBTN_INVOKE_GETTIPSICON

3) Where can I find a detailed description of what all of the BTNINFO_MASK_* mask values are for?

BTNINFO_MASK_MODEFLAG: You must fill the BUTTONINFO.dwMask field with combination of flags:
BTN_FLAG_PLANE - the button is always flat like Net Monitor. You will never get Run for this button.
BTN_FLAG_STOPDRAG - Disable Drag&Drop for button. Set when you drag sliders or others controls inside plugin.
BTN_FLAG_COLAPCEONRUN - Not used
BTN_FLAG_NOTIPS - Disable tips for plugin
BTN_FLAG_SUPPORTSAVEDICON - in design right now
BTN_FLAG_SUPPORTPNGICONS - in design right now
BTN_FLAG_INPLACERENAME - in design right now

BTNINFO_MASK_ACTIONS: BUTTONINFO.dwActions
TLB asks for supported actions. If some of action must be performed then TLB calls DoAction method with one of flags. Can be combinations of flags:
CTMS_PROPERTIES - Plugin supports Properties
CTMS_RENAME - Plugin supports renaming
CTMS_CHANGEICON - Plugin supports "Change Icon" feature
CTMS_HOVERRUN - Plugin supports hover run feature (if enabled in TLB)
CTMS_FINDTARGET - Plugin supports "Find Target" feature
CTMS_OPENFOLDER - Plugin supports "Open Folder" feature
CTMS_NODELETE - not used
CTMS_RESETICON - Plugin supports "Reset Icon" feature
CTMS_SETIMAGE - Plugin supports "Set Image" feature
CTMS_ABOUT - Plugin supports "About" feature (will be released in the next version of TLB)
CTMS_DELETE - Plugin supports "Delete" feature.

BTNINFO_MASK_SIZE: The size of plugin. The size can be different if plugin insize toolbar and when on menu.

BTNINFO_MASK_ACTUALSIZE: The size of plugin when it is placed on toolbar. You must ignore the real location of plugin.

BTNINFO_MASK_ICON, BTNINFO_MASK_SELECTEDICON: not used.
BTNINFO_MASK_DESCRIPTION: The tip text. But in the last versions is not used. (btninfo->strData)
BTNINFO_MASK_TEXT: If you implement this TLB draw text with all current styles and when needed. (btninfo->strData)

4) What is InvokeCommand() used for? What are potential IDs that can occur?

Invoke command from context menu. First you must implement QueryContextMenu:

Code:

STDMETHODIMP_(int) ITlbButton::QueryContextMenu(HMENU hMenu, int index, int cmdFirst, int cmdLast)

hMenu - Insert your menu items here
index - Insert you items from this index
cmdFirst - Beginning of commands ID
cmdLast - End of commands ID (actually can be ignored).
Return value Number of items you have inserted into menu.

When user click one of menu item you've inserted then TLB call InvokeCommand with ID == menuItemID - cmdFirst.

What is Invoke() used for? I found the following comments in a .h file

This method used for extending TLB. Most of new features are released using this method. You must switch by ID, see sources.

6) What is SetLCID() ?

This function used for localization of plugins. TLB call this function with laguage ID and resource module if exists.

7) In StateChanged(), what are the possible values of 'state' ?

TS_STATE_NORMAL
TS_STATE_OVER
TS_STATE_DOWN
TS_STATE_OPENACTIVE (menu is opened and active)
TS_STATE_OPENINACTIVE (menu is opened and not active)

The examples provided did show some usage, but again without comments, so I could see it being used but didn't really understand what was happening.

I'm working on documentation for PDK and the classes that can simplify developing. When I'm finish this work I'll open special section for developers on wesite. Right now you can ask any question here.

For samples you need CxImage library. You can download it here

Yuri, you are awesome.

Thanks for all the excellent details and the pointer to the latest library. I'll need some time to digest all of this but really appreciate your response!

Thanks!

I think your reply should go into the FAQ or into a permanent plugin development thread.

antidigerati