Класс CImageList

Предоставляет функциональные возможности стандартного элемента управления "список изображений" Windows.

Синтаксис

class CImageList : public CObject

Участники

Открытые конструкторы

Имя	Описание
CImageList::CImageList	Формирует объект CImageList.

Открытые методы

Имя	Описание
CImageList::Add	Добавляет изображение или изображения в список изображений.
CImageList::Attach	Присоединяет список изображений к объекту CImageList .
CImageList::BeginDrag	Начинает перетаскивание изображения.
CImageList::Copy	Копирует изображение в объекте CImageList .
CImageList::Create	Инициализирует список изображений и присоединяет его к объекту CImageList .
CImageList::DeleteImageList	Удаляет список изображений.
CImageList::DeleteTempMap	Вызывается обработчиком CWinApp времени простоя, чтобы удалить любой временный CImageList объект, созданный с помощью FromHandle.
CImageList::Detach	Отсоединяет объект списка изображений от CImageList объекта и возвращает дескриптор в список изображений.
CImageList::DragEnter	Блокирует обновления во время операции перетаскивания и отображает изображение перетаскивания в указанной позиции.
CImageList::DragLeave	Разблокирует окно и скрывает изображение перетаскивания, чтобы окно можно было обновить.
CImageList::DragMove	Перемещает изображение, перетаскиваемое во время операции перетаскивания.
CImageList::DragShowNolock	Отображает или скрывает изображение перетаскивания во время операции перетаскивания без блокировки окна.
CImageList::Draw	Рисует изображение, перетаскиваемое во время операции перетаскивания.
CImageList::DrawEx	Рисует элемент списка изображений в указанном контексте устройства. Функция использует указанный стиль рисования и объединяет изображение с указанным цветом.
CImageList::DrawIndirect	Рисует изображение из списка изображений.
CImageList::EndDrag	Завершает операцию перетаскивания.
CImageList::ExtractIcon	Создает значок на основе изображения и маски в списке изображений.
CImageList::FromHandle	Возвращает указатель на CImageList объект при указании дескриптора списку изображений. Если объект CImageList не прикреплен к дескриптору, создается и прикрепляется временный объект CImageList.
CImageList::FromHandlePermanent	Возвращает указатель на CImageList объект при указании дескриптора списку изображений. CImageList Если объект не присоединен к дескриптору, возвращается значение NULL.
CImageList::GetBkColor	Извлекает текущий цвет фона для списка изображений.
CImageList::GetDragImage	Возвращает временный список изображений, используемый для перетаскивания.
CImageList::GetImageCount	Извлекает количество изображений в списке изображений.
CImageList::GetImageInfo	Извлекает сведения об изображении.
CImageList::GetSafeHandle	Извлекает m_hImageList.
CImageList::Read	Считывает список изображений из архива.
CImageList::Remove	Удаляет изображение из списка изображений.
CImageList::Replace	Заменяет изображение в списке изображений новым изображением.
CImageList::SetBkColor	Задает цвет фона для списка изображений.
CImageList::SetDragCursorImage	Создает новое изображение перетаскивания.
CImageList::SetImageCount	Сбрасывает количество изображений в списке изображений.
CImageList::SetOverlayImage	Добавляет отсчитываемый от нуля индекс изображения в список изображений, которые будут использоваться в качестве маски наложения.
CImageList::Write	Записывает список изображений в архив.

Открытые операторы

Имя	Описание
CImageList::operator HIMAGELIST	Возвращает присоединенный HIMAGELIST к объекту CImageList.

Открытые члены данных

Имя	Описание
CImageList::m_hImageList	Дескриптор, содержащий список изображений, присоединенный к этому объекту.

Замечания

"Список изображений" представляет собой коллекцию одинаковых изображений, каждая из которых может ссылаться на его отсчитываемый от нуля индекс. Списки изображений используются для эффективного управления большими наборами значков или растровых изображений. Все изображения в списке изображений содержатся в одном широкоформатном растровом изображении в формате экрана. Список изображений также может содержать монохромное растровое изображение, содержащее маски, используемые для прозрачного рисования изображений (стиль значка). Интерфейс программирования приложений Microsoft Win32 (API) предоставляет функции списка изображений, которые позволяют создавать изображения, создавать и уничтожать списки изображений, добавлять и удалять изображения, заменять изображения, объединять изображения и перетаскивать изображения.

Этот элемент управления (и, следовательно CImageList , класс) доступен только для программ под управлением Windows 95/98 и Windows NT версии 3.51 и более поздних версий.

Дополнительные сведения об использовании CImageListсм. в разделе "Элементы управления " и "Использование CImageList".

Иерархия наследования

CObject

CImageList

Требования

Заголовок.afxcmn.h

CImageList::Add

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

int Add(
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Add(
    CBitmap* pbmImage,
    COLORREF crMask);

int Add(HICON hIcon);

Параметры

pbmImage
Указатель на растровое изображение, содержащее изображение или изображения. Количество изображений выводится из ширины растрового изображения.

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

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

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

Возвращаемое значение

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

Замечания

Вы несете ответственность за освобождение дескриптора значка при завершении работы с ним.

Пример

// Add my icons.
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON1));
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON2));

// Add my bitmap, make all black pixels transparent.
CBitmap bm;
bm.LoadBitmap(IDB_BITMAP1);
m_myImageList.Add(&bm, RGB(0, 0, 0));

CImageList::Attach

Вызовите эту функцию для присоединения списка изображений к объекту CImageList .

BOOL Attach(HIMAGELIST hImageList);

Параметры

hImageList
Дескриптор объекта списка изображений.

Возвращаемое значение

Ненулевое значение, если вложение выполнено успешно; в противном случае — 0.

Пример

void AddQuestion(HIMAGELIST hmyImageList)
{
   CImageList imgList;

   // Attach the image list handle to the CImageList object.
   imgList.Attach(hmyImageList);

   // Add a new icon to the image list.
   imgList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

   // Detach the handle from the CImageList object.
   imgList.Detach();
}

CImageList::BeginDrag

Вызовите эту функцию, чтобы начать перетаскивание изображения.

BOOL BeginDrag(
    int nImage,
    CPoint ptHotSpot);

Параметры

nImage
Отсчитываемый от нуля индекс изображения для перетаскивания.

ptHotSpot
Координаты начальной позиции перетаскивания (как правило, позиция курсора). Координаты относительно левого верхнего угла изображения.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Эта функция создает временный список изображений, используемый для перетаскивания. Изображение объединяет указанное изображение и его маску с текущим курсором. В ответ на последующие WM_MOUSEMOVE сообщения можно переместить изображение перетаскивания с помощью DragMove функции-члена. Чтобы завершить операцию перетаскивания, можно использовать EndDrag функцию-член.

Пример

void CImageListDlg::OnLButtonDown(UINT nFlags, CPoint point)
{
   // Initialize the drag image (usually called from WM_LBUTTONDOWN).
   m_myImageList.BeginDrag(0, CPoint(0, 0));
   m_myImageList.DragEnter(this, point);

   CDialog::OnLButtonDown(nFlags, point);
}

CImageList::CImageList

Формирует объект CImageList.

CImageList();

CImageList::Copy

Эта функция-член реализует поведение функции ImageList_CopyWin32, как описано в пакете SDK для Windows.

BOOL Copy(
    int iDst,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

BOOL Copy(
    int iDst,
    CImageList* pSrc,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

Параметры

iDst
Отсчитываемый от нуля индекс изображения, используемый в качестве назначения операции копирования.

iSrc
Отсчитываемый от нуля индекс изображения, используемый в качестве источника операции копирования.

uFlags
Значение битового флага, указывающее тип операции копирования, которую необходимо выполнить. Этот параметр может принимать одно из следующих значений :

Значение	Значение
ILCF_MOVE	Исходный образ копируется в индекс целевого образа. Эта операция приводит к нескольким экземплярам заданного образа. Значение по умолчанию — ILCF_MOVE.
ILCF_SWAP	Исходные и конечные изображения обмениваются позициями в списке изображений.

pSrc
Указатель на CImageList объект, который является целью операции копирования.

Возвращаемое значение

Ненулевое значение в случае успеха, иначе — 0.

Пример

CImageList myImageList2;
myImageList2.Create(32, 32, ILC_COLOR8, 0, 4);

// Copy the first image from myImageList2 and make it
// the first image of m_myImageList.
m_myImageList.Copy(0, &myImageList2, 0, ILCF_MOVE);

// Recopy the image to make it also the last image in m_myImageList.
m_myImageList.Copy(m_myImageList.GetImageCount() - 1, (int)0,
                   (UINT)ILCF_MOVE);

CImageList::Create

Инициализирует список изображений и присоединяет его к объекту CImageList .

BOOL Create(
    int cx,
    int cy,
    UINT nFlags,
    int nInitial,
    int nGrow);

BOOL Create(
    UINT nBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    LPCTSTR lpszBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    CImageList& imagelist1,
    int nImage1,
    CImageList& imagelist2,
    int nImage2,
    int dx,
    int dy);

BOOL Create(CImageList* pImageList);

Параметры

cx
Размеры каждого изображения в пикселях.

cy
Размеры каждого изображения в пикселях.

nFlags
Указывает тип создаваемого списка изображений. Этот параметр может быть сочетанием следующих значений, но может содержать только одно из значений ILC_COLOR .

Значение	Значение
ILC_COLOR	Используйте поведение по умолчанию, если ни один из других ILC_COLOR* флагов не указан. Как правило, по умолчанию используется ILC_COLOR4значение по умолчанию, но для старых драйверов отображения используется ILC_COLORDDBзначение по умолчанию.
ILC_COLOR4	Используйте раздел 4-разрядной (16 цветов) независимой от устройства растровой карты (DIB) в качестве растрового изображения для списка изображений.
ILC_COLOR8	Используйте 8-разрядный раздел DIB. Цвета, используемые для таблицы цветов, совпадают с цветами, что и палитра полутонов.
ILC_COLOR16	Используйте 16-разрядный (32/64k цвет) diB.
ILC_COLOR24	Используйте 24-разрядный раздел DIB.
ILC_COLOR32	Используйте 32-разрядный раздел DIB.
ILC_COLORDDB	Используйте зависимый от устройства растровый рисунок.
ILC_MASK	Использует маску. Список изображений содержит два растровых изображения, одно из которых является монохромным растровым изображением, используемым в качестве маски. Если это значение не включено, список изображений содержит только одно растровое изображение. Дополнительные сведения о маскированных изображениях см. в разделе " Рисование изображений из списка изображений".

nInitial
Количество изображений, которые изначально содержит список изображений.

nGrow
Количество изображений, по которым может расти список изображений, когда системе необходимо изменить размер списка, чтобы освободить место для новых образов. Этот параметр представляет количество новых изображений, которые может содержать список измененных изображений.

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

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

lpszBitmapID
Строка, содержащая идентификаторы ресурсов изображений.

imagelist1
Ссылка на объект CImageList.

nImage1
Индекс первого существующего образа.

imagelist2
Ссылка на объект CImageList.

nImage2
Индекс второго существующего образа.

dx
Смещение оси x второго изображения в связи с первым изображением в пикселях.

dy
Смещение оси Y второго изображения в связи с первым изображением в пикселях.

pImageList
Указатель на объект CImageList.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Вы создаете два CImageList шага. Сначала вызовите конструктор и вызов Create, который создает список изображений и присоединяет его к объекту CImageList .

Пример

m_myImageList.Create(32, 32, ILC_COLOR8, 0, 4);

CImageList::DeleteImageList

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

BOOL DeleteImageList();

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Пример

// Delete the image list and verify.
myImageList2.DeleteImageList();
ASSERT(myImageList2.GetSafeHandle() == NULL);

CImageList::DeleteTempMap

Вызывается автоматически обработчиком CWinApp времени простоя, удаляет все временные CImageList объекты, DeleteTempMap созданные FromHandle, но не уничтожает дескрипторы (hImageList) временно связанные с объектамиImageList.

static void PASCAL DeleteTempMap();

Пример

// Note that this is a static member so an instantiated CImageList
// object is unnecessary.
CImageList::DeleteTempMap();

CImageList::Detach

Вызовите эту функцию, чтобы отключить объект списка изображений от CImageList объекта.

HIMAGELIST Detach();

Возвращаемое значение

Дескриптор объекта списка изображений.

Замечания

Эта функция возвращает дескриптор объекту списка изображений.

Пример

Пример см. в примере CImageList::Attach.

CImageList::DragEnter

Во время операции перетаскивания блокирует обновления окна, заданного pWndLock и отображает изображение перетаскивания в позиции, указанной в pointполе.

static BOOL PASCAL DragEnter(
    CWnd* pWndLock,
    CPoint point);

Параметры

pWndLock
Указатель на окно, которое владеет изображением перетаскивания.

point
Положение, в котором отображается изображение перетаскивания. Координаты относительно левого верхнего угла окна (а не клиентской области).

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Координаты относятся к левому верхнему углу окна, поэтому при указании координат необходимо компенсировать ширину элементов окна, например границу, строку заголовка и строку меню.

Если pWndLock это NULLтак, эта функция рисует изображение в контексте отображения, связанном с окном рабочего стола, и координаты относятся к левому верхнему углу экрана.

Эта функция блокирует все остальные обновления заданного окна во время операции перетаскивания. Если во время операции перетаскивания необходимо сделать любой рисунок, например выделение цели операции перетаскивания, можно временно скрыть перетаскиваемое изображение с помощью CImageList::DragLeave функции.

Пример

Пример см. в примере CImageList::BeginDrag.

CImageList::DragLeave

Разблокирует окно, указанное pWndLock и скрывает изображение перетаскивания, что позволяет обновить окно.

static BOOL PASCAL DragLeave(CWnd* pWndLock);

Параметры

pWndLock
Указатель на окно, которое владеет изображением перетаскивания.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Пример

Пример см. в примере CImageList::EndDrag.

CImageList::DragMove

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

static BOOL PASCAL DragMove(CPoint pt);

Параметры

pt
Новая позиция перетаскивания.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Обычно эта функция вызывается в ответ на WM_MOUSEMOVE сообщение. Чтобы начать операцию перетаскивания, используйте функцию-член BeginDrag .

Пример

void CImageListDlg::OnMouseMove(UINT nFlags, CPoint point)
{
   m_myImageList.DragMove(point);

   CDialog::OnMouseMove(nFlags, point);
}

CImageList::DragShowNolock

Отображает или скрывает изображение перетаскивания во время операции перетаскивания без блокировки окна.

static BOOL PASCAL DragShowNolock(BOOL bShow);

Параметры

bShow
Указывает, должен ли отображаться изображение перетаскивания.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Функция CImageList::DragEnter блокирует все обновления окна во время операции перетаскивания. Однако эта функция не блокирует окно.

CImageList::Draw

Вызовите эту функцию, чтобы нарисовать изображение, перетаскиваемое во время операции перетаскивания.

BOOL Draw(
    CDC* pDC,
    int nImage,
    POINT pt,
    UINT nStyle);

Параметры

pDC
Указатель на контекст конечного устройства.

nImage
Отсчитываемый от нуля индекс рисунка.

pt
Расположение для рисования в заданном контексте устройства.

nStyle
Флаг, указывающий стиль рисования. Это может быть одно или несколько из следующих значений:

Значение	Значение
ILD_BLEND25, ILD_FOCUS	Рисует изображение, смешивая 25 процентов с цветом выделения системы. Это значение не влияет, если список изображений не содержит маску.
ILD_BLEND50, ILD_SELECTED, ILD_BLEND	Рисует изображение, смешивая 50 процентов с цветом выделения системы. Это значение не влияет, если список изображений не содержит маску.
ILD_MASK	Рисует маску.
ILD_NORMAL	Рисует изображение с помощью цвета фона для списка изображений. Если цвет фона является CLR_NONE значением, изображение рисуется прозрачно с помощью маски.
ILD_TRANSPARENT	Рисует изображение прозрачно с помощью маски независимо от цвета фона.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Пример

Пример см. в примере CImageList::SetOverlayImage.

CImageList::DrawEx

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

BOOL DrawEx(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    COLORREF clrBk,
    COLORREF clrFg,
    UINT nStyle);

Параметры

pDC
Указатель на контекст конечного устройства.

nImage
Отсчитываемый от нуля индекс рисунка.

pt
Расположение для рисования в заданном контексте устройства.

sz
Размер части изображения для рисования относительно левого верхнего угла изображения. См dx . и dy в ImageList_DrawEx пакете SDK для Windows.

clrBk
Цвет фона изображения. См rgbBk . в ImageList_DrawEx пакете SDK для Windows.

clrFg
Цвет переднего плана изображения. См rgbFg . в ImageList_DrawEx пакете SDK для Windows.

nStyle
Флаг, указывающий стиль рисования. См fStyle . в ImageList_DrawEx пакете SDK для Windows.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Функция использует указанный стиль рисования и объединяет изображение с указанным цветом.

Пример

m_myImageList.DrawEx(&dc, 0, CPoint(0, 0), CSize(16, 16), CLR_DEFAULT,
                     CLR_DEFAULT, ILD_IMAGE);

CImageList::DrawIndirect

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

BOOL DrawIndirect(IMAGELISTDRAWPARAMS* pimldp);

BOOL DrawIndirect(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    POINT ptOrigin,
    UINT fStyle = ILD_NORMAL,
    DWORD dwRop = SRCCOPY,
    COLORREF rgbBack = CLR_DEFAULT,
    COLORREF rgbFore = CLR_DEFAULT,
    DWORD fState = ILS_NORMAL,
    DWORD Frame = 0,
    COLORREF crEffect = CLR_DEFAULT);

Параметры

pimldp
Указатель на IMAGELISTDRAWPARAMS структуру, содержащую сведения об операции рисования.

pDC
Указатель на контекст целевого устройства. Этот объект необходимо удалить CDC при завершении работы.

nImage
Отсчитываемый от нуля индекс изображения.

pt
Структура POINT , содержащая координаты X и Y, где будет вырисовано изображение.

sz
Структура SIZE , указывающая размер нарисованного изображения.

ptOrigin
Структура POINT , содержащая координаты X и Y, указывающая верхний левый угол операции рисования относительно самого изображения. Пиксели изображения, которые находятся слева от координат x и выше координаты y, не рисуются.

fStyle
Флаг, указывающий стиль рисования и, при необходимости, изображение наложения. Дополнительные сведения о изображении наложения см. в разделе "Примечания". Реализация по умолчанию ILD_NORMALMFC рисует изображение с помощью цвета фона для списка изображений. Если цвет фона является CLR_NONE значением, изображение рисуется прозрачно с помощью маски.

Другие возможные стили описаны в fStyle элементе IMAGELISTDRAWPARAMS структуры.

dwRop
Значение, указывающее код растровой операции. Эти коды определяют, как данные цвета для исходного прямоугольника будут объединены с цветными данными для целевого прямоугольника для достижения окончательного цвета. Реализация SRCCOPYпо умолчанию MFC копирует исходный прямоугольник непосредственно в прямоугольник назначения. Этот параметр игнорируется, если fStyle параметр не включает ILD_ROP флаг.

Другие возможные значения описаны в dwRop элементе IMAGELISTDRAWPARAMS структуры.

rgbBack
Цвет фона изображения по умолчанию CLR_DEFAULT. Этот параметр может быть определяемым приложением значением RGB или одним из следующих значений:

Значение	Значение
CLR_DEFAULT	Цвет фона по умолчанию. Изображение рисуется с помощью цвета фона списка изображений.
CLR_NONE	Нет цвета фона. Изображение рисуется прозрачно.

rgbFore
Цвет переднего плана изображения по умолчанию CLR_DEFAULT. Этот параметр может быть определяемым приложением значением RGB или одним из следующих значений:

Значение	Значение
CLR_DEFAULT	Цвет переднего плана по умолчанию. Изображение рисуется с помощью цвета выделения системы в качестве цвета переднего плана.
CLR_NONE	Нет цвета смешения. Изображение смешивается с цветом контекста целевого устройства.

Этот параметр используется только в том случае, если fStyle он включает ILD_BLEND25 или ILD_BLEND50 флаг.

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

Frame
Влияет на поведение насыщенных и альфа-смешивающих эффектов.

При использовании с ILS_SATURATEэтим элементом содержится значение, добавляемое к каждому компоненту цвета RGB-триплета для каждого пикселя в значке.

При использовании с ILS_APLHAэтим элементом содержится значение альфа-канала. Это значение может быть от 0 до 255, с 0 полностью прозрачным и 255 полностью непрозрачным.

crEffect
Значение, используемое COLORREF для эффектов свечения и тени.

Возвращаемое значение

TRUE Значение , если изображение успешно нарисовано; в противном случае FALSE.

Замечания

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

Изображение наложения — это изображение, нарисованное поверх основного изображения, указанного в этой функции-члене параметром nImage . Нарисуйте маску наложения с помощью Draw функции-члена с одним индексом маски наложения, указанной INDEXTOOVERLAYMASK с помощью макроса.

Пример

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   m_myImageList.DrawIndirect(&dc, i, CPoint(dx, 0),
                              CSize(cx, cy), CPoint(0, 0));
   dx += cx;
}

CImageList::EndDrag

Вызовите эту функцию, чтобы завершить операцию перетаскивания.

static void PASCAL EndDrag();

Замечания

Чтобы начать операцию перетаскивания, используйте функцию-член BeginDrag .

Пример

void CImageListDlg::OnLButtonUp(UINT nFlags, CPoint point)
{
   // Terminate the drag image (usually called from WM_LBUTTONUP).
   m_myImageList.DragLeave(this);
   m_myImageList.EndDrag();

   CDialog::OnLButtonUp(nFlags, point);
}

CImageList::ExtractIcon

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

HICON ExtractIcon(int nImage);

Параметры

nImage
Отсчитываемый от нуля индекс изображения.

Возвращаемое значение

Дескриптор значка в случае успешного выполнения; в противном случае NULL.

Замечания

Этот метод зависит от поведения ImageList_ExtractIcon макроса для создания значка. Дополнительные сведения о создании и очистке значков см. в ImageList_ExtractIcon макросе.

Пример

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();
HICON hIcon;

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   hIcon = m_myImageList.ExtractIcon(i);

   dc.DrawIcon(dx, 0, hIcon);
   dx += cx;
}

CImageList::FromHandle

Возвращает указатель на CImageList объект при указании дескриптора списку изображений.

static CImageList* PASCAL FromHandle(HIMAGELIST hImageList);

Параметры

hImageList
Указывает список изображений.

Возвращаемое значение

Указатель на объект в случае успешного CImageList выполнения; в противном случае NULL.

Замечания

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

Пример

CImageList *ConvertHandle(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandle(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

CImageList::FromHandlePermanent

Возвращает указатель на CImageList объект при указании дескриптора списку изображений.

static CImageList* PASCAL FromHandlePermanent(HIMAGELIST hImageList);

Параметры

hImageList
Указывает список изображений.

Возвращаемое значение

Указатель на объект в случае успешного CImageList выполнения; в противном случае NULL.

Замечания

CImageList Если объект не присоединен к дескриптору, NULL возвращается.

Пример

CImageList *ConvertHandlePermanent(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandlePermanent(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

CImageList::GetBkColor

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

COLORREF GetBkColor() const;

Возвращаемое значение

Значение цвета RGB для цвета фона CImageList объекта.

Пример

Пример см. в примере CImageList::SetBkColor.

CImageList::GetDragImage

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

static CImageList* PASCAL GetDragImage(
    LPPOINT lpPoint,
    LPPOINT lpPointHotSpot);

Параметры

lpPoint
POINT Адрес структуры, получающей текущую позицию перетаскивания.

lpPointHotSpot
POINT Адрес структуры, получающей смещение изображения перетаскивания относительно позиции перетаскивания.

Возвращаемое значение

При успешном выполнении указатель на временный список изображений, используемый для перетаскивания; NULLв противном случае .

CImageList::GetImageCount

Вызовите эту функцию, чтобы получить количество изображений в списке изображений.

int GetImageCount() const;

Возвращаемое значение

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

Пример

Пример см. в примере CImageList::ExtractIcon.

CImageList::GetImageInfo

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

BOOL GetImageInfo(
    int nImage,
    IMAGEINFO* pImageInfo) const;

Параметры

nImage
Отсчитываемый от нуля индекс изображения.

pImageInfo
Указатель на структуру IMAGEINFO , которая получает сведения о изображении. Сведения в этой структуре можно использовать для непосредственного управления растровыми изображениями для изображения.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Структура IMAGEINFO содержит сведения об изображении в списке изображений.

CImageList::GetSafeHandle

Вызовите эту функцию, чтобы получить m_hImageList член данных.

HIMAGELIST GetSafeHandle() const;

Возвращаемое значение

Дескриптор в присоединенном списке изображений; в противном случае NULL , если объект не подключен.

Пример

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.GetSafeHandle();

CImageList::m_hImageList

Дескриптор списка изображений, присоединенного к этому объекту.

HIMAGELIST m_hImageList;

Замечания

Элемент m_hImageList данных — это общедоступная переменная типа HIMAGELIST.

Пример

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.m_hImageList;

CImageList::operator HIMAGELIST

Используйте этот оператор, чтобы получить присоединенный дескриптор CImageList объекта.

operator HIMAGELIST() const;

Возвращаемое значение

В случае успешного выполнения дескриптор списка изображений, представленный CImageList объектом; в противном случае NULL.

Замечания

Этот оператор является оператором приведения, который поддерживает прямое использование HIMAGELIST объекта.

Пример

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList;

CImageList::Read

Вызовите эту функцию для чтения списка изображений из архива.

BOOL Read(CArchive* pArchive);

Параметры

pArchive
Указатель на CArchive объект, из которого должен быть считывается список изображений.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Пример

// Open the archive to load the image list from.
CFile myFile(_T("myfile.data"), CFile::modeRead);
CArchive ar(&myFile, CArchive::load);
CImageList myImgList;

// Load the image list from the archive.
myImgList.Read(&ar);

CImageList::Remove

Вызовите эту функцию, чтобы удалить изображение из объекта списка изображений.

BOOL Remove(int nImage);

Параметры

nImage
Отсчитываемый от нуля индекс образа.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

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

Пример

// Remove every other image from the image list.
for (int i = 0; i < m_myImageList.GetImageCount(); i++)
{
   m_myImageList.Remove(i);
}

CImageList::Replace

Вызовите эту функцию, чтобы заменить изображение в списке изображений новым изображением.

BOOL Replace(
    int nImage,
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Replace(
    int nImage,
    HICON hIcon);

Параметры

nImage
Отсчитываемый от нуля индекс изображения для замены.

pbmImage
Указатель на растровое изображение, содержащее изображение.

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

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

Возвращаемое значение

Возвращаемая BOOL версия возвращает ненулевое значение; в противном случае — значение 0.

Возвращаемая int версия возвращает отсчитываемый от нуля индекс изображения в случае успешного выполнения; в противном случае — 1.

Замечания

Вызовите эту функцию-член после вызова SetImageCount , чтобы назначить новые допустимые изображения номерам индекса заполнителя.

Пример

Пример см. в примере CImageList::SetImageCount.

CImageList::SetBkColor

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

COLORREF SetBkColor(COLORREF cr);

Параметры

cr
Цвет фона для задания. Это может быть CLR_NONE. В этом случае изображения рисуются прозрачно с помощью маски.

Возвращаемое значение

Предыдущий цвет фона при успешном выполнении; в противном случае CLR_NONE.

Пример

// Set the background color to white.
m_myImageList.SetBkColor(RGB(255, 255, 255));
ASSERT(m_myImageList.GetBkColor() == RGB(255, 255, 255));

CImageList::SetDragCursorImage

Создает новое изображение перетаскивания путем объединения заданного изображения (обычно изображения курсора мыши) с текущим изображением перетаскивания.

BOOL SetDragCursorImage(
    int nDrag,
    CPoint ptHotSpot);

Параметры

nDrag
Индекс нового изображения для объединения с изображением перетаскивания.

ptHotSpot
Положение горячей точки в новом изображении.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Так как функции перетаскивания используют новое изображение во время операции перетаскивания, следует использовать функцию Windows ShowCursor для скрытия фактического курсора мыши после вызова CImageList::SetDragCursorImage. В противном случае система может иметь два курсора мыши в течение длительности операции перетаскивания.

CImageList::SetImageCount

Вызовите эту функцию-член, чтобы сбросить количество изображений в объекте CImageList .

BOOL SetImageCount(UINT uNewCount);

Параметры

uNewCount
Значение, указывающее новое общее количество изображений в списке изображений.

Возвращаемое значение

Ненулевое значение в случае успеха, иначе — 0.

Замечания

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

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

Пример

// Set the image count of the image list to be 10 with
// all images being the system question mark icon.
m_myImageList.SetImageCount(10);
HICON hIcon = AfxGetApp()->LoadStandardIcon(IDI_QUESTION);

for (int i = 0; i < 10; i++)
{
   m_myImageList.Replace(i, hIcon);
}

CImageList::SetOverlayImage

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

BOOL SetOverlayImage(
    int nImage,
    int nOverlay);

Параметры

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

nOverlay
Одноуровневый индекс маски наложения.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

В список можно добавить до четырех индексов.

Маска наложения — это изображение, нарисованное прозрачно по другому изображению. Нарисуйте маску наложения на изображение с помощью CImageList::Draw функции-члена с одним индексом маски наложения, указанной с помощью INDEXTOOVERLAYMASK макроса.

Пример

// Add a new image to the image list.
int nIndex = m_myImageList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

if (nIndex != -1)
{
   // Make the new image an overlay image.
   m_myImageList.SetOverlayImage(nIndex, 1);

   // Draw the first image in the image list with an overlay image.
   m_myImageList.Draw(&dc, 0, CPoint(0, 0), INDEXTOOVERLAYMASK(1));
}

CImageList::Write

Вызовите эту функцию для записи объекта списка изображений в архив.

BOOL Write(CArchive* pArchive);

Параметры

pArchive
Указатель на CArchive объект, в котором должен храниться список изображений.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Пример

// Open the archive to store the image list in.
CFile myFile(_T("myfile.data"), CFile::modeCreate | CFile::modeWrite);
CArchive ar(&myFile, CArchive::store);

// Store the image list in the archive.
m_myImageList.Write(&ar);

См. также

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