/** * @file XTPTaskPanelGroup.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(__XTPTASKPANELGROUP_H__) # define __XTPTASKPANELGROUP_H__ /** @endcond */ # if _MSC_VER > 1000 # pragma once # endif // _MSC_VER > 1000 # include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h" class CXTPTaskPanel; class CXTPTaskPanelItems; class CXTPTaskPanelItem; class CXTPTaskPanelPaintManager; class CXTPTaskPanelGroupItem; class CXTPTaskPanelGroupItems; /** * @brief * CXTPTaskPanelGroup is used in a Task Panel control to represent a group. */ class _XTP_EXT_CLASS CXTPTaskPanelGroup : public CXTPTaskPanelItem { /** @cond */ DECLARE_SERIAL(CXTPTaskPanelGroup) /** @endcond */ public: /** * @brief * Constructs a CXTPTaskPanelGroup object. * @param pPanel Pointer to the parent Task Panel. */ CXTPTaskPanelGroup(CXTPTaskPanel* pPanel = NULL); /** * @brief * Destroys a CXTPTaskPanelGroup object, handles cleanup and deallocation. */ virtual ~CXTPTaskPanelGroup(); public: /** * @brief * Gets the collection of group items. * @return * A pointer to the collection of group items. */ CXTPTaskPanelItems* GetItems() const; /** * @brief * Retrieves the group item at a specified index in * the collection of group items. * @param nIndex Zero-based index of the group item to retrieve. * @return * A pointer to the group item at the specified index in * the collection of group items. */ CXTPTaskPanelGroupItem* GetAt(int nIndex) const; /** * @brief * Retrieves the group item with a specified identifier. * @param nID Identifier of the item to retrieve. * @return * A pointer to the group item with the specified identifier if successful, * otherwise NULL. */ CXTPTaskPanelGroupItem* FindItem(int nID) const; /** * @brief * Adds a link item to the group. * @param nID Identifier of the link item to be added. * @param nImage Image index in the Task Panel image list. * @return * A pointer to the newly added link item. */ CXTPTaskPanelGroupItem* AddLinkItem(UINT nID, int nImage = -1); /** * @brief * Adds a link item to the group. * @param nID Identifier of the link item to be added. * @param lpCaption Caption of the item. * @param lpTooltip Tooltip of the item. * @param nImage Image index in the Task Panel image list. * @return * A pointer to the newly added link item. */ CXTPTaskPanelGroupItem* AddLinkItem(UINT nID, LPCTSTR lpCaption, LPCTSTR lpTooltip = NULL, int nImage = -1); /** * @brief * Adds a text item to the group. * @param strText Text of the item. * @return * A pointer to the newly added text item. */ CXTPTaskPanelGroupItem* AddTextItem(LPCTSTR strText); /** * @brief * Adds a control item to the group. * @param hWnd Window handle of the item. * @return * A pointer to the newly added control item. */ CXTPTaskPanelGroupItem* AddControlItem(HWND hWnd); /** * @brief * Determines which group item, if any, is at a specified point. * @param pt Point to be tested. * @param lpRect Pointer to a CRect object to receive the bounding rectangle of the item. * Can be NULL if the bounding rectangle does not need to be retrieved. * @return * A pointer to the group item at the specified point, if any, otherwise NULL. */ CXTPTaskPanelGroupItem* HitTest(CPoint pt, CRect* lpRect = 0) const; /** * @brief * This method is called when the group is repositioned. * @param rc New position of the group. * @param bRecalcOnly TRUE to recalculate without repositioning. * @return * The target location of the group. * @details * Groups must be repositioned during animation. This method will * retrieve the target location of the group. * @details * CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, IsDirty, OnAnimate */ CRect OnReposition(CRect rc, BOOL bRecalcOnly = TRUE); /** * @brief * This method is called when an animation step is executed. * @param nStep Animation step that was executed. * @details * CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, IsDirty, OnReposition */ void OnAnimate(int nStep); /** * @brief * This method is called to draw the group. * @param pDC Pointer to the client device context. * @details * OnPaint calls CXTPTaskPanelPaintManager::DrawGroupCaption and * CXTPTaskPanelPaintManager::DrawGroupClient. */ void OnPaint(CDC* pDC); /** * @brief * Gets the rectangle of the caption. * @return * The rectangle of the caption. */ CRect GetCaptionRect() const; /** * @brief * Gets the rectangle of the client. * @return * The rectangle of the client. */ CRect GetClientRect() const; /** * @brief * Gets the target rectangle of the client. * @return * The target rectangle of the client. */ CRect GetTargetClientRect() const; /** * @brief * Gets the target rectangle of the caption. * @return * The target rectangle of the caption. */ CRect GetTargetCaptionRect() const; /** * @brief * Specifies if the group should be special. * @param bSpecial TRUE to set the group to special, FALSE otherwise. * @details * If a group is special, then it will be displayed in a different * color than normal groups to draw the user's attention to that group. * Setting a group to special is an excellent way to show the user * the "default" or important items. */ void SetSpecialGroup(BOOL bSpecial = TRUE); /** * @brief * Determines if the group is special. * @return * TRUE if the group is special, otherwise FALSE. * @details * If a group is special, then it will be displayed in a different * color than normal groups to draw the user's attention to that group. * Setting a group to special is an excellent way to show the user * the "default" or important items. */ BOOL IsSpecialGroup() const; /** * @brief * Sets the expandable state for the group. * @param bExpandable TRUE to set the group to expandable, FALSE otherwise. */ void SetExpandable(BOOL bExpandable); /** * @brief * Gets the expandable state of the group. * @return * TRUE if the group is expandable, otherwise FALSE. */ BOOL IsExpandable() const; /** * @brief * Shows/hides the caption of the group. * @param bShow TRUE to show the caption of the group, * FALSE to hide the caption of the group. */ void ShowCaption(BOOL bShow); /** * @brief * Determines if the caption of the group is shown/hidden. * @return * TRUE if the caption of the group is shown, * FALSE if the caption of the group is hidden. * @see * ShowCaption */ BOOL IsCaptionVisible() const; /** * @brief * Determines if the group is expanded/collapsed. * @return * TRUE if the group is expanded, FALSE if the group is collapsed. * @see * SetExpanded, CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, IsDirty, IsExpanding */ BOOL IsExpanded() const; /** * @brief * Determines if the group is expanding. * @return * TRUE is group is expanding, otherwise FALSE. * @see * SetExpanded, CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, IsDirty, IsExpanded */ BOOL IsExpanding() const; /** * @brief * Gets the client height of the expanded group. * @return * The client height of the expanded group. */ int GetExpandedClientHeight() const; /** * @brief * Expands/collapses the group. * @param bExpanded TRUE to expand the group, FALSE to collapse the group. * @see * CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, IsDirty, IsExpanding, IsExpanded */ void SetExpanded(BOOL bExpanded); /** * @brief * Determines if the group position is "dirty" (i.e. moving during animation). * @return * TRUE if the group position is "dirty", otherwise FALSE. * @see * CXTPTaskPanel::AnimateGroups, CXTPTaskPanel::SetAnimation, * CXTPTaskPanel::GetAnimation, OnAnimate, m_rcGroupTarget, m_rcGroupCurrent */ BOOL IsDirty() const; /** * @brief * Gets the outer margins of the group. * @return * A reference to the outer margins of the group. */ CRect& GetOuterMargins(); /** * @brief * Gets the inner margins of the group. * @return * A reference to the inner margins of the group. */ CRect& GetInnerMargins(); /** * @brief * Gets the minimum client height of the group. * @return * The minimum client height of the group. */ int GetMinimumClientHeight() const; /** * @brief * Sets the minimum client height for the group. * @param nMinClientHeight Minimum client height to be set. */ void SetMinimumClientHeight(int nMinClientHeight); /** * @brief * Determines if the group can accept focus. * @return * TRUE if the group can accept focus, otherwise FALSE. */ BOOL IsAcceptFocus() const; /** * @brief * Sets the client bitmap for the group. * @param nID Bitmap resource identifier. * @param clrTransparent Color in the bitmap to make transparent. * @param nBackgroundAlignment Alignment of the bitmap. * @details * The bitmap will always be in the lower right corner * of the group and will not move. * The bitmap is drawn in the group by OnFillClient. * @see * OnFillClient */ void SetClientBitmap(UINT nID, COLORREF clrTransparent, int nBackgroundAlignment = DT_RIGHT | DT_BOTTOM); /** * @brief * This method is called when the Task Panel group client face is drawn. * @param pDC Pointer to a valid device context. * @param rc CRect object specifying the size of the area. * @details * This method is called by CXTPTaskPanelPaintManager::DrawGroupClientFace * to fill the group client face. * * This method determines if a bitmap should be drawn in the lower right * corner of the group and will draw the bitmap if a bitmap was added. * A bitmap can be added with SetClientBitmap. * @see * SetClientBitmap */ virtual void OnFillClient(CDC* pDC, CRect rc); /** * @brief * Gets the item layout of the group. * @return * The item layout of the group; one of the values * defined by the XTPTaskPanelItemLayout enumeration. * @details * Item layouts include text only, image only, image and text, and * image with text below the image. */ XTPTaskPanelItemLayout GetItemLayout() const; /** * @brief * Sets the item layout for the group. * @param itemLayout Item layout to be set; must be one of the values * defined by the XTPTaskPanelItemLayout enumeration. * @details * Item layouts include text only, image only, image and text, and * image with text below the image. * * This method only applies to this group. */ void SetItemLayout(XTPTaskPanelItemLayout itemLayout); /** * @brief * Selects a specified group item. * @param pItem Pointer to the group item to be selected. * @details * Selected items will appear either "pressed" or "highlighted" * depending on the selected theme. * * Multiple items can have focus. * See CXTPTaskPanel::SetSelectItemOnFocus for details. * @see * XTPTaskPanelGroupItem::IsItemSelected, XTPTaskPanelGroupItem::SetItemSelected, * CXTPTaskPanel::SetSelectItemOnFocus */ void SetSelectedItem(CXTPTaskPanelGroupItem* pItem); /** * @brief * Determines if the item currently being dragged over the group * is a child item of the group. * @return * TRUE if the item is a child item of the group, otherwise FALSE. * @details * This method is used in the paint manager to determine if an inverted * rectangle must be drawn for the item. An inverted rectangle is only * drawn when the theme of the Task Panel control is Visual Studio 2003. * @see * XTPTaskPanelPaintTheme, CXTPTaskPanelToolboxTheme::DrawGroupCaption */ BOOL IsChildItemDragOver() const; /** * @brief * Gets the number of items in the group. * @return * The number of items in the group. */ int GetItemCount() const; /** * @brief * Determines if a specified group scroll button is enabled/disabled. * @param bScrollButtonUp TRUE to check if the group Up scroll button is enabled, * FALSE to check if the group Down scroll button is enabled. * @return * TRUE if the specified group scroll button is enabled, * FALSE if the specified group scroll button is disabled. * @details * CXTPTaskPanel::UpdateScrollButtons uses this method to * update the state of the scroll buttons. */ BOOL IsScrollButtonEnabled(BOOL bScrollButtonUp) const; /** * @brief * Gets the scroll offset of the first visible item in the group. * @return * The scroll offset of the first visible item in the group. * @details * The scroll offset is the height, in pixels, that has been scrolled. * @see * Scroll, GetOffsetItem, GetItemCount, GetItemsInRow */ int GetScrollOffsetPos() const; /** * @brief * Sets the index for the first visible item in the group. * @param nScrollOffset Index to be set. * @param bUpdateScrollButtons TRUE to update scroll buttons, otherwise FALSE. */ void SetOffsetItem(int nScrollOffset, BOOL bUpdateScrollButtons = TRUE); /** * @brief * Determines if a specified item is visible in the group. * @param pItem Pointer to the group item to test. * @param bAllowPart TRUE to allow the item to be partially visible, FALSE otherwise. * @return * TRUE if the specified item is visible in the group, otherwise FALSE. */ BOOL IsItemVisible(CXTPTaskPanelGroupItem* pItem, BOOL bAllowPart) const; /** * @brief * Gets the index of the first visible item in the group. * @return * The index of the first visible item in the group. * @see * GetScrollOffsetPos, Scroll, GetItemCount, GetItemsInRow */ int GetOffsetItem() const; /** * @brief * Scrolls to the item at a specified scroll offset in the group when * the group has scroll buttons. * @param nDelta Offset of the item to be scrolled to. * @details * The scroll offset begins at zero and remains at zero until * the view of the group is too small to display all items. * * If the group is scrolled, then the offset will increment by one * for each item that is scrolled from the top unless there is more * than one item in a row. If there is more than one item in a row, * then the offset will increment by GetItemsInRow instead. * * GetItemCount and GetOffsetItem can be used to determine * which item to scroll to. * * Setting nDelta to 0 will scroll to the top of the group. * @see * GetScrollOffsetPos, GetOffsetItem, GetItemCount, GetItemsInRow */ void Scroll(int nDelta); /** * @brief * Ensures that a specified group item is visible in the Task Panel. * @param pItem Pointer to the group item to ensure the visibility of. * @param bUpdateScrollButtons TRUE to update scroll buttons, otherwise FALSE. * @details * This method will scroll the task panel and the group that * the item is within until the item is visible. */ void EnsureVisible(CXTPTaskPanelGroupItem* pItem, BOOL bUpdateScrollButtons = TRUE); /** * @brief * Gets the number of group items per row in the group. * @return * The number of group items per row in the group. * @see * If the Task Panel behaviour is set to xtpTaskPanelBehaviourExplorer or * xtpTaskPanelBehaviourList, then the number of group items per row * in the group will always be one unless the Task Panel layout * is set to xtpTaskItemLayoutImages. * * If the Task Panel behavior is set to xtpTaskPanelBehaviourToolbox, * then there can be multiple group items per row in the group. * @see * XTPTaskPanelBehaviour, XTPTaskPanelItemLayout, Scroll */ int GetItemsInRow() const; /** * @brief * Reads/writes this object from/to an archive. * @param pPX Pointer to a CXTPPropExchange object to serialize to/from. */ virtual void DoPropExchange(CXTPPropExchange* pPX); /** * @brief * Gets the rectangle of the "tooltip zone". * @return * The rectangle of the "tooltip zone". * @details * The "tooltip zone" is the area where the tooltip will be displayed * when the mouse is positioned over the group caption. * @see * CXTPTaskPanelGroupItem::GetHitTestRect */ virtual CRect GetHitTestRect() const; /** * @brief * Gets the rectangle of the "drawing zone". * @return * The rectangle of the "drawing zone". * @see * CXTPTaskPanelGroupItem::GetHitTestRect */ virtual CRect GetInvalidateRect() const; /** * @brief * Gets the height of the group caption. * @return * The height of the group caption. */ int GetCaptionHeight() const; /** * @brief * Gets the size of group item icons. * @return * The size of group item icons. * @see * SetItemIconSize */ CSize GetItemIconSize() const; /** * @brief * Sets the size for group item icons. * @param szItemIcon Size to be set. * @see * GetItemIconSize */ void SetIconSize(CSize szItemIcon); /** * @brief * Retrieves the index of the next/previous visible item in this group * from a specified index. * @param nIndex Index to begin search. * @param nDirection Direction to search in (+1 for next, -1 for previous). * @return * A pointer to the next/previous visible item in this group * from the specified index if successful, otherwise NULL. */ CXTPTaskPanelGroupItem* GetNextVisibleItem(int nIndex, int nDirection = +1) const; protected: /** * @brief * Calculates the height, in pixels, of the available area that * can be used to draw the active group if the behaviour of * the Task Panel is not set to Windows Explorer. * @return * The height, in pixels, of the available area that * can be used to draw the active group. * @see * OnCalcClientHeight */ int CalcInsideHeight(); /** * @brief * This method is called to calculate the group client area * required to display all items. * @param pDC Pointer to a valid device context. * @param rc Bounding rectangle of the Task Panel group. * @see * CalcInsideHeight */ virtual void OnCalcClientHeight(CDC* pDC, CRect rc); /** * @brief * This method is called when the group is removed from * the parent groups collection. */ void OnRemoved(); protected: /** @cond */ // System accessibility Support virtual HRESULT GetAccessibleState(VARIANT varChild, VARIANT* pvarState); virtual HRESULT GetAccessibleDefaultAction(VARIANT varChild, BSTR* pszDefaultAction); virtual HRESULT AccessibleDoDefaultAction(VARIANT varChild); /** @endcond */ private: void RepositionAutoHeightControls(int nHeightOffset); void RepositionScrollOffset(); protected: CRect m_rcGroupTarget; /**< Target rectangle of the group during animation. */ CRect m_rcGroupCurrent; /**< Current rectangle of the group during animation. */ CRect m_rcMarginsOuter; /**< Outer margins. */ CRect m_rcMarginsInner; /**< Inner margins. */ int m_nCaptionHeight; /**< Height of the caption. */ BOOL m_bSpecial; /**< TRUE if the group is special. */ BOOL m_bExpandable; /**< TRUE if the group is expandable. */ BOOL m_bExpanded; /**< TRUE if the group is expanded. */ BOOL m_bExpanding; /**< TRUE if the group is expanding. */ int m_nExpandedClientHeight; /**< Expanded client height. */ int m_nMinClientHeight; /**< Minimum client height. */ BOOL m_bCaptionVisible; /**< TRUE if the caption is visible. */ int m_nScrollOffset; /**< Scroll offset of the group. Only applies if the task panel behavior is set to xtpTaskPanelBehaviourList or xtpTaskPanelBehaviourToolbox. */ int m_nItemsInRow; /**< Number of group items in a row when using the xtpTaskPanelBehaviourToolbox XTPTaskPanelBehaviour. For all other behaviors, it will only be 1 unless the layout is set to to xtpTaskPanelBehaviourExplorer or xtpTaskPanelBehaviourList. */ CSize m_szItemIcon; /**< Size of group item icons. */ CXTPTaskPanelGroupItems* m_pItems; /**< Collection of items. */ XTPTaskPanelItemLayout m_itemLayout; /**< Currently set layout for the group. */ int m_nBackgroundImage; /**< Index of the background image for the group within the image manager. */ int m_nBackgroundAlignemnt; /**< Alignment of the background image for the group. */ private: # ifdef _XTP_ACTIVEX /** @cond */ DECLARE_DISPATCH_MAP() DECLARE_INTERFACE_MAP() DECLARE_OLETYPELIB_EX(CXTPTaskPanelGroup) enum { dispidItems = 10L, dispidSpecial = 11L, dispidCaptionVisible = 12L, dispidExpandable = 13L, dispidExpanded = 14L, }; afx_msg LPDISPATCH OleGetItems(); afx_msg void OleSetIconSize(long cx, long cy); afx_msg void OleSetBackgroundImage(int ImageIndex, int Alignment); /** @endcond */ # endif friend class CXTPTaskPanel; }; AFX_INLINE CXTPTaskPanelItems* CXTPTaskPanelGroup::GetItems() const { _ASSERTE(m_pItems); return (CXTPTaskPanelItems*)m_pItems; } AFX_INLINE int CXTPTaskPanelGroup::GetExpandedClientHeight() const { return m_nExpandedClientHeight; } AFX_INLINE CRect& CXTPTaskPanelGroup::GetOuterMargins() { return m_rcMarginsOuter; } AFX_INLINE CRect& CXTPTaskPanelGroup::GetInnerMargins() { return m_rcMarginsInner; } AFX_INLINE int CXTPTaskPanelGroup::GetItemsInRow() const { return m_nItemsInRow; } AFX_INLINE int CXTPTaskPanelGroup::GetCaptionHeight() const { return m_nCaptionHeight; } # include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h" /** @cond */ #endif // !defined(__XTPTASKPANELGROUP_H__) /** @endcond */