Класс CMFCRibbonCategory

Класс CMFCRibbonCategory реализует вкладку ленты, содержащую группу панелей ленты.

class CMFCRibbonCategory : public CObject

Как правило, вы создаете категорию ленты косвенно путем вызова CMFCRibbonBar::AddCategory, который возвращает указатель на только что созданную категорию ленты. Добавьте панели в категорию, вызвав CMFCRibbonCategory::AddPanel.

Класс CMFCRibbonTab рисует категории ленты. Он является производным от класса CMFCRibbonBaseElement.

В следующем примере показано, как создать категорию ленты и добавить в нее панель.

// Create a new ribbon category and get a pointer to it`
CMFCRibbonCategory* pCategory = m_wndRibbonBar.AddCategory
    (_T("&Write"),           // Category name
    IDB_WRITE,               // Category small images (16 x 16)
    IDB_WRITE_LARGE);        // Category large images (32 x 32)

// Add a panel to the new category
CMFCRibbonPanel* pPanel = pCategory->AddPanel (
    _T("Clipboard"),                // Panel name
    m_PanelIcons.ExtractIcon (0));  // Panel icon

На следующей схеме показан рисунок категории "Главная" из примера приложения RibbonApp.

CObject

CMFCRibbonCategory

Заголовок: afxribboncategory.h

Добавляет указанный элемент ленты в массив элементов ленты, отображаемых в диалоговом окне настройки.

void AddHidden(CMFCRibbonBaseElement* pElem);

pElem
[in] Указатель на элемент ленты.

Элементы ленты в диалоговом окне настройки — это команды, которые можно добавить на панель быстрого доступа.

Создает панель ленты для категории ленты.

CMFCRibbonPanel* AddPanel(
    LPCTSTR lpszPanelName,
    HICON hIcon = 0,
    CRuntimeClass* pRTI = NULL);

lpszPanelName
[in] Указатель на имя новой панели ленты.

hIcon
[in] Обработайте значок по умолчанию для новой панели ленты.

pRTI
[in] Указатель на сведения о классе среды выполнения для настраиваемой панели ленты.

Указатель на новую панель ленты, если метод выполнен успешно; В противном случае значение NULL, если панель не создана.

Если вы хотите создать настраиваемую панель ленты, необходимо указать сведения о классе среды выполнения в pRTI. Класс настраиваемой CMFCRibbonPanel панели ленты должен быть производным от класса.

Значок по умолчанию для панели ленты отображается, если недостаточно места для отображения элементов ленты.

В следующем примере показано, как использовать AddPanel метод в CMFCRibbonCategory классе.

// Create "Favorites" panel:
strTemp.LoadString(IDS_RIBBON_FAVORITES);
// CMFCRibbonCategory* pCategoryCustom
CMFCRibbonPanel *pPanelFavorites = pCategoryCustom->AddPanel(strTemp,
                                                             m_PanelImages.ExtractIcon(15));

Создает и инициализирует объект CMFCRibbonCategory .

CMFCRibbonCategory(
    CMFCRibbonBar* pParenrRibbonBar,
    LPCTSTR lpszName,
    UINT uiSmallImagesResID,
    UINT uiLargeImagesResID,
    CSize sizeSmallImage = CSize(16,
    16),
    CSize sizeLargeImage = CSize(32,
    32));

pParenrRibbonBar
[in] Указатель на родительскую панель ленты категории ленты.

lpszName
[in] Имя категории ленты.

uiSmallImagesResID
[in] Идентификатор ресурса списка изображений для небольших изображений, используемых элементами ленты в категории ленты.

uiLargeImagesResID
[in] Идентификатор ресурса списка изображений для больших изображений, используемых элементами ленты в категории ленты.

sizeSmallImage
[in] Размер небольших изображений для элементов ленты в категории ленты по умолчанию.

sizeLargeImage
[in] Размер больших изображений по умолчанию для элементов ленты в категории ленты.

Копирует состояние указанного объекта CMFCRibbonCategory в текущий объект CMFCRibbonCategory.

virtual void CopyFrom(CMFCRibbonCategory& src);

src
[in] Исходный CMFCRibbonCategory объект.

Извлекает элемент ленты, связанный с указанными данными.

CMFCRibbonBaseElement* FindByData(
    DWORD_PTR dwData,
    BOOL bVisibleOnly = TRUE) const;

dwData
[in] Данные, связанные с элементом ленты.

bVisibleOnly
[in] ЗНАЧЕНИЕ TRUE для включения элементов ленты быстрого доступа в поиск; ЗНАЧЕНИЕ FALSE, чтобы исключить элементы ленты быстрого доступа в поиске.

Указатель на элемент ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Извлекает элемент ленты, связанный с указанным идентификатором команды.

CMFCRibbonBaseElement* FindByID(
    UINT uiCmdID,
    BOOL bVisibleOnly = TRUE) const;

uiCmdID
[in] Идентификатор команды, связанный с элементом ленты.

bVisibleOnly
[in] ЗНАЧЕНИЕ TRUE для включения элементов ленты быстрого доступа в поиск; ЗНАЧЕНИЕ FALSE, чтобы исключить элементы ленты быстрого доступа в поиске.

Указатель на элемент ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Извлекает панель ленты, содержащую указанный элемент ленты.

CMFCRibbonPanel* FindPanelWithElem(const CMFCRibbonBaseElement* pElement);

pElement
[in] Указатель на элемент ленты.

Указатель на панель ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Извлекает идентификатор контекста категории ленты.

UINT GetContextID() const;

Идентификатор контекста категории ленты.

Идентификатор контекста равен 0, если категория ленты не является категорией контекстной ленты.

Извлекает определяемые пользователем данные, связанные с категорией ленты.

DWORD_PTR GetData() const;

Определяемые пользователем данные, связанные с категорией ленты.

Извлекает указатель на элемент ленты, который в настоящее время отображает всплывающее меню.

CMFCRibbonBaseElement* GetDroppedDown();

Указатель на элемент ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Извлекает все элементы ленты в категории ленты.

void GetElements(
    CArray <CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);

arElements
[in, out] Ссылка на CArray элементов ленты.

Элементы ленты, предназначенные для использования на панели быстрого доступа, включены в массив.

Извлекает все элементы ленты, связанные с указанным идентификатором команды.

void GetElementsByID(
    UINT uiCmdID,
    CArray <CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);

uiCmdID
[in] Идентификатор команды, связанный с элементом ленты.

arElements
[in, out] Ссылка на CArray элементов ленты.

Элементы ленты, предназначенные для использования на панели быстрого доступа, включены в массив.

Извлекает первый видимый элемент, принадлежащий категории ленты.

CMFCRibbonBaseElement* GetFirstVisibleElement() const;

Указатель на первый видимый элемент; Может иметь значение NULL, если категория не содержит видимых элементов.

Возвращает элемент, имеющий фокус ввода.

CMFCRibbonBaseElement* GetFocused();

Указатель на элемент с фокусом или NULL.

Возвращает выделенный элемент.

CMFCRibbonBaseElement* GetHighlighted();

Указатель на выделенный элемент или NULL, если элементы не выделены.

Извлекает количество изображений в указанном списке образов, содержащихся в категории ленты.

int GetImageCount(BOOL bIsLargeImage) const;

bIsLargeImage
[in] ЗНАЧЕНИЕ TRUE для количества изображений в списке больших изображений; FALSE для количества изображений в списке небольших изображений.

Количество изображений в указанном списке изображений.

Извлекает размер изображения в указанном списке образов, который содержится в категории ленты.

CSize GetImageSize(BOOL bIsLargeImage) const;

bIsLargeImage
[in] ЗНАЧЕНИЕ TRUE для размера больших изображений; FALSE для размера небольших изображений.

Размер изображения в указанном списке изображений.

Полученный размер включает глобальный коэффициент масштабирования изображений.

Извлекает идентификаторы команд для элементов ленты, содержащихся в категории ленты.

void GetItemIDsList(
    CList<UINT, UINT>& lstItems,
    BOOL bHiddenOnly = FALSE) const;

lstItems
[out] Список идентификаторов команд для элементов ленты в категории ленты.

bHiddenOnly
[in] ЗНАЧЕНИЕ TRUE, чтобы исключить элементы ленты, отображаемые на панелях ленты в категории ленты; Значение FALSE для включения всех элементов ленты в категорию ленты.

Извлекает список больших изображений, содержащихся в категории ленты.

CMFCToolBarImages& GetLargeImages();

Список больших изображений, содержащихся в категории ленты.

Извлекает последний видимый элемент, принадлежащий категории ленты.

CMFCRibbonBaseElement* GetLastVisibleElement() const;

Указатель на последний видимый элемент; Может иметь значение NULL, если категория не содержит видимых элементов.

Извлекает максимальную высоту панелей ленты, содержащихся в категории ленты.

int GetMaxHeight(CDC* pDC);

pDC
[in] Указатель на контекст устройства для панелей ленты.

Максимальная высота панелей ленты, содержащихся в категории ленты.

Полученное значение включает высоту верхних и нижних полей для панелей ленты.

Извлекает имя категории ленты.

LPCTSTR GetName() const;

Имя категории ленты.

Возвращает указатель на панель ленты, расположенную по указанному индексу.

CMFCRibbonPanel* GetPanel(int nIndex);

nIndex
[in] Отсчитываемый от нуля индекс панели ленты.

Указатель на панель ленты, расположенную по указанному индексу.

Исключение возникает, если nIndex выходит за пределы диапазона.

Возвращает количество панелей ленты в категории ленты.

int GetPanelCount() const;

Количество панелей ленты в категории ленты.

Извлекает указатель на панель ленты, если указанная точка находится в ней.

CMFCRibbonPanel* GetPanelFromPoint(CPoint point) const;

point
[in] Координаты x и y указателя относительно левого верхнего угла окна.

Указатель на панель ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Тестируются только панели ленты, содержащиеся в категории ленты.

Извлекает отсчитываемый от нуля индекс указанной панели ленты.

int GetPanelIndex(const CMFCRibbonPanel* pPanel) const;

pPanel
[in] Указатель на панель ленты.

Отсчитываемый от нуля индекс указанной панели ленты, если метод выполнен успешно; в противном случае - 1.

Поиск выполняются только панели ленты, содержащиеся в категории ленты.

Извлекает родительский элемент ленты категории ленты.

CMFCRibbonBaseElement* GetParentButton() const;

Возвращает указатель на родительский элемент ленты или ЗНАЧЕНИЕ NULL, если родительский элемент отсутствует.

Возвращает указатель на родительскую строку CMFCRibbonCategory меню объекта.

CMFCRibbonPanelMenuBar* GetParentMenuBar() const;

Возвращает содержимое защищенного m_pParentMenuBar элемента.

Извлекает родительскую панель ленты для категории ленты.

CMFCRibbonBar* GetParentRibbonBar() const;

Указатель на родительскую панель ленты для категории ленты.

Извлекает прямоугольник отображения для категории ленты.

CRect GetRect() const;

Прямоугольник отображения для категории ленты.

Прямоугольник отображения для категории ленты не включает вкладку категории.

Извлекает список небольших изображений, содержащихся в категории ленты.

CMFCToolBarImages& GetSmallImages();

Список небольших изображений, содержащихся в категории ленты.

Возвращает текущий цвет вкладки категории ленты.

AFX_RibbonCategoryColor GetTabColor() const;

Текущий цвет вкладки категории ленты.

Возвращаемое значение может быть одним из следующих перечисленных значений:

• AFX_CategoryColor_Red

• AFX_CategoryColor_Orange

• AFX_CategoryColor_Yellow

• AFX_CategoryColor_Green

• AFX_CategoryColor_Blue

• AFX_CategoryColor_Indigo

• AFX_CategoryColor_Violet

Извлекает прямоугольник отображения для вкладки категории ленты.

CRect GetTabRect() const;

Прямоугольник отображения для вкладки категории ленты.

Извлекает вертикальное расположение текста на кнопках ленты в категории ленты, отображающей большие изображения.

int GetTextTopLine() const;

Вертикальное расположение текста (в пикселях) на кнопках ленты, отображающих большие изображения.

Извлекает все видимые элементы, принадлежащие категории ленты.

void GetVisibleElements(
    CArray <CMFCRibbonBaseElement*,
    CMFCRibbonBaseElement*>& arElements);

arElements
Массив всех видимых элементов.

Выделяет указанную панель ленты.

CMFCRibbonPanel* HighlightPanel(
    CMFCRibbonPanel* pHLPanel,
    CPoint point);

pHLPanel
[in] Указатель на панель ленты для выделения.

point
[in] Координаты x и y указателя относительно левого верхнего угла окна.

Указатель на ранее выделенную панель ленты; В противном случае значение NULL, если панель ленты не выделена при вызове этого метода.

Дополнительные сведения о выделении панели ленты см. в разделе CMFCRibbonPanel::Highlight.

Извлекает указатель на элемент ленты, если указанная точка находится в ней.

CMFCRibbonBaseElement* HitTest(
    CPoint point,
    BOOL bCheckPanelCaption = FALSE) const;

point
[in] Координаты указателя мыши x и y относительно левого верхнего угла окна.

bCheckPanelCaption
[in] ЗНАЧЕНИЕ TRUE для проверки заголовка панели ленты; ЗНАЧЕНИЕ FALSE, чтобы исключить заголовок панели ленты.

Указатель на элемент ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Тестируются только элементы ленты, содержащиеся в категории ленты.

Извлекает отсчитываемый от нуля индекс элемента ленты, если указанная точка находится в ней.

int HitTestEx(CPoint point) const;

point
[in] Координаты указателя мыши x и y относительно левого верхнего угла окна.

Отсчитываемый от нуля индекс элемента ленты, если метод выполнен успешно; в противном случае - 1.

Тестируются только элементы ленты, содержащиеся в категории ленты.

Если точка попадает в левую или правую кнопку прокрутки ленты, возвращает указатель на эту кнопку.

CMFCRibbonBaseElement* HitTestScrollButtons(CPoint point) const;

point
[in] Точка для проверки.

Если точка попадает в ограничивающий прямоугольник левой или правой кнопки прокрутки категории ленты, возвращает указатель на эту кнопку или возвращает значение NULL.

Указывает, является ли категория ленты активной категорией на панели ленты.

BOOL IsActive() const;

ЗНАЧЕНИЕ TRUE, если категория ленты является активной категорией; в противном случае ЗНАЧЕНИЕ FALSE.

В активной категории ленты отображаются панели ленты.

Указывает, отображается ли категория ленты.

BOOL IsVisible() const;

ЗНАЧЕНИЕ TRUE, если категория ленты видна; в противном случае ЗНАЧЕНИЕ FALSE.

Категории ленты, которые отображаются на вкладке категорий.

Указывает, имеет ли родительская лента вид Windows 7 (небольшая прямоугольная кнопка приложения).

BOOL IsWindows7Look() const;

ЗНАЧЕНИЕ TRUE, если родительская лента имеет вид Windows 7; в противном случае ЗНАЧЕНИЕ FALSE.

Доставляет сообщение команды WM_NOTIFY всем CMFCRibbonPanel элементам в сообщении CMFCRibbonCategory , пока сообщение не будет обработано.

virtual BOOL NotifyControlCommand(
    BOOL bAccelerator,
    int nNotifyCode,
    WPARAM wParam,
    LPARAM lParam);

bAccelerator
[in] Значение TRUE, если эта команда возникла из акселератора или FALSE.

nNotifyCode
[in] Код уведомления.

wParam
[in] Поле WPARAM сообщения.

lParam
[in] Поле LPARAM сообщения.

Возвращает значение TRUE, если сообщение было обработано или false, если нет.

Вызывает режим отмены во всех CMFCRibbonPanel элементах CMFCRibbonCategory.

virtual void OnCancelMode();

Вызывается платформой для рисования категории ленты.

virtual void OnDraw(CDC* pDC);

pDC
[in] Указатель на контекст устройства для категории ленты.

Вызывается платформой для рисования указанного изображения в категории ленты.

virtual BOOL OnDrawImage(
    CDC* pDC,
    CRect rect,
    CMFCRibbonBaseElement* pElement,
    BOOL bIsLargeImage,
    BOOL nImageIndex,
    BOOL bCenter);

pDC
[in] Указатель на контекст устройства для изображения.

rect
[in] Отображение прямоугольника для изображения.

pElement
[in] Указатель на элемент ленты, содержащий изображение.

bIsLargeImage
[in] ЗНАЧЕНИЕ TRUE, если изображение имеет большой размер; ЗНАЧЕНИЕ FALSE, если изображение имеет небольшой размер.

nImageIndex
[in] Отсчитываемый от нуля индекс изображения в массиве изображений, который содержится в категории ленты.

bCenter
[in] ЗНАЧЕНИЕ TRUE для центра изображения в прямоугольнике отображения; Значение FALSE для рисования изображения в левом верхнем углу прямоугольника отображения.

ЗНАЧЕНИЕ TRUE, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ FALSE.

Вызывается платформой для рисования границы всплывающего меню.

virtual void OnDrawMenuBorder(
    CDC* pDC,
    CMFCRibbonPanelMenuBar* pMenuBar);

pDC
[in] Этот параметр не используется.

pMenuBar
[in] Этот параметр не используется.

По умолчанию этот метод ничего не делает. Переопределите этот метод, чтобы нарисовать границу всплывающего меню.

Вызывается платформой, когда пользователь нажимает кнопку клавиатуры.

virtual BOOL OnKey(UINT nChar);

nChar
Код виртуального ключа для клавиши, нажатой пользователем.

Вызывается платформой для извлечения элемента ленты в указанной точке, когда пользователь нажимает левую кнопку мыши.

virtual CMFCRibbonBaseElement* OnLButtonDown(CPoint point);

point
[in] Координаты указателя мыши x и y относительно левого верхнего угла окна.

Указатель на элемент ленты, если метод выполнен успешно; в противном случае ЗНАЧЕНИЕ NULL.

Вызывается платформой, когда пользователь освобождает левую кнопку мыши, а указатель — на категорию ленты.

virtual void OnLButtonUp(CPoint point);

point
[in] Координаты x и y указателя относительно левого верхнего угла окна.

Вызывается платформой, когда указатель перемещается на панели ленты, чтобы обновить отображение категории ленты.

virtual void OnMouseMove(CPoint point);

point
[in] Координаты x и y указателя относительно левого верхнего угла окна.

Вызывается платформой при изменении направления макета.

virtual void OnRTLChanged(BOOL bIsRTL);

bIsRTL
[in] ЗНАЧЕНИЕ TRUE, если макет находится справа налево; Значение FALSE, если макет находится слева направо.

Этот метод настраивает макет всех панелей ленты и элементов ленты, содержащихся в категории ленты.

Прокручивает категорию ленты в горизонтальном направлении.

virtual BOOL OnScrollHorz(
    BOOL bScrollLeft,
    int nScrollOffset = 0);

bScrollLeft
[in] Значение TRUE для прокрутки влево; Значение FALSE для прокрутки справа.

nScrollOffset
[in] Расстояние прокрутки в пикселях.

ЗНАЧЕНИЕ TRUE, если категория ленты перемещается в горизонтальном направлении; в противном случае ЗНАЧЕНИЕ FALSE.

OnUpdateCmdUI Вызывает функцию-член в каждом из CMFCRibbonPanel элементов элемента, чтобы включить или отключить элементы пользовательского CMFCRibbonCategory интерфейса в них.

virtual void OnUpdateCmdUI(
    CMFCRibbonCmdUI* pCmdUI,
    CFrameWnd* pTarget,
    BOOL bDisableIfNoHndler);

pCmdUI
[in] Указатель на CMFCRibbonCmdUI объект, указывающий, какие элементы пользовательского интерфейса должны быть включены и которые должны быть отключены.

pTarget
[in] Указатель на окно, которое управляет включением или отключением элементов пользовательского интерфейса.

bDisableIfNoHndler
[in] ЗНАЧЕНИЕ TRUE, чтобы отключить элемент пользовательского интерфейса, если обработчик не определен в карте сообщений; в противном случае — ЗНАЧЕНИЕ FALSE.

Настраивает макет всех элементов управления в категории ленты.

virtual void RecalcLayout(CDC* pDC);

pDC
[in] Указатель на контекст устройства для категории ленты.

Удаляет панель ленты из категории ленты.

BOOL RemovePanel(
    int nIndex,
    BOOL bDelete = TRUE);

nIndex
[in] Номер индекса панели для удаления. Получен путем вызова метода CMFCRibbonCategory::GetPanelIndex .

bDelete
[in] ЗНАЧЕНИЕ TRUE, чтобы удалить объект панели из памяти; ЗНАЧЕНИЕ FALSE, чтобы удалить объект панели, не удаляя его.

ЗНАЧЕНИЕ TRUE, если метод выполнен успешно; в противном случае — ЗНАЧЕНИЕ FALSE.

Настраивает макет всех элементов управления на панелях ленты, содержащихся в категории ленты.

virtual void ReposPanels(CDC* pDC);

pDC
[in] Указатель на контекст устройства для панелей ленты, содержащихся в категории ленты.

Определяет порядок сворачивания панелей ленты категории ленты.

void SetCollapseOrder(const CArray<int,int>& arCollapseOrder);

arCollapseOrder
[in] Указывает порядок свертывания. Массив содержит отсчитываемые от нуля индексы панелей ленты.

Библиотека определяет порядок свершения. Однако это поведение можно настроить, указав категорию со списком индексов, указывающих порядок сворачивания.

Когда категория обнаруживает, что она должна свернуть панель ленты, она ищет следующий элемент в указанном списке. Если список пуст или вы не указали достаточно элементов, категория использует внутренний алгоритм.

Например, категория имеет три панели ленты и может быть свернута несколько раз, пока все панели не находятся в полностью свернутом состоянии. Вы можете задать следующий порядок свершения: 0, 0, 2, 2. В этом случае категория свернет панель 0 два раза, панель 2 раза. Панель с индексом 1 остается незавершивой.

В следующем примере показано, как использовать SetCollapseOrder метод в CMFCRibbonCategory классе. В примере показано, как создать массив для порядка свершения и задать порядок свершения категории ленты.

CArray<int, int> arCollapseOrder;
arCollapseOrder.Add(0);
arCollapseOrder.Add(1);
arCollapseOrder.Add(2);
// CMFCRibbonCategory* pCategoryHome
pCategoryHome->SetCollapseOrder(arCollapseOrder);

Задает определяемые пользователем данные, связанные с категорией ленты.

void SetData(DWORD_PTR dwData);

dwData
[in] Определяемые пользователем данные.

Назначает подсказку для категории ленты.

void SetKeys(LPCTSTR lpszKeys);

lpszKeys
[in] Текст подсказки.

Подсказки клавиш отображаются при нажатии клавиши ALT или клавиши F10.

Назначает имя и подсказку ключа категории ленты.

void SetName(LPCTSTR lpszName);

lpszName
[in] Имя и подсказка для категории ленты.

Чтобы задать подсказку для категории ленты, добавьте новую строку escape-последовательности, за которой следует символы клавиши lpszName.

Задает цвет категории ленты.

void SetTabColor(AFX_RibbonCategoryColor color);

color
[in] Задает новый цвет категории ленты.

Цвет может быть одним из следующих значений:

• AFX_CategoryColor_None

• AFX_CategoryColor_Red

• AFX_CategoryColor_Orange

• AFX_CategoryColor_Yellow

• AFX_CategoryColor_Green

• AFX_CategoryColor_Blue

• AFX_CategoryColor_Indigo

• AFX_CategoryColor_Violet

Диаграмма иерархии
Классы
Класс CObject