1 package Reaction::UI::FocusStack;
5 use namespace::clean -except => [ qw(meta) ];
9 isa => 'Reaction::UI::ViewPort', is => 'rw',
10 clearer => 'clear_vp_head',
13 isa => 'Reaction::UI::ViewPort', is => 'rw',
14 clearer => 'clear_vp_tail',
17 isa => 'Int', is => 'rw', required => 1, default => sub { 0 }
19 has loc_prefix => (isa => 'Str', is => 'rw', predicate => 'has_loc_prefix');
21 my ($self, $class, %create) = @_;
22 my $tail = $self->vp_tail;
23 my $loc = $self->vp_count;
24 if ($self->has_loc_prefix) {
25 $loc = join('.', $self->loc_prefix, $loc);
31 (defined $tail ? ( outer => $tail ) : ()), # XXX possibly a bug in
34 if ($tail) { # if we already have a tail (non-empty vp stack)
35 $tail->inner($vp); # set the current tail's inner vp to the new vp
36 } else { # else we're currently an empty stack
37 $self->vp_head($vp); # so set the head to the new vp
39 $self->vp_count($self->vp_count + 1);
46 my $head = $self->vp_head;
47 confess "Can't pop from empty focus stack" unless defined($head);
48 my $vp = $self->vp_tail;
53 $self->vp_tail($vp->outer);
55 $self->vp_count($self->vp_count - 1);
59 sub pop_viewports_to {
61 1 while ($self->pop_viewport ne $vp);
67 my $vp = $self->vp_tail;
69 $vp->apply_events(@_);
75 __PACKAGE__->meta->make_immutable;
82 Reaction::UI::FocusStack - A linked list of ViewPort-based objects
86 my $stack = Reaction::UI::FocusStack->new();
88 # Or more commonly, in a Reaction::UI::RootController based
89 # Catalyst Controller:
90 my $stack = $ctx->focus_stack;
92 # Add a new basic viewport inside the last viewport on the stack:
93 my $vp = $stack->push_viewport('Reaction::UI::ViewPort' =>
97 # Fetch the innermost viewport from the stack:
98 my $vp = $stack->pop_viewport();
100 # Remove all viewports inside a given viewport:
101 $stack->pop_viewports_to($vp);
103 # Create a named stack as a tangent to an existing viewport:
104 my $newstack = $vp->create_tangent('somename');
106 # Resolve current events using your stack:
107 # This is called by Reaction::UI::RootController in the end action.
108 $stack->apply_events($ctx, $param_hash);
112 A FocusStack represents a list of related L<ViewPort|Reaction::UI::ViewPort>
113 objects. The L<Reaction::UI::RootController> creates an empty stack for you in
114 it's begin action, which represents the main thread/container of the page.
115 Typically you add new ViewPorts to this stack as the main parts of your page.
116 To add multiple parallel page subparts, create a tangent from the outer
117 viewport, and add more viewports as normal.
125 =item Arguments: none
129 Create a new empty FocusStack. This is done for you in
130 L<Reaction::UI::RootController>.
136 =item Arguments: $class, %options
140 Creates a new L<Reaction::UI::ViewPort> based object and adds it to the stack.
142 The following attributes of the new ViewPort are set:
148 Is set to the preceding ViewPort in the stack.
152 Is set to the FocusStack object that created the ViewPort.
156 Is set to the location of the ViewPort in the stack.
164 =item Arguments: none
168 Removes the last/innermost ViewPort from the stack and returns it.
170 =head2 pop_viewports_to
174 =item Arguments: $viewport
178 Pops all ViewPorts off the stack until the given ViewPort object
179 remains as the last item. If passed a $viewport not on the stack, this
180 will empty the stack completely (and then die complainingly).
182 TODO: Should pop_viewports_to check $vp->focus_stack eq $self first?
188 =item Arguments: none
192 Retrieve the first ViewPort in this stack. Useful for calling
193 L<Reaction::UI::Window/render_viewport> on a
194 L<Reaction::UI::ViewPort/focus_tangent>.
200 =item Arguments: none
204 Retrieve the first ViewPort in this stack. Useful for calling
205 L<Reaction::UI::Window/render_viewport> on a
206 L<Reaction::UI::ViewPort/focus_tangent>.
212 =item Arguments: none
216 Retrieve the last ViewPort in this stack. Useful for calling
217 L<Reaction::UI::Window/render_viewport> on a
218 L<Reaction::UI::ViewPort/focus_tangent>.
224 =item Arguments: none
234 =item Arguments: $ctx, $params_hashref
238 Instruct each of the ViewPorts in the stack to apply the given events
239 to each of it's tangent stacks, and then to itself. These are applied
240 starting with the last/innermost ViewPort first.
244 See L<Reaction::Class> for authors.
248 See L<Reaction::Class> for the license.