Генератор беглого взгляда API

Заголовочный файл QLGenerator.h в Беглом взгляде платформа объявляет программируемый интерфейс для генераторов Беглого взгляда. (Другой заголовочный файл, QLBase.h, находится также в Headers папка, но этот файл просто содержит определения различных макросов, используемых и Беглым взглядом открытые и закрытые интерфейсы.) Программируемый интерфейс для генераторов разделен между запросами миниатюры и запросами предварительного просмотра, представленными непрозрачными типами QLThumbnailRequestRef и QLPreviewRequestRef, соответственно. API попадает в три отличных категории:

• Обратные вызовы

  Генераторы должны реализовать функцию обратного вызова, введенную как GenerateThumbnailForURL создать и возвратить представление миниатюры документа. Они должны реализовать функцию обратного вызова, введенную как GeneratePreviewForURL создать и возвратить предварительный просмотр документа. Как отмечено в Создании и Конфигурировании Проекта Беглого взгляда, шаблон Xcode для генераторов делает имена по умолчанию функций обратного вызова тем же как их имена типов.

  Дополнительная пара функций обратного вызова может быть реализована для отмены генерации предварительных просмотров и миниатюр, которые в настоящее время выполняет генератор. Для получения дополнительной информации об этих обратных вызовах посмотрите Предварительные просмотры Отмены и Миниатюры.

• Функции, используемые в генерации миниатюр и предварительных просмотров

  Беглый взгляд обеспечивает диапазон функциональных альтернатив для генераторов, чтобы создать и возвратить миниатюры и предварительные просмотры. Например, QLThumbnailRequestCreateContext и QLPreviewRequestCreateContext функции обеспечивают графический контекст для рисования растровых и векторных изображений в. Вы используете QLPreviewRequestSetDataRepresentation функционируйте для возврата встроенного или динамично сгенерированного предварительного просмотра, часто для содержимого HTML, обогащенного присоединениями. С QLThumbnailRequestSetImage функционируйте Вы возвращаете статическое изображение миниатюр, представляющее документ.

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

• Функции, возвращающие информацию о запросе или генераторе

  Остающиеся функции в QLGenerator.h позвольте Вам, получают атрибуты предварительного просмотра или запросов миниатюры или получить другие данные, связанные с ними. Например, QLThumbnailRequestCopyURL функционируйте возвращает URL, идентифицирующий документ, на который требуют миниатюру. QLThumbnailRequestGetGeneratorBundle функционируйте возвращает ссылку (CFBundleRef) к пакету генератора. И QLPreviewRequestCopyContentUTI функционируйте возвращает идентификатор UTI содержания текущего документа (например, com.apple.sketch1).

Важное различие для учета, когда программирование генераторов является различием между опциями и свойствами. Оба - имена CFDictionaryRef параметры в функциях Беглого взгляда. Но параметр опций в функциях обратного вызова GenerateThumbnailForURL и GeneratePreviewForURL словарь опций или подсказки, от клиента к генератору для того, как должен быть обработан запрос. Параметр свойств является последним параметром в QLThumbnailRequest и QLPreviewRequest функции, используемые для создания миниатюр и предварительных просмотров; properties словарь содержит данные, дополнительные к создаваемой миниатюре или предварительному просмотру.

Подходы к генерации миниатюры и предварительного просмотра

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

• Это связывается (как, например, документ Страниц), или это несвязывается (или плоское)?

• Это содержит графику или текст? Или и графика и текст?

• Если графика, действительно ли это - растровое или векторное изображение?

• Это имеет единственную страницу или многократные страницы?

Конечно, ли запрос для миниатюры, или предварительный просмотр вводит в Ваш выбор подхода. Если запрос для миниатюры с размером, не больше, чем регулярный значок документа, то миниатюра в том размере может быть не лучше, чем значок. Если запрос для предварительного просмотра многостраничного документа, Вы показываете просто первую страницу документа или всего этого? Является ли запрос для миниатюры или предварительного просмотра, производительность Вашего генератора первостепенной важности. Например, когда клиент запрашивает миниатюры, это может запросить их на десятки различных документов; неэффективные генераторы могут заставить дисплей клиента миниатюр казаться вялым. Если клиент запрашивает предварительный просмотр на документ, который составляет более чем 200 страниц, возможно необходимо включать только достаточно документа для пользователя для идентификации его. Для Вашего генератора необходимо принять надлежащие методы управления памятью и надлежащую стратегию многопоточности. Для получения дополнительной информации о многопоточных генераторах и проблемах потокобезопасности, посмотрите Генераторы и Потокобезопасность

Если Вы хотите указать статическую миниатюру и изображения предварительного просмотра для связанного документа, можно проявить самый простой подход — это даже не требует генератора. Просто имейте свое место приложения изображения в пакете документа в названной подпапке QuickLook; файл образа для миниатюр нужно назвать Thumbnail.расширение и файл для предварительных просмотров нужно назвать Preview.расширение (где расширение является расширением такой как tiff, png, или jpg). При выборе этого подхода Вы не должны создавать генератор.

Программно, можно проявить один из следующих подходов для генерации миниатюр и предварительных просмотров, в зависимости от документа и других обстоятельств:

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

• Если документ имеет больше чем одну страницу векторной графики или текста, можно нарисовать предварительный просмотр как содержание PDF в графическом контексте, предоставленном QLPreviewRequestCreatePDFContext. Можно вызвать регулярные Базовые Графические функции для рисования изображения предварительного просмотра.

  Преимущество этого и предыдущего подхода состоит в том, что Вы полностью управляете тем, что нарисовано; однако, необходимо обработать расположение сами. Приложения, которые являются хорошими кандидатами на этот подход, являются Книгой Шрифта, Представлением ведущих идей и Страницами.

• Для любого вида документа приложение может записать миниатюру и изображение предварительного просмотра как часть данных документа, которые генератор получает и возвращает с функциями QLThumbnailRequestSetImageWithData и QLPreviewRequestSetDataRepresentation, соответственно. Рисунок 4-1 иллюстрирует этот подход. Для предварительных просмотров необходимо указать, в каком собственном типе Беглого взгляда данные предварительного просмотра находятся через contentTypeUTI параметр. Для миниатюр возвращенные данные должны в формате, который может быть обработан Изображением платформа I/O: JPG, TIFF, PNG, и т.д.

  

• Для многостраничных документов, обычно текстовых документов, генератор может динамично генерировать предварительный просмотр «на лету» и возвратить его с QLPreviewRequestSetDataRepresentation функция.

  Несмотря на то, что можно сделать это для предварительного просмотра в любом собственном типе Беглого взгляда (таком как RTF), рекомендуемый подход для документов с «обогащенным» текстовым содержанием должен использовать QLPreviewRequestSetDataRepresentation с contentTypeUTI параметром kUTTypeHTML. Эта комбинация функции и параметра говорит Беглому взгляду использовать веб-Набор для обработки расположения предварительного просмотра. В заключительном параметре функции, properties словарь, можно указать присоединения в HTML (такие как изображения, звуки, и даже вещи как карты Адресной книги). Для этого подхода, чтобы быть выполнимыми, конечно, данные документа должны быть конвертируемыми к HTML.

• Когда Вы не можете обеспечить Беглый взгляд (через QLThumbnailRequestSetImageWithData) версия изображения миниатюр, которое находится в формате, подходящем для Изображения платформа I/O, но можно генерировать сериализированное изображение миниатюр в некотором другом формате, можно использовать QLThumbnailRequestSetImage функционируйте для возврата этого изображения Беглому взгляду.

Генераторы и потокобезопасность

По причинам производительности, демон Беглого взгляда (quicklookd) когда тот генератор работает над многократными документами, предпочитает выполнять генератор в его собственном потоке, обычно одновременно с другими генераторами или даже с тем же генератором. Когда Вы пишете код для генератора, учитывая это, возникают несколько вопросов о потокобезопасности:

• Сам ориентирован на многопотоковое исполнение код генератора?

• Платформы то, что генератор вызывает в ориентированный на многопотоковое исполнение в текущем контексте?

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

• Код генератора или код платформы вызваны генератором, который в состоянии быть выполненным в неосновном потоке?

Если можно определить ответ на эти вопросы, можно сконфигурировать генератор для оптимальной производительности путем установки QLSupportsConcurrentRequests и QLNeedsToBeRunOnMainThread свойства в Вас информационный список свойств генератора (Info.plist). (Если Вы не уверены в ответе на какой-либо из вышеупомянутых вопросов, принимаете самый консервативный ответ с точки зрения потокобезопасности.) Таблица 4-1 суммирует состояние потокобезопасности, которое Беглый взгляд принимает при присвоении различных значений этим двум свойствам.

Для получения информации о проблемах потокобезопасности, включая ориентированное на многопотоковое исполнение состояние платформ Углерода и Какао, см. Руководство по программированию Поточной обработки.