Class: Charming::Controller

Inherits:
Object
  • Object
show all
Extended by:
ClassMethods
Includes:
CommandPalette, ComponentDispatching, Dispatching, FocusManagement, Rendering, SessionState, SidebarNavigation
Defined in:
lib/charming/controller.rb,
lib/charming/controller/focus.rb,
lib/charming/controller/rendering.rb,
lib/charming/controller/dispatching.rb,
lib/charming/controller/class_methods.rb,
lib/charming/controller/session_state.rb,
lib/charming/controller/command_palette.rb,
lib/charming/controller/focus_management.rb,
lib/charming/controller/sidebar_navigation.rb,
lib/charming/controller/component_dispatching.rb

Overview

Controller is the base class for all controller implementations in a Charming application. It provides the action dispatch pipeline, key/command/timer/task bindings, sidebar navigation, command palette management, and view rendering with layout composition.

Defined Under Namespace

Modules: ClassMethods, CommandPalette, ComponentDispatching, Dispatching, FocusManagement, Rendering, SessionState, SidebarNavigation Classes: Focus, TaskBinding, TimerBinding

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ClassMethods

auto_render, auto_render_action, command, command_bindings, focus_ring, focus_ring_slots, key, key_binding_scopes, key_bindings, layout, on_task, task_bindings, timer, timer_bindings

Methods included from CommandPalette

#close_command_palette, #command_palette, #command_palette_open?, #open_command_palette

Methods included from SidebarNavigation

#content_focused?, #current_route?, #focus_content, #focus_sidebar, #sidebar_focused?, #sidebar_index, #sidebar_routes

Methods included from FocusManagement

#focus, #focused?

Methods included from SessionState

#form, #mouse_targets, #register_mouse_targets, #run_task, #session, #state

Constructor Details

#initialize(application:, event: nil, params: {}, screen: nil, route: nil) ⇒ Controller

Initializes the controller with its parent application and optional event. Defaults to an 80x24 screen when no backend size is available.



24
25
26
27
28
29
30
31
 
# File 'lib/charming/controller.rb', line 24

def initialize(application:, event: nil, params: {}, screen: nil, route: nil)
  @application = application
  @event = event
  @params = params
  @screen = screen || Screen.new(width: 80, height: 24)
  @route = route
  @response = nil
end

Instance Attribute Details

#application ⇒ Object (readonly)

Returns the value of attribute application.



20
21
22
 
# File 'lib/charming/controller.rb', line 20

def application
  @application
end

#event ⇒ Object (readonly)

Returns the value of attribute event.



20
21
22
 
# File 'lib/charming/controller.rb', line 20

def event
  @event
end

#params ⇒ Object (readonly)

Returns the value of attribute params.



20
21
22
 
# File 'lib/charming/controller.rb', line 20

def params
  @params
end

#route ⇒ Object (readonly)

Returns the value of attribute route.



20
21
22
 
# File 'lib/charming/controller.rb', line 20

def route
  @route
end

#screen ⇒ Object (readonly)

Returns the value of attribute screen.



20
21
22
 
# File 'lib/charming/controller.rb', line 20

def screen
  @screen
end

Instance Method Details

#dispatch(action) ⇒ Object

Dispatches a named action on this controller (e.g. :show).



34
35
36
37
38
 
# File 'lib/charming/controller.rb', line 34

def dispatch(action)
  public_send(action)
  render_default_action if response.nil? && auto_render_after?(action)
  response || render("")
end

#dispatch_key ⇒ Object

Key event dispatch: checks command palette first, then global bindings, sidebar (if focused), content bindings, tab traversal, and focused component.



42
43
44
45
46
47
48
49
50
 
# File 'lib/charming/controller.rb', line 42

def dispatch_key
  return dispatch_command_palette_key if command_palette_open?
  return dispatch(global_key_action) if global_key_action
  return dispatch_sidebar_key if sidebar_focused?
  return dispatch(content_key_action) if content_key_action
  return response if dispatch_tab_traversal == :handled
  return response if dispatch_to_focused_component == :handled
  nil
end

#dispatch_mouse ⇒ Object

Mouse event dispatcher: checks command palette (if open), sidebar (if focused).



68
69
70
71
72
73
74
75
 
# File 'lib/charming/controller.rb', line 68

def dispatch_mouse
  return dispatch_command_palette_mouse if command_palette_open?

  mouse_response = dispatch_component_mouse
  return mouse_response if mouse_response

  dispatch_sidebar_mouse if sidebar_focused?
end

#dispatch_task ⇒ Object

Task event dispatcher: looks up the handler in task bindings.



62
63
64
65
 
# File 'lib/charming/controller.rb', line 62

def dispatch_task
  b = self.class.task_bindings[event.name.to_sym]
  b ? dispatch(b.action) : nil
end

#dispatch_timer ⇒ Object

Timer event dispatcher: looks up the named action in timer bindings.



53
54
55
56
57
58
59
 
# File 'lib/charming/controller.rb', line 53

def dispatch_timer
  b = self.class.timer_bindings[event.name.to_sym]
  return nil unless b

  public_send(b.action)
  response
end

#logger ⇒ Object

Returns the application logger. The default logger writes to File::NULL, so logging calls are safe in TUI code unless the app explicitly configures a file or custom logger.



105
106
107
 
# File 'lib/charming/controller.rb', line 105

def logger
  application.logger
end

#navigate_to(path) ⇒ Object

Navigates to the given URL path.



117
118
119
 
# File 'lib/charming/controller.rb', line 117

def navigate_to(path)
  @response = Response.navigate(path)
end

#open_theme_palette ⇒ Object

Opens the theme picker (a CommandPalette populated with the registered themes) and renders.



110
111
112
113
114
 
# File 'lib/charming/controller.rb', line 110

def open_theme_palette
  session[:command_palette] = command_palette_state(:themes)
  focus.push_scope([:command_palette], origin: :command_palette)
  render_default_action
end

#quit ⇒ Object

Exits the application — sets a quit response that terminates the event loop.



122
123
124
 
# File 'lib/charming/controller.rb', line 122

def quit
  @response = Response.quit
end

#render(body = "", **assigns) ⇒ Object

Renders a body or template wrapped in the controller’s layout.



78
79
80
81
 
# File 'lib/charming/controller.rb', line 78

def render(body = "", **assigns)
  body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
  @response = Response.render(render_with_layout(body))
end

#render_template(name, **assigns) ⇒ Object

Renders a template from ‘app/views` by name, applying the controller’s layout. name is the template path (e.g., “home/show”) and additional keyword assigns are forwarded to the view.



89
90
91
 
# File 'lib/charming/controller.rb', line 89

def render_template(name, **assigns)
  @response = Response.render(render_with_layout(template_body(name, **assigns)))
end

#render_view(view_class, **assigns) ⇒ Object 



83
84
85
 
# File 'lib/charming/controller.rb', line 83

def render_view(view_class, **assigns)
  @response = Response.render(render_with_layout(view_class.new(**template_assigns(assigns))))
end

#theme ⇒ Object

Returns the active theme for this request, delegated to the application.



94
95
96
 
# File 'lib/charming/controller.rb', line 94

def theme
  application.theme
end

#use_theme(name) ⇒ Object

Switches the active theme to name and persists the choice in the application session.



99
100
101
 
# File 'lib/charming/controller.rb', line 99

def use_theme(name)
  application.use_theme(name)
end