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

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

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

/**
 * @brief
 * Enumeration used to determine animation style.
 * @details
 * XTPAnimationDCType type defines constants used by the
 * CXTPAnimationDC class to determine the animation
 * effect for the current device context.
 * @see
 * CXTPAnimationDC, CXTPAnimationDC::Animate, CXTPAnimationDC::SetCustomAnimation
 *
 * @see xtpAniDefault, xtpAniRandom, xtpAniUnfold, xtpAniSlide, xtpAniFade, xtpAniNone
 */
enum XTPAnimationDCType
{
	xtpAniDefault, /**< Uses Windows default animation settings. */
	xtpAniRandom,  /**< Animates a window with a random animation type. */
	xtpAniUnfold,  /**< Animates a window to unfold top to bottom. */
	xtpAniSlide,   /**< Animates a window to slide in from the left. */
	xtpAniFade,	/**< Animates a window with a fade-in effect. */
	xtpAniNone	 /**< No animation. */
};

/**
 * @brief
 * CXTPAnimationDC is a CXTPBufferDC derived class. This class
 * can be used to render animation effects for the current device
 * context.
 * @details
 * By calling Animate, the device context is drawn on the
 * screen with a defined animation type. See XTPAnimationDCType for
 * a list of available animation styles.<p/>
 * Animations are similar to the menu animation effect as seen in
 * Microsoft(r) Windows(r) or Microsoft(r) Office products.
 * <b>Example:</b>
 * See Animate for an example that demonstrates the use of CXTPAnimationDC.
 * @see
 * LPFNANIMATION, XTPAnimationDCType, Animate, SetCustomAnimation
 */
class _XTP_EXT_CLASS CXTPAnimationDC : public CDC
{
public:
	/**
	 * @brief
	 * Function pointer used to define a custom animation effect.
	 * @param rc              Area to display.
	 * @param pDestDC         Destination device context.
	 * @param pSrcDC          Source device context.
	 * @param nType           Enumerated XTPAnimationDCType to determine
	 * animation effect.
	 * @param nSteps          Number of steps to complete animation.
	 * @param nAnimationTime  Amount of time in milliseconds between each step.
	 * <b>Example:</b>
	 * See CXTPAnimationDC::SetCustomAnimation for an example that
	 * demonstrates the use of LPFNANIMATION.
	 * @see
	 * CXTPAnimationDC::SetCustomAnimation, XTPAnimationDCType
	 */
	typedef void(AFX_CDECL* LPFNANIMATION)(CRect rc, CDC* pDestDC, CDC* pSrcDC, int nType,
										   int nSteps, int nAnimationTime);

public:
	/**
	 * @brief
	 * Constructs a CXTPBufferDC object used to create a memory
	 * device context used to draw an off-screen bitmap.
	 * @param hDestDC Handle to the destination device context the memory
	 *                device is BitBlt to.
	 * @param rcPaint Size of the area to paint.
	 */
	CXTPAnimationDC(HDC hDestDC, const CRect& rcPaint);

	/**
	 * @brief
	 * Constructs a CXTPBufferDC object used to create a memory
	 * device context used to draw an off-screen bitmap.
	 * @param hDestDC Handle to the destination device context the memory
	 *                device is BitBlt to.
	 * @param rcPaint Size of the area to paint.
	 * @param clrBack Represents background color for fill; can be COLORREF or
	 *                gradient values using CXTPPaintManagerColorGradient.
	 * @param bHorz   Used when drawing a gradient background. TRUE to draw
	 *                gradient from left-to-right, otherwise drawn top-to-bottom.
	 */
	CXTPAnimationDC(HDC hDestDC, const CRect& rcPaint, const CXTPPaintManagerColorGradient& clrBack,
					const BOOL bHorz = FALSE);

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

	/**
	 * @brief
	 * This member function performs the animation.
	 * @param nType           [in] Type of animation to perform.
	 * @param nSteps          [in] Number of steps to take during animation.
	 * @param nAnimationTime  [in] Amount of time to rest, in milliseconds, between
	 * each step.
	 * @details
	 * Call this member function from your WM_PAINT handler to render the
	 * animation background.
	 * <b>Example:</b>
	 * The following example demonstrates the use of Animate:
	 * <pre>
	 * void CMainFrame::DoAnimationTest(CDC* pDC, XTPAnimationDCType anim)
	 * {
	 *    CRect r(100, 100, 300, 200);
	 *    CXTPBufferDC background(pDC, r, (COLORREF)-1);
	 *    background.FromDC();
	 *    {
	 *       CXTPAnimationDC memDC(pDC, r, NULL);
	 *
	 *       r -= r.TopLeft();
	 *
	 *       memDC.Rectangle(r);
	 *       memDC.MoveTo(0, 0);
	 *       memDC.LineTo(r.BottomRight());
	 *       memDC.SelectStockObject(GRAY_BRUSH);
	 *       memDC.FloodFill(r.left + 10, r.top + 10, RGB(0, 0, 0));
	 *       memDC.Animate(anim, 10, 1000);
	 *    }
	 *
	 *    Sleep(2000);
	 * }
	 * </pre>
	 * @see
	 * LPFNANIMATION, XTPAnimationDCType, SetCustomAnimation
	 */
	void Animate(int nType = xtpAniDefault, int nSteps = 10, int nAnimationTime = 1000);

	/**
	 * @brief
	 * This member implements default animation effects <i>Fade</i>, <i>Slide</i>
	 * and <i>Unfold</i>.
	 * @param rc              [in] Bounding rectangle.
	 * @param pDestDC         [in] Pointer to the device context you must draw to.
	 * @param pSrcDC          [in] Device context that contains the bitmap you must
	 * take.
	 * @param nType           [in] Type of animation to perform. For custom animation,
	 * you must use numbers greater than <i>xtpAniNone</i>.
	 * @param nSteps          [in] Number of steps to take during the animation.
	 * @param nAnimationTime  [in] Amount of time to rest, in milliseconds, between
	 * each step.
	 * @details
	 * You can add new animation effects to call the SetCustomAnimation member.
	 * <b>Example:</b>
	 * See SetCustomAnimation for an example that demonstrates the use of
	 * DefaultAnimation.
	 * @return
	 * @see
	 * LPFNANIMATION, XTPAnimationDCType, Animate, SetCustomAnimation
	 */
	static void AFX_CDECL DefaultAnimation(CRect rc, CDC* pDestDC, CDC* pSrcDC, int nType,
										   int nSteps, int nAnimationTime);

	/**
	 * @brief
	 * Call this member function to setup new Animation effects.
	 * @param pCustom  [in] Function pointer that holds the address of a custom
	 * animation function.
	 * @details
	 * You can call DefaultAnimation in your custom animation method to
	 * handle default animation effects.
	 * <b>Example:</b>
	 * The following example demonstrates the use of SetCustomAnimation:
	 * <pre>
	 * int CMainFrame::OnCreate()
	 * {
	 *    // custom animation procedure.
	 *    CXTPAnimationDC::SetCustomAnimation(CustomAnimation);
	 *    ...
	 * }
	 * ...
	 * void CMainFrame::CustomAnimation(CRect rc, CDC* pDestDC,
	 *    CDC* pSrcDC, int nType, int nSteps, int nAnimationTime)
	 * {
	 *    if (nType == xtpAniUnfold)
	 *    {
	 *       // do custom animation
	 *    }
	 *    else
	 *    {
	 *       CXTPAnimationDC::DefaultAnimation(rc, pDestDC,
	 *       pSrcDC, nType, nSteps, nAnimationTime);
	 *    }
	 * }
	 * </pre>
	 * @return
	 * @see
	 * LPFNANIMATION, XTPAnimationDCType, Animate, DefaultAnimation
	 */
	static void AFX_CDECL SetCustomAnimation(LPFNANIMATION pCustom);

private:
	/**
	 * @brief
	 * Private LPFNANIMATION pointer that points to the address of a
	 * user defined animation method.
	 */
	static LPFNANIMATION m_pCustomAnimation;

	/**
	 * @brief
	 * Private method is used internally for alpha-blending.
	 */
	static void AFX_CDECL AlphaBlendU(PBYTE, PBYTE, int, int, PBYTE, BYTE);

protected:
	HDC m_hDestDC;		  /**< Handle to the destination device context. */
	CBitmap m_bitmap;	 /**< Bitmap in memory device context */
	CRect m_rect;		  /**< Size of the area to paint. */
	HGDIOBJ m_hOldBitmap; /**< Handle to the previously selected bitmap. */
};

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