Adding Custom Menu/Button Items

There are a few ways that plugins can customize the farr interface, including setting custom statusbar icons/menus, and custom right-click context menu items for results.

To customize these you use the farr->set_strvalue command, for example:

 FARR.setStrValue("addmenu.statusbar","type=item|caption=MyTest|hint=this is hint|icon=help.ico|launch=restartsearch help");

This tells farr to add a button item to the statusbar (far right on bottom) which when clicked performs the launch action "restartsearch help".

When to Call addmenu:

It's important to know *when* you should call the addmenu command for different kinds of menus.

The statusbar "menu" gets cleared after every search -- because it's meant to show icons and menu buttons only relevant for the current search.  So you need to call addmenu at the start of every search where you want to add items.

The "contextmenu" addmenu command must be called at a very specific time, only after farr requests it from your plugin.  This happens when your plugin received an AllowProcessTrigger call with triggermode=PrepareContextMenu.

Syntax of addmenu commands:

call FARR.setstrvalue("addmenu.MENUNAME","MENUSTRINGS")

MENUNAME can currently be from: statusbar,contextmenu (more possibilities will come in future versions).

MENUSTRINGS has the following syntax:

Multiple items are separated by newlines (\n).

Each item consists of multiple field assignments separated by a | pipe character.

Each item must begin with a first field assignment of type:

type=TYPENAME

where TYPENAME is from: item, submenu, endmenu, separator

The item type describes a menu item or button; except for endmenu and separator types, it must contain a caption assignment, but others are optional:

caption=TEXT TO DISPLAY FOR MENU ITEM

icon=NAME OF FILE TO USE AS ICON, EITHER FULL PATH OR PLAIN FILENAME IF REFERING TO FILE IN FARR ICONS\ DIRECTORY

hint=TEXT TO DISPLAY ON MOUSE OVER

launch=LAUNCH COMMANDS TO RUN IF USER CHOOSES ITEM (SEPARATE MULTIPLE WITH $$$, SEE HERE FOR MORE HELP).

The submenu type should have a caption and can also have an icon and hint; launch values are ignored.

All items after a submenu are treated as children, until an endmenu type is parsed.  You can nest submenus.

For example:

 FARR.setStrValue("addmenu.statusbar","type=submenu|caption=GO2|icon=web\ntype=item|caption=MyTest|hint=this is hint|icon=help.ico|launch=restartsearch micro word \ntype=endmenu");

Other stuff:

Call FARR.setstrvalue("clearmenus","")

to clear the current statusbar icon menus.  This can be useful if you want to change the statusbar icons after a result is triggered, and/or after switching to html or memo mode.