Contracts & Loose Coupling
Folder Protocols/ menyimpan seluruh definisi kontrak (protocol) yang berfungsi sebagai antarmuka abstraksi. Penggunaan protocol sangat krusial dalam arsitektur Maktabah untuk mencegah ketergantungan yang kuat (tight coupling) antar-modul, khususnya komunikasi lintas layar (seperti dari Sidebar Annotations ke modul Reader).
AnnotationDelegate (Protocol)
Protocol yang mendefinisikan aksi saat sebuah anotasi dipilih dari antarmuka pengguna:
Penjelasan Parameter & Anotasi
@MainActor: Mengikat implementasi dari protocol ini agar dieksekusi pada Main Thread karena respons pemilihan anotasi memicu navigasi UI dan manipulasi tampilan secara langsung.AnyObject: Membatasi bahwa pengadopsi protocol ini hanyalah class (reference type). Hal ini memungkinkan penggunaan referensiweakpada penugasan delegasi untuk mencegah retain cycle (kebocoran memori).annotation: Annotation: Menyalurkan seluruh data model anotasi (termasuk Book ID, Content ID, dan NSRange) sehingga delegasi dapat menghitung pergeseran fokus ke teks yang bersangkutan.
Implementasi Navigasi (IbarotTextVC)
IbarotTextVC merupakan View Controller pembaca buku utama (berada di modul Reader/) yang mengimplementasikan AnnotationDelegate. Implementasi didelegasikan secara asinkron ke metode openAnnotation(_:):
extension IbarotTextVC: AnnotationDelegate {
func didSelect(annotation: Annotation) {
Task { [weak self] in
try? await self?.openAnnotation(annotation)
}
}
}
Metode openAnnotation(_:) pada IbarotTextVC menangani seluruh siklus hidup navigasi, validasi buku, pembatalan task restorasi yang tertunda (pendingRestoreTask), dan scrolling sorotan anotasi:
func openAnnotation(_ annotation: Annotation) async throws {
let bkId = annotation.bkId
let contentId = annotation.contentId
guard let book = LibraryDataManager.shared.getBook([bkId]).first else {
ReusableFunc.showAlert(
title: String(localized: .Library.bookNotFound(bkId)),
message: String(localized: .Library.bookMissingOnAnnotationClick)
)
return
}
pendingRestoreTask?.cancel()
pendingRestoreTask = nil
do {
if currentBook?.id != bkId {
try await displayBook(book, loadContent: false)
}
} catch {
ReusableFunc.showAlert(
title: DatabaseError.bookNotFound(bkId).localizedDescription,
message: DatabaseError.noConnection.localizedDescription
)
return
}
if contentId != viewModel.currentContentId {
handleDelegate(contentId)
}
await textDelegate?.highlightAndScrollToAnns(annotation)
}
Analisis Alur Pemanggilan
- Pengecekan Buku: Sistem memastikan bahwa arsip buku untuk anotasi tersebut (melalui
bkId) terpasang di perangkat. Apabila belum diunduh, pesan peringatan akan ditampilkan. - Pembatalan Tugas Restorasi Tertunda: Membatalkan
pendingRestoreTaskyang mungkin sedang berjalan dari siklus restorasi state sebelumnya guna menghindari konflik posisi. - Perpindahan Konteks (Context Switching): Menggunakan Swift Concurrency (
Task), sistem membandingkan buku yang sedang terbuka. Jika berbeda, fungsi memuat buku yang sesuai (displayBook). - Pemuatan Konten (
contentId): Memuat bagian / halaman menujucontentIdyang bersangkutan. - Scrolling & Highlighting: Menginstruksikan
textDelegate(Text View AppKit / UIKit) untuk menyorot teks secara visual dan menggulir (scroll) area pandang menuju lokasi anotasi.