FairView

FairView Documentation

v01.07.00

Released: 04/16/05

Program Summary

FairView is an image viewer that can be controlled from within other Windows applications. It is specially designed to allow other applications to initiate the viewing of images without being disruptive to the application window from which it was launched. This means that you can launch FairView, and the last window that was active before doing so retains focus, unless you manually specify otherwise. This is useful when working with databases and other applications which may benefit from the viewing of images while retaining control over the application itself. FairView may be launched, updated, and taken away as needed, all from the command line or from inside any program that can launch another program.

The program may be set to either resizing or scrolling mode by virtue of the geometry specified at startup, if any. By default, FairView starts in the top-left corner of your screen, in window-resizing mode. When in window-resizing mode, the window automatically resizes to fit the image to be displayed. When in scrolling mode, the window stays the same size, and if the image is larger than the window you may use scrollbars or arrow keys to pan around the image as needed. The window may be resized manually in scrolling mode, and will retain the new size when displaying further images.

New images are displayed in the same window simply by invoking the program again with a new image name.

Supported Platforms

The current supported platforms are:

Windows 9x/NT/ME/2000/XP/2003
Linux

System Requirements

The following is required to use FairView:

An 800MHz (or better) Pentium or equivalent class computer
Microsoft Windows 95, NT, or a later version for Win32
Linux and X11 or Xvnc for Linux

Demo Versions

A demo version is available. The demo versions stamp the top of the viewing window with an [UNREGISTERED DEMO] label. This extra label indicates the unregistered status of the software. This does not occur with the fully licensed version.

Download the demo for your platform:

Installation

Unpack the zip archive into any directory you choose. A subdirectory named FairView will be created, and all program files are present within this subdirectory.

You may call the program directly from this directory at any time. If you wish to relocate the program itself to a location, you must copy all the included dynamic libraries to the same location in order for the program to work correctly. Relocation is purely optional.

Usage

Utilise the following syntax from inside any program that has the ability to launch other applications:

fairview [options] image_file

Supported image formats are: GIF, JPG, BMP, TIFF, PNG, XBM, XPM, PPM, and PGM.

Options

--geometry=string, -g string

The geometry string may be one of three formats:

+X+Y

Position the window at the top-left, and use resize mode.

XxY

The middle 'x' is literal. Set the dimension of the window to X by Y, position the window at the top-left, and use scrolling mode.

XxY+X+Y

The middle 'x' is literal. Set the dimension of the window to the first X by Y, position the window so its top-left corner starts at the second X by Y coordinate, and use scrolling mode.

If no --geometry is invoked, the default is to start in resize mode, at the top-left corner of your display.

This option only affects the initial instance of FairView.

--resize=string, -r string

The resize string takes this format:

XxY

The middle 'x' is literal. This sets the size to which you wish the image resized. If you specify a size larger than the image, the image will be displayed at its normal size, unless you also use --aspect and one of the axes of the image is greater than the resize request.

--aspect, -a

This option tells the program to scale all photos so that they fit within the geometry specified by --resize. You must specify a --resize geometry for this option to work.

--focus, -f

Give the FairView window focus, rather than retaining focus for the window that had it prior to FairView being started, as is the default. This option only affects the initial instance of FairView.

--kill, -k

Cause the existing FairView window to terminate. This option does not require you to specify an image file. It is a command directive to allow you to "tear down" the existing instance of the application.

--nolabel, -n

Do not display the filename label above the picture. The default behaviour is to display a label with the image name (including the full path, if it was supplied).

--prune, -p

Prune the filename label to just the basename of the file, discarding the path information.

--session=N, -s N

Use instance N of the program. If omitted, the default is session 0. If you wish to have multiple instances, you may use -s 1 and so forth to start, control, and stop individual sessions.

--top, -t

Causes the window to stay on top of all other windows. (Win32 Only.)

--help, -h

This option brings up the program documentation window. Help is also available from any window in the program via the menu.

Menus

The menu available in the main window lets you control the functionality of the program while it is running. The menu options are as follows:

File->Scroll Mode

Toggles the program between resize and scrolling modes.

File->Display Label

Toggles whether the image label is shown above the image itself.

File->Window Manager Enabled

Toggles whether the window manager is active for the main window. In the Microsoft Windows version, this is on by default, and turning it off serves no purpose unless you wish to take away the titlebar and ability to move and resize the window via the window manager. In Microsoft Windows, it's safe to just leave this alone at its default setting and never think twice.

In X-Windows, this is turned off by default to prevent window focus stealing. If you need to move or resize the window, you may turn it on, do your resizing and/or moving, and then turn it back off. In some window managers, you may need to turn this on to enable other windows to be seen "on top" if they overlap the main window. This would include the help, feedback, and other windows of this program.

File->Stay on Top

Toggles whether the image display window remains on top of all other windows. (Win32 only.)

File->Provide Feedback

Allows you to submit feedback to the author from within the program itself. This option requires an active Internet connection to successfully provide the feedback.

File->Exit

Exits the program.

Help->Instructions

Provides program usage information.

Help->Show Geometry

Allows you to see what the geometry of your FairView window is. This is useful for determining what geometry to use on the command line. Simply start in or switch to scrolling mode, resize and/or reposition the window, and use this option to obtain your geometry. Use the parts that are relevant to your particular scenario.

Help->About

Provides information about the program version, copyright, and author.

Advanced Optimisation for Speed

By nature, FairView requires a fair amount of resources. Every time you invoke the program, it must load all its shared libraries again, which takes a little time. One can expedite window updates to the same session by launching the session window only once, and then manipulating two files that are monitored by the program. The following describes the methodology for taking advantage of raw file manipulation to eliminate the load time for secondary calls to alter the contents of established session windows.

There are two files you need to be concerned with. On *nix systems, they will be placed into the /tmp directory. On Win32, these files will be placed into the directory in which FairView.exe resides (and from which it was called). All filenames are case sensitive, even on Win32, so pay close attention to the filename casing.

First, we write the file FairViewImagePath-[username]-[session].TXT.

That is not the actual filename. You need to do substitutions on [username] and [session] in order to accomodate which user you're running as, and which session you wish to affect. On *nix systems, the username section will be whatever is stored in $USER in your environment. In Win32, the username is always set to undefuser (unless you actually have an environment variable for $USER set, which is doubtful). The second substitution is the session number. This is identical to the number you would give the -s argument. Session 0 is the default, and both -s with no argument and -s0 are equivalent to omitting the option altogether. All other sessions are usable. Simply substitute the appropriate numeral in the filename section.

In this fashion, if I'm running on Win32 and altering session 0, my filename would actually be

FairViewImagePath-undefuser-0.TXT

We will write the contents of this file according to what we wish to do. The following parameters are all followed by an equals sign and their respective values as described below:

file

The file we wish to display.

label

Either on or off. The value off is equivalent to specifying -n on the command line.

aspect

Either on or off. The value on is equivalent to specifying -a on the command line.

prunelabel

Either on or off. The value on is equivalent to specifying -p on the command line.

top

Either on or off. The value on is equivalent to specifying -t on the command line. (Win32 Only.)

resize

The value we wish to use to resize the image when subsampling. (e.g., 200x200) This value is what you would specify to the -r option on the command line.

There is a special line which, in its entirety, may read __KILL__. That is in all caps, and there are two underscores on either side. This option, regardless of the presence of any others, will result in the immediate death of the session. This is equivalent to using -k on the command line.

All lines should end in their respective platform's line-ending. On *nix, this is a single newline. On Win32, this is a carriage-return followed by a newline.

After writing the file, close the file, as the program will want full permission to remove it.

There is one more thing we must do in order to finalise our request and let the program act upon them. Take the filename you constructed above and replace the TXT suffix with the SEM suffix. Simply open and close this file. No contents are necessary--only its presence is required. The closing part is important, as the program needs to unlink this file! Do not forgot to close either file!

After creating that second file, you're done. The session that's being manipulated will act on the data nearly instantaneously (250ms maximum delay).

This methodology is for advanced users who wish to speed performance of FairView, and who know what they're doing. This method is also not officially "supported" behaviour, although it does work. Please bear in mind that there is absolutely no error checking done on this file for bad pathnames, bad sizes, etc. This mechanism is really meant to be used by FairView itself, which does all the command line sanity checking. You can't seriously damage anything, although you may net some unexpected results if you accidentally give strange values.

Changelog

v01.04.00 - 04/11/05

Original Release.

v01.05.00 - 04/12/05

Added multiple instances, multiuser facilities, and pathname pruning. Fixed fonts to be uniform on all versions of Windows, regardless of native font scaling settings and reworked geometry to be smaller for several windows. Did pre-work on Linux version modifications (hence, adding multiuser).

v01.06.00 - 04/12/05

Finished Linux version and integrated into one codebase. Not released publicly.

v01.06.01 - 04/12/05

A little more work on Linux version. Added auto-backgrounding code. Corrected window manager issues. Worked out issues with compiler.

v01.06.02 - 04/13/05

Added "Always on Top" mode for Win32. (User requested feature.)

v01.07.00 - 04/16/05

Added TIFF support. (User requested feature.)

This software remains the property of Fairlight Consulting, and license to use the program is sold to users. FairView is licensed at a cost of $49.95 USD per system on which it is used. Each license fee entitles you to use FairView on one system, in any role you require.

Upon receipt of payment for a license, program will be delivered to the licensee via email at the email address associated with the PayPal payment.

Upgrades for the product are currently free when moving to new minor and major versions. Fairlight Consulting reserves the right to change this policy in the future, with no prior warning.

There is no warranty for this software. This software is offered "AS-IS" and without warranties as to performance or merchantability or any other warranties, whether expressed or implied.

Good computing practice dictates that any program should be thoroughly tested with non-critical data before deploying it for production. The user assumes the entire risk of using the program. In no event shall Fairlight Consulting be held liable for loss of data, failure of performance, or any other damages, be they real or perceived.