Программные интерфейсы (API) платформы Ubiq Mobile

Программные интерфейсы (API) платформы Ubiq Mobile
Структура приложения Ubiq Mobile
Приложения Ubiq Mobile выполняются в среде, которую обеспечивает сервер Ubiq Mobile. Для
каждого установленного экземпляра Ubiq Mobile SDK (и, значит, для каждой группы
разработчиков, работающих с этим экземпляром) при регистрации создается свой экземпляр
сервера («песочница»), на который разработчики могут загружать приложения в процессе их
разработки и отладки. Приложения, выполняющиеся на «песочнице», могут быть двух типов.
Первый тип представляют приложения, соответствующие сессиям мобильных пользователей
(«пользовательские приложения»). Они создаются при первом подключении мобильного
пользователя к серверу («песочнице») по соответствующему каналу. Другой тип – приложениясервисы, не связанные непосредственно с пользовательскими сессиями. Они запускаются при
первом обращении из пользовательского приложения и после этого существуют в системе
постоянно.
Каждое приложение Ubiq Mobile представляет собой компоненту (сборку в смысле .NET,
содержащую библиотеку классов), выполняющуюся на отдельном потоке, берущемся из пула
потоков (используется асинхронное программирование в рамках платформы .NET). Эта
компонента запускается сервером Ubiq Mobile либо при установлении соединения с мобильным
пользователем (если это пользовательское приложение), либо по запросу из пользовательского
приложения (если это приложение-сервис).
При отключении мобильного пользователя от сервера Ubiq Mobile или при разрыве мобильного
соединения, приложение, соответствующее сессии мобильного пользователя, продолжает
существовать в «свернутом» (suspended) состоянии в ожидании следующего подключения
пользователя. В этом состоянии могут накапливаться некоторые события (например, получение
приложением сообщений от других приложений), которые будут обработаны после
возобновления активности свернутого приложения. В то же время, мобильный пользователь
может отключиться от сервера специальным образом («завершить сессию»), при котором все
запущенные им приложения будут завершены.
Разработчик приложения может выполнить какие-то дополнительные действия в момент свертки
или завершения приложения, переопределив реакцию на соответствующее системное событие.
Понятно, что переопределенная реакция на свертку, отсоединение или завершение приложения
должна выполняться «мгновенно» с точки зрения приложения и не должна содержать ожидания
каких-то событий. По понятным причинам, эти события, скорее всего, не произойдут.
Если приложение было свернуто (suspended), то при последующем подключении этого
пользователя оно будет автоматически возобновлено (resumed). При возобновлении содержимое
экрана мобильного устройства восстанавливается в состояние, в котором оно было
непосредственно перед сверткой, и обрабатываются все накопившиеся за время свертки события.
При необходимости разработчик приложения может выполнить какие-то дополнительные
действия при возобновлении приложения (например, обновление изображения на экране),
переопределив реакцию на соответствующее событие.
Основной класс приложения должен являться наследником системного класса
Ubiq.Graphics.MExtendedThreadApp, а метод, который запускается при запуске приложения –
переопределенный виртуальный метод MainOverride (). Вся содержательная логика приложения
должна запускаться из этого метода.
Для корректной сборки и работы приложения Ubiq Mobile, в дополнение к стандартным,
необходимо указать следующие пространства имен:
using System.Threading.Tasks;
using Ubiq.Graphics;
using Ubiq.Attributes;
При генерации приложения из диаграммы модулей при помощи Ubiq Mobile SDK автоматически
порождаются два файла с исходным текстом. Первый из них, с именем <Имя_приложения>.cs,
содержит автоматически генерируемое описание основного класса приложения (наследника
MExtendedThreadApp), описания интерфейсов этого приложения с другими модулями (подробнее
об интерфейсах – в разделе InterfaceAPI) и автоматически генерируемые методы инициализации
служебных объектов. Вызываемый системой метод MainOverride () содержит вызовы методов
инициализации и вызов метода UserSection(), который содержится во втором генерируемом
файле, и куда разработчиком записывается содержательная логика приложения.
Второй файл, с именем UserSection.cs , представляет собой частичное описание основного класса
приложения и содержит описание метода UserSection (). С точки зрения программиста –
пользователя SDK, именно этот метод и должен считаться головным методов приложения и
именно этот метод должен содержать написанный вручную код. При всех перегенерациях
проекта в рамках SDK (которые могут быть вызваны, в частности, изменениями диаграммы
модулей), файл служебной секции <Имя_приложения>.cs каждый раз генерируется заново, а файл
UserSection.cs не изменяется. При необходимости, естественно, разрабатываемое приложение
может включать дополнительные файлы с описаниями других методов основного класса
приложения или описания других классов. Эти файлы вручную включаются разработчиком в
проект и при всех перегенерациях проекта остаются без изменений.
Исполняемая логика приложения должна быть организована в виде бесконечного цикла с
выходом в состояние ожидания (асинхронного) на каждом обороте цикла. Все действия,
выполняемые между двумя переходами в состояние ожидания, выполняются «мгновенно» с
точки зрения системы. Таким образом, они не должны содержать операций, связанных с
задержкой текущего потока (например, thread.sleep) или длительным ожиданием результата
операции (например, http запроса). На время любого ожидания, отличного от системного
ожидания, переход в которое происходит при вызове MExtendedThreadApp.Wait(), приложение
блокируется и обработка любых внешних событий не происходит.
Структура логики главной функции типичного приложения может выглядеть следующим образом:
protected async Task UserSection ()
{
< Инициализация >
for (;;)
{
< Действия, выполняемые в цикле >
await Wait ();
}
}
Вся обработка асинхронных событий (например, событий, приходящих от пользовательского
интерфейса мобильного клиента, событий, связанных с разрывом или восстановлением
соединений, событий таймера, асинхронного получения сообщений и т.д.) происходит внутри
метода Wait (). При программировании рекомендуется максимально облегчать обработчик
событий (в идеале – сводя все действия обработчика к сохранению необходимой информации в
локальных переменных), а содержательную обработку производить внутри основного цикла
обработки.
Для управления приложением и получения различной информации о нем предназначены ряд
виртуальных методов и свойств (properties) класса MExtendedThreadApp. Опишем некоторые из
них:
void OnSuspend () – виртуальный метод, вызываемый системой при свертке приложения,
например, при отключении мобильного клиента. Переопределяя этот метод в приложении,
можно задавать содержательные реакции на это событие в терминах пользовательского
приложения.
void OnDisconnect () – виртуальный метод, вызываемый системой при разрыве мобильного
соединения (в отличие от явного отключения клиента, при котором вызывается OnSuspend()).
Переопределяя этот метод, разработчик может задать собственную реакцию на это событие в
терминах своего приложения.
void OnResume () – виртуальный метод, вызываемый системой при возобновлении ранее
свернутого приложения (например, при повторном подключении мобильного клиента). При
возобновлении приложения автоматически восстанавливается содержимое экрана мобильного
устройства, которое было на момент отключения. Переопределяя метод OnResume (),
разработчик приложеия может задавать содержательные реакции на событие возобновления
приложения.
void OnScreenResizeEventOverride() – виртуальный метод, вызываемый системой при изменении
размеров экрана мобильного устройства при его повороте. Переопределяя этот метод,
разработчик может задать собственную реакцию на это событие в приложении – в частности,
переразместить управляющие элементы в соответствии с новой конфигурацией экрана.
this.Name – строковое свойство, содержащее имя приложения
UbiqEnvironment.BaseDirectory – строковое свойство, содержащее путь к папке на диске, куда
можно сохранять данные
this.Trace (string) – метод для вывода строки в протокол (log) сервера
this.Screen – вершина дерева графических управляющих элементов (controls)
API взаимодействия между приложениями (Interface API)
Взаимодействие между приложениями в системе Ubiq Mobile основано на обмене сообщениями.
Взаимодействовать могут как пользовательские приложения, обслуживающие сессии мобильных
пользователей, так и приложения-сервисы, в любых комбинациях. Для организации
взаимодействия между приложениями используются объекты специального класса
Ubiq.InterfaceAPI.UbiqInterface. Одно из участвующих во взаимодействии приложений создает
объект класса UbiqInterface в режиме публикации, после чего другие приложения могут
подписываться на этот интерфейс и получать возможность обмениваться через интерфейс
сообщениями. Идентификация интерфейсов происходит по строковым внешним именам, которые
должны быть уникальны на уровне сервера («песочницы»). Каждое приложение может
опубликовать один или более интерфейсов, и, в свою очередь, может быть подписанным на один
или несколько интерфейсов.
Для публикации интерфейса предназначен статический метод
UbiqInterface PublishInterface (MAPIApp app, string externalName, InterfaceAttr attrs)
где параметр app – ссылка на текущее приложение (нужно передать в качестве этого параметра
this), externalName – внешнее имя интерфейса, attrs – атрибуты интерфейса. Если в качестве
параметра attrs указать значение InterfaceAPI.InterfaceAttrs.None, то передача сообщений через
интерфейс будет возможна только в одну сторону – от приложения-подписчика к приложению,
опубликовавшему интерфейс. Если же указан атрибут InterfaceAPI.InterfaceAttrs.Duplex, то
передача сообщений через интерфейс будет возможна в обе стороны.
В качестве значения этот метод выдает ссылку на созданный и опубликованный интерфейс.
Для подписки приложения на интерфейс предназначен статический метод
UbiqInterface SubscribeInterface (MAPIApp app, string externalName)
где параметр app – ссылка на текущее приложение (в качестве этого параметра передается this), а
externalName – внешнее строковое имя интерфейса. В качестве значения этот метод выдает
ссылку на интерфейс, на который произошла подписка.
Интерфейсы предназначены для обмена сообщениями. Все передаваемые через интерфейсы
сообщения должны быть экземплярами классов - наследников системного класса
Ubiq.InterfaceAPI.IntMessage. Все свойства, методы и конструкторы этого класса являются
внутренними и не представляют интереса для разработчика приложения, за исключением метода
SendBack (), которые отправляет полученное сообщение по обратному адресу, тому приложению,
которое его послало.
Для посылки и получения сообщений используются следующие методы класса UbiqInterface:
IntMessage Ask (IntMessage msg) – синхронная посылка сообщения с ожиданием ответа.
Сообщение msg посылается через данный интерфейс и выполнение текущего приложения
задерживается до получения ответа (который может быть послан, например, посредством метода
SendBack () ).
void Send (IntMessage msg) – асинхронная посылка сообщения. Сообщение msg посылается через
данный интерфейс и выполнение текущего приложения продолжается.
Получение сообщений (если это не ответы на посланные через Ask сообщения) выполняется
асинхронно; при получении сообщения вызывается событие
event TypedEventHandler<UbiqInterface, EventArgs<IntMessage>> MessageReceived
параметром которого является получаемое сообщение. Определяя обработчики этого события,
можно обрабатывать получение сообщений.
При использовании Ubiq Mobile SDK можно определять интерфейсы компонент, входящих в
разрабатываемое приложение, на этапе проектирования компонентной архитектуры при помощи
дизайнера компонент. Для каждой вновь разрабатываемой (не библиотечной) компоненты
можно как задать публикуемые интерфейсы, так и определить связи (подписку) на интерфейсы,
публикуемые другими модулями. Основные параметры каждого интерфейса также могут быть
заданы на уровне дизайнера архитектуры. Для библиотечных компонент параметры и свойства
публикуемых интерфейсов определяются их реализацией. В процессе генерации решения
(solution) по диаграмме компонент автоматически генерируются описания всех описанных
интерфейсов. Они помещаются в стандартный автогенерируемый файл <Имя_приложения>.cs,
который обновляется при каждой перегенерации.
API взаимодействия мобильных пользователей (Dispatcher API)
Для решения задач, связанных с обеспечением взаимодействия между пользователями
мобильных приложений в системе Ubiq Mobile, возможно использование прикладного
интерфейса компоненты диспетчеризации (DispatcherAPI).
Логика работы с интерфейсом
Логическая модель взаимодействия пользователей через интерфейс диспетчера опирается на два
основополагающих класса сущностей: пользователь (user) и диалог (dialog), представляющие,
соответственно, пользователей мобильных приложений и соединения между ними. В рамках
диалогов пользователи могут обмениваться сообщениями. В системе поддерживаются диалоги с
любым количеством участников (как один-к-одному, так и многие-ко-многим). Также в рамках
диалога возможно «подписывать» пользователя на уведомления об изменении статуса другого
пользователя. Любые изменения статуса пользователя и информации, связанной с пользователем
в приложении, могут порождать подобные уведомления.
Объект класса пользователь позволяет хранить следующие данные:





Имя пользователя (UserName)
Идентификатор (UserID)
Пароль (Password)
Статус (UserStatus)
Объект хранения дополнительной информации (UserInfo object) – может содержать
произвольные данные в зависимости от конкретного приложения (личный счет в игровом
приложении и т.д.)
Объект класса диалог позволяет хранить следующие данные:



Идентификатор (DialogID)
Статус (DialogStatus)
Объект хранения дополнительной информации (DialogInfo object) – может содержать
произвольные данные в зависимости от конкретного приложения (история сообщений в
чате и т.д.)
Диспетчер представляет собой сервисное приложение, запускаемое в отдельном потоке. Для
различных приложений могут быть запущены отдельные экземпляры компоненты диспетчера.
Для взаимодействия с экземпляром диспетчера в приложении необходимо локально создать
объект интерфейса диспетчера и вызывать его методы (каждый вызов метода интерфейса
инициирует отправку сообщения в соответствующий экземпляр диспетчера, и возвращает либо
запрошенные данные, либо код ошибки). На каждое асинхронное сообщение от диспетчера
создается соответствующее асинхронное событие в интерфейсе, для которого можно определить
собственный обработчик в рамках приложения.
Методы интерфейса диспетчера реализуют следующие группы функций:




Авторизация и регистрация пользователей
Работа с данными пользователя
Работа с диалогами
Межпользовательское взаимодействие
Свойства интерфейса диспетчера
Свойства доступны после создания
Имя
свойства
UserName
UserId
Password
_lastError
Тип
Описание
String Имя текущего пользователя. Сохраняется при регистрации или
авторизации и до конца сессии пользователя.
Int
Идентификатор пользователя.
String Пароль.
int
Код последней ошибки.
События интерфейса диспетчера
В приложении можно создавать обработчики указанных ниже событий диспетчера, например так:
dispatcherAPI.DialogInvite += new DialogInviteEvent(
// Your code here
);
Событие
MessageRecieve
Тип
MessageEvent
UserUpdate
UserInfoEvent
UserSubscribe
UserEvent
UserUnsubscribe
DialogInvite
DialogReject
DialogUserAdd
DialogUserRemove
DialogRemove
Параметры
int dialogId,
int userId,
object message
UserInfo userInfo
int userId,
object info
UserEvent
int userId,
object info
DialogInviteEvent int dialogId,
int userId,
object message
DialogInviteEvent int dialogId,
int userId,
object message
DialogUserEvent int dialogId,
int userId
DialogUserEvent int dialogId,
int userId
DialogEvent
int dialogId,
object info
Описание
Получено входящее сообщение от
другого пользователя.
Пользователь обновил информацию
о себе.
Пользователь пытается подписаться
на обновления.
Пользователь пытается отписаться
от обновлений.
Пришло приглашение на включение
в диалог.
Пользователь отклонил
приглашение на включение в
диалог.
Пользователь принял приглашение
и присоединился к диалогу.
Пользователь был удален из
диалога.
Диалог был удален.
Методы интерфейса диспетчера
Метод
Параметры
DispatcherAPI
MAPIApp app – ссылка на
приложение, которое пытается
создать экземпляр интерфейса
диспетчера,
string boxName – название почты
экземпляра диспетчера
string userName – имя
пользователя,
string password - пароль,
object info – данные
пользователя специфичные для
данного приложения
Register
Возвращаемое
значение
Объект
интерфейса
диспетчера.
Описание
True в случае
успешной
регистрации,
иначе false
Регистрация нового
пользователя в
системе по имени с
заданием пароля.
Создает новый
экземпляр интерфейса
диспетчера для
переданного потока
приложения.
Register
string userName – имя
пользователя,
object info – данные
пользователя специфичные для
данного приложения
Login
True в случае
успешной
авторизации,
иначе false
Login
string userName – имя
пользователя,
string password – пароль
Login
string userName – имя
пользователя
AutoLogin
string userName – имя
пользователя,
string password - пароль,
object info – данные
пользователя специфичные для
данного приложения
AutoLogin
string userName – имя
пользователя,
object info – данные
пользователя специфичные для
данного приложения
Logoff
True в случае
успешной
авторизации,
иначе false
True в случае
успешной
авторизации,
иначе false
True в случае
успешной
авторизации /
регистрации,
иначе false
True в случае
успешной
авторизации /
регистрации,
иначе false
True в случае
успешной
деавторизации
, иначе false
GetUserInfo
string userName – имя
пользователя
GetUserInfo
Int userId – идентификатор
пользователя
Suspend
True в случае
успешной
регистрации,
иначе false
UserInfo с
информацией
о пользователе
или null
UserInfo с
информацией
о пользователе
или null
True в случае
успешной
смены
состояния,
иначе false
Регистрация нового
пользователя в
системе по имени.
Пароль задается по
умолчанию.
Авторизация
пользователя по
идентификатору
клиентского
устройства.
Авторизация
пользователя по
имени и паролю.
Авторизация
пользователя по
имени (пароль по
умолчанию).
Авторизация
пользователя по
имени и паролю, если
он зарегистрирован в
системе. Иначе,
регистрация нового
пользователя по
имени и паролю.
Авторизация
пользователя по
имени, если он
зарегистрирован в
системе. Иначе,
регистрация нового
пользователя по
имени.
Деавторизация
пользователя по
идентификатору
клиентского
устройства.
Возвращает
информацию о
пользователе по его
имени.
Возвращает
информацию о
пользователе по его
идентификатору.
Переводит
пользователя в
состояние "Suspend".
Используется, когда
приложение должно
Resume
UpdateUserInfo
object info – данные
пользователя специфичные для
данного приложения
SubscribeToUser
Int userId – идентификатор
пользователя, на обновление
которого необходимо
подписаться,
object info – дополнительная
информация о подписке
string userName – имя
пользователя, на обновление
которого необходимо
подписаться,
object info – дополнительная
информация о подписке
Int userId – идентификатор
пользователя, от обновлений
которого необходимо
отписаться,
object info – дополнительная
информация о подписке
Int userId – идентификатор
приглашаемого в диалог
пользователя,
object info – дополнительная
информация о приглашении
string userName – имя
приглашаемого в диалог
пользователя,
object info – дополнительная
информация о приглашении
Int userId – идентификатор
приглашаемого в диалог
пользователя,
Int dialogId – идентификатор
диалога,
object info – дополнительная
информация о приглашении
string userName – имя
приглашаемого в диалог
пользователя,
int dialogId – идентификатор
диалога,
SubscribeToUser
UnsubscribeFrom
User
InviteUser
InviteUser
InviteUser
InviteUser
True в случае
успешной
смены
состояния,
иначе false
True в случае
успешного
обновления,
иначе false
True в случае
успешного
создания
подписки,
иначе false
быть временно
"свернуто".
Восстанавливает
пользователя из
состояния "Suspend".
Обновляет
специфичные для
данного приложения
данные текущего
пользователя
Создает подписку на
обновления
пользователя.
True в случае
успешного
создания
подписки,
иначе false
Создает подписку на
обновления
пользователя.
True в случае
успешного
удаления
подписки,
иначе false
Удаляет подписку на
обновления
указанного
пользователя.
Идентификатор
диалога или -1
Приглашает
пользователя для
участия в диалоге по
его идентификатору и
создает диалог.
Приглашает
пользователя для
участия в диалоге по
его имени и создает
диалог.
Приглашает
пользователя для
участия в указанном
диалоге по его
идентификатору.
Идентификатор
диалога или -1
Идентификатор
диалога или -1
Идентификатор
диалога или -1
Приглашает
пользователя для
участия в указанном
диалоге по его имени.
RejectInvitation
JoinDialog
object info – дополнительная
информация о приглашении
Int userId – идентификатор
пригласившего в диалог
пользователя,
Int dialogId – идентификатор
диалога,
object info – дополнительная
информация о приглашении
Int dialogId – идентификатор
диалога
RemoveFromDial
og
Int dialogId – идентификатор
диалога
RemoveDialog
Int dialogId – идентификатор
диалога
UpdateDialogInf
o
Int dialogId – идентификатор
диалога,
object info – дополнительная
информация о диалоге
SendMessage
Int dialogId – идентификатор
диалога,
string message – сообщение
UserQueryType type – тип
искомых пользователей
GetUserList
Отклоняет
приглашение в диалог
True в случае
успешного
включения в
диалог, иначе
false
True в случае
успешного
удаления
диалога, иначе
false
True в случае
успешного
обновления
диалога, иначе
false
List<UserInfo> список
объектов
данных
пользователей
Присоединяет
текущего
пользователя к
диалогу.
Удаляет текущего
пользователя из
диалога.
Удаляет диалог
Обновляет объект с
дополнительной
информацией о
диалоге.
Отправляет
сообщение всем
участникам диалога.
Возвращает список
пользователей,
запрашиваемого типа
API аутентификации
Для решения задач, связанных с обеспечением разделенного и безопасного доступа к данным
пользователя, а также ресурсам, функциям и данным мобильного приложения в системе Ubiq
Mobile, возможно использование прикладного интерфейса компоненты аутентификации
(AuthenticationAPI).
Логика работы с интерфейсом
Интерфейс аутентификации может быть подключен в двух типах приложений:


В приложениях-сервисах, не связанных непосредственно с пользовательскими сессиями.
Они запускаются при первом обращении из пользовательского приложения и после этого
существуют в системе постоянно. В этом случае необходимо использовать интерфейс
аутентификации для сервисов (ServiceAPI).
В приложениях, соответствующих сессиям мобильных пользователей («пользовательские
приложения»). Они создаются при первом подключении мобильного пользователя к
серверу («песочнице») по соответствующему каналу. В этом случае следует использовать
один из интерфейсов аутентификации клиента.
Существует два типа интерфейсов аутентификации клиентов:


Пользовательский (ClientAPI) – предоставляет возможности работы с аутентификацией на
уровне пользователя.
Административный (ClientAdminAPI) – предоставляет возможности работы с
аутентификацией на уровне администратора.
Кроме того, для всех указанных выше интерфейсов существует базисный набор функций
интерфейса аутентификации (AuthServiceAPI).
Для реализации работы аутентификации в приложении можно использовать один из трех
подходов, каждый из которых использует соответствующий протокол:



Внутренняя аутентификация. При этом данные пользователей будут хранится в базе на
серверной стороне.
Внешняя аутентификация через vkontakte. При этом будет происходит подключение к
интерфейсу аутентификации, который предоставляет vkontakte. Для авторизации
необходимо использовать данные учетных записей vkontakte.
Внешняя аутентификация через подключение произвольного провайдера сервиса
аутентификации, реализующего протокол OpenAuth 2.0.
Для работы с интерфейсом аутентификации необходимо создать экземпляр объекта интерфейса
аутентификации в коде приложения и подписаться на события интерфейса, чтобы получать
уведомления об изменениях данных пользователя. После этого можно вызывать методы
интерфейса (логин, регистрация и т.д.), при этом будут отправляться асинхронные сообщения в
компонент аутентификации.
Свойства интерфейса аутентификации ClientAPI
Имя
свойства
CurToken
Logged
Тип
Описание
Token
Bool
Содержит данные текущего подключения
Статус авторизации текущего экземпляра интерфейса
События интерфейса аутентификации ClientAPI
Событие
onLogOut
onDelete
onPasswordChange
onPasswordForce
Тип
onAuthAPIEvent
onAuthAPIEvent
onAuthAPIEvent
onAuthAPIEvent
Описание
Пользователь деавторизован
Пользователь удален
Пароль изменен
Необходимо сменить пароль
Методы интерфейса аутентификации ClientAPI
Метод
Параметры
ClientAuthAPI
MAPIApp app – ссылка на
приложение, в котором
создается экземпляр интерфейса
AuthObject target – объект базы
пользователей,
string name – имя пользователя,
string password – пароль
LogIn
LonIn
AuthObject target – объект базы
пользователей,
Возвращаемое
значение
Ссылка на
объект
интерфейса
True, если вход
был успешен,
иначе false,
ошибка в
LastAuthError,
токен в
CurToken
True, если вход
был успешен,
Описание
Создает экземпляр
интерфейса для
текущего приложения
Авторизация в рамках
указанной базы
пользователей по
имени и паролю
Авторизация в рамках
указанной базы
Int userId – идентификатор
пользователя,
string password – пароль
LogIn
AuthObject target – объект базы
пользователей
LogInForUID
AuthObject target – объект базы
пользователей,
Int clientId – идентификатор
клиентского приложения
LogOut
AuthObject target – объект базы
пользователей
UnRegistration
AuthObject target – объект базы
пользователей
SetPassword
AuthObject target – объект базы
пользователей,
string newPassword – новый
пароль
IsLogged
AuthObject target – объект базы
пользователей
IsForced
AuthObject target – объект базы
пользователей
иначе false,
ошибка в
LastAuthError,
токен в
CurToken
True, если вход
был успешен,
иначе false,
ошибка в
LastAuthError,
токен в
CurToken
Int UserId, если
вход был
успешен, иначе
-1, ошибка
будет в
LastAuthError
True, если
выход был
успешен, иначе
false, ошибка
будет в
LastAuthError
True, если
удаление было
успешно, иначе
false, ошибка
будет в
LastAuthError
True, если
пароль был
изменен, иначе
false, ошибка
будет в
LastAuthError
True, если
подан, иначе
false, ошибка
будет в
LastTestResult
True, если
подан, иначе
false, ошибка
будет в
LastTestResult
пользователей по
идентификатору и
паролю
Авторизация в рамках
указанной базы
пользователей по
идентификатору
клиентского
приложения
Авторизация в рамках
указанной базы
пользователей по
идентификатору
клиентского
приложения с
получением userId
Деавторизация
пользователя из
указанной базы
Удаление
пользователя из
указанной базы
Установка нового
пароля для
пользователя в
указанной базе
Функция для
проверки, подан ли
пользователю запрос
на смену пароля при
следующем входе
Функция для
проверки, подан ли
пользователю запрос
на смену пароля при
следующем входе
Свойства интерфейса аутентификации AuthServiceAPI
Имя свойства
LastAuthError
Тип
AuthError
Описание
Последняя ошибка методов LogIn, LogOut, UnRegistration и
SetPassword.
Коды ошибок:
 DataBaseUnknownError = 0,
 NotInternalUser = 1,
 NotExternalUser = 2,
 FeatureNotSupported = 3,
 NoError = 10,
 TokenExpired = 11,
 WrongNameOrPassword = 20,
 WrongUserIdOrPassword = 21,
 ClientIsNotLogged = 22,
 AlreadyLoggedIn = 23,
 NotLoggedIn = 24,
 ExternalAuthServiceError = 25,
 WrongToken = 26
LastRegError
RegError
Последняя ошибка метода Registration
Коды ошибок:
 DataBaseUnknownError = 0,
 NotInternalUser = 1,
 NotExternalUser = 2,
 FeatureNotSupported = 3,
 NoError = 10,
 WrongName = 20,
 WrongPassword = 21,
 AlreadyRegistered = 22
LastTestResult
TestResult Последняя ошибка методов IsLogged и IsForced
Коды ошибок:
 DataBaseUnknownError = 0,
 NotInternalUser = 1,
 NotExternalUser = 2,
 FeatureNotSupported = 3,
 TokenExpired = 11,
 True = 20,
 False = 21,
 NoSuchUser = 22
DeveloperName string
Имя разработчика приложения, используется для именования
базы пользователей при использовании внутренней авторизации.
Методы интерфейса аутентификации AuthServiceAPI
Метод
Параметры
GenerateTarget
String target – имя внутренней
базы пользователей
GenerateTarget
String baseName – имя внешней
базы пользователей,
AuthTargetType target – тип
подключения
TryRegistrateOA
uth2Provider
string ProviderName – название
провайдера,
Возвращаемое
значение
AuthObject
указатель на
базу
пользователей
или null в случае
ошибки
AuthObject
указатель на
базу
пользователей
или null в случае
ошибки
AuthObject
указатель на
базу
Описание
Возвращает указатель
на базу пользователей
по имени внутренней
базы.
Возвращает указатель
на базу пользователей
по имени базы и типу
внешнего
подключения.
Регистрация
провайдера OAuth2
Registration
RedirectParser redirectParser –
обработчик редиректов,
string OAuthLoginForCodeURL –
адрес логина для кода,
string OAuthCodeForTokenURL –
адрес для токена,
string OAuthRedirectURL – адрес
финального редиректа,
string clientId – идентификатор
клиентского приложения
AuthObject target – объект базы
пользователей,
String name – имя
пользователя,
String password – пароль
IsLogged
AuthObject target – объект базы
пользователей,
String name – имя пользователя
IsLogged
AuthObject target – объект базы
пользователей,
Int userId – идентификатор
пользователя
AuthObject target – объект базы
пользователей,
Token token – объект данных
текущего подключения
AuthObject target – объект базы
пользователей,
String name – имя пользователя
IsLogged
GetUserId
пользователей
или null в случае
ошибки
True, если
регистрация
была успешна,
иначе false,
ошибка будет в
LastRegError
True, если online,
иначе false,
ошибка будет в
LastTestResult
True, если online,
инаTYtче false,
ошибка будет в
LastTestResult
True, если online,
иначе false,
ошибка будет в
LastTestResult
UserId, если
пользователь
был найден,
иначе -1, ошибка
будет в
LastAuthError
Регистрация нового
пользователя в базе
Проверка статуса
авторизации
пользователя по
имени
Проверка статуса
авторизации
пользователя по
идентификатору
Проверка статуса
авторизации
пользователя по
токену
Получение
идентификатора
пользователя по
имени
Графический интерфейс (графическое API)
Программный интерфейс графической подсистемы (графическое API) предназначен для
реализации пользовательских интерфейсов приложений Ubiq Mobile на клиентских мобильных
устройствах. Это единственный способ реализации UI для приложений Ubiq Mobile: стандартные
средства реализации интерфейсов .NET для десктопных или web-приложений не могут
использоваться в рамках платформы Ubiq Mobile.
Графическая подсистема Ubiq Mobile имеет традиционную для современных графических пакетов
структуру: изображения, предназначенный для вывода на экран мобильного устройства,
представляют собой иерархическое дерево объектов – графических элементов (controls). Корнем
дерева служит объект класса Screen, описывающий экран мобильного устройства; листья дерева –
конечные элементы, имеющие графическое представление и отрисовываемые на экране; на
промежуточных уровнях находятся контейнеры и панели - графические элементы, отвечающие за
размещение и масштабирование других элементов. Размеры и размещение элементов могут
задаваться либо явно, либо (что происходит чаще) неявно; неявное задание размеров и
размещения элементов облегчает адаптацию изображений к экранам различных графических
устройств различных размеров и формы.
Платформа Ubiq Mobile поддерживает две различных модели взаимодействия с клиентскими
устройствами: для относительно простых устройств реализована так называемая Basic-модель
интерфейса, при которой основная часть отрисовки и размещения элементов выполняется на
сервере, а на экран мобильного устройства передаются фрагменты уже сформированных
изображений. Только «активные» элементы, с которыми пользователь может выполнять какие-то
действия (кнопки, поля ввода, выпадающие списки для выбора элементов и т.д.), передаются на
мобильное устройство и отрисовыватся на экране клиентскими средствами.
Для смартфонов с богатыми интерфейсными возможностями используется другая модель
интерфейса – Native-Basic. В рамках этой модели с сервера на клиентское мобильное устройство
передаются фрагменты дерева управляющих элементов, и все размещение элементов и их
отрисовка на экране происходит исключительно средствами мобильного клиента. Это позволяет
сделать внешний вид отрисовываемых элементов максимально «нативным», выглядящим
традиционно для данной мобильной платформы. Кроме того, посылка фрагментов дерева вместо
прямоугольных элементов изображений экономит мобильный трафик.
Для формирования изображения на экране клиентского мобильного устройства необходимо
сформировать дерево графических элементов с корнем – объектом класса Screen. Вывод
сформированного дерева на экран будет выполняться автоматически при переходе в режим
ожидания. Точно так же, при изменениях дерева оно (целиком или его фрагменты) автоматически
будет перевыводиться при очередном переходе приложения в состояние ожидания.
Формирование дерева графических элементов может быть выполнено статически (для этого у
большинства элементов предусмотрены конструкторы без параметров), либо, при
необходимости, отдельные элементы или свойства элементов могут формироваться
динамически. Динамически также определяются обработчики событий для входящих в дерево
активных управляющих элементов.
Пример статического определения дерева управляющих элементов (содержимого экрана) –
используемые в примере типы графических элементов, их свойства и значения этих свойств
описаны ниже, в соответствующих разделах документа:
Screen.Content =
new TextBlock
{
VerticalAlignment=VerticalAlignment.Center,
HorizontalAlignment=HorizontalAlignment.Center,
Foregrouund = new SolidColorBrush (Colors.Blue),
Font = new Font (new FontFamily (“Arial”),
Screen.LargeFontSize,
FontStyle.Bold | FontStyle.Italic),
Text = “Hello”
};
Пример динамического задания содержимого экрана:
var OKButton =
new Button
{
Height = 2.5 * Screen.NormalFontSize,
Padding = new Thickness (20, 5, 5, 20),
HorizontalAlignment = HorizontalAlignment.Center,
Font = new Font (new FontFamily (“Arial”),
Screen.NormalFontSize,
FontStyle.Bold),
Text = “OK”,
WrapContentH = true
};
OKButton.Pressed += (s, e)=> OnOkButtonPressed(); //Обработчик
var CancelButton =
new Button
{
Height = 2.5 * Screen.NormalFontSize,
Padding = new Thickness (20, 5, 5, 20),
HorizontalAlignment = HorizontalAlignment.Center,
Font = new Font (new FontFamily (“Arial”),
Screen.NormalFontSize,
FontStyle.Bold),
Text = “Cancel”,
WrapContentH = true
};
CancelButton.Pressed += (s, e) => OnCancelButtonPressed // Обработчик
Screen.Content =
new StackPanel
{
Children =
{
new TextBlock
{
VerticalAlignment=VerticalAlignment.Center,
HorizontalAlignment=HorizontalAlignment.Center,
Foreground = new SolidColorBrush (Colors.Blue),
Font = new Font (new FontFamily (“Arial”),
Screen.LargeFontSize,
FontStyle.Bold | FontStyle.Italic),
Text = “Are you sure”
},
new StackPanel
{
VerticalAlignment = VerticalAlignment.Bottom,
Orientation = Orientation.Horizontal,
WrapContentV = true,
Children = { OKButton, CancelButton }
}
}
}
В этом примере отдельно описываются две кнопки, определяются реакции на них, а затем
формируется общее изображение, состоящее из текста и горизонтальной панели из двух кнопок.
Типы графических элементов и их общие параметры
Графические элементы бывают следующих типов:





Элемент класса Screen, представляющий экран клиентского устройства – по сравнению с
другими элементами, он обладает рядом специфических свойств
Панели – элементы, как правило, не имеющие непосредственного графического
представления, предназначенные для организации размещения других элементов
Контейнеры – элементы, как правило, не имеющие самостоятельного графического
представления и содержащие внутри себя другие элементы. «Оборачивание» элемента в
контейнер расширяет свойства элемента свойствами контейнера-обертки. В некоторых
случаях контейнеры могут выступать в роли панелей, т.е., служить для управления
размещением и масштабированием элементов.
Конечные графические элементы (leaf controls) – разнообразные элементы, имеющие
графическое представление и, как правило, не содержащие внутри себя других элементов.
Могут быть как активными (с которыми пользователь мобильного клиента может
выполнять какие-то действия), так и пассивными. Примеры активных элементов – поле
ввода, «галочка» (checkbox), кнопка и т.д. Примеры пассивных элементов – текстовый
фрагмент или картинка.
Простые формы – это конечные графические элементы, предназначенные для
представления элементарных графических объектов – линий, эллипсов, прямоугольников
и т.д.
Все графические элементы (за исключением, в некоторых случаях, элементов класса Screen)
имеют ряд общих свойств (properties).
Размер
Каждый графический элемент занимает некоторую прямоугольную область, размер элемента –
это размер этого прямоугольника. Размеры элементов могут задаваться как явно, так и неявно и
определяются отдельно по каждому измерению. Размер задается явно через два
предопределенных свойства формата double – Width и Height. Если значение Width или Height
отлично от нуля, это означает, что размер по соответствующему измерению задан явно – в
пикселах. Если же значение нулевое, это означает, что размер по соответствующему измерению
задается неявно и определяется одним из двух способов:


FillParent – размер элемента определяется размером пространства, которое ему может
выделить объемлющий элемент (элемент «заполняет» пространство, выделенное
элементом – «родителем»)
WrapContent – размер элемента определяется его внутренним содержимым – элемент
«оборачивает» внутреннее содержимое.
По умолчанию, если значение размера не задано, считается, что оно определяется как FillParent.
Если же необходимо задание размера как WrapContent, необходимо установить одно из
следующих свойств элемента в true:
WrapContentH = true горизонтальный размер определяется как WrapContent
WrapContentV = true вертикальный размер определяется как WrapContent
WrapContent = true
оба размера определяются как WrapContent.
Следует отметить, что признак WrapContent распространяется «вниз» по дереву графических
элементов: если для некоторого элемента задан признак WrapContent, то для всех элементов, для
которых он является родителем, если не задан явный размер, принудительно устанавливается
признак WrapContent по соответствующему измерению.
Размещение
Размещение элементов задается относительно объемлющих элементов отдельно по горизонтали
и вертикали. Для этого служат свойства HorizontalAlignment и VerticalAlignment.
HotizontalAlignment может принимать значения Ubiq.Graphics.HorizontalAlignment.Left,
Ubiq.Graphics.HorizontalAlignment.Center и Ubiq.Graphics.HorizontalAlignment.Right.
VerticalAlignnment может принимать значения Ubiq.Graphics.VerticalAlignment.Top,
Ubiq.Graphics.VerticalAlignment.Center и Ubiq.Graphics.VerticalAlignment.Bottom.
Абсолютное размещение элементов (с заданием позиции элемента в пикселах) может задавать
только в одной ситуации – когда элементы размещаются внутри панели типа OverlayPanel.
Размещение элементов в этой панели может задаваться как при помощи HorizontalAlignment или
VerticalAlignment, так и явно при помощи свойства Origin, значения которого задают пары
координат (double x, double y) в пикселах. Во всех остальных случаях задание параметра Origin не
оказывает влияния на размещения элементов.
Отступы
У каждого элемента может быть задан внешний отступ (Margin) и внутренний отступ (Padding).
Внешний отступ определяет набор интервалов (слева, сверху, справа и снизу) от границ
размещения данного элемента до границ объемлющего пространства, выделенного элементом –
«родителем». Внутренний отступ определяет четверку интервалов от границ размещения данного
элемента до границ его внутреннего содержимого. Для некоторых элементов отступы могут не
иметь смысла (например, внешний отступ для Screen или внутренний отступ для простой формы –
линии) и, соответственно, не быть определены.
Величины отступов задаются при помощи структуры Thickness, содержащей четверку значений
типа double, которые представляют, соответственно, отступы слева, сверху, справа и снизу. У этой
структуры предусмотрены два конструктора – Thickness (double Left, double Top, double Right,
double Bottom) и Thickness (double th). Второй вариант конструктора используется, если значения
отступов по всем направлениям одни и те же. Внешние отступы задаются через свойство Margin, а
внутренние отступы – через свойство Padding. Оба эти свойства имеют тип Thickness.
Фон
Для большинства элементов может быть задан фон, которым заполняется соответствующая
элементу прямоугольная область перед отрисовкой самого элемента. Для отрисовки фона
задается специальный объект – кисть (Brush), которая может быть одного из следующих типов:



Кисть фиксированного цвета (SolidBrush) – заполняет фон заданным фиксированным
цветом. Если фон не задан, то считается, что он заполняется прозрачным цветом.
При создании экземпляра кисти этого типа в конструктор должен быть передан параметр
типа Ubiq.Graphics.Color, определяющий цвет кисти. Основные значения цветов собраны в
классе Ubiq.Graphics.Colors в качестве статических элементов.
Градиентная кисть (LinearGradientBrush) – заполняет фон линейным градиентом.
Направление градиента может быть горизонтальным, вертикальным или одним из двух
диагональных. Опорных цветов может быть два или больше. Для создания экземпляров
градиентной кисти предусмотрены два конструктора:
GradientBrush (Ubiq.Graphics.Color c1, Ubiq.Graphics.Color c2, Ubiq.Graphics.LineDirection d)
Здесь с1 и с2 – начальный и конечный цвета, d – направление градиента, которое может
принимать значения LineDirection.Hoirizontal, LineDirection.Vertical,
LineDirection.DiagonalUp, LineDirection.DiagonalDown.
Другой конструктор –
GradientBrush(List<Ubiq.Graphics.Color> colors, List<double>offets, Ubiq.Graphics.LineDirection
d) - в этом конструкторе задается список опорных цветов и соответствующий ему список
смещений – вещественных чисел в диапазоне от 0 до 1, определяющий точки смены
цветов в градиенте. Направление градиента задается так же, как и в предыдущем случае.
Растровая кисть (ImageBrush) – заполняет фон заданным растровым изображением. При
заполнении прямоугольной области изображение может растягиваться под размеры
области (Scale), выкладываться «плиткой» (Tile) или никак не преобразовываться (None).
Для создания экземпляров такой кисти предусмотрены два конструктора:
ImageBrush (Ubiq.Graphics.Image) – создает кисть на основе изображения, представленного
в виде объекта класса Ubiq.Graphics.Image. Подробнее этот класс описан в разделе,
посвященном описанию графического элемента ImageBlock. При заполнении
прямоугольной области созданной с помощью этого конструктора кистью преобразования
изображения не происходит.
ImageBrush(Ubiq.Graphics.Image img, Ubiq.Graphics.WrapMode wrapMode) – другой вариант
конструктора, имеющий дополнительный параметр для задания способа преобразования
изображения. Этот параметр может иметь значения UbiqGraphics.WrapMode.None,
Ubiq.Graphics.WrapMode.Scale и Ubiq.Graphics.WrapMode.Tile.
Описания графических элементов
Screen
Элемент Screen описывает экран, являющийся корнем элементом дерева графических элементов.
Все остальные управляющие элементы являются его прямыми или непрямыми потомками.
В каждом приложении Ubiq Mobile, использующем графику, экран существует в единственном
экземпляре и создается при инициализации графической среды приложения. Для инициализации
экрана из приложения служит метод Init (), который по умолчанию определяет физический
размер экрана, соответствующий физическому размеру клиентского устройства. Этот метод
является перегруженным, существуют несколько других вариантов метода Init(), позволяющие
явно задавать размеры и другие свойства экрана.
Свойства HorizontalSizingType, VerticalSizingType, WrapContent и Background аналогичны
соответствующим свойствам для всех управляющих элементов. Свойство Margin для экрана не
используется. Padding, как и для других управляющих элементов, определяет отступы от краев
экрана до его содержимого. Свойства Height и Width определяют соответственно высоту и
ширину экрана со следующими ограничениями: если соответствующий размер не задан (т.е.,
HorizontalSizingType либо VerticalSizingType не равен FixedSize), то выдается нулевое значение; в
противном случае выдается физический размер экрана устройства в пикселах по
соответствующему измерению.
Содержимое экрана определяется при помощи свойства Content, которому можно присваивать
экранный элемент, являющийся вершиной дерева графических элементов, которые будут
формировать изображение на экране.
Для масштабирования шрифтов по размеру экрана мобильного устройства в элементе Screen
предусмотрен набор свойств для задания величины размера шрифта: SmallFontSize,
NormalFontSize, LargeFontSize, ExtraLargeFontSize. Все они имеют тип double и задают числовые
значения, которые можно использовать в качестве параметров в конструкторах шрифтов.
Конкретные значения этих величин зависят от размеров экрана клиентского мобильного
устройства.
Свойство Focus предназначено для управления фокусом на экране. Если этому свойству
присваивается некоторый графический элемент, находящийся в дереве, при отрисовке на экране
мобильного устройства фокус будет установлен именно на этот элемент. При приходе с
мобильного устройства информации о некотором экранном событии, связанном с действиями
пользователя, значение этого свойства будет указывать на элемент, на котором был фокус на
мобильном устройстве.
Свойство ColorScheme указывает, какая цветовая схема установлена на клиентском устройстве –
темная (тогда значение этого свойства – Ubiq.Graphiсs.ColorScheme.Dark) или светлая
(Ubiq.Graphics.ColorScheme.Light). Цветовая схема не может быть изменена из приложения.
StackPanel
Элемент StackPanel представляет собой панель (т.е., элемент, не имеющий своего визуального
представления, за исключением, возможно, фона, но определяющий размещение других
элементов), позволяющий размещать дочерние графические элементы последовательно, по
горизонтали или вертикали.
Области для размещения дочерних элементов выделяются по следующим правилам:



Для элементов с признаком WrapContent выделяется ровно столько места, сколько нужно
для размещения этого элемента;
Для элементов с явно заданным размером по соответствующему измерению выделяется
место, соответствующее размеру
Оставшееся место (т.е., для элементов, чей размер определяется как FillParent) делится
поровну между оставшимися элементами.
В дополнение к стандартным свойствам (Padding, Margin, Size, WrapContent, HorizontalAlignment,
VerticalAlignment, Background), StackPanel имеет следующие дополнительные свойства:
Children – коллекция графических элементов, представляющая собой список дочерних элементов,
размещаемых в рамках StackPanel. Элементы размещаются в панели в том порядке, в каком они
расположены в списке Children. Наличие свойства Children является общим для всех панелей.
Orientation – свойство, определяющее ориентацию панели (горизонтальную или вертикальную),
которое может принимать значения Ubiq.Graphics.Orientation.Vertical или
Ubiq.Graphics.Orientation.Horizontal.
OverlayPanel
Элемент OverlayPanel представляет собой панель, позволяющую размещать дочерние элементы с
перекрытиями, по абсолютным смещениям или по общим правилам размещения. Это –
единственная панель, при размещении элементов в которой используется информация из их
свойств Origin, значения которых трактуются как пары смещений (в пикселях) по горизонтали и по
вертикали относительно левого верхнего угла панели. Как и другие панели, OverlayPanel имеет
дополнительное свойство Children – коллекцию дочерних элементов.
Grid
Элемент Grid представляет собой панель, в которой элементы располагаются в виде двумерной
таблицы. Конструктор объекта Grid имеет два целочисленных параметра – размеры таблицы по
горизонтали и по вертикали соответственно. Для доступа к элементам предусмотрен оператор
вырезки [ , ] в котором индекс по первому измерению соответствует номеру строки (начиная с 0),
а индекс по второму – номеру столбца. В отличие от других панелей, Grid заполняется элементами
не через свойство Children, а посредством присваиваний ссылок на необходимые элементы
соответствующим вырезкам.
Области для размещения дочерних элементов выделяются по следующим правилам:



Для элементов с признаком WrapContent выделяется ровно столько места, сколько нужно
для размещения этого элемента;
Для элементов с явно заданным размером по соответствующему измерению выделяется
место, соответствующее размеру
Оставшееся место (т.е., для элементов, чей размер определяется как FillParent) делится
поровну между оставшимися элементами.
Border
Элемент Border представляет собой пример контейнера – элемента, содержащего внутри себя
единственный графический элемент (содержимое). Контейнеры могут как иметь собственное
графическое представление (помимо задания фона), так и не иметь его. В частности, контейнер
Border рисует вокруг элемента – содержимого рамку заданного цвета и толщины.
В дополнение к стандартным, элемент Border имеет следующие дополнительные свойства:
Content – графический элемент – содержимое. Это свойство является общим для всех
контейнеров.
Stroke – задает кисть (Brush), рисующую рамку. В отличие от задания фона, эта кисть может быть
только фиксированного цвета. Если это свойство не задано, по умолчанию используется черный
цвет.
StrokeThickness – задает толщину (Thickness) рамки по каждой стороне.
Selectable
Элемент Selectable представляет собой прозрачный контейнер, который позволяет устанавливать
фокус на выбранный элемент-содержимое, и «выбирать» его действием пользователя на экране
мобильного устройства, отправляя при этом сообщение на сервер. Таким образом, Selectable
можно рассматривать как некоторый аналог гиперссылки.
В дополнение к стандартным, Selectable имеет следующие дополнительные свойства:
Content – графический элемент – содержимое. Это свойство является общим для всех
контейнеров.
Clicked – событие, которое происходит при «выборе» элемента пользователем. Определяя свои
обработчики для этого события, разработчик приложения может использовать элементы
Selectable для управления логикой выполнения приложения.
Selectable не имеет дополнительных свойств для своего описания, за исключением общего для
всех контейнеров свойства Content, указывающего на элемент-содержимое.
Cell
Элемент Cell похож на элемент Selectable с той разницей, что он не является активным – т.е., его
нельзя выбрать на экране мобильного устройства и он не порождает событий, отправляемых на
сервер. Cell представляет собой контейнер, не имеющий самостоятельного графического
представления (за исключением, возможно, фона); основное его предназначение – служить
«прослойкой» между содержимым, размер которого определяется одним способом (например,
WrapContent) и внешним элементом, для резервирования места в котором хочется использовать
другой способ задания размера (наример, FillParent или FixedSize). Кроме того, элемент Cell (с
пустым содержимым) может использоваться для занятия пустого места (например, внутри
панелей StackPanel или Grid).
Cell не имеет дополнительных свойств для своего описания, за исключением общего для всех
контейнеров свойства Content, указывающего на элемент-содержимое.
TextBlock
Элемент TextBlock предназначен для представления текстовых нередактируемых полей. Помимо
стандартных свойств, она содержит свойства, определяющие цвет выводимого текста,
выравнивание текста внутри поля, используемый для вывода текста шрифт (тип шрифта, размер и
стиль) и собственно строку выводимого текста.
Foreground – свойство, задающее кисть, при помощи которой текст выводится на экран. Эта кисть
должна быть фиксированного цвета
TextAlignment - свойство, задающее выравнивание текста по горизонтали. Может принимать
значения Ubiq.Graphics.TextAlignment.Left, Ubiq.Graphics.TextAlignment.Right,
Ubiq.Graphics.TextAlignment.Center.
SingleLine – свойство, определяющее, должен ли текст выводиться в одну строку с возможным
обрезанием (если он принимает значение true) или возможен многострочный вывод текста (если
свойство принимает значение false).
Font – свойство, задающее шрифт выводимого текста. Значение этого свойства – экземпляр класса
Ubiq.Graphics.Font. Для этого класса имеются конструкторы нескольких форматов – в частности,
Font (String fontFamily, double emSize) – задается строка, определяющая тип шрифта, и размер
шрифта в пунктах. В графическом API поддерживаются типы шрифтов Arial, Times и Courier.
Font (FontFamily family, double emSize) – отличается от предыдущего конструктора тем, что тип
шрифта задается значением класса FontFamily, который, в свою очередь, имеет конструктор от
строкового параметра – типа шрифта. Параметр emSize определяется размер шрифта в пунктах.
Font (FontFamily family, double emSize, FontStyle style) – в дополнение к предыдущим
конструкторам, задает стиль используемого шрифта. Этот параметр может принимать значения
Ubiq.Graphics.FontStyle.Regular, Ubiq.Graphics.FontStyle.Bold, Ubiq.Graphics.FontStyle.Italic,
Ubiq.Graphics.FontStyle.Underline, Ubiq.Graphics.FontStyle.Strikeout, а также их комбинаций
(значения представляют собой битовые шкалы).
Text – задает строку текста, выводимого в текстовое поле
ImageBlock
Элемент ImageBlock предназначен для отрисовки графических изображений, подобно тому, как
TextBlock предназначен для вывода текстов.
Сами изображения представляются объектами класса Image, являющихся «обертками»
изображений .NET. Для объектов класса Image предусмотрены следующие конструкторы:
Image (System.Drawing.Image srcImage, Ubiq.Graphics.EncodingFormat encodingFormat, bool
persistent) – параметр srcImage задает «оборачиваемое» изображение, параметр encodingFormat –
способ сжатия изображения при передаче его на мобильные клиенты – предусмотрены значения
Ubiq.Graphics.EncodingFormat.EFormatJpeg и Ubiq.Graphics.EncodingFormat.EFormatPng. Параметр
persistent указывает, нужно ли кэшировать данное изображение на мобильном устройстве
(persistent = true) или этого делать не нужно (в частности, в тех случаях, когда изображение
используется однократно).
Image (System.Drawing.Image srcImage, Ubiq.Graphics.EncodingFormat encodingFormat) –
сокращенный вариант конструктора. Значение параметра persistent по умолчанию – true.
Image (System.Drawing.Image srcImage) – сокращенный вариант конструктора. Значение параметра
encodingFormat – Ubiq.Graphics.EncodingFormat.EFormatJpeg, параметра persistent – true.
Для объектов класса Image могут быть доступны следующие свойства:
Width – ширина исходного изображения в пикселах (double)
Height – высота исходного изображения в пикселах (double)
ImageType – тип изображения. Устанавливается в зависимости от заданного в конструкторе
формата сжатия. Для формата Ubiq.Graphics.EncodingFormat.EFormatJPeg тип изображения
принимает значение Ubiq.Graphics.ImageType.PhotoImage, а для формата
Ubiq.Graphics.EncodingFormat.EFormatPng – Ubiq.Graphics.ImageType.LineImage.
Persistent – определяет, должно ли изображение кэшироваться на клиенте. Изначально
принимает значение, соответствующее значению, переданному в конструкторе, но в программе
этому свойству может быть присвоено другое значение.
Объекты класса ImageBlock, помимо стандартных, имеют следующие свойства:
Image – объект класса Image, изображение, которое должно отображаться
Stretch – свойство типа bool, определяющее, нужно ли масштабировать изображение в
соответствии с размерами объемлющего графического элемента. Если Stretch = false, то при
недостатке места в объемлющем элементе изображение будет обрезаться, начиная с левого
верхнего угла.
Input
Этот графический элемент определяет поле текстового ввода. В дополнение к стандартным,
поддерживаются следующие свойства:
Foreground – свойство, задающее кисть, при помощи которой вводимый текст отображается в
поле ввода. Эта кисть должна быть фиксированного цвета
TextAlignment - свойство, задающее выравнивание вводимого текста по горизонтали. Может
принимать значения Ubiq.Graphics.TextAlignment.Left, Ubiq.Graphics.TextAlignment.Right,
Ubiq.Graphics.TextAlignment.Center.
Font – свойство, задающее шрифт выводимого текста. Значение этого свойства – экземпляр класса
Ubiq.Graphics.Font. Для этого класса имеются конструкторы нескольких форматов – в частности,
Font (String fontFamily, double emSize) – задается строка, определяющая тип шрифта, и размер
шрифта в пунктах. В графическом API поддерживаются типы шрифтов Arial, Times и Courier.
Font (FontFamily family, double emSize) – отличается от предыдущего конструктора тем, что тип
шрифта задается значением класса FontFamily, для которого, в свою очередь, имеется конструктор
от строкового параметра – типа шрифта. Параметр emSize определяется размер шрифта в пунктах.
Font (FontFamily family, double emSize, FontStyle style) – в дополнение к предыдущим
конструкторам, задает стиль используемого шрифта. Этот параметр может принимать значения
Ubiq.Graphics.FontStyle.Regular, Ubiq.Graphics.FontStyle.Bold, Ubiq.Graphics.FontStyle.Italic,
Ubiq.Graphics.FontStyle.Underline, Ubiq.Graphics.FontStyle.Strikeout, а также их комбинаций
(значения представляют собой битовые шкалы).
Text – задает начальное заполнение строки ввода. При начале пользовательского ввода
происходит редактирование этой строки.
Prompt – задает строку-приглашение, отображаемую первоначально в поле ввода. Основная
разница со свойством Text заключается в том, что приглашение исчезает из поля ввода сразу же
после начала ввода, а текст – остается и может редактироваться.
Clickable – это булевское свойство определяет, нужно ли посылать событие на сервер после
завершения ввода в данное поле или нет. Например, если на экране имеется единственное поле
ввода, то установка значения свойства Clickable = true является разумной альтернативой
помещению на экран дополнительной кнопки «OK». Если же, например, на экране имеется
несколько полей ввода, то это свойство должно быть установлено в false. По умолчанию Clickable
== false.
InputMode – свойство, определяющее фильтрацию символов при вводе – может принимать
значения Ubiq.Graphics.InputMode.Text (допустимы все символы) или
Ubiq.Graphics.InputMode.Numeric (только цифровые символы).
Clicked – событие, которое происходит при завершении ввода в текстовое поле, если значение
свойства Clickable установлено в true. В момент возбуждения этого события свойство Text уже
содержит введенную строку. Определяя свои обработчики для этого события, приложение может
реагировать на завершение пользовательского ввода.
Button
Элемент Button предназначен для представления стандартных кнопок на экране телефона. Кнопка
отрисовывается на экране способом, традиционным для данного конкретного мобильного
устройства, на уровне приложения задаются только цвета и текст надписи на кнопке.
В дополнение к стандартным, в элементе Button предусмотрены следующие дополнительные
свойства:
Foreground – свойство, задающее кисть, при помощи которой текст рисуется на кнопке Эта кисть
должна быть фиксированного цвета
TextAlignment - свойство, задающее выравнивание текста по горизонтали. Может принимать
значения Ubiq.Graphics.TextAlignment.Left, Ubiq.Graphics.TextAlignment.Right,
Ubiq.Graphics.TextAlignment.Center.
SingleLine – свойство, определяющее, должен ли текст выводиться в одну строку с возможным
обрезанием (если он принимает значение true) или возможен многострочный вывод текста (если
свойство принимает значение false).
Font – свойство, задающий шрифт выводимого текста. Значение свойства – экземпляр класса
Ubiq.Graphics.Font. Для этого класса имеются конструкторы нескольких форматов – в частности,
Font (String fontFamily, double emSize) – задается строка, определяющая тип шрифта, и размер
шрифта в пунктах. В графическом API поддерживаются типы шрифтов Arial, Times и Courier.
Font (FontFamily family, double emSize) – отличается от предыдущего конструктора тем, что тип
шрифта задается значением класса FontFamily, который, в свою очередь, имеет конструктор от
строкового параметра – типа шрифта. Параметр emSize определяется размер шрифта в пунктах.
Font (FontFamily family, double emSize, FontStyle style) – в дополнение к предыдущим
конструкторам, задает стиль используемого шрифта. Этот параметр может принимать значения
Ubiq.Graphics.FontStyle.Regular, Ubiq.Graphics.FontStyle.Bold, Ubiq.Graphics.FontStyle.Italic,
Ubiq.Graphics.FontStyle.Underline, Ubiq.Graphics.FontStyle.Strikeout, а также их комбинаций
(значения представляют собой битовые шкалы).
Text – задает строку текста – заголовка кнопки
Pressed – событие, которое происходит по нажатию кнопки пользователем мобильного
устройства. Разработчик приложения может обрабатывать нажатие кнопки, определяя свой
обработчик для этого события.
ImageButton
Элемент ImageButton позволяет разработчику определять кнопки собственного вида на телефоне.
Кнопка ImageButton определяется парой изображений, соответствующих положению кнопки в
отжатом и нажатом состояниях.
В дополнение к стандартным, в элементе ImageButton предусмотрены следующие свойства:
Image – объект класса Image, соответствующий кнопке в отжатом состоянии
SelectedImage – объект класса Image, соответствующий кнопке в нажатом состоянии
Stretch – булевское свойство, определяющий, следует ли масштабировать картинки (Image и
SelectedImage) по размеру объемлющего элемента.
Pressed – событие, которое происходит по нажатию кнопки пользователем мобильного
устройства. Разработчик приложения может обрабатывать нажатие кнопки, определяя свой
обработчик для этого события.
CheckBox
Этот графический элемент предназначен для описания флажков, имеющих два состояния: выбран
(поставлена галочка) и не выбран (пустое). Собственно элемент CheckBox включает в себя флажок
и текстовый комментарий, размещаемый справа от флажка.
В дополнение к стандартным, CheckBox имеет следующие свойства:
Foreground – свойство, задающее кисть, при помощи которой выводится флажок и текст
комментария. Эта кисть должна быть фиксированного цвета
Font – свойство, задающее шрифт для вывода текста комментария. Значение свойства – экземпляр
класса Ubiq.Graphics.Font. Для этого класса имеются конструкторы нескольких форматов – в
частности,
Font (String fontFamily, double emSize) – задается строка, определяющая тип шрифта, и размер
шрифта в пунктах. В графическом API поддерживаются типы шрифтов Arial, Times и Courier.
Font (FontFamily family, double emSize) – отличается от предыдущего конструктора тем, что тип
шрифта задается значением класса FontFamily, который, в свою очередь, имеет конструктор от
строкового параметра – типа шрифта. Параметр emSize определяется размер шрифта в пунктах.
Font (FontFamily family, double emSize, FontStyle style) – в дополнение к предыдущим
конструкторам, задает стиль используемого шрифта. Этот параметр может принимать значения
Ubiq.Graphics.FontStyle.Regular, Ubiq.Graphics.FontStyle.Bold, Ubiq.Graphics.FontStyle.Italic,
Ubiq.Graphics.FontStyle.Underline, Ubiq.Graphics.FontStyle.Strikeout, а также их комбинаций
(значения представляют собой битовые шкалы).
Text – задает текст комментария. Если значение этого свойства – пустая строка, то элемент
CheckBox состоит из одного только флажка.
SingleLine – логическое свойство, определяющее, нужно ли выводить текст комментария
исключительно в одну строку (если его значение – true).
Clickable – логическое свойство, определяющее, нужно ли формировать событие и посылать его
на сервер при установке значений флажка. По умолчанию Clickable == false.
Clicked – событие, которое происходит при установке флажка, если значение свойства Clickable
установлено в true. В момент возбуждения этого события свойство Value уже содержит
установленное значение флажка. Определяя свои обработчики для этого события, приложение
может реагировать на установку пользователем флажка.
DropBox
Элемент DropBox представляет на экране мобильного устройства выпадающий список, из
которого можно выбрать один элемент. Этот элемент предусматривает следующие
дополнительные свойства:
Foreground – свойство, задающее кисть, при помощи которой выводятся строки выпадающего
списка и его элемент, отображаемый по умолчанию в «свернутом» виде. Эта кисть должна быть
фиксированного цвета
Font – свойство, задающее шрифт для вывода текста элементов выпадающего списка. Значение
свойства – экземпляр класса Ubiq.Graphics.Font. Для этого класса имеются конструкторы
нескольких форматов – в частности,
Font (String fontFamily, double emSize) – задается строка, определяющая тип шрифта, и размер
шрифта в пунктах. В графическом API поддерживаются типы шрифтов Arial, Times и Courier.
Font (FontFamily family, double emSize) – отличается от предыдущего конструктора тем, что тип
шрифта задается значением класса FontFamily, который, в свою очередь, имеет конструктор от
строкового параметра – типа шрифта. Параметр emSize определяется размер шрифта в пунктах.
Font (FontFamily family, double emSize, FontStyle style) – в дополнение к предыдущим
конструкторам, задает стиль используемого шрифта. Этот параметр может принимать значения
Ubiq.Graphics.FontStyle.Regular, Ubiq.Graphics.FontStyle.Bold, Ubiq.Graphics.FontStyle.Italic,
Ubiq.Graphics.FontStyle.Underline, Ubiq.Graphics.FontStyle.Strikeout, а также их комбинаций
(значения представляют собой битовые шкалы).
ItemList – список строк (List<String>), представляющий собой выпадающий список.
Index – целочисленное свойство, которое, если выбор еще не сделан, задает индекс элемента
(считая от 0) в списке, который должен отображаться в окне DropBox в свернутом виде. Если
выбор уже сделан, значение этого свойства соответствует индексу выбранного элемента.
Text – строка текста выбранного элемента выпадающего списка. Если выбор не сделан, то это
строка элемента, отображаемого по умолчанию в окне DropBox.
Clickable – булевское свойство, определяющее, нужно ли формировать событие и посылать его на
сервер при выборе элемента из выпадающего списка. По умолчанию Clickable = false.
Clicked – событие, которое происходит при выборе пользователем элемента из списка DropBox
при установленном свойстве Clickable = true. В момент возбуждения этого события свойства Index
и Text уже содержат индекс выбранного элемента и строку из этого элемента соответственно.
Определяя свои обработчики для этого события, разработчик в своем приложении может
реагировать на выбор пользователем элемента из выпадающего списка.
ListBox
Этот графический элемент предназначен для представления списков. Элементами списков в
модели NB могут быть произвольные графические элементы, в модели B элементами списков
могут быть только элементы типа TextBlock и панели StackPanel, содержащие либо элементы
TextBlock, либо другие панели StackPanel.
Элемент ListBox имеет следующие дополнительные свойства:
Separator – это булевское свойство определяет, нужно ли выводит линию-разделитель между
элементами списка.
Clickable – булевское свойство, определяющее, нужно ли формировать событие и посылать его на
сервер при выборе элемента списка. По умолчанию Clickable=false.
Focus – целочисленное свойство, определяющее номер выбранного элемента из списка (при
Clickable = true, после выбора элемента), либо номер элемента, который должен быть
обязательно отображен в видимой части списка при выводе списка на экран. Номера элементов
считаются, начиная с 1.
Clicked – событие, которое происходит при выборе пользователем элемента из списка при
установленном свойстве Clickable = true. В момент возбуждения этого события свойство Focus уже
содержит номер выбранного элемента. Определяя свои обработчики для этого события,
разработчик в своем приложении может реагировать на выбор пользователем элемента списка.
Append (Element) – метод, позволяющий добавлять в список графические элементы. Элементы
добавляются в конец списка.
Простые формы (прямоугольники, эллипсы, линии, многоугольники)
Для вывода простых форм на экран мобильного устройства предназначено несколько типов
графических элементов. Все они имеют, в дополнение к стандартными два дополнительных
свойства:
Stroke – задает кисть, при помощи которой отрисовывается граница элемента. Эта кисть должна
быть фиксированного цвета. По умолчанию – задается кисть черного цвета.
StrokeThickness – толщина границы в пикселах. Если задано значение 0, то граница не
отрисовывается. По умолчанию StrokeThickness = 1.
Rectangle – графический элемент для отображения прямоугольника. Дополнительных свойств не
имеет.
Ellipse – графический элемент для отображения эллипса, вписанного в прямоугольную область,
определяемую объемлющим элементом. Дополнительных свойств не имеет.
Polygon – графический элемент для отображения многоугольника. Имеет дополнительное
свойство Points типа Collection<Ubiq.Graphics.Point>. Эта коллекция задает набор точек, по
которым строится многоугольник. Точки многоугольника задаются в абсолютных координатах.
Line – графический элемент для представления отрезков прямых линий. Линия считается
вписанной в прямоугольную область, определяемую объемлющим прямоугольником. Имеет
дополнительное свойство Direction типа Ubiq.Graphics.LineDirection, которое определяет
направление линии. В сочетании со стандартными свойствами выравнивания (VerticalAlignment и
HorizontalAlignment) свойство Direction определяет способ вписывания линии в объемлющий
прямоугольник. Это свойство может принимать следующие значения:
Ubiq.Graphics.LineDirection.Horizontal



При VerticalAlignment = Ubiq.Graphics.VerticalAlignment.Top соответствует верхней
горизонтальной стороне прямоугольника;
При VerticalAlignment = Ubiq.Graphics.VerticalAlignment.Center соответствует
горизонтальному отрезку, соединяющему середины вертикальных сторон
прямоугольника;
При VerticalAlignment = Ubiq.Graphics.VerticalAlignment.Bottom соответствует нижней
горизонтальной стороне прямоугольника.
Ubiq.Graphics.LineDirection.Vertical



При HorizontalAlignment = Ubiq.Graphics.HorizontalAlignment.Left соответствует левой
вертикальной стороне прямоугольника;
При HorizontalAlignment = Ubiq.Graphics.HorizontalAlignment.Center соответствует
вертикальному отрезку, соединяющему середины горизонтальных сторон
прямоугольника;
При HorizontalAlignment = Ubiq.Graphics.HorizontalAlignment.Right соответствует правой
вертикальной стороне прямоугольника.
Ubiq.Graphics.LineDirection.DiagonalUp соответствует дигонали, проведенной из левого нижнего
угла прямоугольника в правый верхний угол.
Ubiq.Graphics.LineDirection.DiagonalDown соответствует диагонали, проведенной из левого
верхнего угла прямоугольника в правый нижний угол.