Приложения

Приложение А. Функции, константы и структуры RDS

А.2. События блока и связанные с ними описания

А.2.3. RDS_BLOCKDATA – структура данных блока

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

  typedef struct {
    LPVOID VarTreeData;    // Адрес дерева переменных блока
    LPVOID BlockData;      // Адрес личной области данных блока
    RDS_BHANDLE Block;     // Идентификатор блока
    RDSCSTR BlockNameA;    // Имя блока (UTF8)
    RDSWCSTR BlockNameW;   // Имя блока (UTF16)
    //RDSXCSTR BlockName;  // Имя блока (поле-псевдоним)
    RDS_BHANDLE Parent;    // Идентификатор подсистемы
    DWORD Flags;           // Флаги
    RDSINT32 Width,Height; // Размеры прямоугольника блока
    RDSINT32 Tag;          // Пользовательское поле
  } RDS_BLOCKDATA;
  typedef RDS_BLOCKDATA *RDS_PBLOCKDATA;

Поля структуры

VarTreeData (LPVOID)

Указатель на дерево переменных блока. В дереве переменных хранятся все значения статических переменных блока, функция модели может считывать их оттуда и записывать туда новые значения. Для переменных сложной структуры (строк, массивов, структур, переменных произвольного типа) в дереве переменных хранятся указатели на области памяти, занимаемые этими переменными, в которых, в свою очередь, могут содержаться указатели на другие области и т.д., поэтому данные переменных блока в общем случае имеют древовидную структуру. Для изменения размера массивов и длины строк, изменения фактического типа переменных произвольного типа и операций со сложными переменными предусмотрены специальные сервисные функции RDS, модель блока не должна самостоятельно пытаться отводить память в дереве переменных или изменять значение самого поля VarTreeData. Работа со статическими переменными блока подробно рассмотрена в §2.5 руководства программиста.

BlockData (LPVOID)

Указатель на личную область данных блока. Перед самым первым для данного блока вызовом модели RDS записывает в это поле значение NULL и больше к нему не обращается. Если модели блока требуется отводить память под свои нужды, она может записать указатель на отведенную область памяти в это поле. В этом случае освободить отведенную область тоже должна будет функция модели – обычно это делается в реакции на событие RDS_BFM_CLEANUP, вызываемой непосредственно перед отключением модели от блока. Фактически, поскольку RDS никак не вмешивается в работу функции модели с этим полем, разработчик может использовать его для хранения любого нужного ему указателя.

Block (RDS_BHANDLE)

Уникальный идентификатор данного блока. Для идентификаторов блоков в RDS введен специальный тип RDS_BHANDLE, такие идентификаторы используются в сервисных функциях для указания блока, с которым нужно произвести то или иное действие. Из этого поля функция модели может считать идентификатор «своего» блока, менять значение поля она не должна.

BlockNameA (RDSCSTR), BlockNameW (RDSWCSTR), BlockName (RDSXCSTR)

Указатель на строку во внутренней памяти RDS, в которой хранится имя данного блока. Функция модели не должна как-либо изменять эту строку, для переименования блоков существует специальная сервисная функция rdsRenameBlock.

Parent (RDS_BHANDLE)

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

Flags (DWORD)

Битовые флаги, определяющие состояние и поведение блока – некоторые из них модель может и читать, и писать, некоторые – только читать (их изменение игнорируется RDS):

RDS_VARCHECKFAILED	Блок имеет не совместимую с моделью структуру статических переменных. Этот флаг взводится RDS по результатам вызова модели блока для проверки типов переменных (событие RDS_BFM_VARCHECK). Модель блока может только читать этот флаг, его установка игнорируется. На самом деле, модель сможет обнаружить этот флаг взведенным только в реакции на событие отключения модели RDS_BFM_CLEANUP, поскольку при несовместимом типе переменных все остальные вызовы модели блокируются.
RDS_NEEDSDLLREDRAW	Действия, выполненные функцией модели, привели к изменению внешнего вида блока, и он должен быть перерисован при следующем обновлении окна подсистемы. Этот флаг используется только в блоках, изображения которых рисуются функцией модели программно в реакции на событие RDS_BFM_DRAW, для всех остальных блоков он игнорируется. Перед любым вызовом функции модели RDS автоматически взводит этот флаг, поэтому модели не обязательно работать с ним – если она ничего не предпримет, блок будет перерисован. Если внешний вид блока в результате вызова функции модели не изменился, модель может сбросить этот флаг чтобы избежать затрат времени на лишнюю перерисовку.
RDS_MOUSECAPTURE	Блок «захватил» мышь: если модель взведет этот флаг, информация обо всех манипуляциях мышью в окне родительской подсистемы блока будет поступать только в этот блок, независимо от того, над каким блоком находится курсор. Сброс флага восстановит нормальный порядок работы. Установка и сброс этого флага возможны только в реакциях на перемещение мыши или нажатие и отпускание ее кнопок, во всех остальных реакциях RDS игнорирует изменения этого флага и возвращает его в исходное состояние.
RDS_PROCESSUNHANDLEDMOUSE	Блок обрабаывает действия пользователя мышью в своей подсистеме не на своем изображении.
RDS_NAMEMOUSEREACTION	Перемещения курсора мыши и нажатие ее кнопок на отображаемом имени блока в режимах моделирования и расчета порождает такие же события, как и аналогичные действия с изображением блока.
RDS_NOWINREFRESH	При взведении этого флага перерисовка немодальных окон данного блока (если они есть) или окна подсистемы (если данный блок – подсистема) будет временно запрещена. Временное запрещение обновления окон используется в тех случаях, когда выполняется какая-либо длительная операция, занимающая несколько тактов расчета, и в середине этой операции, когда готовы еще не все данные, перерисовывать окна нежелательно. Для установки и сброса этого флага обычно применяется сервисная функция rdsEnableWindowRefresh, но, при желании, разработчик модели может управлять им непосредственно.
RDS_WINREFRESHWAITING	Установка этого флага сигнализирует о том, что немодальные окна блока или окно подсистемы необходимо перерисовать, как только обновление окон будет разрешено. Если обновление окон запрещено (взведен флаг RDS_NOWINREFRESH) и поступает команда обновления (по таймеру или от сервисной функции rdsRefreshBlockWindows), этот флаг взводится автоматически. Как только обновление окон снова будет разрешено сервисной функцией rdsEnableWindowRefresh, RDS проверит флаг RDS_WINREFRESHWAITING и, если он установлен, даст повторную команду на обновление окон. При необходимости, разработчик модели может взводить и сбрасывать этот флаг вручную.
RDS_DISABLED	Блок не реагирует на действия пользователя: пользователь не сможет удалить этот блок, изменить его параметры и выделить его в режиме редактирования. RDS не взводит этот флаг, модель блока может управлять им самостоятельно. По умолчанию флаг сброшен.
RDS_CTRLCALC	Если этот флаг взведен, перед началом каждого такта расчета модель этого блока вызывается для реакции на событие RDS_BFM_PREMODEL в том случае, если в этом такте блок должен быть запущен в режиме RDS_BFM_MODEL, то есть если он запускается каждый такт или его первая статическая переменная («Start») не равна нулю. По умолчанию флаг сброшен, модель может взвести его, если ей нужно вызываться непосредственно перед каждым тактом расчета. Взвести флаг нужно до перехода в режим моделирования или расчета, иначе его фактическая установка будет отложена до перехода в режим редактирования (это связано с внутренней логикой работы RDS).
RDS_SUSPENDED	Была вызвана сервисная функция rdsSuspendCalc для остановки вызовов этого блока и его соседей в режимах RDS_BFM_MODEL и RDS_BFM_PREMODEL. Следует учитывать, что вызовы будут продолжаться несмотря на это, если взведен флаг RDS_NOSUSPEND (см. ниже).
RDS_NOSUSPEND	Вызовы блока в режимах RDS_BFM_MODEL и RDS_BFM_PREMODEL не могут быть остановлены сервисной функцией rdsSuspendCalc. По умолчанию флаг сброшен, модель может его установить.
RDS_ALWAYSSETUP	Вход в настройку блока разрешен, даже если проверка переменных вернула ошибку (установлен флаг RDS_VARCHECKFAILED). По умолчанию флаг сброшен, модель может его установить.
RDS_ALWAYSLOADSAVE	Сохранение и загрузка параметров блока разрешены, даже если проверка переменных вернула ошибку (установлен флаг RDS_VARCHECKFAILED). По умолчанию флаг сброшен, модель может его установить.
RDS_BLOCKHASHELP	У блока есть пункт «справка» в контекстном меню. По умолчанию флаг сброшен, модель может взвести его, если для блока предусмотрена справка и она будет реагировать на событие RDS_BFM_HELP, показывая ее.
RDS_LOCKTEXTRECT	Изменение параметров прямоугольника с текстом во внешнем виде блока производится программно или в настройках самого блока. При установленном флаге в окне параметров блока на вкладке «внешний вид» выводится предупреждение и запрещается редактроование параметров прямоугольника. По умолчанию флаг сброшен, модель устанавливает его при необходимости заблокировать редактирование.
RDS_HIDESTART	Скрывать переменную «Start» при присоединении связей к блоку. Если модель блока программно управляет его запуском, взведение флага запуска по связи может нарушить этот механизм. В таком случае модель может установить этот флаг, чтобы пользователь по ошибке не попытался самостоятельно запускать блок. По умолчанию флаг сброшен.
RDS_BLOCKHASEXAMPLE	У блока есть пункт «пример схемы» в контекстном меню. По умолчанию флаг сброшен, модель может взвести его, если для блока предусмотрена справка и она будет реагировать на событие RDS_BFM_SHOWEXAMPLE, загружая схему с примером использования этого блока.
RDS_NOFPEXCEPTIONS	На время вызова модели блока отключить обработку математических ошибок. По умолчанию флаг сброшен.
RDS_SETUPNONCHANGING	Вызов настройки блока не изменяет его параметров. Если этот флаг взведен, в контекстном меню блока будет присутствовать пункт для вызова настройки, даже если редактирование схемы запрещено. По умолчанию флаг сброшен, модель может установить его, если окно настройки на самом деле ничего не настраивает, а просто показывает какую-либо информацию.
RDS_BLOCKDRAWOVER	При перетаскивании и масштабировании блока модель рисует его изображение с функцией исключающего ИЛИ (т.е. таким образом, что два последовательных вызова рисования по одним и тем же координатам восстанавливают исходное изображение). По умолчанию флаг сброшен, модель может взвести его, если она будет реагировать на событие RDS_BFM_DRAWOVER.
RDS_IGNOREEXCEPTIONS	Игнорировать любые исключительные ситуации (ошибки, exceptions) при вызове модели блока. По умолчанию флаг сброшен.
RDS_INITCALC	Блок вызывается для «инициализационного» расчета при первом после загрузки схемы или сброса расчета выходе из режима редактирования, если на его входы пришли данные от других блоков. По умолчанию флаг сброшен.
RDS_INITCALCFIRST	Блок вызывается для «инициализационного» расчета при первом после загрузки схемы или сброса расчета выходе из режима редактирования, независимо от того, пришли ли на его входы какие-либо данные. Блоки, модели которых взвели эти флаги, вызываются при «инициализационном» расчете самыми первыми и обычно являются начальными блоками каких-либо цепочек вычисления. Если этот флаг взведен, взводить RDS_INITCALC не обязательно. По умолчанию флаг сброшен.
RDS_CONNCHANGECTRL	Модель блока самостоятельно решает, какие входы влияют на какие выходы при наблюдении за срабатыванием связей. Этот флаг используется моделями только при ожидании окончания промежуточных изменений в передаваемых по связям данных. По умолчанию флаг сброшен.
RDS_DYNVARBYINPUT	Блок изменяет динамические переменные, на которые он подписан, при изменении своих входов. Этот флаг используется только при ожидании окончания промежуточных изменений в связях. По умолчанию флаг сброшен.
RDS_MULTICALC	Блок может перезапускать сам себя для продолжения начатых в такте вычислений. Этот флаг используется только при ожидании окончания промежуточных изменений в связях. По умолчанию флаг сброшен.
RDS_MULTICALCON	В данный момент блок перезапускает сам себя для продолжения начатых в такте вычислений. Этот флаг используется только при ожидании окончания промежуточных изменений в связях. Флаг автоматически сбрасывается перед вызовом модели в такте расчета.
RDS_FASTUNDO	При отмене операции редактирования не обязательно отключать модель от блока и подключать ее снова, если эта операция не меняет модель блока. Этот флаг имеет смысл использовать в сложных блоках, подключение/отключение моделей которых может занимать большое время. По умолчанию флаг сброшен.

Width, Height (RDSINT32)

Ширина (Width) и высота (Height) описывающего прямоугольника блока в точках экрана в масштабе 100% без учета возможной связи с переменными, то есть размер блока, заданный пользователем в режиме редактирования. Эти поля можно использовать только в том случае, если модель блока рисует его внешний вид программно. Если изображение блока задано прямоугольником с текстом или векторной картинкой, эти поля не используются.

Tag (RDSINT32)

Целое значение, никак не обрабатываемое RDS. Разработчик модели может использовать его по своему усмотрению – например, для хранения каких-либо флагов. RDS не инициализирует это поле при подключении к блоку новой модели, поэтому функция модели должна заниматься этим самостоятельно.