Приложения

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

А.5. Сервисные функции и макросы RDS

А.5.30. Вспомогательный объект для вывода индикатора выполнения

Описываются функции и команды вспомогательного объекта RDS, предназначенного для вывода на экран индикатора хода выполнения какой-либо длительной операции (progress bar).

А.5.30.1. rdsPBARCreate – создать объект для вывода индикатора выполнения

Функция rdsPBARCreate создает вспомогательный объект RDS, позволяющий показывать пользователю горизонтальный индикатор (progress bar), обычно символизирующий ход выполнения какой-либо операции.

  RDS_HOBJECT RDSCALL rdsPBARCreateA(
    int Max,         // Максимум значения
    RDSCSTR Caption  // Заголовок индикатора (UTF8)
  );
  RDS_HOBJECT RDSCALL rdsPBARCreateW(
    int Max,         // Максимум значения
    RDSWCSTR Caption // Заголовок индикатора (UTF16)
  );
  // Функция-псевдоним
  RDS_HOBJECT RDSCALL rdsPBARCreate(
    int Max,         // Максимум значения
    RDSXCSTR Caption // Заголовок индикатора (кодировка по умолчанию)
  );

Тип указателя на эту функцию

RDS_HoIS (для UTF8) или RDS_HoIWs (для UTF16)

Параметры

Max (int)

Максимальное значение индикатора (его позиция изменяется от нуля до этого значения).

Caption (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с заголовком индикатора или NULL, если заголовка нет или он будет задан позже.

Возвращаемое значение

Уникальный идентификатор созданного объекта (RDS_HOBJECT).

Примечания

Эта функция создает вспомогательный объект, который будет отображать в отдельном окне горизонтальный, увеличивающийся вправо индикатор. Размеры индикатора и его окна фиксированы и определяются RDS. Значение позиции индикатора может изменяться от нуля до параметра Max, при этом нулевому значению соответствует пустой (не заполненный) индикатор, а значению Max – индикатор, заполненный из конца в конец. Обычно в параметре Max передают число элементарных шагов какой-либо длительной операции, а в его позиции в процессе выполнения этой операции отражают число уже выполненных шагов. Если одновременно показывается несколько индикаторов, их окна автоматически выстраиваются друг рядом с другом.

Сразу после создания объекта индикатор не отображается, его нужно вывести на экран командой RDS_PBAR_SHOW. Скрыть индикатор с экрана, не уничтожая объект, можно командой RDS_PBAR_HIDE. Созданный вспомогательный объект будет существовать до тех пор, пока схема не будет выгружена из памяти, или пока он не будет удален вызовом функции rdsDeleteObject (при удалении объекта индикатор автоматически исчезнет с экрана).

Чаще всего работа с объектом для отображения индикатора выполнения строится по следующему сценарию:

• перед выполнением длительной операции объект создается вызовом rdsPBARCreate, в этот момент задается максимум и заголовок индикатора;
• индикатор выводится на экран командой RDS_PBAR_SHOW;
• в процессе выполнения операции командами RDS_PBAR_POSITION или RDS_PBAR_ADDTOPOS позиция индикатора изменяется, отображая ход выполнения этой операции (к моменту ее окончания индикатор должен быть полностью заполнен);
• объект удаляется вызовом rdsDeleteObject, при этом индикатор исчезает с экрана.

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

См. также

Вспомогательные объекты, rdsDeleteObject, RDS_PBAR_SHOW, RDS_PBAR_POSITION, RDS_PBAR_ADDTOPOS.