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

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

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

/**
 * @brief
 * CXTPIconHandle is a standalone helper class.  It is used to
 * automatically destroy dynamically created hIcon handles.
 */
class _XTP_EXT_CLASS CXTPIconHandle
{
public:
	/**
	 * @brief
	 * Constructs a CXTPIconHandle object.
	 */
	CXTPIconHandle();

	/**
	 * @brief
	 * Constructs a CXTPIconHandle object.
	 * @param hIcon Handle to a dynamically created icon.
	 */
	CXTPIconHandle(HICON hIcon);

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

public:
	/**
	 * @brief
	 * This operator is used to retrieve a handle to the icon
	 * associated with the CXTPIconHandle object.
	 * @return
	 * An HICON handle to the icon.
	 */
	operator HICON() const;

	/**
	 * @brief
	 * This operator is used to initialize the icon associated with
	 * the CXTPIconHandle object.
	 * @param hIcon Handle to a dynamically created icon.
	 * @return
	 * A reference to a CXTPIconHandle object.
	 */
	CXTPIconHandle& operator=(HICON hIcon);

	/**
	 * @brief
	 * This member function gets the extent of an icon.
	 * @return
	 * A CSize object.
	 */
	CSize GetExtent() const;

	/**
	 * @brief
	 * This member function gets the extent of an icon.
	 * @param hIcon Icon handle whose dimensions are to be retrieved.
	 * @return
	 * A CSize object.
	 */
	static CSize AFX_CDECL GetExtent(HICON hIcon);

	/**
	 * @brief
	 * This member function scales an icon to fit into a rectangle.
	 * The width and height ratio is retained as much as possible.
	 * The caller assumes ownership of the returned icon handle.
	 * @param desiredExtent Desired icon extent.
	 * @return
	 * An icon handle.
	 */
	HICON ScaleToFit(CSize desiredExtent) const;

	/**
	 * @brief
	 * This member function scales an icon to fit into a rectangle.
	 * The width and height ratio is retained as much as possible.
	 * The caller assumes ownership of the returned icon handle.
	 * @param hIcon         Icon to be fitted.
	 * @param desiredExtent Desired icon extent.
	 * @return
	 * An icon handle.
	 */
	static HICON AFX_CDECL ScaleToFit(HICON hIcon, CSize desiredExtent);

protected:
	HICON m_hIcon; /**< Handle to a dynamically created icon. */
};
/** @cond */
AFX_INLINE CXTPIconHandle::operator HICON() const
{
	return m_hIcon;
}
/** @endcond */
/**
 * @brief
 * CXTPSplitPath conveniently wraps the _splitpath API for easier
 * access to path components such as file name and extension.
 */
class _XTP_EXT_CLASS CXTPSplitPath
{
public:
	/**
	 * @brief
	 * Constructs a CXTPSplitPath object and breaks a path into its
	 * four components.
	 * @param lpszPathBuffer A NULL-terminated string that represents the
	 * path to split.
	 */
	CXTPSplitPath(LPCTSTR lpszPathBuffer = NULL);

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

public:
	/**
	 * @brief
	 * Call SplitPath to break a path into its four components.
	 * @param lpszPathBuffer A NULL-terminated string that represents the
	 * path to split.
	 */
	void SplitPath(LPCTSTR lpszPathBuffer);

	/**
	 * @brief
	 * Call GetDrive() to retrieve the drive letter, followed by a
	 * colon (:) for the path split.
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetDrive() const;

	/**
	 * @brief
	 * Call GetDir() to retrieve the directory path, including
	 * trailing slash. Forward slashes (/), backslashes (\\), or
	 * both may be used.
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetDir() const;

	/**
	 * @brief
	 * Call GetFName() to retrieve the base filename without the
	 * filename extension.
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetFName() const;

	/**
	 * @brief
	 * Call GetExt() to retrieve the filename extension, including
	 * the leading period (.)
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetExt() const;

	/**
	 * @brief
	 * Call GetFullPath() to retrieve the full path that was split.
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetFullPath() const;

	/**
	 * @brief
	 * Call GetFullName() to retrieve the filename plus the filename
	 * extension only for the path that was split.
	 * @return
	 * A NULL-terminated string.
	 */
	CString GetFullName() const;

protected:
	TCHAR m_szDrive[_MAX_DRIVE]; /**< Optional drive letter, followed by a colon (:). */
	TCHAR m_szDir[_MAX_DIR]; /**< Optional directory path, including trailing slash. Forward slashes
								(/), backslashes (\\), or both may be used. */
	TCHAR m_szFName[_MAX_FNAME]; /**< Base filename (no extension). */
	TCHAR m_szExt[_MAX_EXT];	 /**< Optional filename extension, including leading period (.). */
};

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

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