will/thechart
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Consolidate documentation into a single comprehensive guide

Browse Source 
- Created `CONSOLIDATED_DOCS.md` to serve as the primary documentation source, integrating user and developer guides, API references, and troubleshooting sections.
- Updated `README.md` to reference the new consolidated documentation.
- Preserved existing documentation files for backward compatibility, including `USER_GUIDE.md`, `DEVELOPER_GUIDE.md`, and others.
- Enhanced navigation structure in `docs/README.md` to facilitate easier access to documentation.
- Implemented UI flickering fixes, including auto-save optimizations, debounced filter updates, and efficient tree updates to improve user experience.
- Added verification script `verify_docs_consolidation.py` to ensure successful documentation consolidation and integrity.
This commit is contained in:
William Valentin
2025-08-06 15:02:49 -07:00
parent 55682a1d53
commit 8fc87788f9
10 changed files with 1190 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main.py
+66 -45
View File
@@ -667,8 +667,8 @@ Use Ctrl+S to save entries and Ctrl+Q to quit."""
def _auto_save_callback(self) -> None:
"""Callback function for auto-save operations."""
try:
# Force refresh of data display to ensure consistency
self.refresh_data_display()
# Only save data, don't refresh the display during auto-save
# This prevents flickering during user interaction
logger.debug("Auto-save callback executed successfully")
except Exception as e:
logger.error(f"Auto-save callback failed: {e}")
@@ -862,13 +862,9 @@ Use Ctrl+S to save entries and Ctrl+Q to quit."""
logger.debug("Loading data from CSV.")
try:
# Clear existing data in the treeview efficiently
children = self.tree.get_children()
if children:
self.tree.delete(*children)
# Load data from the CSV file
# Load data from the CSV file once
df: pd.DataFrame = self.data_manager.load_data()
original_df = df.copy() # Keep a copy for graph updates
# Apply filters if requested and filters are active
if apply_filters and self.data_filter.get_filter_summary()["has_filters"]:
@@ -877,48 +873,14 @@ Use Ctrl+S to save entries and Ctrl+Q to quit."""
else:
self.current_filtered_data = None
# Update the treeview with the data
if not df.empty:
# Build display columns dynamically
# (exclude dose columns for table view)
display_columns = ["date"]
# Add pathology columns
for pathology_key in self.pathology_manager.get_pathology_keys():
display_columns.append(pathology_key)
# Add medicine columns (without dose columns)
for medicine_key in self.medicine_manager.get_medicine_keys():
display_columns.append(medicine_key)
display_columns.append("note")
# Filter to only the columns we want to display
if all(col in df.columns for col in display_columns):
display_df = df[display_columns]
else:
# Fallback - just use all columns
display_df = df
# Batch insert for better performance with alternating row colors
for index, row in display_df.iterrows():
# Add alternating row tags for better visibility
tag = "evenrow" if index % 2 == 0 else "oddrow"
self.tree.insert(
parent="", index="end", values=list(row), tags=(tag,)
)
logger.debug(f"Loaded {len(display_df)} entries into treeview.")
# Use efficient tree update to reduce flickering
self._update_tree_efficiently(df)
# Update the graph (always use unfiltered data for complete picture)
original_df = self.data_manager.load_data() if apply_filters else df
self.graph_manager.update_graph(original_df)
# Update status bar with file info
if apply_filters:
total_entries = len(self.data_manager.load_data())
else:
total_entries = len(df)
total_entries = len(original_df) if apply_filters else len(df)
displayed_entries = len(df)
if apply_filters and self.current_filtered_data is not None:
@@ -956,6 +918,65 @@ Use Ctrl+S to save entries and Ctrl+Q to quit."""
],
)
def _update_tree_efficiently(self, df: pd.DataFrame) -> None:
"""Update tree view efficiently to reduce flickering."""
# Store current scroll position
import contextlib
current_scroll_top = 0
with contextlib.suppress(tk.TclError, IndexError):
current_scroll_top = self.tree.yview()[0]
# Use update_idletasks to batch operations and reduce flickering
try:
# Clear existing data efficiently
children = self.tree.get_children()
if children:
self.tree.delete(*children)
# Update the treeview with the data
if not df.empty:
# Build display columns dynamically
# (exclude dose columns for table view)
display_columns = ["date"]
# Add pathology columns
for pathology_key in self.pathology_manager.get_pathology_keys():
display_columns.append(pathology_key)
# Add medicine columns (without dose columns)
for medicine_key in self.medicine_manager.get_medicine_keys():
display_columns.append(medicine_key)
display_columns.append("note")
# Filter to only the columns we want to display
if all(col in df.columns for col in display_columns):
display_df = df[display_columns]
else:
# Fallback - just use all columns
display_df = df
# Batch insert for better performance with alternating row colors
for index, row in display_df.iterrows():
# Add alternating row tags for better visibility
tag = "evenrow" if index % 2 == 0 else "oddrow"
self.tree.insert(
parent="", index="end", values=list(row), tags=(tag,)
)
logger.debug(f"Loaded {len(display_df)} entries into treeview.")
# Process pending events to update display
self.root.update_idletasks()
# Restore scroll position
with contextlib.suppress(tk.TclError, IndexError):
if current_scroll_top > 0:
self.tree.yview_moveto(current_scroll_top)
except Exception as e:
logger.error(f"Error updating tree efficiently: {e}")
if __name__ == "__main__":
root: tk.Tk = tk.Tk()
src/search_filter_ui.py
+38 -14
View File
@@ -43,6 +43,10 @@ class SearchFilterWidget:
self.search_history = SearchHistory()
# Debouncing mechanism to reduce filter update frequency
self._update_timer = None
self._debounce_delay = 300 # milliseconds
# UI state variables
self.search_var = tk.StringVar()
self.start_date_var = tk.StringVar()
@@ -216,24 +220,48 @@ class SearchFilterWidget:
self.status_label.pack(side="right")
def _bind_events(self) -> None:
"""Bind events for real-time updates."""
# Update filters when search changes
self.search_var.trace("w", lambda *args: self._on_search_change())
"""Bind events for real-time updates with debouncing."""
# Update filters when search changes (debounced)
self.search_var.trace("w", lambda *args: self._debounced_update())
# Update filters when date range changes
self.start_date_var.trace("w", lambda *args: self._on_date_change())
self.end_date_var.trace("w", lambda *args: self._on_date_change())
# Update filters when date range changes (debounced)
self.start_date_var.trace("w", lambda *args: self._debounced_update())
self.end_date_var.trace("w", lambda *args: self._debounced_update())
# Update filters when medicine selections change
# Update filters when medicine selections change (debounced)
for var in self.medicine_vars.values():
var.trace("w", lambda *args: self._on_medicine_change())
var.trace("w", lambda *args: self._debounced_update())
# Update filters when pathology ranges change
# Update filters when pathology ranges change (debounced)
pathology_vars = list(self.pathology_min_vars.values()) + list(
self.pathology_max_vars.values()
)
for var in pathology_vars:
var.trace("w", lambda *args: self._on_pathology_change())
var.trace("w", lambda *args: self._debounced_update())
def _debounced_update(self) -> None:
"""Update filters with debouncing to prevent excessive calls."""
import contextlib
# Cancel any pending update
if self._update_timer:
with contextlib.suppress(tk.TclError):
self.parent.after_cancel(self._update_timer)
# Schedule a new update
self._update_timer = self.parent.after(
self._debounce_delay, self._execute_filter_update
)
def _execute_filter_update(self) -> None:
"""Execute the actual filter update."""
self._update_timer = None
self._on_search_change()
self._on_date_change()
self._on_medicine_change()
self._on_pathology_change()
# Only call the update callback once after all filters are applied
self.update_callback()
def _on_search_change(self) -> None:
"""Handle search term changes."""
@@ -244,7 +272,6 @@ class SearchFilterWidget:
self.search_history.add_search(search_term)
self._update_status()
self.update_callback()
def _on_date_change(self) -> None:
"""Handle date range changes."""
@@ -253,7 +280,6 @@ class SearchFilterWidget:
self.data_filter.set_date_range_filter(start_date, end_date)
self._update_status()
self.update_callback()
def _on_medicine_change(self) -> None:
"""Handle medicine filter changes."""
@@ -268,7 +294,6 @@ class SearchFilterWidget:
self.data_filter.set_medicine_filter(medicine_key, False)
self._update_status()
self.update_callback()
def _on_pathology_change(self) -> None:
"""Handle pathology filter changes."""
@@ -296,7 +321,6 @@ class SearchFilterWidget:
)
self._update_status()
self.update_callback()
def _apply_filters(self) -> None:
"""Manually apply all current filter settings."""
src/ui_manager.py
+40 -2
View File
@@ -288,9 +288,16 @@ class UIManager:
table_frame, columns=columns, show="headings", style="Modern.Treeview"
)
# Configure treeview selection behavior
# Configure treeview for optimal scrolling performance
tree.configure(selectmode="browse") # Single selection mode
# Disable some visual effects that can cause flickering during scroll
import contextlib
with contextlib.suppress(tk.TclError):
# These settings help reduce redraws during scrolling
tree.configure(displaycolumns=columns)
# Configure row tags for alternating colors
theme_colors = self.theme_manager.get_theme_colors()
tree.tag_configure("evenrow", background=theme_colors["bg"])
@@ -321,11 +328,14 @@ class UIManager:
tree.pack(side="left", fill="both", expand=True)
# Add scrollbar
# Add scrollbar with optimized scroll handling
scrollbar = ttk.Scrollbar(table_frame, orient="vertical", command=tree.yview)
tree.configure(yscrollcommand=scrollbar.set)
scrollbar.pack(side="right", fill="y")
# Optimize tree scrolling performance
self._optimize_tree_scrolling(tree)
return {"frame": table_frame, "tree": tree}
def create_graph_frame(self, parent_frame: ttk.Frame) -> ttk.LabelFrame:
@@ -1529,3 +1539,31 @@ class UIManager:
except tk.TclError:
# Handle potential errors when accessing children
pass
def _optimize_tree_scrolling(self, tree: ttk.Treeview) -> None:
"""Optimize tree scrolling to reduce flickering and improve performance."""
# Store scroll state to prevent unnecessary updates
last_scroll_position = [0.0, 1.0]
def optimized_yscrollcommand(first, last):
"""Optimized scroll command to reduce update frequency."""
nonlocal last_scroll_position
# Only update if position significantly changed
first_f, last_f = float(first), float(last)
if (
abs(first_f - last_scroll_position[0]) > 0.001
or abs(last_f - last_scroll_position[1]) > 0.001
):
last_scroll_position = [first_f, last_f]
# Update scrollbar position
scrollbar = None
for child in tree.master.winfo_children():
if isinstance(child, ttk.Scrollbar):
scrollbar = child
break
if scrollbar:
scrollbar.set(first, last)
# Apply the optimized scroll command
tree.configure(yscrollcommand=optimized_yscrollcommand)