Win32 API. Буфер обмена - Функция SetClipboardData

Written on . Posted in Win32

ОГЛАВЛЕНИЕ

Страница 37 из 55

Функция SetClipboardData

(УстановкаДанныхВБуферОбмена)

Функция SetClipboardData помещает данные в буфер обмена в заданном формате. Окно должно быть текущим владельцем буфера обмена, а прикладная программа, должна вызвать функцию OpenClipboard. (При ответе на сообщения WM_RENDERFORMAT и WM_RENDERALLFORMATS, владелец буфера обмена не должен вызвать OpenClipboard перед вызовом SetClipboardData.)

Синтаксис 

HANDLE SetClipboardData
(
	UINT uFormat,		// формат буфера обмена
	HANDLE hMem		// дескриптор данных
);

Параметры
uFormat
Определяет формат буфера обмена. Этот параметр может быть зарегистрированным форматом или любым из стандартных форматов буфера обмена, перечисленных в ниже следующем разделе Замечания. За информацией о зарегистрированных форматах буфера обмена обратитесь к статье о функции RegisterClipboardFormat.
hMem
Идентифицирует данные в заданном формате. Этот параметр может иметь значение ПУСТО (NULL), указывая, что окно предоставляет данные в заданном формате буфера обмена (представляет формат) после запроса. Если окно задерживает его представление, оно должно обработать сообщения WM_RENDERFORMAT и WM_RENDERALLFORMATS.
Как только вызывается функция SetClipboardData, система идентифицирует владельца объекта при помощи параметра hMem. Прикладная программа может считывать данные, но не должна освобождать или оставлять заблокированным дескриптор. Если параметр hMem идентифицирует объект в памяти, объект, должен быть помещен, используя функцию GlobalAlloc с флажками GMEM_DDESHARE и GMEM_MOVEABLE.

Возвращаемые значения
Если функция завершается успешно, возвращаемое значение - дескриптор данных.
Если функция завершается с ошибкой, возвращаемое значение ПУСТО (NULL). Чтобы получить дополнительные данные об ошибке, вызовите функцию GetLastError.

Замечания
Параметр uFormat может идентифицировать зарегистрированный формат буфера обмена или он может быть одним из следующих значений:

  • CF_BITMAP - Дескриптор к точечному рисунку (HBITMAP).
  • CF_DIB - Объект в памяти содержит структуру BITMAPINFO, сопровождаемую растровыми битами.
  • CF_DIF - Формат обмена данными программы Arts'.
  • CF_DSPBITMAP - Растровый формат отображения данных на дисплее, связанный с собственным форматом. Параметр hMem должен быть дескриптором данных, которые могут отображаться в растровом формате вместо, частным образом форматируемых данных.
  • CF_DSPENHMETAFILE - Формат отображения улучшенного метафайла связанного с собственным форматом. Параметр hMem должен быть дескриптор данных, которые могут отображаться в улучшеннном формате метафайла вместо, частным образом форматируемых данных.
  • CF_DSPMETAFILEPICT - Формат отображения данных метафайла-картинки, связанного с собственным форматом. Параметр hMem должен быть дескриптором данных, которые могут отображаться в формате метафайла-картинки вместо частным образом форматируемых данных.
  • CF_DSPTEXT - Формат отображения текста, связанный с собственным форматом. Параметр hMem должен быть дескриптором данных, которые могут отображаться в текстовом формате вместо частным образом форматируемых данных.
  • CF_ENHMETAFILE - Дескриптор улучшенного метафайла (HENHMETAFILE).
  • От CF_GDIOBJFIRST до CF_GDIOBJLAST - Диапазон целочисленных значений для определяемых программой форматов буфера обмена объекта GDI. Дескрипторы, связанные с форматами буфера обмена в этом диапазоне автоматически не удаляются, при использовании функции GlobalFree, когда опорожняется буфер обмена. Также, при использовании значений в этом диапазоне, параметр hMem - не дескриптор к объекту GDI, а дескриптор, помещенный функцией GlobalAlloc с флажками GMEM_MOVEABLE и GMEM_DDESHARE.
  • CF_HDROP - Дескриптор типа HDROP - это тот, который идентифицирует список файлов. Прикладная программа может извлечь информацию о файлах, передавая дескриптор функции DragQueryFile.
  • CF_LOCALE - Данные являются дескриптором локального идентификатора, связанного с текстом в буфере обмена. Когда вы закрываете буфер обмена, если он содержит данные CF_TEXT, а не данные CF_LOCALE, система автоматически устанавливает формат CF_LOCALE в текущем месте ввода информации. Вы можете использовать формат CF_LOCALE, чтобы сопоставлять различные места действия с текстом буфера обмена. Прикладная программа, которая вставляет текст из буфера обмена, может извлечь этот формат, чтобы определить, какой набор символов использовался, чтобы создать текст. Обратите внимание, что буфер обмена не поддерживает обычный текст в многокомпонентных наборах символов. Чтобы добиться этого, взамен используйте форматированный текстовый тип данных такой как RTF. Windows NT: система использует кодовую страницу, связанную с CF_LOCALE, чтобы неявно преобразовать из CF_TEXT в CF_UNICODETEXT. Следовательно, правильная таблица кодовой страницы используется для преобразования.
  • CF_METAFILEPICT - Дескриптор метафайла изображает формат как определено структурой METAFILEPICT. При передаче дескриптора CF_METAFILEPICT посредством динамического обмена данными (прямой ввод данных (DDE)), прикладная программа, ответственная за удаление hMem должна также освободить метафайл, упоминаемый дескриптором CF_METAFILEPICT.
  • CF_OEMTEXT - Текстовый формат, содержащий символы в OEM наборе символов. Каждые строка заканчивается комбинацией возврат каретки / перевод строки (carriage return/linefeed)(CR-LF). Символ пробела сообщает о конце данных.
  • CF_OWNERDISPLAY - Собственный формат отображения данных. Владелец буфера обмена должен отображать, и модифицировать окна просмотра буфера обмена, и приннимать сообщения WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD и WM_VSCROLLCLIPBOARD. Параметр hMem должен иметь значение ПУСТО (NULL).
  • CF_PALETTE - Дескриптор цветовой палитры. Всякий раз, когда прикладная программа помещает данные в буфер обмена, которые зависят от цветовой палитры или назначает цветовую палитру, она должна поместить в буфер обмена также и палитру. Если буфер обмена содержит данные в формате CF_PALETTE (логическая цветовая палитра), прикладная программа должна использовать функции SelectPalette и RealizePalette, чтобы реализовать ( сравнить) любые другие данные в буфере обмена в зависимости от этой логической палитры. При отображении данных буфера обмена, буфер обмена Windows всегда использует как свою текущую палитру любого объекта в буфере обмена, который находится в формате CF_PALETTE.
  • CF_PENDATA - Дополнительные данные для пера в Microsoft Windows для Pen Computing (Компьютерного пера).
  • От CF_PRIVATEFIRST до CF_PRIVATELAST - Диапазон целых значений для собственных форматов буфера обмена. Дескрипторы, связанные с собственными форматами буфера обмена автоматически не освобождаются; владелец буфера обмена должен освобождать такие дескрипторы, обычно в ответ на сообщение WM_DESTROYCLIPBOARD.
  • CF_RIFF - Представляет звуковые данные более сложные, чем они могут быть представлены в стандартном звуковом формате CF_WAVE.
  • CF_SYLK - Формат Символической Связи Microsoft (SYLK) (Microsoft Symbolic Link).
  • CF_TEXT - Текстовый формат. Каждая строка оканчивается комбинацией возврата каретки / перевода строки (CR-LF). Символ пробела сообщает о конце данных. Используйте этот формат для текста ANSI.
  • CF_WAVE - Представляет звуковые данные в одном из стандартных звуковых форматах, таких как импульсно-кодовой модуляции 11 кГц или 22 кГц (ИКМ) (PCM- pulse code modulation).
  • CF_TIFF - Формат Файла Тегированного Изображения (TIFF - Tagged-image file format).
  • CF_UNICODETEXT - Только Windows NT: Формат текста Уникода. Каждая строка оканчивается комбинацией возврата каретки / перевода строки (CR-LF). Символ пробела сообщает о конце данных.

Операционная система выполняет неявные преобразования формата данных между некоторыми форматами буфера обмена, когда прикладная программа вызывает функцию GetClipboardData. Например, если формат CF_OEMTEXT - в буфере обмена, окно может вернуть данные в формате CF_TEXT. Формат в буфере обмена преобразуется в запрошенный формат по требованию. Нижеследующая таблица показывает преобразования типов данных буфера обмена, которые являются доступными. Обратите внимание, что некоторые из этих автоматических преобразований типов не доступны на всех платформах. 

Формат буфера обмена	Преобразованный формат	Поддерживающая платформа
CF_BITMAP			CF_DIB			Windows NT, Windows 95
CF_DIB			CF_BITMAP			Windows NT, Windows 95
CF_DIB			CF_PALETTE		Windows NT, Windows 95
CF_ENHMETAFILE		CF_METAFILEPICT		Windows NT, Windows 95
CF_METAFILEPICT		CF_ENHMETAFILE		Windows NT, Windows 95
CF_OEMTEXT		CF_TEXT			Windows NT, Windows 95
CF_OEMTEXT		CF_UNICODETEXT		Windows NT
CF_TEXT			CF_OEMTEXT		Windows NT, Windows 95
CF_TEXT			CF_UNICODETEXT		Windows NT
CF_UNICODETEXT		CF_OEMTEXT		Windows NT
CF_UNICODETEXT		CF_TEXT			Windows NT

Если операционная система обеспечивает автоматическое преобразование типов для собственного формата буфера обмена, не имеется никакого преимущества для размещения преобразованного формата(ов) в буфере обмена.
При копировании точечных рисунков, лучше всего в буфер обмена поместить только формат CF_DIB. Это делается так потому, что цвета в аппаратно-зависимом точечном рисунке (CF_BITMAP) - относятся к палитре системы, которая может измениться до того, как точечный рисунок будет вставлен. Если же в буфере обмена формат CF_DIB, а окно запрашивает формат CF_BITMAP, система представляет аппаратно-зависимый точечный рисунок, использующий текущую палитру на этот момент.
Если Вы помещаете формат CF_BITMAP в буфер обмена (а не CF_DIB), система переведет его в формат буфера обмена CF_DIB, как только буфер обмена будет закрыт. Это гарантия того, что используется правильная палитра, чтобы создать не зависящий от устройства точечный рисунок (DIB). Преобразования между другими форматами буфера обмена происходят после запроса.
Платформы Windows поддерживают два формата буфера обмена для метафайлов: CF_ENHMETAFILE и CF_METAFILEPICT. Устанавливайте CF_ENHMETAFILE для расширенных метафайлов и CF_METAFILEPICT для метафайлов Windows.

Смотри также
BITMAPINFO, GetClipboardData, GlobalAlloc, GlobalFree, METAFILEPICT, OpenClipboard, RealizePalette, RegisterClipboardFormat, SelectPalette, WM_ASKCBFORMATNAME, WM_DESTROYCLIPBOARD, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_RENDERFORMAT, WM_RENDERALLFORMATS, WM_SIZECLIPBOARD, WM_VSCROLLCLIPBOARD

Размещение и совместимость SetClipboardData 

Windows NT			Да 
Win95				Да 
Win32s				Да 
Импортируемая библиотека		user32.lib
Заголовочный файл			winuser.h 
Unicode				Нет 
Замечания по платформе		Не имеется

c++ форум