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

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

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

#	if defined(XTP_INIT_BY_REGULAR_DLL)

/**
 * @brief
 * This member function will initialize the resources for the Xtreme Toolkit.
 * If using the Xtreme Toolkit as an extension .DLL within a regular
 * DLL, then add the following two lines to your stdafx.h file. This will
 * give you access to the exported function XTPInitDLL():
 * <b>Example:</b>
 * The following code sample demonstrates the usage of XTPInitDLL:
 * <pre>
 * #define XTP_INIT_BY_REGULAR_DLL
 * #include "XTToolkit.h"
 * </pre>
 *
 * You will then need to add XTP_INIT_BY_REGULAR_DLL to the Xtreme Toolkit
 * preprocessor definitions and rebuild it. After you have done this,
 * locate your CWinApp::InitInstance() method for your regular DLL
 * and make the following call:
 *
 * <pre>
 * XTPInitDLL();
 * </pre>
 *
 * This will initialize the resources for the Xtreme Toolkit.
 */
_XTP_EXT_CLASS void AFXAPI XTPInitDLL();

#	endif //#if defined(XTP_INIT_BY_REGULAR_DLL)

class CXTPImageManager;

/**
 * @brief
 * The XTPChangeWindowFont function will set the font for
 * the window specified by <i>pWnd</i> and all of the child windows
 * owned by <i>pWnd</i>.
 * @param pWnd   Pointer to a valid CWnd object.
 * @param pFont  Pointer to the new font to set for the window.
 * @return
 */
_XTP_EXT_CLASS void AFXAPI XTPChangeWindowFont(CWnd* pWnd, CFont* pFont);

/**
 * @brief
 * The XTPDrawEmbossed function will draw an embossed icon onto the specified
 * device context from the image list <i>imageList</i>. It is typically used
 * by toolbars and menus to draw a disabled icon in color.
 * @param pDC        Pointer to the current device context.
 * @param imageList  Address of an image list.
 * @param nIndex     Index of the image in the image list.
 * @param point      XY location of where to draw the icon.
 * @param bInColor   TRUE to draw the item in color; otherwise the icon will
 * be drawn with the default disabled look.
 * @return
 */
_XTP_EXT_CLASS void AFXAPI XTPDrawEmbossed(CDC* pDC, CImageList& imageList, int nIndex,
										   CPoint point, BOOL bInColor);

/**
 * @brief
 * Renders a shadow onto the specified device context.
 * @param pDC   Pointer to the current device context.
 * @param rect  Size of the area to draw.
 * @details
 * The XTPDrawShadedRect function will render a shaded or
 * 'shadow' rectangle onto the the device context specified by pDC.
 * @return
 */
_XTP_EXT_CLASS void AFXAPI XTPDrawShadedRect(CDC* pDC, CRect& rect);

/**
 * @brief
 * The XTPChildWindowFromPoint function will retrieve an HWND
 * handle for the child window (if any) located directly under the
 * cursor position specified by <i>point</i>.
 * @param hWnd   HWND handle of the parent window to find the child for.
 * @param point  Current cursor position.
 * @return
 * An HWND handle for the child window at <i>point</i>.
 */
_XTP_EXT_CLASS HWND AFXAPI XTPChildWindowFromPoint(HWND hWnd, POINT point);

/**
 * @brief
 * The XTPPathExists function searches a directory for a
 * file or sub-directory whose name matches the specified name.
 * @param lpszFileName  [in] A pointer to a NULL-terminated string that specifies a
 * valid directory or path and file name, which can contain
 * wild card characters (* and ?). If the string ends with a
 * wild card, a period, or a directory name, then the user must
 * have access to the root and all sub-directories on the path.
 * @return
 * TRUE if the file or sub-directory exists, otherwise FALSE.
 */
_XTP_EXT_CLASS BOOL AFXAPI XTPPathExists(LPCTSTR lpszFileName);

/**
 * @brief
 * Creates a view based on a CRuntimeClass object.
 * @param pParentWnd  Pointer to the parent of the view to be created. The parent
 * must be valid.
 * @param pViewClass  Specifies the CRuntimeClass of the new view.
 * @param pDocument   CDocument associated with the view. It can be NULL.
 * @param pContext    Create context for the view. It can be NULL.
 * @param dwStyle     Default style for the view.
 * @param pOwnerWnd   Owner of the view. If NULL, then 'pParentWnd' is used.
 * @param nID         Control ID of the view.
 * @details
 * The XTPCreateView function will create a view based on
 * the CRuntimeClass <i>pViewClass</i>.
 * @return
 * A CWnd* pointer to the newly created view if successful, otherwise NULL.
 * <b>Example:</b>
 * <pre>
 * CView* pView = (CView*)XTPCreateView(this, RUNTIME_CLASS(CMyView));
 * _ASSERTE(pView);
 * </pre>
 */
_XTP_EXT_CLASS CWnd* AFXAPI XTPCreateView(CWnd* pParentWnd, CRuntimeClass* pViewClass,
										  CDocument* pDocument	 = NULL,
										  CCreateContext* pContext = NULL,
										  DWORD dwStyle			   = AFX_WS_DEFAULT_VIEW,
										  CWnd* pOwnerWnd = NULL, UINT nID = AFX_IDW_PANE_FIRST);

/**
 * @brief
 * Call this member function to display a context menu that is
 * compatible with both pro and standard versions.
 * @param pPopup     Pointer to a valid CMenu object.
 * @param nFlags     Specifies a screen-position flag and a mouse-button flag. The
 *                   screen-position flag can be one of the following:
 *                   <code>TPM_CENTERALIGN</code>: Centers the pop-up menu horizontally relative
 *                   to the coordinate specified by x.
 *                   <code>TPM_LEFTALIGN</code>: Positions the pop-up menu so that its left side
 *                   is aligned with the coordinate specified by x.
 *                   <code>TPM_RIGHTALIGN</code>: Positions the pop-up menu so that its right side
 *                   is aligned with the coordinate specified by x.
 *                   The mouse-button flag can be either of the following:
 *                   <code>TPM_LEFTBUTTON</code>: Causes the pop-up menu to track the left mouse
 *                   button.
 *                   <code>TPM_RIGHTBUTTON</code>: Causes the pop-up menu to track the right mouse
 *                   button.
 * @param xPos       Specifies the horizontal position in screen coordinates of the
 *                   pop-up menu. Depending on the value of the nFlags parameter, the
 *                   menu can be left-aligned, right-aligned, or centered relative to
 *                   this position.
 * @param yPos       Specifies the vertical position in screen coordinates of the top
 *                   of the menu on the screen.
 * @param pWnd       Identifies the window that owns the pop-up menu. This window
 *                   receives all WM_COMMAND messages from the menu. In Windows versions
 *                   3.1 and later, the window does not receive WM_COMMAND messages until
 *                   TrackPopupMenu returns. In Windows 3.0, the window receives
 *                   WM_COMMAND messages before TrackPopupMenu returns.
 * @param nIDBitmap  Toolbar resource ID that contains images to be displayed with menu
 *                   commands.
 * @param bNoNotify  TRUE to notify the control.
 * @details
 * A floating pop-up menu can appear anywhere on the screen.
 * @see
 * CXTPCommandBars::TrackPopupMenu
 *
 * <b>Example:</b>
 * The following example demonstrates using XTPContextMenu:
 * <pre>
 * CPoint pt = point;
 * ClientToScreen(&amp;pt);
 *
 * CMenu menu;
 * VERIFY(XTPResourceManager()-\>LoadMenu(&amp;menu, XTP_IDM_POPUP));
 *
 * CMenu* pPopup = menu.GetSubMenu(0);
 * _ASSERTE(pPopup != NULL);
 * CWnd* pWndPopupOwner = this;
 *
 * XTPContextMenu(pPopup, TPM_LEFTALIGN | TPM_RIGHTBUTTON,
 *    pt.x, pt.y, pWndPopupOwner, XTP_IDR_TBAR_OUT);
 * </pre>
 * @return True to display a context menu
 */
_XTP_EXT_CLASS BOOL AFXAPI XTPContextMenu(CMenu* pPopup, UINT nFlags, int xPos, int yPos,
										  CWnd* pWnd, int nIDBitmap, BOOL bNoNotify = TRUE);

/**
 * @brief
 * Call this member function to display a context menu that is
 * compatible with both pro and standard versions.
 * @param pPopup        Pointer to a valid CMenu object.
 * @param nFlags        Specifies a screen-position flag and a mouse-button flag. The
 *                      screen-position flag can be one of the following:
 *                      <code>TPM_CENTERALIGN</code>: Centers the pop-up menu horizontally relative
 *                      to the coordinate specified by x.
 *                      <code>TPM_LEFTALIGN</code>: Positions the pop-up menu so that its left side
 *                      is aligned with the coordinate specified by x.
 *                      <code>TPM_RIGHTALIGN</code>: Positions the pop-up menu so that its right
 * side is aligned with the coordinate specified by x. The mouse-button flag can be either of the
 * following: <code>TPM_LEFTBUTTON</code>: Causes the pop-up menu to track the left mouse button.
 *                      <code>TPM_RIGHTBUTTON</code>: Causes the pop-up menu to track the right
 * mouse button.
 * @param xPos          Specifies the horizontal position in screen coordinates of the
 *                      pop-up menu. Depending on the value of the nFlags parameter, the
 *                      menu can be left-aligned, right-aligned, or centered relative to
 *                      this position.
 * @param yPos          Specifies the vertical position in screen coordinates of the top
 *                      of the menu on the screen.
 * @param pWnd          Identifies the window that owns the pop-up menu. This window
 *                      receives all WM_COMMAND messages from the menu. In Windows versions
 *                      3.1 and later, the window does not receive WM_COMMAND messages until
 *                      TrackPopupMenu returns. In Windows 3.0, the window receives
 *                      WM_COMMAND messages before TrackPopupMenu returns.
 * @param pImageManager Points to a CXTPImageManager object.
 * @param bNoNotify     TRUE to notify the control.
 * @details
 * A floating pop-up menu can appear anywhere on the screen.
 * @see
 * CXTPCommandBars::TrackPopupMenu
 *
 * <b>Example:</b>
 * The following example demonstrates using XTPContextMenu:
 * <pre>
 * CPoint pt = point;
 * ClientToScreen(&amp;pt);
 *
 * CMenu menu;
 * VERIFY(XTPResourceManager()-\>LoadMenu(&amp;menu, XTP_IDM_POPUP));
 *
 * CMenu* pPopup = menu.GetSubMenu(0);
 * _ASSERTE(pPopup != NULL);
 * CWnd* pWndPopupOwner = this;
 *
 * XTPContextMenu(pPopup, TPM_LEFTALIGN | TPM_RIGHTBUTTON,
 *    pt.x, pt.y, pWndPopupOwner, XTP_IDR_TBAR_OUT);
 * </pre>
 * @return True to display a context menu
 */
_XTP_EXT_CLASS BOOL AFXAPI XTPContextMenu(CMenu* pPopup, UINT nFlags, int xPos, int yPos,
										  CWnd* pWnd, CXTPImageManager* pImageManager,
										  BOOL bNoNotify = TRUE);

//////////////////////////////////////////////////////////////////////

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