ossp-pkg/as/as-gui/as-gui.pod
##
## OSSP asgui - Accounting system graphical user interface
## Copyright (c) 2002-2004 The OSSP Project (http://www.ossp.org/)
## Copyright (c) 2002-2004 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2002-2004 Michael Schloh von Bennewitz <michael@schloh.com>
## Copyright (c) 2002-2004 Cable & Wireless Telecommunications Services GmbH
##
## This file is part of OSSP asgui, an accounting system graphical user
## interface which can be found at http://www.ossp.org/pkg/tool/asgui/.
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
## as-gui.pod: Plain old documentation file
##
=pod
=head1 NAME
B<as-gui> - accounting system graphical client
=head1 VERSION
as-gui ASGUI_VERSION_STR
=head1 SYNOPSIS
B<as-gui>
[I<X11_options>]
[I<Qt_options>]
[file]
=head1 DESCRIPTION
The B<as-gui> application tracks the time a person spends on a number of
predefined tasks. This is the graphical client to the B<Accounting System>
server (B<AS>). Although the two can interact through means of interprocess
communication mechanisms, B<as-gui> is a generic stand-alone tool which can be
used with no B<AS> server.
When logging to a local file, B<as-gui> takes input and waits until receiving
a save request from the user. Then, the time sheet will save its data entries
to the associated file name (as shown in the title bar).
Logging to a remote B<AS> server follows a similar input scheme, but at least
one B<AS> server must be specified in the preferences. A simple 'syncronize
with server' operation does the rest.
=head1 X11 OPTIONS
The following I<X11 options> are passed directly to the X11 subsystem, and
allow for the typical customization of a X11 application.
=over 4
=item B<-display display>
Sets the X display (host:server.screen). The default value is $DISPLAY.
=item B<-geometry geometry>
Sets the client geometry (width x height + xoffset + yoffset) of the main widget.
=item B<-fn font>, B<-font font>
Defines the application font. The font should be specified using a X logical
font description.
=item B<-bg color>, B<-background color>
Sets the default background color and an application palette (light and dark
shades are calculated).
=item B<-fg color>, B<-foreground color>
Sets the default foreground color.
=item B<-btn color>, B<-button color>
Sets the default button color.
=item B<-name name>
Sets the application name.
=item B<-title title>
Sets the application title (caption).
=item B<-visual TrueColor>
Forces the application to use a TrueColor visual on an 8-bit display.
=item B<-ncols count>
Limits the number of colors allocated in the color cube on an 8-bit display,
if the application is using the QApplication::ManyColor color specification.
If count is 216 then a 6x6x6 color cube is used (i.e. 6 levels of red, 6 of
green, and 6 of blue). For other values, a cube approximately proportional to
a 2x3x1 cube is used.
=item B<-cmap>
Causes the application to install a private color map on an 8-bit display.
=back
=head1 Qt OPTIONS
The following I<Qt options> are used when rendering the graphics of the Qt
widget library. They are not compatible with other X11 or Win32 applications,
unless they were first linked with the Qt widget library.
=over 4
=item B<-session session>
Restores the application from an earlier session.
=item B<-widgetcount>
Prints debug message at the end about number of widgets left undestroyed and
maximum number of widgets existed at the same time.
=back
=head1 ENVIRONMENT
C<USER> The user name to use when accounting.
C<HOME> The full path of the user's home directory.
=head1 RETURN VALUES
C<0> The application exited sucessfully.
C<E<gt>0 or E<lt>0> At least one error ocurred.
=head1 EXAMPLES
Try out some of these examples to customize B<as-gui> from the command
line. Remember that options can be mixed.
Initially editing the document 'figo.as':
=over 4
$ as-gui figo.as
=back
Showing lovely blue shades in most widgets:
=over 4
$ as-gui -bg lightblue -fg darkblue
=back
Starting with a title bar that reads 'Yours here':
=over 4
$ as-gui -title 'Yours here'
=back
Displaying graphics output on the host borchert:
=over 4
$ as-gui -display borchert:0.0
=back
A slim window slightly left of the top right corner:
=over 4
$ as-gui -geometry 761x347-120+0
=back
=head1 FILES
=over 4
=item ~/.as-gui
User preferences file.
=item as-gui.html
Help reference.
=back
=head1 BUGS
Sometimes a click on a widget (like a toolbar button) is seemingly ignored.
Consistent row shading is not always maintained. This means that the sharp
colour difference between one row and the next may not correctly follow the
chosen sort order. Press 'refresh' to work around this problem.
The row highlight may be wrong after resorting the entire time sheet. Press
the arrow keys a few times to find the currently selected row if this happens.
Double clicking on column separators should automatically expand or shrink
the corresponding column to the exact size needed. Broken.
Local reports only take datewise sorting into account. Attention! This is not
a bug, and local reports are almost always only useful when sorted by date.
=head1 SEE ALSO
as-gui.conf(5),
as-events(5),
as-accounts(5)
=head1 AUTHOR
Michael Schloh von Bennewitz
(michael@schloh.com)
=cut
