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

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

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

class CXTPMarkupContext;
class CXTPMarkupUIElement;

/**
 * @brief
 * Notifies Markup context window about Markup redraw event.
 * @param wParam Not used.
 * @param lParam Points to the update rectangle of type RECT or NULL if the entire window must be
 * updated.
 * @return
 * TRUE if application handles the request and no default processing is required. Returning
 * FALSE will invalidate and update the affected rectangle by default.
 * @see
 * XTPMarkupCreateContext
 */
const UINT XTP_WM_MARKUPREDRAW = (WM_USER + 9820);

/**
 * @brief
 * XTPMarkupCreateContext is part of Markup API that creates new CXTPMarkupContext object
 * @param hWnd Window handle to link context with
 * @param bDpiAware TRUE to enable DPI awarness.
 * @details
 * XTPMarkupCreateContext creates new CXTPMarkupContext that holds common properties of Markup
 * Elements like default font, default text color, current selected element, etc.
 *
 * <b>Example:</b>
 * <pre>
 * CXTPMarkupContext* pContext = XTPMarkupCreateContext(NULL, TRUE);
 * pContext->SetDpiAware();
 * CXTPMarkupUIElement* pElement = XTPMarkupParseText(pContext, "<Ellipse Fill='Red' Width='100'
 * Height='100'/>"); CSize sz = XTPMarkupMeasureElement(pElement);
 * XTPMarkupRenderElement(pElement, pDC->GetSafeHdc(), CRect(CPoint(0), sz));
 * XTPMarkupReleaseElement(pElement);
 * XTPMarkupReleaseContext(pContext, TRUE);
 * </pre>
 * @return
 * Returns new CXTPMarkupContext object pointer
 * @see
 * XTPMarkupReleaseContext, XTPMarkupParseText, XTPMarkupReleaseElement, XTP_WM_MARKUPREDRAW
 */
_XTP_EXT_CLASS CXTPMarkupContext* AFX_CDECL XTPMarkupCreateContext(HWND hWnd	  = NULL,
																   BOOL bDpiAware = FALSE);

/**
 * @brief
 * XTPMarkupCreateContext is part of Markup API that creates new CXTPMarkupContext object
 * @param hWnd Window handle to link context with
 * @param rcUpdate Target update rectangle
 * @param bDpiAware TRUE to enable DPI awarness.
 * @details
 * XTPMarkupCreateContext creates new CXTPMarkupContext that holds common properties of Markup
 * Elements like default font, default text color, current selected element, etc.
 *
 * <b>Example:</b>
 * <pre>
 * CXTPMarkupContext* pContext = XTPMarkupCreateContext(NULL, TRUE);
 * pContext->SetDpiAware();
 * CXTPMarkupUIElement* pElement = XTPMarkupParseText(pContext, "<Ellipse Fill='Red' Width='100'
 * Height='100'/>"); CSize sz = XTPMarkupMeasureElement(pElement);
 * XTPMarkupRenderElement(pElement, pDC->GetSafeHdc(), CRect(CPoint(0), sz));
 * XTPMarkupReleaseElement(pElement);
 * XTPMarkupReleaseContext(pContext, TRUE);
 * </pre>
 * @return
 * Returns new CXTPMarkupContext object pointer
 * @see
 * XTPMarkupReleaseContext, XTPMarkupParseText, XTPMarkupReleaseElement, XTP_WM_MARKUPREDRAW
 */
_XTP_EXT_CLASS CXTPMarkupContext* AFX_CDECL XTPMarkupCreateContext(HWND hWnd, RECT rcUpdate,
																   BOOL bDpiAware);

/**
 * @brief
 * Assigns handle to using the items specified by <code>pContext</code> and <code>hWnd</code>.
 * @param pContext Points to a CXTPMarkupContext object.
 * @param hWnd Window handle to link context with.
 * @return
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupAssignHandle(CXTPMarkupContext* pContext, HWND hWnd);

/**
 * @brief
 * Assigns handle to using the items specified by <code>pContext</code> and <code>hWnd</code>.
 * @param pContext Points to a CXTPMarkupContext object.
 * @param hWnd Window handle to link context with.
 * @param rcUpdate Target update rectangle
 * @return
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupAssignHandle(CXTPMarkupContext* pContext, HWND hWnd,
													CRect rcUpdate);

/**
 * @brief
 * XTPMarkupReleaseContext is part of Markup API that destroys CXTPMarkupContext object
 * @param pContext Pointer to CXTPMarkupContext that will be released
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @details
 * XTPMarkupReleaseContext without bShutdown argument does not perform context shutdown
 * and simply decrements context reference counter.
 * @return
 * @see
 * XTPMarkupCreateContext
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupReleaseContext(CXTPMarkupContext*& pContext);

/**
 * @brief
 * XTPMarkupReleaseContext is part of Markup API that destroys CXTPMarkupContext object
 * @param pContext Pointer to CXTPMarkupContext that will be released
 * @param bShutdown If TRUE then the context will be shutdown, i.e. all data and states will be
 * reset. Otherwise it simply decrements context reference counter.
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @details
 * XTPMarkupReleaseContext without bShutdown argument does not perform context shutdown
 * and simply decrements context reference counter.
 * @return
 * @see
 * XTPMarkupCreateContext
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupReleaseContext(CXTPMarkupContext*& pContext, BOOL bShutdown);

/**
 * @brief
 * XTPMarkupParseText is part of Markup API that creates new Markup elements using Markup string
 * @param pContext   Pointer to CXTPMarkupContext. All new elements will be part of this context.
 * @param lpszMarkup String to parse
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return A root markup UI element pointer or NULL if there is an error.
 * @see
 * XTPMarkupCreateContext, XTPMarkupReleaseElement, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CXTPMarkupUIElement* AFX_CDECL XTPMarkupParseText(CXTPMarkupContext* pContext,
																 LPCSTR lpszMarkup);

/**
 * @brief
 * XTPMarkupParseText is part of Markup API that creates new Markup elements using Markup string
 * @param pContext   Pointer to CXTPMarkupContext. All new elements will be part of this context.
 * @param lpszMarkup String to parse
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return A root markup UI element pointer or NULL if there is an error.
 * @see
 * XTPMarkupCreateContext, XTPMarkupReleaseElement, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CXTPMarkupUIElement* AFX_CDECL XTPMarkupParseText(CXTPMarkupContext* pContext,
																 LPCWSTR lpszMarkup);

/**
 * @brief
 * XTPMarkupParseText is part of Markup API that creates new Markup elements using Markup string
 * @param pContext   Pointer to CXTPMarkupContext. All new elements will be part of this context.
 * @param lpszMarkup String to parse
 * @param nLength Length of string to parse.
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return A root markup UI element pointer or NULL if there is an error.
 * @see
 * XTPMarkupCreateContext, XTPMarkupReleaseElement, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CXTPMarkupUIElement* AFX_CDECL XTPMarkupParseText(CXTPMarkupContext* pContext,
																 LPCSTR lpszMarkup,
																 INT_PTR nLength);

/**
 * @brief
 * XTPMarkupParseText is part of Markup API that creates new Markup elements using Markup string
 * @param pContext   Pointer to CXTPMarkupContext. All new elements will be part of this context.
 * @param lpszMarkup String to parse
 * @param nLength Length of string to parse.
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return A root markup UI element pointer or NULL if there is an error.
 * @see
 * XTPMarkupCreateContext, XTPMarkupReleaseElement, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CXTPMarkupUIElement* AFX_CDECL XTPMarkupParseText(CXTPMarkupContext* pContext,
																 LPCWSTR lpszMarkup,
																 INT_PTR nLength);

/**
 * @brief
 * XTPMarkupParseText is part of Markup API that creates new Markup elements using Markup string
 * @param pContext   Pointer to CXTPMarkupContext. All new elements will be part of this context.
 * @param pStream Points to an IStream object.
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return A root markup UI element pointer or NULL if there is an error.
 * @see
 * XTPMarkupCreateContext, XTPMarkupReleaseElement, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CXTPMarkupUIElement* AFX_CDECL XTPMarkupParseText(CXTPMarkupContext* pContext,
																 IStream* pStream);

/**
 * @brief
 * XTPMarkupReleaseElement is part of Markup API that destroys CXTPMarkupUIElement object
 * @param pElement   Pointer to CXTPMarkupUIElement that will be released
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return
 * @see
 * XTPMarkupCreateContext, XTPMarkupParseText, XTPMarkupMeasureElement,
 * XTPMarkupRenderElement
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupReleaseElement(CXTPMarkupUIElement*& pElement);

/**
 * @brief
 * XTPMarkupMeasureElement is part of Markup API that calculates dimensions of Markup element
 * @param pElement   Pointer to CXTPMarkupUIElement that size need to calculate
 * @param cxAvail    Available width
 * @param cyAvail    Available height
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return
 * Returns the dimensions of the CXTPMarkupUIElement
 * @see
 * XTPMarkupCreateContext, XTPMarkupParseText, XTPMarkupRenderElement
 */
_XTP_EXT_CLASS CSize AFX_CDECL XTPMarkupMeasureElement(CXTPMarkupUIElement* pElement,
													   int cxAvail = INT_MAX,
													   int cyAvail = INT_MAX);

/**
 * @brief
 * XTPMarkupRenderElement is part of Markup API that draws Markup element to device context
 * @param pElement   CXTPMarkupUIElement object to draw
 * @param hDC        Handle to the device context
 * @param rc         Pointer to a RECT structure that contains the rectangle in which the element is
 * to be formatted
 *
 * <b>Example:</b>
 * See Example for XTPMarkupCreateContext function
 * @return
 * @see
 * XTPMarkupCreateContext, XTPMarkupParseText, XTPMarkupMeasureElement
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupRenderElement(CXTPMarkupUIElement* pElement, HDC hDC,
													 LPCRECT rc);

/**
 * @brief
 * XTPMarkupSetDefaultFont is part of Markup API. Call it to set default font and text color for
 * Markup elements
 * @param pContext Pointer to a CXTPMarkupContext object.
 * @param hFont   Handle to default font.
 * @param clrText Default text color.
 *
 * <b>Example:</b>
 * <pre>
 * CXTPMarkupContext* pContext = XTPMarkupCreateContext(NULL, TRUE);
 * pContext->SetDpiAware();
 * CXTPMarkupUIElement* pElement = XTPMarkupParseText(pContext,
 * &ldquo;\<TextBlock Text='Hello, world'/\>&rdquo;);
 * XTPMarkupSetDefaultFont(pContext, 0, RGB(255, 0, 0));
 *
 * CSize sz = XTPMarkupMeasureElement(pElement);
 * XTPMarkupRenderElement(pElement, pDC->GetSafeHdc(), CRect(CPoint(0), sz));
 * XTPMarkupReleaseElement(pElement);
 * XTPMarkupReleaseContext(pContext, TRUE);
 * </pre>
 * @return
 * @see
 * XTPMarkupCreateContext, XTPMarkupParseText, XTPMarkupMeasureElement
 */
_XTP_EXT_CLASS void AFX_CDECL XTPMarkupSetDefaultFont(CXTPMarkupContext* pContext, HFONT hFont,
													  COLORREF clrText);

/**
 * @brief
 * XTPMarkupRelayMessage is part of Markup API. It used to notify Markup element about events of
 * associated window.
 * @param pElement  Pointer to Markup element that need to notify
 * @param message   Specifies the message to be sent.
 * @param wParam    Specifies additional message-dependent information
 * @param lParam    Specifies additional message-dependent information
 * @param pResult   The return value of WindowProc. Depends on the message
 * @return
 * Nonzero if message was handled; otherwise 0.
 * @see
 * XTPMarkupCreateContext
 */
_XTP_EXT_CLASS BOOL AFX_CDECL XTPMarkupRelayMessage(CXTPMarkupUIElement* pElement, UINT message,
													WPARAM wParam, LPARAM lParam, LRESULT* pResult);

/**
 * @brief
 * XTPMarkupRelayMessage is part of Markup API. It used to notify Markup element about events of
 * associated window.
 * @param pContext  Pointer to CXTPMarkupContext object.
 * @param message   Specifies the message to be sent.
 * @param wParam    Specifies additional message-dependent information
 * @param lParam    Specifies additional message-dependent information
 * @param pResult   The return value of WindowProc. Depends on the message
 * @return
 * Nonzero if message was handled; otherwise 0.
 * @see
 * XTPMarkupCreateContext
 */
_XTP_EXT_CLASS BOOL AFX_CDECL XTPMarkupRelayMessage(CXTPMarkupContext* pContext, UINT message,
													WPARAM wParam, LPARAM lParam, LRESULT* pResult);

/**
 * @brief
 * XTPMarkupElementContext is part of Markup API that returns Markup contrext of Markup element
 * @param pElement  Pointer to Markup element that context need to know
 * @return
 * Pointer of associated CXTPMarkupContext
 * @see
 * XTPMarkupCreateContext
 */
_XTP_EXT_CLASS CXTPMarkupContext* AFX_CDECL XTPMarkupElementContext(CXTPMarkupUIElement* pElement);

_XTP_EXT_CLASS void AFX_CDECL XTPMarkupDrawText(CXTPMarkupContext* pContext, HDC hDC,
												LPCTSTR lpszText, LPRECT lpRect, UINT nFormat);

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