Интерфейс iDoc
При разработке приложения для iPhone обязательно следует учесть тот факт, что они предназначаются для решения конкретных задач, а вовсе не являются универсальными функциями, предназначенными для всех жизненных ситуаций. С их помощью пользователь должен быстро и без применения дополнительных инструментов находить основную информацию о Java-классах, включая имена классов и методов, их сигнатуры и необходимые комментарии. В iDoc поддерживаются три уровня навигации, что позволяет переходить на итоговую страницу о нужных классах, предоставляющей детальную информацию.
Навигация на уровне пакетов предполагает просмотр пакетов, включающий данные только верхнего уровня.
Навигация на уровне классов является более подробной, в просмотр включены классы, интерфейсы, исключения, а также ошибки в пакетах.
Детализированная навигация на уровне классов предполагает просмотр полей, конструкторов и методов классов.
На итоговой странице содержатся комментарии к функциям, сигнатуры и параметры методов.
Для простоты восприятия из файлов iDoc исключены некоторые данные, присутствующие в стандартных файлах Javadoc, в связи с их недостаточной информативностью и функциональностью. К примеру, здесь полностью отсутствуют или не демонстрируются комментарии к объявлениям пакетов, поскольку они очень часто не являются источником полезных данных (так, показателем этого является «пакет acme.client», где содержится клиентский код).
Для каждого из трех уровней навигации применяются edge-to-edge-списки, т.е. растянутые на весь экран. Пользователи, которые работали с исконными приложениями iPhone, предназначенными, например, для просмотра контактов, электронных писем или музыки, знакомы с ними. В edge-to-edge-списках данные демонстрируются в виде строк высотой в 44 пикселя. Это особенно удобно, если требуется прокручивать большой объем данных. Информация о рекомендуемых параметрах, которые нужны для создания edge-to-edge-списков (сведения с названием и размером шрифта, интервалами и расстояниями между границами строк и т.д.), - имеются в руководстве по созданию интерфейсов для iPhone. С помощью CSS и JavaScript данные параметры поддерживаются в iUi, поэтому есть возможность создавать простые HTML-списки, которые в дальнейшем неотличимы от компонентов iPhone.
В листинге 1 приводится код страницы, где содержится заголовок и ссылки на два верхних уровня навигации по пакетам java.applet и java.rmi.
Листинг 1. Документ HTML, содержащий заголовок и два верхних уровня навигации
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>iDoc</title>
<meta name="viewport" content="width=320; initial-scale=1.0;
maximum-scale=1.0;
user-scalable=0;"/>
<style type="text/css" media="screen">@import
"iui/iui.css";</style>
<style type="text/css" media="screen">@import
"iDoc.css";</style>
<script type="application/x-javascript"
src="/iui/iui.js"></script>
</head>
<body onclick="console.log('Hello', event.target);">
<div class="toolbar">
<h1 id="pageTitle"></h1>
<a id="backButton" class="button"
href="#"></a>
</div>
<ul id="home" title="Packages" selected="true">
<li><a href="#java.applet">java.applet</a></li>
<!-- more packages...-->
<li><a href="#java.rmi">java.rmi</a></li>
</ul>
<ul id="java.applet" title="java.applet">
<li class="group">Interfaces</li>
<li><a href="/java.applet.AppletContext.html">
AppletContext</a></li>
<li><a href="/java.applet.AppletStub.html">
AppletStub</a></li>
<li><a href="/java.applet.AudioClip.html">
AudioClip</a></li>
<li class="group">Classes</li>
<li><a href="/java.applet.Applet.html">Applet
</a></li>
<li><a href="/java.applet.Applet.AccessibleApplet.html">
AccessibleApplet</a></li>
</ul>
<ul id="java.rmi" title="java.rmi">
<li class="group">Interfaces</li>
<li><a href="/java.rmi.Remote.html">
Remote</a></li>
<li class="group">Classes</li>
<li><a href="/java.rmi.MarshalledObject.html">
MarshalledObject</a></li>
<li><a href="/java.rmi.Naming.html">
Naming</a></li>
<li><a href="/java.rmi.RMISecurityManager.html">
RMISecurityManager</a></li>
<li class="group">Exceptions</li>
<li><a href="/java.rmi.AccessException.html">
AccessException</a></li>
<li><a href="/java.rmi.AlreadyBoundException.html">
AlreadyBoundException</a></li>
<li><a href="/java.rmi.ConnectException.html">
ConnectException</a></li>
<li><a href="/java.rmi.ConnectIOException.html">
ConnectIOException</a></li>
<li><a href="/java.rmi.MarshalException.html">
MarshalException</a></li>
<li><a href="/java.rmi.NoSuchObjectException.html">
NoSuchObjectException</a></li>
<li><a href="/java.rmi.NotBoundException.html">
NotBoundException</a></li>
<li><a href="/java.rmi.RemoteException.html">
RemoteException</a></li>
<li><a href="/java.rmi.RMISecurityException.html">
RMISecurityException</a></li>
<li><a href="/java.rmi.ServerError.html">
ServerError</a></li>
<li><a href="/java.rmi.ServerException.html">
ServerException</a></li>
<li><a href="/java.rmi.ServerRuntimeException.html">
ServerRuntimeException</a></li>
<li><a href="/java.rmi.StubNotFoundException.html">
StubNotFoundException</a></li>
<li><a href="/java.rmi.UnexpectedException.html">
UnexpectedException</a></li>
<li><a href="/java.rmi.UnknownHostException.html">
UnknownHostException</a></li>
<li><a href="/java.rmi.UnmarshalException.html">
UnmarshalException</a></li>
</ul>
Полученный в результате интерфейс Javadoc, выглядит как родной компонент приложения iPhone.
Навигация уровня пакетов в данном случае осуществляется с использованием одного edge-to-edge-списка, предназначенного для выбора пакетов верхнего уровня.
В режиме предварительного просмотра iPhone показывается содержимое пакета java.rmi, которое включает в себя демонстрацию интерфейсов, классов и исключений данного пакета.
Показ итоговой страницы, содержащей детальную информацию, будет осуществляться благодаря использованию еще одного стандартного виджета iPhone, а именно с помощью rounded-rectangle-списка, в котором содержатся прямоугольные блоки с закругленными углами. Такие списки часто встречаются в различных конфигурационных панелях, они удобны, если необходима группировка информации. Подобный виджет в iDoc служит для отделения сигнатур методов от списка параметров и исключений.
При создании web-приложения для iPhone необходимо расширить стандартную CSS, поскольку прямоугольно-закругленные списки в iUi версии 0.13 поддерживаются только в формах ввода, а при отображении статичного текста могут появиться некорректно отформатированные блоки. Во избежание подобных проблем в стандартную CSS добавляются описания из файла iDoc.css, к которым относится и элемент textRow, позволяющий вводить обычные текстовые строки внутри списка с прямоугольно-закругленными блоками. Порядок добавления нового строкового стиля в iUi показан в листинге 2.
Листинг 2. Элемент textRow, добавленный в CSS для корректного отображения статического текста
.textRow {
position: relative;
border-bottom: 1px solid #999999;
-webkit-border-radius: 0;
text-align: right;
}
.textRow > p {
text-align: left;
margin: 5px 8px 5px 10px;
padding: 0px 0px 0px 0px;
}
fieldset > .textRow:last-child {
border-bottom: none !important;
}
Код страницы, приведенный в листинге 3 и созданный с использованием стилей textRow , описывает один из конструкторов класса java.math.BigDecimal.
Листинг 3. HTML-код итоговой страницы
<div id="java.math.BigDecimal(long,java.math.MathContext)" title="BigDecimal"
class="panel">
<fieldset>
<div class="textRow"><p><b>
public BigDecimal(long, MathContext)</b></p></div>
<div class="textRow"><p>Translates a
<code>long</code> into a
<code>BigDecimal</code>, with rounding according to the context settings.
The scale of the <code>BigDecimal</code>, before any rounding, is zero.
</p></div>
</fieldset>
<h2>Parameters</h2>
<fieldset>
<div class="textRow"><p><b>long val
</b>: <code>long</code> value to be converted
to <code>BigDecimal</code>.</p></div>
<div class="textRow"><p><b>MathContext mc
</b>: the context to use.</p></div>
</fieldset>
<h2>Throws</h2>
<fieldset>
<div class="textRow"><p><b>ArithmeticException
</b>: if the result is inexact but
the rounding mode is <code>UNNECESSARY</code>.</p></div>
</fieldset>
</div>
Расположенный внутри тела <fieldset> текст построчно будет отображаться внутри закругленного прямоугольника, при этом элементы <div> со стилем textRow и будут выступать здесь в качестве строк. Заголовки, или элементы <h2> будут выводиться как названия групп внутри прямоугольников непосредственно над списками. Созданная страница детально будет отображать информацию о конструкторе класса java.math.BigDecimal.
Весь пользовательский интерфейс, в результате, будет состоять из трехуровневой навигации и итоговой страницы, где отобразится детализированная информация. iDoc внешне выглядит как родной продукт для iPhone благодаря инфраструктуре iUi и за счет дополнительной CSS-страницы. Он позволяет пользователю быстро совершать конкретные действия.