/**
 * @file XTPGaugeBaseType.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
 *
 */

#if !defined(__XTPGAUGEBASE_H__)
#	define __XTPGAUGEBASE_H__

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

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

class CXTPGaugeCtrl;
class CXTPGaugeTraits;

/**
 * @brief
 * A base class for all gauge types. Implements common gauge type specific actions.
 *
 * @see CXTPGaugeCtrl
 * @see CXTPGaugeTraits
 */
class _XTP_EXT_CLASS CXTPGaugeBaseType
	: public CXTPCmdTarget
	, private IXTPMarkupClientSite
{
	DECLARE_DYNAMIC(CXTPGaugeBaseType);

	friend class CXTPGaugeCtrl;

protected:
	/**
	 * @brief
	 * Handles gauge type object construction.
	 */
	CXTPGaugeBaseType();

public:
	/**
	 * @brief
	 * Handles gauge type object destruction.
	 */
	~CXTPGaugeBaseType();

public:
	/**
	 * @brief
	 * Obtains implementation specified type name.
	 *
	 * @returns Type name string point.
	 */
	virtual LPCWSTR GetTypeName() const = 0;

	/**
	 * @brief
	 * Gets automatic update flag value. If enabled, all gauge trait changes will
	 * immediately trigger the Update call to reflect the changes right away. By default
	 * automatic update is disabled as using it can result in performance loss when related
	 * traits change too frequently.
	 *
	 * @returns <code>TRUE</code> automatic update is enabled, otherwise <code>FALSE</code>.
	 * @see EnableAutomaticUpdate
	 */
	BOOL IsAutomaticUpdateEnabled() const;

	/**
	 * @brief
	 * Sets automatic update flag value. If enabled, all gauge trait changes will
	 * immediately trigger the Update call to reflect the changes right away. By default
	 * automatic update is disabled as using it can result in performance loss when related
	 * traits change too frequently.
	 *
	 * @param bEnable <code>TRUE</code> to enable automatic update, <code>FALSE</code> to disable
	 * it.
	 * @see IsAutomaticUpdateEnabled
	 */
	void EnableAutomaticUpdate(BOOL bEnable = TRUE);

	/**
	 * @brief
	 * Gets a trait value using the specified JPath expression. Unlike CXTPGaugeTrait,
	 * these methods operate on the actual evaluated traits and can be called after a gauge
	 * type is load to modify its traits at run time.
	 *
	 * @details
	 * A JavaScript path is an expression in JavaScript language that points to a nested object
	 * value. Root object values can be accessed by their names, nested object values require a
	 * period sign placed before the name, and array elements can be accessed by specifying a
	 * zero-base array element index in square brackets.
	 * For example, in order to access the <code>bar</code> value from the following object
	 * <code>'{foo: [ {null}, {bar:"#"} ]}' the following JPath expression must be used:
	 * 'foo[1].bar'</code>.
	 *
	 * @param pJPath  A JavaScript value path. See Remarks.
	 * @param vtValue Specifies or receives a trait value
	 * @returns <code>S_OK</code> if succeeds and an error code otherwise.
	 */
	HRESULT GetTrait(LPCTSTR pJPath, COleVariant& vtValue) const;

	/**
	 * @brief
	 * Sets a trait value using the specified JPath expression. Unlike CXTPGaugeTraits,
	 * these methods operate on the actual evaluated traits and can be called after a gauge
	 * type is load to modify its traits at run time.
	 *
	 * @details
	 * A JavaScript path is an expression in JavaScript language that points to a nested object
	 * value. Root object values can be accessed by their names, nested object values require a
	 * period sign placed before the name, and array elements can be accessed by specifying a
	 * zero-base array element index in square brackets.
	 * For example, in order to access the <code>bar</code> value from the following object
	 * <code>'{foo: [ {null}, {bar:"#"} ]}' the following JPath expression must be used:
	 * 'foo[1].bar'</code>.
	 *
	 * @param pJPath  A JavaScript value path. See above remarks.
	 * @param vtValue Specifies or receives a trait value
	 * @returns <code>S_OK</code> if succeeds and an error code otherwise.
	 */
	HRESULT SetTrait(LPCTSTR pJPath, const COleVariant& vtValue);

	/**
	 * @brief
	 * Causes <code>onUpdate</code> JavaScript callback to be invoked to apply state and traits
	 * changes.
	 *
	 * @returns <code>S_OK</code> if succeeds and an error code otherwise.
	 */
	HRESULT Update();

	/**
	 * @brief
	 * Obtains the current evaluated traits object in JSON format.
	 *
	 * @param strTraits String that receives JSON data
	 * @returns <code>TRUE</code> if succeeds and <code>FALSE</code> otherwise.
	 */
	BOOL DumpTraits(CString& strTraits) const;

	/**
	 * @brief
	 * Invokes named gauge action.
	 *
	 * @param lpName    Required action name.
	 * @param vtArg     Optional action argument.
	 * @param pvtResult Optional pointer to a variable that receives result returned by the
	 *                  action function.
	 * @returns An error code or <code>S_OK</code> if no error occurs.
	 */
	HRESULT InvokeAction(LPCTSTR lpName, const COleVariant& vtArg = COleVariant(),
						 COleVariant* pvtResult = NULL);

protected:
	/** @cond */
	virtual void OnLoad();
	virtual void OnInit();
	virtual void OnUpdate();
	virtual void OnCleanup();

	void SetDirty();
	HRESULT GetDispValue(LPDISPATCH pDisp, LPCWSTR pJPath, COleVariant& vtValue) const;
	HRESULT SetDispValue(LPDISPATCH pDisp, LPCWSTR pJPath, const COleVariant& vtValue);
	void GetNamedObject(LPDISPATCH pDisp, LPCWSTR pJPath, VARTYPE vt, BOOL bRequired,
						COleVariant& vtValue) const;
	/** @endcond */

private:
	BOOL Load(CXTPMarkupContext* pContext, IStream& stream, const CXTPGaugeTraits& traits);
	void Unload();
	void Draw(CDC& dc, CRect rc);
	void TraceTraits() const;

	CXTPMarkupContext* GetMarkupContext();
	CXTPMarkupUIElement* GetMarkupRoot();

	void Bind(CXTPGaugeCtrl* pCtrl);
	BOOL OnWndMsg(UINT message, WPARAM wParam, LPARAM lParam, LRESULT& lResult);

	CString GetJSLib(UINT nResourceID) const;

private:
	/**
	 * IXTPMarkupClientSite implementation
	 */

	virtual LPWSTR PrepareCodeChunk(LPCWSTR pCode, const CList<LPCWSTR, LPCWSTR>& requirements);

protected:
	/** @cond */
	DECLARE_DISPATCH_MAP();
	afx_msg void OleInit(LPDISPATCH pData);
	afx_msg LPDISPATCH OleGetTraits();
	afx_msg BSTR OleGetUserTraits();
	afx_msg BSTR OleGetUserTraitsArg();
	afx_msg BOOL OleIsDebug();
	afx_msg void OleGetTraitsModifiers(LPDISPATCH pCallback);
	afx_msg BSTR OleGetLibrary(LPCOLESTR pName);
	afx_msg void OleUpdate();
	afx_msg void OleRedraw();
	afx_msg void OleSetTransparentBackgroundColor(LPDISPATCH pBrushDisp);
	afx_msg void OleSetBackgroundColor(LPDISPATCH pBrushDisp);
	afx_msg double OleDpiX(double dX);
	afx_msg double OleDpiY(double dY);
	afx_msg double OleUnDpiX(double dX);
	afx_msg double OleUnDpiY(double dY);
	/** @endcond */

private:
	CXTPGaugeCtrl* m_pCtrl;
	BOOL m_bAutomaticUpdate;
	const CXTPGaugeTraits* m_pUserTraits;
	CXTPMarkupContext* m_pMarkupContext;
	CXTPMarkupUIElement* m_pMarkupRoot;
	LPDISPATCH m_pInitObj;
	LPDISPATCH m_pDispTraits;
	LPDISPATCH m_pDispUpdate;
	LPDISPATCH m_pDispShutdown;
	LPDISPATCH m_pDispInput;
	LPDISPATCH m_pDispDumpTraits;
	BOOL m_bDirty;

	struct JSLib
	{
		LPCWSTR pName;
		UINT nResID;
	};

	static const JSLib m_JSLibs[];
};

AFX_INLINE BOOL CXTPGaugeBaseType::IsAutomaticUpdateEnabled() const
{
	return m_bAutomaticUpdate;
}

AFX_INLINE void CXTPGaugeBaseType::EnableAutomaticUpdate(BOOL bEnable /*= TRUE*/)
{
	m_bAutomaticUpdate = bEnable;
}

AFX_INLINE CXTPMarkupContext* CXTPGaugeBaseType::GetMarkupContext()
{
	return m_pMarkupContext;
}

AFX_INLINE CXTPMarkupUIElement* CXTPGaugeBaseType::GetMarkupRoot()
{
	return m_pMarkupRoot;
}

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

#endif // !defined(__XTPGAUGEBASE_H__)