From ac4bb9210616343bdca0d2f7e1620e66d15f1c95 Mon Sep 17 00:00:00 2001
From: Terry Truong <terry06890@gmail.com>
Date: Sat, 21 Jan 2023 16:55:37 +1100
Subject: Adjust documentation for layout/search handling

---
 src/components/TimeLine.vue | 85 ++++++++++++++++++++++++++-------------------
 1 file changed, 49 insertions(+), 36 deletions(-)

(limited to 'src/components/TimeLine.vue')

diff --git a/src/components/TimeLine.vue b/src/components/TimeLine.vue
index 6c58ae3..9cfa5cf 100644
--- a/src/components/TimeLine.vue
+++ b/src/components/TimeLine.vue
@@ -497,40 +497,14 @@ const endIsLastVisible = computed(() => {
 	}
 });
 
-// ========== For displayed events ==========
+// ========== For event display ==========
 
-function dateToUnitOffset(date: HistDate){ // Assumes 'date' is >=firstDate and <=lastDate
-	// Find containing major tick
-	let tickIdx = firstIdx.value;
-	for (let i = tickIdx + 1; i < lastIdx.value; i++){
-		if (ticks.value[i].major){
-			if (!date.isEarlier(ticks.value[i].date)){
-				tickIdx = i;
-			} else {
-				break;
-			}
-		}
-	}
-
-	// Get offset within unit
-	const tick = ticks.value[tickIdx];
-	if (!hasMinorScale.value){
-		if (scale.value == DAY_SCALE){
-			return tick.offset;
-		} else {
-			const nextScale = SCALES[scaleIdx.value + 1];
-			return tick.offset + getUnitDiff(tick.date, date, nextScale) / getNumSubUnits(tick.date, scaleIdx.value);
-		}
-	} else {
-		return tick.offset + getUnitDiff(tick.date, date, minorScale.value) / getNumSubUnits(tick.date, scaleIdx.value);
-	}
-}
-
-const idToEvent: Ref<Map<number, HistEvent>> = ref(new Map()); // Maps visible event IDs to HistEvents
+// Represents candidate events for display, as a map from event IDs to HistEvents
+const idToEvent: Ref<Map<number, HistEvent>> = ref(new Map());
 
 function updateIdToEvent(){
 	let map: Map<number, HistEvent> = new Map();
-	// Find events to display
+	// Find events in date range
 	let itr = props.eventTree.lowerBound(new HistEvent(0, '', firstDate.value));
 	while (itr.data() != null){
 		let event = itr.data()!;
@@ -538,12 +512,16 @@ function updateIdToEvent(){
 		if (dateToUnit(event.start, scale.value) > dateToUnit(lastDate.value, scale.value)){
 			break;
 		}
+
+		// Check for disabled categories and events
 		if ((store.ctgs as {[ctg: string]: boolean})[event.ctg] == false){
 			continue;
 		}
 		if (store.reqImgs && event.imgId == null){
 			continue;
 		}
+
+		// Add to map
 		map.set(event.id, event);
 	}
 	idToEvent.value = map;
@@ -551,13 +529,20 @@ function updateIdToEvent(){
 
 watch(() => props.eventTree, updateIdToEvent);
 watch(ticks, updateIdToEvent);
+// Note: updateIdToEvent() is also called when jumping to a search result
+
+// Represents a layout of events in idToEvent, as a map from event IDs to x/y/w/h
+const idToPos: Ref<Map<number, [number, number, number, number]>> = ref(new Map());
 
-const idToPos: Ref<Map<number, [number, number, number, number]>> = ref(new Map()); // Maps event IDs to x/y/w/h
-const idsToSkipTransition: Ref<Set<number>> = ref(new Set()); // Used to prevent events moving across mainline
+// Holds IDs of events for which movement transitions should be skipped (for preventing movement across mainline)
+const idsToSkipTransition: Ref<Set<number>> = ref(new Set());
 
 type LineCoords = [number, number, number, number]; // x, y, length, angle
-const eventLines: Ref<Map<number, LineCoords>> = ref(new Map()); // Maps event ID to event line data
 
+// Represents lines from events to mainline, as a map from event IDs to LineCoords
+const eventLines: Ref<Map<number, LineCoords>> = ref(new Map());
+
+// Computes a layout for events in idToEvent
 function getEventLayout(): Map<number, [number, number, number, number]> {
 	let map: Map<number, [number, number, number, number]> = new Map();
 	if (!mounted.value){
@@ -743,7 +728,8 @@ function getEventLayout(): Map<number, [number, number, number, number]> {
 	return map;
 }
 
-// Updates idToPos and eventLines
+// Calls getEventLayout() and updates idToPos and eventLines
+	// Also notifies parent, which might get more events from server, adjust eventTree, and trigger relayout
 function updateLayout(){
 	let map = getEventLayout();
 
@@ -826,6 +812,33 @@ watch(idToEvent, updateLayout);
 watch(width, updateLayout);
 watch(height, updateLayout);
 
+function dateToUnitOffset(date: HistDate){ // Assumes 'date' is >=firstDate and <=lastDate
+	// Find containing major tick
+	let tickIdx = firstIdx.value;
+	for (let i = tickIdx + 1; i < lastIdx.value; i++){
+		if (ticks.value[i].major){
+			if (!date.isEarlier(ticks.value[i].date)){
+				tickIdx = i;
+			} else {
+				break;
+			}
+		}
+	}
+
+	// Get offset within unit
+	const tick = ticks.value[tickIdx];
+	if (!hasMinorScale.value){
+		if (scale.value == DAY_SCALE){
+			return tick.offset;
+		} else {
+			const nextScale = SCALES[scaleIdx.value + 1];
+			return tick.offset + getUnitDiff(tick.date, date, nextScale) / getNumSubUnits(tick.date, scaleIdx.value);
+		}
+	} else {
+		return tick.offset + getUnitDiff(tick.date, date, minorScale.value) / getNumSubUnits(tick.date, scaleIdx.value);
+	}
+}
+
 // ========== For event density indicators ==========
 
 // Maps tick index to event count
@@ -1311,7 +1324,7 @@ watch(endDate, onStateChg);
 // ========== For jumping to search result ==========
 
 const searchEvent = ref(null as null | HistEvent); // Holds most recent search result
-let pendingSearch = false;
+let pendingSearch = false; // Used to prevent removal of search highlighting until after a search jump has completed
 
 watch(() => props.searchTarget, () => {
 	const event = props.searchTarget[0];
@@ -1352,7 +1365,7 @@ watch(() => props.searchTarget, () => {
 		// Jump to range
 		if (startDate.value.equals(targetStart) && endDate.value.equals(targetEnd) && scale.value == tempScale){
 			updateIdToEvent();
-		} else {
+		} else { // Trigger bound change and relayout
 			startDate.value = targetStart;
 			endDate.value = targetEnd;
 			scaleIdx.value = SCALES.findIndex((s: number) => s == tempScale);
-- 
cgit v1.2.3

