Reader macOS Implementation (AppKit)
Implementasi layar pembaca Maktabah pada macOS dibangun secara native menggunakan hierarki murni AppKit tanpa lapisan SwiftUI. Hal ini bertujuan untuk mencapai performa optimal saat me-render puluhan ribu baris teks Arab berharakat secara instan tanpa hambatan visual.
Sumber kode:
- Controller:
Source/Features/Reader/macOS/IbarotTextVC.swift - Custom TextView:
Source/UI/macOS/TextView/IbarotTextView.swift
1. Arsitektur Komponen Visual (UI Hierarchy)
Hierarki tampilan pembaca AppKit dirancang terpisah antara pembungkus kontainer gulir (NSScrollView), kanvas perenderan teks kustom (IbarotTextView), serta subsistem tipografi teks bawaan macOS:
flowchart TD
V_SPLIT["ViewerSplitVC (Main Container)"] --> ITVC["IbarotTextVC (View Controller)"]
V_SPLIT --> TOC["SidebarVC (Table of Contents)"]
ITVC --> SV["NSScrollView (Scrolling & Insets)"]
SV --> ITV["IbarotTextView (Custom NSTextView)"]
ITV --> TS["NSTextStorage (Attributed String Buffer)"]
ITV --> LM["NSLayoutManager (Non-Contiguous Layout)"]
ITV --> TC["NSTextContainer (Page Geometry)"]
2. Peta Kontrol, Menu & Popover Interaktif
Seluruh fitur interaktif yang terhubung pada IbarotTextView dikelompokkan ke dalam beberapa kategori kontrol:
mindmap
root((IbarotTextView))
Menu Kontekstual Klik-Kanan
Palet Warna Cepat (AnnotationColorMenuView)
Ubah Tipe (Highlight vs Underline)
Salin Teks (Dengan / Tanpa Tashkil)
Pencarian Kontekstual (In-Book / Global)
Menu Berbagi (Share Sheet)
Navigasi & Paging
Bilah Geser (Slider Halaman)
Tombol Prev dan Next
Lompat Bab (Daftar Isi / TOC)
Panel Popover Mandiri
AnnotationEditorVC (Catatan & Tag)
BookInfoPopoverVC (Metadata & Tafsir)
Pengaturan Tampilan
Keluarga Font Arab
Ukuran Font Dinamis
Tema Latar Belakang
3. Alur Pemuatan Halaman (Page Loading Pipeline): Dari Aksi Navigasi ke TextView
Alur linier pemrosesan data ketika pengguna berpindah halaman hingga teks tampil di layar:
flowchart TD
NAV_EVENT["Aksi Navigasi (Next / Prev / Slider / TOC)"] --> RVM_CALL["ReaderViewModel.loadPage(contentId)"]
RVM_CALL --> CACHE_CHECK{"Cek BookPageCache?"}
CACHE_CHECK -->|Hit| GET_CACHE["Ambil BookContent dari LRU Cache"]
CACHE_CHECK -->|Miss| SQL_GET["BookConnection.getContent()"]
SQL_GET --> DECOMP["LZString Decompression"]
DECOMP --> SAVE_CACHE["Simpan ke BookPageCache"]
GET_CACHE --> RENDER["ArabicTextRenderer.render(content, font, harakatMode)"]
SAVE_CACHE --> RENDER
RENDER --> ON_READY["IbarotTextVC.onContentReady(attributedText)"]
ON_READY --> TEXT_STORAGE["IbarotTextView.textStorage.setAttributedString()"]
4. Siklus Hidup Sinkron & Restorasi Layout
Diagram status (State Diagram) berikut memperlihatkan perlunya eksekusi sinkron pada Main Thread untuk mencegah pergeseran posisi gulir (content jumping):
stateDiagram-v2
[*] --> Idle : Halaman Ditampilkan
Idle --> LoadingContent : Navigasi Dipicu
LoadingContent --> Rendering : Teks Decompress & Format
state SynchronousMainThreadExecution {
[*] --> MutasiTextStorage : setAttributedString()
MutasiTextStorage --> ForceLayout : layoutManager.ensureLayout()
ForceLayout --> RestoreScroll : restoreScrollPosition()
RestoreScroll --> [*]
}
Rendering --> SynchronousMainThreadExecution : onContentReady Dipanggil
SynchronousMainThreadExecution --> Idle : Tampilan Stabil (Tanpa Content Jump)
5. Bedah Komponen & Logika Antarmuka
A. Orkestrasi Sinkron dengan IbarotTextVC
IbarotTextVC mengontrol alur presentasi tanpa bergantung pada observer asinkron:
func bindViewModel() {
viewModel.onContentReady = { [weak self] attributedText in
guard let self = self else { return }
self.textView.textStorage?.setAttributedString(attributedText)
self.textView.layoutManager?.ensureLayout(for: self.textView.textContainer!)
self.restoreScrollPosition()
}
}
- Mencegah Content Jumping: Karena
textStoragediperbarui secara sinkron pada siklus RunLoop yang sama, posisi gulirNSScrollViewtidak terdistorsi saat berganti halaman.
B. IbarotTextView (Class) - Subclass NSTextView
Mengoptimalkan rendering teks Arab berukuran besar:
| Fitur / Modifikasi | Tujuan Teknis |
|---|---|
allowsNonContiguousLayout = true |
Optimasi Memori: Hanya menghitung glif dan baris yang berada dalam area viewport aktif. |
baseWritingDirection = .rightToLeft |
Memastikan pergerakan kursor dan seleksi teks berjalan alami dari kanan ke kiri (RTL). |
C. Pencegatan Event Klik & Anotasi (mouseDown)
IbarotTextView menangkap event klik untuk memeriksa apakah pengguna mengetuk anotasi yang sudah ada (apabila pengaturan UserDefaults.enableAnnotationClick aktif):
flowchart TD
CLICK["User Klik pada IbarotTextView (mouseDown)"] --> COORD["Konversi Titik: characterIndexForInsertion(at: point)"]
COORD --> CHECK{"Apakah Berada di Rentang Anotasi?"}
CHECK -->|"Ya (Ada Annotation ID)"| SHOW_POP["Tampilkan Popover AnnotationEditorVC"]
SHOW_POP --> SYNC_POP["Sajikan Editor Catatan & Warna Anotasi"]
CHECK -->|Tidak| SUPER_EVENT["super.mouseDown(with: event)"]
SUPER_EVENT --> SELECT_MODE["Mode Seleksi Teks Normal"]
override func mouseDown(with event: NSEvent) {
let point = self.convert(event.locationInWindow, from: nil)
let charIndex = self.characterIndexForInsertion(at: point)
if let annotationId = findAnnotation(at: charIndex) {
showAnnotationEditor(id: annotationId, at: point)
} else {
super.mouseDown(with: event)
}
}
D. Menu Kontekstual Lengkap (menu(for event:))
Ketika pengguna mengklik kanan pada teks atau melakukan seleksi:
- Palet Warna Cepat (
AnnotationColorMenuView): Menyajikan bulatan warna sorotan langsung di menu klik kanan tanpa harus membuka modal editor. - Toggle Underline & Highlight: Mengubah gaya penandaan antara garis bawah atau latar warna.
- Opsi Salin Teks:
- Copy with Tashkil: Menyalin teks lengkap beserta harakat.
- Copy without Tashkil: Menghapus tanda harakat secara instan melalui
ArabicTextRenderer.stripHarakat()sebelum dimasukkan ke clipboard. - Pencarian Kontekstual: Opsi mencari frasa yang diseleksi di dalam kitab aktif (In-Book Search) atau di seluruh katalog perpustakaan (Global FTS).
- Menu Penampilan Teks: Menyesuaikan ukuran font, famili font Arab (Traditional Arabic, Scheherazade, Amiri), dan tema latar belakang (Sepia, Dark Sepia, White, Black).
E. Navigasi Terisolasi, State Component & Perekaman Histori Bersyarat (IbarotTextVC)
IbarotTextVC menyediakan API navigasi asinkron tingkat tinggi yang aman dari race condition untuk membuka anotasi dan riwayat:
openAnnotation(_ annotation: Annotation) async throws: MembatalkanpendingRestoreTask, memastikan kitab terkait terbuka, berpindah kecontentId, dan menginstruksikan perender teks untuk menggulir serta menyorot anotasi.openHistory(book: BooksData, contentId: Int?) async throws: Membuka buku dan melompat ke posisi bacaan terakhir.- Proteksi Status Restorasi pada ReaderStateComponent: Pada metode
updateState(_:), perekaman koordinatstate.scrollPosition = scrollView.contentView.bounds.origindiproteksi dengan guardpendingRestoreTask == nil. Hal ini mencegah koordinat sementara yang belum tuntas (intermediate scroll position) tersimpan secara keliru ke dalamReaderStatesaat pemulihan posisi sedang berjalan. - Pemulihan Seleksi Outline Seketika: Saat beralih tab (
applyState), apabilalibraryVC?.dataVM.isSetupComplete == true, sistem langsung memanggillibraryVC?.dataVM.restoreSelection(byBookName: book.book)agar baris kitab aktif pada outline view segera tersorot tanpa jeda. - Perekaman Histori Bersyarat: Pembaruan seleksi buku ke
LibraryViewModelmembedakan antara aksi navigasi aktif dan pemuatan pratinjau:if viewModel.recordHistory { libraryVC?.dataVM.viewModel.handleBookSelection(book: book) } else { libraryVC?.dataVM.viewModel.selectedBookName = book.book } if libraryVC?.dataVM.isSetupComplete == true { libraryVC?.dataVM.restoreSelection(byBookName: book.book) }handleBookSelection(yang mengunggah riwayat ke CloudKit) hanya dipanggil jikarecordHistory == true, mencegah pencatatan histori palsu saat sekadar memulihkan state jendela.
F. Pencegahan Retain Cycle & Siklus Hidup Observer
Untuk mencegah kebocoran memori (memory leaks) pada controller tampilan:
- Tangkapan
[weak self]: Seluruh closureNotificationCenterdan KVO padaViewerSplitVC(pengamat tinggi baris, penampilan, warna latar, harakat, dan font),SidebarVC(pengamat tab bar dan jendela), sertaIbarotTextVCwajib menggunakan[weak self]. - Pembersihan Independen di
deinit: PadaViewerSplitVC, observer dihapus secara individual tanpa bergantung pada keberadaan seluruh token sekaligus:deinit { if let bgObserver { NotificationCenter.default.removeObserver(bgObserver) } if let fontObserver { NotificationCenter.default.removeObserver(fontObserver) } if let tasykilObserver { NotificationCenter.default.removeObserver(tasykilObserver) } if let lineHeightObservation { NotificationCenter.default.removeObserver(lineHeightObservation) } // ... } - Otomasi
NotificationToken:IbarotTextVCmemanfaatkan koleksiobserverTokens: [NotificationToken]yang secara otomatis mencabut registrasi observer dariNotificationCentersaat controller di-dealokasi.