Win32 API. Буфер обмена
Страница 37. Функция SetClipboardData
Страница 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_BITMAPCF_DIBWindows NT, Windows 95
CF_DIBCF_BITMAPWindows NT, Windows 95
CF_DIBCF_PALETTEWindows NT, Windows 95
CF_ENHMETAFILECF_METAFILEPICTWindows NT, Windows 95
CF_METAFILEPICTCF_ENHMETAFILEWindows NT, Windows 95
CF_OEMTEXTCF_TEXTWindows NT, Windows 95
CF_OEMTEXTCF_UNICODETEXTWindows NT
CF_TEXTCF_OEMTEXTWindows NT, Windows 95
CF_TEXTCF_UNICODETEXTWindows NT
CF_UNICODETEXTCF_OEMTEXTWindows NT
CF_UNICODETEXTCF_TEXTWindows 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Нет 
Замечания по платформеНе имеется
 
« Предыдущая статья   Следующая статья »