Описание интерфейса поставщиков данных табличного поля

Описание интерфейса поставщиков данных табличного поля

Настоящее описание является основной документацией для разработки поставщиков данных. Поставщики данных - это объекты, работающие под управлением элемента управления (ЭУ) - объекта ТабличноеПоле.

Поставщик данных должен реализовать интерфейсы двух абстрактных классов:

  • CDataProvider;
  • CV7DataProvider.

Через эти интерфейсы поставщик должен передавать объекты строк данных. Эти объекты должны реализовать интерфейсы двух абстрактных классов:

  • CDataRow;
  • CV7DataRow.

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

Классы CDataProvider и CDataRow описаны в заголовочном файле DataProvider.h. Они являются общими и могут применяться вне среды 1C (V7).

Классы CV7DataProvider и CV7DataRow описаны в заголовочном файле V7DataProvider.h. Они являются расширением интерфейса поставщиков данных для более эффективной и гибкой работы в среде 1C (V7).

  • CDataProvider
  • CDataRow
  • CV7DataProvider
  • CV7DataRow


CDataProvider

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: Описание интерфейса поставщиков данных табличного поля | Далее: GetControl
CDataProvider

Базовый класс для всех поставщиков данных. Содержит интерфейсы, через которые ЭУ управляет поставщиком данных. Каждый поставщик данных должен реализовать Интерфейс запроса и получения строк.

Интерфейс общего назначения

Собраны функции общего назначения.

GetControl | позволяет получить дескриптор ЭУ, подключенного в данный момент к поставщику данных.
SetControl | позволяет установить дескриптор ЭУ, подключая таким образом поставщика данных к ЭУ. Эту процедуру вызывает сам ЭУ.
ResetData | позволяет инициализировать заполнение ЭУ. Имеет эффект только в том случае, когда поставщик данных подключен к ЭУ.
SetCurrentRow | позволяет сделать текущей переданную строку. Имеет эффект только в том случае, когда поставщик данных подключен к ЭУ.
OnDetach | вызвается после отключения поставщика данных от ЭУ.
OnAttach | вызвается после подключения поставщика данных к ЭУ.

Интерфейс запроса и получения строк

Основной интерфейс поставщика данных.

Реализация обязательна.

QueryRows | запрашивает строки у поставщика данных. После вызова метода всегда будет один или несколько вызов Fetch для собственно получения строк элементом управления.
Fetch | возвращает запрошенные методом QueryRows строки данных. Если возвращается NULL - это означает, что все строки последнего запроса были выбраны. Поставщик данных должен вернуть столько строк, сколько запрошено в параметре nRowsCount в предыдущем вызове метода QueryRows, иначе ЭУ считает, что в данном направлении достигнут конец выборки строк, и последующие запросы в этом направлении выполнять не будет.
RefreshRow | поставщик данных должен обновить данные строки.
CompareRows | поставщик данных должен сравнить объекты строк. Дело в том, что при работе ЭУ может сохранять объекты строк, но в некоторых ситуациях он может запросить те же строки заново. Для того, чтобы ЭУ знал, что новый полученный объект представляет ту же строку - необходим этот метод.
GetLastError | метод нужен для диагностики неправильной работы поставщика данных. Если метод возвращает не NULL, то ЭУ будет визуально сообщать об ошибке текстом полученным при вызове этого метода.
GetRowCount | этим методом запрашивается общее количество строк в наборе данных и размер набора данных. Если метод возвращает TRUE - значит, поставщик поддерживает определение относительного положения записи во всем наборе данных, и по указателю pCount записано общее количество строк в наборе, иначе поставщик не поддерживает определение относительное положения записи в наборе данных. См. также GetRowIndex.

Интерфейс управления составом полей

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

Реализация не обязательна.

QueryField | метод вызывается, когда элементу управления требуется отображать содержимое поля с именем szFieldName.
ReleaseField | метод вызывается, когда элементу управления больше не требуется отображать содержимое поля с именем szFieldName.
OnFieldsChanged | этот метод должен вызываться поставщиком данных внутренне при изменении состава полей данных. Стандартные действия этого метода - команда элементу управления о том, что состав полей изменился.

Интерфейс быстрого поиска

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

Реализация не обязательна.

GetQuickSearchType | метод вызывается, когда элементу управления требуется определить - поддерживается ли поставщиком данных быстрый поиск по полю szFieldName. Если возвращается dtUndefined - по этому полю быстрый поиск не поддерживается, иначе возвращяемое значение определяет тип данных для ввода образца для поиска по полю szFieldName.
QuickSearch | поставщик данных должен выполнить быстрый поиск по переданному образцу. Результатом поиска должна быть активизация строки (SetCurrentRow). А также возможно изменение данных структуры stQuickSearchPattern.

Структуры даных

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

Перечисления

DataType используется для обозначения типа данных поля поставщика данных:


CDataProvider::GetControl

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: CDataProvider | Далее: SetControl
CDataProvider :: GetControl

Синтаксис: HWND GetControl() const;

Возвращает: дескриптор ЭУ, если NULL - поставщик не подключен к ЭУ.

Описание: позволяет получить дескриптор ЭУ, подключенного в данный момент к поставщику данных.


CDataProvider::SetControl

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetControl | Далее: ResetData
CDataProvider :: SetControl

Синтаксис: void SetControl(HWND hControl);

Описание: позволяет установить дескриптор ЭУ, подключая таким образом поставщика данных к ЭУ. Эту процедуру вызывает сам ЭУ.


CDataProvider::ResetData

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: SetControl | Далее: SetCurrentRow
CDataProvider :: ResetData

Синтаксис: void ResetData(CDataRow* pDataRow = NULL);

Параметры:

  • pDataRow - указатель на строку данных, которую требуется сделать текущей при инициализации.

Описание: позволяет инициализировать заполнение ЭУ. Имеет эффект только в том случае, когда поставщик данных подключен к ЭУ.


CDataProvider::SetCurrentRow

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: ResetData | Далее: OnDetach
CDataProvider :: SetCurrentRow

Синтаксис: void SetCurrentRow(CDataRow* pDataRow);

Параметры:

  • pDataRow - указатель на строку данных, которую требуется сделать текущей.

Описание: позволяет сделать текущей переданную строку. Имеет эффект только в том случае, когда поставщик данных подключен к ЭУ.


CDataProvider::OnDetach

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: SetCurrentRow | Далее: OnAttach
CDataProvider :: OnDetach

Синтаксис: virtual void OnDetach();

Описание: вызвается после отключения поставщика данных от ЭУ.


CDataProvider::OnAttach

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: OnDetach | Далее: QueryRows
CDataProvider :: OnAttach

Синтаксис: virtual void OnAttach();

Описание: вызвается после подключения поставщика данных к ЭУ.


CDataProvider::QueryRows

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: OnAttach | Далее: Fetch
CDataProvider :: QueryRows

Синтаксис: virtual void QueryRows(CDataRow* pRowFrom, int nRowsCount, int nPageSizeHint) = 0;

Параметры:

  • pRowFrom - строка данных, от которой необходимо получить строки. Может быть равен NULL, это означает, что строки запрашиваются с крайнего положения: с начала или с конца (см. параметр nRowsCount);
  • nRowsCount - запрашиваемое количество строк. Знак указывает направление. Если параметр больше нуля - запрашиваются следующие строки (вниз). Если параметр меньше нуля - запрашиваются предыдущие строки (вверх);
  • nPageSizeHint - размер страницы. Всегда положительное число, которое передается элементом управления для подсказки поставщику, чтобы тот мог оптимизировать свое поведение.

Описание: запрашивает строки у поставщика данных. После вызова метода всегда будет один или несколько вызов Fetch для собственно получения строк элементом управления.


CDataProvider::Fetch

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: QueryRows | Далее: RefreshRow
CDataProvider :: Fetch

Синтаксис: virtual CDataRow* Fetch() = 0;

Возвращает: указатель на строку данных.

Описание: возвращает запрошенные методом QueryRows строки данных. Если возвращается NULL - это означает, что все строки последнего запроса были выбраны. Поставщик данных должен вернуть столько строк, сколько запрошено в параметре nRowsCount в предыдущем вызове метода QueryRows, иначе ЭУ считает, что в данном направлении достигнут конец выборки строк, и последующие запросы в этом направлении выполнять не будет.

Замечание: поставщик данных не должен следить за освобождением памяти объекта строки данных. После того, как строка передана поставщику данных ЭУ, освобождение этого объекта - ответственность ЭУ.


CDataProvider::RefreshRow

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: Fetch | Далее: CompareRows
CDataProvider :: RefreshRow

Синтаксис: virtual BOOL RefreshRow(CDataRow* pRowFrom) = 0;

Параметры:

  • pRowFrom - указатель на строку данных, данные которой необходимо обновить.

Возвращает: результат успешности обновления данных строки.

Описание: поставщик данных должен обновить данные строки.


CDataProvider::CompareRows

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: RefreshRow | Далее: GetLastError
CDataProvider :: CompareRows

Синтаксис: virtual BOOL CompareRows(CDataRow* pRow1, CDataRow* pRow2) const = 0;

Параметры:

  • pRow1 - указатель на одну строку данных;
  • pRow2 - указатель на другую строку данных.

Возвращает: TRUE, если эти два объекта представляют одну и ту же строку, иначе FALSE.

Описание: поставщик данных должен сравнить объекты строк. Дело в том, что при работе ЭУ может сохранять объекты строк, но в некоторых ситуациях он может запросить те же строки заново. Для того, чтобы ЭУ знал, что новый полученный объект представляет ту же строку - необходим этот метод.


CDataProvider::GetLastError

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: CompareRows | Далее: GetRowCount
CDataProvider :: GetLastError

Синтаксис: virtual LPCSTR GetLastError();

Возвращает: указатель на строку - описание ошибки в работе поставщика данных.

Описание: метод нужен для диагностики неправильной работы поставщика данных. Если метод возвращает не NULL, то ЭУ будет визуально сообщать об ошибке текстом полученным при вызове этого метода.


CDataProvider::GetRowCount

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetLastError | Далее: QueryField
CDataProvider :: GetRowCount

Синтаксис: virtual BOOL GetRowCount(UINT* pCount);

Параметры:

  • pCount - указатель на переменную, принимающую количество строк в наборе данных.

Возвращает: поддерживает ли поставщик данных определение относительного положения записи.

Описание: этим методом запрашивается общее количество строк в наборе данных и размер набора данных. Если метод возвращает TRUE - значит, поставщик поддерживает определение относительного положения записи во всем наборе данных, и по указателю pCount записано общее количество строк в наборе, иначе поставщик не поддерживает определение относительное положения записи в наборе данных. См. также GetRowIndex.


CDataProvider::QueryField

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetRowCount | Далее: ReleaseField
CDataProvider :: QueryField

Синтаксис: virtual void QueryField(LPCSTR szFieldName);

Параметры:

  • szFieldName - имя поля данных.

Описание: метод вызывается, когда элементу управления требуется отображать содержимое поля с именем szFieldName.


CDataProvider::ReleaseField

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: QueryField | Далее: OnFieldsChanged
CDataProvider :: ReleaseField

Синтаксис: virtual void ReleaseField(LPCSTR szFieldName);

Параметры:

  • szFieldName - имя поля данных.

Описание: метод вызывается, когда элементу управления больше не требуется отображать содержимое поля с именем szFieldName.


CDataProvider::OnFieldsChanged

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: ReleaseField | Далее: GetQuickSearchType
CDataProvider :: OnFieldsChanged

Синтаксис: virtual void OnFieldsChanged();

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


CDataProvider::GetQuickSearchType

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: OnFieldsChanged | Далее: QuickSearch
CDataProvider :: GetQuickSearchType

Синтаксис: virtual DataType GetQuickSearchType(LPCSTR szFieldName);

Параметры:

  • szFieldName - имя поля данных.

Возвращает: тип данных для ввода образца для поиска по полю szFieldName.

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

Замечание: в настоящий момент поддерживается только dtText.


CDataProvider::QuickSearch

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetQuickSearchType | Далее: stQuickSearchPattern
CDataProvider :: QuickSearch

Синтаксис: virtual void QuickSearch(stQuickSearchPattern& QSPattern);

Параметры:

  • QSPattern - ссылка на структуру stQuickSearchPattern - с данными образца для поиска.

Описание: поставщик данных должен выполнить быстрый поиск по переданному образцу. Результатом поиска должна быть активизация строки (SetCurrentRow). А также возможно изменение данных структуры stQuickSearchPattern.


CDataProvider::stQuickSearchPattern

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: QuickSearch | Далее: DataType
CDataProvider :: stQuickSearchPattern

Синтаксис:

struct stQuickSearchPattern
{
        LPCSTR szFieldName;
        DataType dataType;
        union
        {
                CString* pTextData; //for text fields;
        };
};
szFieldName: Имя поля данных, по которому требуется выполнить поиск.
dataType: Тип данных образца для поиска.
pTextData: Образец для поиска типа dtText. После поиска поставщик должен изменить эту строку в зависимости от результатов поиска: в ней должно остаться столько символов слева, сколько удовлетворяет значению поля в найденной строке.

Описание: используется для передачи образца данных для выполнения быстрого поиска поставщиком данных.


CDataProvider::DataType

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: stQuickSearchPattern | Далее: CDataRow
CDataProvider :: DataType

Синтаксис:

enum DataType
{
        dtUndefined,
        dtText,
        dtNumeric,
        dtDate,
        dtFalse,
        dtTrue,
};

Описание: используется для обозначения типа данных поля поставщика данных:

  • dtUndefined: тип не определен;
  • dtText: строка (текст);
  • dtNumeric: число;
  • dtDate: дата;
  • dtFalse: булево значение Ложь;
  • dtTrue: булево значение Истина.


CDataRow

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: DataType | Далее: GetFieldCount
CDataRow

Базовый класс для класса строки данных (записи).

Интерфейс строки данных

GetFieldCount | позволяет определить количество полей.
GetFieldIndexOf | позволяет определить индекс поля по имени. Если поля с таким именем нет, должно возвращаться значение -1.
GetFieldName | позволяет определить имя поля по индексу.
GetFieldType | позволяет определить тип поля данных. Используется элементом управления, для общепринятого отображения различных типов данных.
FormatField | форматирует значение поля данных. strValue - строка, в которой должно произойти форматирование.
GetRowIndex | позволяет получить индекс строки (записи) для определения относительного положения строки в наборе данных. Метод вызывается только в том случае, если поставщик поддерживает этот функционал. См. также GetRowCount.


CDataRow::GetFieldCount

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: CDataRow | Далее: GetFieldIndexOf
CDataRow :: GetFieldCount

Синтаксис: virtual int GetFieldCount() = 0;

Возвращает: количество полей.

Описание: позволяет определить количество полей.


CDataRow::GetFieldIndexOf

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetFieldCount | Далее: GetFieldName
CDataRow :: GetFieldIndexOf

Синтаксис: virtual int GetFieldIndexOf(LPCSTR szFieldName) = 0;

Параметры:

  • szFieldName - имя поля данных.

Возвращает: индекс поля данных.

Описание: позволяет определить индекс поля по имени. Если поля с таким именем нет, должно возвращаться значение -1.


CDataRow::GetFieldName

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetFieldIndexOf | Далее: GetFieldType
CDataRow :: GetFieldName

Синтаксис: virtual LPCSTR GetFieldName(int nIndex) = 0;

Параметры:

  • nIndex - индекс поля данных.

Возвращает: указатель на строку с именем поля данных.

Описание: позволяет определить имя поля по индексу.


CDataRow::GetFieldType

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetFieldName | Далее: FormatField
CDataRow :: GetFieldType

Синтаксис: virtual DataType GetFieldType(int nIndex);

Параметры:

  • nIndex - индекс поля данных.

Возвращает: тип поля данных.

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


CDataRow::FormatField

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetFieldType | Далее: GetRowIndex
CDataRow :: FormatField

Синтаксис: virtual void FormatField(int nIndex, CString& strValue) = 0;

Параметры:

  • nIndex - индекс поля данных;
  • strValue - строка для форматирования значения поля данных.

Описание: форматирует значение поля данных. strValue - строка, в которой должно произойти форматирование.


CDataRow::GetRowIndex

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: FormatField | Далее: CV7DataProvider
CDataRow :: GetRowIndex

Синтаксис: virtual UINT GetRowIndex();

Возвращает: индекс строки данных (записи) в наборе данных.

Описание: позволяет получить индекс строки (записи) для определения относительного положения строки в наборе данных. Метод вызывается только в том случае, если поставщик поддерживает этот функционал. См. также GetRowCount.


CV7DataProvider

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetRowIndex | Далее: GetV7DataRow
CV7DataProvider

Базовый класс для поставщика данных. Этот класс является расширением поставщиков данных для среды 1CV7.

Интерфейс

GetV7DataRow | Этот метод является вспомогательным. Служит для преобразования CDataRow* в CV7DataRow*. Дело в том, что сам ЭУ не может выполнить такое преобразование безопасно, или для этого придется применять динамическое преобразование по RTTI - это неоправдано медленно для каждой строки. А поставщик данных может выполнить такое преобразование статически. (фактически нужно выполнить upcast и downcast)
GetRowValue | с помощью этого метода ЭУ получает в параметре value значение, представляющее переданную параметром pDataRow строку данных.
BuildRowByValue | с помощью этого метода ЭУ пытается получить от поставщика данных новый экземпляр строки данных по значению переданному параметром value. Значение параметра должно представлять строку данных. Объект строки данных, указатель на который возвращается, должен быть временным и будет освобожден элементом управления, после использования его для установки текущей строки.


CV7DataProvider::GetV7DataRow

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: CV7DataProvider | Далее: GetRowValue
CV7DataProvider :: GetV7DataRow

Синтаксис: virtual CV7DataRow* GetV7DataRow(CDataRow* pDataRow) const = 0;

Параметры:

  • pDataRow - указатель на строку данных (получен от поставщика данных).

Возвращает: указатель на строку данных типа CV7DataRow.

Описание: Этот метод является вспомогательным. Служит для преобразования CDataRow* в CV7DataRow*. Дело в том, что сам ЭУ не может выполнить такое преобразование безопасно, или для этого придется применять динамическое преобразование по RTTI - это неоправдано медленно для каждой строки. А поставщик данных может выполнить такое преобразование статически. (фактически нужно выполнить upcast и downcast)


CV7DataProvider::GetRowValue

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetV7DataRow | Далее: BuildRowByValue
CV7DataProvider :: GetRowValue

Синтаксис: virtual void GetRowValue(CDataRow* pDataRow, CValue& value) const;

Параметры:

  • pDataRow - указатель на строку данных (получен от поставщика данных).
  • value - [out] объект для приема результата.

Описание: с помощью этого метода ЭУ получает в параметре value значение, представляющее переданную параметром pDataRow строку данных.

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


CV7DataProvider::BuildRowByValue

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetRowValue | Далее: CV7DataRow
CV7DataProvider :: BuildRowByValue

Синтаксис: virtual CDataRow* BuildRowByValue(const CValue& value);

Параметры:

  • value - значение представляющее строку данных.

Возвращает: указатель на строку данных.

Описание: с помощью этого метода ЭУ пытается получить от поставщика данных новый экземпляр строки данных по значению переданному параметром value. Значение параметра должно представлять строку данных. Объект строки данных, указатель на который возвращается, должен быть временным и будет освобожден элементом управления, после использования его для установки текущей строки.

Примечание: метод используется для реализации свойства табличного поля ТекущаяСтрока по записи.


CV7DataRow

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: BuildRowByValue | Далее: GetValue
CV7DataRow

Базовый класс для класса строки данных (записи). Этот класс является расширением класса строки данных для среды 1CV7.

Интерфейс

GetValue | позволяет элементу управления получить значение поля данных.
FormatValue | вспомогательная процедура, которая форматирует значение Value по общепринятым в 1CV7 правилам форматирования значений для отображения в таблицах.


CV7DataRow::GetValue

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: CV7DataRow | Далее: FormatValue
CV7DataRow :: GetValue

Синтаксис: virtual const CValue& GetValue(int nIndex) const = 0;

Параметры:

  • nIndex - индекс поля данных.

Возвращает: ссылку на объект значения поля данных.

Описание: позволяет элементу управления получить значение поля данных.


CV7DataRow::FormatValue

1C++ :: Описание интерфейса поставщиков данных табличного поля | Ранее: GetValue | Далее:
CV7DataRow :: FormatValue

Синтаксис: static void FormatValue(const CValue& Value, CString& strValue);

Параметры:

  • Value - значение для форматирования;
  • strValue - [out] результат форматирования.

Описание: вспомогательная процедура, которая форматирует значение Value по общепринятым в 1CV7 правилам форматирования значений для отображения в таблицах.