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

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

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

/**
 * @brief
 * The base interface for a preview handler implementation.
 * @see
 * IXTPPreviewHost, IXTPPreviewProvider
 */
struct IXTPPreview
{
	/**
	 * @brief
	 * Handles object destruction.
	 */
	virtual ~IXTPPreview()
	{
	}

	/**
	 * @brief
	 * Returns TRUE if the handler has attempted and finished loading the
	 * preview regardless of the actual loading result.
	 * @return
	 * TRUE if the handler is ready.
	 */
	virtual BOOL IsReady() const = 0;

	/**
	 * @brief
	 * Determines if the preview is available (i.e. the handler was able
	 * to load preview data successfully).
	 * @return
	 * TRUE if the preview is available.
	 */
	virtual BOOL IsAvailable() const = 0;

	/**
	 * @brief
	 * Determines if the handler implements its own page navigator.
	 * @details
	 * In the case that the handler implements its own page navigator,
	 * it does not require the common page navigator to be used for it.
	 * @return
	 * TRUE if the handler implements its own page navigator.
	 */
	virtual BOOL HasOwnNavigator() const = 0;

	/**
	 * @brief
	 * Retrieves the number of pages available for the common page navigator.
	 * @return
	 * The number of pages available for the common page navigator,
	 * or 0 if no pages are supported.
	 */
	virtual UINT GetNumberOfPages() const = 0;

	/**
	 * @brief
	 * Obtains the preferred page size in pixels if that is required by the
	 * preview. If zero size is returned, then it is assumed that the
	 * preview can be scaled to the entire available preview area.
	 * @return
	 * Preferred page size, or 0,0.
	 */
	virtual SIZE GetPreferredPageSize() const = 0;

	/**
	 * @brief
	 * If pages are supported by the preview, then it should cause navigation
	 * to the specified page number. Otherwise, the call should be ignored.
	 * @param page Zero-based page number to show preview for.
	 */
	virtual void GoToPage(UINT page) = 0;

	/**
	 * @brief
	 * This method is called every time the preview has to draw itself into
	 * the available client area. If the preview drawing is not provided by
	 * the preview handler, then the call should be ignored.
	 * @param dc Target device context.
	 * @param clientSize The size of the available client rectangle starting at 0,0.
	 * @param updateRect Rectangular area requested for an update.
	 */
	virtual void Draw(HDC dc, SIZE clientSize, RECT updateRect) = 0;

	/**
	 * @brief
	 * Handles a window message sent to the host preview control. It can
	 * be used by windowless preview handlers for handling events.
	 * @param msg Message structure pointer.
	 * @param result Pointer to the message result.
	 * @return
	 * TRUE if the message is handled by the preview handler and must not
	 * be forwarded to the host control, otherwise FALSE is expected.
	 */
	virtual BOOL OnHostWndMsg(LPMSG msg, LRESULT* result) = 0;

	/**
	 * @brief
	 * Determines if the preview implementation is compatible with
	 * composited top level windows (i.e. if any of its parents has
	 * the WS_EX_COMPOSITED style specified).
	 * @return
	 * TRUE if the preview implementation is WS_EX_COMPOSITED compatible.
	 */
	virtual BOOL SupportsCompositedParent() const = 0;

	/**
	 * @brief
	 * Activate preview.
	 */
	virtual void Activate() = 0;
};

/**
 * @brief
 * Interface implemented by the preview host control.
 * @see
 * IXTPPreview, IXTPPreviewProvider
 */
struct IXTPPreviewHost
{
	/**
	 * @brief
	 * Handles object destruction.
	 */
	virtual ~IXTPPreviewHost()
	{
	}

	/**
	 * @brief
	 * Obtains the background color used by the host control.
	 * @return
	 * The background color used by the host control.
	 */
	virtual COLORREF GetBackgroundColor() const = 0;

	/**
	 * @brief
	 * Obtains the foreground color used by the host control.
	 * @return
	 * The foreground color used by the host control.
	 */
	virtual COLORREF GetForegroundColor() const = 0;
};

/**
 * @brief
 * Interface to be implemented by a preview provider.
 * @see
 * IXTPPreviewHost, IXTPPreview, CXTPPreviewProviderBase
 */
struct IXTPPreviewProvider
{
	/**
	 * @brief
	 * Handles object destruction.
	 */
	virtual ~IXTPPreviewProvider()
	{
	}

	/**
	 * @brief
	 * This method is called by the host control when it first binds the provider.
	 * @param host Preview host control interface reference.
	 */
	virtual void BindHost(IXTPPreviewHost& host) = 0;

	/**
	 * @brief
	 * Obtains the list of file extensions supported by the associated preview
	 * implementation. The list is a semicolon separated string of extensions
	 * without periods (e.g. "doc;docx;xls;xlsx"). The return value can also be
	 * NULL which means that the preview implementation is capable of extracting
	 * previews from all supplied file types.
	 * @return
	 * The list of supported extensions, or NULL to indicate ability to preview
	 * all file types.
	 */
	virtual LPCTSTR GetDefaultFileAssociations() const = 0;

	/**
	 * @brief
	 * Creates a preview object for the specified file.
	 * @param pFilePath  File path value for which the preview is to be created.
	 * @param hwndParent Preview parent window handle.
	 * @return
	 * A valid pointer to the new preview object created, or NULL if it was not
	 * possible to create a preview object.
	 */
	virtual IXTPPreview* CreatePreview(LPCTSTR pFilePath, HWND hwndParent) = 0;

	/**
	 * @brief
	 * Creates a preview object for the specified file.
	 * @param stream           Data stream that contains file data to be previewed.
	 * @param pImpliedFileName An implied name of the file associated with the stream object, only
	 *                         extension part is important for identiying the format of the data to
	 * be previewed.
	 * @param hwndParent       Preview parent window handle.
	 * @return
	 * A valid pointer to the new preview object created, or NULL if it was not
	 * possible to create a preview object.
	 */
	virtual IXTPPreview* CreatePreview(IStream& stream, LPCTSTR pImpliedFileName,
									   HWND hwndParent) = 0;
};

class CXTPPreviewCtrl;

/**
 * @brief
 * Base class for a preview provider which implements common behavior
 * to be exposed by a preview provider.
 * @see
 * IXTPPreviewProvider
 */
class _XTP_EXT_CLASS CXTPPreviewProviderBase : public IXTPPreviewProvider
{
	friend class CXTPPreviewCtrl;

protected:
	/**
	 * @brief
	 * Handles object construction.
	 */
	CXTPPreviewProviderBase();

	/**
	 * @brief
	 * The method is called by the host preview control when the provider
	 * is initially bound to the host.
	 * @param host Host interface.
	 */
	void BindHost(IXTPPreviewHost& host);

	/**
	 * @brief
	 * Obtains the preview host interface that the provider is bound to.
	 * @return
	 * Preview host interface.
	 */
	IXTPPreviewHost& GetHost() const;

private:
	mutable IXTPPreviewHost* m_pHost;
};
/** @cond */
AFX_INLINE CXTPPreviewProviderBase::CXTPPreviewProviderBase()
	: m_pHost(NULL)
{
}

AFX_INLINE void CXTPPreviewProviderBase::BindHost(IXTPPreviewHost& host)
{
	m_pHost = &host;
}

AFX_INLINE IXTPPreviewHost& CXTPPreviewProviderBase::GetHost() const
{
	_ASSERTE(NULL != m_pHost);
	return *m_pHost;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // #if !defined(__XTPPREVIEWABSTRACT_H__)
	   /** @endcond */