/**
 * @file  XTPChartDeviceCommand.h
 *
 * @copyright
 * (c) 1998-2025 Codejock Software, All Rights Reserved.
 *
 * This source file is the property of Codejock Software and must not be
 * redistributed by any means without the explicit written permission of
 * Codejock Software.
 *
 * The use of this source code is governed by the terms and conditions specified
 * in the Toolkit Pro license agreement. Codejock Software grants you, as a
 * single software developer, the limited right to use this software on one
 * computer only.
 *
 * Contact Information:
 * support@codejock.com
 * http://www.codejock.com
 *
 */

/** @cond */
#if !defined(__XTPCHARTDEVICECOMMAND_H__)
#	define __XTPCHARTDEVICECOMMAND_H__
/** @endcond */

#	if _MSC_VER >= 1000
#		pragma once
#	endif // _MSC_VER >= 1000

#	include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"

class CXTPChartDeviceContext;
class CXTPChartFont;
class CXTPChartElement;
class CXTPChartSeriesStyle;
class CXTPChartElementView;

/**
 * @brief
 * Defines a callback interface for a chart device command event sink.
 *
 * @see
 * CXTPChartDeviceCommand
 */
class _XTP_EXT_CLASS CXTPChartDeviceCommandEvents
	: public CXTPTypeIdProvider<CXTPChartDeviceCommandEvents>
{
protected:
	/**
	 * @brief
	 * Constructs an event sink.
	 */
	CXTPChartDeviceCommandEvents();

public:
	/**
	 * @brief
	 * Notifies that a command has entered the BeforeExecute step.
	 *
	 * @param pCommand Sender command pointer.
	 * @param pDC Device context pointer for which a command is being executed.
	 */
	virtual void OnBeforeExecute(CXTPChartDeviceCommand* pCommand, CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Notifies that a command has entered the AfterExecute step.
	 *
	 * @param pCommand Sender command pointer.
	 * @param pDC Device context pointer for which a command has been executed.
	 */
	virtual void OnAfterExecute(CXTPChartDeviceCommand* pCommand, CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Notifies about updated boundaries for the command result.
	 *
	 * @param pCommand Sender command pointer.
	 * @param rcBounds Updated boundary rectangle.
	 */
	virtual void OnUpdateBounds(CXTPChartDeviceCommand* pCommand, CRect rcBounds);

	/**
	 * @brief
	 * Invoked when an event sink is to be unsubscribed from command events.
	 *
	 * @param pCommand Sender command pointer.
	 */
	void OnUnsubscribe(CXTPChartDeviceCommand* pCommand);
};

/**
 * @brief
 * Defines a common implementation interface for chart drawing commands.
 */
class _XTP_EXT_CLASS CXTPChartDeviceCommand
	: public CXTPChartObject
	, public CXTPObservable<CXTPChartDeviceCommand, CXTPChartDeviceCommandEvents>
{
	DECLARE_DYNAMIC(CXTPChartDeviceCommand);

public:
	/**
	 * @brief
	 * Constructs a CXTPChartDeviceCommand object.
	 */
	CXTPChartDeviceCommand();

	/**
	 * @brief
	 * Destroys a CXTPChartDeviceCommand object, handles cleanup.
	 */
	virtual ~CXTPChartDeviceCommand();

public:
	/**
	 * @brief
	 * Determines if the execution of the command has been committed.
	 *
	 * @return TRUE if the execution of the command has been committed, FALSE otherwise.
	 *
	 * @see
	 * Commit
	 */
	BOOL IsCommitted() const;

	/**
	 * @brief
	 * Commits the execution of the command. A command cannot be modified
	 * after being committed.
	 *
	 * @see
	 * IsCommitted
	 */
	void Commit();

	/**
	 * @brief
	 * Obtains the number of immediate children commands.
	 *
	 * @return The number of immediate children commands.
	 *
	 * @see
	 * GetChildCommand
	 */
	int GetChildCommandCount() const;

	/**
	 * @brief
	 * Obtains immediate child command point by index.
	 *
	 * @param nIndex Child command index. Must not exceed value returned by
	 *				GetChildCommandCount call.
	 *
	 * @return Child command pointer or NULL if no child command is defined
	 *		  at the specified location.
	 *
	 * @see
	 * GetChildCommandCount
	 */
	CXTPChartDeviceCommand* GetChildCommand(int nIndex) const;

	/**
	 * @brief
	 * Call this function to add a child device command.
	 *
	 * @param pCommand A pointer to the child device command.
	 *
	 * @details
	 * A device command object keeps an array of child device commands.
	 * An instruction to execute the drawing of the parent object triggers the
	 * drawing of children as well.
	 * @return A newly added command object pointer.
	 */
	CXTPChartDeviceCommand* AddChildCommand(CXTPChartDeviceCommand* pCommand);

	/**
	 * @brief
	 * Call this function to execute the drawing.
	 *
	 * @param pDC A pointer to the chart device context.
	 *
	 * @details
	 * An instruction to execute the drawing of the parent object triggers the
	 * drawing of children as well.
	 */
	virtual void Execute(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * This method gets called before a command is executed which allows for
	 * the customization of command behavior.
	 *
	 * @param pDC A pointer to the chart device context.
	 */
	virtual void BeforeExecute(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * This method gets called after a command is executed which allows for
	 * the customization of command behavior.
	 *
	 * @param pDC A pointer to the chart device context.
	 */
	virtual void AfterExecute(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Override this function to write the drawing code for specific objects.
	 *
	 * @param pDC A pointer to the chart device context.
	 */
	virtual void ExecuteOverride(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Get the number of executions made by the command.
	 *
	 * @return The number of executions made by the command.
	 */
	UINT GetPassNumber() const;

	/**
	 * @brief
	 * Performs recursive hit testing of the element at the specified point.
	 *
	 * @param point Point in which an element is to be found.
	 * @param pParent Parent element pointer.
	 *
	 * @return A pointer to the element found at the specified point or NULL
	 *		  if no element is found.
	 */
	virtual CXTPChartElement* HitTest(CPoint point, CXTPChartElement* pParent) const;

	/**
	 * @brief
	 * Applies series style to the current element.
	 *
	 * @param pStyle Series style to apply.
	 */
	virtual void ApplySeriesStyle(CXTPChartSeriesStyle* pStyle);

	/**
	 * @brief
	 * Performs inital preparation steps necessary for successful command execution.
	 *
	 * @param pDC Device context pointer for which the command is to be prepared.
	 *
	 * @see
	 * PrepareOverride
	 */
	virtual void Prepare(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Derived implementation must override this method for implementing
	 * implementation specific preparation behavior.
	 *
	 * @param pDC Device context pointer for which the command is to be prepared.
	 *
	 * @see
	 * Prepare
	 */
	virtual void PrepareOverride(CXTPChartDeviceContext* pDC);

	/**
	 * @brief
	 * Determines if the command is currently enabled.
	 *
	 * @return TRUE if the command is currently enabled, FALSE otherwise.
	 *
	 * @see
	 * SetEnabled
	 */
	virtual BOOL IsEnabled() const;

	/**
	 * @brief
	 * Enables/disable the command.
	 *
	 * @param bEnabled TRUE to enable the command, FALSE to disable the command.
	 */
	void SetEnabled(BOOL bEnabled = TRUE);

	/**
	 * @brief
	 * Obtains device context pointer for which the command is currenly
	 * being prepared or executed.
	 *
	 * @return Device context pointer for which the command is currently
	 *		  being prepared or executed or NULL if no preparation or execution
	 *		  is in progress.
	 */
	CXTPChartDeviceContext* GetCurrentDC() const;

	/**
	 * @brief
	 * Binds a view to the command object. The view reference is held
	 * until another view is bound.
	 *
	 * @param pView A view pointer. If another view is bound its reference
	 *			   is released. NULL unbinds the current view.
	 */
	void BindView(CXTPChartElementView* pView);

	/**
	 * @brief
	 * Obtains a bound view pointer or NULL if no view is bound.
	 *
	 * @return A bound view pointer or NULL if no view is bound.
	 */
	CXTPChartElementView* GetBoundView() const;

protected: /**< The array of child device commands.*/
	CArray<CXTPChartDeviceCommand*, CXTPChartDeviceCommand*> m_arrChildren;

private:
	BOOL m_bCommitted;
	UINT m_nPassNumber;
	BOOL m_bEnabled;
	CXTPChartDeviceContext* m_pCurrentDC;
	CXTPChartElementView* m_pBoundView;
};

AFX_INLINE BOOL CXTPChartDeviceCommand::IsCommitted() const
{
	return m_bCommitted;
}
AFX_INLINE void CXTPChartDeviceCommand::Commit()
{
	_ASSERTE("Must not be committed twice" && !m_bCommitted);
	m_bCommitted = TRUE;
}

AFX_INLINE UINT CXTPChartDeviceCommand::GetPassNumber() const
{
	return m_nPassNumber;
}

AFX_INLINE void CXTPChartDeviceCommand::SetEnabled(BOOL bEnabled /*= TRUE*/)
{
	m_bEnabled = bEnabled;
}

AFX_INLINE CXTPChartDeviceContext* CXTPChartDeviceCommand::GetCurrentDC() const
{
	return m_pCurrentDC;
}

AFX_INLINE CXTPChartElementView* CXTPChartDeviceCommand::GetBoundView() const
{
	return m_pBoundView;
}

enum XTPChart3dAntialiasingPolicy
{
	xtpChart3dAntialiasingPolicyDefault,
	xtpChart3dAntialiasingPolicyEnabled,
	xtpChart3dAntialiasingPolicyDisabled,
};

/**
 * @brief
 * Defines a common implementation interface for chart 3D drawing commands.
 */
class _XTP_EXT_CLASS CXTPChart3dDeviceCommand : public CXTPChartDeviceCommand
{
	DECLARE_DYNAMIC(CXTPChart3dDeviceCommand);

protected:
	/**
	 * @brief
	 * Constructs a CXTPChart3dDeviceCommand object.
	 * @param nAntialiasingPolicy One of the antialiasing policies defined by the
	 * XTPChart3dAntialiasingPolicy enumeration.
	 */
	CXTPChart3dDeviceCommand(XTPChart3dAntialiasingPolicy nAntialiasingPolicy);

public:
	/**
	 * @brief
	 * Determines if the command is currently enabled.
	 *
	 * @return
	 * TRUE if the command is currently enabled, FALSE otherwise.
	 *
	 * @details
	 * 3D commands consider anti-aliasing policy and current device context
	 * rendering state in order to determine current enabled status.
	 * If device context is skipping anti-aliasing phase when calling
	 * this method then the policy is disregarded and the command is
	 * considered enabled unles it's been explicitly disabled by the user.
	 * If device context is in anti-alising od refault rendering state when
	 * this method is called the policy determines the command state
	 * unless it's been explicitly disabled by the user.
	 *
	 * @see
	 * SetEnabled,
	 * XTPChart3dAntialiasingPolicy
	 */
	virtual BOOL IsEnabled() const;

private:
	XTPChart3dAntialiasingPolicy m_nAntialiasingPolicy;
};

/**
 * @brief
 * Defines a base class interface for a 2D hit test command.
 */
class _XTP_EXT_CLASS CXTPChartHitTestElementCommand : public CXTPChartDeviceCommand
{
public:
	/**
	 * @brief
	 * Constructs a CXTPChartHitTestElementCommand object instance.
	 *
	 * @param pElement Chart element pointer for which hit testing is to be performed
	 *				  including all its children elements recursively.
	 */
	CXTPChartHitTestElementCommand(CXTPChartElement* pElement);

	/**
	 * @brief
	 * Constructs a CXTPChartHitTestElementCommand object instance.
	 *
	 * @param pElement Chart element pointer for which hit testing is to be performed
	 *				  including all its children elements recursively.
	 * @param rcBounds Hit test boundary rectangle.
	 */
	CXTPChartHitTestElementCommand(CXTPChartElement* pElement, const CRect& rcBounds);

	/**
	 * @brief
	 * Constructs a CXTPChartHitTestElementCommand object instance.
	 *
	 * @param pElement Chart element pointer for which hit testing is to be performed
	 *				  including all its children elements recursively.
	 * @param rcBounds Hit test boundary rectangle.
	 */
	CXTPChartHitTestElementCommand(CXTPChartElement* pElement, const CXTPChartRectF& rcBounds);

	/**
	 * @brief
	 * Performs recursive hit testing of the element at the specified point.
	 *
	 * @param point Point in which an element is to be found.
	 * @param pParent Parent element pointer.
	 *
	 * @return
	 * A pointer to the element found at the specified point or NULL
	 * if no element is found.
	 */
	virtual CXTPChartElement* HitTest(CPoint point, CXTPChartElement* pParent) const;

protected:
	CXTPChartElement* m_pElement; /**< Chart element pointer for which hit testing is to be
									 performed.*/
	CRect m_rcBounds;			  /**< Hit test boundary rectangle.*/
};
/** @cond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif //#if !defined(__XTPCHARTDEVICECOMMAND_H__)
/** @endcond */