Exterminate Wave

function ExterminateWave(w)
wave w
	variable retVal = 0
	if( WaveExists(w) )
		RemoveWaveFormAllWindows(w)
		CheckDisplayed /A w	// successfully removed (e.g. subwindows not treated yet) ?
		if( V_Flag )
			retVal = -1		// code for "in use in windows"
		endif
		try					// this may fail since do not treat user functions (yet)
			KillWaves w	// no /Z flag, since that does not generate a V_Flag return value
		catch				// but any user of this function really wants to know if it did not work
			retVal = -2		// code for "in use in functions"
		endtry
	endif
	return retVal
end

function RemoveWaveFormAllWindows(w)
wave w
	CheckDisplayed /A w
	if( V_Flag )
		RemoveWaveFromAllGraphs(w)
		RemoveWaveFromAllTables(w)
	endif
end

function RemoveWaveFromAllGraphs(w)
wave w
	string graphList = WindowsUsingWave(w, 1)
	variable k
	for( k = 0; k < ItemsInList(graphList); k += 1 )
		RemoveWaveFromGraph(StringFromList(k, graphList), w, -1)
	endfor
end

function RemoveWaveFromAllTables(w)
wave w
	string table, tableList = WindowsUsingWave(w, 2)
	variable numCols, oldCols, k
	for( k = 0; k < ItemsInList(tableList); k += 1 )
		table = StringFromList(k, tableList)
		numCols = NumberByKey("COLUMNS", TableInfo(table, -2))
		do
			oldCols = numCols
			RemoveFromTable /W=$table w		// RemoveFromTable is not picky about column specs...
			numCols = NumberByKey("COLUMNS", TableInfo(table, -2))
		while( oldCols > numCols )
		if( numCols == 0 )
			DoWindow /K $table
		endif
	endfor
end

function/S WindowsUsingWave(w, windowtype)
wave w
variable windowtype
	string win, wins = WinList("*", ";", "WIN:"+num2str(windowtype))	// should be modified to include subwindows
	string result = ""
	variable k
	for( k = 0; k < ItemsInList(wins); k += 1 )
		win = StringFromList(k, wins)
		CheckDisplayed /W=$win w	// this may not be the best way...
		if( V_Flag )
			result = AddListItem(win, result)
		endif
	endfor
	return result
end

function RemoveWaveFromGraph(graph, w, options)
string graph
wave w
variable options // bit-wise: 1=waves, 2=contours, 4=images; pass -1 for "all"

	string wavPath = GetWavesDataFolder(w, 2)	// full path of data folder, including possibly quoted wave name
	string allObjects = ""
	string instanceList, instance, objPath, xwavePath
	variable k
	
 	if( options & 1 )	// traces
		instanceList = TraceNameList(graph, ";", 1)	
		allObjects += instanceList
	 	for( k = ItemsInList(instanceList); k > 0 ; k -= 1 )		// need backward loop since ...
	 		instance = StringFromList(k-1, instanceList)
	 		objPath = GetWavesDataFolder(TraceNameToWaveRef(graph, instance), 2)
	 		wave xwave = XWaveRefFromTrace(graph, instance)
	 		if( WaveExists(xwave) )
		 		xwavePath = GetWavesDataFolder(xwave, 2)
		 	else
		 		xwavePath = ""
		 	endif
	 		if( !cmpstr(wavPath, objPath) || !cmpstr(wavPath, xwavePath) )
				RemoveFromGraph /W=$graph $instance	// ... this changes instance numbers
				allObjects = RemoveFromList(instance, allObjects)
			endif
		endfor
	endif
	
 	if( options & 2 )	// contours
		instanceList = ContourNameList(graph, ";")
		allObjects += instanceList
	 	for( k = ItemsInList(instanceList); k > 0 ; k -= 1 )		// need backward loop since ...
	 		instance = StringFromList(k-1, instanceList)
	 		objPath = GetWavesDataFolder(ContourNameToWaveRef(graph, instance), 2)
	 		if( !cmpstr(wavPath, objPath) )
		 		RemoveContour /W=$graph $instance		// ... this changes instance numbers
				allObjects = RemoveFromList(instance, allObjects)
			endif
		endfor
	endif
	
 	if( options & 4 )	// images
		instanceList = ImageNameList(graph, ";")
		allObjects += instanceList
	 	for( k = ItemsInList(instanceList); k > 0 ; k -= 1 )		// need backward loop since ...
	 		instance = StringFromList(k-1, instanceList)
	 		objPath = GetWavesDataFolder(ImageNameToWaveRef(graph, instance), 2)
	 		if( !cmpstr(wavPath, objPath) )
		 		RemoveImage /W=$graph $instance		// ... this changes instance numbers
				allObjects = RemoveFromList(instance, allObjects)
			endif
		endfor
	endif
	
	if( ItemsInList(allObjects) == 0 )
		DoWindow /K $graph
	endif
end