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;