Получение и установка свойств и элементов

В этой главе описываются, как работать со сценариями Какао, чтобы позволить ей получать и устанавливать значения свойств и элементов в Вашем scriptable приложении. Это также обеспечивает примеры KVC-совместимых методов доступа.

Обзор получения и установки значений

Разрешение сценаристам добраться и установить значения scriptable объектов является важной частью scriptability. В Вашем sdef Вы определяете ключи для scriptable свойств и элементов. В то время как элементы представлены - много отношений, в Вашем приложении свойства эквивалентны атрибуту и - отношения.

Какао, пишущее сценарий поддержек, добирающихся и устанавливающих значения с помощью кодирования значения ключа (KVC). Для Вашего рвения с этой поддержкой необходимо соответствовать соглашениям KVC в именовании ключей sdef файле и соответствующих методах доступа (или переменные экземпляра) в scriptable классах:

В обработке get и set пишущий сценарий команд, сценарии Какао заботятся о следующем автоматически:

Для описания того, как сценарии Какао и приложение сотрудничают для выполнения a set команда, посмотрите, что Реальный мир Пишет сценарий Примера.

Кодирование значения ключа и сценарии какао

Когда сценарии Какао используют KVC, чтобы получить и установить значения, это вызывает один из нескольких методов KVC, в зависимости от типа включенного отношения (свойства или элементы) и на том, является ли работа получать или набором. Они включают два примитивных метода экземпляра NSObject класс: valueForKey: и setValue:forKey:. Эти методы используются прежде всего имея дело со свойствами, хотя они могут также обработать наборы элемента простым, но потенциально неэффективным способом. Для более эффективной обработки наборов KVC вызывает mutableArrayValueForKey:.

Эти методы KVC поочередно ищут Ваш список методов определенные методы в определенном порядке, как описано в Значении ключа, Кодирующем Руководство по программированию. Шаблоны для методов, которые ищет KVC, описаны в, Поддерживают Соответствие KVC.

Ваше приложение не вызывает или переопределяет методы KVC — оно просто называет свои методы доступа или переменные экземпляра так, чтобы KVC мог найти их.

Поддержите соответствие KVC

Для сценариев Какао для работы успешно с KVC каждый scriptable класс в приложении должен быть KVC-совместимым для каждого ключа, соответствующего его scriptable свойствам и элементам. Для обеспечения этого необходимо определить ключи sdef файле, как описано в, Обеспечивают Ключи для Кодирования Значения ключа, и необходимо придерживаться следующих соглашений о присвоении имен для методов доступа или переменных экземпляра (где Вы заменяете <ключ> или <Ключ> со строкой ключа для построения фактического имени метода):

  • Для свойств (атрибуты и к - отношения), Вы реализуете <key> и, если свойство не только для чтения, set<Key>: средства доступа.

  • Для классов элемента (к - много отношений), Вы реализуете <key> и, если класс элемента не только для чтения, insertObject:in<Key>AtIndex: и removeObjectFrom<Key>AtIndex: методы. Для лучшей производительности Вы, возможно, также должны реализовать replaceObjectIn<Key>AtIndex:withObject:.

    Если нет никакого способа эффективно реализовать <key> (например, если значение к - многие отношение не естественно сохранено в экземпляре NSArray), можно вместо этого реализовать countOf<Key> и objectIn<Key>AtIndex:. KVC's valueForKey: и mutableArrayValueForKey:, то, которые вызываются сценариями Какао, возвратит прокси набора, вызывающие Ваши методы в надлежащих случаях.

  • Чтобы позволить Какао автоматически создать прокси массива для обработки наборов элемента можно реализовать countOf<Key> и objectIn<Key>AtIndex: методы.

    Если к - многие отношение является непостоянным, необходимо также реализовать insertObject:in<Key>AtIndex: и removeObjectFrom<Key>AtIndex: методы.

    И для лучшей производительности, Вы, возможно, должны реализовать replaceObjectIn<Key>AtIndex:withObject:.

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

  • Как альтернатива реализации методов доступа, можно использовать в своих интересах прямую переменную экземпляра KVC, получают доступ к функции. Вы делаете это путем простого предоставления переменной экземпляра имени, соответствующего ключ, определенный в sdef с дополнительным начальным символом подчеркивания — например, xPosition или _xPosition,

    Переменные экземпляра, соответствующие перезаписываемым классам элемента, должны иметь тип NSMutableArray если Вы не реализуете insertObject:in<Key>AtIndex: и removeObjectFrom<Key>AtIndex: методы.

  • Для классов элемента, к которым можно получить доступ по имени или ID (т.е. классу идентифицировали свойства четыре кода символа 'pnam' или 'ID '), можно оптимизировать оценку имени и спецификаторов ID путем реализации методов valueIn<Key>WithName: или valueIn<Key>WithUniqueID:, соответственно.

Если Вы следуете стандартным соглашениям о присвоении имен Какао для средств доступа, Вы уже находитесь на пути к соответствию KVC:

  • «Получить» средство доступа должно запуститься со строчной буквы и иметь то же имя как переменная, к которой это получает доступ — например, xPosition.

  • Средство доступа «набора» должно запуститься с «набора», сопровождаемого именем переменной, с первой капитализируемой буквой — например, setXPosition.

Для примеров KVC-совместимых методов доступа на основе шаблонов, описанных здесь, посмотрите Демонстрационные KVC-совместимые Методы доступа.

При исключении средств доступа KVC

Использование методов доступа поддерживает скрытие данных, стандартную практику кодирования. Однако в случаях, где Вы обеспечиваете доступ KVC к своим данным исключительно для поддержки scriptability (или привязка Какао), инкапсуляция может быть менее важной, и Вы могли бы принять решение опустить методы доступа в целом. Если так, Вы должны только поддержать соответствие KVC в именовании Ваших переменных экземпляра для соответствия ключей sdef.

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

Соображения производительности с KVC

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

Поддержите Соответствие KVC, описывает методы сбора, которые необходимо реализовать для лучшей производительности (insertObject:in<Key>AtIndex: и removeObjectFrom<Key>AtIndex:).

Можно вместо этого просто реализовать метод установщика (как в, set<Key>:) и KVC вызовет его, но знать о том, что KVC, как используется Сценариями Какао, должен сделать в этом случае: для вставки или удаления, это должно получить массив значения, сделать непостоянную копию из него, видоизменить копию, и затем установить его снова. Это может быть медленно.

Взаимодействие с наблюдением значения ключа

Поскольку сценарии Какао вызывают setValue:forKey: вместо takeValue:forKey: (осуждаемый метод KVC), изменения в объектах модели, сделанных сценариями AppleScript, являются заметным использующим автоматическим наблюдением значения ключа. Однако, если рассматриваемый контейнер переопределяет takeValue:forKey:, Сценарии какао вызывают takeValue:forKey: для обратной совместимости на уровне двоичных кодов.

Сценарии какао не зависят от KVO. Однако, если Ваше приложение использует привязку Какао, необходимо следовать инструкциям, описанным в Значении ключа, Наблюдая Руководство по программированию. Для соответствующей информации в этом документе посмотрите Взаимодействие С Привязкой Какао и Базовыми Данными.

Преобразование KVC значений скаляра и структуры

Реализации по умолчанию методов KVC valueForKey: и setValue:forKey: предоставьте поддержку для автоматического объектного обертывания скалярных типов данных такой как BOOL, char, double, float, int, и структуры такой как NSPoint, NSRange, и NSRect. Когда сценарии Какао вызывают valueForKey: для получения значения KVC автоматически преобразовывает значение в NSNumber объект (для скаляров) или NSValue объект (для структур) при необходимости.

Точно так же setValue:forKey: определяет тип данных, требуемый надлежащим средством доступа или переменной экземпляра для указанного ключа. Если тип данных не является объектом, то значение извлечено из переданного объекта с помощью надлежащего NSNumber илиNSValue метод.

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

Сценарии дополнений к KVC

Какао определяет категорию NSScriptKeyValueCoding обеспечить связанные со сценариями дополнения к методам кодирования значения ключа, реализованным в NSObject. Методы в этой категории на NSObject обеспечьте дополнительные возможности работы с кодированием значения ключа, включая получение и установку значений ключа индексом в наборе и принуждении (или преобразование) значение ключа. Дополнительные методы позволяют лицу, осуществляющему внедрение scriptable контейнерного класса обеспечивать быстрый доступ к элементам, на которые ссылаются по имени и уникальный идентификатор.

Демонстрационные KVC-совместимые методы доступа

Предположим, что у Вас есть a DrawingCanvas класс, который Вы хотите сделать scriptable. В простом сценарии Вы хотите, чтобы сценарии были в состоянии получить доступ к свойствам графических форм, связанных с объектом холста, и Вы также хотите, чтобы сценарии были в состоянии получить доступ к булеву значению, указывающему, был ли изменен холст. Предположите, что сценаристы могут получить и установить свойства формы, но могут только считать текущую стоимость измененного свойства.

Во-первых, Вы указываете ключи "shape" и "modified" в scriptability информации для Вашего приложения. Чтобы сделать это, Вы могли определить следующие записи в class определение для drawing canvas scriptable класс объекта в Вашем sdef файле:

    <property name="modified" code="iMod" type="boolean" access="ro"
        description="Has the canvas been modified since the last save?">
    </property>
    <element type="shape">

Эти два ключа также становятся переменными экземпляра DrawingCanvas класс. Помните что Какао, пишущее сценарий pluralizes ключ для элемента, как показано в заявленной переменной типа массив, shapes. Если Вы предоставляете полную KVC-совместимую страховую защиту метода, Однако имена переменной экземпляра не должны соответствовать ключи.

@interface DrawingCanvas: NSObject <NSCoding> {
    NSMutableArray *shapes; // An array of shape objects
    BOOL modified; // Whether the canvas has been modified
    // ...

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

Доступ единственного значения

Обеспечить scriptable доступ к булево свойству DrawingCanvas класс, на основе ключа "modified", можно определить KVC-совместимый метод получателя как следующее:

  Метод get булево свойства перечисления 5-1

- (BOOL)modified
{
    // If necessary, obtain or update value
    return modified;
}

Если modified свойство было устанавливаемо (если бы свойство было определено как чтение-запись, значение по умолчанию), то Вы могли бы определить KVC-совместимый метод установщика как следующее:

  Метод set булево свойства перечисления 5-2

- (void)setModified:(BOOL)flag
{
    modified = flag;
}

Как отмечено в При Исключении Средств доступа KVC, в случаях, где Вы обеспечиваете доступ KVC к своим данным исключительно для поддержки scriptability, Вы могли бы принять решение опустить методы доступа. Если так, Вы должны только назвать свои переменные экземпляра для соответствия ключей sdef — в этом случае, modified или _modified.

Доступ значения набора

Для простого scriptable доступа к к - многие отношение, можно реализовать методы доступа как те в Перечислении 5-3. Однако метод установщика может не быть эффективным по причинам, описанным в Соображениях Производительности С KVC.

  Средства доступа элемента Простого массива перечисления 5-3

- (NSArray *)shapes
{
    return [[shapes retain]autorelease];
}
- (void)setShapes:(NSArray *)newShapes
{
    if (shapes != newShapes)
    {
        [shapes release];
        shapes = [newShapes copy];
    }
}

Можно поддерживать доступ KVC для к - много отношений путем реализации индексированных методов доступа. Эти средства доступа работают, хранятся ли связанные объекты в массиве — Какао автоматически создает прокси массива для Вас в случае необходимости.

Для лучшей производительности необходимо реализовать два KVC-совместимых метода, показанные в следующем перечислении, вместо setShapes: метод:

  Элемент матрицы перечисления 5-4 вставляет/удаляет средства доступа (индексом)

-(void)insertObject:(id)anObject inShapesAtIndex:(unsigned)index
{
    [shapes insertObject:anObject atIndex:index];
}
 
-(void)removeObjectFromShapesAtIndex:(unsigned)index
{
    [shapes removeObjectAtIndex:index];
}

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

  Заменяющее средство доступа Элемента матрицы перечисления 5-5 (индексом)

-(void)replaceObjectInShapesAtIndex:(unsigned)index withObject:(id)anObject
{
    // possible implementation-specific code
    [shapes replaceObjectAtIndex:index withObject:anObject];
}

Специальные методы доступа

Иногда метод доступа должен сделать что-то специальное для поддержки сценариев. Например, считайте документы управляемыми основанным на документе приложением. Когда сценарий просит документы приложения, приложение могло вызвать documents метод NSDocumentController объект получить все в настоящее время открываемые документы, упорядоченные созданием.

Однако это не то, что ожидается сценаристом. AppleScript имеет понятие a first document и a last document (а также front document, document 1, и связанные нотации), и это подразумевает упорядочивание документов, видимых на экране. NSApplication класс поэтому реализует orderedDocuments метод, в ответ на запрос на его документы, возвращающий массив объектов документа, где позиция документа в массиве основывается на передней стороне к задерживанию заказов ее связанного (экранного) окна.

Иногда объектная модель приложения обеспечивает доступ сценариев к объектам на уровне гранулярности, которая была бы непрактична для реализации с отдельными объектами. Например, сценарий AppleScript может попросить characters из текстового документа, но было бы довольно дорого для приложения представлять каждый символ как объект. NSTextStorage класс обрабатывает этот случай со специальным методом доступа, characters

Поддержка свойства свойств

Хорошим scriptable приложениям свойственно сделать полный набор свойств для каждого scriptable объекта доступным в форме единственной записи, которая является значением properties свойство. Категория на NSObject (определенный в файле Основы NSObjectScripting.h) объявляет следующие общедоступные методы доступа KVC для этого свойства:

- (NSDictionary *)scriptingProperties;
- (void)setScriptingProperties:(NSDictionary *)properties;

Для всех scriptable классов, наследовавшихся от item, Сценарии какао предоставляют автоматическую scriptability поддержку для properties свойство. Таким образом, если Ваши scriptable классы то убывание от NSObject обеспечьте KVC-совместимые средства доступа для их отдельных scriptable свойств и элементов, у Вас автоматически будет поддержка properties свойство.

Приведение

Приведение является процессом преобразования данных от одного типа до другого. AppleScript предоставляет многим значение по умолчанию (или встроенный) приведения. Например, когда это выполняет оператор set theValue to "20.05" as number, AppleScript преобразовывает строку "20.05" к числовому значению 20.05.

Сценарии какао поддерживают типы, показанные во Встроенной Поддержке Основных Типов AppleScript, и используют приведения по умолчанию по мере необходимости, когда это обрабатывает события Apple, полученные приложением Какао. Для получения информации о приведениях по умолчанию посмотрите Обработчики Приведения По умолчанию в Руководстве по программированию Событий Apple.