##########################################################################
#
#  Copyright (c) 2010, Image Engine Design Inc. All rights reserved.
#
#  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 Image Engine Design nor the names of any
#       other contributors to this software 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 THE COPYRIGHT OWNER OR
#  CONTRIBUTORS 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.
#
##########################################################################
import IECore


## The Preset class serves as a base class for the implementation of
## 'presets'. In a nutshell, they are callable classes that manipulate
## the parameters of a Parameterised object. \see BasicPreset for an
## implementation that provides parameter value loading an saving, with
## support for Class and ClassVector parameters.
##
## Presets themselves are Parametersied objects, to allow them to have
## their own parameters to control how they might be applied.
class Preset( IECore.Parameterised ) :

	def __init__( self, description="" ) :

		IECore.Parameterised.__init__( self, description )

	## \return Presets may return a dictionary of arbitrary metadata
	## to describe their contents/function. The default implementation
	## simply sets "title" to the class name.
	def metadata( self ) :

		return { "title" : self.__class__ }

 	## \return True if the Preset can be applied to the given rootParameter
	## on the given parameterised object, otherwise False
	def applicableTo( self, parameterised, rootParameter ) :

		raise NotImplementedError

	## Applies the preset to the specified parameterised and
	## root parameter.
	def __call__( self, parameterised, rootParameter ) :

		raise NotImplementedError

IECore.registerRunTimeTyped( Preset )

