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;