# Copyright (c) Jupyter Development Team.
# Distributed under the terms of the Modified BSD License.
"""String class.
Represents a unicode string using a widget.
"""
from .widget_description import DescriptionWidget
from .valuewidget import ValueWidget
from .widget import CallbackDispatcher, register
from .widget_core import CoreWidget
from traitlets import Unicode, Bool, Int
from warnings import warn
class _String(DescriptionWidget, ValueWidget, CoreWidget):
"""Base class used to create widgets that represent a string."""
value = Unicode(help="String value").tag(sync=True)
# We set a zero-width space as a default placeholder to make sure the baseline matches
# the text, not the bottom margin. See the last paragraph of
# https://www.w3.org/TR/CSS2/visudet.html#leading
placeholder = Unicode(u'\u200b', help="Placeholder text to display when nothing has been typed").tag(sync=True)
def __init__(self, value=None, **kwargs):
if value is not None:
kwargs['value'] = value
super(_String, self).__init__(**kwargs)
_model_name = Unicode('StringModel').tag(sync=True)
@register
class HTML(_String):
"""Renders the string `value` as HTML."""
_view_name = Unicode('HTMLView').tag(sync=True)
_model_name = Unicode('HTMLModel').tag(sync=True)
@register
class HTMLMath(_String):
"""Renders the string `value` as HTML, and render mathematics."""
_view_name = Unicode('HTMLMathView').tag(sync=True)
_model_name = Unicode('HTMLMathModel').tag(sync=True)
@register
class Label(_String):
"""Label widget.
It also renders math inside the string `value` as Latex (requires $ $ or
$$ $$ and similar latex tags).
"""
_view_name = Unicode('LabelView').tag(sync=True)
_model_name = Unicode('LabelModel').tag(sync=True)
@register
class Textarea(_String):
"""Multiline text area widget."""
_view_name = Unicode('TextareaView').tag(sync=True)
_model_name = Unicode('TextareaModel').tag(sync=True)
rows = Int(None, allow_none=True, help="The number of rows to display.").tag(sync=True)
disabled = Bool(False, help="Enable or disable user changes").tag(sync=True)
continuous_update = Bool(True, help="Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.").tag(sync=True)
@register
class Text(_String):
"""Single line textbox widget."""
_view_name = Unicode('TextView').tag(sync=True)
_model_name = Unicode('TextModel').tag(sync=True)
disabled = Bool(False, help="Enable or disable user changes").tag(sync=True)
continuous_update = Bool(True, help="Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.").tag(sync=True)
def __init__(self, *args, **kwargs):
super(Text, self).__init__(*args, **kwargs)
self._submission_callbacks = CallbackDispatcher()
self.on_msg(self._handle_string_msg)
def _handle_string_msg(self, _, content, buffers):
"""Handle a msg from the front-end.
Parameters
----------
content: dict
Content of the msg.
"""
if content.get('event', '') == 'submit':
self._submission_callbacks(self)
def on_submit(self, callback, remove=False):
"""(Un)Register a callback to handle text submission.
Triggered when the user clicks enter.
Parameters
----------
callback: callable
Will be called with exactly one argument: the Widget instance
remove: bool (optional)
Whether to unregister the callback
"""
import warnings
warnings.warn("on_submit is deprecated. Instead, set the .continuous_update attribute to False and observe the value changing with: mywidget.observe(callback, 'value').", DeprecationWarning)
self._submission_callbacks.register_callback(callback, remove=remove)
@register
class Password(Text):
"""Single line textbox widget."""
_view_name = Unicode('PasswordView').tag(sync=True)
_model_name = Unicode('PasswordModel').tag(sync=True)
disabled = Bool(False, help="Enable or disable user changes").tag(sync=True)
def _repr_keys(self):
# Don't include password value in repr!
super_keys = super(Password, self)._repr_keys()
for key in super_keys:
if key != 'value':
yield key