Description Dirk Baeumer 2001-10-10 22:21:29 EDT

The new marker implementation allows defining of new marker types. To be able to render those markers in the
	UI we also need a generic way to define / find an icon for a marker.


NOTES:
EG (3/5/01 2:45:53 PM)
	The debugger has started to define a custom mechanism. This is bad, there should be a standard mechanism
	provided by the platform.

EG (4/4/01 11:26:28 AM)
	This is the proposal discussed with KH:


Problem:
*  an Editor should be able to render a marker in the annotation bar without having to know about
 a specific marker type. For example, the standard text editor should be able to render
 search match markers, without having to know about the search plugin.
* the rendering of a marker should not result in loading the owner's plugin prematuerly
* the rendering of a marker can depend on some other state, e.g., a break point can be
 enabled or disabled and this should be reflected in the image


Assumption:
* the rendering of a marker cannot change when the plugin isn't activated, e.g. to change
 the enabled state of a breakpoint the debugger plugin has to be activated.
* most markers have a fixed image


Proposal:
a) add an attribute (URL?) to a marker type that describes the location of a marker's default image.
 this attribute has to describe the location so that the Editor can get the image without
 having to know about the owner plugin.
b) for dynamically changing markers each marker carries an attribute that refers
 to the markers current image. 
Here is how the editor would use it:
* if the marker is of the type TextMarker check whether the marker has an image attribute.
 if it has use it for rendering.
* if the marker has no current image attribute use the default image attribute registered
 for the marker type.
Clients with static marker images
* register an image with the marker type in the xml markup
Clients with dynamic marker image
* register a default image for the marker type in the xml markup
* whenever the dynamic image changes update the current image attribute of the
 marker.
The idea is that when the workbench is saved the markers are persisted.
When the workbench is loaded again and an editor is opened, the editor can use the
current marker image without having to activate the owner plugin. 


KH (4/10/2001 11:04:49 AM)
	Moving to Core for comment

JM (4/11/2001 4:22:23 PM)
	Discussed issues with EG.  EG will come back with a new proposal.
	Moving to Canadidates pending more information.

EG (4/18/01 1:18:11 PM)
	The proposal below is at the UI level only.
	*	workbench defines an extension point for registering images
		for marker types.

	*	For simple/static marker images the URL to the
		images is defined in the extension point. 
		Search would use this to define its static search marker icon.
		<extension
    		point = "com.ibm.eclipse.ui.markerImageProvider">
    			<imageprovider id ="..."
      				markertype="com.ibm.eclipse.search.searchmarker"
					iconURL="..."     
    			</imageprovider>
		</extension>

	*	For dynamic marker images the name of a class
		implementing IMarkerImageProvider can be defined.
		<extension
    		point = "com.ibm.eclipse.ui.markerImageProvider">
    			<imageprovider id ="..."
      				markertype="com.ibm.dtcore.linebreakpoint"
					class="com.ibm.dtcore.BreakPointMarkerImageProvider"     
    			</imageprovider>
		</extension>

		IMarkerImageProvider has a single method:
			ImageDescriptor getImageDescriptor(IMarker)
		Debugger would use this to define its dynamic icons.
		
	*	The desktop provides an IMarkerImageRegistry that
		can be queried for an image descriptor for a marker.
			ImageDescriptor getMarkerImageDescriptor(IMarker)
		GetMarkerImage will either return the declared image or
		forward the call to a MarkerImageProvider that is registers
		for the passed in marker type.

	Issue:
	-	when using dynamic marker images then code needs to be
	 	executed from a plugin and this can result in a plugin activation.
		No plugin activation will happen for static images.

	Moving to ITPUI

NE (4/19/01 2:00:55 PM)
	Rather than defining an IMarkerImageRegistry, we could use adapters since IMarker extends IAdaptable.
	The workbench could register an IWorkbenchAdapter which provides getImageDescriptor.
	The implementation would look in an internal registry.  
	Pros: 
		- does not requiring any API changes
		- consistent with current IWorkbenchAdapters on resources
	Cons:
		- may be slower.

	The fact that using dynamic IMarkerImageProviders can lead to plugin activation seems to be a non-starter.

	To avoid having to instantiate an IMarkerImageProvider for a plugin which has not yet started,
	the registry could cache the URL for the last obtained image as an attribute on the marker.
	This would get saved with the workspace.
	If the cache was not set, the registry would use the static URL if the plugin has not yet been activated.

	Caching the URL would require IMarkerImageProvider to return a URL, not an arbitrary ImageDescriptor (can't use file names
	since resources may be non-local).
	Or, we could require that it answer a FileImageDescriptor (class name + relative file name, so it's OK if non-local)
	or a URLImageDescriptor, and the registry caches the information needed to recreate the descriptor.  
	This would require API changes to FileImageDescriptor and URLImageDescriptor.
	Unfortunately, this would also prevent the IMarkerImageProvider from doing its own image composition.

	Whenever any attribute on the marker changed, it would clear the cache.  Presumably the plugin has to be
	active in order to change attributes, although the task list can change message and priority on tasks.
	We could assume that tasks are non-dynamic.
	The registry would also have to be notified of any workspace changes which occurred between Workbench shutdown and startup
	(core has support for this).

	Another issue is that, if changing a marker can cause its icon to change, then all content providers for viewers showing markers
	will have to register for workspace notification, and update any markers which have changed.
	They should already be doing so, but it means they can't be "smart" - the content providers can't know which attribute changes 
	would result in an image update.  They would always have to update in response to any marker change.

EG (4/20/01 6:24:55 PM)
	Re: use of an Adapter
	using an Adapter would be the better solution.

	>The fact that using dynamic IMarkerImageProviders can lead to plugin activation seems to be a non-starter.
	in the editor case the plugin will only be activated when the editor shows
	a marker. If an editor shows a marker and is saved then it has to
	activate the marker updater, since only the marker updater knows how to handle a changed
	marker.
 	
	Re: plugin activation is a non-starter
	you are trading caching space and logic against activating a plugin.
	Given that the MarkerImageProvider only implements decision logic to
	map marker attributes to an image it will only drag in a few classes.
	Actually, the code for mapping attributes to icons could be easily put into a very
	small helper plugin. Instead of activating the full plugin only the small helper
	plugin would get activated. It would be acceptable to me to put more burden
	on clients that require dynamic marker images. Couldn't we come up with
	a solution along these lines?

	>Unfortunately, this would also prevent the IMarkerImageProvider from doing its own image composition.
	I don't think that any of the current markers are doing image composition.

	>Another issue is that, if changing a marker can cause its icon to change
	as you say clients should already do this an listen to marker deltas. 
	I don't think you have to give up all the smartness, a viewer typically is constrained
	to show as set of known-markers (e.g. Bookmarks view->bookmarks, Search Results view->search results)

EJP (4/27/01 11:59:14 AM)
	The solucion discribed above was implemented:
		- Create interface IMarkerImageProvider  (in the internal package for now).
		- Added the extension point:
				extension-point name="Marker Image Provider" id="markerImageProviders
		 with the tags id, markertype, icon or class.
		- If the tag class (an implementation of IMarkerImageProvider) is specified it will
		 always call the provider otherwise the icon must be specify the relative path name
   		to the image.
		- Changed the class WorkbenchMarker so that the method getImageDescriptor calls
		the provider.
		- Added the provider for problem markers org.eclipse.ui.internal.ProblemImageProvider
		- Added the extension to return the image for marker type taskmarker. 
  
EJP (5/15/01 4:38:43 PM)
	See: 1G3UM6S: ITPUI:ALL - MarkerExtender should define an icon for T_SEARCH