NAME

       UR::Object::View - a base class for "views" of UR::Objects

SYNOPSIS

         $object = Acme::Product->get(1234);

         ## Acme::Product::View::InventoryHistory::Gtk2

         $view = $object->create_view(
           perspective         => 'inventory history',
           toolkit             => 'gtk2',
         );
         $widget = $view->widget();    # returns the Gtk2::Widget itself directly
         $view->show();                # puts the widget in a Gtk2::Window and shows everything

         ##

         $view = $object->create_view(
           perspective         => 'inventory history',
           toolkit             => 'xml',
         );
         $widget = $view->widget();    # returns an arrayref with the xml string reference, and the output filehandle (stdout)
         $view->show();                # prints the current xml content to the handle

         $xml = $view->content();     # returns the XML directly

         ##

         $view = $object->create_view(
           perspective         => 'inventory history',
           toolkit             => 'html',
         );
         $widget = $view->widget();    # returns an arrayref with the html string reference, and the output filehandle (stdout)
         $view->show();                # prints the html content to the handle

         $html = $view->content();     # returns the HTML text directly

USAGE API

       create
           The constructor requires that the subject_class_name, perspective, and toolkit be set.
           Most concrete subclasses have perspective and toolkit set as constant.

           Producing a view object does not "render" the view, just creates an interface for
           controlling the view, including encapsualting its creation.

           The subject can be set later and changed.  The aspects viewed may be constant for a
           given perspective, or mutable, depending on how flexible the of the perspective logic
           is.

       show
           For stand-alone views, this puts the view widget in its a window.  For views which are
           part of a larger view, this makes the view widget visible in the parent.

       hide
           Makes the view invisible.  This means hiding the window, or hiding the view widget in
           the parent widget for subordinate views.

       show_modal
           This method shows the view in a window, and only returns after the window is closed.
           It should only be used for views which are a full interface capable of closing itself
           when done.

       widget
           Returns the "widget" which renders the view.  This is built lazily on demand.  The
           actual object type depends on the toolkit named above.  This method might return HTML
           text, or a Gtk object.  This can be used directly, and is used internally by
           show/show_modal.

           (Note: see UR::Object::View::Toolkit::Text for details on the "text" widget, used by
           HTML/XML views, etc.  This is just the content and an I/O handle to which it should
           stream.)

       delete
           Delete the view (along with the widget(s) and infrastructure underlying it).

CONSTRUCTION PROPERTIES (CONSTANT)

       The following three properties are constant for a given view class.  They determine which
       class of view to construct, and must be provided to create().

       subject_class_name
           The class of subject this view will view.  Constant for any given view, but this may
           be any abstract class up-to UR::Object itself.

       perspective
           Used to describe the layout logic which gives logical content to the view.

       toolkit
           The specific (typically graphical) toolkit used to construct the UI.  Examples are
           Gtk, Gkt2, Tk, HTML, XML.

CONFIGURABLE PROPERTIES

       These methods control which object is being viewed, and what properties of the object are
       viewed.  They can be provided at construction time, or afterward.

       subject
           The particular "model" object, in MVC parlance, which is viewed by this view.  This
           value may change

       aspects / add_aspect / remove_aspect
           Specifications for properties/methods of the subject which are rendered in the view.
           Some views have mutable aspects, while others merely report which aspects are revealed
           by the perspective in question.

           An "aspect" is some characteristic of the "subject" which is rendered in the view.
           Any property of the subject is usable, as is any method.

IMPLEMENTATION INTERFACE

       When writing new view logic, the class name is expected to follow a formula:

            Acme::Rocket::View::FlightPath::Gtk2
            \          /           \    /      \
            subject class name    perspective  toolkit

       The toolkit is expected to be a single word.   The perspective is everything before the
       toolkit, and after the last 'View' word.  The subject_class_name is everything to the left
       of the final '::View::'.

       There are three methods which require an implementation, unless the developer inherits
       from a subclass of UR::Object::View which provides these methods:

       _create_widget
           This creates the widget the first time ->widget() is called on a view.

           This should be implemented in a given perspective/toolkit module to actually create
           the GUI using the appropriate toolkit.

           It will be called before the specific subject is known, so all widget creation which
           is subject-specific should be done in _bind_subject().  As such it typically only
           configures skeletal aspects of the view.

       _bind_subject
           This method is called when the subject is set, or when it is changed, or unset.  It
           updates the widget to reflect changes to the widget due to a change in subject.

           This method has a default implementation which does a general subscription to changes
           on the subject.  It probably does not need to be overridden in custom views.
           Implementations which _do_ override this should take an undef subject, and be sure to
           un-bind a previously existing subject if there is one set.

       _update_view_from_subject
           If and when the property values of the subject change, this method will be called on
           all views which render the changed aspect of the subject.

       _update_subject_from_view
           When the widget changes, it should call this method to save the UI changes to the
           subject.  This is not applicable to read-only views.

OTHER METHODS

       _toolkit_package
           This method is useful to provide generic toolkit-based services to a view, using a
           toolkit agnostic API.  It can be used in abstract classes which, for instance, want to
           share logic for a given perspective across toolkits.

           The toolkit class related to a view is responsible for handling show/hide logic, etc.
           in the base UR::Object::View class.

           Returns the name of a class which is derived from UR::Object::View::Toolkit which
           implements certain utility methods for views of a given toolkit.

EXAMPLES

       $o = Acme::Product->get(1234);

       $v = Acme::Product::View::InventoryHistory::HTML->create();
       $v->add_aspect('outstanding_orders'); $v->show;