Спины виджета и предпочтения

Виджеты имеют возможность вывести на экран, записать, и получить предпочтения. Это позволяет пользователям настраивать Ваш виджет на основе возможностей, которые Вы предоставляете. Предпочтения должны быть выведены на экран в конце Вашего виджета. Раздел Displaying a Widget's Back обсуждает, как установить Ваш виджет для сторон и как обеспечить надлежащие кнопки и анимации. Обеспечение Предпочтений обсуждает сохранение и получение предпочтений.

Обеспечение предпочтений

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

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

if(window.widget)
{
    widget.setPreferenceForKey("Goodbye, World!","worldString");
}

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

Второй метод, widget.preferenceForKey(key), получает предпочтение предоставленного ключа или возвраты undefined если никакая запись не существует для ключа:

if(window.widget)
{
    var worldString = widget.preferenceForKey("worldString");
 
    if (worldString && worldString.length > 0)
    {
        worldText.innerText = worldString;
    }
}

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

Строки, сохраненные и полученные через этот механизм, сохранены как открытый текст и поэтому не безопасны и не рекомендуемые для сохранения паролей или другой уязвимой информации.

Отображение виджета Назад

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

В Вашем файле HTML

Во-первых, в теле HTML Вашего виджета, Вы должны иметь два <div> уровни на месте: один для передней части Вашего виджета и один для спины (который должен быть скрыт через CSS). Также необходимо включать a <div> для AppleInfoButton, помещенный в переднюю сторону виджета и a <div> для кнопки Done, помещенной в спину виджета. Пример кода ниже приводит скелет включая все эти элементы:

<body onload='setup();'>
 
    <div id="front">
 
        <!-- Your widget’s front side here -->
        <div id='infoButton'></div>
 
    </div>
 
    <div id="back">
 
        <!-- Your widget’s back side here -->
        <div id="doneButton"></div>
 
    </div>
 
</body>

Знаменитый onload обработчик, setup(). В разделе In Your JavaScript File, setup() создает объекты, обеспечивающие AppleInfoButton, используемый для зеркального отражения виджета к его спине, и AppleGlassButton, используемый, когда пользователь сделан, установив предпочтения. Для setup() функционируйте для работы правильно (подразумевать, что информация и стеклянные кнопки должным образом создаются), необходимо включать эти классы в HTML виджета:

<script type='text/javascript' src='/System/Library/WidgetResources/AppleClasses/AppleInfoButton.js' charset='utf-8'/>
<script type='text/javascript' src='/System/Library/WidgetResources/AppleClasses/AppleAnimator.js' charset='utf-8'/>
<script type='text/javascript' src='/System/Library/WidgetResources/AppleClasses/AppleButton.js' charset='utf-8'/>

Требуемые Классы Apple присутствуют на OS X v10.4.3 и более новый. При предназначении для виджета для более ранних версий OS X v10.4 считайте Введение в Классы Apple, чтобы изучить, как включать эти классы с обратной совместимостью в памяти.

В Вашем файле JavaScript

Часть JavaScript Вашего виджета должна включать код, зеркально отражающий Ваш виджет между его сторонами и создающий Информацию и Сделанные стеклянные кнопки.

Построение информации Apple и стеклянных кнопок

setup() функция, объявленная как виджет onload когда HTML виджета, CSS и файлы JavaScript загружаются, обработчик в его файле HTML, вызывается. В этой функции вызывают конструкторов для получения информации и кнопки Done:

var gDoneButton;
var gInfoButton;
 
function setup()
{
    gDoneButton = new AppleGlassButton(document.getElementById("doneButton"), "Done", hidePrefs);
    gInfoButton = new AppleInfoButton(document.getElementById("infoButton"), document.getElementById("front"), "white", "white", showPrefs);
}

Заметьте это, в дополнение к setup() функция, две глобальные переменные объявляются. Эти переменные соответствуют этим двум создаваемым кнопкам. Обычно, Вы хотите сохранить кнопки сохраненными как глобальные объекты так, чтобы можно было взаимодействовать с ними позже.

Затем, setup() вызовы функции конструкторы для AppleInfoButton и AppleGlassButton. Вспомните, что Ваш файл HTML включал необходимые классы для инстанцирования этих кнопок; setup() вызывается после того, как классы загружаются, и new вызов создает новые экземпляры каждого класса. Функции, следующие за новым вызовом, AppleGlassButton()и AppleInfoButton() конструкторы, берущие в параметрах, как элемент DOM, куда кнопка должна быть помещена или обработчик событий для щелчка по той кнопке. Последний параметр в обоих конструкторах является обработчиками, переворачивающими виджет; обработчики определяются в следующем разделе, Зеркально отражая Стороны. Конструктор возвращает ссылку на объект, представляющий кнопку. Полученные объекты присваиваются в глобальные переменные, указанные ранее. Теперь, когда кнопки создаются, можно использовать ранее заявленные глобальные переменные для взаимодействия с ними в любое время. например, Вы могли изменить цвет AppleInfoButton в любой точке путем вызова:

gInfoButton.setStyle("black","black");

Для больше на методах, доступных для AppleGlassButton, считайте Подкласс Кнопки Стекла Apple.

Зеркальное отражение сторон

Следующие функциональные переключатели Ваш виджет к его спине. Это определяется как Информационный обработчик событий Кнопки Apple в конструкторе кнопки в предшествующем разделе, Создавая Информацию Apple и Стеклянные Кнопки:

function showPrefs()
{
    var front = document.getElementById("front");
    var back = document.getElementById("back");
 
    if (window.widget)
        widget.prepareForTransition("ToBack");
 
    front.style.display="none";
    back.style.display="block";
 
    if (window.widget)
        setTimeout ('widget.performTransition();', 0);
}

Нажатие кнопки Info (определенный как <div id='infoButton'> в Вашем HTML и созданный в Вашем JavaScript), вызывает эту функцию, заставляющую спину быть выведенной на экран. В функции уровни передней и задней части получены и присвоены локальным переменным. Затем, widget.prepareForTransition("ToBack") замораживает текущий интерфейс, означая, что не показаны любые изменения в пользовательском интерфейсе Вашего виджета после этой точки. Передняя сторона тогда скрыта, и спина сделана активной. Наконец, переход выполняется, который зеркально отражает Ваш виджет с замороженным пользовательским интерфейсом на передней стороне перехода и интерфейса в настоящее время активного пользователя на спине.

(Как в стороне, Вы, возможно, заметили это setTimeout() используется для вызова performTransition(). Путем установки тайм-аута в 0, переход выполняется на следующем цикле событий, допуская стороны, которые будут подкачаны, прежде чем будет выполнен переход. Это - оптимизация, гарантирующая, чтобы обе стороны зеркально отраженного взгляда исправили.)

Сокрытие предпочтений и возврат Вашему основному интерфейсу пользователя выполняют подобную процедуру; обратите внимание на то, что эта функция была присвоена кнопке Done в ее конструкторе в предыдущем разделе, Создав Информацию Apple и Стеклянные Кнопки:

function hidePrefs()
{
    var front = document.getElementById("front");
    var back = document.getElementById("back");
 
    if (window.widget)
        widget.prepareForTransition("ToFront");
 
    back.style.display="none";
    front.style.display="block";
 
    if (window.widget)
        setTimeout ('widget.performTransition();', 0);
}

На сей раз, однако, задний уровень скрыт, и передний уровень показан. Метод widget.prepareForTransition("ToFront") замораживает текущий пользовательский интерфейс и гарантирует, что зеркально отраженный переход происходит в противоположном направлении как тогда, когда были показаны предпочтения.

В Вашем файле CSS

Теперь, когда у Вас есть передние и задние части, определенные для виджета, а также частей кнопки Info, необходимо использовать CSS, чтобы расположить их, установить их видимость и установить другие параметры:

#infoButton {
    position:absolute;
    bottom:12px;
    right:40px;
}
 
#front {
    display:block;
}
 
#back {
    display:none;
}
 
#doneButton {
    position:absolute;
    bottom:20px;
    left:82px;
}

Первый стиль касается кнопки Info. Это помещает кнопку в правом нижнем углу виджета.

Также знаменитый вот front и back стили, так как они устанавливают видимость сторон виджета. Когда виджет сначала открыт, его передняя сторона является просматриваемой стороной, таким образом, должна быть скрыта спина. Стили устанавливают переднюю сторону <div> быть видимым и скрывает спину <div>. Просматриваемое <div> изменяется с помощью кода JavaScript в следующем разделе.

Наконец, стиль, помещающий кнопку Done, включен.