=encoding utf8

=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Tickit::Widget::Layout::Desktop
at lib/Tickit/Widget/Layout/Desktop.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

Tickit::Widget::Layout::Desktop - provides a holder for "desktop-like" widget behaviour

=head1 SYNOPSIS

 #!/usr/bin/env perl
 use strict;
 use warnings;
 use Tickit;
 use Tickit::Widget::Placegrid;
 use Tickit::Widget::Layout::Desktop;
 my $tickit = Tickit->new;
 my $desktop = Tickit::Widget::Layout::Desktop->new;
 $tickit->later(sub {
 	my $left = int($desktop->window->cols * rand);
 	my $top = int($desktop->window->lines * rand);
 	my $cols = 20 + int(10 * rand);
 	my $lines = 5 + int(20 * rand);
 	$left = $desktop->window->cols - $cols if $left + $cols >= $desktop->window->cols;
 	$top = $desktop->window->lines - $lines if $top + $lines >= $desktop->window->lines;
 	$desktop->create_panel(
 		label => 'widget',
 		left => $left,
 		top => $top,
 		cols => $cols,
 		lines => $lines,
 	)->add(Tickit::Widget::Placegrid->new);
 });
 $tickit->set_root_widget($desktop);
 $tickit->run;

=head1 DESCRIPTION

Experimental release for a container that provides move/resize/minimize/maximize "window" behaviour.

=begin HTML

<p><img src="http://tickit.perlsite.co.uk/cpan-screenshot/tickit-widget-layout-desktop1.gif" alt="Desktop widget in action" width="539" height="315"></p>

=end HTML

Constructed of:

=over 4

=item * L<Tickit::Widget::Layout::Desktop::Window> - the window implementation

=item * this class - background desktop on which the floats are displayed

=back

and maybe later:

=over 4

=item * ::Desktop::Taskbar - a subclass of statusbar which provides
window lists and launchers

=back

=head1 METHODS

=head2 render_to_rb

Clears the exposed area. All rendering happens in the
floating windows on top of this widget.

=head2 overlay

Render all window outlines on top of the target widget.

Takes the following parameters:

=over 4

=item * $rb - the L<Tickit::RenderBuffer> we will be drawing into

=item * $exclude - the current L<Tickit::Widget> we are drawing - this will be used
to check for intersections so we don't waste time drawing unrelated areas

=back

=head2 window_gained

Records our initial window geometry when the L<Tickit::Window> is first attached.

=head2 create_panel

Creates a L<Tickit::Widget::Layout::Desktop::Window> on this L<Tickit::Widget::Layout::Desktop>.

Takes the following named parameters:

=over 4

=item * top - offset from top of desktop

=item * left - offset from desktop left margin

=item * lines - how many lines the new widget will have, should be >2 to display anything useful

=item * cols - how many columns the new widget will have, should be >2 to display anything useful

=item * label - what label to use, default is the uninspiring text C<window>

=back

=head1 API METHODS

These methods are provided as an API for the L<Tickit::Widget::Layout::Desktop::Window> children.
They allow widgets to interact with the desktop for requesting focus etc.

=head2 make_active

Makes the requested L<Tickit::Widget::Layout::Desktop::Window> active - brings it to the front of
the stack and gives it focus.

Returns $self.

=head2 weld

"Welds" edges of windows together.

Takes 4 parameters:

=over 4

=item * Source widget edge

=item * Source widget

=item * Destination edge

=item * Destination widget

=back

For example:

 $desktop->weld(
  right => $left_panel,
  left  => $right_panel,
 );

Given a two-panel layout, this would mean any changes to the right edge of the panel on the
left would adjust the left edge of the panel on the right, and vice versa.

As you increase the size of the left panel, the right panel shrinks, so instead of the normal
behaviour where the widget on the left would start to overlap the one on the right, this maintains
the relative positioning by resizing the target widget. This can be used to provide movable dividers
between desktop panels, allowing temporary resize without disrupting the layout.

Returns C< $self > for chaining.

=head2 reshape

Deal with reshape requests.

Since our windows are positioned directly, we're going to lose some information if shrink
then expand the parent window again. This isn't ideal but hopefully we can get away with
it for now.

Returns $self.

=head2 cascade

Arrange all the windows in a cascade (first at 1,1, second at 2,2, etc.).

=head2 tile

Tiles all the windows. Tries to lay them out so things don't overlap.
Since we're resizing, things may end up ridiculously small.

Pass overlap => 1 to have overlapping edges.

Returns $self.

=head2 close_all

Close all the windows.

=head1 SEE ALSO

=over 4

=item * L<Tickit::Widget::FloatBox> - eventually ::Desktop will probably start using FloatBox for the float management

=back

=head1 INHERITED METHODS

=over 4

=item L<Tickit::ContainerWidget>

L<add|Tickit::ContainerWidget/add>, L<child_opts|Tickit::ContainerWidget/child_opts>, L<child_resized|Tickit::ContainerWidget/child_resized>, L<children_changed|Tickit::ContainerWidget/children_changed>, L<find_child|Tickit::ContainerWidget/find_child>, L<remove|Tickit::ContainerWidget/remove>, L<set_child_opts|Tickit::ContainerWidget/set_child_opts>, L<window_lost|Tickit::ContainerWidget/window_lost>

=item L<Tickit::Widget>

L<get_style_pen|Tickit::Widget/get_style_pen>, L<get_style_text|Tickit::Widget/get_style_text>, L<get_style_values|Tickit::Widget/get_style_values>, L<key_focus_next_after|Tickit::Widget/key_focus_next_after>, L<key_focus_next_before|Tickit::Widget/key_focus_next_before>, L<parent|Tickit::Widget/parent>, L<pen|Tickit::Widget/pen>, L<redraw|Tickit::Widget/redraw>, L<requested_cols|Tickit::Widget/requested_cols>, L<requested_lines|Tickit::Widget/requested_lines>, L<requested_size|Tickit::Widget/requested_size>, L<resized|Tickit::Widget/resized>, L<set_parent|Tickit::Widget/set_parent>, L<set_requested_size|Tickit::Widget/set_requested_size>, L<set_style|Tickit::Widget/set_style>, L<set_style_tag|Tickit::Widget/set_style_tag>, L<set_window|Tickit::Widget/set_window>, L<split_widget_opts|Tickit::Widget/split_widget_opts>, L<style_classes|Tickit::Widget/style_classes>, L<take_focus|Tickit::Widget/take_focus>, L<window|Tickit::Widget/window>

=item L<Object::Pad::UNIVERSAL>

L<BUILDARGS|Object::Pad::UNIVERSAL/BUILDARGS>

=back

=head1 AUTHOR

Tom Molesworth <TEAM@cpan.org>

=head1 LICENSE

Copyright Tom Molesworth 2011-2017. Licensed under the same terms as Perl itself.

