Skip to main content

core.nagview

Modal dialog view for confirmations and alerts. Displays a message with buttons, dims the background, and captures focus. Multiple dialogs queue automatically.

local nagview = require "core.nagview"

__index​

(field) __index: core.object

Base class providing OOP functionality for Lua. All classes in Pragtical inherit from Object.

context​

(field) context: 'application'|'session'

current_scale​

(field) current_scale: number

cursor​

(field) cursor: 'arrow'|'hand'|'ibeam'|'sizeh'|'sizev'

dim_alpha​

(field) dim_alpha: number

Alpha for background dimming [0-1]

force_focus​

(field) force_focus: boolean

Whether to force focus on this view

h_scrollbar​

(field) h_scrollbar: core.scrollbar

Scrollable viewport indicator with draggable thumb. Supports both vertical and horizontal orientation with configurable alignment. Uses a "normal" coordinate system internally that treats all scrollbars as vertical-end-aligned, then transforms to the actual orientation/alignment.

hovered_item​

(field) hovered_item: integer?

Index of currently hovered button

hovered_scrollbar​

(field) hovered_scrollbar: boolean

message​

(field) message: string?

Current dialog message

new_on_mouse_pressed_root​

(field) new_on_mouse_pressed_root: function?

New RootView.on_mouse_pressed for validation

on_mouse_pressed_root​

(field) on_mouse_pressed_root: function?

Saved RootView.on_mouse_pressed for restoration

on_selected​

(field) on_selected: function?

Current dialog selection callback

options​

(field) options: core.nagview.option[]?

Current dialog options

position​

(field) position: core.view.position

queue​

(field) queue: core.nagview.queue_item[]

Queued dialogs waiting to show

scroll​

(field) scroll: core.view.scroll

scrollable​

(field) scrollable: boolean

show_height​

(field) show_height: number

Animated height for slide-in effect

size​

(field) size: core.view.position

View size

super​

(field) super: core.view

Base view.

target_height​

(field) target_height: number

Target height for current message

title​

(field) title: string?

Current dialog title

underline_progress​

(field) underline_progress: number

Animation progress for hover underline [0-1]

v_scrollbar​

(field) v_scrollbar: core.scrollbar

Scrollable viewport indicator with draggable thumb. Supports both vertical and horizontal orientation with configurable alignment. Uses a "normal" coordinate system internally that treats all scrollbars as vertical-end-aligned, then transforms to the actual orientation/alignment.

visible​

(field) visible: boolean

Whether dialog is currently visible

core.nagview.option​

default_yes​

(field) default_yes: boolean?

True if this is the default "yes" option

text​

(field) text: string

Button text

core.nagview.queue_item​

message​

(field) message: string

Dialog message text

on_selected​

(field) on_selected: fun(option: core.nagview.option)?

Callback when option selected

options​

(field) options: core.nagview.option[]

Available button options

title​

(field) title: string

Dialog title

from_state​

function core.view.from_state(state: table)
  -> view: (core.view)?

Create and initialize a new view instance from a previously saved state.

This function is called when restoring workspace/session state. Implementations are responsible for:

  • creating the view instance
  • applying any persisted state

If loading the instance failed nil will be returned.

__call​

(method) core.object:__call(...any)
  -> obj: core.object

Metamethod allowing class to be called like a constructor. Enables syntax: local obj = MyClass(args) instead of MyClass:new(args) Automatically creates instance and calls new() with provided arguments.

@return obj — The new instance of the class

__tostring​

(method) core.nagview:__tostring()
  -> string

change_hovered​

(method) core.nagview:change_hovered(i?: integer)

Change which button is currently hovered. Resets underline animation when hover changes.

@param i — Button index to hover (nil to clear)

clamp_scroll_position​

(method) core.view:clamp_scroll_position()

Clamp scroll position to valid range (0 to max scrollable size). Called automatically by update(). Override get_scrollable_size() to customize.

dim_window_content​

(method) core.nagview:dim_window_content()

Draw semi-transparent overlay to dim content behind the dialog.

draw​

(method) core.nagview:draw()

Draw the nagview. Defers actual rendering to draw_nagview_message.

draw_background​

(method) core.view:draw_background(color: renderer.color)

Draw a solid background color for the entire view. Commonly called at the start of draw() methods.

draw_scrollbar​

(method) core.view:draw_scrollbar()

Draw the view's scrollbars. Commonly called at the end of draw() methods.

each_option​

(method) core.nagview:each_option()
  -> iterator: fun():integer, core.nagview.option, number, number, number, number

Iterate over dialog option buttons with their positions. Buttons are yielded right-to-left.

@return iterator — Iterator yielding: index, option, x, y, width, height

extend​

(method) core.object:extend()
  -> cls: core.object

Create a new class that inherits from this one. Returns a new class with this class as its parent. Example: local MyClass = Object:extend()

@return cls — The new class table

extends​

(method) core.object:extends(T: any)
  -> extends: boolean

Check if object inherits from the given type (inheritance-aware). Use this to check class hierarchy. Example: view:extends(View) returns true for View and all subclasses

@param T — Class to check inheritance from

@return extends — True if object is T or inherits from T

get_buttons_height​

(method) core.nagview:get_buttons_height()
  -> height: number

Get button area height (excluding top/bottom view padding). Includes internal button padding and borders.

@return height — Button height in pixels

get_content_bounds​

(method) core.view:get_content_bounds()
  -> x1: number
  2. y1: number
  3. x2: number
  4. y2: number

Get the content bounds in content coordinates (accounting for scroll).

@return x1 — Left edge

@return y1 — Top edge

@return x2 — Right edge

@return y2 — Bottom edge

get_content_offset​

(method) core.view:get_content_offset()
  -> x: number
  2. y: number

Get the top-left corner of content area in screen coordinates. Accounts for scroll offset. Use for drawing content at correct position.

@return x — Screen x coordinate

@return y — Screen y coordinate

get_h_scrollable_size​

(method) core.view:get_h_scrollable_size()
  -> width: number

Get the total scrollable width of the view's content. Used by horizontal scrollbar.

@return width — Width in pixels (default: 0, no horizontal scroll)

get_line_height​

(method) core.nagview:get_line_height()
  -> height: integer

Get line height for text rendering. Duplicated from DocView for independence.

@return height — Line height in pixels

get_line_text_y_offset​

(method) core.nagview:get_line_text_y_offset()
  -> offset: number

Get vertical offset to center text within line height. Duplicated from DocView for independence.

@return offset — Y offset in pixels

get_message_height​

(method) core.nagview:get_message_height()
  -> height: number

Calculate height needed to display the message text.

@return height — Message height in pixels

get_module​

(method) core.view:get_module()
  -> path: string?

Returns the module path of this view.

This method resolves the Lua module name that loaded the concrete view class (for example "core.view").

If the view class cannot be associated with any loaded module, nil is returned.

get_name​

(method) core.view:get_name()
  -> name: string

Get the name displayed in the view's tab. Override to show document name, file path, etc.

get_scrollable_size​

(method) core.nagview:get_scrollable_size()
  -> height: number

Get scrollable size when message is taller than window. Adjusts view size and enables scrolling if needed.

@return height — Scrollable height (0 if not scrollable)

get_state​

(method) core.view:get_state()
  -> state: table?

Serialize this view into a persistable state table.

This method is called when the editor is saving workspace/session state. The returned table must contain only plain Lua data (no functions, userdata, metatables, or cyclic references).

Returning nil indicates that this view should NOT be restored when reloading the workspace.

get_target_height​

(method) core.nagview:get_target_height()
  -> height: number

Get target height for the nagview content (including top/bottom padding).

@return height — Total target height in pixels

get_title​

(method) core.nagview:get_title()
  -> title: string?

Get the current dialog title.

@return title — Current title or nil if no dialog active

is​

(method) core.object:is(T: any)
  -> is_exact: boolean

Check if object is exactly of the given type (no inheritance check). Use this for strict type matching. Example: view:is(DocView) returns true only if view is a DocView, not a subclass

@param T — Class to check against

@return is_exact — True if object is exactly type T

is_class_of​

(method) core.object:is_class_of(T: any)
  -> is_instance: boolean

Check if the given object is exactly an instance of this class. Inverse of is() - checks if T is an instance of self. Example: DocView:is_class_of(obj) checks if obj is exactly a DocView

@param T — Object to check

@return is_instance — True if T is exactly an instance of this class

is_extended_by​

(method) core.object:is_extended_by(T: any)
  -> is_extended: boolean

Check if the given object/class inherits from this class. Inverse of extends() - checks if T is a subclass of self. Example: View:is_extended_by(DocView) checks if DocView inherits from View

@param T — Object or class to check

@return is_extended — True if T inherits from this class

move_towards​

(method) core.view:move_towards(t: table, k: string|number, dest: number, rate?: number, name?: string)

Smoothly animate a value towards a destination. Use this for animations instead of direct assignment.

@param t — Table containing the value

@param k — Key in table

@param dest — Target value

@param rate — Animation speed (0-1, default 0.5, higher = faster)

@param name — Transition name (for config.disabled_transitions)

new​

(method) core.nagview:new()

Constructor - initializes the modal dialog view.

next​

(method) core.nagview:next()

Show the next dialog from the queue. Dequeues and displays the next waiting dialog, or hides if queue is empty.

on_file_dropped​

(method) core.view:on_file_dropped(filename: string, x: number, y: number)
  -> consumed: boolean

Handle file drop events (drag and drop from OS). Override to handle dropped files. Return true to consume event.

@param filename — Absolute path to dropped file

@param x — Screen x where file was dropped

@param y — Screen y where file was dropped

@return consumed — True to consume event, false to propagate

on_ime_text_editing​

(method) core.view:on_ime_text_editing(text: string, start: number, length: number)

Handle IME (Input Method Editor) text composition events. Override for IME support in text editors. Called during composition.

@param text — Composition text being edited

@param start — Start position of selection within composition

@param length — Length of selection within composition

on_mouse_left​

(method) core.view:on_mouse_left()

Called when mouse leaves the view's area. Override to clear hover states. Base implementation notifies scrollbars.

on_mouse_moved​

(method) core.nagview:on_mouse_moved(mx: number, my: number, ...any)

Handle mouse movement to update button hover states.

@param mx — Screen x coordinate

@param my — Screen y coordinate

on_mouse_pressed​

(method) core.nagview:on_mouse_pressed(button: 'left'|'right', mx: number, my: number, clicks: integer)
  -> handled: boolean

Handle mouse press events on dialog buttons.

@param mx — Screen x coordinate

@param my — Screen y coordinate

@param clicks — Number of clicks

@return handled — True if event was handled

button:
    | 'left'
    | 'right'

on_mouse_released​

(method) core.view:on_mouse_released(button: 'left'|'right', x: number, y: number)

Handle mouse button release events. Override to handle click completion. Base implementation handles scrollbar.

@param x — Screen x coordinate

@param y — Screen y coordinate

button:
    | 'left'
    | 'right'

on_mouse_wheel​

(method) core.view:on_mouse_wheel(y: number, x: number)
  -> consumed: boolean?

Handle mouse wheel scroll events. Override for custom scroll behavior. Base implementation does nothing.

@param y — Vertical scroll delta; positive is "up"

@param x — Horizontal scroll delta; positive is "left"

@return consumed — True to consume event

on_scale_change​

(method) core.nagview:on_scale_change(new_scale: number, old_scale: number)

Handle DPI scale changes. Updates border widths and recalculates target height.

@param new_scale — New DPI scale

@param old_scale — Previous DPI scale

on_text_input​

(method) core.nagview:on_text_input(text: string)

Handle text input for keyboard shortcuts (Y/N).

@param text — Input text

on_touch_moved​

(method) core.view:on_touch_moved(x: number, y: number, dx: number, dy: number, i: number)

Handle touch move events (touchscreen/trackpad gestures). Override for touch-specific behavior. Base implementation handles scrolling.

@param x — Current touch x coordinate

@param y — Current touch y coordinate

@param dx — Delta x since last position

@param dy — Delta y since last position

@param i — Touch finger/pointer index

scrollbar_dragging​

(method) core.view:scrollbar_dragging()
  -> dragging: boolean

Check if user is currently dragging either scrollbar.

@return dragging — True if scrollbar drag is in progress

scrollbar_hovering​

(method) core.view:scrollbar_hovering()
  -> hovering: boolean

Check if mouse is hovering over either scrollbar track.

@return hovering — True if mouse is over scrollbar

scrollbar_overlaps_point​

(method) core.view:scrollbar_overlaps_point(x: number, y: number)
  -> overlaps: boolean

Check if a screen point overlaps either scrollbar. Useful for determining cursor style or handling clicks.

@param x — Screen x coordinate

@param y — Screen y coordinate

@return overlaps — True if point is over vertical or horizontal scrollbar

show​

(method) core.nagview:show(title: string, message: string, options: core.nagview.option[], on_select?: fun(option: core.nagview.option))

Queue and optionally show a dialog. If no dialog is currently showing, displays immediately. Otherwise queues it.

@param title — Dialog title

@param message — Dialog message text

@param options — Button options

@param on_select — Callback when button is clicked

supports_text_input​

(method) core.view:supports_text_input()
  -> boolean

Whether this view accepts text input (enables IME). Override and return true for text editors and input fields.

try_close​

(method) core.view:try_close(do_close: function)

Called when view is requested to close (e.g., tab close button). Override to show confirmation dialogs for unsaved changes. Example: core.command_view:enter("Save?", \{submit = do_close\})

@param do_close — Call this function to actually close the view

update​

(method) core.nagview:update()

Update the nagview each frame. Handles animations for show/hide, dimming, and button hover underline.

update_scrollbar​

(method) core.view:update_scrollbar()

Update scrollbar positions and sizes. Called automatically by update(). Rarely needs to be called manually.