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;

perl v5.32.1                                       2022-01-17                              UR::Object::View(3pm)