Shofel2_T124_python/venv/lib/python3.10/site-packages/asciimatics/widgets/frame.py

725 lines
27 KiB
Python

# -*- coding: utf-8 -*-
"""This module defines a class to display widgets"""
from __future__ import division
from __future__ import absolute_import
from __future__ import print_function
from __future__ import unicode_literals
from builtins import range
from copy import copy, deepcopy
from logging import getLogger
from wcwidth import wcswidth
from asciimatics.effects import Effect
from asciimatics.event import KeyboardEvent, MouseEvent
from asciimatics.exceptions import Highlander, InvalidFields
from asciimatics.screen import Screen, Canvas
from asciimatics.utilities import BoxTool
from asciimatics.widgets.scrollbar import _ScrollBar
from asciimatics.widgets.utilities import THEMES
# Logging
logger = getLogger(__name__)
class _BorderManager:
def __init__(self, frame, has_border, can_scroll):
"""
Helper class to manage the border and scroll bar attached to a frame.
Allows for different character to be used in the border and the
changes in sizing requirements with borders on and off with scroll
bars on and off.
:param frame: frame being manager
:param has_border: True if the frame has a border
:param can_scroll: True if the frame has a scroll bar
"""
self._frame = frame
self.has_border = has_border
self.scroll_bar = None
self.box = BoxTool(frame.canvas.unicode_aware)
if can_scroll:
scroll_y = 2
scroll_height = frame.canvas.height - 4
if not has_border:
scroll_height = frame.canvas.height - 2
scroll_y = 1
self.scroll_bar = _ScrollBar(
frame.canvas, frame.palette, frame.canvas.width - 1, scroll_y, scroll_height,
frame.get_scroll_pos, frame.set_scroll_pos, absolute=True
)
# Optimization for non-unicode displays to avoid slow unicode calls.
self.string_len = wcswidth if frame._canvas.unicode_aware else len
@property
def can_scroll(self):
return self.scroll_bar is not None
def get_rectangle(self):
"""
Returns the bounding box defined by the usable space left after
borders and/or scroll bars are accounted for.
:returns: Tuple containing, x, y, height and width of bounding box
"""
if self.has_border:
x = 1
y = self._frame.canvas.start_line + 1
h = self._frame.canvas.height - 2
w = self._frame.canvas.width - 2
else:
x = 0
y = self._frame.canvas.start_line
h = self._frame.canvas.height
w = self._frame.canvas.width
if self.can_scroll:
w -= 1
return x, y, h, w
def draw(self):
"""
Draws the border and/or scroll bars onto the frame managed by this
object.
"""
frame = self._frame
if self.has_border:
# Draw the basic border first.
(colour, attr, bg) = frame.palette["borders"]
for dy in range(frame.canvas.height):
y = frame.canvas.start_line + dy
if dy == 0:
frame.canvas.print_at(
self.box.box_top(frame.canvas.width), 0, y, colour, attr, bg
)
elif dy == frame.canvas.height - 1:
frame.canvas.print_at(
self.box.box_bottom(frame.canvas.width), 0, y, colour, attr, bg
)
else:
frame.canvas.print_at(self.box.v, 0, y, colour, attr, bg)
frame.canvas.print_at(self.box.v, frame.canvas.width - 1, y, colour, attr, bg)
# Now the title
(colour, attr, bg) = frame.palette["title"]
title_width = self.string_len(frame.title)
frame.canvas.print_at(
frame.title, (frame.canvas.width - title_width) // 2, frame.canvas.start_line,
colour, attr, bg
)
if self.can_scroll and frame.canvas.height > 5:
self.scroll_bar.update()
class Frame(Effect):
"""
A Frame is a special Effect for controlling and displaying Widgets.
It is similar to a window as used in native GUI applications. Widgets are text UI elements
that can be used to create an interactive application within your Frame.
"""
#: Colour palette for the widgets within the Frame. Each entry should be
#: a 3-tuple of (foreground colour, attribute, background colour).
palette = {}
def __init__(self, screen, height, width, data=None, on_load=None,
has_border=True, hover_focus=False, name=None, title=None,
x=None, y=None, has_shadow=False, reduce_cpu=False, is_modal=False,
can_scroll=True):
"""
:param screen: The Screen that owns this Frame.
:param width: The desired width of the Frame.
:param height: The desired height of the Frame.
:param data: optional data dict to initialize any widgets in the frame.
:param on_load: optional function to call whenever the Frame reloads.
:param has_border: Whether the frame has a border box. Defaults to True.
:param hover_focus: Whether hovering a mouse over a widget (i.e. mouse move events)
should change the input focus. Defaults to false.
:param name: Optional name to identify this Frame. This is used to reset data as needed
from on old copy after the screen resizes.
:param title: Optional title to display if has_border is True.
:param x: Optional x position for the top left corner of the Frame.
:param y: Optional y position for the top left corner of the Frame.
:param has_shadow: Optional flag to indicate if this Frame should have a shadow when
drawn.
:param reduce_cpu: Whether to minimize CPU usage (for use on low spec systems).
:param is_modal: Whether this Frame is "modal" - i.e. will stop all other Effects from
receiving input events.
:param can_scroll: Whether a scrollbar should be available on the border, or not.
"""
super(Frame, self).__init__(screen)
self._focus = 0
self._max_height = 0
self._layouts = []
self._effects = []
self._canvas = Canvas(screen, height, width, x, y)
self._data = None
self._on_load = on_load
self._hover_focus = hover_focus
self._initial_data = data if data else {}
self._title = None
self.title = title # Use property to re-format text as required.
self._has_shadow = has_shadow
self._reduce_cpu = reduce_cpu
self._is_modal = is_modal
self._has_focus = False
self._border_mgr = _BorderManager(self, has_border, can_scroll)
# A unique name is needed for cloning. Try our best to get one!
self._name = title if name is None else name
# Flag to catch recursive calls inside the data setting. This is
# typically caused by callbacks subsequently trying to re-use functions.
self._in_call = False
# Now set up any passed data - use the public property to trigger any
# necessary updates.
self.data = deepcopy(self._initial_data)
# Ensure that we have the default palette in place
self._theme = None
self.set_theme("default")
def get_scroll_pos(self):
"""
Get current position for scroll bar.
"""
if self._canvas.height >= self._max_height:
return 0
return self._canvas.start_line / (self._max_height - self._canvas.height + 1)
def set_scroll_pos(self, pos):
"""
Set current position for scroll bar.
"""
if self._canvas.height < self._max_height:
pos *= self._max_height - self._canvas.height + 1
pos = int(round(max(0, pos), 0))
self._canvas.scroll_to(pos)
def add_layout(self, layout):
"""
Add a Layout to the Frame.
:param layout: The Layout to be added.
"""
layout.register_frame(self)
self._layouts.append(layout)
def add_effect(self, effect):
"""
Add an Effect to the Frame.
:param effect: The Effect to be added.
"""
effect.register_scene(self._scene)
self._effects.append(effect)
def fix(self):
"""
Fix the layouts and calculate the locations of all the widgets.
This function should be called once all Layouts have been added to the Frame and all
widgets added to the Layouts.
"""
# Remove any focus now before we reset...
if self._has_focus:
try:
self._layouts[self._focus].blur()
except IndexError:
pass
# Do up to 2 passes in case we have a variable height Layout.
fill_layout = None
fill_height = y = 0
for _ in range(2):
# Pick starting point/height - varies for borders.
x, y, height, width = self._border_mgr.get_rectangle()
start_y = y
# Process each Layout in the Frame - getting required height for
# each.
for layout in self._layouts:
if layout.fill_frame:
if fill_layout is None:
# First pass - remember it for now.
fill_layout = layout
elif fill_layout == layout:
# Second pass - pass in max height
y = layout.fix(x, y, width, fill_height)
else:
# A second filler - this is a bug in the application.
raise Highlander("Too many Layouts filling Frame")
else:
y = layout.fix(x, y, width, height)
# Can stop now if no fill required.
if fill_layout is None:
break
# We hit a variable height Layout - figure out the available space and reset everything
# to the new values.
fill_height = max(1, start_y + height - y)
# Remember the resulting height of the underlying Layouts.
self._max_height = y
# Reset text
if self._has_focus:
while self._focus < len(self._layouts):
try:
self._layouts[self._focus].focus(force_first=True)
break
except IndexError:
self._focus += 1
self._clear()
def _clear(self):
"""
Clear the current canvas.
"""
# It's orders of magnitude faster to reset with a print like this
# instead of recreating the screen buffers.
(colour, attr, bg) = self.palette["background"]
self._canvas.clear_buffer(colour, attr, bg)
def _update(self, frame_no):
# TODO: Should really be in a separate Desktop Manager class - wait for v2.0
if self.scene and self.scene.effects[-1] != self:
if self._focus < len(self._layouts):
self._layouts[self._focus].blur()
self._has_focus = False
# Reset the canvas to prepare for next round of updates.
self._clear()
# Update all the widgets first.
for layout in self._layouts:
layout.update(frame_no)
# Then update any effects as needed.
for effect in self._effects:
effect.update(frame_no)
# Draw any border if needed.
self._border_mgr.draw()
# Now push it all to screen.
self._canvas.refresh()
# And finally - draw the shadow
if self._has_shadow:
(colour, _, bg) = self.palette["shadow"]
self._screen.highlight(
self._canvas.origin[0] + 1,
self._canvas.origin[1] + self._canvas.height,
self._canvas.width - 1,
1,
fg=colour, bg=bg, blend=50)
self._screen.highlight(
self._canvas.origin[0] + self._canvas.width,
self._canvas.origin[1] + 1,
1,
self._canvas.height,
fg=colour, bg=bg, blend=50)
def set_theme(self, theme):
"""
Pick a palette from the list of supported THEMES.
:param theme: The name of the theme to set.
"""
if theme in THEMES:
self._theme = theme
self.palette = THEMES[theme]
if self._border_mgr.can_scroll:
self._border_mgr.scroll_bar.palette = self.palette
@property
def title(self):
"""
Title for this Frame.
"""
return self._title
@title.setter
def title(self, new_value):
self._title = " " + new_value[0:self._canvas.width - 4] + " " if new_value else ""
@property
def data(self):
"""
Data dictionary containing values from the contained widgets.
"""
return self._data
@data.setter
def data(self, new_value):
# Don't allow this function to recurse.
if self._in_call:
return
self._in_call = True
# Do a key-by-key copy to allow for dictionary-like objects - e.g.
# sqlite3 Row class.
self._data = {}
if new_value is not None:
for key in list(new_value.keys()):
self._data[key] = new_value[key]
# Now update any widgets as needed.
for layout in self._layouts:
layout.update_widgets()
# All done - clear the recursion flag.
self._in_call = False
@property
def stop_frame(self):
# Widgets have no defined end - always return -1.
return -1
@property
def safe_to_default_unhandled_input(self):
# It is NOT safe to use the unhandled input handler on Frames as the
# default on space and enter is to go to the next Scene.
return False
@property
def canvas(self):
"""
The Canvas that backs this Frame.
"""
return self._canvas
@property
def focussed_widget(self):
"""
The widget that currently has the focus within this Frame.
"""
# If the frame has no focus, it can't have a focussed widget.
if not self._has_focus:
return None
try:
layout = self._layouts[self._focus]
return layout.get_current_widget()
except IndexError:
# If the current indexing is invalid it's because no widget is selected.
return None
@property
def frame_update_count(self):
"""
The number of frames before this Effect should be updated.
"""
result = 1000000
for layout in self._layouts:
if layout.frame_update_count > 0:
result = min(result, layout.frame_update_count)
for effect in self._effects:
if effect.frame_update_count > 0:
result = min(result, effect.frame_update_count)
return result
@property
def reduce_cpu(self):
"""
Whether this Frame should try to optimize refreshes to reduce CPU.
"""
return self._reduce_cpu
@property
def border_box(self):
"""
Instance of :class:`~asciimatics.utilities.BoxTool` that specifies the characters used to
draw the border to this frame. You can change the border character style by modifying the
:attr:`style` property on this object. Allowed styles are defined in
:mod:`~asciimatics.constants`.
"""
return self._border_mgr.box
def find_widget(self, name):
"""
Look for a widget with a specified name.
:param name: The name to search for.
:returns: The widget that matches or None if one couldn't be found.
"""
result = None
for layout in self._layouts:
result = layout.find_widget(name)
if result:
break
return result
def clone(self, _, scene):
"""
Create a clone of this Frame into a new Screen.
:param _: ignored.
:param scene: The new Scene object to clone into.
"""
# Assume that the application creates a new set of Frames and so we need to match up the
# data from the old object to the new (using the name).
if self._name is not None:
for effect in scene.effects:
if isinstance(effect, Frame):
# Using protected access to our own class type on purpose.
# pylint: disable=protected-access
logger.debug("Cloning: %s", effect._name)
if effect._name == self._name:
effect.set_theme(self._theme)
effect.data = self.data
for layout in self._layouts:
layout.update_widgets(new_frame=effect)
def reset(self):
# Reset form to default state.
self.data = deepcopy(self._initial_data)
# Now reset the individual widgets.
self._canvas.reset()
for layout in self._layouts:
layout.reset()
layout.blur()
# Then reset any effects as needed.
for effect in self._effects:
effect.reset()
# Set up active widget.
self._focus = 0
while self._focus < len(self._layouts):
try:
self._layouts[self._focus].focus(force_first=True)
break
except IndexError:
self._focus += 1
# Call the on_load function now if specified.
if self._on_load is not None:
self._on_load()
def save(self, validate=False):
"""
Save the current values in all the widgets back to the persistent data storage.
:param validate: Whether to validate the data before saving.
Calling this while setting the `data` field (e.g. in a widget callback) will have no
effect.
When validating data, it can throw an Exception for any
"""
# Don't allow this function to be called if we are already updating the
# data for the form.
if self._in_call:
return
# We're clear - pass on to all layouts/widgets.
invalid = []
for layout in self._layouts:
try:
layout.save(validate=validate)
except InvalidFields as exc:
invalid.extend(exc.fields)
# Check for any bad data and raise exception if needed.
if len(invalid) > 0:
raise InvalidFields(invalid)
def switch_focus(self, layout, column, widget):
"""
Switch focus to the specified widget.
:param layout: The layout that owns the widget.
:param column: The column the widget is in.
:param widget: The index of the widget to take the focus.
"""
# Find the layout to own the focus.
for i, l in enumerate(self._layouts):
if l is layout:
break
else:
# No matching layout - give up now
return
self._layouts[self._focus].blur()
self._focus = i
self._layouts[self._focus].focus(force_column=column,
force_widget=widget)
def move_to(self, x, y, h):
"""
Make the specified location visible. This is typically used by a widget to scroll the
canvas such that it is visible.
:param x: The x location to make visible.
:param y: The y location to make visible.
:param h: The height of the location to make visible.
"""
start_x, start_y, height, width = self._border_mgr.get_rectangle()
if ((start_x <= x < start_x + width) and (y >= start_y) and (y + h < start_y + height)):
# Already OK - quit now.
return
if y < start_y:
self._canvas.scroll_to(y - 1 if self._border_mgr.has_border else y)
else:
line = y + h - self._canvas.height + (1 if self._border_mgr.has_border else 0)
self._canvas.scroll_to(max(0, line))
def rebase_event(self, event):
"""
Rebase the coordinates of the passed event to frame-relative coordinates.
:param event: The event to be rebased.
:returns: A new event object appropriately re-based.
"""
new_event = copy(event)
if isinstance(new_event, MouseEvent):
origin = self._canvas.origin
new_event.x -= origin[0]
new_event.y -= origin[1] - self._canvas.start_line
logger.debug("New event: %s", new_event)
return new_event
def _find_next_tab_stop(self, direction):
old_focus = self._focus
self._focus += direction
while self._focus != old_focus:
if self._focus < 0:
self._focus = len(self._layouts) - 1
if self._focus >= len(self._layouts):
self._focus = 0
logger.debug("Trying tab to layout {}".format(self._focus))
try:
if direction > 0:
self._layouts[self._focus].focus(force_first=True)
else:
self._layouts[self._focus].focus(force_last=True)
return
except IndexError:
self._focus += direction
# If we get here, we need to reset the layout focus
if direction > 0:
self._layouts[self._focus].focus(force_first=True)
else:
self._layouts[self._focus].focus(force_last=True)
def _switch_to_nearest_vertical_widget(self, direction):
"""
Find the nearest widget above or below the current widget with the focus.
This should only be called by the Frame when normal Layout navigation fails and so this needs to find
the nearest widget in the next available Layout. It will not search the existing Layout for a closer
match.
:param direction: The direction to move through the Layouts.
"""
current_widget = self._layouts[self._focus].get_current_widget()
focus = self._focus
focus += direction
while self._focus != focus:
if focus < 0:
focus = len(self._layouts) - 1
if focus >= len(self._layouts):
focus = 0
match = self._layouts[focus].get_nearest_widget(current_widget, direction)
if match:
self.switch_focus(self._layouts[focus], match[1], match[2])
return
focus += direction
def process_event(self, event):
# Rebase any mouse events into Frame coordinates now.
old_event = event
event = self.rebase_event(event)
# Claim the input focus if a mouse clicked on this Frame.
claimed_focus = False
if isinstance(event, MouseEvent) and event.buttons > 0:
if (0 <= event.x < self._canvas.width and
self._canvas.start_line <= event.y < self._canvas.start_line + self._canvas.height):
self._scene.remove_effect(self)
self._scene.add_effect(self, reset=False)
# No need to set focus - mouse event processing later will do that.
self._has_focus = claimed_focus = True
else:
if self._has_focus and self._focus < len(self._layouts):
self._layouts[self._focus].blur()
self._has_focus = False
elif isinstance(event, KeyboardEvent):
# TODO: Should have Desktop Manager handling this - wait for v2.0
# By this stage, if we're processing keys, we have the focus.
if not self._has_focus and self._focus < len(self._layouts):
self._layouts[self._focus].focus()
self._has_focus = True
# No need to do anything if this Frame has no Layouts - and hence no
# widgets. Swallow all Keyboard events while we have focus.
#
# Also don't bother trying to process widgets if there is no defined
# focus. This means there is no enabled widget in the Frame.
if (self._focus < 0 or self._focus >= len(self._layouts) or
not self._layouts):
if event is not None and isinstance(event, KeyboardEvent):
return None
else:
# Don't allow events to bubble down if this window owns the Screen - as already
# calculated when taking the focus - or is modal.
return None if claimed_focus or self._is_modal else old_event
# Give the current widget in focus first chance to process the event.
event = self._layouts[self._focus].process_event(event, self._hover_focus)
logger.debug("Current widget left event: %s", event)
# If the underlying widgets did not process the event, try processing
# it now.
if event is not None:
if isinstance(event, KeyboardEvent):
if event.key_code == Screen.KEY_TAB:
# Move on to next widget.
self._layouts[self._focus].blur()
self._find_next_tab_stop(1)
# Find next tab stop will have already set the new focus.
old_event = None
elif event.key_code == Screen.KEY_BACK_TAB:
# Move on to previous widget.
self._layouts[self._focus].blur()
self._find_next_tab_stop(-1)
# Find next tab stop will have already set the new focus.
old_event = None
if event.key_code == Screen.KEY_DOWN:
# Move on to nearest vertical widget in the next Layout
self._switch_to_nearest_vertical_widget(1)
old_event = None
elif event.key_code == Screen.KEY_UP:
# Move on to nearest vertical widget in the next Layout
self._switch_to_nearest_vertical_widget(-1)
old_event = None
elif isinstance(event, MouseEvent):
# Give layouts/widgets first dibs on the mouse message.
for layout in self._layouts:
if layout.process_event(event, self._hover_focus) is None:
return None
# If no joy, check whether the scroll bar was clicked.
if self._border_mgr.can_scroll:
if self._border_mgr.scroll_bar.process_event(event):
return None
# Don't allow events to bubble down if this window owns the Screen (as already
# calculated when taking the focus) or if the Frame is modal or we handled the
# event.
return None if claimed_focus or self._is_modal or event is None else old_event