Класс Pzl: различия между версиями

Материал из wikiru.visual-prolog.com

 
(не показаны 53 промежуточные версии этого же участника)
Строка 1: Строка 1:
{{copyright}}
=Назначение=
=Назначение=
Класс pzl предназначен для обеспечения работы с pzl-компонентами и получения информации о состоянии pzl-системы. Этот класс обязательно должен включаться в проект любой pzl-компоненты и главного приложения, генерирующего исполняемый (.EXE) файл, даже если нет необходимости обращения к предикатам этого класса.
Класс pzl предназначен для обеспечения работы с pzl-компонентами и получения информации о состоянии pzl-системы. Этот класс обязательно должен включаться в проект любого pzl-контейнера и главного приложения, генерирующего исполняемый (.EXE) файл, даже если нет необходимости обращения к предикатам этого класса.
 
Обращения к предикатам этого класса возможны из любого класса, включенного в проект, использующий pzl-технологию.


Имплементация класса pzl содержится:  
Имплементация класса pzl содержится:  
Строка 8: Строка 7:
*в случае главного приложения в библиотеке pzlPort_XX.lib
*в случае главного приложения в библиотеке pzlPort_XX.lib
здесь YY и XX - уровень лицензии.
здесь YY и XX - уровень лицензии.
Обращения к предикатам этого класса возможны из любого класса, включенного в проект, использующий pzl-технологию.
=Список нестандартных доменов, используемых классом=
{|cellspacing="0" border="1" style="float:center;background:#F9F9F9;color:green;"
|-
|pzlComponentsRegisterFileName_D
|Состояние файла-реестра компонент данного приложения
|-
|pzlContainerContentInfo_D
|Информация о компонентах контейнера
|-
|pzlComponentInfo_D
|Описание pzl-компоненты контейнера
|-
|entityUID_D
|Идентификатор сущности
|}


=Список предикатов класса=
=Список предикатов класса=
{|border="1" style="float:center;background:#F9F9F9;color:green;"
Предикаты класса Pzl можно разбить условно на группы (стандартный для VIP предикат classInfo не рассматривается):
|-
 
|'''Информация о контейнере'''
*'''Информация о контейнере.''' Эта группа обычно не используется в прикладном программировании и служит для получения информации о контейнере и приложении - уровень лицензии, информация о компонентах и т.д.
*'''Управление компонентами.''' Эта группа используется чаще, чем предыдущая, но без обращения к ней также можно обойтись при использовании стандартного для VIP способа порождения экземпляров классов. Позволяет создавать экземпляры компонент, используя их идентификаторы и имена. В этой же группе содержится предикат переназначения стандартного потока вывода.
*'''Регистрация объектов.''' Эта группа наиболее часто используется в прикладном программировании, поскольку обеспечивает возможность получания информации об активных объектах приложения из любого класса и объекта приложения.
*'''Служебные предикаты.''' Cозданы для использования специальными средствами в специальных целях. Использовать не рекомендуется.
 
{|cellspacing="0" border="1" style="float:center;background:#F9F9F9;color:green;"
|-
|-
|<vip>classInfo.
|<vip>classInfo.
Получение информации о версии и дате последнего изменения класса Pzl</vip>
Получение информации о версии и дате последнего изменения класса Pzl</vip>
|-
|'''Информация о контейнере'''
|-
|-
|<vip>getContainerName:()->string ThisContainerName procedure ().
|<vip>getContainerName:()->string ThisContainerName procedure ().
Строка 34: Строка 58:
|'''Управление компонентами'''
|'''Управление компонентами'''
|-
|-
|<vip>newByID:(pzlDomains::entityUID_D,object InObject)->object OutObject.
|<vip>setStdOutputStream:(outputStream OutputStream).
Создать новый объект, используя уникальный идентификатор компоненты</vip>
Назначить заданный выходной поток в качестве стандартного выходного потока для всех компонент, используемых данным приложением</vip>
|-
|-
|<vip>newByName:(string Name,object InObject)->object OutObject procedure (i,i).
|<vip>newByName:(string Name,object InObject)->object OutObject procedure (i,i).
Создать новый объект, используя имя компоненты</vip>
Создать новый объект, используя имя компоненты</vip>
|-
|-
|<vip>setStdOutputStream:(outputStream OutputStream).
|<vip>newByID:(pzlDomains::entityUID_D,object InObject)->object OutObject.
Назначить заданный выходной поток в качестве стандартного выходного потока для всех компонент, используемых данным приложением</vip>
Создать новый объект, используя уникальный идентификатор компоненты</vip>
|-
|-
|'''Регистрация объектов'''
|'''Регистрация объектов'''
Строка 91: Строка 115:
=Используемые дополнительные ресурсы=
=Используемые дополнительные ресурсы=
Обязательно:
Обязательно:
*использование библиотеки pzlPort_XX.lib, где XX - квалификатор лицензии. Библиотека фактически содержит имплементацию класса pzlPort и включает имплементацию свойств pzl-Контейнера главного исполняемого приложения.
*Класс Pzl использует библиотеку pzlPort_XX.lib, если целью проекта является исполняемоее приложение (.EXE) и библиотеку pzlContainer_XX - если целью проекта является контейнер (DLL). Указанные библиотеки фактически содержат имплементацию класса Pzl.
*наличие пакета pzlConfig, который участвует в процессе инициализации.
*наличие пакета pzlConfig.
 
=Описание доменов=
==pzlDomains::pzlComponentsRegisterFileName_D==
Состояние файла-реестра компонент
<vip>pzlComponentsRegisterFileName_D=
  pzlRegistryFileName(string FileName);
  pzlRegistryFileNameWronglyDefined;
  pzlRegistryFileNameNotInUse.</vip>
Определяет одно из состояний назначения файла-реестра компонент для данного приложения.
<vip>pzlRegistryFileName(string FileName)
назначен файл с именем FileName.</vip>
<vip>pzlRegistryFileNameWronglyDefined
файл-реестр неправильно определен, возможно, отсутствовал на момент назначения.</vip>
<vip>pzlRegistryFileNameNotInUse
файл-реестр к данному моменту не назначался, то есть не используется.</vip>
 
==pzlDomains::entityUID_D==
Домен служит для идентификации различных сущностей. Имеет две возможные формы:
*простую str(string)
*сложную uid(...), соответствующую nativeGuid системы Visual Prolog, которая, в свою очередь соответствует GUID фирмы Microsoft.
 
Простая форма не обеспечивает уникальности идентификаторов и рекомендуется для использования в примерах и упражнениях.
 
Сложная форма обеспечивает уникальность, но неудобна для восприятия и требует автоматизации манипулирования.
<vip>
domains
  entityUID_D =
    str(string Строковый идентификатор);
    uid(
      core::unsigned32 Unsigned,
      core::unsigned16 Short1,
      core::unsigned16 Short2,
      core::unsigned8 Byte1,
      core::unsigned8 Byte2,
      core::unsigned8 Byte3,
      core::unsigned8 Byte4,
      core::unsigned8 Byte5,
      core::unsigned8 Byte6,
      core::unsigned8 Byte7,
      core::unsigned8 Byte8
      ).
</vip>
 
==pzlDomains::pzlContainerContentInfo_D, pzlDomains::pzlComponentInfo_D==
Домен pzlContainerContentInfo_D используется в качестве описания состава pzl-контейнеров. Представляет список описаний отдельных компонент.
<vip>
pzlContainerContentInfo_D = pzlComponentInfo_D*.
</vip>
Каждый элемент списка представляет собой терм домена pzlComponentInfo_D
<vip>
pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )
</vip>
 
Здесь
*Alias - строковое имя компоненты,
*ComponentID - идентификатор компоненты
*Runable - булевый признак возможности самостоятельного запуска компоненты
*UserDefinedInfo - список параметров, задаваемый и интерпретируемый создателем компоненты.
 
=Описание предикатов=
=Описание предикатов=
==pzl::getContainerName/0==
<vip>getContainerName:()->string ThisContainerName procedure ().
Получить имя файла-контейнера, в котором находится данная компонента</vip>
'''Описание'''
Возвращает имя (полный маршрут) файла, в котором находится данная pzl-компонента.<br>
'''Пример'''
<vip>
...
ContainerName=pzl::getContainerName(),
stdIO::writef("Компонента /"MyComponent/" находится в контейнер %",ContainerName),
...
</vip>
'''Исключения'''
Нет.
==pzl::getContainerVersion/0==
<vip>getContainerVersion:()->string ThisContainerVersion procedure ().
Получить идентификатор версии контейнера, в котором находится данная компонента</vip>
'''Описание'''
Возвращает версию pzl-контейнера, в котором находится данная компонента.
Версия контейнера представляется значением строкового типа (string) и определяется константой "pzlContainerVersion_C"
в файле iPzlConfig.i проекта контейнера.
'''Пример'''
Например, файл iPzlConfig.i данного контейнера содержит объявление константы
<vip>constants
  pzlContainerVersion_C="1.0;001".</vip>
Следующий код получает номер версии данного контейнера
<vip>...
ContainerVersion=pzl::getContainerVersion(),
stdIO::writef("Версия контейнера - %",ContainerVersion),
...</vip>
В стандартный выходной поток будет выведено: "Версия контейнера - 1.0;001"
'''Исключения'''
Нет.
==pzl::getLicenseLevel/0==
<vip>getLicenseLevel:()->string PZLUserLicenseLevel procedure ().
Получить значение уровня лицензии контейнера, в котором находится данная компонента</vip>
'''Описание'''
Возвращает значение уровня лицензии контейнера, в котором находится данная pzl-компонента.
Уровень лицензии определяется издателем контейнера путем использования библиотеки с соответствующим уровнем лицензии и может иметь одно из следующих строковых значений
*"Public" (публичная)
*"Commercial" (коммерческая)
*"Exclusive" (эксклюзивная)
*"SuperExclusive" (супер-эксклюзивная)
*"Unknown" (неизвестная)
Если pzl-компонента находится в контейнере главного приложения, тогда возвращается уровень лицензии главного приложения.
'''Пример'''
Код, приведенный ниже, может получить уровень лицензии текущей компоненты
<vip>...
LicenseLevel=pzl::getLicenseLevel(),
stdIO::writef("Уровень лицензии текущего контейнера - %",LicenseLevel),
...</vip>
'''Исключения'''
Нет.
==pzl::getComponentRegisterFileName/0==
<vip>getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure ().
Получить состояние назначения файла-реестра компонент для данного приложения</vip>
'''Описание'''
Возвращает один из следующих термов, определяющих состояние назначения файла-реестра компонент данного приложения.
*pzlRegistryFileName(FileName) - FileName определяет полное имя файла
*pzlRegistryFileNameWronglyDefined - файл-реестр неправильно определен
*pzlRegistryFileNameNotInUse - файл-реестр не используется
'''Пример'''
<vip>
...
RegisterStatus=pzl::getComponentRegisterFileName(),
(
  RegisterStatus=pzlDomains::pzlRegistryFileName(FileName),
  stdio::writef("Файл-реестр компонент - %\n",FileName)
or
  RegisterStatus=pzlDomains::pzlRegistryFileNameNotInUse,
  stdio::write("Файл-реестр компонент не используется\n")
or
  RegisterStatus=pzlDomains::pzlRegistryFileNameWronglyDefined,
  stdio::write("Файл-реестр компонент не был найден при назначении\n")
),
...</vip>
'''Исключения'''


Нет.
==pzl::getContainerContentList/1==
<vip>
getContainerContentList:(string PZLContainerFileName)
  ->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i).
Получить список компонент, содержащихся в контейнере с заданным именем</vip>
'''Описание'''
Предикат возвращает для файла-контейнера с заданным именем список описаний компонент, содержащихся в этом контейнере. Компоненты этого файла-контейнера могут не быть зарегистрированными в pzl-системе.
Для получения компонент, содержащихся в главном приложении в качестве контейнера, имя файла должно быть указано
*"pzlPort" либо
*имя файла (полный или относительный) маршрут к главному приложению
Каждый элемент возвращаемого списка представляет собой терм домена pzlComponentInfo_D
<vip>
pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )
</vip>
Здесь
*Alias - строковое имя компоненты,
*ComponentID - идентификатор компоненты
*Runable - булевый признак возможности самостоятельного запуска компоненты
*UserDefinedInfo - список параметров, задаваемый и интерпретируемый создателем компоненты.
'''Пример'''
В примере ниже по событию onShowComponentsDescription (кнопка на панели) запрашивается информация о компонентах контейнера  "..\\VPPuzzle\\Demo\\PZL\\HelloWorld.pzl", которая выводится в стандартный поток вывода
<vip>
<vip>
predicates
predicates
     classInfo : core::classInfo.
  onShowComponentsDescription : button::clickResponder.
     % @short Class information  predicate.
clauses
     % @detail This predicate represents information predicate of this class.
  onShowComponentsDescription(_Source) = button::defaultAction:-
     % @end
     DataList=pzl::getContainerContentList("..\\VPPuzzle\\Demo\\PZL\\HelloWorld.pzl"),
     foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.
</vip>
В частности, для этого контейнера, получим
<vip>
Element=pzlcomponentinfo("HelloWorld",str("HelloWorld"),1,[])
</vip>
А для контейнера FactDemo_UI тот же код
<vip>
clauses
  onShowComponentsDescription(_Source) = button::defaultAction:-
     DataList=pzl::getContainerContentList("..\\VPPuzzle\\Demo\\PZL\\FactDemo_UI.pzl"),
     foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.
</vip>
Вернет (форматирование элементов терма для наглядности сделано вручную)
<vip>
Data:=pzlcomponentinfo(
  "FactDemo",
  str("Fact_UI"),
  1,
  [
  namedvalue("CodeExporter",string("FactDemoExporter")),
  namedvalue("ProxyExporter",string("FactDemoExporter"))
  ]
  )
</vip>
 
'''Исключения'''
 
Генерируются исключения, если
*Не найден файл-контейнер
*Невозможно загрузить DLL-контейнер
*Версия DLL-контейнера не соответствует версии главного приложения
*Уровень лицензии главного приложения ниже уровня лицензии запрашиваемого контейнера
*DLL-контейнер не соответствует принятым pzl-соглашениям.
 
==pzl::newByID/2==
<vip>newByID:(pzlDomains::entityUID_D ComponentID,object InObject)->object OutObject.
Создать новый объект, используя уникальный идентификатор компоненты</vip>
 
 
'''Описание'''
 
Создает новый объект pzl-компоненты, зарегистрированной c идентификатором ComponentID.
 
Pzl-компонента с указанным идентификатором ComponentID должна быть зарегистрирована в одном из допустимых мест регистрации - в реестре Windows или в файле-реестре пользователя *.pzr.
 
Указатель на объект InObject может быть указателем на любой объект - экземпляр класса. Компонента, чей объект создается, должна знать домен-интерфейс объекта InObject, если в ней предусматривается обращение к этому объекту.
 
Возвращаемый Object является указателем на созданный объект. Для вызова предиката созданного объекта OutObject должен быть преобразован к домену, определяемому интерфейсом этого класса.
 
'''Пример'''
 
Компонента MyComponent поддерживает интерфейс iMyComponent, в котором определен предикат myPredicate(...).
 
<vip>
...
Object=newByID(str("MyComponent"),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...
</vip>
В случае использования уникального идентификатора UID
<vip>
...
Object=newByID(uid(0xDF29A0EA,0x7BA6,0x4425,0x8D,0x88,0x2B,0x3C,0x6F,0xDA,0x0C,0x73),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...
</vip>
 
'''Исключения'''
 
Если pzl-система не может создать экземпляр компоненты по указанным ниже возможным причинам, то генерируется исключение.
 
Возможные причины неуспешного создания компоненты
#pzl-система не имеет доступа к реестру компонент.
#pzl-компонента с указанным именем не найдена в реестре компонент.
#pzl-контейнер, содержащий компоненту, с указанным именем не может быть загружен
#pzl-контейнер и главное приложение имеют несовместимые версии
#главное приложение имеет уровень лицензии ниже, чем pzl-контейнер
#загруженный pzl-контейнер не содержит компоненту с указанным именем
#конструктор данный компоненты не может создать экзмепляр компоненты
 
Если возникает исключительная ситуация, связанная c причинами 3,4 и 5, то pzl-система пытается выгрузить контейнер. При невозможности выгрузить контейнер генерируется исключительная ситуация.
 
В стеке исключительных ситуаций последнее описание исключения содержит текст:
<vip>newByID failured for the Component with the ID <ID>
(предикат NewByID не выполнен для компоненты с идентификатором <ID>"</vip>
 
==pzl::newByName/2==
<vip>newByName:(string Name,object InObject)->object OutObject procedure (i,i).
Создать новый объект, используя имя компоненты</vip>
 
'''Описание'''
 
Создает новый объект pzl-компоненты, зарегистрированной под именем Name.
 
Pzl-компонента с именем Name должна быть зарегистрирована в одном из допустимых мест регистрации - в реестре Windows или в файле-реестре пользователя *.pzr.
 
Указатель на объект InObject может быть указателем на любой объект - экземпляр класса. Компонента, чей объект создается, должна знать домен-интерфейс объекта InObject, если в ней предусматривается обращение к этому объекту.
 
Возвращаемый Object является указателем на созданный объект. Для вызова предиката созданного объекта OutObject должен быть преобразован к домену, определяемому интерфейсом этого класса.
 
'''Пример'''
 
Компонента MyComponent поддерживает интерфейс iMyComponent, в котором определен предикат myPredicate(...).
 
<vip>
...
Object=newByName("MyComponent",This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...
</vip>
 
'''Исключения'''
 
Если pzl-система не может создать экземпляр компоненты по указанным ниже возможным причинам, то генерируется исключение.
 
Возможные причины неуспешного создания компоненты
#pzl-система не имеет доступа к реестру компонент.
#pzl-компонента с указанным именем не найдена в реестре компонент.
#pzl-контейнер, содержащий компоненту, с указанным именем не может быть загружен
#pzl-контейнер и главное приложение имеют несовместимые версии
#главное приложение имеет уровень лицензии ниже, чем pzl-контейнер
#загруженный pzl-контейнер не содержит компоненту с указанным именем
#конструктор данный компоненты не может создать экзмепляр компоненты
 
Если возникает исключительная ситуация, связанная c причинами 3,4 и 5, то pzl-система пытается выгрузить контейнер. При невозможности выгрузить контейнер генерируется исключительная ситуация.
 
В стеке сообщений обработки исключений последнее описание исключения содержит текст:
<vip>newByName failured for the Component 'Name'
(предикат NewByName не выполнен для компоненты с именем "Name")</vip>
 
==pzl::setStdOutputStream/1==
<vip>setStdOutputStream:(outputStream OutputStream).
Назначить заданный выходной поток в качестве стандартного выходного
потока для всех компонент, используемых данным приложением</vip>
 
'''Описание'''
 
Любая компонента может назначить любой существующий выходной поток в качестве стандартного выходного потока. Если это происходит, то все компоненты, используемые данным приложением, начинают использовать этот выходной поток в качестве стандартного.
 
Так, если одна компонента назначила в качестве стандартного выходного потока поток '''A''', а после этого другая компонента назначила в качестве стандартного выходного потока поток '''B''' то, когда управление вернется к первой компоненте, для нее стандартным выходным потоком будет поток '''B''', установленный второй компонентой.
 
Если для первой компоненты такая замена неприемлема, то должны приниматься меры по переназначению необходимого выходного потока.
 
Такое поведение соответсвует принципу целостности приложения, построенного на компонентах.
 
'''Пример'''
 
Следующий пример создает новый выходной поток в окно сообщений и назначает его в качестве стандартного потока вывода
<vip>
...
MessageStream=outputStream_message ::new(),
pzl::setStdOutputStream(MessageStream),
...
</vip>
 
'''Исключения'''
 
Нет.
==pzl::register/2==
<vip>register:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (однократно)</vip>
 
'''Описание'''
 
Позволяет зарегистрировать объект в глобальном (в масштабах данного приложения) регистре экземпляров. Любой объект класса системы программирования Visual Prolog, или объект компоненты могут быть зарегистрированы под именем, действительным в пределах данного приложения.
 
Предикат register(), получая на вход объект Object и строковое имя ObjectName, выбранное пользователем, помещает этот объект под этим именем в регистр.
 
Предикат register позволяет поместить объект с данным именем однократно.
Если в регистре приложения объект с таким именем (независимо от регистра алфавита) уже имеется, то генерируется исключение. Один и тот же объект Object может быть помещен в регистр под различными именами. Повторяемость объекта Object не проверяется.
 
'''Пример'''
 
Следующий пример показывает инициализацию pzl-системы и создание и регистрацию главного окна приложения (TaskWindow), которое может быть создано только один раз. В качестве строкового имени для регистрации используется константное значение, доступное всем компонентам приложения.
<vip>...
run():-
  pzlPort::init(),
  TaskWindow = taskWindow::new(),
  pzl::register(studioConstants::studioTaskWindow_C,TaskWindow),
  TaskWindow:addShowListener(onShow),
  TaskWindow:addMenuItemListener(resourceIdentifiers::id_file_run_profile,onRunProfile),
  TaskWindow:show().
</vip>
По контексту программы известно, что в данном месте окно TaskWindow создается впервые, поэтому обработка возможного исключения не предусмотрена.
 
В примере ниже такая обработка предусмотрена, поскольку возможно повторное создание объекта формы.
Считается, что переменная TaskWindow получила значение прежде и используется в качестве родительского окна
<vip>...
TicketForm = ticketForm::new(),
trap(pzl::register("Билетная Форма",TicketForm ),Error,ExceptionHandler(Error,"Билетная Форма")),
TicketForm :show(TaskWindow).
...
</vip>
 
'''Исключения'''
 
Если в регистре уже имеется объект с таким же именем, что и ObjectName.
 
==pzl::registerMulti/2==
<vip>registerMulti:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (возможно, многократно)</vip>
'''Описание'''
 
Позволяет зарегистрировать объект в глобальном (в масштабах данного приложения) регистре экземпляров. Любой объект класса системы программирования Visual Prolog, или объект компоненты могут быть зарегистрированы под именем, действительным в пределах данного приложения.
 
Предикат registerMulti(...), получая на вход объект Object и строковое имя ObjectName, выбранное пользователем, помещает этот объект под этим именем в регистр.
 
Предикат registerMulti(...) позволяет поместить в регистр только один объект Object c данным именем.
Если такой объект с этим именем уже существует, то никакие действия над регистром не выполняются.
 
Вместе с тем под одним и тем же именем могут быть помещены несколько различных объектов.
 
'''Пример'''
 
Следующий пример показывает регистрацию редактора формы, который может быть создан несколько раз и при каждом создании регистрируется с тем же именем. Программист отвечает за разрешение коллизий между объектами.
<vip>...
FormEditorObject=formEditor::new(This),
pzl::registerMulti("Редактор Формы",FormEditorObject),
FormEditorObject:show(TaskWindow),
...</vip>
 
'''Исключения'''
 
Нет.
==pzl::getObjectByName_nd/1==
<vip>getObjectByName_nd:(string ObjectName)->object Object nondeterm (i).
Получить объект, зарегистрированный под указанным именем ObjectName</vip>
 
'''Описание'''
 
Предикат getObjectByName_nd(...) по заданному имени ObjectName возвращает в недетерминированном режиме все объекты, зарегистрированные ранее в регистре под этим именем.
Если объекта с указанным именем в регистре нет, то предикат завершается неуспешно.
 
'''Пример'''
 
В примере ниже:
 
в первой клаузе проверяется не содержится ли в регистре объект с именем componentAlias_C. Если объект уже создавался, то он преобразуется к домену messageForm и на этот объект устанавливается фокус. Исполнение предиката завершается.
 
Во второй клаузе запоминается текущий выходной поток, создается объект класса messageForm, которому назначается, восстановленное из регистра окно приложения ApplicationWindow. Текущий объект регистрируется в регистре под именем componentAlias_C.
 
Предикат getApplicationWindow() восстанавливает указатель на объект ApplicationWindow из регистра. Если ApplicationWindow не создано (судя по отсутствию регистрации), то генерируется исключительная ситуация.
<vip>
createMessageForm(_InText):-
  Object=pzl::getObjectByName_nd(componentAlias_C),
  LiveObject=convert(messageForm,Object),
  LiveObject:setFocus(),
  !.
createMessageForm(_UserText):-
  defaultOutputStream_V:=stdio::getOutputStream(),
  ApplicationWindow=getApplicationWindow(),
  messageForm_V:=messageForm::display(ApplicationWindow),
  OutputStream=messageForm_V:getOutputStream(),
  pzl::setStdOutputStream(OutputStream),
  pzl::register(componentAlias_C,This),
  messageForm_V:setCloseResponder(onMessageFormCloseRequest),
  messageForm_V:addDestroyListener(onDestroy).


predicates
predicates
    getContainerName:()->string ThisContainerName procedure ().
  getApplicationWindow:()->applicationWindow.
    % @short get the file name of the pzlContainer, in which the given class is placed
clauses
    % @detail Returnes the name (full path) of the file, where the given pzlComponent is placed.<br>
  getApplicationWindow()=convert(applicationWindow,TaskWindowObj):-
     % example:<br>
     TaskWindowObj=pzl::getObjectByName_nd(studioConstants::studioTaskWindow_C),
     ...<br>
     !.
    %  ContainerName=pzl:getContainerName(),<br>
  getApplicationWindow()=_Win:-
     %  stdIO::writef("The component "MyComponent" placed in the Container %",ContainerName),<br>
     common_Exception::raise_User(classInfo,predicate_FullName(),"InternalError: Unexpected Alternative").
    %  ...
</vip>
    % @exception No special exception generated by the PzlSystem<br>
 
    % @end
'''Исключения'''
 
Нет.
==pzl::getNameByObject_nd/1==
<vip>getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i).
Получить регистрационное имя объекта</vip>
 
'''Описание'''
 
Предикат возвращает в недетерминированном режиме все имена, под которыми данный объект был зарегистрирован в регистре активных объектов приложения. Если ни одного объекта в регистре нет, то предикат завершается неуспешно.


predicates
'''Пример'''
    getContainerVersion:()->string ThisContainerVersion procedure ().
 
    % @short get the version of the current pzlContainer, in which the given class is placed
Следующий пример выводит в выходной поток список всех имен, под которыми текущий объект был зарегистрирован в регистре
     % @detail Returnes the version of the pzlContainer, where the given pzlComponent is placed.<br>
<vip>
    % The version of the pzlContainer is of string type and is defined by the constant "pzlContainerVersion_C" in the file iPzlConfig.i
...
    % of the pzlContainer's Project<br>
if not(_RegistryName=pzl::getNameByObject_nd(This)) then
     % example:<br>
  stdio::writef("Текущий объект % в регистре не зарегистрирован",toString(This))
    %  the file iPzlCongig.i of the given pzlContainer contains the declaration of the constant<br>
else
    %  constants<br>
  stdio::write("Список зарегистрированных имен для текущего объекта %\n",This),
    %   pzlContainerVersion_C="1.0;001".<br>
  foreach RegistryName=pzl::getNameByObject_nd(This) do
    % the code below can obtain the version of the current pzlContainer<br>
     stdio::writef("Имя -> %\n",RegistryName)
    %  ContainerVersion=pzl::getContainerVersion(),<br>
  end foreach
    %  stdIO::writef("The version of the Container is  %",ContainerVersion),<br>
endif,
    %  ...
...</vip>
    % @exception No special exception generated by the PzlSystem<br>
'''Исключения'''
    % @end
 
Исключения не генерируются.
 
==pzl::getNameAndObject_nd/2==
<vip>getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o).
Получить имя объекта и сам объект</vip>
 
'''Описание'''
 
Предикат возвращает в недетерминированном режиме все объекты и имена, под которыми они были зарегистрированы в регистре активных объектов приложения. Если ни одного объекта в регистре нет, то предикат завершается неуспешно.
 
'''Пример'''
 
Следующий пример выводит в выходной поток список всех объектов и их имена,
<vip>
...
if not(pzl::getNameAndObject_nd(ObjectName,Object)) then
  stdio::write("Регистр активных объектов пуст\n")
else
  stdio::write("Список зарегистрированных объектов:\n"),
  foreach pzl::getNameAndObject_nd(ObjectName,Object) do
     stdio::writef("Имя: % ;Объект: %\n",ObjectName,toString(Object))
  end foreach
endif,
...</vip>
'''Исключения'''
 
Нет.
==pzl::unRegister/2==
<vip>unRegister:(string ObjectName,object Object) procedure (i,i).
Исключить из регистра объект Object с указанным именем ObjectName</vip>
 
'''Описание'''
 
Предикат удаляет из регистра активных объектов объект Object с указанным именем ObjectName.
Если объекта Object с указанным именем нет, то предикат все равно завершается успешно.
 
'''Пример'''
 
В приведенном примере сначала определяется объект, соответствующий главному окну приложения (TaskWindow), а затем, если объект существует, то он удаляется из регистра
<vip>...
if (TaskWindowObject=pzl::getObjectByName_nd("TaskWindow"),!) then
   pzl::unRegister("TaskWindow",TaskWindowObject)
end if,
...</vip>
 
'''Исключения'''
 
Нет.
 
==pzl::unRegisterByName/1==
<vip>unRegisterByName:(string ObjectName) procedure (i).
Снять с регистрации все объекты с указанным именем ObjectName</vip>
 
'''Описание'''
 
Предикат удаляет из регистра все активные объекты зарегистрированные под указанным именем ObjectName.
Если объектов с указанным именем нет, то предикат все равно завершается успешно.
 
'''Пример'''
 
В приведенном примере сначала определяется объект, соответствующий главному окну приложения (TaskWindow),
<vip>...
pzl::unRegisterByName("TaskWindow"),
...</vip>
 
'''Исключения'''
 
Нет.
 
==pzl::unRegisterByObject/1==
<vip>unRegisterByObject:(object Object) procedure (i).
Снять с регистрации объект Object</vip>
 
'''Описание'''
 
Предикат удаляет из регистра активных объектов все объекты Object.
Если объекта Object с указанным именем нет, то предикат все равно завершается успешно.


predicates
'''Пример'''
    getLicenseLevel:()->string PZLUserLicenseLevel procedure ().
    % @short get the license level of the given pzlContainer, in which the given class is placed
    % @detail Returnes the license level of the pzlContainer, where the given pzlComponent is placed.<br>
    % The License Level is defined by the company, which produces the pzlContainer<br>
    % and may have one of the following string values<br>
    % "Public"<br>
    % "Commercial"<br>
    % "Exclusive"<br>
    % "SuperExclusive"<br>
    % "Unknown"<br>
    %  if the current pzlContainer is the application, then the LicenseLevel returns the License
    %  level of the PzlPort
    %
    % example:<br>
    % the code below can obtain the license level of the current pzlContainer<br>
    %  ...<br>
    %  LicenseLevel=pzl:getLicenseLevel(),<br>
    %  stdIO::writef("The License Level of the current pzlContainer is  %",LicenseLevel),<br>
    %  ...
    % @exception No special exception generated by the PzlSystem<br>
    % @end


В приведенном примере объект MessageForm завершает работу и при этом:
*сохраняет текущее состояние
*удаляет себя из регистра активных компонентов
*восстанавливает состояние выходного потока, существовавшее до создания MessageForm
<vip>...
predicates
predicates
     setStdOutputStream:(outputStream OutputStream).
  onDestroy:window::destroyListener.
clauses
  onDestroy(_Source):-
    setRestoreData(componentAlias_C,[],[]),
     pzl::unRegisterByObject(This), % <--- удаление из регистра информации о себе
    pzl::setStdOutputStream(defaultOutputStream_V),
    messageForm_V:removeDestroyListener(onDestroy),
    defaultOutputStream_V:=erroneous,
    messageForm_V:=erroneous.
...</vip>


predicates
'''Исключения'''
    getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure ().
    getContainerContentList:(string PZLContainerFileName)->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i).


Нет.


predicates
==pzl::unRegisterAll/0==
    newByID:(pzlDomains::entityUID_D,object InObject)->object OutObject.
<vip>unRegisterAll:() procedure ().
Очистить регистр объектов (снять с регистрации все объекты)</vip>


predicates % Creation Object By Name
'''Описание'''
    newByName:(string Name,object InObject)->object OutObject procedure (i,i).
    % @short The class constructor, which creates the new instance of the PzlComponent with the given name
    % @detail Creates the new instance of the pzlComponent with the name Name.
    % The pzlComponent with the name Name must be registered in one of
    % the registration domains - in the Windows Registry or in the local registration file *.pzr.
    % The InObject may be the object pointer of any class instance. And the pzlComponent must
    % know the domain of this Object, if the conversion in the pzlComponent is to be performed.<br>
    %<br>
    % The returned object OutObject is the pointer to the requested object. To invoke the
    % predicate of the named pzlComponent the OutObject must be converted to the domain of
    % this class, for example:<br>
    %  ...<br>
    %  Object=newByName("MyComponent",This),<br>
    %  MyComponentInstance=tryConvert(iMyComponent,Object),<br>
    %  MyComponentInstance:myPredicate(...),<br>
    %  ...
    %
    % @exception The exception is rized if the pzlSystem can not perform the constructor by reasons:<br>
    % - the PzlSystem has no access to the registry store.<br>
    % - the pzlComponent with the given name is not found in the registry Store.<br>
    % - the pzlContainer, which contains the given pzlComponent can not be loaded<br>
    % - the lodaded pzlContainer doesn't contain the given pzlComponent<br>
    % - the constructor of the given pzlComponent can not create the instance<br>
    % The last exception desription contains the text: <br>
    % 'New2. newByName failured for the Component 'Name' '<br>
    % @end


Предикат удаляет из регистра все активные объекты когда-либо зарегистрированные в процессе работы приложения.
Если объектов в регистре нет, то предикат все равно завершается успешно.


    releaseInactiveContainers:().
'''Пример'''
    getContainerActivity_nd:(string FileName,unsigned RefCounter) nondeterm (o,o).
    getContainerToBeUnloaded_nd:(string FileName) nondeterm (o).


    subscribe:(notificationAgency::notificationListener NotificationListener).
<vip>...
    unSubscribe:(notificationAgency::notificationListener NotificationListener).
pzl::unRegisterAll(),
...</vip>


predicates % Object registration
'''Исключения'''
    register:(string ObjectName,object Object) procedure (i,i).
    registerMulti:(string ObjectName,object Object) procedure (i,i).
    getObjectByName_nd:(string ObjectName)->object Object nondeterm (i).
    getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i).
    getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o).
    unRegister:(string ObjectName,object Object) procedure (i,i).
    unRegisterByName:(string ObjectName) procedure (i).
    unRegisterByObject:(object Object) procedure (i).
    unRegisterAll:() procedure ().
</vip>


Нет.


=Ссылки=
[[Категория:VpPuZzle]]
[[Категория:VpPuZzle]]

Текущая версия на 14:42, 21 ноября 2007

Автор: Виктор Юхтенко

Назначение

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

Имплементация класса pzl содержится:

  • в случае pzl-контейнера (DLL) в библиотеке pzlContainer_YY.lib
  • в случае главного приложения в библиотеке pzlPort_XX.lib

здесь YY и XX - уровень лицензии.

Обращения к предикатам этого класса возможны из любого класса, включенного в проект, использующий pzl-технологию.

Список нестандартных доменов, используемых классом

pzlComponentsRegisterFileName_D Состояние файла-реестра компонент данного приложения
pzlContainerContentInfo_D Информация о компонентах контейнера
pzlComponentInfo_D Описание pzl-компоненты контейнера
entityUID_D Идентификатор сущности

Список предикатов класса

Предикаты класса Pzl можно разбить условно на группы (стандартный для VIP предикат classInfo не рассматривается):

  • Информация о контейнере. Эта группа обычно не используется в прикладном программировании и служит для получения информации о контейнере и приложении - уровень лицензии, информация о компонентах и т.д.
  • Управление компонентами. Эта группа используется чаще, чем предыдущая, но без обращения к ней также можно обойтись при использовании стандартного для VIP способа порождения экземпляров классов. Позволяет создавать экземпляры компонент, используя их идентификаторы и имена. В этой же группе содержится предикат переназначения стандартного потока вывода.
  • Регистрация объектов. Эта группа наиболее часто используется в прикладном программировании, поскольку обеспечивает возможность получания информации об активных объектах приложения из любого класса и объекта приложения.
  • Служебные предикаты. Cозданы для использования специальными средствами в специальных целях. Использовать не рекомендуется.
classInfo.
Получение информации о версии и дате последнего изменения класса Pzl
Информация о контейнере
getContainerName:()->string ThisContainerName procedure ().
Получить имя файла-контейнера, в котором находится данная компонента
getContainerVersion:()->string ThisContainerVersion procedure ().
Получить идентификатор версии контейнера, в котором находится данная компонента
getLicenseLevel:()->string PZLUserLicenseLevel procedure ().
Получить значение уровня лицензии контейнера, в котором находится данная компонента
getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure ().
Получить имя файла-реестра компонент, назначенного для данного приложения
getContainerContentList:(string PZLContainerFileName)->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i).
Получить список компонент, содержащихся в контейнере с заданным именем
Управление компонентами
setStdOutputStream:(outputStream OutputStream).
Назначить заданный выходной поток в качестве стандартного выходного потока для всех компонент, используемых данным приложением
newByName:(string Name,object InObject)->object OutObject procedure (i,i).
Создать новый объект, используя имя компоненты
newByID:(pzlDomains::entityUID_D,object InObject)->object OutObject.
Создать новый объект, используя уникальный идентификатор компоненты
Регистрация объектов
register:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (однократно)
registerMulti:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (возможно, многократно)
getObjectByName_nd:(string ObjectName)->object Object nondeterm (i).
Получить объект, зарегистрированный под указанным именем ObjectName
getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i).
Получить регистрационное имя объекта
getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o).
Получить имя объекта и сам объект
unRegister:(string ObjectName,object Object) procedure (i,i).
Снять с регистрации объект Object с указанным именем ObjectName
unRegisterByName:(string ObjectName) procedure (i).
Снять с регистрации все объекты с указанным именем ObjectName
unRegisterByObject:(object Object) procedure (i).
Снять с регистрации объект Object
unRegisterAll:() procedure ().
Очистить регистр объектов (снять с регистрации все объекты)
Служебные предикаты. Не документируются
releaseInactiveContainers:().
getContainerActivity_nd:(string FileName,unsigned RefCounter) nondeterm (o,o).
getContainerToBeUnloaded_nd:(string FileName) nondeterm (o).
subscribe:(notificationAgency::notificationListener NotificationListener).
unSubscribe:(notificationAgency::notificationListener NotificationListener).
newInstance:().
release:().

Используемые дополнительные ресурсы

Обязательно:

  • Класс Pzl использует библиотеку pzlPort_XX.lib, если целью проекта является исполняемоее приложение (.EXE) и библиотеку pzlContainer_XX - если целью проекта является контейнер (DLL). Указанные библиотеки фактически содержат имплементацию класса Pzl.
  • наличие пакета pzlConfig.

Описание доменов

pzlDomains::pzlComponentsRegisterFileName_D

Состояние файла-реестра компонент

pzlComponentsRegisterFileName_D=
  pzlRegistryFileName(string FileName);
  pzlRegistryFileNameWronglyDefined;
  pzlRegistryFileNameNotInUse.

Определяет одно из состояний назначения файла-реестра компонент для данного приложения.

pzlRegistryFileName(string FileName)
назначен файл с именем FileName.
pzlRegistryFileNameWronglyDefined
файл-реестр неправильно определен, возможно, отсутствовал на момент назначения.
pzlRegistryFileNameNotInUse
файл-реестр к данному моменту не назначался, то есть не используется.

pzlDomains::entityUID_D

Домен служит для идентификации различных сущностей. Имеет две возможные формы:

  • простую str(string)
  • сложную uid(...), соответствующую nativeGuid системы Visual Prolog, которая, в свою очередь соответствует GUID фирмы Microsoft.

Простая форма не обеспечивает уникальности идентификаторов и рекомендуется для использования в примерах и упражнениях.

Сложная форма обеспечивает уникальность, но неудобна для восприятия и требует автоматизации манипулирования.

domains
  entityUID_D =
    str(string Строковый идентификатор);
    uid(
       core::unsigned32 Unsigned,
       core::unsigned16 Short1,
       core::unsigned16 Short2,
       core::unsigned8 Byte1,
       core::unsigned8 Byte2,
       core::unsigned8 Byte3,
       core::unsigned8 Byte4,
       core::unsigned8 Byte5,
       core::unsigned8 Byte6,
       core::unsigned8 Byte7,
       core::unsigned8 Byte8
       ).

pzlDomains::pzlContainerContentInfo_D, pzlDomains::pzlComponentInfo_D

Домен pzlContainerContentInfo_D используется в качестве описания состава pzl-контейнеров. Представляет список описаний отдельных компонент.

pzlContainerContentInfo_D = pzlComponentInfo_D*.

Каждый элемент списка представляет собой терм домена pzlComponentInfo_D

pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )

Здесь

  • Alias - строковое имя компоненты,
  • ComponentID - идентификатор компоненты
  • Runable - булевый признак возможности самостоятельного запуска компоненты
  • UserDefinedInfo - список параметров, задаваемый и интерпретируемый создателем компоненты.

Описание предикатов

pzl::getContainerName/0

getContainerName:()->string ThisContainerName procedure ().
Получить имя файла-контейнера, в котором находится данная компонента

Описание

Возвращает имя (полный маршрут) файла, в котором находится данная pzl-компонента.

Пример

...
ContainerName=pzl::getContainerName(),
stdIO::writef("Компонента /"MyComponent/" находится в контейнер %",ContainerName),
...

Исключения

Нет.

pzl::getContainerVersion/0

getContainerVersion:()->string ThisContainerVersion procedure ().
Получить идентификатор версии контейнера, в котором находится данная компонента

Описание

Возвращает версию pzl-контейнера, в котором находится данная компонента.

Версия контейнера представляется значением строкового типа (string) и определяется константой "pzlContainerVersion_C" в файле iPzlConfig.i проекта контейнера.

Пример

Например, файл iPzlConfig.i данного контейнера содержит объявление константы

constants
  pzlContainerVersion_C="1.0;001".

Следующий код получает номер версии данного контейнера

...
ContainerVersion=pzl::getContainerVersion(),
stdIO::writef("Версия контейнера - %",ContainerVersion),
...

В стандартный выходной поток будет выведено: "Версия контейнера - 1.0;001"

Исключения

Нет.

pzl::getLicenseLevel/0

getLicenseLevel:()->string PZLUserLicenseLevel procedure ().
Получить значение уровня лицензии контейнера, в котором находится данная компонента

Описание

Возвращает значение уровня лицензии контейнера, в котором находится данная pzl-компонента. Уровень лицензии определяется издателем контейнера путем использования библиотеки с соответствующим уровнем лицензии и может иметь одно из следующих строковых значений

  • "Public" (публичная)
  • "Commercial" (коммерческая)
  • "Exclusive" (эксклюзивная)
  • "SuperExclusive" (супер-эксклюзивная)
  • "Unknown" (неизвестная)

Если pzl-компонента находится в контейнере главного приложения, тогда возвращается уровень лицензии главного приложения.

Пример

Код, приведенный ниже, может получить уровень лицензии текущей компоненты

...
LicenseLevel=pzl::getLicenseLevel(),
stdIO::writef("Уровень лицензии текущего контейнера - %",LicenseLevel),
...

Исключения

Нет.

pzl::getComponentRegisterFileName/0

getComponentRegisterFileName:()->pzlDomains::pzlComponentsRegisterFileName_D ComponentRegisterFileName procedure ().
Получить состояние назначения файла-реестра компонент для данного приложения

Описание

Возвращает один из следующих термов, определяющих состояние назначения файла-реестра компонент данного приложения.

  • pzlRegistryFileName(FileName) - FileName определяет полное имя файла
  • pzlRegistryFileNameWronglyDefined - файл-реестр неправильно определен
  • pzlRegistryFileNameNotInUse - файл-реестр не используется

Пример

...
RegisterStatus=pzl::getComponentRegisterFileName(),
(
   RegisterStatus=pzlDomains::pzlRegistryFileName(FileName),
   stdio::writef("Файл-реестр компонент - %\n",FileName)
or
   RegisterStatus=pzlDomains::pzlRegistryFileNameNotInUse,
   stdio::write("Файл-реестр компонент не используется\n")
or
   RegisterStatus=pzlDomains::pzlRegistryFileNameWronglyDefined,
   stdio::write("Файл-реестр компонент не был найден при назначении\n")
),
...

Исключения

Нет.

pzl::getContainerContentList/1

getContainerContentList:(string PZLContainerFileName)
  ->pzlDomains::pzlContainerContentInfo_D ContentInfo procedure (i).
Получить список компонент, содержащихся в контейнере с заданным именем

Описание

Предикат возвращает для файла-контейнера с заданным именем список описаний компонент, содержащихся в этом контейнере. Компоненты этого файла-контейнера могут не быть зарегистрированными в pzl-системе.

Для получения компонент, содержащихся в главном приложении в качестве контейнера, имя файла должно быть указано

  • "pzlPort" либо
  • имя файла (полный или относительный) маршрут к главному приложению

Каждый элемент возвращаемого списка представляет собой терм домена pzlComponentInfo_D

pzlComponentInfo_D=pzlComponentInfo
  (
  string Alias,
  entityUID_D ComponentID,
  booleanInt Runable,
  core::namedValue_List UserDefinedInfo
  )

Здесь

  • Alias - строковое имя компоненты,
  • ComponentID - идентификатор компоненты
  • Runable - булевый признак возможности самостоятельного запуска компоненты
  • UserDefinedInfo - список параметров, задаваемый и интерпретируемый создателем компоненты.

Пример

В примере ниже по событию onShowComponentsDescription (кнопка на панели) запрашивается информация о компонентах контейнера "..\\VPPuzzle\\Demo\\PZL\\HelloWorld.pzl", которая выводится в стандартный поток вывода

predicates
  onShowComponentsDescription : button::clickResponder.
clauses
  onShowComponentsDescription(_Source) = button::defaultAction:-
    DataList=pzl::getContainerContentList("..\\VPPuzzle\\Demo\\PZL\\HelloWorld.pzl"),
    foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.

В частности, для этого контейнера, получим

Element=pzlcomponentinfo("HelloWorld",str("HelloWorld"),1,[])

А для контейнера FactDemo_UI тот же код

clauses
  onShowComponentsDescription(_Source) = button::defaultAction:-
    DataList=pzl::getContainerContentList("..\\VPPuzzle\\Demo\\PZL\\FactDemo_UI.pzl"),
    foreach Element=list::getMember_nd(DataList) do
      stdio::writef("Element=%\n",Element)
    end foreach.

Вернет (форматирование элементов терма для наглядности сделано вручную)

Data:=pzlcomponentinfo(
  "FactDemo",
   str("Fact_UI"),
   1,
   [
   namedvalue("CodeExporter",string("FactDemoExporter")),
   namedvalue("ProxyExporter",string("FactDemoExporter"))
   ]
   )

Исключения

Генерируются исключения, если

  • Не найден файл-контейнер
  • Невозможно загрузить DLL-контейнер
  • Версия DLL-контейнера не соответствует версии главного приложения
  • Уровень лицензии главного приложения ниже уровня лицензии запрашиваемого контейнера
  • DLL-контейнер не соответствует принятым pzl-соглашениям.

pzl::newByID/2

newByID:(pzlDomains::entityUID_D ComponentID,object InObject)->object OutObject.
Создать новый объект, используя уникальный идентификатор компоненты


Описание

Создает новый объект pzl-компоненты, зарегистрированной c идентификатором ComponentID.

Pzl-компонента с указанным идентификатором ComponentID должна быть зарегистрирована в одном из допустимых мест регистрации - в реестре Windows или в файле-реестре пользователя *.pzr.

Указатель на объект InObject может быть указателем на любой объект - экземпляр класса. Компонента, чей объект создается, должна знать домен-интерфейс объекта InObject, если в ней предусматривается обращение к этому объекту.

Возвращаемый Object является указателем на созданный объект. Для вызова предиката созданного объекта OutObject должен быть преобразован к домену, определяемому интерфейсом этого класса.

Пример

Компонента MyComponent поддерживает интерфейс iMyComponent, в котором определен предикат myPredicate(...).

...
Object=newByID(str("MyComponent"),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

В случае использования уникального идентификатора UID

...
Object=newByID(uid(0xDF29A0EA,0x7BA6,0x4425,0x8D,0x88,0x2B,0x3C,0x6F,0xDA,0x0C,0x73),This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

Исключения

Если pzl-система не может создать экземпляр компоненты по указанным ниже возможным причинам, то генерируется исключение.

Возможные причины неуспешного создания компоненты

  1. pzl-система не имеет доступа к реестру компонент.
  2. pzl-компонента с указанным именем не найдена в реестре компонент.
  3. pzl-контейнер, содержащий компоненту, с указанным именем не может быть загружен
  4. pzl-контейнер и главное приложение имеют несовместимые версии
  5. главное приложение имеет уровень лицензии ниже, чем pzl-контейнер
  6. загруженный pzl-контейнер не содержит компоненту с указанным именем
  7. конструктор данный компоненты не может создать экзмепляр компоненты

Если возникает исключительная ситуация, связанная c причинами 3,4 и 5, то pzl-система пытается выгрузить контейнер. При невозможности выгрузить контейнер генерируется исключительная ситуация.

В стеке исключительных ситуаций последнее описание исключения содержит текст:

newByID failured for the Component with the ID <ID>
(предикат NewByID не выполнен для компоненты с идентификатором <ID>"

pzl::newByName/2

newByName:(string Name,object InObject)->object OutObject procedure (i,i).
Создать новый объект, используя имя компоненты

Описание

Создает новый объект pzl-компоненты, зарегистрированной под именем Name.

Pzl-компонента с именем Name должна быть зарегистрирована в одном из допустимых мест регистрации - в реестре Windows или в файле-реестре пользователя *.pzr.

Указатель на объект InObject может быть указателем на любой объект - экземпляр класса. Компонента, чей объект создается, должна знать домен-интерфейс объекта InObject, если в ней предусматривается обращение к этому объекту.

Возвращаемый Object является указателем на созданный объект. Для вызова предиката созданного объекта OutObject должен быть преобразован к домену, определяемому интерфейсом этого класса.

Пример

Компонента MyComponent поддерживает интерфейс iMyComponent, в котором определен предикат myPredicate(...).

...
Object=newByName("MyComponent",This),
MyComponentInstance=tryConvert(iMyComponent,Object),
MyComponentInstance:myPredicate(...),
...

Исключения

Если pzl-система не может создать экземпляр компоненты по указанным ниже возможным причинам, то генерируется исключение.

Возможные причины неуспешного создания компоненты

  1. pzl-система не имеет доступа к реестру компонент.
  2. pzl-компонента с указанным именем не найдена в реестре компонент.
  3. pzl-контейнер, содержащий компоненту, с указанным именем не может быть загружен
  4. pzl-контейнер и главное приложение имеют несовместимые версии
  5. главное приложение имеет уровень лицензии ниже, чем pzl-контейнер
  6. загруженный pzl-контейнер не содержит компоненту с указанным именем
  7. конструктор данный компоненты не может создать экзмепляр компоненты

Если возникает исключительная ситуация, связанная c причинами 3,4 и 5, то pzl-система пытается выгрузить контейнер. При невозможности выгрузить контейнер генерируется исключительная ситуация.

В стеке сообщений обработки исключений последнее описание исключения содержит текст:

newByName failured for the Component 'Name'
(предикат NewByName не выполнен для компоненты с именем "Name")

pzl::setStdOutputStream/1

setStdOutputStream:(outputStream OutputStream).
Назначить заданный выходной поток в качестве стандартного выходного
потока для всех компонент, используемых данным приложением

Описание

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

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

Если для первой компоненты такая замена неприемлема, то должны приниматься меры по переназначению необходимого выходного потока.

Такое поведение соответсвует принципу целостности приложения, построенного на компонентах.

Пример

Следующий пример создает новый выходной поток в окно сообщений и назначает его в качестве стандартного потока вывода

...
MessageStream=outputStream_message ::new(),
pzl::setStdOutputStream(MessageStream),
...

Исключения

Нет.

pzl::register/2

register:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (однократно)

Описание

Позволяет зарегистрировать объект в глобальном (в масштабах данного приложения) регистре экземпляров. Любой объект класса системы программирования Visual Prolog, или объект компоненты могут быть зарегистрированы под именем, действительным в пределах данного приложения.

Предикат register(), получая на вход объект Object и строковое имя ObjectName, выбранное пользователем, помещает этот объект под этим именем в регистр.

Предикат register позволяет поместить объект с данным именем однократно. Если в регистре приложения объект с таким именем (независимо от регистра алфавита) уже имеется, то генерируется исключение. Один и тот же объект Object может быть помещен в регистр под различными именами. Повторяемость объекта Object не проверяется.

Пример

Следующий пример показывает инициализацию pzl-системы и создание и регистрацию главного окна приложения (TaskWindow), которое может быть создано только один раз. В качестве строкового имени для регистрации используется константное значение, доступное всем компонентам приложения.

...
run():-
  pzlPort::init(),
  TaskWindow = taskWindow::new(),
  pzl::register(studioConstants::studioTaskWindow_C,TaskWindow),
  TaskWindow:addShowListener(onShow),
  TaskWindow:addMenuItemListener(resourceIdentifiers::id_file_run_profile,onRunProfile),
  TaskWindow:show().

По контексту программы известно, что в данном месте окно TaskWindow создается впервые, поэтому обработка возможного исключения не предусмотрена.

В примере ниже такая обработка предусмотрена, поскольку возможно повторное создание объекта формы. Считается, что переменная TaskWindow получила значение прежде и используется в качестве родительского окна

...
TicketForm = ticketForm::new(),
trap(pzl::register("Билетная Форма",TicketForm ),Error,ExceptionHandler(Error,"Билетная Форма")),
TicketForm :show(TaskWindow).
...

Исключения

Если в регистре уже имеется объект с таким же именем, что и ObjectName.

pzl::registerMulti/2

registerMulti:(string ObjectName,object Object) procedure (i,i).
Зарегистрировать объект под указанным именем ObjectName (возможно, многократно)

Описание

Позволяет зарегистрировать объект в глобальном (в масштабах данного приложения) регистре экземпляров. Любой объект класса системы программирования Visual Prolog, или объект компоненты могут быть зарегистрированы под именем, действительным в пределах данного приложения.

Предикат registerMulti(...), получая на вход объект Object и строковое имя ObjectName, выбранное пользователем, помещает этот объект под этим именем в регистр.

Предикат registerMulti(...) позволяет поместить в регистр только один объект Object c данным именем. Если такой объект с этим именем уже существует, то никакие действия над регистром не выполняются.

Вместе с тем под одним и тем же именем могут быть помещены несколько различных объектов.

Пример

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

...
FormEditorObject=formEditor::new(This),
pzl::registerMulti("Редактор Формы",FormEditorObject),
FormEditorObject:show(TaskWindow),
...

Исключения

Нет.

pzl::getObjectByName_nd/1

getObjectByName_nd:(string ObjectName)->object Object nondeterm (i).
Получить объект, зарегистрированный под указанным именем ObjectName

Описание

Предикат getObjectByName_nd(...) по заданному имени ObjectName возвращает в недетерминированном режиме все объекты, зарегистрированные ранее в регистре под этим именем. Если объекта с указанным именем в регистре нет, то предикат завершается неуспешно.

Пример

В примере ниже:

в первой клаузе проверяется не содержится ли в регистре объект с именем componentAlias_C. Если объект уже создавался, то он преобразуется к домену messageForm и на этот объект устанавливается фокус. Исполнение предиката завершается.

Во второй клаузе запоминается текущий выходной поток, создается объект класса messageForm, которому назначается, восстановленное из регистра окно приложения ApplicationWindow. Текущий объект регистрируется в регистре под именем componentAlias_C.

Предикат getApplicationWindow() восстанавливает указатель на объект ApplicationWindow из регистра. Если ApplicationWindow не создано (судя по отсутствию регистрации), то генерируется исключительная ситуация.

createMessageForm(_InText):-
  Object=pzl::getObjectByName_nd(componentAlias_C),
  LiveObject=convert(messageForm,Object),
  LiveObject:setFocus(),
  !.
createMessageForm(_UserText):-
  defaultOutputStream_V:=stdio::getOutputStream(),
  ApplicationWindow=getApplicationWindow(),
  messageForm_V:=messageForm::display(ApplicationWindow),
  OutputStream=messageForm_V:getOutputStream(),
  pzl::setStdOutputStream(OutputStream),
  pzl::register(componentAlias_C,This),
  messageForm_V:setCloseResponder(onMessageFormCloseRequest),
  messageForm_V:addDestroyListener(onDestroy).
 
predicates
  getApplicationWindow:()->applicationWindow.
clauses
  getApplicationWindow()=convert(applicationWindow,TaskWindowObj):-
    TaskWindowObj=pzl::getObjectByName_nd(studioConstants::studioTaskWindow_C),
    !.
  getApplicationWindow()=_Win:-
    common_Exception::raise_User(classInfo,predicate_FullName(),"InternalError: Unexpected Alternative").

Исключения

Нет.

pzl::getNameByObject_nd/1

getNameByObject_nd:(object Object)->string ObjectNameLow nondeterm (i).
Получить регистрационное имя объекта

Описание

Предикат возвращает в недетерминированном режиме все имена, под которыми данный объект был зарегистрирован в регистре активных объектов приложения. Если ни одного объекта в регистре нет, то предикат завершается неуспешно.

Пример

Следующий пример выводит в выходной поток список всех имен, под которыми текущий объект был зарегистрирован в регистре

...
if not(_RegistryName=pzl::getNameByObject_nd(This)) then
  stdio::writef("Текущий объект % в регистре не зарегистрирован",toString(This))
else
  stdio::write("Список зарегистрированных имен для текущего объекта %\n",This),
  foreach RegistryName=pzl::getNameByObject_nd(This) do
    stdio::writef("Имя -> %\n",RegistryName)
  end foreach
endif,
...

Исключения

Исключения не генерируются.

pzl::getNameAndObject_nd/2

getNameAndObject_nd:(string ObjectName,object Object) nondeterm (o,o).
Получить имя объекта и сам объект

Описание

Предикат возвращает в недетерминированном режиме все объекты и имена, под которыми они были зарегистрированы в регистре активных объектов приложения. Если ни одного объекта в регистре нет, то предикат завершается неуспешно.

Пример

Следующий пример выводит в выходной поток список всех объектов и их имена,

...
if not(pzl::getNameAndObject_nd(ObjectName,Object)) then
  stdio::write("Регистр активных объектов пуст\n")
else
  stdio::write("Список зарегистрированных объектов:\n"),
  foreach pzl::getNameAndObject_nd(ObjectName,Object) do
    stdio::writef("Имя: % ;Объект: %\n",ObjectName,toString(Object))
  end foreach
endif,
...

Исключения

Нет.

pzl::unRegister/2

unRegister:(string ObjectName,object Object) procedure (i,i).
Исключить из регистра объект Object с указанным именем ObjectName

Описание

Предикат удаляет из регистра активных объектов объект Object с указанным именем ObjectName. Если объекта Object с указанным именем нет, то предикат все равно завершается успешно.

Пример

В приведенном примере сначала определяется объект, соответствующий главному окну приложения (TaskWindow), а затем, если объект существует, то он удаляется из регистра

...
if (TaskWindowObject=pzl::getObjectByName_nd("TaskWindow"),!) then
  pzl::unRegister("TaskWindow",TaskWindowObject)
end if,
...

Исключения

Нет.

pzl::unRegisterByName/1

unRegisterByName:(string ObjectName) procedure (i).
Снять с регистрации все объекты с указанным именем ObjectName

Описание

Предикат удаляет из регистра все активные объекты зарегистрированные под указанным именем ObjectName. Если объектов с указанным именем нет, то предикат все равно завершается успешно.

Пример

В приведенном примере сначала определяется объект, соответствующий главному окну приложения (TaskWindow),

...
pzl::unRegisterByName("TaskWindow"),
...

Исключения

Нет.

pzl::unRegisterByObject/1

unRegisterByObject:(object Object) procedure (i).
Снять с регистрации объект Object

Описание

Предикат удаляет из регистра активных объектов все объекты Object. Если объекта Object с указанным именем нет, то предикат все равно завершается успешно.

Пример

В приведенном примере объект MessageForm завершает работу и при этом:

  • сохраняет текущее состояние
  • удаляет себя из регистра активных компонентов
  • восстанавливает состояние выходного потока, существовавшее до создания MessageForm
...
predicates
  onDestroy:window::destroyListener.
clauses
  onDestroy(_Source):-
    setRestoreData(componentAlias_C,[],[]),
    pzl::unRegisterByObject(This), % <--- удаление из регистра информации о себе
    pzl::setStdOutputStream(defaultOutputStream_V),
    messageForm_V:removeDestroyListener(onDestroy),
    defaultOutputStream_V:=erroneous,
    messageForm_V:=erroneous.
...

Исключения

Нет.

pzl::unRegisterAll/0

unRegisterAll:() procedure ().
Очистить регистр объектов (снять с регистрации все объекты)

Описание

Предикат удаляет из регистра все активные объекты когда-либо зарегистрированные в процессе работы приложения. Если объектов в регистре нет, то предикат все равно завершается успешно.

Пример

...
pzl::unRegisterAll(),
...

Исключения

Нет.

Ссылки