文書化された複合文字列を作成する方法に進む前に、段落などのオブジェクトに慣れる必要があります。 これは、複数の行で構成される自動フォーマットされたテキストブロックです。 このレッスンでは、簡単なパラグラフの構築について見ていきます。
レッスンシリーズ「KOMPAS-3D APIの操作」の内容
- 基本
- 図面デザイン
- COMPASSへの正しい接続
- 主な碑文
- グラフィックプリミティブ
- ドキュメントをさまざまな形式で保存する
- 設定を知る
- タイトルブロックに書き込むためのより複雑なメソッド
- キャプションセルの読み取り
- 文字列を含む特殊文字
- シンプルなテキストラベル
- 複合文字列
- 段落
- 複数行テキスト
段落パラメーター（ ksParagraphParam ）
段落は、
ksParagraphParamインターフェイスによって記述されます。 それを取得するには、
KompasObjectインターフェースの
GetParamStructメソッドを使用する必要があります。これには、定数
ko_ParagraphParam （
0x0000001B ）を渡す必要があります。
ksParagraphParamインターフェイスのプロパティを検討してください。
ang-テキストの角度（度単位）。 水平線から反時計回りに遅れています。
ksTextメソッドの
angパラメーターに似ています。
height-ミリメートル単位の段落の高さ。
hFormat-テキストを水平にフォーマットします。 このプロパティは、テキストが幅の段落に収まらない場合に使用されます。 有効な値は、以下の表にリストされています。
style-テキストのスタイル（
レッスン11で説明）。
vFormat-テキストを垂直方向にフォーマットします。 このプロパティは、テキストが段落の高さに収まらない場合に使用されます。 有効な値は、以下の表にリストされています。
vFormatプロパティを使用する際には、次の2つの
点に注意して
ください 。
- KOMPASのドキュメントによると、 vFormatプロパティの有効な値は0と-1ですが、そうではありません。 有効な値は0および1です。
- COMPASSは文字の高さを変更しません。 ライン間の距離を変更するだけです。 行の高さが段落の高さより低い場合、それらは重なる可能性があります。 そのようなオーバーレイの例を下の図に示します。
width-ミリメートル単位の段落の幅。
プロパティ
height 、
hFormat 、
vFormat 、および
widthにより、指定された長方形にテキストを配置する問題を解決できます。 このメソッドは、
レッスン11で説明した
ksGetTextLengthメソッドよりもはるかに信頼性が高く効率的です。
xと
yはアンカーポイントの座標です。 水平軸に沿ったアンカーポイントに対する段落の位置は、
ksDocument2Dインターフェイスの
ksSetTextAlignメソッドによって調整されます（ただし、この可能性は文書化されていません）。 垂直アンカーポイントは、常に段落の最初の行の下部に一致します。 この動作は変更できません。
ksParagraphParamインターフェースに
は、 Init（）という 1つのメソッドしか
ありません。 インターフェイスプロパティの値を初期化します。 入力パラメーターはありません。 成功した場合、
trueを返し
ます 。
パラグラフビル
段落の作成は、3つの連続した手順で構成されます。
- 段落の始まりの宣言。 これを行うには、 ksDocument2DインターフェースのksParagraphメソッドが呼び出されます。 唯一のパラメーターとして、このメソッドは段落のパラメーターを設定するksParagraphParamインターフェースを受け入れます。 成功した場合、 ksParagraphメソッドは1を返し、エラーの場合はゼロを返します 。
- 段落を埋めます。 段落に表示される各行に対して、 ksDocument2DインターフェイスのksTextLineメソッドが呼び出されます。 唯一のパラメーターとして、文字列を記述するksTextItemParamまたはksTextLineParamインターフェイス （ループの前のレッスンで説明）を受け入れます。 出力行には、制御文字である文字@ 、 $ 、 ＆ 、 〜 、 ^および＃を含めることはできません。 それらの作業は、サイクルの次のレッスンで検討されます。
- 段落の終わり。 これを行うには、 ksDocument2DインターフェイスのksEndObj（）メソッドが呼び出されます。 入力パラメーターはなく、成功した場合、作成されたオブジェクト（段落）への整数ポインターを返します。 エラーの場合、 ゼロを返します 。
例。 最も単純な段落
以下は、単純な段落の構成を示すプログラムのソースコードです。// ksTextItemParam TextItemParamPtr textItemParam; textItemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam)); // ParagraphParamPtr paragraphParam; paragraphParam = static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam)); paragraphParam->Init(); paragraphParam->set_x(100.0); paragraphParam->set_y(100.0); // Document2D->ksParagraph(paragraphParam); // BSTR str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); // Document2D->ksEndObj(); paragraphParam.Unbind(); textItemParam.Unbind();
いつものように、ここでは、簡単にするために、ドキュメントの作成と実行を担当するコードは省略されています（このトピックは前のレッスンで説明しました）。
この例では、KOMPAS自体がその内容に基づいて段落のサイズを決定します。 以下の図は、生成された段落を示しています。
注：テキストは1行で表示されます。 段落の幅は指定しなかったため、KOMPASは必要に応じて自動的に幅を広げます。 幅が設定されている場合、COMPASSの動作は、
ksParagraphParamインターフェイスの
hFormatプロパティの値によって決定されます。
複数行の複合テキストを作成するには、前のレッスンで部分的に説明した描画機能を使用する必要があります。
例。 複数行テキスト
新しい行に明示的に
ラップするには、
NEW_LINEフラグ（
0x1000 ）を使用します。
以下は、このフラグを使用して複数行の段落を作成する方法を示すプログラム例です。 // ksTextItemParam TextItemParamPtr textItemParam; textItemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam)); // ParagraphParamPtr paragraphParam; paragraphParam = static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam)); paragraphParam->Init(); paragraphParam->set_x(100.0); paragraphParam->set_y(100.0); // Document2D->ksParagraph(paragraphParam); // BSTR str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); TextItemFontPtr textItemFont; textItemFont = static_cast<TextItemFontPtr>(textItemParam->GetItemFont()); textItemFont->SetBitVectorValue(NEW_LINE, true); str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); textItemFont.Unbind(); str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); // Document2D->ksEndObj(); paragraphParam.Unbind(); textItemParam.Unbind();
この例では、3行の段落が作成されます。 最初の行は通常どおり表示されます。 2番目の場合、
NEW_LINEフラグが
設定されます。 彼は新しい行の始まりについて語っています。 3番目のものは通常どおり表示されますが、
ksTextItemParamインターフェイスの同じインスタンスで作業しているため、
NEW_LINEフラグはまだアクティブです。 以下の図は、このプログラムによって生成された段落を示しています。
これで、行が正しく表示されます。
段落を扱うための課題
テキストの配置
テキストの配置は、
ksDocument2Dインターフェイスの
ksSetTextLineAlignメソッドによって設定されます。 整数パラメーターは1つだけで、アライメントを設定します。 有効な値は、以下の表にリストされています。
成功した場合、
ksSetTextLineAlignメソッドは前の配置フラグを返し、エラーの場合は
-1を返します。
ksSetTextLineAlignメソッドはブロック内でのみ使用できることに注意してください（この場合、段落内で使用されます）。 これは、
ksTextメソッドによるテキスト出力の配置の設定には使用できないことを意味します。 この制限は、この場合、KOMPASはテキストをどの境界に関して整列させる必要があるかを知らないという事実によるものです。
もう1つの重要な点は、
ksSetTextLineAlignメソッドのスコープに関連しています-どの出力行が影響します。 例について考えてみましょう（ここでは、元の構文と比較して非常に単純化された構文が使用されています）。
ksSetTextLineAlign(1); ksTextLine(“ ”); ksSetTextLineAlign(2); ksTextLine(“ ”);
行はどのように配置されますか？ 予想に反して、両方の行が右に揃えられます。 なんで？ 実際のところ、
ksSetTextLineAlignメソッドは、最初に最後の出力行の配置を変更します。 この例で起こることは次のとおりです。最初の行は中央揃えを設定します。 前の出力行がないため、この呼び出しはデフォルトの配置を変更します（左）。
次に、「Center」という行を印刷します。 最初は、以前に設定された中央の位置合わせを使用します。
3行目では、再び配置を変更します。 まず、このメソッドは前の行（「中央」）の配置を変更します。 したがって、計画どおり、中央ではなく右側に配置されます。 デフォルトでは、同じ配置が配置されます。
行「Right」を表示します。
ksSetTextLineAlignメソッド
は呼び出されなくなったため、以前に設定された配置（右側）を使用します。
したがって、両方の行は右に揃えられます。 次に、例を少し変更しましょう。
ksSetTextLineAlign(1); ksTextLine(“ ”); ksTextLine(“”); ksSetTextLineAlign(2); ksTextLine(“ ”);
変更したのは、配置を変更せずに空の行出力を追加することだけでした。 これで、行が正しく表示されます。 これは、空の文字列の出力が設定された右揃えを「吸収」するために発生します。
ksSetTextLineAlignメソッドの2番目の呼び出しは、空の行に影響を与えますが、Center行には影響しません。
以下の例は、空の文字列を表示せずに正しい配置を示しています。
ksTextLine(“ ”); ksSetTextLineAlign(1); ksTextLine(“ ”); ksSetTextLineAlign(2);
ksTextLineと
ksSetTextLineAlignの呼び出しは交換されます。
ksSetTextLineAlignメソッドは主に最後に表示された行に影響するため、配置は正しく設定され、希望どおりに行が表示されます。
例
以下は、段落内のテキストの配置を示すプログラムのソースコードです。 // ksTextItemParam TextItemParamPtr textItemParam; textItemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam)); // ParagraphParamPtr paragraphParam; paragraphParam = static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam)); paragraphParam->Init(); paragraphParam->set_x(100.0); paragraphParam->set_y(100.0); paragraphParam->set_width(60.0); paragraphParam->set_hFormat(2); // Document2D->ksParagraph(paragraphParam); // BSTR str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); TextItemFontPtr textItemFont; textItemFont = static_cast<TextItemFontPtr>(textItemParam->GetItemFont()); textItemFont->SetBitVectorValue(NEW_LINE, true); str = SysAllocString(L""); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); textItemFont.Unbind(); str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); Document2D->ksSetTextLineAlign(1); str = SysAllocString(L""); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); Document2D->ksSetTextLineAlign(3); // Document2D->ksEndObj(); paragraphParam.Unbind(); textItemParam.Unbind();
この例では、テキストの配置に加えて、
ksParagraphParamインターフェイスの
widthプロパティと
hFormatプロパティの使用も示しています。 幅を制限するために使用されます。 それらを変更しなかった場合、KOMPASは段落の幅を広げ、左と幅の整列は表示されません。
段落の読みやすさを向上させるために、空白行が表示されます。 それらは正しいアライメントには影響しません。
以下の図は、このプログラムによって生成された段落を示しています。
スタイルをオンまたはオフにします
サイクルの11番目のレッスンでは 、スタイルを制御するフラグ（
ITALIC_ON 、
ITALIC_OFF 、
BOLD_ON 、
UNDERLINE_ONおよび
UNDERLINE_OFF ）を調べました。 次に、
ksTextメソッドに関連してそれらを調べました。 段落での使用の重要な違いは、アクションが
ksTextLineメソッドの呼び出しに限定されず、段落全体に拡張されることです。 いくつかの例を見てみましょう。
TextItemFont->SetBitVectorValue(BOLD_ON, true); TextItemParam->s = SysAllocString(L” ”); Document2D->ksTextLine(TextItemParam); TextItemFont->Init(); TextItemParam->s = SysAllocString(L” ”); Document2D->ksTextLine(TextItemParam);
最初の行は太字で表示されます。 これに関する質問はありません。 しかし、2行目はどのように表示されますか？ 彼女のフラグ
BOLD_ONはリセットされました。 したがって、通常のフォントで表示されると想定できます。 しかし、これはそうではありません。
BOLD_ONフラグを満たしたKOMPASは、この方法でコマンドを理解します。この段落の後続の行はすべて太字で表示されます。 したがって、段落が完了するか、KOMPASが
BOLD_OFFフラグ
とペアになるまで、後続のすべての行は太字で表示されます。 例を考えてみましょう：
TextItemFont.SetBitVectorValue(BOLD_ON, true); TextItemParam.s = SysAllocString(L” ”); Document2D.ksTextLine(TextItemParam); TextItemFont.Init(); TextItemFont.SetBitVectorValue(BOLD_OFF, true); TextItemParam.s = SysAllocString(L“ ”); Document2D.ksTextLine(TextItemParam); TextItemFont.Init(); TextItemParam.s = SysAllocString(L” ”); Document2D.ksTextLine(TextItemParam);
最初の行は太字で表示されます。 2行目では、
BOLD_ONフラグをリセットし、
BOLD_OFFフラグと
組み合わせて太字スタイルを取り消します。 このため、2行目と3行目は太字で表示されません。
この動作は、フラグ
ITALIC_ON 、
ITALIC_OFF 、
UNDERLINE_ONおよび
UNDERLINE_OFFに適用されますが、オーバーライドフラグのペアがないため、
NEW_LINEフラグには適用されません。
例
以下はプログラムのソースコードで、段落を使用してさまざまなスタイルのテキストの出力を示しています。 // ksTextItemParam TextItemParamPtr textItemParam; textItemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam)); // ParagraphParamPtr paragraphParam; paragraphParam = static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam)); paragraphParam->Init(); paragraphParam->set_x(100.0); paragraphParam->set_y(100.0); // Document2D->ksParagraph(paragraphParam); // BSTR str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); TextItemFontPtr textItemFont; textItemFont = static_cast<TextItemFontPtr>(textItemParam->GetItemFont()); textItemFont->set_bitVector(NEW_LINE | ITALIC_OFF); // str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); textItemFont->set_bitVector(NEW_LINE | ITALIC_ON | BOLD_ON); // str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); textItemFont->set_bitVector(NEW_LINE | BOLD_OFF | UNDERLINE_ON); // str = SysAllocString(L" "); textItemParam->set_s(str); Document2D->ksTextLine(textItemParam); SysFreeString(str); // Document2D->ksEndObj(); paragraphParam.Unbind(); textItemFont.Unbind(); textItemParam.Unbind();
このプログラムの最も重要な部分は、出力行のフラグの適切な設定です。 それをより詳細に分析してみましょう（プログラムの対応する行には、「
// 」という文字のペアが付いています）。
最初の行は変更なしで表示されます。 したがって、フラグは設定されていません。
2番目の行は、勾配なしで新しい行とともに表示されます。 したがって、フラグは
NEW_LINE （新しい行で開始）および
ITALIC_OFF （
斜体を無効化）に設定されます。
3行目は斜体で太字で表示されます。 これを行うために、フラグ
NEW_LINE 、
ITALIC_ON （斜体を
有効にする ）および
BOLD_ON （太字を
有効にする ）を設定します。 他のすべてのフラグはリセットされます。
4行目は、太字ではなく下線付きの斜体で印刷する必要があります。 これを行うために、フラグ
NEW_LINE 、
BOLD_OFF （太字を無効にし、前の行から残した）および
UNDERLINE_ON （下線を有効にします）をコックします。
段落にさらに行がある場合、それらは斜体の下線付きフォントで表示されます。 下線付きスタイルを無効にするには、UNDERLINE_ONフラグをクリアし、UNDERLINE_OFFフラグを設定する必要があります。
次の図は、このプログラムの結果を示しています。
情報をプレゼンテーションから分離する
プログラムの構造に従うと、おそらく前の例の重大な欠点に気づいたでしょう。出力を生成するコードは、その出力を実装するコードと混ざっています。 優れたプログラミングスタイルでは、情報をプレゼンテーションから分離するのが一般的です。
表示される情報が
ksTextItemParamの複数の行で構成されている場合、それらを1つのインターフェイス
ksTextLineParamに結合できます。
ksTextLineメソッドは、これらの両方のインターフェースを処理できます。 ただし、このアプローチには不快な制限があります
。ksTextLineメソッドが
ksTextLineParamインターフェースを受け入れる場合、
NEW_LINE （および
SPECIAL_SYMBOL_END ）フラグは無視されます。 つまり、
ksTextItemParamの一部のインスタンスに
NEW_LINEフラグが
設定されている場合でも、すべての情報が1行で表示されます。 この制限を回避するには、
各行に対して手動で
ksTextLineを呼び出す必要があります。
以下は、この手法を示す例のソースコードです。 // DynamicArrayPtr dynamicArray; dynamicArray = static_cast<DynamicArrayPtr>(kompas->GetDynamicArray(TEXT_ITEM_ARR)); dynamicArray->ksClearArray(); // ksTextItemParam TextItemParamPtr textItemParam; textItemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam)); // BSTR str = SysAllocString(L" "); textItemParam->set_s(str); dynamicArray->ksAddArrayItem(-1, textItemParam); SysFreeString(str); TextItemFontPtr textItemFont; textItemFont = static_cast<TextItemFontPtr>(textItemParam->GetItemFont()); textItemFont->set_bitVector(NEW_LINE | ITALIC_OFF); str = SysAllocString(L" "); textItemParam->set_s(str); dynamicArray->ksAddArrayItem(-1, textItemParam); SysFreeString(str); textItemFont->set_bitVector(NEW_LINE | ITALIC_ON | BOLD_ON); str = SysAllocString(L" "); textItemParam->set_s(str); dynamicArray->ksAddArrayItem(-1, textItemParam); SysFreeString(str); textItemFont->set_bitVector(NEW_LINE | BOLD_OFF | UNDERLINE_ON); str = SysAllocString(L" "); textItemParam->set_s(str); dynamicArray->ksAddArrayItem(-1, textItemParam); SysFreeString(str); // ParagraphParamPtr paragraphParam; paragraphParam = static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam)); paragraphParam->Init(); paragraphParam->set_x(100.0); paragraphParam->set_y(100.0); // Document2D->ksParagraph(paragraphParam); // for(unsigned int i = 0; i < dynamicArray->ksGetArrayCount(); ++i) { dynamicArray->ksGetArrayItem(i, textItemParam); Document2D->ksTextLine(textItemParam); } // Document2D->ksEndObj(); // textItemFont.Unbind(); textItemParam.Unbind(); paragraphParam.Unbind(); dynamicArray->ksDeleteArray(); dynamicArray.Unbind();
この例では、出力行は最初に
DynamicArrayに書き込まれ、その後にのみ段落に出力されます。 これにより、プレゼンテーションから情報を分離できます。 この例で
NEW_LINEフラグが使用されていない場合は、
ksTextLineメソッドを1回呼び出す
だけで十分です。
このプログラムの結果は、前の例の結果に似ています。
おわりにこのレッスンでは、段落を作成する方法と、それを使用して複数行のテキストを表示する方法を検討しました。 また、プレゼンテーションから情報を分離することも学びました。 残念ながら、複数行テキストを正しく出力するには、文字列の配列を手動で走査する必要があります。 これはあまり便利ではありません。 次のレッスンでは、この問題を解決する方法を示します。
継続するには、ブログのニュースに従ってください。
Sergey Norseev博士、「DelphiでのCOMPASのアプリケーション開発」の著者。