Tentang Kontrol Tooltip

Tooltip muncul secara otomatis ketika pengguna menempatkan kursor di atas alat atau elemen UI lainnya. Tooltip muncul di dekat penunjuk dan secara otomatis menghilang ketika pengguna mengklik tombol mouse, menggerakkan penunjuk menjauh dari alat, atau hanya menunggu beberapa detik.

Kontrol tipsalat dalam ilustrasi berikut menampilkan informasi tentang file di desktop Windows. Saat Anda memindahkan mouse pada ilustrasi, Anda juga akan melihat tooltip langsung yang berisi teks deskriptif.

Bagian ini menjelaskan cara kerja kontrol tooltip dan cara membuatnya.

• Perilaku dan Tampilan Tooltip
• Membuat Kontrol Tooltip
• Mengaktifkan Kontrol Tooltip
• Alat Pendukung
• Menampilkan Teks
• Olahpesan dan Pemberitahuan
• Pengujian Tabrakan
• Pemrosesan Pesan Default

Perilaku dan Tampilan Tooltip

Kontrol tipsalat dapat menampilkan satu baris teks atau beberapa baris. Sudutnya bisa berbentuk bulat atau persegi. Mereka mungkin atau mungkin tidak memiliki batang yang menunjuk ke alat seperti balon ucapan kartun. Teks tooltip dapat diam atau bergerak mengikuti penunjuk mouse, yang disebut pelacakan. Teks stasioner dapat ditampilkan berdekatan dengan alat atau dapat ditampilkan di atas alat, yang disebut sebagai secara langsung. Tipsalat standar bersifat stasioner, menampilkan satu baris teks, memiliki sudut persegi, dan tidak memiliki batang yang menunjuk ke alat.

Tooltip pelacakan, yang didukung oleh versi 4.70 dari common controls, mengubah posisi pada layar secara dinamis. Dengan memperbarui posisi dengan cepat, kontrol tipsalat ini tampaknya bergerak dengan lancar, atau "melacak." Ini berguna ketika Anda ingin teks tipsalat mengikuti posisi penunjuk mouse saat bergerak. Untuk informasi lebih lanjut tentang tooltip pelacakan dan contoh kode yang menunjukkan cara membuatnya, lihat Tooltips Pelacakan.

Tooltip multibaris, yang juga didukung oleh kontrol umum sistem versi 4.70, menampilkan teks pada lebih dari satu baris. Ini berguna untuk menampilkan pesan panjang. Untuk informasi selengkapnya dan contoh yang menunjukkan cara membuat tooltip multibaris, simak Tooltip Multibaris.

Tipsalat balon ditampilkan dalam kotak dengan sudut bulat dan batang menunjuk ke alat. Mereka dapat berupa satu baris atau multibaris. Ilustrasi berikut menunjukkan tipsalat balon dengan batang dan persegi panjang dalam posisi defaultnya. Untuk informasi selengkapnya tentang tooltip balon dan contoh yang menunjukkan cara membuatnya, silakan lihat Menggunakan Kontrol Tooltip.

Tipsalat juga dapat memiliki teks judul dan ikon, seperti yang ditunjukkan dalam ilustrasi berikut. Perhatikan bahwa tipsalat harus memiliki teks; jika hanya memiliki teks judul, tipsalat tidak ditampilkan. Ikon juga tidak muncul kecuali ada judul.

Terkadang string teks diklip karena terlalu panjang untuk ditampilkan sepenuhnya di jendela kecil. Tooltip langsung digunakan untuk menampilkan string teks pada objek yang terpotong, seperti nama file dalam ilustrasi berikut. Untuk contoh yang menunjukkan cara membuat tooltip langsung, silakan lihat In-Place Tooltips.

Kursor harus berada di atas alat untuk jangka waktu tertentu sebelum tooltip ditampilkan. Durasi default batas waktu ini dikontrol oleh waktu klik ganda pengguna dan biasanya sekitar satu setengah detik. Untuk menentukan nilai batas waktu non-default, kirim kontrol tooltip pesan "TTM_SETDELAYTIME".

Membuat Kontrol Tooltip

Untuk membuat kontrol tooltip, panggil CreateWindowEx dan tentukan kelas jendela TOOLTIPS_CLASS. Kelas ini terdaftar ketika DLL kontrol umum dimuat. Untuk memastikan bahwa DLL ini dimuat, sertakan fungsiInitCommonControlsEx dalam aplikasi Anda. Anda harus secara eksplisit mendefinisikan kontrol tooltip sebagai yang teratas. Jika tidak, mungkin tertutupi oleh jendela utama. Fragmen kode berikut menunjukkan cara membuat kontrol tooltip.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

Prosedur jendela untuk kontrol tipsalat secara otomatis mengatur ukuran, posisi, dan visibilitas kontrol. Tinggi jendela tooltip didasarkan pada tinggi font yang saat ini dipilih ke dalam konteks perangkat untuk kontrol tooltip. Lebar bervariasi berdasarkan panjang string yang saat ini berada di jendela tooltip.

Mengaktifkan Kontrol Tooltip

Kontrol tooltip dapat dalam keadaan aktif atau tidak aktif. Saat aktif, teks penunjuk muncul ketika penunjuk mouse berada di alat. Ketika tidak aktif, teks tooltip tidak muncul, bahkan jika kursor berada di alat. Pesan TTM_ACTIVATE mengaktifkan dan menonaktifkan kontrol tooltip.

Alat Pendukung

Kontrol tooltip dapat mendukung sejumlah alat. Untuk mendukung alat tertentu, Anda harus mendaftarkan alat tersebut dengan kontrol tooltip dengan mengirimkan pesan TTM_ADDTOOL ke kontrol. Pesan ini mencakup alamat struktur TOOLINFO, yang menyediakan informasi yang diperlukan kontrol tooltip untuk menampilkan teks alat. uID anggota dari struktur TOOLINFO ditentukan oleh aplikasi. Setiap kali Anda menambahkan alat, aplikasi Anda menyediakan pengidentifikasi unik. Anggota cbSize dari struktur TOOLINFO diperlukan, dan harus menentukan ukuran struktur.

Kontrol tooltip mendukung alat yang diimplementasikan sebagai jendela (seperti jendela anak atau jendela kontrol) dan area persegi panjang di dalam area klien jendela. Saat Anda menambahkan alat yang diimplementasikan sebagai area segi empat panjang, anggota struktur TOOLINFO harus menentukan handle ke jendela yang berisi area, dan anggota harus menentukan koordinat klien dari segi empat panjang pembatas area. Selain itu, anggota uID harus menentukan pengidentifikasi yang ditentukan oleh aplikasi untuk alat tersebut.

Saat Anda menambahkan alat yang diimplementasikan sebagai jendela, anggota uID dari struktur TOOLINFO harus berisi pegangan jendela untuk alat tersebut. Selain itu, anggota uFlags harus menentukan nilai TTF_IDISHWND, yang memberi tahu kontrol tooltip untuk menginterpretasikan anggota uID sebagai handle jendela.

Menampilkan Teks

Saat Anda menambahkan alat ke kontrol tipsalat, lpszText anggota struktur TOOLINFO harus menentukan alamat string yang akan ditampilkan untuk alat tersebut. Setelah menambahkan alat, Anda dapat mengubah teks menggunakan pesan TTM_UPDATETIPTEXT.

Jika kata urutan tinggi lpszText adalah nol, kata berurutan rendah harus menjadi pengidentifikasi sumber daya string. Ketika kontrol tipsalat membutuhkan teks, sistem memuat sumber daya string yang ditentukan dari instans aplikasi yang diidentifikasi oleh hinst anggota TOOLINFO struktur.

Jika Anda menentukan nilai LPSTR_TEXTCALLBACK dalam anggota lpszText, kontrol tooltip akan memberi tahu jendela yang ditentukan dalam anggota hwnd struktur TOOLINFOsetiap kali kontrol tooltip perlu menampilkan teks untuk alat. Kontrol tooltip mengirimkan kode pemberitahuan TTN_GETDISPINFO ke jendela. Pesan ini mencakup alamat strukturNMTTDISPINFO, yang berisi handel jendela serta pengidentifikasi yang ditentukan aplikasi untuk alat tersebut. Jendela memeriksa struktur untuk menentukan alat yang membutuhkan teks, dan mengisi anggota struktur yang sesuai dengan informasi yang diperlukan oleh kontrol tooltip untuk menampilkan string.

Banyak aplikasi membuat toolbar yang berisi alat yang sesuai dengan perintah menu. Untuk alat-alat tersebut, lebih nyaman jika kontrol tooltip menampilkan teks yang sama dengan item menu yang bersangkutan. Sistem secara otomatis menghapus karakter akselerator ampersand (&) dari semua string yang diteruskan ke kontrol tooltip, dan mengakhiri string pada karakter tab pertama (\t), kecuali kontrol tersebut memiliki gaya TTS_NOPREFIX.

Untuk mengambil teks untuk alat, gunakan pesan TTM_GETTEXT.

Olahpesan dan Pemberitahuan

Teks tooltip biasanya ditampilkan ketika penunjuk mouse melayang di sebuah area, biasanya persegi panjang yang ditentukan oleh alat seperti tombol kontrol. Namun, Microsoft Windows hanya mengirim pesan terkait mouse ke jendela yang berisi penunjuk, bukan kontrol tipsalat itu sendiri. Informasi terkait mouse harus disampaikan ke kontrol tipsalat agar dapat menampilkan teks tipsalat pada waktu dan tempat yang sesuai.

Anda dapat menyampaikan pesan secara otomatis jika:

• Alat ini adalah kontrol atau didefinisikan sebagai persegi panjang dalam struktur TOOLINFO dari alat tersebut.
• Jendela yang terkait dengan alat ini berada di utas yang sama dengan kontrol tooltip.

Jika kedua kondisi ini terpenuhi, atur flag TTF_SUBCLASS di anggota uFlags dari struktur TOOLINFO saat Anda menambahkan tool ke kontrol tooltip dengan TTM_ADDTOOL. Pesan mouse yang diperlukan kemudian akan disampaikan secara otomatis ke kontrol tooltip.

Mengatur TTF_SUBCLASS agar pesan mouse disampaikan ke kontrol cukup untuk sebagian besar tujuan. Namun, ini tidak akan berfungsi dalam kasus di mana tidak ada koneksi langsung antara kontrol tooltip dan jendela alat. Misalnya, jika alat diimplementasikan sebagai area persegi panjang di jendela yang ditentukan aplikasi, prosedur jendela menerima pesan mouse. Pengaturan TTF_SUBCLASS sudah cukup untuk memastikan bahwa mereka diteruskan ke pengendali. Namun, jika alat diimplementasikan sebagai jendela yang ditentukan sistem, pesan mouse dikirim ke jendela tersebut dan tidak tersedia secara langsung untuk aplikasi. Dalam hal ini, Anda harus mensubkelas jendela atau menggunakan kait pesan untuk mengakses pesan mouse. Anda kemudian harus secara eksplisit menyampaikan pesan mouse ke kontrol tipsalat dengan TTM_RELAYEVENT. Untuk contoh cara menggunakan TTM_RELAYEVENT, lihat Pelacakan Tooltip.

Ketika kontrol tooltip menerima pesan WM_MOUSEMOVE, kontrol memutuskan apakah penunjuk mouse berada di area batas alat. Jika ya, kontrol tooltip akan mengatur timer. Pada akhir interval penghentian, kontrol tooltip memeriksa posisi penunjuk untuk melihat apakah penunjuk telah bergerak. Jika belum, kontrol tooltip mengambil teks untuk alat dan menampilkan tooltip. Kontrol tipsalat terus menampilkan jendela hingga menerima pesan tombol atas atau tombol-bawah yang disampaikan atau hingga pesan WM_MOUSEMOVE menunjukkan bahwa penunjuk telah bergerak di luar persegi panjang pembatas alat.

Kontrol tooltip sebenarnya memiliki tiga durasi kedaluwarsa yang terkait dengannya. Durasi awal adalah waktu penunjuk mouse harus tetap diam dalam persegi panjang pembatas alat bantu sebelum jendela tooltip ditampilkan. Durasi reshow adalah jangka waktu tunda sebelum jendela tooltip berikutnya ditampilkan saat penunjuk pindah dari satu alat ke alat lain. Durasi pop-up adalah durasi waktu jendela tooltip tetap ditampilkan sebelum disembunyikan. Jadi, jika penunjuk tetap diam di dalam kotak pembatas setelah jendela tooltip ditampilkan, jendela tooltip secara otomatis disembunyikan setelah durasi pop-up berakhir. Anda dapat menyesuaikan semua durasi batas waktu dengan menggunakan TTM_SETDELAYTIME pesan.

Jika sebuah aplikasi menyertakan alat yang diimplementasikan sebagai area persegi panjang dan ukuran atau posisi kontrol berubah, aplikasi dapat menggunakan pesan TTM_NEWTOOLRECT untuk melaporkan perubahan ke kontrol tooltip. Aplikasi tidak perlu melaporkan perubahan ukuran dan posisi untuk alat yang diimplementasikan sebagai jendela karena kontrol tooltip menggunakan pegangan jendela alat untuk menentukan apakah pointer mouse berada di alat, bukan persegi panjang pembatas alat.

Saat tooltips akan ditampilkan, kontrol tooltips mengirimkan jendela pemilik kode notifikasi TTN_SHOW. Jendela pemilik menerima kode pemberitahuan TTN_POP ketika tooltip akan ditutup. Setiap kode pemberitahuan dikirim dalam konteks pesan WM_NOTIFY.

Pengujian Tabrakan

Pesan TTM_HITTEST memungkinkan Anda untuk mengambil informasi yang disimpan oleh kontrol tooltip mengenai alat yang berada pada titik tertentu. Pesan ini mencakup struktur TTHITTESTINFO yang berisi handle jendela, koordinat titik, dan alamat struktur TOOLINFO. Kontrol tooltip menentukan apakah alat tersebut mengambil posisi di titik tersebut dan, jika ya, mengisi TOOLINFO dengan informasi tentang alat tersebut.

Pemrosesan Pesan Default

Tabel berikut ini menjelaskan pesan-pesan yang ditangani oleh prosedur jendela untuk kontrol tooltip.