# Source code for enaml.widgets.multiline_field

    #------------------------------------------------------------------------------
    # Copyright (c) 2013-2025, Nucleic Development Team.
    #
    # Distributed under the terms of the Modified BSD License.
    #
    # The full license is in the file LICENSE, distributed with this software.
    #------------------------------------------------------------------------------
    from atom.api import Bool, Typed, ForwardTyped, Str, set_default

    from enaml.core.declarative import d_, observe

    from .control import Control, ProxyControl

    class ProxyMultilineField(ProxyControl):
        """ The abstract definition of a proxy MultilineField object.

        """
        #: A reference to the MultilineField declaration.
        declaration = ForwardTyped(lambda: MultilineField)

        def set_text(self, text):
            raise NotImplementedError

        def set_read_only(self, read_only):
            raise NotImplementedError

        def set_auto_sync_text(self, sync):
            raise NotImplementedError

        def sync_text(self):
            raise NotImplementedError

        def field_text(self):
            raise NotImplementedError

    class MultilineField(Control):
        """ A simple multiline editable text widget.

        """
        #: The unicode text to display in the field.
        text = d_(Str())

        #: Whether or not the field is read only.
        read_only = d_(Bool(False))

        #: Whether the text in the control should be auto-synchronized with
        #: the text attribute on the field. If this is True, the text will
        #: be updated every time the user edits the control. In order to be
        #: efficient, the toolkit will batch updates on a collapsing timer.
        auto_sync_text = d_(Bool(True))

        #: Multiline fields expand freely in width and height by default.
        hug_width = set_default('ignore')
        hug_height = set_default('ignore')

        #: A reference to the ProxyMultilineField object.
        proxy = Typed(ProxyMultilineField)

        #--------------------------------------------------------------------------
        # Observers
        #--------------------------------------------------------------------------
        @observe('text', 'read_only', 'auto_sync_text')
        def _update_proxy(self, change):
            """ An observer which sends state change to the proxy.

            """
            # The superclass handler implementation is sufficient.
            super(MultilineField, self)._update_proxy(change)

        #--------------------------------------------------------------------------
        # Public API
        #--------------------------------------------------------------------------

        def sync_text(self):
            """ Synchronize the text with the text in the control.

            """
            if self.proxy_is_active:
                self.proxy.sync_text()

        def field_text(self):
            """ Get the text stored in the field control.

            Depending on the state of the field, this text may be different
            than that stored in the 'text' attribute.

            Returns
            -------
            result : unicode
                The unicode text stored in the field.

            """
            if self.proxy_is_active:
                return self.proxy.field_text()
            return ''