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

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

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

/**
 * @brief
 * Enumeration used to determine sort type.
 * @details
 * XTPSortType type defines the constants used by the CXTPSortClass
 * to determine what type of sorting to perform.
 * @see
 * CXTPSortClass::Sort
 *
 * @see xtpSortInt, xtpSortString, xtpSortDateTime, xtpSortDecimal>
 */
enum XTPSortType
{
	xtpSortInt = 1,  /**< Sort type integer.   */
	xtpSortString,   /**< Sort type string.    */
	xtpSortDateTime, /**< Sort type date/time. */
	xtpSortDecimal   /**< Sort type decimal.   */
};

/**
 * @brief
 * CXTPSortClass is a standalone class. This class will sort a list control
 * by a column of text, integer, float or date/time type. It could be
 * easily extended for other data types. To use this class, instantiate
 * a CXTPSortClass object, passing in a pointer to the list control as
 * the first argument and the column index as the second argument.
 *
 * <b>Example:</b>
 * The following example demonstrates how to use CXTPSortClass:
 * <pre>
 * CXTPSortClass sortClass(pListCtrl, 0);
 * </pre>
 *
 * Then call the sort method setting ascending as the first argument, either
 * TRUE or FALSE, and the type of sort to perform in the second argument.
 *
 * The following example demonstrates how to use the sortClass Sort member function:
 * <pre>
 * sortClass.Sort(TRUE, xtpSortString);
 * </pre>
 */
class _XTP_EXT_CLASS CXTPSortClass
{
public:
	/**
	 * @brief
	 * Constructs a CXTPSortClass object.
	 * @param pListCtrl  Pointer to a valid CListCtrl object.
	 * @param nCol       Index of the column to be sorted.
	 * @param pfnCompare Address of the application-defined comparison function.
	 * See CListCtrl::SortItems for more details.
	 */
	CXTPSortClass(CListCtrl* pListCtrl, const int nCol, PFNLVCOMPARE pfnCompare = NULL);

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

	/**
	 * @brief
	 * This member function is called to perform the actual sort procedure.
	 * @param bAsc  true to sort ascending.
	 * @param iType The type of sort to perform can be one of the values listed
	 * in the Remarks section.
	 * @details
	 * Sort type can be one of the following:<p/>
	 * <b>xtpSortInt</b>: Sort type int.
	 * <b>xtpSortString</b>: Sort type string.
	 * <b>xtpSortDateTime</b>: Sort type date/time.
	 * <b>xtpSortDecimal</b>: Sort type decimal.
	 * <b>xtpSortCustom</b>: Sort type user-defined.
	 */
	virtual void Sort(bool bAsc, int iType);

	/**
	 * @brief
	 * This callback member function is called to compare two data items during
	 * sorting operations.
	 * @param lParam1    Specifies the item data for the first of the two items
	 * being compared.
	 * @param lParam2    Specifies the item data for the second of the two items
	 * being compared.
	 * @param lParamSort Specifies the application defined value that is passed to the
	 * comparison function.
	 * @return
	 * The comparison function must return a negative value if the first item
	 * should precede the second, a positive value if the first item should
	 * follow the second, or zero if the two items are equivalent.
	 */
	static int CALLBACK Compare(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort);

	/**
	 * @brief
	 * This member function is called by the sort class to remove non-numeric
	 * characters from the specified source string.
	 * @param strSource String to remove non-numeric characters from.
	 * @return
	 * The length of the specified string after non-numeric characters
	 * have been removed.
	 */
	static int AFX_CDECL RemoveNonNumeric(CString& strSource);

	/**
	 * @brief
	 * This member function is called by the application defined comparison
	 * function to perform integer sorting.
	 * @param lpszItem1 NULL-terminated string representing the first int
	 * being compared.
	 * @param lpszItem2 NULL-terminated string representing the second int
	 * being compared.
	 * @param sOrder    Represents the sort order; set to 1 for ascending,
	 * or -1 for descending.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 * @see
	 * SortString, SortDateTime, SortDecimal
	 */
	static int AFX_CDECL SortInt(LPCTSTR lpszItem1, LPCTSTR lpszItem2, const short sOrder);

	/**
	 * @brief
	 * This member function is called by the application defined comparison
	 * function to perform string sorting.
	 * @param lpszItem1 NULL-terminated string representing the first string
	 * being compared.
	 * @param lpszItem2 NULL-terminated string representing the second string
	 * being compared.
	 * @param sOrder    Represents the sort order; set to 1 for ascending,
	 * or -1 for descending.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 * @see
	 * SortInt, SortDateTime, SortDecimal
	 */
	static int AFX_CDECL SortString(LPCTSTR lpszItem1, LPCTSTR lpszItem2, const short sOrder);

	/**
	 * @brief
	 * This member function is called by the application defined comparison
	 * function to perform date/time sorting.
	 * @param lpszItem1 NULL-terminated string representing the first date/time
	 * being compared.
	 * @param lpszItem2 NULL-terminated string representing the second date/time
	 * being compared.
	 * @param sOrder    Represents the sort order; set to 1 for ascending,
	 * or -1 for descending.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 * @see
	 * SortInt, SortString, SortDecimal
	 */
	static int AFX_CDECL SortDateTime(LPCTSTR lpszItem1, LPCTSTR lpszItem2, const short sOrder);

	/**
	 * @brief
	 * This member function is called by the application defined comparison
	 * function to perform decimal sorting.
	 * @param lpszItem1 NULL-terminated string representing the first decimal
	 * being compared.
	 * @param lpszItem2 NULL-terminated string representing the second decimal
	 * being compared.
	 * @param sOrder    Represents the sort order; set to 1 for ascending,
	 * or -1 for descending.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 * @see
	 * SortInt, SortString, SortDateTime
	 */
	static int AFX_CDECL SortDecimal(LPCTSTR lpszItem1, LPCTSTR lpszItem2, const short sOrder);

	/**
	 * @brief
	 * This structure is used by the CXTPSortClass for storing a temporary
	 * item data pointer that contains each list item's name (used for sorting)
	 * and original item data (if any).
	 */
	struct ITEMDATA
	{
		CString strItem;  /**< NULL-terminated string that represents the list item's text. */
		DWORD_PTR dwData; /**< List item's application defined value (if any). */
	};

protected:
	CListCtrl* m_pListCtrl;	/**< Pointer to the CListCtrl object to perform the sort on. */
	PFNLVCOMPARE m_pfnCompare; /**< Address of the application-defined comparison function. See */
							   /**
								* CListCtrl::SortItems for more details.
								*/
};

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