#!/usr/bin/env perl
# vim:ts=8 sw=4 sts=4 ai
require v5.6.1;
use strict;
use warnings;

=head1 NAME

muralis - display wallpaper on your desktop.

=head1 VERSION

This describes version B<0.03> of muralis.

=cut

our $VERSION = '0.03';

=head1 SYNOPSIS

muralis --help | --manpage | --version

muralis --list [ --exclude I<string> ] [ --is_image I<string> ]
[ --listformat I<format> ] [ --match I<string> ] [ --outfile I<filename> ]

muralis [ --centre | --center ] [ --colours I<num> | --colors I<num> ]
[ --config_dir I<directory> ] [ --exclude I<string> ]
[ --is_image I<string> ] [ --fullscreen ] [ --match I<string> ]
[ --rotate I<degrees> ] [ --smooth ] [ --tile ] [ --unseen ]
[ --verbose ] [ --zoom I<percent> ]
( --random | --repeat_last | I<file> )

=head1 DESCRIPTION

The muralis script displays a given image file on the desktop
background (that is, the root window) of an X-windows display.

This tries to determine what size would best suit the image; whether to
show it fullscreen or normal size, whether to show it tiled or centred
on the screen.  Setting the options overrides this behaviour.

One can also repeat the display of the last-displayed image, changing the
display options as one desires.

This uses the xloadimage program to display the image file.
This will display images from the directories given in the "path"
section of the .xloadimagerc file.

This also depends on xwininfo to get information about the root window.

=head2 The Name

The name "muralis" comes from the Latin "muralis" which is the word from
which "mural" was derived.  I just thought it was a cool name for a wallpaper
script.

=head1 OPTIONS

Boolean options can be disabled by prefixing them with 'no'; for example,
--notile will turn off tiling of the image.

=over

=item --centre | --center

Centre the image on the root window.

=item --colours I<num> | --colors I<num>

Limit the number of colours used to display the image.  This is useful
for a 256-colour display.

=item --config_dir I<directory>

Alternative directory in which to look for muralis config files.
Note that muralis will still look for the xloadimage config file
at "~/.xloadimagerc".

=item --exclude I<string>

If an image matches this, it is excluded from --random, --list, or --nth
display.

=item --is_image I<string>

What files are considered to be image files?  This is a regular
expression checked against the filenames to see if they are image
files.  By default, muralis checks for commonly known image extensions,
so that it doesn't try to display non-image files (such as text files)
which might be in the image directories.
Most of the time you don't need to use this option.

=item --fullscreen

The image will be zoomed to fit the size of the screen.

=item --help

Print help message and exit.

=item --list

List all the images muralis knows about.  If --match is given,
this will restrict the list to those images matching the match-string.
(see --listformat)

=item --listformat I<format>

This defines the format used in the --list command.
The format is either "normal" or "fullname".
The normal format gives the directory names followed by the files in them.
The "fullname" format gives just the full names of the files.

=item --manpage

Print the full help documentation (manual page) and exit.
This will only work if you have perldoc installed.

=item --match I<string>

If using the --list or --random options, limit the image(s) to those 
which match the string.

=item --nth I<num>

Display the nth image.  If --match is given, limit the selection
to images which match the match-string.

=item --outfile

Output file for the --list command to print its output.  If this
argument is not given, list will list to standard output.

=item --random

Pick a random image to display.  If --match is given, limit
the selection to images which match the match-string.

=item --repeat_last

Display the last image which was displayed.  This is useful to
re-display an image while overriding the default display options.

=item --rotate I<degrees>

Rotate the image by 90, 180 or 270 degrees.

=item --smooth

Smooth the image (useful if the image has been zoomed).
Only works if using xloadimage as the displayer.

=item --tile

Tile the image to fill the root window.

=item --unseen

When using the --rand or --nth option, this selects the images from a list
of 'unseen' images.  This can be used to cycle through your images
without repeats.  If this option is not used, then the --random option
is truly random.

The 'unseen' list is in the '~/.muralis/unseen' file, which is
automatically updated or created whenever the --unseen option is used.
Note that if this file exists and the --unseen option is used, muralis does
not check the image directories, so if you have added a new directory to
your .xloadimagerc file, you will need to delete the 'unseen' file in order
to reset the list of unseen images.

=item --verbose

Print informational messages.

=item --version

Print version information and exit.

=item --zoom I<percent>

Enlarge or reduce the size of the image by the given percent.

=back

=head1 ENVIRONMENT

=over

=item HOME

muralis looks in the HOME directory for config files.

=back

=head1 FILES

=over 

=item ${HOME}/.xloadimagerc

muralis uses the "path" section of this file to determine what directories
to look in for image files.

=back

Configuration files for muralis are placed in the $HOME/.muralis
directory (which is created if it doesn't exist).

=over

=item ~/.muralis/last

The name of the most recently displayed image.

=item ~/.muralis/unseen

Contains a list of unseen image files.

=back

=head1 REQUIRES

    Getopt::Long
    Pod::Usage
    Getopt::ArgvFile
    File::Basename
    X11::Muralis;

=head1 SEE ALSO

perl(1)
Getopt::Long
Getopt::ArgvFile
Pod::Usage
X11::Muralis

=cut

use Getopt::Long 2.34;
use Getopt::ArgvFile qw(argvFile);
use Pod::Usage;
use X11::Muralis;

#========================================================
# Subroutines

sub init_data ($) {
    my $data_ref = shift;

    $data_ref->{manpage} = 0;
    $data_ref->{verbose} = 0;
    $data_ref->{imgcmd} = 'xloadimage';
} # init_data

sub process_args ($) {
    my $data_ref = shift;

    my $ok = 1;

    argvFile(home=>1,current=>1,startupFilename=>'.muralisrc');

    pod2usage(2) unless @ARGV;

    my $op = new Getopt::Long::Parser;
    $op->configure(qw(auto_version auto_help));
    $op->getoptions($data_ref,
	       'verbose!',
	       'manpage',
	       'list',
	       'listformat=s',
	       'outfile=s',
	       'config_dir=s',
	       'is_image=s',
	       'tile!',
	       'fullscreen!',
	       'smooth!',
	       'seamless!',
	       'zoom=n',
	       'rotate=n',
	       'nth=n',
	       'colors|colours=n',
	       'center|centre!',
	       'match=s',
	       'exclude=s',
	       'random',
	       'unseen!',
	       'repeat_last',
	       'imgcmd=s',
	      ) or pod2usage(2);

    if ($data_ref->{'manpage'})
    {
	pod2usage({ -message => "$0 version $VERSION",
		    -exitval => 0,
		    -verbose => 2,
	    });
    }

} # process_args

#========================================================
# Main

MAIN: {
    my %data = ();

    init_data(\%data);
    process_args(\%data);
    my $obj = X11::Muralis->new(%data);
    if ($data{list})
    {
	$obj->list_images(%data);
    }
    else
    {
	$obj->display_image(%data,filename=>$ARGV[0]);
    }
}

=head1 BUGS

Please report any bugs or feature requests to the author.

=head1 AUTHOR

    Kathryn Andersen (RUBYKAT)
    perlkat AT katspace dot com
    http://www.katspace.org/tools/muralis

=head1 COPYRIGHT AND LICENCE

Copyright (c) 2005-2006 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

__END__
