На предыдущих уроках цикла мы подробно рассмотрели различные средства работы с текстом. КОМПАС позволяет создавать текстовые документы. Они отличаются от файлов, создаваемых стандартным блокнотом Windows наличием оформления в виде основной надписи различных видов.
На этом уроке мы рассмотрим, как открывать существующий, создавать новый, закрывать и сохранять в различные форматы текстовый документ. К сожалению, API интерфейсов версии 5 не позволяет работать с содержимым текстовых документов, только с содержимым их основной надписи. Поэтому рассмотрение текстовых документов ограничится только этим уроком. А на следующем мы вновь вернемся к графическим документам.
Текстовый документ описывается интерфейсом ksDocumentTxt. Он может быть получен двумя способами: с помощью метода DocumentTxt() интерфейса KompasObject и с помощью метода ActiveDocumentTxt() того же интерфейса. Оба этих метода не имеют входных параметров и в случае успеха возвращают интерфейс ksDocumentTxt, а в случае ошибки – значение NULL.
Единственное различие между ними состоит в том, что метод ActiveDocumentTxt() возвращает интерфейс текущего активного текстового документа, а метод DocumentTxt() интерфейс, еще не привязанный к какому-либо документу. Получив интерфейс, вы можете открыть существующий документ или создать новый.
Для открытия существующего текстового документа используется метод ksOpenDocument интерфейса ksDocumentTxt. Ниже приводится его прототип
Параметр regim задает режим редактирования документа. Его допустимые значения приведены ниже:
0 – видимый режим (документ отображается на экране);
1 – невидимый режим (документ не отображается на экране).
Невидимый режим используется тогда, когда вы хотите изменить документ так, чтобы пользователь не видел ваших действий.
В случае успеха метод ksOpenDocument возвращает true, а в случае ошибки – false.
Примечание: учтите, что если открываемый вами документ уже открыт в КОМПАС, то метод ksOpenDocument вернет true. При этом вы будете работать с ранее открытым документом.
Ниже приводится пример программы, демонстрирующей открытие существующего текстового документа.
В данном примере открывается документ «TextDocument.kdw», находящийся в каталоге приложения.
Параметры текстового документа (ksTextDocumentParam).
Параметры текстового документа описываются интерфейсом ksTextDocumentParam.
Получить его можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextDocumentParam. Рассмотрим свойства этого интерфейса:
author – строка с именем автора документа;
comment – строка, содержащая комментарий к документу;
fileName – полный путь к файлу с растровым изображением;
regime – режим редактирования документа. Допустимые значения перечислены ниже:
0 – видимый режим (документ отображается на экране и виден пользователю);
1 – «слепой» режим (документ не виден пользователю). Данный режим обычно используется при скрытой работе с несколькими документами.
type – целочисленный тип документа. Его допустимые значения приведены в таблице ниже.
Теперь рассмотрим методы интерфейса ksTextDocumentParam.
Init() – инициализирует свойства интерфейса. Не имеет входных параметров. В случае успеха возвращает true, а в случае ошибки – false.
GetSheetParam() – возвращает интерфейс параметров листа. Не имеет входных параметров. Если текстовый документ имеет листы стандартного размера (type == lt_DocTxtStandart), то метод возвращает интерфейс ksStandartSheet. Если же документ имеет листы нестандартного размера (type == ls_DocTxtUser), то возвращается интерфейс ksSheetSize. Оба этих интерфейса рассматривались на 2 уроке цикла.
Остальные методы интерфейса ksTextDocumentParam связаны с оформлением документа. Так как они не позволяют изменять оформление документа (только читать его), рассматривать их мы не будем.
Для создания нового текстового документа используется метод ksCreateDocument интерфейса ksDocumentTxt. Ниже приводится его прототип.
Единственным параметром данного метода является интерфейс ksTextDocumentParam, задающий параметры создаваемого документа. В случае успеха метод возвращает значение true, а в случае ошибки – false.
Ниже приводится исходный текст программы, демонстрирующей создание нового текстового документа.
В результате работы данной программы в КОМПАС будет создан новый текстовый документ. Может показаться, что КОМПАС не создал для него никакого оформления, но это не так. Стоит нажать на кнопку «Отображать оформление» на панели инструментов КОМПАС, как появится основная надпись. На рисунке ниже показан фрагмент окна КОМПАС с кнопкой «Отображать оформление» и созданным текстовым документом.
Метод ksGetDocumentPagesCount() интерфейса ksDocumentTxt возвращает количество листов в документе. Он не имеет входных параметров. Если с интерфейсом ksDocumentTxt не связан никакой документ (открытый или созданный), то метод возвращает значение ноль.
Метод GetStamp() интерфейса ksDocumentTxt возвращает интерфейс ksStamp, описывающий основную надпись (рассматривался на 4 и 8 уроках). Метод не имеет входных параметров. Полученный интерфейс ksStamp описывает основную надпись первого листа документа.
Метод GetStampEx позволяет получить основную надпись любого листа документа. В качестве единственного параметра он принимает номер листа, интерфейс основной надписи (ksStamp) которого мы хотим получить. Нумерация листов ведется с 1 (с единицы).
Для закрытия текстового документа используется метод ksCloseDocument() интерфейса ksDocumentTxt. Он не имеет входных параметров и, в случае успеха, возвращает значение true, а в случае ошибки – false. Учтите, метод ksCloseDocument() не сохраняет документ.
Для сохранения документа в интерфейсе ksDocumentTxt предусмотрено несколько методов.
Метод ksSaveDocument сохраняет документ по заданному пути. В качестве единственного параметра он принимает строку, содержащую полный путь к файлу, в который нужно сохранить документ. В случае успеха он возвращает значение true, а в случае ошибки – false. Файл сохраняется в версии используемого КОМПАС.
Метод ksSaveDocumentEx позволяет выбрать, в какой версии сохранять документ. Ниже приводится прототип этого метода.
В отличие от метода ksSaveDocument здесь добавился параметр saveMode. Его допустимые значения приведены в таблице ниже.
В случае успеха метод ksSaveDocumentEx возвращает значение true, а в случае ошибки – false.
Метод SaveAsToRasterFormat сохраняет документ в растровый формат. Ниже приводится его прототип:
Параметры сохранения в растровый формат задаются с помощью интерфейса ksRasterFormatParam (рассматривался на 6 уроке цикла). В случае успеха метод SaveAsToRasterFormat возвращает значение true, а в случае ошибки – false.
Для получения интерфейса ksRasterFormatParam нужно использовать метод RasterFormatParam() интерфейса ksDocumentTxt. Данный метод не имеет входных параметров и возвращает интерфейс параметров сохранения в растровом формате. В случае ошибки он возвращает NULL.
Метод SaveAsToUncompressedRasterFormat сохраняет документ в растровый формат без сжатия. Он имеет такой же прототип, что и метод SaveAsToRasterFormat. В случае успеха метод SaveAsToUncompressedRasterFormat возвращает значение true, а в случае ошибки – false.
К сожалению, API интерфейсов версии 5, рассматриваемый в нашем цикле статей, не содержит средств для наполнения текстового документа. Для этого нужно использовать API интерфейсов версии 7.
Заключение
На данном уроке мы познакомились с текстовыми документами. API интерфейсов версии 5 позволяет открывать, создавать и сохранять текстовые документы, но не редактировать их содержимое. В последующих уроках цикла мы больше не будем возвращаться к текстовым документам.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».
На этом уроке мы рассмотрим, как открывать существующий, создавать новый, закрывать и сохранять в различные форматы текстовый документ. К сожалению, API интерфейсов версии 5 не позволяет работать с содержимым текстовых документов, только с содержимым их основной надписи. Поэтому рассмотрение текстовых документов ограничится только этим уроком. А на следующем мы вновь вернемся к графическим документам.
Содержание цикла уроков «Работа с API КОМПАС-3D»
- Основы
- Оформление чертежа
- Корректное подключение к КОМПАС
- Основная надпись
- Графические примитивы
- Сохранение документа в различные форматы
- Знакомство с настройками
- Более сложные методы записи в основную надпись
- Чтение ячеек основной надписи
- Спецсимволы, включающие строку
- Простые текстовые надписи
- Составные строки
- Параграфы
- Многострочный текст
- Составные строки на основе параграфа
- Управляющие символы
- Текстовый документ
Получение интерфейса ksDocumentTxt
Текстовый документ описывается интерфейсом ksDocumentTxt. Он может быть получен двумя способами: с помощью метода DocumentTxt() интерфейса KompasObject и с помощью метода ActiveDocumentTxt() того же интерфейса. Оба этих метода не имеют входных параметров и в случае успеха возвращают интерфейс ksDocumentTxt, а в случае ошибки – значение NULL.
Единственное различие между ними состоит в том, что метод ActiveDocumentTxt() возвращает интерфейс текущего активного текстового документа, а метод DocumentTxt() интерфейс, еще не привязанный к какому-либо документу. Получив интерфейс, вы можете открыть существующий документ или создать новый.
Открытие существующего документа
Для открытия существующего текстового документа используется метод ksOpenDocument интерфейса ksDocumentTxt. Ниже приводится его прототип
BOOL ksOpenDocument (
BSTR nameDoc, //Полный путь к открываемому документу
BOOL regim //Режим
);
Параметр regim задает режим редактирования документа. Его допустимые значения приведены ниже:
0 – видимый режим (документ отображается на экране);
1 – невидимый режим (документ не отображается на экране).
Невидимый режим используется тогда, когда вы хотите изменить документ так, чтобы пользователь не видел ваших действий.
В случае успеха метод ksOpenDocument возвращает true, а в случае ошибки – false.
Примечание: учтите, что если открываемый вами документ уже открыт в КОМПАС, то метод ksOpenDocument вернет true. При этом вы будете работать с ранее открытым документом.
Ниже приводится пример программы, демонстрирующей открытие существующего текстового документа.
//Формируем полный путь к открываемому документу
WideString wideStr = WideString(ExtractFileDir(Application->ExeName));
wideStr += L"\\TextDocument.kdw";
BSTR filePath = SysAllocString(wideStr.c_bstr());
//Открываем документ
DocumentTxtPtr documentTxt;
documentTxt = static_cast<DocumentTxtPtr>(kompas->DocumentTxt());
documentTxt->ksOpenDocument(filePath, 0);
//Освобождаем ресурсы
documentTxt.Unbind();
В данном примере открывается документ «TextDocument.kdw», находящийся в каталоге приложения.
Параметры текстового документа (ksTextDocumentParam).
Параметры текстового документа описываются интерфейсом ksTextDocumentParam.
Получить его можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextDocumentParam. Рассмотрим свойства этого интерфейса:
author – строка с именем автора документа;
comment – строка, содержащая комментарий к документу;
fileName – полный путь к файлу с растровым изображением;
regime – режим редактирования документа. Допустимые значения перечислены ниже:
0 – видимый режим (документ отображается на экране и виден пользователю);
1 – «слепой» режим (документ не виден пользователю). Данный режим обычно используется при скрытой работе с несколькими документами.
type – целочисленный тип документа. Его допустимые значения приведены в таблице ниже.
Теперь рассмотрим методы интерфейса ksTextDocumentParam.
Init() – инициализирует свойства интерфейса. Не имеет входных параметров. В случае успеха возвращает true, а в случае ошибки – false.
GetSheetParam() – возвращает интерфейс параметров листа. Не имеет входных параметров. Если текстовый документ имеет листы стандартного размера (type == lt_DocTxtStandart), то метод возвращает интерфейс ksStandartSheet. Если же документ имеет листы нестандартного размера (type == ls_DocTxtUser), то возвращается интерфейс ksSheetSize. Оба этих интерфейса рассматривались на 2 уроке цикла.
Остальные методы интерфейса ksTextDocumentParam связаны с оформлением документа. Так как они не позволяют изменять оформление документа (только читать его), рассматривать их мы не будем.
Создание документа
Для создания нового текстового документа используется метод ksCreateDocument интерфейса ksDocumentTxt. Ниже приводится его прототип.
BOOL ksCreateDocument (
LPDISPATCH par
);
Единственным параметром данного метода является интерфейс ksTextDocumentParam, задающий параметры создаваемого документа. В случае успеха метод возвращает значение true, а в случае ошибки – false.
Ниже приводится исходный текст программы, демонстрирующей создание нового текстового документа.
//Подготавливаем параметры документа
TextDocumentParamPtr textDocumentParam;
textDocumentParam=static_cast<TextDocumentParamPtr>(kompas->GetParamStruct(ko_TextDocumentParam));
textDocumentParam->Init();
textDocumentParam->set_type(lt_DocTxtStandart);
//Подготавливаем параметры листа
StandartSheetPtr standartSheet;
standartSheet = static_cast<StandartSheetPtr>(textDocumentParam->GetSheetParam());
standartSheet->set_format(ksFormatA4);
//Создаем документ
DocumentTxtPtr documentTxt;
documentTxt = static_cast<DocumentTxtPtr>(kompas->DocumentTxt());
documentTxt->ksCreateDocument(textDocumentParam);
//Освобождаем ресурсы
standartSheet.Unbind();
textDocumentParam.Unbind();
documentTxt.Unbind();
В результате работы данной программы в КОМПАС будет создан новый текстовый документ. Может показаться, что КОМПАС не создал для него никакого оформления, но это не так. Стоит нажать на кнопку «Отображать оформление» на панели инструментов КОМПАС, как появится основная надпись. На рисунке ниже показан фрагмент окна КОМПАС с кнопкой «Отображать оформление» и созданным текстовым документом.
Количество листов и основная надпись
Метод ksGetDocumentPagesCount() интерфейса ksDocumentTxt возвращает количество листов в документе. Он не имеет входных параметров. Если с интерфейсом ksDocumentTxt не связан никакой документ (открытый или созданный), то метод возвращает значение ноль.
Метод GetStamp() интерфейса ksDocumentTxt возвращает интерфейс ksStamp, описывающий основную надпись (рассматривался на 4 и 8 уроках). Метод не имеет входных параметров. Полученный интерфейс ksStamp описывает основную надпись первого листа документа.
Метод GetStampEx позволяет получить основную надпись любого листа документа. В качестве единственного параметра он принимает номер листа, интерфейс основной надписи (ksStamp) которого мы хотим получить. Нумерация листов ведется с 1 (с единицы).
Закрытие документа
Для закрытия текстового документа используется метод ksCloseDocument() интерфейса ksDocumentTxt. Он не имеет входных параметров и, в случае успеха, возвращает значение true, а в случае ошибки – false. Учтите, метод ksCloseDocument() не сохраняет документ.
Сохранение документа
Для сохранения документа в интерфейсе ksDocumentTxt предусмотрено несколько методов.
Метод ksSaveDocument сохраняет документ по заданному пути. В качестве единственного параметра он принимает строку, содержащую полный путь к файлу, в который нужно сохранить документ. В случае успеха он возвращает значение true, а в случае ошибки – false. Файл сохраняется в версии используемого КОМПАС.
Метод ksSaveDocumentEx позволяет выбрать, в какой версии сохранять документ. Ниже приводится прототип этого метода.
BOOL ksSaveDocumentEx (
BSTR fileName, //Полный путь к файлу
long saveMode //Версия для сохранения
);
В отличие от метода ksSaveDocument здесь добавился параметр saveMode. Его допустимые значения приведены в таблице ниже.
В случае успеха метод ksSaveDocumentEx возвращает значение true, а в случае ошибки – false.
Метод SaveAsToRasterFormat сохраняет документ в растровый формат. Ниже приводится его прототип:
BOOL SaveAsToRasterFormat (
BSTR fileName, //Полный путь к файлу
LPDISPATCH rasterPar //Параметры сохранения в растровый формат
);
Параметры сохранения в растровый формат задаются с помощью интерфейса ksRasterFormatParam (рассматривался на 6 уроке цикла). В случае успеха метод SaveAsToRasterFormat возвращает значение true, а в случае ошибки – false.
Для получения интерфейса ksRasterFormatParam нужно использовать метод RasterFormatParam() интерфейса ksDocumentTxt. Данный метод не имеет входных параметров и возвращает интерфейс параметров сохранения в растровом формате. В случае ошибки он возвращает NULL.
Метод SaveAsToUncompressedRasterFormat сохраняет документ в растровый формат без сжатия. Он имеет такой же прототип, что и метод SaveAsToRasterFormat. В случае успеха метод SaveAsToUncompressedRasterFormat возвращает значение true, а в случае ошибки – false.
Наполнение документа
К сожалению, API интерфейсов версии 5, рассматриваемый в нашем цикле статей, не содержит средств для наполнения текстового документа. Для этого нужно использовать API интерфейсов версии 7.
Заключение
На данном уроке мы познакомились с текстовыми документами. API интерфейсов версии 5 позволяет открывать, создавать и сохранять текстовые документы, но не редактировать их содержимое. В последующих уроках цикла мы больше не будем возвращаться к текстовым документам.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».