Source code for AutoArchive._mainf.icomponent_ui

# icomponent_ui.py
#
# Project: AutoArchive
# License: GNU GPLv3
#
# Copyright (C) 2003 - 2012 Róbert Čerňanský



""":class:`IComponentUi` interface, :data:`UiMessageKinds` and :data:`VerbosityLevels` enums."""



__all__ = ["UiMessageKinds", "VerbosityLevels", "IComponentUi"]



# {{{ INCLUDES

from abc import *

from .._py_additions import *
from .iinterface_accessor import *

# }}} INCLUDES



# {{{ CONSTANTS

#: Kinds of user messages.
UiMessageKinds = Enum(
    "Verbose",
    "Notification",
    "Info",
    "Warning",
    "Error")



#: Verbosity levels.
VerbosityLevels = Enum(
    "Quiet",
    "Normal",
    "Verbose")

# }}} CONSTANTS



# {{{ CLASSES

[docs]class IComponentUi(IComponentInterface): """Basic interface for an :term:`UI` implementation. Defines basic methods for showing messages of various importance to a user. .. note:: There should be at least one :term:`component` that implements this interface in order to provide an \ :term:`UI` access to other components. See also the description of _mainf package (:mod:`._mainf`).""" @abstractmethod @event def messageShown(messageKind): """Fired after a user message was shown. Event is fired when one of the message kinds from :data:`UiMessageKinds` enum was shown or would be shown (but was suppressed due to the verbosity level). :param messageKind: Kind of the message that was shown. :type messageKind: :data:`UiMessageKinds`""" @abstractproperty def verbosity(self): """Gets the verbosity level. If verbosity level is :data:`VerbosityLevels.Quiet` only messages of kind :data:`UiMessageKinds.Error` are shown. For level :data:`VerbosityLevels.Normal` all messages kinds except :data:`UiMessageKinds.Verbose` are shown. For level :data:`VerbosityLevels.Verbose` all message kinds are shown. :rtype: :data:`VerbosityLevels`"""
[docs] @abstractmethod def showVerbose(self, msg): """Show a verbose-type message (:data:`UiMessageKinds.Verbose`) to the user. Verbose messages should be shown only if user enables it. Although this method can be called regardless of current verbosity level, the concrete implementation can decide whether it will be shown or not if verbosity level is 0. It is not recommended to call this method if verbosity level is 0 due to performance reasons. Current verbosity level can be obtained via :attr:`verbosity` property. See also: :attr:`verbosity`. :param msg: The message that should be shown to the user. :type msg: ``str``"""
[docs] @abstractmethod def showNotification(self, msg): """Show an unintrusive notification message (:data:`UiMessageKinds.Notification`) to the user. .. note:: If user interface implementation does not have means to support notifications then it should be presented to the user similarly as :meth:`showInfo`. See also: :attr:`verbosity`. :param msg: The message that should be shown to the user. :type msg: ``str``"""
[docs] @abstractmethod def showInfo(self, msg): """Show an information message (:data:`UiMessageKinds.Info`) to the user. See also: :attr:`verbosity`. :param msg: The message that should be shown to the user. :type msg: ``str``"""
[docs] @abstractmethod def showWarning(self, msg): """Show a warning message (:data:`UiMessageKinds.Warning`) to the user. See also: :attr:`verbosity`. :param msg: The message that should be shown to the user. :type msg: ``str``"""
[docs] @abstractmethod def showError(self, msg): """Show an error message to (:data:`UiMessageKinds.Error`) the user. See also: :attr:`verbosity`. :param msg: The message that should be shown to the user. :type msg: ``str``"""
[docs] @abstractmethod def presentLine(self, line): """Present a line of text to the user. .. note:: The verbosity level has no effect on presenting the line. :param line: The text that shall be presented to the user. :type line: ``str``"""
# }}} CLASSES