Name:	Contextual Menu
Version:	1.5
Last update:	2019-02-18 17:51:25

The Contextual Menu package provides support for the contextual menu (CM), invoked in the Mac OS by pressing Control (⌃) and the mouse button simultaneously (or the mouse's right button if there is one). The contextual menu appears at the position of the mouse click and its contents depend on what surrounds this location.
Within the contextual menu, there is an item Customize which displays a dialog that lets you add or remove some commands or some submenus (aka modules) from the menu. In other words you can configure the menu. Note that this dialog, like the contextual menu itself, is mode specific, and you can change the modules associated with the mode of the current window as well as global settings.
Click here to display the Contextual Menu Preferences panel.

Description of the main modules

Here is a description of the main modules found in the contextual menu. This list is far from exhaustive because AlphaTcl package may define their own modules which will be available only if the package has been activated.

Alpha Help

In addition to these default contextual menu items, modes might have additional contextual menu modules which only appear for that mode, such as a Process submenu in TeX mode, or an Html Attributes submenu which will list all possible options for the tag surrounding the contextual menu click position. These additional modules can be turned on and off by selecting the contextual menu's Customize command.
Some packages in AlphaTcl offer additional plug-ins to add submenus which might already appear in some of Alpha's global menus, such as one containing a list of all recent files (package Recent Files Menu), or note files that you have created and saved (package Notes), etc. The best way to find out what these items do is to simply activate them and see what is now available in the contextual menu -- items can always be turned off, with the changes taking effect immediately.

Information for developers

This section contains more information for developers on how to create contextual menu plug-ins.

Description

The Contextual Menu package is designed to make it much easier for modes or other packages in AlphaTcl to create/add/remove items from the contextual menu. This menu is completely modular -- the user can add or remove items from the contextual menu with changes taking effect immediately. Modes, global packages, and mode specific packages can all create new modules to add to the contextual menu Preferences dialog.
The context here might be specifics about the current window, the current mode, or the position and/or selection surrounding the contextual menu click point. The items added via this package might be global or mode specific, but will be added no matter what is going on in the window regarding selected text and/or click position. Items within particular submenus added to the main contextual menu, however, can certainly change depending whether the click position is in a selected region (query the proc [contextualMenu::isSelection)], or if it surrounds a particular word (query the proc [contextualMenu::clickWord)] or based upon other context parameters.
Non-contextual modules can also be added to the contextual menu, generally global submenus that might already be inserted into one of the menu bar menus that users might find useful as a contextual menu shortcut. If these perform text editing tasks within the current window, however, they must take the contextual menu click position (again, available via the list of values in alpha::CMArgs), and NOT on the current position.
The contextual menu is listed in four sections, each separated by a divider. The first contains window specific modules defined by this package, such as the current path (similar to the title bar pop-up), and the current marks. The second is for mode-specific modules. The third includes global contextual menu modules defined by other packages in AlphaTcl. The final section includes more window specific modules defined in this package that probably won't be accessed very often, such as mode, format, and wrap. The contextual menu Customize item is always inserted at the end of the menu.
The following sections explain how to add modules to the second and third sections, how to dim contextual menu menus/items, and other miscellaneous information.

Adding Global Submenus

Any package can add a submenu in the third section of the contextual menu by simply defining a new contextualMenu package preference, as in:

contextualMenu::declare submenu  PROC 0

and then declaring a menu build proc using the proc [menu::buildProc] for a menu whose name does not end in Menu. The package Notes, for example, can add this:

contextualMenu::declare submenu "notes" PROC 0

This preference will then appear in the Contextual Menu preferences page, allowing the user to add it if desired. During the actual construction of the contextual menu, the Menu string will be stripped from the name of the submenu which will be added, in this example appearing as Notes. In this case, the package Notes has already defined a menu with this stripped name, so nothing more needs to be done here.
Packages that already create submenus for Alpha's global menu bar will find that adding a contextual menu submenu involves just this one line of extra code, so long as a menu build proc is registered.
Only defined submenus can be added this way, not menus created for the menu bar with alpha::menu or addMenu.
These preferences should be declared in a package's initialization script so that they're available the first time the contextual menu is created. Because the number of potential modules is virtually unlimited, it is considered bad practice to set the initial value of these preferences to 1, simply let the user know in a help file that the module is available, and allow him/her to choose to activate it.
If your package has not been activated the first time that the contextual menu is built (which will always be well past initialization, btw), the user's module pref for your package will be ignored. If your package is not likely to be globally activated but is intended for a specific mode, simply declare the preference for each mode which might make use of it as described below.

Adding Global Items

It is also possible to add an item that appears in the third section of the main contextual menu, although this is not recommended -- given that there will be a lot of possibilities for adding contextual menu items/submenus, the contextual menu could get very busy very quickly which kind of defeats the purpose of the whole exercise.
Given that ... simply define a preference without Menu at the end of its name. If the name ends with Item that will be stripped from the item's name before being inserted into the contextual menu. (The rationale here is that it will be much easier for a user to know what they're adding or removing in the prefs dialog if each name ends with Menu or Item, although we don't place that as a hard restriction for items.)
However, you're not done yet. These items will not be routed through a submenu's menu proc, as they are with the submenus described above, but rather through contextualMenu::contextualProc. In order for the item's procedure to be properly called, you must define a proc with either the name

::

contextualMenu::

where <menuItemName> is the item name without the Item suffix. No arguments are passed -- the proc must get the contextual menu click position via the alpha::CMArgs variable or the [contextualMenu::getPositions] proc.
An alternative is to register a contextualMenuHandler hook -- this is passed through the proc [contextualMenu::contextualProc], along with some arguments as indicated. Note that once this hook is registered, it is called even if the contextual menu preference has been turned off. For this reason it is best to check to see if the item is still active before making any calls to the command enableMenuItem .

Adding Mode Specific CM Menus and Items

Mode specific CM modules appear in the second section of the contextual menu, and can be turned on and off by the user in a separate page presented in the Contextual Menu Items dialog. These can be defined both by a mode or by a package that might be activated by the mode.
This is done just as in (1) and (2), except that the preference should be declared for contextualMenu<mode>, as in:

contextualMenu::declare (submenu|item) someCMThing PROC 0 mode

which in practice will look something like:

contextualMenu::declare submenu "tclUtils" PROC 0 Tcl

These menus must also have a build proc declared, as in:

menu::buildProc "tclUtils" Tcl::buildCMUtils

Dimming CM modules

Any submenu can dim or mark items within it via a menu post build proc in the normal manner -- see the examples below. To dim menus or items within the main contextual menu, register a contextualPostBuildHook instead, as in

hook::register contextualPostBuildHook {somePackage::postBuildCM}

This will be called each time after the contextual menu is built. If the module is mode specific, add a <mode> argument at the end, as in

hook::register contextualPostBuildHook {Tcl::dimCM} "Tcl"

so that the hook is only called when in Tcl mode, for example.

Contextual menu tooltip help tags

As with all preferences defined with [newPref], any comments which immediately precede this command will be indexed as prefs help. This will be available to the user either as tooltip tags (if available) or via the Modules Help button that appears in the dialog. Do _not_ use this sort of description:

# Turn this item on to include a 'Recent Dirs' submenu in the
# contextual pop-up menu|| Turn this item off to remove the 'Open
# Recent Dir' submenu from the contextual pop-up menu
contextualMenu::declare submenu recentDirs PROC 0

These descriptive strings should assume that the user is looking at the dialog, and already knows that checking a flag next to a contextual menu module's name will insert something new into the contextual menu.
These tooltip tags will be much more useful if they let the user know what sorts of items will be included, and what happens when these items are selected, as in

# Includes the folder names of the most recently opened files.
# Selecting a folder name will trigger an 'Open File' dialog using
# that folder as the default location.
contextualMenu::declare submenu "recentFolders" PROC 0

Don't bother with the "||" construction that used to display different help tags depending on the status of the checkbox; it is now obsolete.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2001-2019, Jonathan Guyer.
All rights reserved.
The Contextual Menu package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Jonathan Guyer nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JONATHAN GUYER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This document has been placed in the public domain.