PREAMBLE.
=========
This document refers to new mini-window feature available with GUI version
of the application. Its original goal was providing xsadp with docking
facilities. While docking applies to Window Maker only, mini-window feature
can be used with other window managers to control the application and watch
visual effects when the main application window is unanvailable (iconified,
lowered, hidden, etc). Alternatively, you might prefer to see both windows
at once, so that either can be used to control the player.

In case you don't find this feature useful, it can be excluded from the 
binary code by commenting out the definition of ICON_WINDOW_SUPPORT in
sadp_config.h  before compiling xsadp.

CONTENT.
========
Icon Style and Window State arguments.
Active Icon with WindowMaker.
Active Icon with fvwm and clones.
Operating mini-windows.
Icon images.
Known bugs.


Icon Style and Window State.
============================
In case mini-window support is included, the appearance can be specified
with 'iconstyle' and 'wstate' command line arguments, or though equivalent
resource settings  'XSadp.wnd.iconstyle' and  'XSadp.wnd.state'.  

For example 'xsadp -wstate i -iconstyle a' iconifies main window at start,
and selects active icon

Initial window state ('wstate' argument) can be:

	n  - normal size
	i  - iconified
	m  - maximum size (800x600, or screen size - whatever is less)
	h  - hidden (to use with Window Maker or in dual-icon mode)

Icon style ('iconstyle' argument) can be:

	s - static icon - equivalent to old xsadp. Icon appearance is
	    selected with 'aicon' command line argument, as specified in
	    xsadp man page. 
	a - active icon mode. Mini-window is shown as the application icon.
            Requires colour icon placement support by window manager (fvwm
	    and clones, mwm, olwm, AfterStep and WindowMaker are some of
	    those). Icon placement might need to be configured - see section
	    'Active Icon with fvwm and clones' below. The icon is dockable
	    with WindowMaker - see 'Active Icon with WindowMaker'.
	d - dual window mode. There is no formal relashionships between the
	    mini-window and main window. Both windows can be seen at same time,
	    main window can be hidden, iconified and restored at any time,
	    while represented by static icon in iconic state.
	    DUAL WINDOW MODE WORKS WITH ANY WINDOW MANAGER!


Active Icon with WindowMaker
============================

Icon size and Border.
---------------------

SADP active icon size is 48x48. Since the default WindowMaker icon size
is 64x64, it provides a 8-pixel width border which is convenient for dragging.
WindowMaker icon size 56x56 is also all right for xsadp. With icon size 48x48
the border is abscent, therefore dragging is impossible. However you can dock
with a bigger icon size, and then change it to 48x48. Be aware, that some other
WindowMaker docked applications (e.g. asclock) migh be upset with an icon
size less that 64x64. Window Maker icon size can be set up with WPrefs utility,
supplied with WM.


To get the icon appearance adequate with the border colour, you might with to 
include "-bgcol' option to xsadp command line (see xsadp man page).


Docking.
--------
For WindowMaker active icon mode looks pretty much the same as dual-window:
mini-window is always seen, while main window is represented by a static 
icon when iconified. However only active icon mode allows docking. To dock:

1. Start xsadp in active icon mode:

	xsadp -iconstyle a               ( shows both windows at start)
	xsadp -iconstyle a -wstate h     ( shows only icon window at start)

2. Click the active icon's border and drag the icon to a dock. That's it!

If memory is not a problem for your computer, and you have a separate CD
drive for playing audio discs, you may wish to start xsadp with WindowMaker
session. In this case, consider '-auto' argument the instructs xsadp to
start playback automatically when media is inserted.


Active Icon with fvwn and clones
================================

This is how you can configure fvwm and its successors for icon placement
support:

fvwm-1
^^^^^^
This Robert Nation's creature is the most stable window manager, I've
ever seen. Since icon placement is typically enabled for fvwm, you
shouldn't have any problems at all. If you are curious, just open
configuration file (~/.fvwmrc or /usr/lib/X11/fvwm/system.fvwmrc) and
make sure that line starting with 'NoIcon' is NOT present, or commented
out. You are also adviced to include 'IconBox' line to specify the location
of placed icon on the screen:

IconBox -160 60 -80 -90
IconBox 5 -90 -80 -5


fvwm-2 (and fvwm95)
^^^^^^^^^^^^^^^^^^^
With fvwm-2 such a great feature as icon placement is often suppressed in
favour of the stupid task bar. Fortunately fvwm-2 provides a compromise:
you can allow icon placement for xsadp only!  This is how you can do it
(in ~/.fvwm2rc or /usr/lib/X11/fvwm2/system.fvwm2rc):

# This disables icon placement for everything ...
Style "*"  NoIcon

	.............

#       ... but not xsadp !
Style "xsadp"  Icon
# Specifies icon that goes for xsadp to the task bar (if needed)
Style "xsadp"  TitleIcon mini-sadp.xpm
# Specifies rectangle where the icon is placed (recommended if task bar used)
Style "xsadp"  IconBox  3 -100 120 -30
# Removes caption for xsadp mini-window in dual icon mode (optional)
Style "xsadp", NakedTransients


N.B. If AnotherLevel is used, these lines go to ~/.fvwm2rc.defstyles
or /etc/X11/AnotherLevel/fvwm2rc.defstyles.m4


Operating mini-windows.
=======================

Top left lines of the mini-window are PROGRESS BARS, that show location
within the disc (top bar) and current track (lower bar). This bars also
provide a feedback - you can click them to force going to a different place
within the disc and the track resp.

Below progress bars you can see PROGRESS INDICATOR, that can show time or
percentage elapsed or remained. Similarly to progress bars, the indicator
can relate to the whole disc or to the current track - its colour always
matches the colour of corresponding progress bar: click the indicator to
change the binding. The signs arround the progress indicator show its
current mode, which are: time elapsed, time remained, percentage elapsed
and percentage remained - click the signs to select previous/next mode.

Top right corner of the window is the current TRACK NUMBER. It is also
a hot spot though: click it to show/hide the main window. In active icon
mode (fvwm and similar) this will deiconify the window.

BOTTOM buttons are designed to control the player and switch panels.
Some of the buttons provide a different action depending on whether
left, middle or right mouse button was used for click. Alternatively
Shift or Ctrl keys can be used: Shift+LeftBtn is equivalent to Right
button click, while Ctrl+LeftBtn simulates middle button click.

The buttons are (left to right):
    - Previous panel (inactive if DSP support is disabled)
    - Previous track (LeftBtn), first track(MiddleBtn)
      or back in track (RightBtn)
    - Stop/Eject/Load
    - Play/Pause/Resume
    - Quit (RightBtn - quit and stop)
    - Next track (LeftBtn), last track(MiddleBtn)
      or forward in track (RightBtn)
    - Next panel (inactive if DSP support is disabled)
    
The panels are: spectrum analyser, oscillator and common.

Only common panel is available if DSP support is disabled (e.g. with -noadev
argument).  The common panel displays disc and track names and tooltips.
Track names are automatically displayed when the new track starts. To stop
showing track name, or to display it instantly, click somewhere within the
panel. Tooltips are shown only in the common panel, using same timeout settings
as for the main form (see man page), in particular a tooltip automatically
reappears. To stop the tooltip, just remove a mouse pointer from the hot spot.

Icon images.
============

The 'icons' directory contains xpm files, that can be used as application
desktop icons (kde desktop, fvwm GoodStuff, AfterStep wharf, etc): e.g.
with WindowMaker you can assign an icon to a docked application that will
be seen when the application is not running (click the icon with right
button and select "Settings").

During installation the icons are copied to /usr/X11R6/include/X11/pixmaps
directory which is common for this stuff, however you may wish to move them
elsewhere (e.g. /usr/share/pixmaps). Edit makefile if needed.


Known Bugs.
===========

Mini-windows with XFree86 3.3.1
-------------------------------
Version 3.3.1 (1997 or start 1998, unless I am wrong) was probably released
in a hurry and has a number of bugs. The one is especially crucial for xsadp
mini-window. It messes up bottom buttons and makes messages jerky and 
shifted. This bug appears to be exclusive to 3.3.1: though I can't find
my copy of 3.3.0, mini-windows work perfectly well with a dinosaurus
XFree86 3.1.2 release (August 1995).

If you aren't convinced and still want to use XFree 3.3.1, you can avoid
messing up bottom buttons with '-noiconbtnhi' that disables button high-
lighting feature. You will still have troubles with messages.

Putting back KeymapNotify
-------------------------
When running xsadp from xterm (especially on 486), I occasionally
come across the following message:

	In PutBackEvent [events.c 318] Q overflow
	PutBackEvent Event(11,w=0x0 s=1169953) KeymapNotify 

This message is hidden inside XForms library, which source code is
unavailable. It does not crash the application, but may be annoying.
I still can't establish the pattern, but it is definitely related to
mini-windows. The problem could go with recent fixes in xsadp code.

Dead window
------------
Another problem related to a slow (at the moment!) computer.
If you turn from sadp mini-window to another window while the
application is engaged (e.g. waiting for play start), the other
window appears dead. Wait for a while. If the problem persists,
move the pointer back to xsadp mini-window and remove it in 
a smooth and gracious way. This will help.

Wrong colour map
----------------
When using colour maps (8bpp or less), the colour map does not switch
properly when mini-window gets the focus . Work all right with XFree86
3.1.2 and occasionally with XFree86 3.3.2. Can't find the pattern yet.

