レッスンシリーズ「KOMPAS-3D APIの操作」の内容
段落パラメーター（ 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のアプリケーション開発」の著者。