imv v0.15.1 - keyboard-friendly image viewer in Gtk2-perl
BETA VERSION:
There might still be some errors in the code and things might be
changed in the later version.
=== Files ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
imv main
imv_tnv.pm thumbnail viewer
imv_pop.pm popup image viewer
imv_snd.pm SE player
imv_help.pm message window for key-bind settings
imv_ver.pm about me window
imv_fck.pl file checker
imv_dm.pm directory scanner
imv_ex.pm archive extractor
imv_cv.pm file converter
imv_ft.pm list of non-image supported files
imv_fte.pm file checker by extension
imv_ftf.pm file checker by contents
imv_rmdir.pl temporary directory cleaner
loaders/ default location for external image loaders
...
resources/pix
imv*.png icon pix
pause.png pause pix used for slideshow
play.png play pix used for slideshow
hatena.png pix for unloadable files
blue.png LED-like pix shown in thumbnail viewer
gray.png LED-like pix shown in thumbnail viewer
logo/* for "imv_ver.pm"
resources/snd
page.mp3 page turn SE
slide.mp3 slide turn SE
stop.mp3 stop slideshow SE
start.mp3 start slideshow SE
extensions/ default directory for extensions
...
=== Install ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Copy all the files to the installation directory and run imv. For
example,
% tar xvJf imv.tar.xz -C ~/lib
% ln -s ~/lib/imv/imv ~/bin/imvy
% rehash
% imvy ~/my/images
or
% perl imvy ~/my/images
* imv assumes perl is located in "/usr/local/bin"
=== Uninstall ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Remove all the files you have copied at the installation. imv makes no
files other than temporary files, which are to be deleted on normal exit
and file-list files saved by the user.
=== Requirements :::::::::::::::::::::::::::::::::::::::::::::::::::::::
imv has been developed mainly on armv7l Linux 2.6.28-15-araneo (Ubuntu
9.04) and tested with the following packages:
Binaries:
* perl v5.16.2 mandatory
+ file v5.13 for checking file by contents
+ gs v8.64 for ps/eps/pdf conversion
+ unrar v3.80 for extracting files from archives
+ unzip v5.52 for extracting files from archives
+ tar v1.26 for extracting files from archives
+ lsof v4.78 for checking extracted or converted files
perl modules:
* Glib v1.280 mandatory
* Gtk2 v1.247 mandatory
+ Cairo v1.103 for slideshow
+ GStreamer v0.18 for playing SE
* Cwd v3.39_02 mandatory: for directory scan etc
* Encode v2.44 mandatory: imv assumes utf8 for filenames
+ File::Find v1.20 for directory scan
+ File::Path v2.08_01 for $TMPDIR cleaning
+ File::Temp v0.22 for making $TMPDIR of extracted/converted
files
+ base v2.18 for "imv_pop.pm"
+ Digest::MD5 v2.51 for searching duplicate files etc.
=== Usage ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
imv [options] files
= files can be of the following types: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* image files: jpg, png, etc that "gtk-query-immodules-2.0" recognizes.
* archive files: zip, rar, tar.gz, tar.bz2, tar.xz.
* ps, eps and pdf files that "gs" can convert to png file.
* directories.
* '-' to read filenames from stdin.
= options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-s, -S sort_by
Set sorter used when reading files. "-s" for start-up
only, "-S" for whole session. "sort_by" can be one of
the following characters: "z", "n", "t", "s", "x" and
"R" for sort by full path, base filename, file time,
file size, and image size, respectively and may end
with "-" for sorting in descending order. The sorter
waits for all the files to be ready, and will take
some time before the first image shows up(esp. when
extracting or converting), however,
++<sort_command>
will sort the files without blocking image display.
-l file Read a file as a file-list.
-r, -R Disables conversion of files to png on reading, which
is the default action for ps, eps, pdf and some other
supported formats such as xcf. "-r" for start-up only,
"-R" for whole session.
-f, -F Ignore archive files. "-f" for start-up only,
"-F" for whole session.
-d, -D Allow dot-files to be scanned. "-d" for start-up only,
"-D" for whole session.
-e, -E Identify files by extension. "-e" for start-up only,
"-E" for whole session.
-x, -X Bypass file scan process for speed. It also disables
reading of directories and archives, and possible
conversions. "-x" for start-up only, "-X" for whole
session.
-g options Set options for gs. Default:
"-q -dSAFER -dNOPAUSE -dBATCH
-dTextAlphaBits=4 -dGraphicsAlphaBits=4
-r200
-sDevice=pngdev"
-p password Set password for unzip or unrar.
-C command Set shell command to be executed when "^e" is
pressed. For example,
-C "mv %_s:q ~/images"
will move the selected images to ~/images. See "Shell"
section of the help window for available arguments
(e.g., run "imv +question").
-A Enable sound effect.
-j font,font Specify fonts for log window and osd of thumbnail
viewer. If the length of "font" is 1, "Monospace 11"
will be set.
-t time Set interval of pagescan in ms. Default: 1000.
-T time Set interval of slideshow in second. Default: 5.
-u time Set fade-in/out time of slideshow in ms. Default: 120.
If 0, fade-in/out will be disabled.
-W Disable window decorations.
-b color,color,color
Sets background colors for main window, thumbnail
pane/window, and selected thumbnails. Unrecognized
names will simply be ignored. Note that this option
also enables mouse event handler (by design).
-B colors Comma separated list of colors used in creating linear
gradient pattern for background of slideshow. The
direction of the pattern can be specified with the
following prefixes: "v:", "h:", "d:" and "r:" for
vertical(default), horizontal, diagonal and another
diagonal, respectively. If one of the given color is
not recognized, the first valid color is used as solid
pattern if any, otherwise filled with black(default).
The word "rainbow" is interpreted as "violet,navy,
blue,green,yellow,orange,red"
+[+]cmd Colon separated list of commands to be executed on
start-up. "::" will be replaced with ":". "++cmd" will
be executed after reading files. "S-", "C-" and "M-"
can be used as prefix for shift, control and meta
keys, respectively. If begins with [0-9], the command
will be passed with the number(s). If begins with "=",
it would not be treated as a command and passed to
some other window. "Tab" makes the main window grab
focus. For example, ++slash:=gif:Tab:CS-k:Escape will
remove gif files from the list and +640,400S sets
window size to 640x400.
-a file Specify a file containing perl script to be executed
right before setting main window and reading
files. The script will be evaluated and run in the
main:: context and can access any subroutines and
variables. At present, this is only useful for
developers. Here is an example of valid script:
$dpx=1; # pixel size for scroll by arrow-key
$dpx_boost=10; # multiplication factor for $dpx with shift-key
$fit="f"; # fit image to window
$defw=1024; # default window width
$defh=600; # default window height
Note that the script must be written as a subroutine
body.
=== User-defined Functions :::::::::::::::::::::::::::::::::::::::::::::
imv can assign a keybind to a subroutine, which is supplied by the
users as a kind of perl script. The file containing the script might
have "#KEY:<keybind>" or "#NAME:<name>"line in it, where <keybind> is
a combination of S-, C- or M- and keysym, to invoke the subroutine and
<name> is used as internal command in shell command mode. The whole
script should look like a subroutine body and not a pure perl
script. It will be evaluated at main:: context of imv and can access
any subroutines and variables.
Here is an example script, "pop_selected.pl":
#KEY: M-p
#NAME: pops
return unless @files && $nselect;
for(0..$#stats){
&dopop($_) if substr($stats[$_],0,1);
}
1;
which will open popup windows with selected images by pressing "Alt+p"
or entering "pops" in shell command box.
There are several ways to load the scripts:
1) use the &set_ufnc in a start-up script
&set_ufnc("/path/to/the/file/pop_selected.pl");
is equivalent to
&set_ufnc("pop_selected.pl","M-p");
&dup_ufnc("M-p","'pops");
if the script is at default location for extensions.
2) use the "load" command in shell command mode
load pop_selected.pl
will do the same as &set_ufnc("pop_selected.pl") at runtime.
3) use the "run" command in shell command mode
run pop_selected.pl
will load and run the script without assigning keybind to it.
* At present, this functionality is useful only for the developers
since there can be no detailed explanations of the source code
found.
=== User-defined Keybinds ::::::::::::::::::::::::::::::::::::::::::::::
imv has a functionality that translates a input key-event to another
one. The translations can be described in the start-up script, which
will be passed by "-a" option. For example, this line will set a
"Shift+space" to "go to previous image", which is set to "scroll page
up" by default:
&set_keybind("S-space => BackSpace");
* the translations will be only valid in the key-event handler of imv
and have no effect on some other handlers.
=== Keyboard Bindings ::::::::::::::::::::::::::::::::::::::::::::::::::
S-, ^ and M- prefixes mean that Shift, Control and Alt keys are
pressed, respectively. Note that some keybinds might not work if
trapped by window manager.
= System ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
q quit
ESC cancel file loading, exit to normal mode or grab focus of the
image window
TAB switch focus among widgets
= File I/O ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^o open 'select files' dialog to add files
^f open 'select directories' dialog to add files
^O open 'select files' dialog to replace files
^F open 'select directories' dialog to replace files
^S open 'save file list as' dialog
^s save file list
* saving is for all images or the selected if selected
= Navigation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
RET/j to next image
BS/k to previous Image
Home to the first image
End to the last image
SP scroll page down
S-SP scroll page up
Arrow scroll by pixel
S-Arrow scroll by some pixels
g to page top
G to page bottom
C to page center
< decrease page scroll step
> increase page scroll step
* toggle scan mode on/off (default: off)
; toggle order priority in scan mode (default: vertical first)
. toggle page orientation (default: top to bottom, right to
left)
S-^SP toggle selection mode on/off
^SP toggle group mode on/off
[Group Mode]
^RET to next group
^BS to previous group
= Size Adjustment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
w fit image width to window
h fit image height to window
x fit image size to window
e fit window size to image
W toggle set/unset "w" as default
H toggle set/unset "h" as default
X toggle set/unset "x" as default
E toggle set/unset "e" as default
_ keep original size
M-Left decrease window width
M-Up increase window height
M-Right increase window width
M-Down decrease window height
M toggle maximize/unmaximize window
f toggle fullscreen
F toggle keep above
^z iconify window
^x toggle window decoration on/off
= Image manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
v vertical flip
m horizontal flip
r rotate counter-clockwise
R rotate clockwise
+ zoom in
- zoom out
= revert to original
^c entering crop mode
[Crop mode]
^c toggle node to move (upper-left/lower-right corner)
Arrow move the node by pixel
S-Arrow move the node by some pixels
ESC exit crop mode
$ keep flip state for all
# keep rotate state for all
% keep zoom state for all
^ keep crop state for all
^Left decrease image width
^Up decrease image height
^Right increase image width
^Down increase image height
= Entry management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
u move entry up in the list
d move entry down int the list
DEL remove the current entry
^k remove the selected entry
^w remove entry in the range
^K remove all entry
a toggle set/unset range start
b toggle set/unset range end
^b set selected by range
B reverse range
y toggle select/deselect the current image
Y select the current image
D deselect the current image
^a select all image
^d deselect all image
^r reverse the selection
^g gather the selected to the top of the entry
M-d clear all group id
~ set group id by the root path, i.e. images in the same directory
belong to the same group, which is the default grouping.
= Sorting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
z,Z sort by absolute path
n,N sort by base filename
s,S sort by file size
t,T sort by file time
M-s,M-S sort by image size
M-g,M-G sort by group ID
V reverse order
U shuffle
* capitals for descending
= Thumbnail ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
o Toggle thumbnail pane embedding position (left, top, right,
bottom, and none=default)
O open thumbnail window
{ decrease size of thumbnail pane
} increase size of thumbnail pane
^ESC close thumbnail pane
[Thumbnail Pane/Window]
+ increase thumbnail size (S- for larger change)
- decrease thumbnail size (S- for larger change)
= adjust aspect ratio of the thumbnails to the best fit
p clear cache and redraw thumbnails
i toggle filename bar display (base filename, absolute path
and none)
I toggle page number, filename or group id display on/off
^+ increase number/filename display size (S- for larger change)
^- decrease number/filename display size (S- for larger change)
g to the first image
G to the last image
a set range start
b set range end
Arrow select a thumbnail
S-Arrow select thumbnails
d move (S-Arrow selected) entry down
u move (S-Arrow selected) entry up
SP toggle select/deselect a thumbnail, or fix the selection
when multiple thumbnails are selected with S-Arrow
DEL remove S-Arrow selected or the current entry
RET show image in the main window
\ open popup window with the image
M toggle maximize/unmaximize the window
f toggle fullscreen
F toggle set/unset keep above
^z iconify the window
| toggle scrollbar position of the window
ESC switch focus to the main window
* any other key-events in the thumbnail pane/window will be
handled by the main window.
= Popup Image ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\ open popup window with the current image
[Popup Window]
p reload the image
RET show the image in the main window
+ increase image size
- decrease image size
t,T toggle tooltip on/off for base filename or absolute path
^c copy the tooltip text to clipboard
^z iconify the window
^x toggle with/without window decoration
F toggle set/unset keep above
q/ESC close the window
= Players ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
P start/stop auto-scroll
[ decrease auto-scroll time interval
] increase auto-scroll time interval
ESC stop auto-scroll
^p start slideshow
( decrease slideshow time interval
) increase slideshow time interval
^t enable/disable fade-in/out in slide-show (default: enabled)
ESC exit slideshow
[Slideshow mode]
SP toggle pause/play slideshow
* players are subject to the range(=[A,B]) settings. If A is undef,
equivalent to A=1, and if B is undef, B="number of images". It is
possible that A=B or A>B, the former simply repeats the reloading of
an image, the latter plays in reverse order.
= Shell command mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
! entering shell command mode
RET run the command
M-RET run the command and remember
ESC exit the shell command mode
^m redo last shell command
^e run shell command remembered
^Up,^Down
set commands from history record
^d complete the word for filename
[Internal Commands]
cd dir
run script args
load script key_or_name run args
eval expression
[Shell Command Arguments]
%[_]<var>[:mod] replaced with filename
#[_]<var>[:mod] replaced with status word and filename
\% replaced with %
\# replaced with #
[Variables]
f current image
s selected images
u deselected images
a all images
[0-9] an image of the given index
[Modifiers]
:h head of the full path
:t tail of the full path
:r remove the extension
:e extension
:q enclose by double quote
:n append newline
* if %f=/a/b/c.d, %f:h=/a/b/, %f:t=c.d, %f:r=/a/b/c,
%f:e=d, %f:t:r=c
* the underscore before the variable makes the list separated by a
space. For example, if %a=a.jpgb.jpgc.jpg, %_a=a.jpg b.jpg c.jpg.
* the command:
echo "#s:n" > a.flist
will save the selected images as file list
= Num-key command mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[,0-9] entering num-key command mode
BS delete one character
ESC exit the num-key command mode
^j redo last num-key command
[Commands]
[+-]g go to the image. "1g" to the 1st image, "1+g" to the
next image, "-1g" to the last image.
[-,]\ open popup window with the image
x zoom by the factor
[+-]w set image width
[+-]h set image height
[+-,]s set image width and height
[+-]l crop left
[+-]u crop top
[+-]r crop right
[+-]d crop bottom
[+-]W set window width
[+-]H set window height
[+-,]S set window width and height
RET set group id for the current image or selected entries
in the thumbnail pane/window. set 0 to clear.
[-,]M-d remove the given group id. 0 to clear all.
[-,]SP select the given group id. 0 to select all.
[-,]S-SP deselect the given group id. 0 to deselect all.
a set start of range
b set end of range
[-,]y toggle select/deselect images
[-,]Y select images
[-,]D deselect images
[-,]k remove the images
X set page scroll size factor
t set page scroll interval in ms
T set slideshow interval in s
u set transition time for slideshow in ms
p set base pixel size (default 10)
P set multiplication factor for base pixel size (default 4)
z set zoom increment/decrement factor (default 0.05)
@ entering key-record mode
[key-record mode]
^ESC/^F1..12 exit
* The recorded key-events are replayed by the keys F1 to F12.
= Miscellaneous ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
p reload the current image
| switch scroll-bar position
A enable/disable animation for GIF (default: disabled)
J toggle always go to page top on new page (default: off)
^F1..12 toggle start/stop recording of key events
F1..12 replay key events
S-F1..12 print contents of recorded key events
/ entering find-files mode
M-/ toggle target for match: root path or base name
M-f entering MD5 based duplicate search mode. The duplicated images
are given the same group id. the identical files including
hard or symbolic links are ignored. M-f or ^ESC to exit.
i toggle status bar on/off (default: on). toggle filename display
in slideshow (status bar is disabled).
I toggle status bar display mode and print internal settings on the
log window.
? show keyboard help
M-RET Turn log window in/out
[Log window]
^L clear
l list files
L list files with details
I print info on some internal settings
A toggle sync'd output on/off (default: off).
RET to bottom line
* when log window is on, some image related commands will not work
=== Mouse control ::::::::::::::::::::::::::::::::::::::::::::::::::::::
Mouse controls will not fully work unless '-b' option is passed. The
clicked widget will have keyboard focus.
[Main Window]
1 to next image
2 open the popup window with the image
3 to previous image
[Thumbnail Pane/Window]
1 show the image in the main window
2 open the popup window with the image
3 toggle select/deselect the image
[Popup Window]
1 increase image size (S- for larger change)
2 show image in the main window
3 decrease image size (S- for larger change)
=== Status bar format ::::::::::::::::::::::::::::::::::::::::::::::::::
REC %r| blank unless key record mode. %r="register id".
> %m | blank unless num-key command mode. %m="num-key command
argument".
%M | blank unless none of the following modes is on: find
files (F), search duplicates (D), selection (S) and
group (G) mode.
%s[%i/%n:%ns]@%g
%s='*' if current image is selected otherwise
%blank. %i="current image index". n="number of
%files". %ns="number of selected files". %g="group id".
%w'x'%h%x %w="width of the image". %h="height of the
image". %x="(scale factor)" or blank.
T:%t blank unless transformed. %t=combination of 'c',
'm','f','r1','r2' and 'r3' for cropped, mirrored,
vertically flipped, rotated by 90, 180 and 270 deg,
respectively. When in crop mode '(*c)' or '(c*)' will
appear instead of 'c' for upper-left or lower-right
cropping, respectively.
=%W'x'%H %W="width of the pix". %H="height of the pix".
o:%o1%o2 page orientation. %o1,%o2='<' or '>' and 'v' or '^',
for right to left, left to right, top to bottom and
bottom to top, respectively. When scan mode, page
scrolls by %o1 and then %o2. For example, "o:v<" means
scroll top to bottom and then return to top and scroll
to left once and to bottom and so forth.
R:On blank unless "return to top on new page" is on.
S:On blank unless page scan mode is on.
F:%f blank unless fit mode is on. %f='W', 'f', 'fw' or 'fh'
for fit window, size, width and height respectively.
P:%p'x'%B,%P %p="movement pixel size", %B="multiplication factor for
%p" enabled when shift-key is pressed, %p="page scroll
size" relative to size of scroll bar.
K:%k blank unless transform keeping mode. %k=combination of
'C','F','R','X','S' and 'P' for keep crop, flip,
rotation, zoom, size and position, respectively.
%a->%b blank unless range is set. %a="start index" or '?'
if undef, %b="end index" or '?' if undef.
Play %d ms blank unless auto-scroll mode. %d="scroll interval" in
ms.
A: %A blank unless animation mode. %A='On' or 'Off' for image
can be animated or not.
* The strings in the status bar can be set by a user defined scripts,
which must set as "_sbarstr" by &set_ufnc.
=== Bugs etc :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
* Everything about "scan mode" is in the experimental phase.
* Changing window size in "fit image mode" with thumbnail pane might
occasionally show scroll bar. This is partly because I don't know how
to get the "handle-size" of the thumbnail pane.
* It can happen that pausing in slideshow shows next image when the
slide fade-in/out is enabled. This is because there are some ms
between pix set and the start of fade-in/out.
=== Copyright and License ::::::::::::::::::::::::::::::::::::::::::::::
This software is free and provided to you ``AS IS'' without warranty
of any kind and is
Copyright (c) 2013 by Elseif Laboratory,
licensed under:
The Artistic License 2.0
=== Author ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Elseif Laboratory <elseifkk@users.sf.net>
