//
// (C) Copyright 2007-2008 by Autodesk, Inc.
//
// Permission to use, copy, modify, and distribute this software in
// object code form for any purpose and without fee is hereby granted, 
// provided that the above copyright notice appears in all copies and 
// that both that copyright notice and the limited warranty and
// restricted rights notice below appear in all supporting 
// documentation.
//
// AUTODESK PROVIDES THIS PROGRAM "AS IS" AND WITH ALL FAULTS. 
// AUTODESK SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF
// MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE.  AUTODESK, INC. 
// DOES NOT WARRANT THAT THE OPERATION OF THE PROGRAM WILL BE
// UNINTERRUPTED OR ERROR FREE.
//
// Use, duplication, or disclosure by the U.S. Government is subject to 
// restrictions set forth in FAR 52.227-19 (Commercial Computer
// Software - Restricted Rights) and DFAR 252.227-7013(c)(1)(ii)
// (Rights in Technical Data and Computer Software), as applicable.
//
// dbPropertyFilterCustomizationPEPE.H
//
// DESCRIPTION: Protocol extension base class
//                AcDbPropertyFilterCustomizationPE
//
#pragma once

#include "acdb.h"
#include "dynprops.h"

#pragma pack (push, 8)


/// <summary>
/// This protocol extension interface can be implemented and associated with
/// an AcRxClass to take some level of control over the way an entity type
/// participates in property filter customization in the CUI dialog.  If this
/// protocol extension is not associated with the AcRxClass of a particular
/// entity type, the entity type will be handled in a "default" manner.  The
/// "default" behavior is as follows.
/// The CUI property filter customization framework will make the entity type
/// available for property filter customization when it is registered in the
/// class dictionary by instantiating an instance of the entity via the
/// AcRxClass::create() method.  It will check if this entity is able to
/// function properly when it's not database resident by seeing if the entity
/// implements the IAcadBaseObject2 interface and checking that interface's
/// "ForceDbResident()" method.  If the interface is implemented and
/// "ForceDbResident()" indicates that the entity does not need to be database
/// resident, the entity will be used as is for determining its display name
/// and properties.  If the entity does not support non-database residency,
/// it will be added to model space of a temporary database before being used
/// to determine its display name and properties.
/// </summary>
///
class AcDbPropertyFilterCustomizationPE : public AcRxObject
{
public:

    ACRX_DECLARE_MEMBERS(AcDbPropertyFilterCustomizationPE);

    /// <summary>
    /// Gives an ARxClass a chance to opt out of the CUI
    /// property filter customization framework.
    /// </summary>
    ///
    /// <param name="context">
    /// An enum value that indicates what context the property filter will
    /// be used for.  The current contexts that exist are for the Quick
    /// Properties feature and the Rollover Tooltips feature.
    /// </param>
    ///
    /// <param name="pCls">
    /// A pointer to an AcRxClass that indicates the entity type which
    /// would be eligible for property filter customization in the CUI dialog.
    /// </param>
    ///
    /// <returns>
    /// A boolean value indicating whether this type should be blocked
    /// from property filter customization for the passed in context.
    /// Returning "true" would block participation.
    /// </returns>
    ///
    virtual bool vetoCustomization(AcFilterablePropertyContext context,
                                   AcRxClass* pCls) const = 0;

    /// <summary>
    /// Gives an ARxClass a chance to do its own creation of an entity
    /// instance that will be used for interrogation by the CUI
    /// property filter customization framework.  This may be necessary
    /// if the entity type requires special initialization steps in order to
    /// reliably provide its set of properties or display name.
    /// </summary>
    ///
    /// <param name="pDb">
    /// A pointer to a temporary database that can be used if the object type
    /// requires database-residency for property access.
    /// </param>
    ///
    /// <param name="pCls">
    /// A pointer to an AcRxClass that indicates the type for which an
    /// instance is needed.
    /// </param>
    ///
    /// <param name="ppEnt">
    /// A pointer to a pointer to an AcDbEntity.  This is an output parameter
    /// which should be used to pass an entity instance back if the
    /// implementation creates a non-database resident instance for
    /// interrogation by the CUI property filter customization framework.
    /// The framework will free this instance's memory when it's no longer
    /// needed.
    /// </param>
    ///
    /// <param name="objId">
    /// A reference to an AcDbObjectId.  This is an output parameter
    /// which should be used to pass an AcDbObjectId back if the
    /// implementation creates a database resident instance for
    /// interrogation by the CUI property filter customization framework.
    /// If a database resident instance is created, it should reside in
    /// the temporary database created by the framework to which
    /// the "pDb" input parameter refers.
    /// </param>
    ///
    /// <param name="sGUID">
    /// A const reference to an AcString. This is an input parameter
    /// which indicates the type of sub-entity that needs to be created.
    /// An empty sGUID indicates that there is no subtype.
    /// </param>
    ///
    /// <returns>
    /// Return true if implementation has successfully created an instance
    /// and has populated either the output "ppEnt" parameter or
    /// the "objId" parameter.  If false is returned, the framework
    /// will create an object instance via the "default" methodology described
    /// in the summary for this protocol extension interface.
    /// </returns>
    ///
    virtual bool createObject(AcDbDatabase* pDb,
                              AcRxClass* pCls,
                              AcDbEntity** ppEnt,
                              AcDbObjectId& objId,
                              const AcString& sGUID) const = 0;
};

#pragma pack (pop)

