Geekly articles weekly

Bekerja dengan API KOMPAS-3D → Pelajaran 13 → Paragraf

Sebelum beralih ke cara terdokumentasi untuk membuat string majemuk, kita perlu membiasakan diri dengan objek seperti paragraf. Ini adalah blok teks yang diformat secara otomatis yang terdiri dari beberapa baris. Dalam pelajaran ini, kita akan melihat membangun paragraf sederhana.



Isi seri pelajaran “Bekerja dengan API KOMPAS-3D”


  1. Dasar-dasarnya
  2. Desain gambar
  3. Koneksi yang benar ke KOMPAS
  4. Prasasti utama
  5. Primitif grafis
  6. Menyimpan dokumen dalam berbagai format
  7. Mengenal pengaturan
  8. Metode penulisan yang lebih canggih di blok judul
  9. Membaca sel teks
  10. Karakter khusus termasuk string
  11. Label teks sederhana
  12. Senar majemuk
  13. Paragraf
  14. Teks multiline

Parameter Paragraf ( ksParagraphParam )


Paragraf dijelaskan oleh antarmuka ksParagraphParam . Untuk mendapatkannya, Anda harus menggunakan metode GetParamStruct dari antarmuka KompasObject , untuk ini Anda harus meneruskan ko_ParagraphParam ( 0x0000001B ) konstan ke sana. Pertimbangkan properti dari antarmuka ksParagraphParam .

ang - sudut teks dalam derajat. Ditunda dari garis horizontal berlawanan arah jarum jam. Mirip dengan parameter ang dari metode ksText .

tinggi - ketinggian paragraf dalam milimeter.

hFormat - memformat teks secara horizontal. Properti ini digunakan ketika teks tidak sesuai dengan lebar paragraf. Nilai yang valid tercantum dalam tabel di bawah ini.



gaya - gaya teks (dijelaskan dalam pelajaran 11 ).

vFormat - memformat teks secara vertikal. Properti ini digunakan ketika teks tidak sesuai dengan tinggi paragraf. Nilai yang valid tercantum dalam tabel di bawah ini.



Ada dua hal yang perlu diingat ketika bekerja dengan properti vFormat :

  1. Menurut dokumentasi KOMPAS, nilai valid properti vFormat adalah 0 dan -1 , tetapi tidak demikian. Nilai yang valid adalah 0 dan 1 .
  2. COMPASS tidak mengubah ketinggian karakter. Itu hanya mengubah jarak antara garis. Jika tinggi baris kurang dari tinggi paragraf, maka mereka bisa tumpang tindih. Contoh overlay seperti itu ada pada gambar di bawah ini.



width - lebar paragraf dalam milimeter.
Properti tinggi , hFormat , vFormat dan lebar memungkinkan kita untuk memecahkan masalah menempatkan teks dalam persegi panjang yang diberikan. Metode ini jauh lebih dapat diandalkan dan efisien daripada metode ksGetTextLength yang dibahas dalam Pelajaran 11 .

x dan y adalah koordinat titik jangkar. Posisi paragraf relatif terhadap titik jangkar sepanjang sumbu horizontal disesuaikan dengan metode ksSetTextAlign dari antarmuka ksDocument2D (meskipun kemungkinan ini tidak didokumentasikan). Titik jangkar vertikal selalu cocok dengan bagian bawah baris pertama paragraf. Perilaku ini tidak dapat diubah.
Antarmuka ksParagraphParam hanya memiliki satu metode: Init () . Ini menginisialisasi nilai properti antarmuka. Tidak memiliki parameter input. Jika berhasil, mengembalikan true .

Bangunan paragraf


Membuat paragraf terdiri dari tiga langkah berurutan.

  1. Deklarasi awal paragraf. Untuk melakukan ini, metode ksParagraph dari antarmuka ksDocument2D disebut . Sebagai satu-satunya parameter, metode ini menerima antarmuka ksParagraphParam , yang menetapkan parameter paragraf. Jika berhasil, metode ksParagraph mengembalikan satu, dan jika terjadi kesalahan, mengembalikan nol .
  2. Mengisi paragraf. Untuk setiap baris yang ditampilkan dalam paragraf, metode ksTextLine dari antarmuka ksDocument2D disebut . Sebagai satu-satunya parameter, ia menerima antarmuka ksTextItemParam atau ksTextLineParam (dibahas dalam pelajaran sebelumnya di loop) yang menggambarkan string. Harap dicatat bahwa garis output tidak boleh mengandung karakter @ , $ , & , ~ , ^ dan # , karena mereka adalah karakter kontrol. Bekerja dengan mereka akan dipertimbangkan dalam pelajaran siklus berikutnya.
  3. Akhir paragraf. Untuk melakukan ini, metode ksEndObj () dari antarmuka ksDocument2D disebut . Tidak memiliki parameter input dan, jika berhasil, mengembalikan pointer integer ke objek yang dibuat (paragraf). Jika terjadi kesalahan, ia mengembalikan nol .

Sebuah contoh Paragraf paling sederhana


Di bawah ini adalah kode sumber program, menunjukkan konstruksi paragraf sederhana.
//  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();


Seperti biasa, di sini, untuk kesederhanaan, kode yang bertanggung jawab untuk pembuatan dan pelaksanaan dokumen dihilangkan (topik ini dibahas dalam pelajaran sebelumnya).

Dalam contoh ini, KOMPAS sendiri menentukan ukuran paragraf berdasarkan isinya. Gambar di bawah ini menunjukkan paragraf yang dihasilkan.



Harap dicatat: teks ditampilkan sebagai satu baris. Kami tidak menentukan lebar paragraf, sehingga KOMPAS secara otomatis meningkatkannya sesuai kebutuhan. Jika lebarnya ditetapkan, maka perilaku COMPASS akan ditentukan oleh nilai properti hFormat dari antarmuka ksParagraphParam .

Untuk membentuk teks multi-baris dan majemuk, Anda perlu menggunakan fitur menggambar yang sebagian dibahas dalam pelajaran sebelumnya.

Sebuah contoh Teks multiline


Untuk membungkus secara eksplisit ke baris baru, gunakan bendera NEW_LINE ( 0x1000 ).

Berikut ini adalah contoh program yang menunjukkan pembuatan paragraf multi-baris menggunakan bendera ini.
 //  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();


Dalam contoh ini, paragraf tiga baris dibuat. Baris pertama ditampilkan seperti biasa. Untuk yang kedua, bendera NEW_LINE diatur . Dia berbicara tentang awal dari sebuah baris baru. Yang ketiga ditampilkan seperti biasa, tetapi flag NEW_LINE masih aktif untuk itu, karena kami bekerja dengan instance yang sama dari antarmuka ksTextItemParam . Gambar di bawah ini menunjukkan paragraf yang dihasilkan oleh program ini.


Sekarang garis ditampilkan dengan benar.

Tantangan untuk bekerja dengan paragraf


Perataan teks


Perataan teks diatur oleh metode ksSetTextLineAlign dari antarmuka ksDocument2D . Hanya memiliki satu parameter integer - atur perataan. Nilai yang valid tercantum dalam tabel di bawah ini.



Jika berhasil, metode ksSetTextLineAlign mengembalikan bendera penyelarasan sebelumnya, dan jika terjadi kesalahan, mengembalikan -1 .

Perhatikan bahwa metode ksSetTextLineAlign hanya dapat digunakan di dalam blok (dalam kasus kami, ini digunakan di dalam paragraf). Ini berarti bahwa itu tidak dapat digunakan untuk mengatur perataan untuk keluaran teks dengan metode ksText . Keterbatasan ini disebabkan oleh fakta bahwa dalam kasus ini, KOMPAS tidak tahu sehubungan dengan batas mana teks perlu disejajarkan.
Poin penting lainnya terkait dengan ruang lingkup metode ksSetTextLineAlign - garis output yang terpengaruh . Pertimbangkan sebuah contoh (sintaks yang sangat sederhana digunakan di sini dibandingkan dengan aslinya):

 ksSetTextLineAlign(1); ksTextLine(“ ”); ksSetTextLineAlign(2); ksTextLine(“  ”);

Bagaimana garis-garis akan diluruskan? Bertentangan dengan harapan kami, kedua baris akan disejajarkan dengan kanan. Mengapa Faktanya adalah bahwa metode ksSetTextLineAlign pertama-tama mengubah perataan garis keluaran terakhir. Inilah yang terjadi dalam contoh kita: baris pertama mengatur perataan tengah. Karena tidak ada jalur output sebelumnya, panggilan ini mengubah perataan standar (kiri).

Kemudian kami mencetak garis "Tengah". Awalnya, ia menggunakan perataan tengah yang ditetapkan sebelumnya.

Di baris ketiga, kami kembali mengubah perataan. Pertama-tama, metode ini mengubah perataan garis sebelumnya ("Tengah"). Oleh karena itu, itu sejajar dengan kanan, dan bukan ke pusat, seperti yang kami rencanakan. Alignment yang sama menjadi sejajar secara default.
Kami menampilkan baris "Benar". Karena metode ksSetTextLineAlign tidak lagi dipanggil, ia menggunakan perataan yang ditetapkan sebelumnya (ke kanan).
Dengan demikian, kedua garis selaras ke kanan. Sekarang mari kita ubah sedikit contoh:

 ksSetTextLineAlign(1); ksTextLine(“ ”); ksTextLine(“”); ksSetTextLineAlign(2); ksTextLine(“  ”);

Yang kami ubah hanyalah menambahkan output dari string kosong tanpa mengubah perataan. Sekarang garis ditampilkan dengan benar. Ini terjadi karena output dari string kosong "menyerap" perataan yang benar. Panggilan kedua ke metode ksSetTextLineAlign memengaruhi garis kosong dan tidak memengaruhi garis tengah dengan cara apa pun.
Contoh di bawah ini menunjukkan perataan yang benar tanpa menampilkan string kosong.

 ksTextLine(“ ”); ksSetTextLineAlign(1); ksTextLine(“  ”); ksSetTextLineAlign(2);

Panggilan ksTextLine dan ksSetTextLineAlign ditukar. Karena metode ksSetTextLineAlign terutama mempengaruhi baris yang terakhir ditampilkan, keberpihakan diatur dengan benar, dan garis ditampilkan seperti yang kita inginkan.

Contoh


Berikut ini adalah kode sumber program yang menunjukkan perataan teks dalam paragraf.
 //  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();


Dalam contoh ini, selain perataan teks, penggunaan properti width dan hFormat dari antarmuka ksParagraphParam juga diperlihatkan. Mereka digunakan untuk membatasi lebarnya. Jika kami tidak mengubahnya, KOMPAS akan menambah lebar paragraf, dan kami tidak akan melihat perataan ke kiri dan ke lebar.

Baris kosong ditampilkan untuk meningkatkan keterbacaan paragraf. Mereka tidak mempengaruhi perataan yang benar.

Gambar di bawah ini menunjukkan paragraf yang dihasilkan oleh program ini.



Hidupkan atau matikan gayanya


Dalam pelajaran ke 11 dari siklus, kami memeriksa bendera yang mengontrol gaya ( ITALIC_ON , ITALIC_OFF , BOLD_ON , UNDERLINE_ON dan UNDERLINE_OFF ). Kemudian kami memeriksanya sehubungan dengan metode ksText . Perbedaan penting antara penggunaannya dalam paragraf adalah bahwa tindakan tidak terbatas pada memanggil metode ksTextLine , tetapi meluas ke seluruh paragraf. Mari kita lihat beberapa contoh.

 TextItemFont->SetBitVectorValue(BOLD_ON, true); TextItemParam->s = SysAllocString(L” ”); Document2D->ksTextLine(TextItemParam); TextItemFont->Init(); TextItemParam->s = SysAllocString(L” ”); Document2D->ksTextLine(TextItemParam);

Baris pertama akan ditampilkan dalam huruf tebal. Tidak ada pertanyaan dengan ini. Tetapi bagaimana baris kedua akan ditampilkan? Bendera BOLD_ON telah disetel ulang untuknya. Karena itu, kita dapat mengasumsikan bahwa itu akan ditampilkan dalam font biasa. Tapi ini tidak benar. Setelah memenuhi bendera BOLD_ON , KOMPAS memahami perintah sebagai berikut: semua baris paragraf berikutnya ditampilkan dalam huruf tebal. Oleh karena itu, semua baris berikutnya ditampilkan dalam huruf tebal hingga paragraf selesai atau KOMPAS menemukan bendera BOLD_OFF yang dipasangkan dengannya . Pertimbangkan sebuah contoh:

 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);

Baris pertama ditampilkan dalam huruf tebal. Untuk baris kedua, kami menghapus bendera BOLD_ON dan mengibarkan bendera BOLD_OFF yang dipasangkan dengannya , yang membatalkan gaya tebal. Karena ini, baris kedua dan ketiga ditampilkan tanpa huruf tebal.

Perilaku ini berlaku untuk bendera ITALIC_ON , ITALIC_OFF , UNDERLINE_ON dan UNDERLINE_OFF , tetapi tidak berlaku untuk bendera NEW_LINE , karena tidak memiliki sepasang bendera yang menimpa.

Contoh


Berikut ini adalah kode sumber program, menampilkan output teks dengan gaya yang berbeda menggunakan paragraf.
 //  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();


Bagian terpenting dari program ini adalah pengaturan flag yang tepat untuk jalur output. Mari kita menganalisisnya lebih terinci (baris yang sesuai dari program ditandai dengan sepasang karakter " // ").

Baris pertama ditampilkan tanpa perubahan apa pun. Karenanya, tidak ada flag yang ditetapkan untuk itu.

Baris kedua harus ditampilkan tanpa kemiringan dan dengan garis baru. Oleh karena itu, tanda ditetapkan untuk itu: NEW_LINE (mulai pada baris baru) dan ITALIC_OFF (nonaktifkan miring ).

Baris ketiga harus muncul dalam huruf miring dan tebal. Untuk melakukan ini, kami mengibarkan bendera: NEW_LINE , ITALIC_ON ( aktifkan huruf miring) dan BOLD_ON ( aktifkan wajah tebal). Semua flag lainnya disetel ulang.

Baris keempat harus dicetak miring, bergaris bawah dan tidak tebal. Untuk melakukan ini, kami mengibarkan bendera: NEW_LINE , BOLD_OFF (nonaktifkan huruf tebal, yang tersisa dari baris sebelumnya) dan UNDERLINE_ON (aktifkan bergaris bawah).

Jika ada lebih banyak baris dalam paragraf, mereka akan ditampilkan dalam huruf miring bergaris miring. Untuk menonaktifkan gaya yang digarisbawahi, Anda harus menghapus bendera UNDERLINE_ON dan mengibarkan bendera UNDERLINE_OFF .

Gambar di bawah ini menunjukkan hasil dari program ini.



Memisahkan informasi dari presentasi


Jika Anda mengikuti struktur program Anda, Anda mungkin melihat kelemahan serius dari contoh sebelumnya: kode yang bertanggung jawab untuk menghasilkan output dicampur dengan kode yang bertanggung jawab untuk mengimplementasikan outputnya. Dengan gaya pemrograman yang baik, biasanya memisahkan informasi dari presentasinya.

Jika informasi output terdiri dari beberapa baris ksTextItemParam , maka mereka dapat digabungkan menjadi satu antarmuka ksTextLineParam . Metode ksTextLine dapat menangani kedua antarmuka ini. Tetapi pendekatan ini memiliki batasan yang tidak menyenangkan: jika metode ksTextLine menerima antarmuka ksTextLineParam , maka flag NEW_LINE (dan SPECIAL_SYMBOL_END ) diabaikan. Yaitu, semua informasi akan ditampilkan pada satu baris, bahkan jika flag NEW_LINE diatur untuk beberapa instance ksTextItemParam . Untuk mengatasi batasan ini, Anda harus secara manual memanggil ksTextLine untuk setiap baris.

Berikut ini adalah kode sumber untuk contoh yang menunjukkan teknik ini.
 //    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();


Dalam contoh ini, baris output pertama kali ditulis ke DynamicArray , dan hanya kemudian output ke paragraf. Ini memungkinkan Anda untuk memisahkan informasi dari presentasinya. Jika flag NEW_LINE tidak digunakan dalam contoh kita, maka kita bisa bertahan dengan satu panggilan ke metode ksTextLine .

Hasil dari program ini mirip dengan hasil dari contoh sebelumnya.

Kesimpulan

Dalam pelajaran ini, kami melihat bagaimana membangun paragraf dan bagaimana menggunakannya untuk menampilkan teks multi-baris. Kami juga belajar memisahkan informasi dari presentasinya. Sayangnya, output teks multi-baris yang benar membutuhkan lintasan string array secara manual. Ini sangat tidak nyaman. Dalam pelajaran selanjutnya saya akan menunjukkan cara mengatasi masalah ini.

Untuk dilanjutkan, ikuti berita blog.

Sergey Norseev, Ph.D., penulis buku "Pengembangan Aplikasi untuk COMPAS di Delphi."

Source: https://habr.com/ru/post/id434336/

More articles:


All Articles