.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Object::View 3pm"
.TH UR::Object::View 3pm "2014-07-04" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Object::View \- a base class for "views" of UR::Objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  $object = Acme::Product\->get(1234);
\&
\&  ## Acme::Product::View::InventoryHistory::Gtk2
\&
\&  $view = $object\->create_view(
\&    perspective         => \*(Aqinventory history\*(Aq,
\&    toolkit             => \*(Aqgtk2\*(Aq,              
\&  );
\&  $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         => \*(Aqinventory history\*(Aq,
\&    toolkit             => \*(Aqxml\*(Aq,              
\&  );
\&  $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         => \*(Aqinventory history\*(Aq,
\&    toolkit             => \*(Aqhtml\*(Aq,              
\&  );
\&  $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
.Ve
.SH "USAGE API"
.IX Header "USAGE API"
.IP "create" 4
.IX Item "create"
The constructor requires that the subject_class_name, perspective,
and toolkit be set.  Most concrete subclasses have perspective and toolkit 
set as constant.
.Sp
Producing a view object does not \*(L"render\*(R" the view, just creates an 
interface for controlling the view, including encapsualting its creation.
.Sp
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.
.IP "show" 4
.IX Item "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.
.IP "hide" 4
.IX Item "hide"
Makes the view invisible.  This means hiding the window, or hiding the view
widget in the parent widget for subordinate views.
.IP "show_modal" 4
.IX Item "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.
.IP "widget" 4
.IX Item "widget"
Returns the \*(L"widget\*(R" which renders the view.  This is built lazily
on demand.  The actual object type depends on the toolkit named above.  
This method might return \s-1HTML\s0 text, or a Gtk object.  This can be used
directly, and is used internally by show/show_modal.
.Sp
(Note: see UR::Object::View::Toolkit::Text for details on the \*(L"text\*(R" widget,
used by \s-1HTML/XML\s0 views, etc.  This is just the content and an I/O handle to 
which it should stream.)
.IP "delete" 4
.IX Item "delete"
Delete the view (along with the widget(s) and infrastructure underlying it).
.SH "CONSTRUCTION PROPERTIES (CONSTANT)"
.IX Header "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 \fIcreate()\fR.
.IP "subject_class_name" 4
.IX Item "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.
.IP "perspective" 4
.IX Item "perspective"
Used to describe the layout logic which gives logical content
to the view.
.IP "toolkit" 4
.IX Item "toolkit"
The specific (typically graphical) toolkit used to construct the \s-1UI.\s0
Examples are Gtk, Gkt2, Tk, \s-1HTML, XML.\s0
.SH "CONFIGURABLE PROPERTIES"
.IX Header "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.
.IP "subject" 4
.IX Item "subject"
The particular \*(L"model\*(R" object, in \s-1MVC\s0 parlance, which is viewed by this view.
This value may change
.IP "aspects / add_aspect / remove_aspect" 4
.IX Item "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.
.Sp
An \*(L"aspect\*(R" is some characteristic of the \*(L"subject\*(R" which is rendered in the 
view.  Any property of the subject is usable, as is any method.
.SH "IMPLEMENTATION INTERFACE"
.IX Header "IMPLEMENTATION INTERFACE"
When writing new view logic, the class name is expected to 
follow a formula:
.PP
.Vb 3
\&     Acme::Rocket::View::FlightPath::Gtk2
\&     \e          /           \e    /      \e
\&     subject class name    perspective  toolkit
.Ve
.PP
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::'.
.PP
There are three methods which require an implementation, unless
the developer inherits from a subclass of UR::Object::View which
provides these methods:
.IP "_create_widget" 4
.IX Item "_create_widget"
This creates the widget the first time \->\fIwidget()\fR is called on a view.
.Sp
This should be implemented in a given perspective/toolkit module to actually
create the \s-1GUI\s0 using the appropriate toolkit.
.Sp
It will be called before the specific subject is known, so all widget creation 
which is subject-specific should be done in \fI_bind_subject()\fR.  As such it typically
only configures skeletal aspects of the view.
.IP "_bind_subject" 4
.IX Item "_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.
.Sp
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.
.IP "_update_view_from_subject" 4
.IX Item "_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.
.IP "_update_subject_from_view" 4
.IX Item "_update_subject_from_view"
When the widget changes, it should call this method to save the \s-1UI\s0 changes
to the subject.  This is not applicable to read-only views.
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.IP "_toolkit_package" 4
.IX Item "_toolkit_package"
This method is useful to provide generic toolkit-based services to a view,
using a toolkit agnostic \s-1API. \s0 It can be used in abstract classes which,
for instance, want to share logic for a given perspective across toolkits.
.Sp
The toolkit class related to a view is responsible for handling show/hide logic,
etc. in the base UR::Object::View class.
.Sp
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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\f(CW$o\fR = Acme::Product\->get(1234);
.PP
\&\f(CW$v\fR = Acme::Product::View::InventoryHistory::HTML\->\fIcreate()\fR;
\&\f(CW$v\fR\->add_aspect('outstanding_orders');
\&\f(CW$v\fR\->show;