Open With Plugin Help

Customising the ‘Open With’ Menu

Each row in the grid in the plugin configuration dialog represents a possible menu item to include in your menu. Depending on the operating system platform that you are running Calibre on you will see a different set of default applications included with the plugin for your convenience with default application installation paths. Or you can add your own (or edit the existing ones) as required.

The following table details each column in the grid. You can double-click any cell in the grid to edit its value.

*Active*	Items ticked in this first column will appear in your menu. A small selection of menu items have been ticked as a default selection to get you started.
*Menu Text*	The name to appear in the menu. Leave this blank if you want a separator row to appear between your menu items (other columns will be ignored). You must have a value in this column before you can edit the later columns. Erasing the value in this column will clear the other columns (as not valid for separator rows)
*Submenu*	An optional sub-menu name to display this menu item within. If you have many menu items you may find it more manageable to group them within sub-menus. So for instance typing Amazon into this column for all the Amazon rows in the grid will ensure they are displayed within an “Amazon” sub-menu when the “Search the Internet” menu is expanded.
*Format*	The format of the selected book this application should be passed on the command line, such as EPUB, MOBI etc. A special value of COVER will instead allow passing the filename of the cover.jpg associated with the book, such as a paint program for cropping etc.
*Image*	The filename of an image icon to display next to your menu item, leave blank for no image. Images for the supplied menu items are included in the plugin zip file. To add your own image files, choose the Add New Image... menu item within the combobox.
*Application Path*	The physical file path to the executable application for this menu item. Included are the default paths for various applications on Windows 32-bit and 64-bit operating systems. If you use different versions of the applications or a different operating system then you must edit these to suit your installed locations. Double click on this cell to bring up a file chooser dialog allowing you to select the application to execute.
*Args*	Optional command line arguments that are to be passed along with the filename to the application. Multiple arguments should be comma separated. E.g. an application requiring command line switches of “-foo 100 –bar” on the command line should have “–foo 100,-bar” specified in this column (without quotes). Args specified here will be insert before the filename i.e. {Path to application} [args] {Path to book format or cover} IMPORTANT for OSX Users: Command line arguments for OSX applications are NOT currently supported and any specified here will be ignored.

The buttons available perform the following functions:

Move Up / Move Down – Change the order the included items will appear in your menu. You can select multiple rows at once to move up and down.
Add – Adds a blank row for you to create your own application menu link below the currently selected row.
Delete – Allows you to remove menu items from the list completely. Although this should rarely be necessary as you can just untick an item to not display it.
Reset to Defaults – Can be used if you want to discard all your changes and return to the plugin default menu. You will be prompted to confirm this action before proceeding, as this will remove any custom menu items or other changes you have made to ordering, names etc. Should you change your mind after the change you can cancel all changes made in the configuration dialog when you exit.
Keyboard Shortcuts... – Launches the Calibre shortcuts dialog showing all of the available active menu items that you could apply a keyboard shortcut to along with their current settings.

In addition there is a context menu available within the grid, offering these options:

Add image – Alternative way to add new images to the Calibre images repository for use by the plugin. Functionally equivalent to that in the dropdown image combo, except that if you add an image it will not change the image name selected in the dropdown values.
Open images folder – Allows direct access to the Calibre configuration folder for your custom images. If the folder does not yet exist you are prompted if you would like to create it.
Import... – Allows importing of menu items from a .owip file, created using the Export menu item described below. Can be used to import menu items created by other users, or your own if you use Export to back them up. All menu items imported will be inserted below the currently selected row, along with any images they require.
Export... – Allows you to export the selected menu item(s) to a .owip file, which is actually a .zip file with a renamed extension. All data for those selected menu items entered will be stored in the .owip file along with any custom images you may have added. This feature could be used to share menu items with other users, or as an alternative way to backup your menu settings.

Custom Image Folder Location

As of Calibre 0.7.34 it became no longer necessary to copy the image files within the plugin zip to a separate resources folder, as was the case with earlier versions of plugins. Instead the images are actually read by Calibre each time it starts up from its installed copy of the plugin zip file.

If however you wish to customise the menus with your own images, these should be placed in a \resources\images folder within the Calibre configuration folder as described in the Calibre help. You can find this directory by using:

Preferences -> Miscellaneous -> Open calibre configuration directory

Alternatively you can use the Open images folder context menu option available in the menu items grid on the configuration dialog for this plugin.

It is quite probable you do not already have the required resource subfolder. If that is the case create the \resources\images subdirectories yourself.

Adding Custom Menu Images

You have three choices for how you add custom .png images for your menu items. Of course you can manually source them and drop them into the images folder completely outside of Calibre.

However the easiest way is to expand the Image column dropdown on the configuration dialog for the plugin and select the Add New Image... menu option. This will show a configuration dialog allowing you to source the image:

From web domain favicon - Use this option to download the image file that you see in your browser location bar/bookmarks when you navigate to a website. You might like to use this option if you want to use the company’s website icon rather than that of the executable itself. It uses a google service (http://www.google.com/s2/favicons?domain=xxx) which returns the image as a png file for you to save. You just need to type the top level domain name such as www.google.com or www.amazon.com along with the name to save it as.
From .png file - Allows you to copy a .png file from your local drives to the correct Calibre location for you. You could either capture the icon using a screenshot and editing within a graphics program, or extract the icon using specialised software (such as Axialis IconWorkshop) to export it as a .png file.

Backing Up Your Settings

Menu items are persisted into a “open_with.json” file located within the calibre configuration directory for plugins (see above). So if you backup your Calibre configuration directory these settings will be included. Along with all your other Calibre preferences.

You may also chose to use the Export... right click feature to save your settings in a .owip file that can be re-imported at any time.

Known Issues

Calibre decides on startup whether to scan the resources\images folder for custom images only if that folder exists at that time. The very first time you add a custom image using this plugin it will create this directory for you if it does not exist. However in that one scenario you will need to restart Calibre before any custom images you add will be displayed within Calibre. If the directory already exists when Calibre starts, then any new images you add will be displayed immediately. This limitation is by design for performance reasons.
Retrieving the favicon for a website using Google’s service (as done underneath the covers by this plugin) will lose any transparency for the image. If the icon is a 16x16 coloured square this is unimportant, however icons that are “shaped” with a transparent background will instead have a white background. If this is important to you either edit the downloaded .png manually to erase the background or download it by looking at the web page source code.
Command line arguments for OSX users are ignored. I don’t have an OSX system to test them out and the way of launching applications differs from other operating systems. If an OSX developer out there is willing to supply the necessary code changes I will be happy to add support for them.

Further Help

For any problems, issues or obtaining the latest version of this plugin, please refer to the MobileRead Open With Plugin Thread.