/**
 * @file XTPApplication.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(__XTPAPPLICATION_H__)
#	define __XTPAPPLICATION_H__
/** @endcond */

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

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

class CXTPApplication;
class CXTPComInitializer;

namespace Gdiplus
{
struct GdiplusStartupOutput;
};

/**
 * @brief
 * Global ambient property identifiers.
 */
enum XTPApplicationAmbientProperty
{
	/**
	 * @brief
	 * Ambient accent color value. A COLORREF value determined by VT_I4 variant field.
	 * COLORREF_NULL should be used to specify a default accent color value determined
	 * individually by each suscribed client.
	 */
	xtpApplicationAccentColor,

	/**
	 * @brief
	 * Ambient state color value. A COLORREF value determined by VT_I4 variant field.
	 * COLORREF_NULL should be used to specify a default state color value determined
	 * individually by each suscribed client.
	 * @see
	 * XTPSetVSStateColor
	 */
	xtpApplicationStateColor,

	/**
	 * @brief
	 * A long boolean value that enables use of the current system accent/colorization color used
	 * instead applicable. The default value is 0.
	 */
	xtpApplicationUseSystemAccentColor,

	/** @cond */
	xtpApplicationPropertyCount
	/** @endcond */
};

/**
 * @brief
 * Defines a callback interface for XTP application event sink.
 */
struct IXTPApplicationEvents
{
	/**
	 * @brief
	 * Handles object destruction
	 */
	virtual ~IXTPApplicationEvents()
	{
	}

	/**
	 * @brief
	 * Is called by framework before application shut down processing starts.
	 * @param pApplication Event sending application pointer.
	 */
	virtual void OnBeforeApplicationShutdown(CXTPApplication* pApplication)
	{
		UNREFERENCED_PARAMETER(pApplication);
	}

	/**
	 * @brief
	 * Is called by framework when application is being shutdown before
	 * the actual shutting down.
	 * @param pApplication Event sending application pointer.
	 */
	virtual void OnApplicationShutdown(CXTPApplication* pApplication)
	{
		UNREFERENCED_PARAMETER(pApplication);
	}

	/**
	 * @brief
	 * Is called by framework after application shut down processing is completed.
	 * @param pApplication Event sending application pointer.
	 */
	virtual void OnAfterApplicationShutdown(CXTPApplication* pApplication)
	{
		UNREFERENCED_PARAMETER(pApplication);
	}

	/**
	 * @brief
	 * Called by framework when an ambient property is changed.
	 * @param pApplication Event sending application pointer.
	 * @param nProperty Updated ambient property identifier.
	 * @see
	 * CXTPApplication::SetAmbientProperty, CXTPApplication::GetAmbientProperty
	 */
	virtual void OnAmbientPropertyChanged(CXTPApplication* pApplication,
										  XTPApplicationAmbientProperty nProperty)
	{
		UNREFERENCED_PARAMETER(pApplication);
		UNREFERENCED_PARAMETER(nProperty);
	}
};

/**
 * @brief
 * Defines a global XTP application object interface. The object is
 * kept alive until a call to XTPShutdown. At any moment there is
 * one and only one XTP application instance per loaded dynamic or
 * executable module which links XTP framework.
 * @see
 * XTPGetApplication, XTPInitialize, XTPShutdown, CXTPWinApp
 */
class _XTP_EXT_CLASS CXTPApplication
	: public CObject
	, public CXTPObservable<CXTPApplication, IXTPApplicationEvents>
	, public CXTPSynchronized
{
	friend class CXTPSingleton<CXTPApplication>;

	friend _XTP_EXT_CLASS CXTPApplication* AFX_CDECL XTPGetApplication();
	friend _XTP_EXT_CLASS BOOL AFX_CDECL XTPInitialize(int xtpComInit);
	friend _XTP_EXT_CLASS void AFX_CDECL XTPShutdown();

	DECLARE_DYNAMIC(CXTPApplication);

public:
	/**
	 * @brief
	 * Determines if the application object is ready to be used, i.e. it has been initialized and
	 * hasn't been shutdown.
	 * @return
	 * TRUE is the application object is ready, FALSE otherwise.
	 * @see
	 * XTPInitialize, XTPGetApplication
	 */
	BOOL IsReady() const;

	/**
	 * @brief
	 * Returns module state pointer obtained at the point where XTPInitialize
	 * or XTPGetApplication is first called.
	 * @return
	 * Module state pointer.
	 * @see
	 * XTPInitialize, XTPGetApplication
	 */
	AFX_MODULE_STATE* GetModuleState();

	/**
	 * @brief
	 * Sets ambient property value.
	 * @param nProperty Ambient property identifier.
	 * @param vtValue Ambient property value determined by its identifier.
	 * @details
	 * Ambient properties are the global values specific to the current application.
	 * Unlike global variables, changing an ambient property notifies all subscribed
	 * clients about a property changed so that takes effect immediately accross
	 * entire application.
	 * Accessing ambient properties asynchronously should be guarded using XTPAccessShared or
	 * XTPAccessExclusive.
	 * @see
	 * XTPApplicationAmbientProperty, IXTPApplicationEvents
	 */
	void SetAmbientProperty(XTPApplicationAmbientProperty nProperty, COleVariant vtValue);

	/**
	 * @brief
	 * Gets ambient property value.
	 * @param nProperty Ambient property identifier.
	 * @return
	 * A reference to a COleVariant object tha represents ambient property value.
	 * @details
	 * Ambient properties are the global values specific to the current application.
	 * Unlike global variables, changing an ambient property notifies all subscribed
	 * clients about a property changed so that takes effect immediately accross
	 * entire application.
	 * Accessing ambient properties asynchronously should be guarded using XTPAccessShared or
	 * XTPAccessExclusive.
	 * @see
	 * XTPApplicationAmbientProperty, IXTPApplicationEvents
	 */
	const COleVariant& GetAmbientProperty(XTPApplicationAmbientProperty nProperty) const;

	/**
	 * @brief
	 * Triggers ambient property update notification even if property value is not changed.
	 * @param nProperty Ambient property identifier.
	 * @see
	 * XTPInitialize, XTPGetApplication
	 */
	void TriggerAmbientPropertyUpdate(XTPApplicationAmbientProperty nProperty);

	/**
	 * @brief
	 * Obtains COM initialization flags.
	 * @return
	 * COM initialization flags
	 */
	int GetComInitFlags() const;

	/**
	 * @brief
	 * Obtains main application thread ID.
	 * @return
	 * Main application thread ID.
	 */
	DWORD GetAppThreadId() const;

	/** @cond */
	~CXTPApplication();
	/** @endcond */
private:
	CXTPApplication();
	static CXTPApplication& AFX_CDECL GetInstance();

	BOOL Initialize(int xtpComInit);
	void Shutdown();
	void InitAmbientProperties();

	AFX_MODULE_STATE* m_pModuleState; /**< Module state */
	BOOL m_bInitialized;
	CXTPComInitializer* m_pComInit;
	DWORD m_dwThreadId;
	BOOL m_bShutdown; /**< FALSE until XTPShutdown is called */
	HMODULE m_hGdiPlusModule;
	ULONG_PTR m_nGdiplusToken;
	Gdiplus::GdiplusStartupOutput* m_pGdiplusStartupOutput;
	COleVariant m_arAmbientProperties[xtpApplicationPropertyCount];
};
/** @cond */
AFX_INLINE BOOL CXTPApplication::IsReady() const
{
	return m_bInitialized && !m_bShutdown;
}

AFX_INLINE DWORD CXTPApplication::GetAppThreadId() const
{
	return m_dwThreadId;
}
/** @endcond */
/**
 * @brief
 * Initializes XTP framework. Must not be called after XTPShutdown call.
 * For backward compatibility the call is optional, however future versions
 * may require it to be called before any other call to XTP framework.
 * CXTPWinApp calls it automatically in InitInstance.
 * @param xtpComInit Global COM/OLE initialization method.
 * @return
 * TRUE if XTP framework is initialized successfully.
 * @details
 * If extended COM initialization flags are being used bu CoInitializeEx function is not
 * available then xtpComInitSTA is assumed, all other flags get ignored and the legacy
 * CoInitialize gets called.
 * @see
 * XTPGetApplication, XTPShutdown, CXTPWinApp
 */
_XTP_EXT_CLASS BOOL AFX_CDECL XTPInitialize(int xtpComInit = xtpComInitAppDefault);

/**
 * @brief
 * Obtains the only XTP application instance pointer. Must be called
 * between XTPInitialize and XTPShutdown calls.
 * @return
 * The only XTP application instance pointer.
 * @see
 * XTPInitialize, XTPShutdown
 */
_XTP_EXT_CLASS CXTPApplication* AFX_CDECL XTPGetApplication();

/**
 * @brief
 * Performs XTP application shutting down with releasing all internal
 * XTP pointers and resources but not terminating the calling thread.
 * The call to XTPShutdown must happen as late as possible at runtime
 * but no later than returning from WinMain or DllMain.
 * For backward compatibility it still is called by framework automatically
 * on static storage destruction but the order of this operation
 * is not guaranteed.
 * CXTPWinApp calls it automatically in ExitInstance.
 * @see
 * XTPInitialize, XTPGetApplication, CXTPWinApp
 */
_XTP_EXT_CLASS void AFX_CDECL XTPShutdown();

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // !defined(__XTPAPPLICATION_H__)
/** @endcond */