Работа с 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».
Символ «эпсилон» на компьютере: все о способах его набора
You will be interested: How dangerous is the new coronavirus?
Используем копирование
Символ «эпсилон» принято считать специальным символом. Он не используется при основной печати текста.
Для вставки соответствующего знака в документ придется выполнить такие манипуляции:
На данном этапе действия можно закончить. Символ «эпсилон» появится на дисплее в указанном месте.
Аналогичным образом можно отыскать в Сети готовый файл с соответствующим знаком, затем выделить его, скопировать и вставить в свой текст. Только это не самое лучшее решение.
Функции «Ворда»
Символ «эпсилон» в «Ворде» любой версии можно написать иначе. На помощь приходят встроенные опции текстового редактора.
Чтобы воспользоваться ими нужно провести следующие манипуляции.
На дисплее ПК в указанном «пространстве» появится специальный символ. Данное решение пользуется огромным спросом, особенно среди начинающих пользователей ПК. Никаких навыков, знаний и особых умений прием не требует.
Коды и вставка
Символ «эпсилон» на клавиатуре найти нельзя. Тем не менее каждый юзер способен набрать его при помощи клавиатурной панели. Достаточно воспользоваться так называемым ASCII-кодом. При помощи соответствующих наборов цифр пользователи смогут за несколько секунд вставить любой специальный символ в свой текстовый документ.
Как действовать? Руководство по использованию ASCII для печати греческого алфавита имеет такое исполнение.
В тексте в указанном заранее месте отпечатается «ε». Этот прием значительно упрощает жизнь. С его помощью пользователь может избавиться от необходимости поиска специального знака в «Таблице символов» Windows.
Шестнадцатеричный код
Чтобы поставить греческую букву «эпсилон» в «Ворде», потребуется:
Важно: при использовании приема необходимо пользоваться латинскими буквами. В противном случае код не пройдет стадию обработки.
Работа с API КОМПАС-3D → Урок 10 → Спецсимволы, включающие строку
Мы уже знакомились со спецсимволами в 4 уроке нашего цикла. Там было показано их простейшее использование. Там же говорилось, что если интерфейс ksTextItemParam задает и спецсимвол, и строку, то строка располагается сразу за спецсимволом. Однако существуют спецсимволы, которые нарушают это правило. О них мы сегодня и поговорим.
Содержание цикла уроков «Работа с API КОМПАС-3D»
Спецсимволы, включающие строку
Таблица спецзнаков находится в приложении V основной справки КОМПАСа
Спецсимволы с номерами 78-80, 83, 93-99, 171 и 172 включают в свой состав строку. В этом случае строка s интерфейса ksTextItemParam располагается не после спецсимвола, а внутри него. Например, спецсимвол с номером 80 выводит текст в рамке. Ниже приводится пример программы, которая демонстрирует работу с таким спецсимволом.
Для простоты в данном примере опущен код, ответственный за создание и оформление документа (эта тема рассматривалась в предыдущих уроках цикла). На рисунке ниже показана основная надпись, сформированная этой программой.
Для простоты мы заполняем только одну ячейку. Спецсимвол с номером 98 определяет знак квадратного корня. Обратите внимание — значение свойства s интерфейса ksTextItemParam полностью оказывается под знаком корня. Точно так же работают и другие спецсимволы, включающие строку.
Спецсимволы и ksTextLineParam
Действие спецсимволов не ограничивается интерфейсом ksTextItemParam. Рассмотрим пример ниже.
В этом примере в основную надпись заносится строка, состоящая из трех компонент. Первые две содержат спецсимвол и строку. Третья компонента содержит только строку, без спецсимвола. Посмотрим на результат работы программы (на рисунке ниже приводится только сформированная строка без основной надписи).
Обратите внимание — в состав второго спецсимвола вошла как строка «Стр 2», так и строка «Стр 3», которую мы планировали вывести вне спецсимвола. Более того, обе этих строки вошли в состав первого спецсимвола (этого мы тоже не планировали). Данный пример демонстрирует два важных момента:
Параметры шрифта компоненты текста (ksTextItemFont)
Согласно документации интерфейс ksTextItemFont описывает параметры шрифта компоненты текста. Но на самом деле его возможности превышают простое описание используемого шрифта. Данный интерфейс позволяет формировать составные строки (о них — в следующих уроках цикла).
Получить его можно несколькими способами. Во-первых, с помощью метода GetParamStruct интерфейса KompasObject: для этого в качестве единственного параметра данному методу нужно передать константу ko_TextItemFont. Во-вторых, с помощью метода GetItemFont интерфейса ksTextItemParam. Этот метод не имеет входных параметров и возвращает интерфейс ksTextItemFont уже ассоциированным с компонентой текста.
Рассмотрим свойства интерфейса ksTextItemFont.
bitvector — битовый вектор, задающий признаки начертания текста (они будут подробно рассматриваться в следующих уроках цикла).
сolor — цвет символов в формате RGB.
fontName — строка с именем шрифта.
height — высота шрифта в миллиметрах.
ksu — коэффициент растяжения текста.
Методов у интерфейса ksTextItemFont всего три.
Init() сбрасывает значения всех свойств интерфейса. Не имеет входных параметров. В случае успеха возвращает значение TRUE, а в случае ошибки — FALSE.
GetBitVectorValue возвращает значение отдельного флага из набора bitvector. В качестве единственного параметра принимает флаг, значение которого мы хотим определить. Если он установлен, метод возвращает значение TRUE, если сброшен — FALSE.
SetBitVectorValue изменяет значение отдельного флага. Ниже приводится прототип данного метода:
Если значение параметра state равно TRUE, то флаг bitVector взводится, в противном случае — сбрасывается.
В случае успеха метод SetBitVectorValue возвращает значение TRUE, а в случае ошибки — FALSE.
Методы GetBitVectorValue и SetBitVectorValue позволяют работать со свойством bitvector, не обращаясь к нему напрямую.
Ограничение действия спецсимвола
Для управления спецсимволами предназначено два флага. Они приведены в таблице ниже.
Флаг SPECIAL_SYMBOL мы уже рассматривали, когда описывали интерфейс ksTextItemParam. Он нужен для того, чтобы указать — выводится спецсимвол. Этот же флаг дублируется в свойстве bitVector интерфейса ksTextItemFont (как показывают мои эксперименты, это дублирование необязательно).
Второй флаг (SPECIAL_SYMBOL_END) имеет смысл только для спецсимволов, включающих строку. Он отменяет действие спецсимвола. Строки, выводимые после этого флага, не входят в состав спецсимвола.
Совместное действие обоих флагов отменяет действие спецсимвола. В этом случае спецсимвол не будет выведен в документ.
Пример
Ниже приводится исходный код доработанной программы. В нём с помощью флагов, описанных выше, реализуется правильный вывод компонент.
Единственное отличие этого примера от предыдущего — после каждого спецсимвола выводится компонента, для которой в интерфейсе ksTextItemFont установлен флаг SPECIAL_SYMBOL_END. Единственное ее назначение — отмена действия спецсимвола. В первом случае она не содержит никаких данных (кроме флага, разумеется). А во втором случае содержит строку «Стр 3».
Объединять флаг SPECIAL_SYMBOL_END с выводом второго спецсимвола нельзя. Так как в этом случае данный флаг отменит действие обоих спецсимволов. Строка «Стр2» будет выведена без зачеркивания.
На рисунке ниже показана строка, выведенная данной программой в основную надпись.
Как видите, теперь действие спецсимволов распространяется только на «свою» компоненту.
Вложенные спецсимволы
Первый пример нашего сегодняшнего урока наглядно показывает — спецсимволы могут вкладываться друг в друга. Флаг SPECIAL_SYMBOL_END отменяет действие одного (последнего) спецсимвола. Это позволяет строить сложные строки с вложенными спецсимволами.
Ниже приводится исходный код доработанного примера, в котором подстрока «Стр 2» тоже входит в состав выражения под знаком квадратного корня.
Обратите внимание — после вывода подстроки «Стр 2» мы дважды выводим компоненту с флагом SPECIAL_SYMBOL_END (первый раз — в составе пустой компоненты, второй — вместе со строкой «Стр 3»). Это нужно для отмены действия спецсимволов. Первый раз мы отменяем спецсимвол 169 (зачеркивание), второй раз — 98 (квадратный корень). Если бы мы вывели только одну компоненту с флагом SPECIAL_SYMBOL_END, это отменило бы только спецсимвол 169, но не 98. В этом случае строка «Стр 3» не была бы зачеркнута, но входила бы в состав выражения под знаком корня.
На рисунке ниже показан результат работы данной программы.
В рамках этого урока мы познакомились со спецсимволами, включающими строку. Как вы увидели, они значительно отличаются от простых спецсимволов (например, букв греческого алфавита). Хотя мы показывали их на примере основной надписи, это не должно вас смущать. Данные символы могут быть использованы и в других методах вывода текста. Один из таких методов мы рассмотрим на следующем уроке.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».