Работа с API КОМПАС-3D → Урок 16 → Управляющие символы
Продолжаем цикл статей по работе с API САПР КОМПАС-3D. Управляющие символы уже несколько раз встречались нам на предыдущих уроках цикла. Тогда каждый раз говорилось, что выводимые строки не должны их содержать, так как КОМПАС обрабатывает их особым образом. Теперь пришло время познакомиться с ними поближе.
Освоив работу с ними, вы поймете, что создание сложных составных строк – тривиальная задача, в большинстве случаев не требующая написания большого объёма кода.
В уроке мы рассмотрим, как с помощью управляющих символов выводить спецсимволы и символы шрифта, поговорим о том, как с их помощью создавать дроби и отклонения, а также рассмотрим их использование совместно с параграфами.
Содержание цикла уроков «Работа с API КОМПАС-3D»
Беглый обзор
, ^ и #. К сожалению в КОМПАС SDK крайне мало информации о том, как их использовать. Более подробная информация приведена в справке КОМПАС, в разделе «9. Настройки КОМПАС-3D/Хранение настроек системы/Служебные файлы/Файл пользовательских меню/Синтаксис файла».
Все управляющие символы условно можно разделить на две группы: основные и вспомогательные. Вспомогательные символы используются только совместно с основными и, сами по себе не описывают какую-либо компоненту. В таблице ниже приводится краткое описание управляющих символов.
Рассмотрим их более подробно.
Вставка специальных символов
Мы уже рассматривали специальные символы (см. уроки 4 и 10). Тогда для вставки одного спецсимвола использовался отдельный экземпляр интерфейса ksTextItemParam. С помощью управляющих символов вы можете вставлять в строку столько спецсимволов, сколько сочтете нужным без многократного использования интерфейса ksTextItemParam.
Синтаксис вставки специальных символов имеет вид:
где
АА – строка, располагаемая до специального символа,
Y – модификатор представления кода спецсимвола,
XXXX – код вставляемого спецсимвола.
BB – строка, располагаемая после спецсимвола.
Код вставляемого спецсимвола указывается между @ и
. При этом в зависимости от значения модификатора Y, он может задаваться в десятичной или шестнадцатеричной системе счисления. Допустимые значения модификатора Y приведены в таблице ниже.
Примечание: как показывают мои эксперименты, КОМПАС нормально обрабатывает отсутствие символа
Ниже приводится пример программы, демонстрирующей вывод спецсимволов.
В данном примере дважды выводится один и тот же символ (α альфа). В первый раз его код задается в десятичной системе счисления, во второй раз – в шестнадцатеричной. На рисунке ниже показан результат работы программы.
Управляющие символы позволяют выводить в одной строке несколько спецсимволов. Так, в следующем примере демонстрируется вывод первых трех букв греческого алфавита за один вызов метода ksText.
На рисунке ниже показан результат работы этой программы.
Модификатор + является модификатором по умолчанию. Поэтому приведенную выше строку можно записать так:
При этом результат работы программы останется прежним.
Если после @ стоит недопустимый символ, то строка между @ и
опускаются. Например, при строке:
В документ будет выведено:
Примечание: такое поведение КОМПАС является недокументированным и может различаться в разных версиях программы.
Примечание: управляющие символы не подходят для вставки спецсимволов, содержащих строку. Дело в том, что для ограничения их действия нужно использовать флаг SPECIAL_SYMBOL_END (более подробно см. 10 урок цикла), но управляющие символы не позволяют использовать флаги.
Вставка символов шрифта
. Их синтаксис приведен ниже
где
AA – строка располагаемая до вставляемого символа,
FNAME – наименование шрифта, из которого берется символ,
Y – модификатор представления кода символа (аналогично @),
XXXX – числовой код вставляемого символа,
BB – строка располагаемая после вставляемого символа.
По своему назначению управляющий символ ^ похож на @. У них даже схожий синтаксис. Но между ними есть два важных отличия:
Если шрифт не указан, то используется шрифт по умолчанию. Ниже приводится пример использования символа ^.
В данном примере в результирующую строку вставляются два символа, для первого мы выбираем шрифт Arial, для второго оставляем шрифт по умолчанию. На рисунке ниже показана строка, которая выводится в документ.
Обратите внимание: шрифт задается только для выводимого символа. Как показывают мои эксперименты, КОМПАС нормально обрабатывает отсутствие завершителя
. Однако я не рекомендую полагаться на такое поведение и всегда ставить завершитель.
Если после ^ указан недопустимый символ (или недопустимый код), то ^ и
опускаются, а строка между ними выводится как есть с использованием шрифта по умолчанию. Например, при строке
В документ будет выведено:
Если в поле FNAME будет указано некорректное имя шрифта, то КОМПАС сам подберет шрифт и выведет символ в нём.
Если в строке нет закрывающей круглой скобки, то такая строка будет выведена не полностью. Например, при строке:
В документ будет выведено только
Примечание: приводимое выше поведение при некорректном синтаксисе управляющих символов справедливо для КОМПАС-3D V17 и не документировано. В других версиях оно может отличаться.
Дополнительные способы вставки символов
У символов @ и ^ есть аналоги – & и # соответственно. Они имеют схожий синтаксис:
AA – строка, выводимая до вставляемого символа,
XX – код вставляемого символа (для & – спецсимвола, для # – символа шрифта),
BB – строка, выводимая после вставляемого символа,
FNAME – наименование шрифта.
Различий между символами @ и ^, и их аналогами всего два:
На рисунке ниже показан результат работы этой программы.
Многострочный текст
. Ниже приводится исходный код программы, демонстрирующей вывод многострочного текста с помощью управляющих символов.
Обратите внимание: благодаря использованию управляющих символов мы выводим двустрочный текст всего одним вызовом метода ksText. На рисунке ниже показан результат работы этой программы.
Вставка управляющих символов
Мы разобрались, как вставлять произвольные спецсимволы и символы Unicode. Но что если требуется вставить сам управляющий символ? Тут можно пойти двумя путями. Первый способ это использовать символ ^ и вставить их как обычные символы шрифта. Но есть и более простой способ.
Символ ; является вспомогательным и может быть вставлен непосредственно в текст. Для вставки других управляющих символов их нужно задвоить. То есть пара символов @@ вставляет в текст один символ @. Это же справедливо и для других управляющих символов.
Ниже приводится пример программы, демонстрирующей вставку управляющих символов в строку.
На рисунке ниже показан результат работы этой программы.
Верхнее и нижнее отклонения
Для вставки отклонений используется следующий синтаксис:
AA – текст выводимый до отклонений;
XX – верхнее отклонение;
YY – нижнее отклонение;
BB – текст выводимый после отклонений.
Обратите внимание: вся конструкция ограничивается символами $, а символ «;» служит разделителем между верхним и нижним отклонениями.
Если между символами $ нет разделителя «;», то вся строка между ними интерпретируется как верхнее отклонение. Если компонента XX отсутствует, то есть после первого $ сразу идет «;», то вся последующая строка до ближайшего $ интерпретируется как нижнее отклонение.
Примечание: текст верхнего отклонения не должен начинаться с букв b, d, s, m и l (строчная L). Причина этого будет объяснена чуть позже.
Ниже приводится пример программы, демонстрирующей вывод текста с отклонениями
На рисунке ниже показан результат работы этой программы:
Учтите, КОМПАС обрабатывает только один символ «;». Второй символ «;» может интерпретироваться как завершитель всей конструкции. Например, при строке «11$22;33;44$» на экран будет выведено:
Примечание: такое поведение КОМПАС не документировано, поэтому полагаться на него нельзя.
Дробь
Синтаксис дроби похож на синтаксис отклонений и имеет два равнозначных варианта:
AA – текст выводимый до дроби;
XX – числитель;
YY – знаменатель;
BB – текст выводимый после дроби.
Обратите внимание: единственное, чем отличается вывод дроби от вывода отклонений это наличие буквы d или b сразу после первого знака $. Во всем остальном их синтаксисы идентичны.
Если между символами $d ($b) и $ нет символа «;», то вся строка между ними будет интерпретироваться как числитель. Если компонента XX отсутствует, то есть после $d ($b) сразу идет «;», то вся последующая строка до ближайшего $ интерпретируется как знаменатель.
Примечание: текст числителя не должен начинаться с букв s, m или l (строчная L). Причина этого будет объяснена чуть позже.
Ниже приводится пример программы, демонстрирующей вывод дроби с использованием управляющих символов.
На рисунке ниже показан результат работы этой программы.
Учтите, КОМПАС обрабатывает «лишние» символы «;» также как и в случае отклонений. Такое поведение является недокументированным, и полагаться на него нельзя.
Управление размером отклонений и дроби
В самом начале конструкции построения отклонений или дроби может находиться одна из букв: s, m или l (строчная L). Они задают размер отклонений и элементов дроби (числителя и знаменателя). Их назначение описывается в таблице ниже.
Если ни одна из этих букв не указана, то для дроби используется l, а для отклонений m. Ниже приводится пример программы, демонстрирующей использование этих букв.
На рисунке ниже показан результат работы этой программы.
Хотя в данном примере буквы s, m и l используются для дроби, их применение для отклонений ничем не отличается.
Учтите, что если между началом дроби или отклонения ($, $d или $b) и буквой s, m или l находится хотя бы один «посторонний» символ (например, пробел), то КОМПАС «не увидит» букв, и дробь или отклонение будут иметь размер по умолчанию.
Вложенные управляющие символы
При выводе дробей и отклонений, входящие в их состав строки обрабатываются рекурсивно. Это значит, что при формировании числителя и знаменателя так же могут использоваться управляющие символы. Этот подход демонстрируется в следующем примере.
На рисунке ниже показан результат работы этой программы.
Для вставки букв греческого алфавита мы используем управляющие символы @ и ^ (для буквы пи). Степень в первом слагаемом выводится с помощью отклонений. Ее выводит подстрока $s2$. Буква s указывает на малый размер отклонения, а благодаря отсутствию разделителя «;» выводится только верхнее отклонение.
Для формирования дроби используется комбинация $d;$. Причем в состав числителя и знаменателя входят управляющие символы, которые обеспечивают вывод букв греческого алфавита.
Последнее вычитаемое (π пи) выводится как символ шрифта Symbol с помощью управляющих символов ^ и
К сожалению возможности такой «рекурсии» сильно ограничены. Мы не можем дробь и отклонения вкладывать друг в друга. Проблема в том, что они оба формируются с помощью управляющего символа $. Из-за этого КОМПАС не может правильно разобрать, какой $ к какому элементу относится.
Управляющие символы в параграфе
Частично обойти ограничение с вложенными управляющими символами можно с помощью параграфов. Совместное использование управляющих символов и параграфов позволяет строить еще более сложные конструкции. Пример ниже демонстрирует построение 4-уровневой дроби.
В данном примере управляющие символы используются для построения дробей в числителе и знаменателе основной дроби, а также для вставки букв греческого алфавита. На рисунке ниже показан результат работы этой программы.
Заключение
На данном уроке мы познакомились с управляющими символами и научились с помощью них выводить спецсимволы и символы шрифта. Как вы могли убедиться, они предоставляют простой синтаксис создания строк, включающих в свой состав спецсимволы, дроби, отклонения. К сожалению, они плохо подходят для вставки спецсимволов, содержащих строки. Но такие спецсимволы встречаются крайне редко. Это одно из ограничений управляющих символов. Также с их помощью нельзя создавать надстроки и подстроки, и есть ограничения при работе со спецсимволами, включающими строки. Но это ничуть не умаляет их достоинств. На этом мы заканчиваем рассмотрение управляющих символов.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».
Работа с текстом в КОМПАСе
Работа с чертежами и фрагментами не обходится без формирования текстовых надписей. Технические требования, названия видов, произвольный текст на чертеже — текстовые блоки бывают разные и нужно уметь их создавать, редактировать, перемещать между чертежами.
Как создать текст в КОМПАСе
Для создания текста в КОМПАСе необходимо воспользоваться командой «Надпись» 
, которая расположена на инструментальной панели Обозначения.
Альтернативный способ вызова команды — воспользоваться главным текстовым меню. Пусть: Оформление — Надпись.
После вызова команды необходимо кликнуть на чертеже в том месте, где должен находиться текст, либо ввести координаты точки начала текста. До указания точки привязки, на Панели параметров можно задать угол текста и определить размещение текста: справа, слева, по центру. Также можно задать зеркальное отражение.
После указания точки вставки текста Панель параметров будет выглядеть следующим образом:
Основные параметры, представленные на Панели параметров:
Например, значок диаметра или процента мы вводим, используя команду «Спецзнак» 
, а дроби или индексы проставляем также соответствующими командами.
Как изменить текст в КОМПАСе
Изменение текста в КОМПАС может быть двух типов:
Если нужно изменить сам текст, то нужно двойным кликом зайти на редактирование текстового блока, курсор окажется внутри блока и можно будет добавлять текст, удалять, вырезать и т.д.
Если нужно изменить стиль текста, то текстовый блок выделяется одним кликом и после этого нужные параметры меняются на Панели параметров
Если необходимо изменить свойства сразу группы текстовых блоков, которые можно выделить по какому-либо свойству, то необходимо запустить команду «Выделить по свойствам» 
, которая расположена в главном текстовом меню в разделе «Выделить»
После чего выделить абсолютно все тексты, поставив галочку в Объекты «Тексты», либо выбрать определенные параметры, по которым нужно искать.
Рамка текста в КОМПАСе
Рамка текста в КОМПАСе не передается на печать и необходима только для более удобного перемещения текстовых блоков, когда можно перемещать текст не только за контур надписи, но и за саму рамку. Чаще всего вопрос с рамкой текста связан с тем, что она перекрывает объекты, которые размещены за ней. Например, вот так:
Чтобы отрезки, либо любые другие объекты не перекрывались, нужно внести дополнительные настройки. Заходим в раздел Параметры, который размещен в разделе «Настройка» главного текстового меню
Переходим на закладку «Текущий чертеж»
Внизу списка переходим на «Перекрывающиеся объекты» и убираем галочку «Прерывать штриховки и линии при пересечении…». Должно быть вот так.
А сам текст уже не будет перекрывать объекты и изображение будет выглядеть вот так:
Как в КОМПАСе повернуть текст
Ввести текст под углом можно, либо сразу задав угол на Панели параметров (до указания точки привязки текста)
Либо, при уже введенном тексте, выделив одним кликом текстовый блок и изменив параметр «Угол наклона»
Другой способ — использовать команду «Повернуть», которая размещена на инструментальной панели Правка.
Альтернативный способ вызова команды «Повернуть» — воспользоваться главным текстовым меню. Путь: Черчение — Преобразовать — Повернуть
Текст в кривых
Для преобразования текста в кривые нужно воспользоваться командой «Преобразовать в сплайн», которая расположена на инструментальной панели Правка
При использовании команды на Панели параметров можно будет задать тип сплайна, тип аппроксимации и шаг, удалять исходные объекты или нет.
После преобразования текста в кривые, исходный текст будет выглядеть следующим образом:
Вертикальный текст в КОМПАСе
Для ввода вертикального текста нужно вызвать команду «Надпись» , которая расположена на инструментальной панели Обозначения. После чего задать на Панели параметров в окне «Угол» значение 90 или 270.
Текст будет отображаться вот так:
Повернуть текст в таблице
Текст в таблицах КОМПАС может быть размещен горизонтально или вертикально. Для вертикального размещения, при создании таблицы, на Панели параметров нужно активировать параметр «Вертикальный текст»
Не отображается текст в КОМПАС
В своей работе КОМПАС использует шрифты операционной системы. При установке «специфические» шрифты, такие как, например, GOST type A устанавливаются по пути Windows-Fonts диска с операционной системой. Если какой-либо шрифт не отображается, возможно, он был установлен с ошибкой, нужно скопировать его с папки Fonts другого рабочего места, либо переустановить КОМПАС.
Текст по кругу
Для создания текста по кругу в КОМПАСе используется команда «Символы вдоль кривой» 
, которая расположена на инструментальной панели Сервисные инструменты.
Текст в КОМПАС
Работа в КОМПАС — это не только построение геометрических примитивов. Ввод текста не менее важен. Нужно знать как написать или вставить текст в КОМПАС. Повернуть его, например, сделать вертикальным. Как работать с рамкой текста.
Как написать (создать) текст в КОМПАС
Для создания текстового блока в КОМПАС применяется команда «Надпись» 
. Данная команда расположена на инструментальной панели «Обозначения»
Альтернативный способ вызова команды «Надпись» – использовать главное текстовое меню. Путь: Оформление – Надпись
После вызова команды нужно кликнуть в том месте чертежа, где необходимо разместить текстовый блок, а на Панели параметров указать угол наклона текста, его размещение (справа, по центру, слева), а также поставить галочку «Зеркальное отражение», если необходим зеркальный текст.
Создание вертикального текста в КОМПАС как раз и будет заключаться в указании угла 90 или 270 на Панели параметров. Причем вначале текст отображается горизонтальным, а уже после подтверждения действия и нажатия кнопки «Создать объект» 
текстовый блок поворачивается.
Как изменить текст
Под изменением текста чаще всего понимают, не правку содержимого текстового блока, а именно настройки текста, например, изменение шрифта, его высоты и т.п. Если все же вы хотите исправить сам текст, то делается это очень просто. Нужно 2 раза кликнуть по тексту, КОМПАС перейдет в режим редактирования операции, Вы сможете внести изменения и после их подтверждения кнопкой «Создать объект» все изменения будут сохранены.
Если же речь идет про изменение настроек текста, то они зависят от того сколько текстовых блоков Вам необходимо отредактировать. Если один, то достаточно просто кликнуть по тексту один раз и на Панели параметров отредактировать необходимые атрибуты. Не забывайте, что у панели параметров есть несколько закладок, поэтому, если у Вас отображается Дерево чертежа, то Вам нужно просто переключиться на закладку «Параметры»
Если выбрана именно закладка «Параметры», то отобразится вот такое окно.
В данном окне Вы можете отредактировать любой атрибут. Например, чтобы сделать текст вертикальным, нужно просто задать значение угла 90 или 270. Также Вы можете поменять основные параметры текстового блока — тип шрифта, его высоту и коэффициент сужения.
С одиночным текстовым блоком разобрались, теперь, давайте, рассмотрим вариант, когда нам необходимо отредактировать сразу все текстовые блоки на чертеже. Само редактирование ничем не будет отличаться от редактирования одного блока, вопрос только в том — как выделить все блоки? Для такого выделения мы используем команду «Выделить по свойствам». Она вызывается через главное текстовое меню — Выделить — По свойствам… После вызова команды появится вот такое окно:
В данном окне отображаются все типы объектов, которые присутствуют в документы. Нам нужны тексты, поэтому ставим галочку напротив слова «Тексты» и нажимаем «Выделить». Все текстовые блоки будут выделены и Вы сможете отредактировать их через Панель параметров.
Рамка текста КОМПАС
У каждого текстового блока КОМПАС есть невидимая рамка, которая влияет на отображение объектов чертежа. Например, если текст расположен над отрезком, то часть отрезка не будет отображаться
Если нам необходимо, чтобы отображалось всё, то потребуются следующие настройки.
Переходим в Главное текстовое меню — Настройка — Параметры — Закладка Текущий чертеж
Находим строку «Перекрывающиеся объекты» и убираем галочку «Прерывать штриховки ….», нажимаем кнопку «Ок»
После проведенных настроек рамка текстового блока уже ничего не перекрывает
Дополнительные настройки при работе с текстом
Фон текста
Фон текстовых надписей КОМПАС — белый. Данный параметр нельзя изменить. Если Вам нужен отличный от белого фон, то за текстом выполняется заливка. На рисунке ниже пример наложения текста и заливки желтого цвета.
Повернуть текст
Поворот текста можно выполнить изменив угол текста на Панели параметров, либо выполнив команду «Поворот». Путь к команде «Поворот»: Главное текстовое меню — Черчение — Преобразовать — Повернуть
Перевернуть текст
Чтобы перевернуть текст нужно задать значение угла 180. Угол задается на Панели параметров при редактировании текстового блока