agent-command-tab 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. agent_command_tab/__init__.py +4 -0
  2. agent_command_tab/agent_adapters/__init__.py +48 -0
  3. agent_command_tab/agent_adapters/base.py +162 -0
  4. agent_command_tab/agent_adapters/claude_code.py +120 -0
  5. agent_command_tab/agent_adapters/codex.py +102 -0
  6. agent_command_tab/agent_adapters/generic.py +22 -0
  7. agent_command_tab/agent_process_tree.py +557 -0
  8. agent_command_tab/agent_session_pausing.py +254 -0
  9. agent_command_tab/app_controller.py +947 -0
  10. agent_command_tab/claude_code_transcript_records.py +75 -0
  11. agent_command_tab/command_line.py +187 -0
  12. agent_command_tab/context_window_usage.py +230 -0
  13. agent_command_tab/dashboard_core_api.py +57 -0
  14. agent_command_tab/docked_window_frames_store.py +60 -0
  15. agent_command_tab/global_shortcut_key_filter.py +167 -0
  16. agent_command_tab/hook_event_forwarder.py +116 -0
  17. agent_command_tab/hook_event_tracking.py +129 -0
  18. agent_command_tab/hook_states_store.py +60 -0
  19. agent_command_tab/hooks_installer.py +300 -0
  20. agent_command_tab/installed_copy_paths.py +41 -0
  21. agent_command_tab/iterm2_actions.py +325 -0
  22. agent_command_tab/iterm2_connection_thread.py +2299 -0
  23. agent_command_tab/iterm2_snapshot_builder.py +403 -0
  24. agent_command_tab/list_sorting.py +117 -0
  25. agent_command_tab/messages_between_agent_sessions.py +78 -0
  26. agent_command_tab/monitor_assignment.py +109 -0
  27. agent_command_tab/pause_records_store.py +61 -0
  28. agent_command_tab/screen_readings.py +108 -0
  29. agent_command_tab/session_preview_computation.py +228 -0
  30. agent_command_tab/session_status_computation.py +235 -0
  31. agent_command_tab/settings_store.py +292 -0
  32. agent_command_tab/snapshot_data_classes.py +145 -0
  33. agent_command_tab/start_with_iterm2.py +138 -0
  34. agent_command_tab/tab_order_computation.py +26 -0
  35. agent_command_tab/user_interface/__init__.py +1 -0
  36. agent_command_tab/user_interface/agent_session_outline_view.py +2120 -0
  37. agent_command_tab/user_interface/agent_tool_icons.py +124 -0
  38. agent_command_tab/user_interface/app_icon.py +75 -0
  39. agent_command_tab/user_interface/control_helpers.py +38 -0
  40. agent_command_tab/user_interface/list_window.py +116 -0
  41. agent_command_tab/user_interface/menu_bar_status_item.py +193 -0
  42. agent_command_tab/user_interface/named_colors.py +58 -0
  43. agent_command_tab/user_interface/pointing_hand_button.py +42 -0
  44. agent_command_tab/user_interface/popover_container.py +461 -0
  45. agent_command_tab/user_interface/row_text_rendering.py +342 -0
  46. agent_command_tab/user_interface/screen_layout.py +91 -0
  47. agent_command_tab/user_interface/settings_window.py +530 -0
  48. agent_command_tab/user_interface/sidebar_panel.py +486 -0
  49. agent_command_tab/user_interface/sidebar_placement.py +105 -0
  50. agent_command_tab/user_interface/talk_to_each_other_alert.py +130 -0
  51. agent_command_tab/window_list_ordering.py +44 -0
  52. agent_command_tab-0.1.0.dist-info/METADATA +85 -0
  53. agent_command_tab-0.1.0.dist-info/RECORD +57 -0
  54. agent_command_tab-0.1.0.dist-info/WHEEL +5 -0
  55. agent_command_tab-0.1.0.dist-info/entry_points.txt +2 -0
  56. agent_command_tab-0.1.0.dist-info/licenses/LICENSE +21 -0
  57. agent_command_tab-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,486 @@
1
+ """The sidebar at the screen edge.
2
+
3
+ A non-activating panel that floats above windows on every desktop, including full-screen
4
+ ones, and takes keyboard focus only for typing (a rename). Three modes (settings_store.SIDEBAR_MODES):
5
+ - auto_hide: slides in when the pointer touches the chosen edge and slides out half a second
6
+ after the pointer leaves, unless a rename, drag or menu is open, or at once on a click in
7
+ another app;
8
+ - floating: always visible, over the windows beneath it;
9
+ - docked: always visible, and the core keeps iTerm2 windows on that monitor out of its area
10
+ (macOS lets no app reserve screen space for other apps, so other apps' windows can still
11
+ reach under it).
12
+ Its width can be dragged at its inner edge, where the pointer turns into left-right arrows. A
13
+ borderless window gets no resizing edges from macOS, so a thin strip of our own does this.
14
+
15
+ No window sits on the edge while the sidebar is hidden: a global mouse-moved monitor (which
16
+ needs no Accessibility permission and only watches) tests the pointer position.
17
+ """
18
+
19
+ import ctypes
20
+ import time
21
+
22
+ import objc
23
+ from AppKit import (NSAnimationContext, NSBackingStoreBuffered, NSCursor, NSEvent, NSEventMaskLeftMouseDown,
24
+ NSEventMaskMouseMoved, NSEventMaskOtherMouseDown, NSEventMaskRightMouseDown, NSMakeRect, NSPanel, NSStatusWindowLevel, NSTrackingActiveAlways, NSTrackingArea,
25
+ NSTrackingCursorUpdate, NSTrackingInVisibleRect, NSTrackingMouseEnteredAndExited,
26
+ NSTrackingMouseMoved, NSView, NSViewHeightSizable, NSViewMaxXMargin, NSViewMinXMargin,
27
+ NSViewWidthSizable, NSVisualEffectBlendingModeBehindWindow, NSVisualEffectMaterialSidebar,
28
+ NSVisualEffectStateActive, NSVisualEffectView, NSWindowCollectionBehaviorCanJoinAllSpaces,
29
+ NSWindowCollectionBehaviorFullScreenAuxiliary, NSWindowCollectionBehaviorIgnoresCycle,
30
+ NSWindowCollectionBehaviorStationary, NSWindowStyleMaskBorderless,
31
+ NSWindowStyleMaskNonactivatingPanel)
32
+ from Foundation import NSObject, NSTimer
33
+
34
+ from agent_command_tab.user_interface.agent_session_outline_view import AgentSessionListController
35
+ from agent_command_tab.user_interface.popover_container import ListPanelController
36
+ from agent_command_tab.user_interface.screen_layout import read_monitors_from_screens
37
+ from agent_command_tab.user_interface.sidebar_placement import (choose_sidebar_edge, compute_dragged_sidebar_width,
38
+ compute_sidebar_frame, pointer_is_at_edge)
39
+
40
+ SECONDS_BEFORE_HIDING = 0.5
41
+ # Slid in by the menu bar icon, its menu's "Show sidebar" or the global shortcut.
42
+ SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT = 5
43
+ SLIDE_ANIMATION_SECONDS = 0.15
44
+ SMALLEST_WIDTH = 200
45
+ LARGEST_WIDTH = 1200
46
+ WIDTH_DRAG_STRIP_THICKNESS = 6
47
+ CF_STRING_ENCODING_UTF8 = 0x08000100
48
+
49
+
50
+ def allow_pointer_changes_while_another_app_is_in_front():
51
+ """Lets the dashboard change the pointer while another app is the active one; returns whether that worked.
52
+
53
+ macOS ignores pointer changes from an app that isn't active, and the sidebar never makes the
54
+ dashboard active, so the inner edge's left-right arrows would never show. This turns on the
55
+ window server's undocumented "SetsCursorInBackground" setting, as other menu bar utilities
56
+ do. Should a macOS version drop it, the edge still drags, only without the arrows.
57
+ """
58
+ try:
59
+ core_foundation = ctypes.CDLL("/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation")
60
+ core_graphics = ctypes.CDLL("/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics")
61
+ core_foundation.CFStringCreateWithCString.restype = ctypes.c_void_p
62
+ core_foundation.CFStringCreateWithCString.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint32]
63
+ core_graphics._CGSDefaultConnection.restype = ctypes.c_int
64
+ core_graphics.CGSSetConnectionProperty.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_void_p, ctypes.c_void_p]
65
+ core_graphics.CGSSetConnectionProperty.restype = ctypes.c_int
66
+ setting_name = core_foundation.CFStringCreateWithCString(None, b"SetsCursorInBackground", CF_STRING_ENCODING_UTF8)
67
+ connection = core_graphics._CGSDefaultConnection()
68
+ return core_graphics.CGSSetConnectionProperty(
69
+ connection, connection, setting_name, ctypes.c_void_p.in_dll(core_foundation, "kCFBooleanTrue")) == 0
70
+ except (OSError, AttributeError, ValueError):
71
+ return False
72
+
73
+
74
+ class SidebarWindow(NSPanel):
75
+ """A borderless, non-activating panel that may become key, so a rename field can take typing."""
76
+
77
+ def canBecomeKeyWindow(self):
78
+ return True
79
+
80
+ def canBecomeMainWindow(self):
81
+ return False
82
+
83
+
84
+ class SidebarWidthDragStripView(NSView):
85
+ """A thin strip along the sidebar's inner edge: shows the left-right arrows pointer and drags the width.
86
+
87
+ Its tracking area stays active while another app is in front, since the sidebar never
88
+ activates the dashboard (allow_pointer_changes_while_another_app_is_in_front lets it set the
89
+ pointer then). Pointer positions are read in screen coordinates, because the strip moves with
90
+ the window while the width changes.
91
+ """
92
+
93
+ def initWithFrame_controller_(self, frame, controller):
94
+ self = objc.super(SidebarWidthDragStripView, self).initWithFrame_(frame)
95
+ if self is None:
96
+ return None
97
+ self.controller = controller
98
+ self.addTrackingArea_(NSTrackingArea.alloc().initWithRect_options_owner_userInfo_(
99
+ frame, NSTrackingMouseEnteredAndExited | NSTrackingMouseMoved | NSTrackingCursorUpdate
100
+ | NSTrackingActiveAlways | NSTrackingInVisibleRect, self, None))
101
+ return self
102
+
103
+ def acceptsFirstMouse_(self, event):
104
+ return True # the first click starts a drag even though the dashboard isn't the active app
105
+
106
+ def cursorUpdate_(self, event):
107
+ NSCursor.resizeLeftRightCursor().set()
108
+
109
+ def mouseEntered_(self, event):
110
+ NSCursor.resizeLeftRightCursor().set()
111
+
112
+ def mouseMoved_(self, event):
113
+ NSCursor.resizeLeftRightCursor().set()
114
+
115
+ def mouseExited_(self, event):
116
+ if not self.controller.width_drag_is_in_progress():
117
+ NSCursor.arrowCursor().set()
118
+
119
+ def mouseDown_(self, event):
120
+ self.controller.start_width_drag(NSEvent.mouseLocation().x)
121
+
122
+ def mouseDragged_(self, event):
123
+ NSCursor.resizeLeftRightCursor().set()
124
+ self.controller.continue_width_drag(NSEvent.mouseLocation().x)
125
+
126
+ def mouseUp_(self, event):
127
+ self.controller.finish_width_drag()
128
+
129
+
130
+ class SidebarController(NSObject):
131
+ """Owns the sidebar window, its own list controller, and the edge tracking.
132
+
133
+ The owner is the app controller (see AgentSessionListController for the methods it has);
134
+ the sidebar also calls its sidebar_width_changed(width) after the user drags the width, and
135
+ reserve_screen_area(frame or None) whenever the docked area starts, moves or ends.
136
+ """
137
+
138
+ def initWithOwner_(self, owner):
139
+ self = objc.super(SidebarController, self).init()
140
+ if self is None:
141
+ return None
142
+ self.owner = owner
143
+ self.settings = None
144
+ self.placement = None
145
+ self.screens = []
146
+ self.is_shown = False
147
+ self.hide_timer = None
148
+ self.keep_shown_until = 0 # set by show_for_a_few_seconds
149
+ self.shown_from_the_menu = False # out because of show_for_a_few_seconds (until it next hides)
150
+ self.is_kept_hidden = False # hidden by the menu's Show popup or Show window (hide_until_shown_again)
151
+ self.mouse_monitors = []
152
+ self.click_monitor = None # while a sidebar that hides by itself is in (watch_for_clicks_in_other_apps)
153
+ self.width_drag_start = None # (pointer x, width) while the inner edge is dragged
154
+ self.list_controller = AgentSessionListController.alloc().initWithOwner_(owner)
155
+ self.list_controller.width_is_set_by_the_user = True
156
+ self.list_panel_controller = ListPanelController.alloc().initWithListController_(self.list_controller)
157
+ self.window = self.build_window()
158
+ allow_pointer_changes_while_another_app_is_in_front() # for the width strip's left-right arrows
159
+ return self
160
+
161
+ @objc.python_method
162
+ def build_window(self):
163
+ window = SidebarWindow.alloc().initWithContentRect_styleMask_backing_defer_(
164
+ NSMakeRect(0, 0, 320, 600), NSWindowStyleMaskBorderless | NSWindowStyleMaskNonactivatingPanel,
165
+ NSBackingStoreBuffered, False)
166
+ window.setFloatingPanel_(True) # before setLevel_: it resets the level to the floating level
167
+ window.setLevel_(NSStatusWindowLevel)
168
+ window.setCollectionBehavior_(NSWindowCollectionBehaviorCanJoinAllSpaces | NSWindowCollectionBehaviorStationary
169
+ | NSWindowCollectionBehaviorFullScreenAuxiliary | NSWindowCollectionBehaviorIgnoresCycle)
170
+ window.setHidesOnDeactivate_(False)
171
+ window.setAllowsToolTipsWhenApplicationIsInactive_(True) # the sidebar never makes the app active
172
+ window.setBecomesKeyOnlyIfNeeded_(True) # clicks on rows don't take keyboard focus
173
+ window.setDelegate_(self) # windowDidResignKey_
174
+ window.setHasShadow_(True)
175
+ background_view = NSVisualEffectView.alloc().initWithFrame_(NSMakeRect(0, 0, 320, 600))
176
+ background_view.setMaterial_(NSVisualEffectMaterialSidebar)
177
+ background_view.setBlendingMode_(NSVisualEffectBlendingModeBehindWindow)
178
+ background_view.setState_(NSVisualEffectStateActive)
179
+ panel_view = self.list_panel_controller.view()
180
+ panel_view.setFrame_(background_view.bounds())
181
+ panel_view.setAutoresizingMask_(NSViewWidthSizable | NSViewHeightSizable)
182
+ background_view.addSubview_(panel_view)
183
+ # Added last so it lies above the list; update_placement moves it to the inner edge.
184
+ self.width_drag_strip = SidebarWidthDragStripView.alloc().initWithFrame_controller_(
185
+ NSMakeRect(0, 0, WIDTH_DRAG_STRIP_THICKNESS, 600), self)
186
+ background_view.addSubview_(self.width_drag_strip)
187
+ window.setContentView_(background_view)
188
+ # The list's own pointer areas reset the strip's left-right arrows to the plain arrow
189
+ # right after the pointer enters the strip (a quick pointer often lands there only once).
190
+ window.disableCursorRects()
191
+ return window
192
+
193
+ def windowDidResignKey_(self, notification):
194
+ # A click in another window (iTerm2, say) ends an open rename without renaming, as closing
195
+ # the dropdown does; AppKit itself leaves the field open, and the list would stop updating.
196
+ self.list_controller.cancel_rename()
197
+
198
+ @objc.python_method
199
+ def move_width_drag_strip_to_inner_edge(self, edge):
200
+ """Puts the strip on the side facing the screen's middle: left for a sidebar on the right edge."""
201
+ bounds = self.window.contentView().bounds()
202
+ strip_x = 0 if edge == "right" else bounds.size.width - WIDTH_DRAG_STRIP_THICKNESS
203
+ self.width_drag_strip.setFrame_(NSMakeRect(strip_x, 0, WIDTH_DRAG_STRIP_THICKNESS, bounds.size.height))
204
+ self.width_drag_strip.setAutoresizingMask_(
205
+ NSViewHeightSizable | (NSViewMaxXMargin if edge == "right" else NSViewMinXMargin))
206
+
207
+ # ----- settings and screens -----
208
+
209
+ @objc.python_method
210
+ def apply_settings(self, settings):
211
+ """Shows, hides or moves the sidebar to match the settings (called on every settings
212
+ change). One kept hidden stays hidden unless Show as or the sidebar's mode changed."""
213
+ if self.settings is not None and (settings["show_as"], settings["sidebar_mode"]) != (
214
+ self.settings["show_as"], self.settings["sidebar_mode"]):
215
+ self.is_kept_hidden = False
216
+ self.settings = settings
217
+ self.update_placement()
218
+
219
+ @objc.python_method
220
+ def hide_until_shown_again(self):
221
+ """The menu bar icon's menu's Show popup or Show window: slides the sidebar out at once,
222
+ and keeps one set to stay visible out, a docked one giving its room back, through settings
223
+ changes (a sort order chosen in the window) until show_again, or until Show as or the
224
+ sidebar's mode changes (code review, 2026-10-28)."""
225
+ self.is_kept_hidden = True
226
+ self.hide_now()
227
+ self.owner.reserve_screen_area(None)
228
+
229
+ @objc.python_method
230
+ def show_again(self):
231
+ """Ends hide_until_shown_again: a sidebar set to stay visible slides in for good, a docked one taking its room again."""
232
+ self.is_kept_hidden = False
233
+ self.update_placement()
234
+
235
+ @objc.python_method
236
+ def screen_layout_changed(self):
237
+ """Re-checks the edge when monitors are connected, disconnected or rearranged."""
238
+ self.update_placement()
239
+
240
+ @objc.python_method
241
+ def update_placement(self):
242
+ if self.settings is None:
243
+ return
244
+ self.screens = read_monitors_from_screens()
245
+ self.placement = choose_sidebar_edge(self.settings["sidebar_edge"], self.screens)
246
+ if self.placement is None:
247
+ self.stop_tracking_the_pointer()
248
+ self.watch_for_clicks_in_other_apps(False)
249
+ self.cancel_hide_timer()
250
+ self.window.orderOut_(None)
251
+ self.is_shown = False
252
+ self.owner.reserve_screen_area(None)
253
+ return
254
+ visible_frame = self.screens[self.placement.screen_index]["visible_frame"]
255
+ self.move_width_drag_strip_to_inner_edge(self.placement.edge)
256
+ if self.settings["show_as"] != "sidebar":
257
+ # The list shows as a popup or a window: the sidebar is parked just past its edge, so
258
+ # the menu bar icon's menu's "Show sidebar" slides it in from there.
259
+ # While that keeps it out, a settings change (a width dragged meanwhile) leaves it out.
260
+ self.stop_tracking_the_pointer()
261
+ self.owner.reserve_screen_area(None)
262
+ self.set_shown(self.is_shown and self.shown_from_the_menu, animate=False)
263
+ if self.is_shown and self.hide_timer is None:
264
+ # Shown by a click or the shortcut while it auto-hid, its timer stopped while the pointer
265
+ # was on it: without pointer tracking, only a hide check slides it out (code review, 2026-10-28).
266
+ self.check_whether_to_hide_in(SECONDS_BEFORE_HIDING)
267
+ return
268
+ if self.settings["sidebar_mode"] == "auto_hide":
269
+ self.start_tracking_the_pointer()
270
+ # Keep the current visibility: a settings change (for example a width just dragged
271
+ # with the pointer still on the sidebar) mustn't make it vanish; the pointer decides.
272
+ self.set_shown(self.is_shown, animate=False)
273
+ elif self.is_kept_hidden: # hidden by the menu's Show popup or Show window: no room kept for it either
274
+ self.stop_tracking_the_pointer()
275
+ self.set_shown(False, animate=False)
276
+ self.owner.reserve_screen_area(None)
277
+ return
278
+ else:
279
+ self.stop_tracking_the_pointer()
280
+ self.cancel_hide_timer()
281
+ self.set_shown(True, animate=False)
282
+ # Shown for good now, so a later change of Show as hides it (code review, 2026-10-28).
283
+ self.shown_from_the_menu = False
284
+ # Docked: iTerm2 windows on this monitor are kept out of the sidebar's area.
285
+ if self.settings["sidebar_mode"] == "docked":
286
+ screen = self.screens[self.placement.screen_index]
287
+ self.owner.reserve_screen_area({
288
+ "frame": compute_sidebar_frame(visible_frame, screen["frame"], self.placement.edge,
289
+ self.settings["sidebar_width"], True),
290
+ "edge": self.placement.edge,
291
+ "monitor_visible_frame": visible_frame,
292
+ })
293
+ else:
294
+ self.owner.reserve_screen_area(None)
295
+
296
+ # ----- showing and hiding -----
297
+
298
+ @objc.python_method
299
+ def set_shown(self, is_shown, animate=True):
300
+ """Slides the sidebar in or out. Once out of sight it is ordered out too, which gives up
301
+ keyboard focus (after a rename) and lets its list skip redraws while hidden."""
302
+ screen = self.screens[self.placement.screen_index]
303
+ frame = compute_sidebar_frame(screen["visible_frame"], screen["frame"], self.placement.edge,
304
+ self.settings["sidebar_width"], is_shown)
305
+ was_on_screen = self.window.isVisible()
306
+ self.is_shown = is_shown
307
+ if not is_shown:
308
+ self.shown_from_the_menu = False
309
+ self.watch_for_clicks_in_other_apps(is_shown and self.hides_by_itself())
310
+ if is_shown:
311
+ self.window.orderFrontRegardless()
312
+ if not was_on_screen:
313
+ self.list_controller.prepare_to_appear() # the list skips redraws while hidden
314
+
315
+ def order_out_unless_shown_again():
316
+ if not self.is_shown:
317
+ self.window.orderOut_(None)
318
+
319
+ if animate:
320
+ def slide(context):
321
+ context.setDuration_(SLIDE_ANIMATION_SECONDS)
322
+ self.window.animator().setFrame_display_(NSMakeRect(*frame), True)
323
+ NSAnimationContext.runAnimationGroup_completionHandler_(slide, order_out_unless_shown_again)
324
+ else:
325
+ self.window.setFrame_display_(NSMakeRect(*frame), True)
326
+ order_out_unless_shown_again()
327
+
328
+ @objc.python_method
329
+ def show_for_a_few_seconds(self):
330
+ """A click on the menu bar icon or the global shortcut while the list shows as a sidebar,
331
+ and the menu bar icon's menu's "Show sidebar" (user requests, milestone 2 and 2026-10-28),
332
+ also while the list shows as a popup or a window: shows the sidebar for
333
+ SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT, then hides it once the pointer isn't on it. A
334
+ sidebar that is always shown stays as it is."""
335
+ if self.settings is None or self.placement is None or not self.hides_by_itself():
336
+ return
337
+ self.keep_shown_until = time.time() + SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT
338
+ self.set_shown(True)
339
+ self.shown_from_the_menu = True
340
+ self.check_whether_to_hide_in(SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT)
341
+
342
+ @objc.python_method
343
+ def hides_by_itself(self):
344
+ """Whether the sidebar slides out again after it slid in: it auto-hides, or the list shows
345
+ as a popup or a window (it slid in from the menu's "Show sidebar"), rather than always shown."""
346
+ return self.settings["show_as"] != "sidebar" or self.settings["sidebar_mode"] == "auto_hide"
347
+
348
+ @objc.python_method
349
+ def hide_now(self, animate=True):
350
+ """Slides the sidebar out at once, even with the pointer on it or while it was to stay a
351
+ few seconds: the global shortcut pressed again (user request, 2026-10-21) or a click in
352
+ another app (watch_for_clicks_in_other_apps). Without animate it vanishes at once (its top
353
+ bar dragged away into the list window)."""
354
+ self.cancel_hide_timer()
355
+ self.keep_shown_until = 0
356
+ self.list_controller.cancel_rename() # an open rename would keep the list from updating
357
+ self.set_shown(False, animate)
358
+
359
+ @objc.python_method
360
+ def watch_for_clicks_in_other_apps(self, is_watching):
361
+ """Adds or removes a global monitor (it only watches, needing no Accessibility permission)
362
+ of mouse button presses in other apps' windows, which slide out a sidebar that hides by
363
+ itself at once (user request, 2026-10-22), rather than after SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT or
364
+ once the pointer leaves. Clicks on the sidebar and the menu bar icon go to the dashboard,
365
+ so the monitor never sees them."""
366
+ if is_watching and self.click_monitor is None:
367
+ self.click_monitor = NSEvent.addGlobalMonitorForEventsMatchingMask_handler_(
368
+ NSEventMaskLeftMouseDown | NSEventMaskRightMouseDown | NSEventMaskOtherMouseDown, lambda event: self.hide_now())
369
+ elif not is_watching and self.click_monitor is not None:
370
+ NSEvent.removeMonitor_(self.click_monitor)
371
+ self.click_monitor = None
372
+
373
+ @objc.python_method
374
+ def something_belonging_to_the_sidebar_is_open(self):
375
+ """A rename, drag or right-click menu keeps the sidebar in place."""
376
+ return (self.list_controller.rename_in_progress or self.list_controller.drag_in_progress
377
+ or self.list_controller.menu_is_open or self.width_drag_is_in_progress())
378
+
379
+ # ----- pointer tracking -----
380
+
381
+ @objc.python_method
382
+ def start_tracking_the_pointer(self):
383
+ if self.mouse_monitors:
384
+ return
385
+ self.mouse_monitors.append(NSEvent.addGlobalMonitorForEventsMatchingMask_handler_(
386
+ NSEventMaskMouseMoved, lambda event: self.pointer_moved()))
387
+
388
+ def handle_local_event(event):
389
+ self.pointer_moved()
390
+ return event
391
+ self.mouse_monitors.append(NSEvent.addLocalMonitorForEventsMatchingMask_handler_(
392
+ NSEventMaskMouseMoved, handle_local_event))
393
+
394
+ @objc.python_method
395
+ def stop_tracking_the_pointer(self):
396
+ """Removes the mouse monitors; a pending hide check stays (it hides a sidebar shown from the menu)."""
397
+ for mouse_monitor in self.mouse_monitors:
398
+ NSEvent.removeMonitor_(mouse_monitor)
399
+ self.mouse_monitors = []
400
+
401
+ @objc.python_method
402
+ def pointer_moved(self):
403
+ if self.settings is None or self.settings["sidebar_mode"] != "auto_hide" or self.placement is None:
404
+ return
405
+ pointer = NSEvent.mouseLocation()
406
+ if not self.is_shown:
407
+ if pointer_is_at_edge((pointer.x, pointer.y), self.screens[self.placement.screen_index]["frame"],
408
+ self.placement.edge):
409
+ self.set_shown(True)
410
+ return
411
+ if self.pointer_is_over_sidebar():
412
+ self.cancel_hide_timer()
413
+ elif self.hide_timer is None:
414
+ self.check_whether_to_hide_in(SECONDS_BEFORE_HIDING)
415
+
416
+ @objc.python_method
417
+ def pointer_is_over_sidebar(self):
418
+ """Counts the strip between the sidebar and the screen's edge (a Dock on that side) as
419
+ part of the sidebar, since the pointer that showed it touched that edge."""
420
+ pointer = NSEvent.mouseLocation()
421
+ frame = self.window.frame()
422
+ screen_frame = self.screens[self.placement.screen_index]["frame"]
423
+ left, right = frame.origin.x - 1, frame.origin.x + frame.size.width + 1
424
+ if self.placement.edge == "right":
425
+ right = max(right, screen_frame[0] + screen_frame[2])
426
+ else:
427
+ left = min(left, screen_frame[0])
428
+ return left <= pointer.x <= right and frame.origin.y <= pointer.y <= frame.origin.y + frame.size.height
429
+
430
+ @objc.python_method
431
+ def check_whether_to_hide_in(self, seconds):
432
+ self.cancel_hide_timer()
433
+ self.hide_timer = NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(
434
+ seconds, self, "hideTimerFired:", None, False)
435
+
436
+ def hideTimerFired_(self, timer):
437
+ """Hides the sidebar unless a click or the shortcut showed it less than
438
+ SECONDS_SHOWN_AFTER_A_CLICK_OR_SHORTCUT ago, the pointer is on it, or anything of it is
439
+ open; otherwise checks again later (without pointer tracking, a sidebar shown from the
440
+ menu while the list shows as a popup or a window relies on this)."""
441
+ self.hide_timer = None
442
+ seconds_still_kept_shown = self.keep_shown_until - time.time()
443
+ if seconds_still_kept_shown > 0:
444
+ self.check_whether_to_hide_in(seconds_still_kept_shown)
445
+ elif self.something_belonging_to_the_sidebar_is_open() or self.pointer_is_over_sidebar():
446
+ self.check_whether_to_hide_in(SECONDS_BEFORE_HIDING)
447
+ else:
448
+ self.set_shown(False)
449
+
450
+ @objc.python_method
451
+ def cancel_hide_timer(self):
452
+ if self.hide_timer is not None:
453
+ self.hide_timer.invalidate()
454
+ self.hide_timer = None
455
+
456
+ # ----- width -----
457
+
458
+ @objc.python_method
459
+ def width_drag_is_in_progress(self):
460
+ return self.width_drag_start is not None
461
+
462
+ @objc.python_method
463
+ def start_width_drag(self, pointer_x):
464
+ if self.placement is not None and self.is_shown:
465
+ self.width_drag_start = (pointer_x, self.window.frame().size.width)
466
+
467
+ @objc.python_method
468
+ def continue_width_drag(self, pointer_x):
469
+ """Resizes the window under the pointer; the new width is saved when the drag ends."""
470
+ if self.width_drag_start is None:
471
+ return
472
+ pointer_x_at_start, width_at_start = self.width_drag_start
473
+ width = compute_dragged_sidebar_width(width_at_start, pointer_x_at_start, pointer_x, self.placement.edge,
474
+ SMALLEST_WIDTH, LARGEST_WIDTH)
475
+ screen = self.screens[self.placement.screen_index]
476
+ frame = compute_sidebar_frame(screen["visible_frame"], screen["frame"], self.placement.edge, width, True)
477
+ self.window.setFrame_display_(NSMakeRect(*frame), True)
478
+
479
+ @objc.python_method
480
+ def finish_width_drag(self):
481
+ if self.width_drag_start is None:
482
+ return
483
+ self.width_drag_start = None
484
+ width = round(self.window.frame().size.width)
485
+ if width != self.settings["sidebar_width"]:
486
+ self.owner.sidebar_width_changed(width) # saves it; a docked sidebar then reserves the new strip
@@ -0,0 +1,105 @@
1
+ """Where the sidebar goes. Pure functions, no AppKit.
2
+
3
+ Screens are dicts {"name": str, "frame": (x, y, width, height), "visible_frame": (...)} in
4
+ NSScreen's order, so the first one has the menu bar. Only outer edges are offered: an edge
5
+ that borders another monitor can't be touched, because the pointer slides past it.
6
+ """
7
+
8
+ import collections
9
+
10
+ SidebarPlacement = collections.namedtuple("SidebarPlacement", ["screen_index", "edge", "is_the_saved_choice"])
11
+ SidebarPlacement.__doc__ = "The chosen screen and edge, and whether that is what the settings asked for."
12
+
13
+ EDGE_DETECTION_THICKNESS = 2
14
+
15
+
16
+ def edges_touch(first_frame, second_frame, edge_of_first):
17
+ """Returns whether second_frame borders first_frame along first_frame's left or right edge."""
18
+ vertical_overlap = (min(first_frame[1] + first_frame[3], second_frame[1] + second_frame[3])
19
+ - max(first_frame[1], second_frame[1]))
20
+ if vertical_overlap <= 0:
21
+ return False
22
+ if edge_of_first == "right":
23
+ return abs((first_frame[0] + first_frame[2]) - second_frame[0]) < 1
24
+ return abs(first_frame[0] - (second_frame[0] + second_frame[2])) < 1
25
+
26
+
27
+ def find_outer_screen_edges(screen_frames):
28
+ """Returns [(screen index, "left" or "right")] for every edge that no other screen borders."""
29
+ outer_edges = []
30
+ for screen_index, screen_frame in enumerate(screen_frames):
31
+ for edge in ("right", "left"):
32
+ if not any(edges_touch(screen_frame, other_frame, edge)
33
+ for other_index, other_frame in enumerate(screen_frames) if other_index != screen_index):
34
+ outer_edges.append((screen_index, edge))
35
+ return outer_edges
36
+
37
+
38
+ def choose_sidebar_edge(saved_edge, screens):
39
+ """Returns the SidebarPlacement for the saved edge of the menu-bar monitor, or the nearest
40
+ sensible outer edge.
41
+
42
+ Order: the saved edge of the menu-bar monitor; its other edge; otherwise an outer edge on the
43
+ saved edge's side, on the monitor closest to the menu-bar monitor (for example the rightmost
44
+ monitor's right edge when three stand in a row with the menu bar on the middle one and
45
+ "right" saved).
46
+
47
+ Returns None when there are no screens.
48
+ """
49
+ if not screens:
50
+ return None
51
+ frames = [screen["frame"] for screen in screens]
52
+ outer_edges = set(find_outer_screen_edges(frames))
53
+ other_edge = "left" if saved_edge == "right" else "right"
54
+ if (0, saved_edge) in outer_edges:
55
+ return SidebarPlacement(0, saved_edge, True)
56
+ if (0, other_edge) in outer_edges:
57
+ return SidebarPlacement(0, other_edge, False)
58
+
59
+ def rank_outer_edge(screen_index_and_edge):
60
+ """The saved edge's side first, then the monitor closest to the menu-bar monitor."""
61
+ screen_index, edge = screen_index_and_edge
62
+ frame, menu_bar_frame = frames[screen_index], frames[0]
63
+ return (edge != saved_edge, abs((frame[0] + frame[2] / 2) - (menu_bar_frame[0] + menu_bar_frame[2] / 2)))
64
+
65
+ screen_index, edge = min(sorted(outer_edges), key=rank_outer_edge)
66
+ return SidebarPlacement(screen_index, edge, False)
67
+
68
+
69
+ def describe_sidebar_placement_fallback(saved_edge, screens):
70
+ """Returns a sentence for the settings window when the sidebar can't go on the saved edge
71
+ (it borders another monitor), else ""."""
72
+ placement = choose_sidebar_edge(saved_edge, screens)
73
+ if placement is None or placement.is_the_saved_choice:
74
+ return ""
75
+ return (f"The saved edge borders another monitor, so the sidebar is on the {placement.edge} edge "
76
+ f"of {screens[placement.screen_index]['name']}.")
77
+
78
+
79
+ def compute_sidebar_frame(visible_frame, screen_frame, edge, width, is_shown):
80
+ """Returns the sidebar's frame: along the edge of the screen's usable area when shown, and
81
+ just past the screen's full edge when hidden (past a Dock on that side too)."""
82
+ x, y, usable_width, height = visible_frame
83
+ if edge == "right":
84
+ sidebar_x = x + usable_width - width if is_shown else screen_frame[0] + screen_frame[2]
85
+ else:
86
+ sidebar_x = x if is_shown else screen_frame[0] - width
87
+ return (sidebar_x, y, width, height)
88
+
89
+
90
+ def compute_dragged_sidebar_width(width_at_start, pointer_x_at_start, pointer_x, edge, smallest_width, largest_width):
91
+ """Returns the sidebar width while its inner edge is dragged: a sidebar on the right edge grows
92
+ as the pointer moves left, one on the left edge as it moves right."""
93
+ pointer_movement = pointer_x_at_start - pointer_x if edge == "right" else pointer_x - pointer_x_at_start
94
+ return min(max(round(width_at_start + pointer_movement), smallest_width), largest_width)
95
+
96
+
97
+ def pointer_is_at_edge(pointer_location, screen_frame, edge):
98
+ """Returns whether the pointer touches the chosen edge of the screen (its full frame)."""
99
+ pointer_x, pointer_y = pointer_location
100
+ x, y, width, height = screen_frame
101
+ if not y <= pointer_y <= y + height:
102
+ return False
103
+ if edge == "right":
104
+ return pointer_x >= x + width - EDGE_DETECTION_THICKNESS
105
+ return pointer_x <= x + EDGE_DETECTION_THICKNESS - 1