/**
* @file XTPCalendarEvents.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
*
*/
#if !defined(_XTPCALENDAREVENTS_H__)
# define _XTPCALENDAREVENTS_H__
# if _MSC_VER > 1000
# pragma once
# endif // _MSC_VER > 1000
# include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"
class CXTPCalendarEvent;
/**
* @brief
* This class represents a simple array collection of CXTPCalendarEvent
* objects.
*
* @details
* Array indexes always start at position 0.
*
* As with a C array, the access time for an indexed element of this
* array is constant and is independent of the array size.
*
* Methods Add(), SetAt(), and Append() call InternalAddRef() for the
* added event.
* Methods Get(), and Find() do not call InternalAddRef() for the returned
* event.
* Methods RemoveAt(), RemoveBy(), RemoveAll(), and the destructor call
* InternalRelease() for the removed events.
*
* @see CArray overview
* @see CXTPCalendarEvent overview
*/
class _XTP_EXT_CLASS CXTPCalendarEvents : public CXTPCmdTarget
{
/** @cond */
DECLARE_DYNAMIC(CXTPCalendarEvents)
/** @endcond */
public:
/**
* @brief
* Default collection constructor.
*
* @see ~CXTPCalendarEvents()
*/
CXTPCalendarEvents();
/**
* @brief
* Default collection destructor.
*
* @details
* Handles member item deallocation. Decreases reference of all
* stored CXTPCalendarEvent objects.
*
* @see RemoveAll()
*/
virtual ~CXTPCalendarEvents();
/**
* @brief
* This member function is used to add a new event element to the
* end of an array.
*
* @param pNewEvent The event element to add to this array.
* @param bWithAddRef If this parameter is TRUE, then InternalAddRef()
* is called for the pNewEvent, otherwise InternalAddRef()
* is not called. The default value is TRUE.
*
* @details
* Use this method to add the specified event pointer to the end
* of the events collection. Reference to the new object is
* increased or decreased depending on the value of the bWithAddRef parameter.
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents* pList = new CXTPCalendarEvents();
* CXTPCalendarEventPtr ptrEvent1 = new CXTPCalendarEvent()
*
* // Add() will call InernalAddRef()
* pList->Add(ptrEvent1);
*
* // Add() will not call InernalAddRef()
* pList->Add(new CXTPCalendarEvent(), FALSE);
*
* // GetAt() will call InernalAddRef()
* CXTPCalendarEventPtr ptrEvent0 = pList->GetAt(0, TRUE);
*
* // GetAt() will not call InernalAddRef()
* CXTPCalendarEvent* pEvent1 = pList->GetAt(1);
*
* _ASSERTE(2 == pList->GetCount());
*
* //RemoveAll() will call InernalRelease() for all objects
* pList->RemoveAll();
*
* _ASSERTE(0 == pList->GetCount());
*
*
* @see GetAt
* @see RemoveAll
* @see GetCount
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
*/
void Add(CXTPCalendarEvent* pNewEvent, BOOL bWithAddRef = TRUE);
/**
* @brief
* Adds a new events element to the end of an array.
*
* @param pEventsArray The pointer to the collection of event elements
* to add to this array.
*
* @details
* Use this method to add event elements from the specified
* array to the end of the events collection. Reference to the
* new object is increased by default. This depends on the array
* constructor parameter. See array constructor
* CXTPCalendarEvents(BOOL bWithAddRefRelease = TRUE);
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents1;
* CXTPCalendarEventsPtr ptrEvents2 = new CXTPCalendarEvents();
* ...
* ptrEvents2->Append(&arEvents1);
*
*
* @see CXTPCalendarEvents overview
* @see GetAt
* @see RemoveAll
* @see GetCount
* @see constructor CXTPCalendarEvents
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
*/
void Append(CXTPCalendarEvents* pEventsArray);
/**
* @brief
* Call this method to get an event at the specified numeric index.
*
* @param nIndex An integer index that is greater than or equal to 0
* and less than the value returned by GetCount.
* @param bWithAddRef If this parameter is TRUE, the InternalAdRef()
* will be called for the returned object.
* Otherwise it will not be called.
* The default value is FALSE.
*
* @details
* Reference to the returned object is increased or not depending on
* the bWithAddRef parameter.
* Returns the array element at the specified index.
*
* Example:
* See example for CXTPCalendarEvents::Add method.
*
* @return The pointer to the CXTPCalendarEvent element currently at this
* index.
*/
CXTPCalendarEvent* GetAt(int nIndex, BOOL bWithAddRef = FALSE) const;
/**
* @brief
* This member function is used to set a new event element to the
* position specified in the nIndex parameter.
*
* @param nIndex An integer index that is greater than or equal
* to 0 and less than the value returned by
* GetCount.
* @param pEvent The event element to add to this array.
* @param bWithAddRef If this parameter is TRUE, then InternalAddRef()
* is called for the pEvent object,
* otherwise InternalAddRef() is not called.
*
* @details
* Use this method to set the specified event pointer to the
* position specified in the nIndex parameter.
* Reference to the previous object is decreased by default. This
* depends on the array constructor parameter. See the array constructor
* CXTPCalendarEvents(BOOL bWithAddRefRelease = TRUE);
* Reference to the new object is increased or decreased depending
* on the bWithAddRef parameter.
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents* pList = new CXTPCalendarEvents();
* CXTPCalendarEventPtr ptrEvent1 = new CXTPCalendarEvent()
*
* pList->Add(ptrEvent1);
* pList->SetAt(0, new CXTPCalendarEvent(), FALSE);
*
*
* @see CXTPCalendarEvents overview
* @see constructor CXTPCalendarEvents
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
*/
void SetAt(int nIndex, CXTPCalendarEvent* pEvent, BOOL bWithAddRef = TRUE);
/**
* @brief
* Inserts an element at a specified index.
*
* @param nIndex An integer index that is greater than or equal to 0
* and may be greater than the value returned by GetCount.
* @param pEvent Pointer to the event to insert.
* @param bWithAddRef Set this value to TRUE to increment the reference count of the inserted
* object,
* FALSE to insert object without incrementing reference count.
* Default value is TRUE.
*
* @details
* Inserts one element at a specified index in an array. In the process,
* it shifts up (by incrementing the index) the existing element at
* this index, and it shifts up all the elements above it.
*
* @see CXTPCalendarEvents overview
*/
void InsertAt(int nIndex, CXTPCalendarEvent* pEvent, BOOL bWithAddRef = TRUE);
/**
* @brief
* Removes an element of the specified index from this array.
*
* @param nIndex An integer index that is greater than or equal to 0
* and less than the value returned by GetCount.
*
* @details
* Removes the pointer from this array. Reference to the removed
* object is decreased by default.
*
* @see CXTPCalendarEvents overview
*/
void RemoveAt(int nIndex);
/**
* @brief
* This member function is used to obtain the number of
* CXTPCalendarEvent elements in this collection.
*
* @details
* Call this method to retrieve the number of elements in the array.
* Because indexes are zero-based, the size is 1 greater than
* the largest index.
*
* Example:
* See example for CXTPCalendarEvents::Add method.
*
* @return An int that contains the number of items in the collection.
*
* @see CXTPCalendarEvents overview
*/
int GetCount() const;
/**
* @brief
* Set size of the array.
*
* @param nNewSize A new array size (elements count).
* @param nGrowBy Amount of elements to grow array when Add and InsertAt
* methods used. -1 (by default) means using default
* parameter value.
*
* @see GetCount
* @see RemoveAll
*/
void SetSize(int nNewSize, int nGrowBy = -1);
/**
* @brief
* This function is used to remove all of the elements from this array.
*
* @details
* Removes all of the pointers from this array. Reference to
* removed objects are decreased by default.
*
* Example:
* See example for CXTPCalendarEvents::Add method.
*
* @see CXTPCalendarEvents overview
*/
void RemoveAll();
/**
* @brief
* This method is used to find an event using the EventID in this array.
*
* @param pFEvent A pointer to a CXTPCalendarEvent object that
* contains the event object.
*
* @details
* When using dwEventID - This method searches this collection for the
* first match of an event object with event ID
* equal to dwEventID.
* When using pFEvent - This method searches this collection for the first
* match of an event object with identifiers equal to
* identifiers of the pFEvent. If there are no recurrence
* events, then these are Event IDs. For recurrence events,
* then these are RecurrencePatternID, Start/End times,
* or RException_StartTimeOrig/RException_EndTimeOrig.
* For details see implementation CXTPCalendarEvent::IsEqualIDs().
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* CXTPCalendarEvent* pEvent;
* ...
* if (arEvents.Find(pEvent->GetEventID()) < 0) {
* arEvents.Add(pEvent);
* }
*
*
* @return The zero-based index of the first event in the collection
* that matches the requested dwEventID.
* -1 if the event is not found.
*
* @see CXTPCalendarEvents overview
* @see constructor CXTPCalendarEvents
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
*/
int Find(CXTPCalendarEvent* pFEvent) const;
/**
* @brief
* This method is used to find an event using the EventID in this array.
*
* @param dwEventID A DWORD that contains the unique event ID.
*
* @details
* When using dwEventID - This method searches this collection for the
* first match of an event object with event ID
* equal to dwEventID.
* When using pFEvent - This method searches this collection for the first
* match of an event object with identifiers equal to
* identifiers of the pFEvent. If there are no recurrence
* events, then these are Event IDs. For recurrence events,
* then these are RecurrencePatternID, Start/End times,
* or RException_StartTimeOrig/RException_EndTimeOrig.
* For details see implementation CXTPCalendarEvent::IsEqualIDs().
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* CXTPCalendarEvent* pEvent;
* ...
* if (arEvents.Find(pEvent->GetEventID()) < 0) {
* arEvents.Add(pEvent);
* }
*
*
* @return The zero-based index of the first event in the collection
* that matches the requested dwEventID.
* -1 if the event is not found.
*
* @see CXTPCalendarEvents overview
* @see constructor CXTPCalendarEvents
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
*/
int Find(DWORD dwEventID) const;
/**
* @brief
* This member function is used to find an event using the EventID
* in this array.
*
* @param dwEventID A DWORD that contains the unique event ID.
*
* @details
* When using dwEventID -
* This method searches this collection for the first match of
* a event object with event ID equal to dwEventID.
* Reference to the returned object is not increased.
* When using pFEvent -
* This method searches this collection for the first match of
* an event object with identifiers equal to identifiers of
* the pFEvent. In the case of no recurrence events these
* are EventIDs. In the case of recurrence events these are
* RecurrencePatternIDs, Start/End times or
* RException_StartTimeOrig/RException_EndTimeOrig.
* For details see implementation CXTPCalendarEvent::IsEqualIDs()
* Reference to the returned object is not increased by default.
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* CXTPCalendarEvent* pEvent;
* ...
* CXTPCalendarEvent* pEvent2;
* pEvent2 = arEvents.Find(pEvent->GetEventID());
* if (pEvent2) {
* pEvent2.Update(pEvent);
* }
*
*
* @return The pointer to the first event in the collection
* that matches the requested dwEventID;
* NULL if the event is not found.
*
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
*/
CXTPCalendarEvent* FindEvent(DWORD dwEventID) const;
/**
* @brief
* This member function is used to find an event using the EventID
* in this array.
*
* @param pFEvent A CXTPCalendarEvent pointer that contains the
* event object to compare.
*
* @details
* When using dwEventID -
* This method searches this collection for the first match of
* a event object with event ID equal to dwEventID.
* Reference to the returned object is not increased.
* When using pFEvent -
* This method searches this collection for the first match of
* an event object with identifiers equal to identifiers of
* the pFEvent. In the case of no recurrence events these
* are EventIDs. In the case of recurrence events these are
* RecurrencePatternIDs, Start/End times or
* RException_StartTimeOrig/RException_EndTimeOrig.
* For details see implementation CXTPCalendarEvent::IsEqualIDs()
* Reference to the returned object is not increased by default.
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* CXTPCalendarEvent* pEvent;
* ...
* CXTPCalendarEvent* pEvent2;
* pEvent2 = arEvents.Find(pEvent->GetEventID());
* if (pEvent2) {
* pEvent2.Update(pEvent);
* }
*
*
* @return The pointer to the first event in the collection
* that matches the requested dwEventID;
* NULL if the event is not found.
*
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
*/
CXTPCalendarEvent* FindEvent(CXTPCalendarEvent* pFEvent) const;
/**
* @brief
* This member function is used to find and remove an event using
* the EventID in this array.
*
* @param dwEventID A DWORD containing a unique event ID.
*
* @details
* This method searches this collection for the first match of
* an event object with the event ID equal to dwEventID and removes
* the object from the collection.
*
* Example:
*
* // CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* DWORD dwEventIDToRemove;
* ...
* if (arEvents.RemoveByID(dwEventIDToRemove) < 0) {
* ...
* }
*
*
* @return TRUE if the event is found and removed.
* FALSE if the event is not found.
*
* @see CXTPCalendarEvents overview
* @see constructor CXTPCalendarEvents
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
*/
BOOL RemoveByID(DWORD dwEventID);
/**
* @brief
* Clone events in the collection.
*
* @details
* This function pointer is used to replace events objects to their clones.
* If there is not enough memory to clone some events, they are
* removed from the collection.
*
* @see CXTPCalendarEvent::CloneEvent()
*/
void CloneEvents();
/**
* @brief
* Define a function pointer for comparing events.
*
* @param ppEv1 Pointer to calender event pointer(first event).
* @param ppEv2 Pointer to calender event pointer(second event).
*
* @details
* This function pointer is used in the Sort method.
*
* @see Sort method
* @see CompareEvents_ForView function
* @see CompareEvents_ByID function
*/
typedef int(AFX_CDECL* T_CompareFunc)(const CXTPCalendarEvent** ppEv1,
const CXTPCalendarEvent** ppEv2);
/**
* @brief
* This member function is used to sort events in this array.
*
* @param pCompareFunc A T_CompareFunc function pointer that is used
* to compare events.
*
* @details
* This method sorts events in this collection using the specified
* compare events function. The QuickSort algorithm is used.
*
* Example:
*
* CXTPCalendarEvents - derived class
* CXTPCalendarEvents arEvents;
* ...
* arEvents.Sort(CompareEvents_ForView);
* ...
*
*
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvents overview
* @see CXTPCalendarEvent overview
* @see CXTPCalendarEvent overview
* @see CompareEvents_ForView function
* @see CompareEvents_ByID function
* @see qsort() function in the stdlib.h
*/
void Sort(T_CompareFunc pCompareFunc);
/**
* @brief
* This member function is used to compare specified events so that
* the events are displayed properly in the event's views.
*
* @param ppEv1 Pointer to the first event pointer.
* @param ppEv2 Pointer to the second event pointer.
*
* @details
* This function is used as a parameter for the Sort method to sort
* events in the order needed to display the events in the event's views.
*
* Example:
* See example for CXTPCalendarEvents::Sort method.
* @return 0 if Event1 == Event2; 1 if Event1 > Event2; -1 if Event1 \< Event2.
*/
static int AFX_CDECL CompareEvents_ForView(const CXTPCalendarEvent** ppEv1,
const CXTPCalendarEvent** ppEv2);
/**
* @brief
* This member function is used to compare specified events so that
* the events are displayed properly in the event's views.
* An extra function for sort.
*
* @param ppEv1 Pointer to the first event pointer.
* @param ppEv2 Pointer to the second event pointer.
*
* @details
* This function is used as a parameter for the Sort method to sort
* events in the order needed to display the events in the event's views.
*
* Example:
* See example for CXTPCalendarEvents::Sort method.
* @return 0 if Event1 == Event2; 1 if Event1 > Event2; -1 if Event1 \< Event2.
*/
static int AFX_CDECL CompareEvents_ForViewByStart(const CXTPCalendarEvent** ppEv1,
const CXTPCalendarEvent** ppEv2);
/**
* @brief
* This member function is used to compare specified events by
* the event's IDs.
*
* @param ppEv1 Pointer to the first event pointer.
* @param ppEv2 Pointer to the second event pointer.
*
* @details
* This function is used as a parameter for the Sort method to sort
* events using EventIDs in ascending order. This is useful for
* performing a fast search for an event ID.
*
* Example:
* See example for CXTPCalendarEvents::Sort method.
* @return 0 if Event1 == Event2; 1 if Event1 > Event2; -1 if Event1 \< Event2.
* @see method CXTPCalendarEvents::Sort overview
* @see CompareEvents_ForView function
*/
static int AFX_CDECL CompareEvents_ByID(const CXTPCalendarEvent** ppEv1,
const CXTPCalendarEvent** ppEv2);
protected:
CArray m_arEvents; /**< An internal storage for
CXTPCalendarEvent pointers.*/
# ifdef _XTP_ACTIVEX
DECLARE_DISPATCH_MAP()
DECLARE_INTERFACE_MAP()
DECLARE_OLETYPELIB_EX(CXTPCalendarEvents);
DECLARE_ENUM_VARIANT(CXTPCalendarEvents)
LPDISPATCH OleGetItem(long nIndex);
int OleGetItemCount();
void OleAdd(LPDISPATCH pEventDisp);
void OleRemove(long nIndex);
# endif
};
/////////////////////////////////////////////////////////////////////////////
AFX_INLINE int CXTPCalendarEvents::GetCount() const
{
return (int)m_arEvents.GetSize();
}
AFX_INLINE void CXTPCalendarEvents::SetSize(int nNewSize, int nGrowBy)
{
m_arEvents.SetSize(nNewSize, nGrowBy);
}
AFX_INLINE BOOL CXTPCalendarEvents::RemoveByID(DWORD dwEventID)
{
int nFIndex = Find(dwEventID);
if (nFIndex >= 0)
{
RemoveAt(nFIndex);
}
return (nFIndex >= 0);
}
# include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif // !defined(_XTPCALENDAREVENTS_H__)