Description Simon Arsenault 2001-10-10 22:45:13 EDT

This is from the eclipse newsgroup. The documentation should be
	reviewed and updated to provide more details. I've included my comments
	sent to this poster which could be used as areas that need improvement.

	From: Roxie Rochat <rrochat@foresight-systems.com>
	Newsgroups: eclipse.tools
	Subject: constructing path names from Interfaces
	Date: Tue, 18 Sep 2001 17:25:08 -0500

	"Roxie Rochat" <rrochat@foresight-systems.com> wrote in message
	news:3BA7C9C4.6779BCCD@foresight-systems.com...
	> org.eclipse.platform.doc.isv.pdf
	> says the following is a description of the help menu
	> adapted from IWorkbenchActionConstants
	> Standard Help menu actions
	> Start group HELP_START "start"
	> End group HELP_END "end"
	> About action ABOUT "About"
	>
	> I don't understand the context for this example, but
	> I think the formatting may have gotten messed up??

	It is just listing the value of the three constants related to the help
	menu.
	    IWorkbenchActionConstants.HELP_START
	    IWorkbenchActionConstants.HELP_END
	    IWorkbenchActionConstants.ABOUT

	>
	> Later, it says
	> "In general, it's not good practice to contribute to
	> another plug-in's menu or tool bar by deriving the
	> path name from the plugin.xml. It's possible that a
	> future version of the plug-in could change the names
	> of the paths. The recommended practice is to define
	> a public interface (much like IWorkbenchActionConstants)
	> which specifies exactly which menus, tool bar groups,
	> and slots are considered fair game for use by
	> other plug-ins."
	>
	> All the examples seem to use path names like
	>  path="window/additions"
	> yet this paragraph implies that we should
	> be using the statics defined in the interface.
	> But there's also something about "piecing together a path"...
	>
	> It seems rather convoluted.  What am I missing?

	It is recommended that a plug-in developer create a public interface.
	This interface would contain all the menu/tool paths that other plug-in
	developers can use to extend. The interface role is to define the
	"contract". That is, the plug-in developer is agreeing that these paths
	will always be available and supported. Those not listed in the
	interface should be considered off limits and subject to change in the
	future.

	As a developer wanting to extend another plug-in's menu, you can't use
	the interface constants in your plugin.xml file directly. That's why you
	need to "piece together a path" from the constants in the interface. For
	example, the path="window/additions" would come from piecing together
	IWorkbenchActionConstants.M_WINDOW and
	IWorkbenchActionConstants.MB_ADDITIONS

	Does this make more sense now?

	Simon :-)

NOTES: