// This file (IWarFoundryFactory.cs) is a part of the IBBoard.WarFoundry.API project and is copyright 2007, 2008, 2009 IBBoard.
//
// The file and the library/program it is in are licensed and distributed, without warranty, under the GNU Affero GPL license, either version 3 of the License or (at your option) any later version. Please see COPYING for more information and the full license.

using System;
using System.IO;
using System.Collections.Generic;
using IBBoard.WarFoundry.API.Objects;
using IBBoard.WarFoundry.API.Loading;

namespace IBBoard.WarFoundry.API.Factories
{
	public interface IWarFoundryFactory
	{		
		event SingleArgMethodInvoker<GameSystem> GameSystemLoaded;
		
		event SingleArgMethodInvoker<Race> RaceLoaded;
		
		event SingleArgMethodInvoker<Army> ArmyLoaded;
		
		/// <summary>
		/// Completes the loading of an object if it is loaded in stages.
		/// </summary>
		/// <param name="obj">
		/// The <see cref="IWarFoundryStagedLoadObject"/> that should be fully loaded.
		/// </param>
		void CompleteLoading(IWarFoundryStagedLoadObject obj);
		
		/// <summary>
		/// Checks if the factory thinks it can handle the supplied file. Checks can be performed on file extension or some basic check of file content, or some other method.
		/// </summary>
		/// <param name="file">
		/// A <see cref="ILoadableObject"/> for the file to check support for.
		/// </param>
		/// <returns>
		/// <code>true</code> if the file appears to be supported for loading by this factory, else returns <code>false</code>
		/// </returns>
		bool CanHandleFileFormat(ILoadableObject file);

		/// <summary>
		/// Checks if the factory thinks it can handle the supplied file as a Race. Checks can be performed on file extension or some basic check of file content, or some other method.
		/// </summary>
		/// <param name="file">
		/// A <see cref="ILoadableObject"/> for the file to check support for as a file containing Race information.
		/// </param>
		/// <returns>
		/// <code>true</code> if the file appears to be supported for loading by this factory as a Race, else returns <code>false</code>
		/// </returns>
		bool CanHandleFileAsRace(ILoadableObject file);

		/// <summary>
		/// Checks if the factory thinks it can handle the supplied file as a GameSystem. Checks can be performed on file extension or some basic check of file content, or some other method.
		/// </summary>
		/// <param name="file">
		/// A <see cref="ILoadableObject"/> for the file to check support for as a file containing GameSystem information.
		/// </param>
		/// <returns>
		/// <code>true</code> if the file appears to be supported for loading by this factory as a GameSystem, else returns <code>false</code>
		/// </returns>
		bool CanHandleFileAsGameSystem(ILoadableObject file);

		/// <summary>
		/// Checks if the factory thinks it can handle the supplied file as a Army. Checks can be performed on file extension or some basic check of file content, or some other method.
		/// </summary>
		/// <param name="file">
		/// A <see cref="ILoadableObject"/> for the file to check support for as a file containing Army information.
		/// </param>
		/// <returns>
		/// <code>true</code> if the file appears to be supported for loading by this factory as a Army, else returns <code>false</code>
		/// </returns>
		bool CanHandleFileAsArmy(ILoadableObject file);
		
		/// <summary>
		/// Reads the data from the supplied file and returns it as a collection of loadable objects. In addition, it fires the appropriate XxxLoaded event
		/// for each object loaded for asynchronous use.
		/// 
		/// May throw a <see cref=" IBBoard.IO.InvalidFileException"/> if the file is supported by the Factory but the content is invalid.
		/// </summary>
		/// <param name="file">
		/// A <see cref="ILoadableObject"/> for the file to load data from
		/// </param>
		/// <returns>
		/// A <see cref="ICollection`1"/> of <see cref="IWarFoundryObject"/>s that were loaded from the file
		/// </returns>
		ICollection<IWarFoundryObject> CreateObjectsFromFile(ILoadableObject file);
	}
}