Переменные и типы данных

Предопределенные переменные

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

window-

предоставляет доступ к окну программы

Document-

предоставляет доступ к открытой карте

IO-

предоставляет доступ о объектам ввода/вывода

Набор предопределенных объектов, а также состав их свойств и методов определяется исполняющей конкретной средой и может различаться (см. документацию на исполняющие среды). Описание свойств и методов предопределенных объектов можно посмотреть в среде разработки ScriptEdit в инспекторе свойств, когда в редакторе активна вкладка Код
.
Переменные, объявленные внутри функции являются локальными, т.е. они видны только в пределах кода функции, в которой были объявлены. Среда CityMap предоставляет возможность создавать глобальные переменные (видимые из любой функции программы). Для создания глобальной переменной служит метод AddVariable объекта window. Например код:

window.AddVariable("timer1");
timer1=5;

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

Таймеры

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

 timer1= window.Timers.Add("Event1",10000);  //Создает таймер с периодом срабатывания 10 секунд
//и сохраняет его идентификатор в переменной timer1

После выполнения этого кода каждые 10 секунд будет вызываться функция Event1.

 window.Timers.Interval(timer1,20000);

После выполнения этого кода функция Event1 будет вызываться каждые 20 секунд.

 window.Timers.Delete(timer1);

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

Двоичные данные

Для хранения данных произвольного формата в среде CityMap используется объект Blob. Blob -это набор данных произвольного формата. В каждый набор можно добавлять блок новых данных из файла (методом AddFromFile) из поля базы данных (метод FieldByName объекта IBDataBase), а также из карты (методом AddFromMap). Удалить данные из блоба можно только все сразу методом Clear.
Все функции добавления данных в блоб возвращают строку, содержащую URL адрес добавленных данных. Если этот адрес задать в качестве значения параметра src тега HTML формы, то при отображении такой формы в соответствующий тег будут загружены данные из блоба через встроенный HTTP сервер. Перед началом использования этой возможности нужно разрешить HTTP сервер кодом:

 window.HTTPServer=true;

Пример использования блоба:

 var i=window.Blobs.Add(); //Добавляет новый блоб в коллекцию блобов

 var addres=window.Blobs.Items(i).AddFromMap(mapobj,0xffffff); //Добавляет в блоб изображение
 //картографического объекта mapobj с белым фоном

 window.Forms.Form("Test").Code="<img src=\""+addres+"\">" //В HTML форму с именем Test
 //добавляется тэг изображения

Если далее отобразить форму Test, то на ней будет показан картографический объект mapobj.
Все блобы собраны в коллекцию блобов, доступ к которой осуществляется через свойство Blobs объекта window. Для получения нужного блоба из коллекции служит индексированное свойство Items.
У объекта Blob есть два метода для построчной работы с текстовыми данными.Метод ReadString возвращает очередную строку из блока данных с индексом, переданным в качестве второго параметра. Если при этом первый параметр равен true, то чтение начинается с начала блока, в противном случае с текущей позиции, таким образом код:
 var b=window.Blobs.Items(0); //Получение блоба с индексом 0 (он должен уже существовать)
 var buf=b.ReadString(true,0); //Чтение первой строки из блока данных с индексом 0 (он должен существовать)
 while (buf!=null)
 {
 window.alert(buf);
 buf=b.ReadString(false,0); //Чтение очередной строки блока данных
 }

будет выводить по порядку все строки блока данных.
Метод WriteString добавляет в блок данных с индексом, передаваемым в первом параметре строку, передаваемую во втором параметре.

Базы данных

Для доступа к базам данных в среде CityMap служит объект DataBase, доступный через одноименный метод объекта window. В качестве параметра методу DataBase передается тип базы данных. Например, для базы данных MySql 5, это будет строка 'mysql-5'.
При каждом обращении к этому методу создается новый объект DataBase, поэтому для использования, его нужно присвоить локальной или глобальной переменной. Например:

 var db=window.DataBase("mysql-5"); //Создается объект базы данных MySql 5
 if ( db.Connect("dbtest","localhost","root","password") ) //Подключение к базе данных dbtest на локальном сервере
 {//При успешном подключении можно выполнять запрос

   db.SQL("Текст sql запроса");
   //обработка результатов запроса

   // ..........................................

 } else {window.alert("Ошибка подключения к базе!");}

После вызова метода SQL объекта DataBaseформируется таблица, доступ к полям текущей записи которой осуществляется методом FieldByName, который возвращает символьное представление поля с заданным именем. Если содержимое поля является двоичными данными и задан существующий блоб, то данные помещаются в этот блоб, и возвращается адрес этих данных.
Для выбора текущей записи в таблице, служит свойство RecNo.
После окончания работы с базой данных нужно выполнить отключение от нее методом Disconnect объекта DataBase.
Существует также объект IBDataBase предоставляющий доступ к базам данных FireBird (InterBase). Этот объект можно рассматривать как частный случай объекта DataBase. Для его создания служит свойство window.IBDataBase.

Формы

Исполняющая среда CityMap поддерживает два типа форм: HTML (на основе html размерки) и обычные формы. Для управления формами используется объект Forms, который доступен чесрез одноименное свойство объекта window. Формы могут быть созданы на этапе проектирования через дизайнер форм, а также во время исполнения программы. Для программного создания формы служит метод Add объекта Forms. В качестве параметров этому методу передается уникальное имя формы и тип формы (1 - HTML форма, 2- обычная форма). Удалить форму можно методом Delete, передав в качестве параметра индекс удаляемой формы. Свойство Count объекта Forms возвращает общее количество созданных форм (учитываются формы, созданные на этапе проектирования и на этапе выполнения).
Пример:

 window.Forms.Add("Forma1",1); //Создается новая HTML форма с именем Forma1
 var f1=window.Forms.Form("Forma1") //переменная f1 получает объект созданной формы

Доступ к данным формы и управление формой осуществляется через объект Form, который можно получить через индексированной свойство Form объекта Forms. В качестве индекса может быть либо имя формы, либо ее номер.
Через свойства и методы объекта Form можно управлять формой. Свойство Caption - определяет заголовок формы. Свойство Code задает содержимое формы (для HTML форм - это код html разметки, а для обычных форм это код на внутреннем языке описания форм.
Для отображения формы служит методы Show и ShowContext. Метод Show отображает форму в различных режимах. В качестве первого параметра нужно передать режим отображения формы:
1-модальная форма с постоянными размерами;
2-модальная форма с изменяемыми размерами;
3-немодальная форма с постоянными размерами;
4-немодальная форма с изменяемыми размерами;
5-контекстная форма (без заголовка и рамки, автоматически закрывантся при потере фокуса);
6,7,8,9-форма располагается в виде панели в главном окне слева,справа,сверху,снизу соответственно.
Если в метод Show передается второй параметр и он равен false, то форма не пересоздается если она уже показавалась ранее, т.е. в таком режиме все элементы формы будут в текущем состоянии, а не в состоянии, определенном при проектировании формы. Например если форма с именем Forma1 содержит флажок с именем option1, который при проектировании был установлен, то следующий код:

 var f1=window.Forms.Form("Forma1"); //переменная f1 получает объект формы с именем Forma1

 f1.Show(3); //Создается и отображается форма, описанная объектом Forma1

 f1.Hide(); //После первого показа формы она остается в памяти и можно изменять ее элементы
 //даже после скрытия.

 f1.Objects("option1").Checked=false; //Снятие флажка option1

 f1.Show(1,false); //Отображает форму без повторного создания

отобразит форму со снятым флажком. Если же последнюю строчку кода заменить на:

 f1.Show(1,true); //Отображает форму с повторным созданием

то отобразится форма с установленным флажком, т.к таким он был задан при проектировании.
Метод ShowContext отображает форму в режиме 5.
Индексированное свойство Objects объекта Form возвращает объект элемента формы. В качестве индекса можно использовать имя элемента или его порядковый номер в форме. Через полученный объект доступны все свойства элемента формы, видимые в инспекторе свойств дизайнера форм.
Для HTML форм свойство Objects недоступно, вместо этого есть свойство HTMLDocument, которое возврашает интерфейс доступа к объектной модели HTML документа формы.

Меню

Меню, так же как и формы можно создавать на этапе проектирования и на этапе исполнения.
Для доступа к меню на этапе выполнения программы нужно использовать объект Menus, который можно получить через одноименное свойство объекта window. Через этот объект можно создать новое меню методом Add? удалить меню методом Delete. Можно установить текущее главное меню методом SetMainMenu или контекстное, методом SetPopUpMenu, передав в качестве параметра имя существующего меню. Метод PopUp отображает текущее контекстное меню в точке экрана с координатами, переданными в качестве параметров. Если координаты отрицательные, то контекстное меню выводится в позиции указателя мыши.
Метод SetToolBar формирует и отображает панель кнопок на основе меню с именем, переданным в качестве первого параметра. В качестве второго параметра передается индекс панели инструментов, которая должна быть сформирована. Если индекс больше количества существующих панелей, то создается новая панель, иначе заменяется существующая с этим индексом. Очистить все панели инструментов можно методом ClearToolBar

Объекты ввода/вывода

Объекты ввода/вывода доступны через предопределенную переменную IO. В исполняющей среде LksCityMap доступну следующие объекты ввода/вывода: HTTPConnection - загрузка данных с сервера по протоколу http(https), FTPConnection - загрузка данных с сервера по протоколу ftp, OLEObject - подключение к серверу автоматизации, такому как MS Word или MS Excel, Dialog - вызов системных диалогов открытия и сохранения файлов, Function - набор расширенных функций.

Объект HTTPConnection

Объект HTTPConnection реализует обмен с сервером по протоколу HTTP(HTTPS). При каждом обращении к свойству HTTPConnection объекта IO создается и возвращается новый объект HTTPConnection. Этот объект имеет следующие свойства и методы:

СвойствоОписаниеТипДоступ
RequestHeaderИндексированное свойство, принимающее значение параметра заголовка HTTP запросаСтрокаW
ResponseTextТекстовое описание кода ответаСтрокаR

МетодОписаниеВозвращаемое значение
GetЗагрузка данныхЧисловой код ответа
PostОтправка данных на сервер методом POSTЧисловой код ответа
ReadStringЧтение загруженных данных в виде строкиСтрока
ReadBlobЧтение загруженных данных в двоичном виде и добавление их в блобСтрока (url адрес блоба)

Перед выполнением запроса можно установить необходимые заголовки через индексированное свойство RequestHeader. В качестве индекса используется имя параметра. Доступны следующие значения индекса: Username, Password, ProxyServer, ProxyPort, ProxyUsername, ProxyPassword, ProxyAuthenticate, Referer, UserAgent, WWWAuthenticate, LastModified, ContentType.
Загрузка данных с сервера выполняется методом Get, которому в качестве параметра передается URL адрес нужного ресурса. По окончании загрузки этот метод возвращает числовой код ошибки (в случае успешной загрузки возвращается 200). Текстовую расшифровку кода ошибки можно получить, прочитав свойство ResponseText.
После получения данных с сервера их можно поместить в строку методом ReadString или в блоб, методом ReadBlob.

 var hc=IO.HTTPConnection; //Получение объекта HTTP соединения
 if (hc.Get("http://ya.ry")==200); //Получение текста заглавной страницы с сервера ya.ru
 {
  var buf=hc.ReadString(); //Сохранение полученных данных в строке buf
  window.alert(buf); //Вывод кода страницы в диалоговом окне
 } else {window.alert(hc.ResponseText);}


Объект FTPConnection

Объект FTPConnection реализует обмен с сервером по протоколу FTP. При каждом обращении к свойству FTPConnection объекта IO создается и возвращается новый объект FTPConnection. Этот объект имеет следующие свойства и методы:

СвойствоОписаниеТипДоступ
ErrorMessageВозвращает текстовое описание ошибки последней операцииСтрокаR

МетодОписаниеВозвращаемое значение
ConnectУстанавливает соединение с FTP серверомtrue - в случае успеха и false - в случае ошибки
DisconnectРазрывает соединение с серверомtrue - в случае успеха и false - в случае ошибки
GetПолучает файл с ftp сервера и сохраняет его в блобеtrue - в случае успеха и false - в случае ошибки
PutСохраняет блок данных из блоба в файл на ftp сервереtrue - в случае успеха и false - в случае ошибки
ListПолучение списка файловСписок строк - в случае успеха и null - в случае ошибки
MakeDirСоздает папку на FTP сервереtrue - в случае успеха и false - в случае ошибки
RemoveDirУдаляет непустую папку на FTP сервереtrue - в случае успеха и false - в случае ошибки
RenameПереименовывает файл на FTP сервереtrue - в случае успеха и false - в случае ошибки
DeleteУдаляет файл на FTP сервереtrue - в случае успеха и false - в случае ошибки
ChangeDirУстанавливает текущий каталог на FTP сервереtrue - в случае успеха и false - в случае ошибки

Метод Connect устанавливает соединение с FTP сервером, адрес которого передается в качестве первого параметра, по номеру порта указанного во втором параметре, в третьем и четвертом параметрах передается логин и пароль.
Метод Get получает с FTP сервера файл, имя которого указано в первом параметре, и сохраняет его в блобе, переданном во втором параметре. В качестве второго параметра может быть указан индекс блоба в коллекции блобов, в который будут помещены полученные данные.
Метод Put отсылает на сервер блок данных с индексом переданным во втором параметре, из блоба, переданного в первом параметре и сохраняет данные на сервере в файле, с именем, переданном в третьем параметре.
Метод Rename переименовывает файл, имя которого передано в первом параметре, в файл, имя которого передано во втором параметре.
Пример кода построчного вывода на экран текстового файла с FTP сервера:
 var b=window.Blobs.Items(window.Bolbs.Add()); //Создание нового блоба
 var fc=IO.FTPConnection; //Получение объекта HTTP соединения
 if (fc.Connect("192.168.1.1","21","user","password")) //Установка соединения с сервером
 {
  if (fc.Get("filename.txt",b)) //Получение файла filename.txt
  {
   var buf=b.ReadString(true,0); //получение первой строки файла
   while(buf!=null)    {
   window.alert(buf);
   buf=b.ReadString(false,0); //получение очередной строки файла
   }
  } else {window.alert("Ошибка получения файла\r\n"+fc.ErrorMessage);}
 } else {window.alert("Ошибка установки соединения\r\n"+fc.ErrorMessage);}

Использование OLE объектов

Для подключения к серверам автоматизации, таким как MS Word или MS Excel в в исполняющей среде Lks CityMap используется индексированное свойство OLEObject. В качесте индекса нужно передать ProgId сервера автоматизации. Это свойство выполняет поиск нужного сервера, запускает его и возвращает объект запущенного сервера.
Пример доступа к серверу MS Excel

 var exl=IO.OLEObject("excel.Application"); //Подключение к серверу
 exl.Visible=true; //Сделать Excel видимым
 exl.WorkBooks.Add(""); //Добавление новой книги
 var ws1=exl.WorkBooks(1).Worksheets(1); //Получение первого листа с созданной книги
 ws1.Cells(1,1).Value="Hello world!"; //вывод текста в первую ячейку

Системные диалоги

Для вызова системных диалогов используется метод Dialog объекта IO. В качестве первого параметра передается тип диалога ("Open" - диалог открытия файла, "Save" - диалог сохранения файла). Во втором параметре передается заголовок диалога. Количество и значение остальных параметров зависит от типа диалога. Для файловых диалогов в третьем параметре передается фильтр в формате: "название_фильтра|фильтр". В четвертом параметре передается переменная, которая будет содержать имя выбранного файла.


lkssupport@bk.ru