#BEGIN introduction "0. Introduction" "$Id: Help,v 2.9.6.4 2010/10/24 20:15:35 demailly Exp $"
Welcome to the latest version of XPaint.

XPaint is a simple color image-editing tool which provides many standard 
painting and drawing operations as well as certain more advanced features.

It allows for the editing of multiple images simultaneously and supports
various formats, including PNG, JPEG, JPEG2000, GIF, TIFF, BMP, ICO,
PPM, XBM, XPM, etc. It can import vector formats such as PS, PDF and SVG,
and can also convert TeX/LaTeX files to images.

XPaint does not attempt to compete with much more sophisticated programs
such as "The Gimp" (http://www.gimp.org), but instead focuses on ease of use.

The functionality of XPaint is divided into a toolbox area for selecting
the current paint operation and paint windows for modifying/creating
images.  Each paint window has access to its own color palette and set
of patterns, although the paint operation in use is globally selected
for all windows.

By default all images given on the command line are listed in the browser
of preselected files, but only the first one will be displayed. The /o 
switch (resp. /c, /l) indicates that the next images will be opened in a
graphical canvas (resp. in the clipboard, resp. again listed in the file
browser).

XPaint runs on a variety of displays.  Saving images will adapt them
to the current display type (e.g., a color image loaded on a greyscale
screen will be saved as a grey image). This can result in the loss of
data; see the Possible Data Loss section for details.

More information is available under the specific topics.  Enjoy!

#BEGIN data_loss	"1. Possible Data Loss"
XPaint uses the native display format for storing image info while editing;
the original image information is thrown away.  This means that, in general,
color information is irretrievably lost when using any display depth
less than 24 bits.

More specifically, for depths less than 8 bits, both
24-bit (true-color) and 8-bit (palette) images will be reduced to the display
depth; for 8-bit displays, standard color-mapped images are safe but 12-bit
color-mapped and 24-bit true-color images will lose color information;
for 15- and 16-bit displays (typically RGB 555 and 565, respectively), in
general both 8-bit and 24-bit images will suffer data loss; and for 24- or
32-bit displays, only very deep images such as 16-bit grayscale or 48-bit
true-color will lose data.

Also note that any ancillary information associated with the original
image (embedded comments, time stamp, copyright, etc.) will always be lost.

#BEGIN command	"2. Command Line Options"
xpaint [-canvas] [-screenshot] [-magnifier] [-blind] [-nowarn]
#NL
       [-menubar] [-nomenubar] [-fullmenu] [-simplemenu]
#NL
       [-tooltips] [-notooltips] [-quality VALUE] [-toolmode 0,1,2]
#NL
       [-language LANGUAGE] [-zoom VALUE] [-sharedir DIR]
#NL
       [-menufont FONT] [-bntheight VALUE] [-encoding 0/8/16]
#NL
       [-twistcolor VALUE] [-hilitcolor VALUE]
#NL
       [-rcfile FILE] [-msgfile FILE] [-helpfile FILE]
#NL
       [-canvassize WIDTHxHEIGHT] [-winsize WIDTHxHEIGHT] [-dpi DPI]
#NL
       [-undo VALUE] [-operation NUMBER] [-filter FILE] [-proc FILE]
#NL
       [-8 | -12 | -24 | -visual VISUAL]
#NL
       IMAGE1 IMAGE2 ... /o IMAGE3 ... /c IMAGE4 ... /l IMAGE5 ...
#NL
	-language       set LANGUAGE for dialogs and menus
#NL
	-encoding       Use 0 (UTF8), 8 (8 bit) or 16 (16 bit)
#NL
	-menufont       Set freetype font in menus
#NL
	-btnheight      Set height of menu buttons (number of pixels)
#NL
	-twistcolor     Twisting color to brown-ish for insensitive items
#NL
	-hilitcolor     Set highlighting color as hexadecimal #PQRSTU
#NL
	-zoom           default zoom for painting canvas
#NL
	-canvassize     default width and height for painting canvas
#NL
	-winsize        default size for canvas windows
#NL
	-dpi            use DPI resolution when loading vector format images
#NL
	-quality        use VALUE quality when saving JPEG images
#NL
	-undo           default undo maximal VALUE
#NL
	-operation      switch on operation NUMBER# in the tool panel
#NL
	-filter         compile FILE as C-script filter
#NL
	-proc           compile FILE as C-script procedure
#NL
	-8              use an 8-bit PseudoColor visual
#NL
	-12             use a 12-bit PseudoColor visual
#NL
	-24             use a 24-bit TrueColor visual
#NL
	-toolmode       display tool window in vertical/horizontal/square mode
#NL
	-canvas         pop up an empty canvas on startup
#NL
	-screenshot     open xpaint without any GUI, and take screenshot
#NL
	-magnifier      open xpaint in magnifier glass mode
#NL
	-blind          do not open tool window (e.g. for batch mode) 
#NL
	-nowarn         skip data-loss warnings at startup
#NL
	-menubar        show menu bar on top of canvas windows
#NL
	-nomenubar      do not show menu bar on top of canvas windows
#NL
	-fullmenu       show the complete menu on the floating canvas popup
#NL
	-simplemenu     just show the edit menu on the floating canvas popup
#NL
	-tooltips       enable tooltips
#NL
	-notooltips     disable tooltips
#NL
	-sharedir       use DIR instead of default share directory
#NL
	-rcfile         use FILE instead of default .XPaintrc
#NL
	-msgfile        use FILE instead of default localized message file
#NL
	-helpfile       use FILE instead of default localized help file
#NL
	-visual         use VISUAL instead of default.  Choices are
#NL                  
				TrueColor, PseudoColor, DirectColor, StaticColor,
#NL
				StaticGray, GrayScale, or the decimal visual 
#NL
				number (from xdpyinfo).

These options are normally followed by the names IMAGE1, IMAGE2 (...) 
#NL
of the images to be loaded. By default all these images are listed in the
#NL
browser of preselected files, but only the first one will be displayed.
#NL
The /o switch (resp. /c, /l) indicates that the next images will be opened
#NL
in a graphical canvas (resp. in the clipboard, resp. again listed in the
#NL
file browser).
#NL

#BEGIN toolbox "3. Toolbox"
The toolbox is used to set those options that are applicable to all
XPaint canvases.

#PUSH
#BEGIN tool_file "3.1. File Menu"
The File Menu is used to load an image from a file, to create a new 
canvas, to take a screenshot or to activate the magnifier.

Open Image...
#NL
	Opens a file browser to the effect of navigating
#NL
	in the file system, selecting an image file and
#NL
	opening a new canvas for viewing or modifying it.
#NL
	Images can be opened in a variety of formats.
#NL
	If none of the specific formats is selected,
#NL
	XPaint will attempt to perform a "Best Guess" as
#NL
	to the image format.  Unknown formats will result
#NL
	in an error message.
#NL
	Buttons located near the bottom can be used to
#NL
	switch directories. When activated, the 
#NL
	"Ongoing" button allows to use xpaint as a
#NL
	photo/image browser.

List of Loaded Files...
#NL
	Shows the list of all image files which have
#NL
	been called from the command line, or all newly 
#NL
	created files. The widget also contains buttons
#NL
	which can modify default zoom, DPI values,
#NL
	cycle bounding box mode, page numbers, etc.

New Canvas
#NL
	Create a new blank canvas (default size:
#NL
	1024x768).  See "Command Line Options" for
#NL
	changing the default size.

New with Size...
#NL
	Create a new canvas with the specified
#NL
	dimensions.

Magnifier
#NL
	Opens the interactive magnifier. Potentially useful
#NL
	as an accessibility tool for visually impaired
#NL
	people, but it can be used also to take screenshots
#NL
	of small areas of the screen and to apply them 
#NL
	certain transformations.

Take Screenshot...
#NL
	Grab a rectangle from the root window and load
#NL
	that rectangle in a new canvas. The left button
#NL
	is used to select opposite corners of the 
#NL
	rectangle, the middle button to grab a complete
#NL
	window and the third button to cancel the 
#NL
	operation.

Quit
#NL
	Exit XPaint, closing all windows.

#BEGIN tool_help "3.2. Help Menu"
The help menu opens the help widget and provides access to the main 
sections and subsections of the help system.

#BEGIN tool_exclamation "3.3. Exclamation mark !"
Clicking on the exclamation raises the active canvas window, in case that
window has been hidden completely or partially by other windows. Has no 
effect otherwise.

#BEGIN tools "3.4. Painting Tools"
The painting tool icons set the current painting operation for all canvases.

Operations are selected with mouse button one.  Pressing mouse button three
while over any of the icons will bring up a menu of options available for
that tool.  Some icons also allow double-clicking as a faster method of
bringing up style options.

See the specific paint operation for more information.

#PUSH
#BEGIN pencil "Pencil"
The pencil operation paints a connected line on the canvas, following the
cursor while the mouse button is pressed.  The global line width is used
to determine the width of this line.

Button one paints in the primary color/pattern, button two the secondary
color/pattern.

See "Line Menu" under the canvas menu bar for more information about line 
width.

#BEGIN dynpencil "Dynamic Pencil" 
The dynamic pencil operation paints calligraphic stroke-like curves
on the canvas, following the cursor while the mouse button is pressed.
It mimics pulling a variable-width pencil with a rubber string. The
width of the pen gets smaller the faster it moves. The pencil has a
settable mass. Depending on its mass, it follows the cursor more or
less tightly as you accelerate and turn the cursor. A heavy pencil has
large inertia.

The "mass", steady-state width and "drag" can be set with the dialog 
you get if you press button three on the icon.

Button one paints in the primary color/pattern, button two the secondary
color/pattern.

#BEGIN dotPencil "Dot Pencil"
The dot pencil operation paints a series of dots on the canvas, following the
cursor while the mouse button is pressed.

Button one paints in the primary color/pattern, button two the secondary
color/pattern.

See "Pencil" for painting connected lines.

#BEGIN brush "Brush"
The brush operation uses the current brush to paint on the canvas(es).
Painting is accomplished by holding down the mouse button and
moving the mouse in the canvas area.  Button one paints in the selected primary
color/pattern, while button two uses the secondary one.

If the 'Transparent' option is selected from the menu found by pressing button
three on the icon, the selected color is blended with the color already on the
canvas. You can change the opacity of the brush using the 'Parameters...'
option. Zero percent means that the canvas is not changed at all, while 100
percent gives the same result as using a non-transparent brush.

If the 'Stain' option is selected from the menu found by pressing button
three on the icon, the selected color is applied as stain, for instance
all black pixels already present on the canvas are left unmodified, but
less dark pixels can receive some coloring.

The current brush style may be changed through the brush chooser available
on the button three menu for either the brush or erase operation icons.
The brush chooser can also be opened through the brush icon button from
the canvas windows.

#BEGIN spray "Spray"
The spray operation is designed to emulate a spray can.  It will paint
a random set of dots within a given radius.

It is possible to change the attributes of the spray operation to
achieve the desired effect.   There are three parameters that will
modify the configuration of the spray tool:
#NL
	radius	how large of a circle to fill
#NL
	density	number of dots in the given area
#NL
	rate	speed to fill the area in tenths of a second

Additionally, it is possible to change the distribution of the dots to
be either even or gaussian (usually only noticeable at large radii).
These options are found in the menu brought up by clicking button three
on the spray icon.

As with many other operations, the spray operation can make use of either
the primary or secondary color/pattern based on which button (one or two,
respectively) is held down while painting on the canvas.

#BEGIN smear "Smear"
The smear operation paints each pixel under the brush the average color
of all the pixels.
Smearing is done by holding down the mouse button and
moving the mouse in the canvas area.

The current brush style may be changed through the brush chooser available
on the button three menu.

#BEGIN line "Segment"
The line operation paints a segment of straight line in the primary 
color/pattern between two selected points on the canvas, using the 
global line width and the global dash style.

See "Line Menu" under the canvas menu bar for more information about 
line width and dash style.

Lines may also be restricted to increments of 45 degrees (i.e.,
horizontal, vertical, or diagonal) by holding down the shift key while
painting.

Options of the "Segment" tool are "Sheaf", "Vector",
"Arrowhead parameters...", "Position" and "Measurement".

The "Sheaf" option paints an array of "segments" from the first selected 
point to all subsequent points in the primary color/pattern. Button 
two ends this operation (without selecting a new ray point). Rays may 
also be restricted to slopes based on a 45 degree increment (i.e.,
horizontal, vertical, or diagonals) by pressing the shift key while
painting.

When the "Vector" option is set, all segments are drawn with an arrow head 
at the end point.

The "Position" and "Measurement" options do not draw anything.
They cause the opening of an auxiliary window which records the
positions of the points clicked, and, for the "Measurement" option,
the distance between the origin and the end, as well as the polar
angle in degrees.

#BEGIN brokenline "Polygonal Line"
The connected line operation paints a series of straight lines connected at
selected vertices.  Each new vertex is selected using the first mouse button.
Pressing the second mouse button of the "Enter" key ends the operation
at the current cursor position. During the operation, the BackSpace key 
removes the last point that has been entered, and the Escape key restarts 
the operation from the beginning.

All painting is done in the primary color/pattern using the currently defined
line width and dash style.

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN arc "Arc"
The arc operation paints an arc between two selected points in the primary
color/pattern, using the current line width and the current dash style.  
According to the operating mode which is selected, one can obtain 
circle arcs ior ellipse arcs.

There are four operating modes available. The first, which is also the 
default mode, draws a circle arc joining 3 points. As long as the arc is
not finalized, the second extremity of the arc can be changed by pressing 
the Shift key.

The second operating mode produces ellipse quadrants. In this case, the
Shift key changes the arc concavity (turning it upwards rather than
downwards).

The third and fourth operating modes produce arbitrary ellipse arcs
(the ellipse have horizontal and vertical axes, however). One first
selects the ellipse itself, and then the extremities of the arc.
In mode 3, the initial point is the center of the ellipse.
In mode 4, the first two points are opposite vertices of a rectangular
box containing the ellipse. In both cases, the Shift key enforces
a circle arc rather than an arc of ellipse.

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN arrow "Arrow head"
This operation draws arrow heads and only arrow heads. The first clic with
left button mouse selects the extremity of the arrow head, while the second
clic allows to choose the orientation. If the second clic occurs at the
same point as the first one, the arrow head is not drawn (so, this is a
way to cancel the operation).

The arrow head can be changed with the "Parameters..." menu. The available
parameters are head type (1, 2 or 3), head size and an angle equal to
one half of the aperture of the arrow head.

#BEGIN text "Text"
The text operation allows for typing in the currently selected font.
Pressing mouse button two in the canvas area while inserting text
will paste text from the X clipboard at the current insertion point.

See the "Font Menu" for information on changing the selected font.

Note:  Clicking the mouse while inserting text will be viewed as a new
text insertion. Therefore backspacing over text already written before
the mouse click will no longer be possible, "Undo" should be used in 
that case.

#BEGIN erase "Erase"
The erase operation is designed to either erase a section of the painting to
the set background color for the canvas or to revert the erased area to
the originally loaded image.  (Note:  This is not the last saved image!)

The eraser is the style of the current brush, and the brush selection
window is accessible through the menu found by clicking mouse button
three on either the erase or brush icons.

See help on the "Brush" or on "Change Background..." under the Image menu of
the Painting Window for more information.

#BEGIN box "Box [Filled] [Region]"
The box operations paint either rectangles or squares using the current line
width. Pressing shift while moving the mouse after selecting the first point
will constrain the box to a square.

Selecting the 'center' option from the menu found by pressing button three on
the icon will define the first point as the center of the square with
the second point being on the perimeter.

Filled boxes are painted in the primary color/pattern and filled
with the secondary color/pattern for the canvas.

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN ellipse "Ellipse [Filled]  [Region]"
The oval operations paint either circles or ellipses using the current
line width.  Ellipses/circles are painted by selecting two points that
inherently define a box around the area for the ellipse.  Pressing shift
while moving the mouse will constrain the ellipse to a circle.

Selecting the 'center' option from the menu found by pressing button three on
the icon will define the first point as the center of the circle with the
second point being the radius.

Filled ellipses and circles are painted in the primary color/pattern and filled
with the secondary color/pattern for the canvas.

See "Line Menu" under the canvas menu bar for more information about 
line width and dash style.

#BEGIN freehand "Freehand Shape [Filled] [Region]"
Freehand shape operations allow the user to draw open or closed paths
with a pencil-like operation. Drawing is performed while the first
(left) mouse button is clicked and interrupted when the mouse button
is released. In case a new mouse click is performed, a straight line
segment is drawn between the last drawn position and the new cursor
position, and drawing is restarted. The operation is terminated by
clicking on the second (middle) mouse button, or by pressing the
"Return" key. The arrow keys allow to displace the current shape being
drawn. The "Escape" key cancels the operation and the "Backspace" key
gradually rewinds the operation towards the beginning.

Painting of the contour is done in the primary color/pattern. Filled shapes 
are filled in the secondary color/pattern. Border width is determined 
by the current setting for line width. In "Region Mode", the contour
determines a region of the corresponding shape when the operation is
terminated (middle button or "Enter").

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN polygon "Polygon [Filled] [Region]"
Polygon operations paint polygons as defined by a series of straight lines
between selected vertices.  Each new vertex is selected using the first mouse
button.  Ending this operation is done through pressing the second mouse
button or the Enter key. This results in the last vertex being created at 
the current position, and the polygon being closed and drawn
on canvas. During operation, the BackSpace key removes the last
point that has been entered, and the Escape key restarts the operation
from the beginning.

Polygons are drawn in the primary color/pattern, using the currently defined
line width and dash style, and filled in the secondary color/pattern.

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN spline "Spline Curve [Filled] [Region]"
The spline curve operation paints a connected curve made up of Bézier
cubics, or possibly a combination of Bézier cubics and line segments. 
The Bézier cubics are calculated in such a way that they interpolate as 
best as possible the selected points. Each new point is selected using 
the first mouse button. Pressing the second mouse button or the "Enter"
key ends the operation at the current cursor position. It is possible
to create a new portion of line segment or Bézier curve by pressing 
the Shift key - the previously selected point then becomes an angular
point. During the operation, the BackSpace key removes the last
point that has been entered, and the Escape key restarts the operation
from the beginning.

The spline curve can be either open or closed. The Open/Closed
property is selected by opening the menu of the spline curve operation
(click with the third mouse button on the icon). By pressing the
"Control" key during mouse motion, spline curves that ought to be
closed at the end of the point selection process are shown closed at
every step. This enables users to check the shape of the expected
curve before confirming the final point. The "Closed up" option has a
similar effect, except that it is no longer necessary to press the
Control key.

Spline curves are painted in the primary color/pattern and filled
with the secondary color/pattern. The boundary is drawn using the 
currently defined line width and dash style.

See "Line Menu" under the canvas menu bar for more information about line 
width and dash style.

#BEGIN select "Select Regions"
There are five operations for selecting regions:  

1) Select Rectangular Region
#NL
2) Select Elliptic Region
#NL
3) Select Freehand Contour
#NL
4) Select Polygonal Region
#NL
5) Select Spline Contour

All this selections ar available from the blue buttons located in the
same row as the corresponding drawing or filling action.

In the case of rectangular or elliptic regions, holding down the Shift key
while pressing the mouse button with constrain the region to be a
square or a circle, respectively.

By default, the selected region becomes semi-transparent when mouse
button one is pressed : (semi-)transparency is useful when the selected
region has to be positioned accurately with respect to the underlying
canvas. By pressing the spacebar, it is possible to
activate/disactivate transparency, while pressing <Ctrl><Space>
activates/disactivates the commutation between these two modes when
pressing mouse button one (in order not to activate/disactivate
transparency, one can also use mouse button three). Mouse button two
can be used to rotate the selected region.

The three possible modes used by these operations are set by opening
the option menu with button three on the operation icons:

All Colors 	        Select the entire region.
#NL
Omit Color Range	Select the region, excluding the
#NL
				specified range of colors.
#NL
Only Color Range	Select only the specified color range
#NL
				in the region.
#NL
See "Range Selection" for more information on choosing a range of colors
for these operations.

Operations that may be performed on selected regions include the ability
to move and resize them.  Holding shift down during resizing will constrain
the region to its original aspect ratio.  Holding shift down during moving
will constrain movement to horizontal or vertical.  

Note that moving a region will result in the original location being painted
in the current background color. See "Background Color..." under the Image
menu of the Paint Window for more information.

You can also use the cursor keys to move the region one pixel at a time (hold
down the Control key to move in larger steps).

#BEGIN fill "Fill"
The fill operation will paint an area around a selected pixel the current
primary or secondary color/pattern (based on which mouse button used).  The
area is determined by matching adjacent pixel values until a variation is
found.  Diagonal pixels are not considered adjacent.

Selecting the 'Change' option from the menu found by pressing button three on
the icon will enter Change Mode. In this mode, all pixels in the image that
have the same color as the selected one will be changed to the primary or
secondary color.

Selecting the 'Fill Range' option causes XPaint to consider not only pixels of
the exact same color as the selected one, but also pixels within the variance
(delta) set from the color selector found under the 'Select Range...' popup
menu item.

#BEGIN gradientFill "Gradient Fill"
The gradient fill operation will paint an area around a selected pixel with a
range of colors obtained by mixing the primary and secondary colors.
The area is determined by matching adjacent pixel values until a variation is
found.  Diagonal pixels are not considered adjacent.

The 'Fill', 'Change' and 'Fill Range' options in the popup menu work the same
as for the ordinary fill operation.

Linear, Radial, Conical or Square gradient fill can be selected by clicking
mouse button three on the Gradient Fill icon. Also, several parameters can be
adjusted using the 'Parameters' item here:

Angle
#NL
	Defines the tilting of the pattern. Valid range is
#NL
	-360 to 360 degrees.

Pad	If this value is positive, the area where one color
#NL
	blends into the other will be compressed, yielding
#NL
	a sharper transition. If negative, the transition
#NL
	will be smoother. Valid range is -49 % to 49 %.

Horizontal/Vertical offset
#NL
	Defines the center of the pattern. Valid range is
#NL
	-100 % to 100 %.
#NL
	This parameter has no effect for the Linear pattern.

Steps 
#NL
	The maximum number of colors that will be used
#NL
	for the transition from one color to the other.
#NL
	For non-TrueColor displays, it can be useful to
#NL
	limit the number of colors used to avoid running
#NL
	out of palette entries.  Very small numbers can
#NL
	also be used to get a 'blocky' effect. Valid range
#NL
	is 1 through 300.

#BEGIN fractalFill "Fractal Fill"
The fractal fill operation will paint an area around a selected pixel with a
range of colors obtained by mixing the primary and secondary colors.
The area is determined by matching adjacent pixel values until a variation is
found.  Diagonal pixels are not considered adjacent.

The 'Fill', 'Change' and 'Fill Range' options in the popup menu work the same
as for the ordinary fill operation.

Several different fractal patterns can be selected by clicking
mouse button three on the Fractal Fill icon.

#POP
#POP
#BEGIN canvas "4. Canvas Window"
The canvas windows hold a painting area for displaying or editing images.

In order to paint on the canvas, the user normally has first to select
a suitable painting tool by clicking on the icons of the global toolbox,
as well as a set of two colors or patterns, termed here the primary and
secondary patterns. Other parameters can also be adjusted, such as
the line width or the character font; once these choices have been
made, the user can proceed to apply the tool selected on the painting
canvas.

The top panel of the canvas window display a menu bar which gives
access to all file and editing operations, as well as to the selection
of parameters and image transformations. 

Below the menu bar, the top panel displays a small-scale copy of the
palette of available colors and patterns. On the left, the "eye" icon
allows to look-up the color of any pixel that is displayed on the screen.
The three disc near the eye are color selection switches. The circle
activates the selection of the primary color/pattern (usually the 
color/pattern of lines and of bounddaries), the filled disc activates 
the secondary color/pattern (usually meant to fill areas) and the 
filled disc with boundary activates the simultaneous selection of 
primary and secondary colors/patterns - so that any posterior change
will produce identical values for both selections. Another convenience
is that multiple clicks on any of the three discs allow to switch
primary and secondary colors/patterns.

On the right of the menu bar next to the position indicator, one finds 
the "line parameter" widget (linewidth, dash style, joins and caps). 
Below this widget, on the right of the panel, one finds four status
buttons which respectively activate the color/pattern selector, raise
the global toolbox, the brush selector or the font selector. In case
the "simplified floating menu is disabled", all these options become
also selectable from the popup menu, by clicking with button 3 (right
button) on the painting canvas.

It should be observed that each painting canvas has its own set of 
primary and primary patterns; on the contrary, when a tool is
selected, it applies simultaneously to all canvases. See help on each
specific paint operation for its use.

#PUSH
#BEGIN fileMenu "4.1. File Menu"
The file menu on the painting window is for saving information associated
with the image displayed on the current paint canvas. 

XPaint runs on a variety of displays.  Saving
images will adapt them to the current display type (i.e., a color image 
loaded on a greyscale screen will be saved as a grey image).

See "Image Formats" for a description of the image formats usable
by XPaint.

Open Image...
#NL
	Opens a file browser which can be used for
#NL
	exploring the file systems and salecting a
#NL
	file to open as an image. Unless the
#NL
	"Ongoing" button is activated, the browser
#NL
	will close when the file is being loaded.

Save
#NL
	Save the current image with the original
#NL
	filename and format.  If this is a new
#NL
	image, perform the "Save As" operation.

Save As
#NL
	Save the current image with the specified
#NL
	filename and format (default is TIFF).

Save Region...
#NL
	Save the selected region, in the original
#NL
	form that it was selected (width, height and
#NL
	rotation).  Odd-shaped regions will be saved
#NL
	as rectangles filled with the background
#NL
	color.  If the output format supports image
#NL
	masks (e.g., TIFF, PNG, XPM), then this
#NL
	information will also be saved.  See "Load
#NL
	Clipboard..." under the toolbox file menu
#NL
	for more information about odd-shaped
#NL
	images.

Load Clipboard...
#NL
	Open an image file into the XPaint clipboard
#NL
	for pasting.  Images that have been saved in
#NL
	a format supporting odd-shaped regions will be
#NL
	loaded as they were selected, otherwise all
#NL
	images are rectangular.  See "Paste" and
#NL
	"Save Region..." under the Edit and File menus
#NL
	of the Painting Window for more information.

Revert...
#NL
	Reloads the last saved image. This is
#NL
	equivalent to closing without saving
#NL
	and then opening the original file.
#NL
	You are asked for confirmation. If
#NL
	the image has not been changed since
#NL
	the last save, this operation does
#NL
	nothing.

Loaded files...
#NL
	Shows the list of all image files which have
#NL
	been called from the command line, or all newly 
#NL
	created files. The widget also contains buttons
#NL
	which can modify default zoom, DPI values,
#NL
	cycle bounding box mode, page number, etc.

Print...
#NL
	Opens the "Print Utility" widget. Check the
#NL
	corresponding sections for more details.

External viewer...
#NL
	Pipes the last saved image to an external viewing
#NL
	program. Default is "xv". This can be modified by
#NL
	redefining the 
#NL
	"Canvas.extern*form*viewercmd*string"
#NL
	parameter in the app-defaults file.

Close
#NL
	Close the current painting window, saving
#NL
	the image if desired.

#BEGIN editMenu "4.2. Edit Menu"
The edit menu provides for a set of operations that interact with the
current selection and the paint clipboard.  All options in this menu
are also accessible through button three on the painting canvas.  
The clipboard is an off-screen image that is loaded by selecting
a region via one of the five area selection tools.

See "Load Clipboard..." in the "File Menu" for another alternative
to load images from a file and "Change Background..." under the
"Options Menu" for more information on the background color.

Undo
#NL
	Reverse the last performed operation.
#NL
	Multiple undos are possible; see 'Undo Levels..'
#NL
	in the 'Image' menu.
#NL
	If a region is selected, and you have not moved
#NL
	or resized it, the last region operation is undone.

Redo
#NL
	Cancel the effect of the last undo.
#NL
	This must be done immediately after an undo or
#NL
	redo (before drawing anything new on the canvas).

Undo Levels...
#NL
	Changes the number of consecutive changes
#NL
	that can be undone or redone. Note that each
#NL
	undo level uses as much memory as the image
#NL
	itself, so large numbers can use up a lot of
#NL
	memory.

Refresh
#NL
	Refreshes the painting window. Should be useful
#NL
	only when the X display gets garbled; this can
#NL
	happen especially for some buggy X servers.

Cut
#NL
	Load the originally selected region into both 
#NL
	the XPaint and X server clipboards and
#NL
	change the area on the screen to the background
#NL
	color.

Copy
#NL
	Load the originally selected region into the
#NL
	XPaint and X server clipboards.

Paste
#NL
	Place the image in the clipboard onto the
#NL
	canvas at the last position where button one
#NL
	or two was pressed.  Images are first searched
#NL
	for in the X server clipboard and then the
#NL
	internal XPaint clipboard.

Clear
#NL
	Remove the current selection from the paint	
#NL
	canvas.

Select All
#NL
	Select the entire image on the canvas.
#NL
	(Note:  This does not use the color range options
#NL
	that the select-area operators from the toolbox do!)

Unselect
#NL
	Un-selects the current region, if any, and frees
#NL
	the corresponding data structures from memory.

Duplicate
#NL
	Perform both the copy and paste operations in one

Erase All
#NL
	Erases the entire image on the canvas.

Clone canvas
#NL
	Duplicates the whole canvas window into a new
#NL
	window, with the same zoom value.

Clone with Zoom
#NL
	Duplicates the whole canvas window into a new
#NL
	window, while additionally performing a 
#NL
	resize operation according to the selected
#NL
	zoom value (the zoom value becomes equal to 1
#NL
	in the newly opened window). Interpolation of
#NL
	pixels can be enabled (default) or disabled,
#NL
	according to the option specified in the
#NL
	"Options" menu.

Screenshot
#NL
	Grab a rectangle from the root window and load
#NL
	that rectangle in the XPaint clipboard. The left 
#NL
	button is used to select opposite corners of the 
#NL
	rectangle, the middle button to grab a complete
#NL
	window and the third button to cancel the 
#NL
	operation.

#BEGIN tool_line "4.3. Line Menu"
The line menu sets the value of the line width.  This value is used by all
operations that paint any type of line, including the borders of boxes,
ellipses and polygons.

It is also used to set the line and dash style. A dash style is
indicated by a sequence of at most 72 characters = and -, for 
example =========---==--. The = characters indicate pixels which will 
be drawn, and the - characters indicate pixels wchich will not be 
drawn. A continuous line should be indicated by a single character = 
(a string containing only characters = will also produce a 
continuous line).  The line style has two parameters, cap style 
(0 Default, 1 None, 2 Butt, 3 Round, 4 Projecting) and join style
(0 Default, 1 Miter, 2 Round, 3 Bevel).

#BEGIN tool_font "4.4. Font/Text Menu"
This menu selects the current font to use for the text operation and
optionally edits the text which is to be inserted.

There are a few default font choices listed, but all fonts known to
the X server are available through the font browser. T

Note:  Changing the cursor position while inserting will start a new
insertion, and therefore will not allow any more backspacing over 
previously inserted text.

See "Font/Text Selector" for more information on its use.

The menu offers an option "Compose text...", which allows you to
compose a structured text, possibly marked with size indications,
tilt, or vertical expansion of the font. It is possible to choose and
vary the colors, to rotate and translate parts of text, to set the
line spacing. The "Display" button then creates a region containing
the text, that you just have to drop at the desired location of the
canvas, via the action "Write text/formula here".

An analogous "TeX/LaTeX input..." tool is used to compose
formulas using the TeX system, as long as it is installed. Xpaint must
therefore be compiled with the libdvipgm library.  #BEGIN regionMenu
"4.5. Region Menu" This menu provides operations that can be applied
to the currently selected region.  See the "Select Regions" item under
the toolbox Painting tools for information on how to select regions.

Note:  The 'Undo' option found under the Edit menu does not work
on these operations! Use the 'Reset' option of the Region menu,
or the 'Undo' option of the Filter menu instead.

Flip X Axis
#NL
	Flip the current region horizontally.

Flip Y Axis
#NL
	Flip the current region vertically.

Rotate By
#NL
Rotate...
#NL
	Both of these operations allow for rotating
#NL
	the current region by a specified number of
#NL
	degrees.  Rotation may also be done
#NL
	by pressing button two on the selection.
#NL
	Pressing the Shift button while doing this
#NL
	constrains the rotation to multiples of
#NL
	15 degrees.

Linear Transformation...
#NL
	This operation applies to the current region
#NL
	a linear transformation defined by certain
#NL
	parameters specified by user :
#NL
	[ dilation in x, in y, inclination, rotation ].

Reset
#NL
	Return the current image to its original
#NL
	size and orientation.  Note:  None of the
#NL
	image processing operations will be undone.

Expand...
#NL
	Rescale the region with certain horizontal and vertical
#NL
	expansion ratios, with or without an interpolation of pixels.

Downscale...
#NL
	Downscale the region with certain horizontal and vertical
#NL
	reduction factors, with or without an interpolation of pixels.

Edit Region
#NL
	Open a new canvas containing a copy of the 
#NL
	selected region, in the original form that 
#NL
	it was selected (width, height and rotation).
#NL
	Odd-shaped regions will be saved as rectangles
#NL
	filled with the background color. See "Load
#NL
	Clipboard..." under the canvas file menu
#NL
	for more information about odd-shaped
#NL
	images.

Crop to region...
#NL
	Discard all portions of the image outside the region.
#NL
	This operation cannot be undone; therefore, you are
#NL
	required to confirm it.

Create mask of Region
#NL
	This operation hides the blank parts of the region,
#NL
	so that they become invisible and are no longer
#NL
	drawn when the region is dropped onto the canvas.

Merge region
#NL
	Merges the region with the canvas, taking into
#NL
	accounts the pixels in a weighted way, with a weight
#NL
	proportional to their difference with the white pixels
#NL
	(the blank pixels therefore have zero weight, and are
#NL
	not taken into account).

Autocrop...
#NL
	Changes the size of the current canvas by
#NL
	cutting away any borders. The border color
#NL
	is defined as the color common to at least
#NL
	two corners. If no two corners have the same
#NL
	color, nothing is done.
#NL
	This operation is not reversible and 
#NL
	affects the actual image size.
#NL

Complement Region
#NL
	Takes the complement of the current region
#NL
	with respect to the whole canvas. The region
#NL
	must not have been displaced.

Delimit Region
#NL
	Delimits a region according to 6 different
#NL
	possibilities offered by the right popup:
#NL
	select a connected/non connected monocolor 
#NL
	region, respectively a region corresponding
#NL
	to a certain color range defined by the
#NL
	ad hoc selector, or the complement of 
#NL
	regions of any of these 3 types. The selection
#NL
	takes place when a mouse click is performed on
#NL
	the canvas. Once activated but not yet engaged,
#NL
	the operation can be canceled via the 7th option
#NL
	"Cancel" on the right popup menu.

OCR
#NL
	Performs OCR (Optical Character Recognition)
#NL
	on the selected area. Default OCR analyzing
#NL
	programs wich can be used are 'cuneiform'
#NL
	and 'ocrad'. This can be changed by editing 
#NL
	the 'xpaint_ocr' script in share/bin.

#BEGIN filterMenu  "4.6. Filter Menu"
The filter menu provides a set of image processing operations
that can be applied to the currently selected region.  See
the "Select Regions" item under the toolbox Painting tools
for information on how to select regions. In case no region has
been selected, the entire paint canvas is selected as the region
to which the filters shall be applied. 

Any filter operation can be undone by means of the "Undo Last" option,
but this can be applied only once to the very last filter.

Invert
#NL
	Inverts the colors of the selected region
#NL
	(e.g., black to white).

Turn into Greyscale
#NL
	Converts all colors in the image to greyscale.
#NL
	The formula used for grey scale conversion is
#NL
	    grey_level = (30*R + 59*G + 11*B)/100

Normalize Contrast
#NL
	Normalizes the contrast by forcing the lightest pixels
#NL
	to white, the darkest pixels to black, and linearly
#NL
	rescaling the ones in between.
#NL
	You are queried for Black and White levels in %.
#NL
	Pixels darker than the Black level will become black,
#NL
	and pixels brighter than the White level will become
#NL
	white. The pixels in between will be rescaled linearly.
#NL
	'100 %' refers to the brightest pixel in the image.

Transformation RGB/Gamma...
#NL
	Modifies the Red, Geen, Blue components of each Pixel 
#NL
	by means of a suitable transformation process, which is
#NL
	of one of the following types:
#NL
	    R=0, G=1, B=2, max=3, min=4, mask=5,
#NL
	    gamma=6, threshold=7, linear=8.
#NL
	The types R,G,B extract color channels, the types 3,4
#NL
	produce a grey level image corresponding to the maximum,
#NL
	resp. minimum of color channels, type 5 creates a black
#NL
	and white mask specifying pixels differing from default
#NL
	background, and type 8 (linear) allows to combine color
#NL
	channels via an arbitrary linear combination. Type 7 is
#NL
	a uniform linear correction of gray levels determined
#NL
	by prescribed minimum and maximum thresholds.
#NL
	The gamma correction process (type 6), is more subtle.
#NL
	Namely, it applies a non linear correction
#NL
	c --> 255*(c/255)^{2^{-gamma}} for each color channel.
#NL
	As a result, the corresponding color brightness is 
#NL
	increased or decreased according to the sign of
#NL
	the corresponding gamma parameter. The maximal range
#NL
	for the gamma parameter is [-12.0 .. +12.0]. Above
#NL
	+12.0, the color intensity becomes maximal (=255) 
#NL
	unless the value was equal to 0 initially, and below
#NL
	-12.0, the color intensity becomes equal to zero,
#NL
	unless it was initially maximal and equal to 255.
#NL
	Two opposite gamma values tend to compensate each 
#NL
	other, at the expense of a degradation of colors
#NL
	when the gamma shifts are too large.

Floyd-Steinberg Filter...
#NL
	Reduces the number of colors in the image, by means
#NL
	of the clevel Floyd-Steinberg algorithm. Through a
#NL
	suitable "color diffusion", the algorithm minimizes
#NL
	degradation of the image. Grey images can be reduced
#NL
	to only 2 colors (black, white) and color images can
#NL
	be reduced to only 8 colors (black, white, red, green,
#NL
	blue, yellow, magenta, cyan), while still retaining a
#NL
	recognizable color distribution. Any number of colors
#NL
	from 2 to 256 per channel can be chosen. In case 256 is
#NL
	selected, the channel is left untouched. The "mid range"
#NL
	value only has marginal effects, only visible when reducing
#NL
	the image to very few colors.

Quantize Colors...
#NL
	Reduces the number of colors in the image. The
#NL
	algorithm selects the set of colors that gives
#NL
	the best result and then replaces the original
#NL
	colors with the best match in the new color set.
#NL
	You can choose the number of colors to use,
#NL
	from 2 to 256. No diffusion is performed as in 
#NL
	the case of the Floyd-Steinberg algorithm; as
#NL
	a result, a "zoning effect" can become visible.

Solarize...
#NL
	Inverts pixels with a value larger than the 
#NL
	specified threshold. This simulates what happens
#NL
	to a photographic film that is exposed to light
#NL
	during development. Works best for greyscale
#NL
	images. You are queried for the threshold (1-99 %).

Sharpen
#NL
	Applies an image processing algorithm in an
#NL
	attempt to increase the detail on the
#NL
	selected region.

Merge...
#NL
	Merges the selected region with the underlying canvas
#NL
	by taking a certain combination of the pixels which
#NL
	are to be superposed. The combination can be either 
#NL
	linear or progressive (linear combination with variable
#NL
	coefficient approaching zero near the boundary), or
#NL
	given by a maximum or minimum of the pixel values.

Smooth...
#NL
	Attempts to blend the colors of the region
#NL
	by averaging the pixel's color values with
#NL
	those of its neighbors.

Directional Smooth
#NL
	Similar to Smooth, but avoids smearing edges
#NL
	by applying a more sophisticated algorithm.
#NL
	The effect is less pronounced than for Smooth.

Despeckle...
#NL
	Tries to remove scanning artifacts etc. by replacing 
#NL
	each pixel by the median of the pixels inside the
#NL	
	n x n mask centered around that pixel. You are
#NL	
	queried for the mask size; this must be odd and
#NL
	larger than 1.

Edge Detect
#NL
	Performs an image processing edge
#NL
	detection.

Emboss...
#NL
	Converts the selected region to a grey image
#NL
	that is highlighted such that the details
#NL
	appear to stand out from the screen. Takes
#NL
	two parameters, namely background grey value
#NL
	(128 by default) and scaling ratio (default 100).

Oil paint...
#NL
	Does an effect similar to an oil painting.
#NL
	You are queried for the mask size, which must
#NL
	be an odd integer. Recommended values range
#NL
	from 3 to 15. Higher values result in a more
#NL
	pronounced effect.

Add Noise...
#NL
	Add random noise to the image, giving a 'grainy'
#NL
	appearance. You are queried for the maximum
#NL
	noise value. Recommended values range from 
#NL
	5 to 50. Higher values result in a more
#NL
	pronounced effect.

Spread...
#NL
	This operation swaps each pixel in the region with
#NL
	a random pixel near it, giving an effect similar to
#NL
	frosted glass. You are queried for the maximum
#NL
	distance. Good values range from 1 to 10.
#NL
	You can also specify how many iterations you want
#NL
	performed. This is equivalent to manually selecting
#NL
	the operation that many times.

Pixelize...
#NL
	Makes the image look low resolution. This works by
#NL
	replacing each 'megapixel' with the average color 
#NL
	within that region. You are queried for the megapixel
#NL
	size; this can be specified as square (e.g., '5') or 
#NL
	rectangular (e.g., '2x4').

Distortion
#NL
	This operation applies to the region a certain
#NL
	distortion which does not modify the pixels on
#NL
	the boundary but displaces them more and more 
#NL
	towards the center. It takes two scaling 
#NL
	parameters for directions X and Y respectively.

Perspective...
#NL
	This operation applies to the region a certain 
#NL
	projective homographic transform, which can be
#NL
	used to modify the perspective under which the
#NL
	scene is viewed. This procedure can be applied to
#NL
	rectify a distorted rectangle back to a rectangle,
#NL
	or to create an artificial perspective effect.
#NL
	The procedure requires 4 points xi,yi to be given
#NL
	as well as their transforms x'i,y'i, entered
#NL
	normally clockwise. In order to simplify the
#NL
	input, a quadruple of points can also be specified
#NL
	as a rectangle, through one of the alternatives
#NL
		rectxy  x'1,y'1  x'3,y'3
#NL
		rectwh  x'1,y'1  w,h  (width,height)
#NL
		rect  dx,dy  rw,rh
#NL
	where dx,dy = displacement of center (default 0,0),
#NL
	rw,rh = width, height ratios (default 1.0,1.0),
#NL
	and rect without parameters applies the defaults.
#NL
	Coordinates are expressed as pixel numbers.

Blend
#NL
	This operation colors each pixel in the region
#NL
	with a weighted average of the center color and
#NL
	the color on the edge that intersects a line drawn
#NL
	from the center to the pixel in question.
#NL
	The result is to 'blend the region out of existence'.

User Defined Filter...
#NL
	When a filter has been compiled as a C script,
#NL
	this menu option becomes available as a new filter.
#NL
	Users can thus program whatever filters then need.
#NL
	Some simple examples are provided from the
#NL
	C script editor, to which we refer for more details.

Repeat Last
#NL
	This applies the last filter you used again, without
#NL
	querying for any parameters.

Undo Last
#NL
	Undoes the effect of the filter applied in the last
#NL
	instance, and resets the selected region in its former
#NL
	state. If several filters have been applied 
#NL
	consecutively, only the last one can be reverted.

#BEGIN selectorMenu  "4.7. Options/Selectors Menu"
The "Options/Selectors" menu gives access to all popups and option 
selectors which may affect the painting operations and the graphic 
canvas behavior.

Fat Bits Editor...
#NL
	Brings up the Fat Bits editor, which allows
#NL
	for editing an enlarged area of the current
#NL
	image without having to enlarge the entire
#NL
	image.

Color and Pattern Editor...
#NL
	Opens the Color and Pattern Editor, or raises it
#NL
	if the popup-window is already open. This popup 
#NL
	is also raised by pressing the appropriate button
#NL
	on the top panel

Select Color Range...
#NL
	Opens the "Color Range Selection" window, or
#NL
	raises it if the popup-window is already open.
#NL
	This widget can be used to select color domains
#NL
	for the various fill operators and region
#NL
	selection tools. See "Color Range Selection"
#NL
	for more details.

Change Background Color...
#NL
	Opens the "Background Color" popup-window.
#NL
	This popup-window allows to change the
#NL
	background color for the current image
#NL
	(default color is white).
#NL
	This is only used when a region is
#NL
	erased or cut from the current image and
#NL
	when odd-shaped regions are saved. See
#NL
	"Color Wheel" under the "Pattern Editor" for
#NL
	more information on selecting a color.

Toolbox...
#NL
	Raises the Toolbox window, in particular if it
#NL
	has been iconified.

Brush Selector...
#NL
	Opens the Brush Selector, or raises it if it is
#NL
	already open. This window can also be reached
#NL
	from the appropriate button on the top panel.

Font/Text Selector...
#NL
	Opens the Font Selector, or raises it if it is
#NL
	already open. This window can also be reached
#NL
	from the appropriate button on the top panel.
#NL
	It also allows editing text samples.

Magnifier...
#NL
	Opens the interactive magnifier. The magnifier
#NL
	can take screenshots and perform various
#NL
	transformations on them (zoom, 90° rotations,
#NL
	horizontal or vertical rotation, symmetries, 
#NL
	smoothing...)

Connect Tablet
#NL
	In case a graphics tablet is used in combination
#NL
	with an ad hoc user space driver (such as the
#NL
	Wacom tablet driver 'wcmtd' provided on Sourceforge
#NL
	in the 'deskwrite' directory), that driver can be
#NL
	launched and 'linked' to the canvas from which
#NL
	it is called. Notice that the driver can also be
#NL	
	specified from the Toolbox File menu option
#NL	
	'New With Size' as a replacement of the Height
#NL	
	string. A canvas with the appropriate aspect
#NL	
	ratio will then be created. This works at least
#NL	
	with the 3 available drivers bbtd, nytd, wcmtd.

C script Editor...
#NL
	Opens the C Script Editor window, and lets that
#NL
	script be compiled if needed. This is useful
#NL
	e.g. for programmers who want to design their
#NL
	own filter routines, or want to create images
#NL
	or diagrams programmatically.
#NL
	The C script editor also allows the creation
#NL
	of layered XPaint files *.lxp, aimed at combining
#NL
	an arbitrary collection of images into a new
#NL
	merged image.

VXP vector data Editor...
#NL
	Opens the VXP vector data Editor.
#NL
	The main text window is used to view the list of
#NL
	graphic operations performed, with all the
#NL
	necessary parameters. The resulting *.vxp file can be
#NL
	converted to PostScript, TeX or Deskwrite formats,
#NL
	or displayed, optionally after applying a zoom factor.
#NL
	Note: non-vector operations are ignored

Change Size...
#NL
	Changes the size of the current canvas by
#NL
	cutting away or adding area on the right and
#NL
	lower sides.  This operation is not
#NL
	reversible (except by 'Revert') and affects
#NL
	the actual image size.

Change Zoom...
#NL
	Enlarges the working image by the specified
#NL
	scale.  This does not affect the size of the
#NL
	image for saving, etc.

Default Size and Zoom...
#NL
	Select default width/height/zoom values for
#NL
	next canvas windows to be opened.

Blinking regions
#NL
	If set, the option also regions to become
#NL
	semi-transparent while being clicked. This
#NL
	makes it easier to move the region around
#NL
	and adjust it with respect to the underlying
#NL
	image.

Interpolation for reduction
#NL
	If set, the option will enable interpolation of
#NL
	adjacent pixels in operations such as Expanding, 
#NL
	Downscaling, Resizing regions and images. The 
#NL
	resulting rescaled region will appear smoother,
#NL
	as a possible trade-off to sharpness of images.

Snap
#NL
	Turns on/off constraining the current x and
#NL
	y positions of cursor/mouse, which can be
#NL
	restricted to be multiples of a given spacing
#NL
	in terms of a number of pixels.
#NL
	The corresponding 'grid' can be set to be
#NL
	visible or not. When set, this constraint
#NL
	affects all painting operations.

Snap Spacing...
#NL
	Sets the distance between consecutive points on
#NL
	the 'snap grid'.

Visible Grid
#NL
	Turns on and off on Fatbits Editor a visible black
#NL
	grid between the original pixels of images, at least
#NL
	when the zoom value is larger than 1.  This grid
#NL
	is only shown for the sake of editing commodity. 
#NL
	It does not affect the actual image.

Grid Parameters...
#NL
	This is used to fix certain grid parameters
#NL
	(mode of representation, color of the grid lines...)

Simplified Floating Menu
#NL
	When set, the right click canvas menu only
#NL
	shows the Edit submenu. When unset, it shows
#NL
	all options as a tree of menus and submenus.

Hide Menu Bar
#NL
	Hides or shows again the menu bar of the canvas
#NL
	window.

Help
#NL
	Opens the help browser.

#PUSH
#BEGIN patternSelector   "4.7.1. Color and Pattern Selector"
The Color and Pattern Selector is the place from which colors and
patterns can be selected and activated for use on the painting canvases. 
It can also be used to modify the palette of available patterns. 

#PUSH
#BEGIN openPatSel "Opening the Color/Pattern Selector"
The Selector is most conveniently opened by clicking on the appropriate 
button of a painting canvas - in second position at the right of the 
menu bar on the top panel. This button displays an hexagonal icon 
showing the active primary and secondary colors/patterns, such as they 
are in effect when painting operations are applied.

#BEGIN topPatSelStructure "Top Panel of the Pattern Selector"
The Pattern Selector displays on the top menu panel the primary 
and secondary patterns of the associated Painting Canvas (in case 
several canvases are open, this is the one from which the Selector 
has been opened or re-opened in the last instance).

On the right of the top menu bar, an icon is displayed showing an
hexagonal area. The border of this area is drawn with the active primary 
pattern, and its interior with the active secondary pattern. The border
linewidth coincides with the current linewidth of the painting canvas.
A click on the hexagonal icon raises the painting window, without any
effect on the various painting parameters.

On the other hand, a click on the primary or secondary pattern icon
selects one or the other, and sets correspondingly the arrow.

#BEGIN leftPatSel "Selection of Colors"
The central left panel of the Pattern Selector displays the colorwheel
and the buttons used for color selection. The "Lookup" button allows
the user to select any color available on the screen, whilst the
"Record" button adds the selected color to the list of colors
available from the Palette shown in the bottom panel. See "Color
wheel" for more details.

Note:  Manipulating colormap entries effects the canvas immediately
and does not revert when "Cancel" is chosen.

#BEGIN rightPatSel "Selection of Patterns"
The central right panel displays a small graphic canvas in which new
patterns can be created or edited. Patterns are by default 24x24 in
size, but may be set to any size through the "Size" menu.  The other
menus available provide similar functionality to those in the paint
window and pattern editing uses the normal paint operations.

Patterns may be individually saved through the "Save As" option in the
"Canvas" menu or saved globally with the "Save Palette..." option
in the "Palette" menu. Previously created palettes can be loaded with 
the "Load Palette..." option. See "Palette Configuration Files" for 
more details.

#BEGIN bottomPatSel "Palette of Colors and Patterns"
The bottom panel of the pattern selector displays the list of
available colors or patterns, including the initial ones and those
which have been previously created and added. 

A simple click on one of the icons activates it as the primary or
secondary color/pattern, according to the psition of the upper
arrow. 

A double click on an icon puts it in "Edition mode", as visualized by
a red rectangular mark; the effect of pressing on one of the "Record"
buttons is then to replace the corresponding color/pattern by the
color/pattern being edited from the central panel. 

Finally a double "double click" on a pattern icon loads that pattern
on the graphical canvas for further editing. 

Button 3 (right button) activates a popup menu offering similar
options (mark icon in editing mode, unmark icon, load pattern on
canvas, remove pattern).

#BEGIN grabpattern "Grab Colors and Patterns"
A quick method for adding a new color or pattern is found by using the 
"Lookup" and "Grab" buttons.  These buttons allow the user to select 
any color or any colored area available on the screen. A further click on
the "Record" button will then record the selection and add it to the
bottom palette. It should be noted that if a color is already found in 
the palette, the action of the "Record" button is simply to make it
active.

Note: The current palette can be saved for later use with the 
"Save Palette..." option from the "Palette" menu.

#BEGIN colorwheel "Color Wheel"
The XPaint color selection allows access to both the HSV or RGB color
space models.  The color wheel along with the value
slider represents HSV, while the red, green, and blue sliders are for
manipulating the color in an RGB space.  Modifications in either of
these color spaces will effect the other.

Colors can be selected on the color wheel by using the mouse to drag
the selection circle or to click on a desired color.   Changes
to value will determine the brightness of the chosen color.  Colors
can also be modified through the red, green, or blue sliders or by
entering values in the text fields.

The "Match" button will set the current color by allowing the user to
select any color on the screen.  The exact color will be determined
using the colormap of the selected window.

#BEGIN configfile "Palette Configuration Files"
Colors and patterns appearing on the bottom panel of the Pattern Selector
are loaded each time the selector is opened, according to certain
priority rules:
#NL
	.XPaintrc in the user's home directory
#NL
	.XPaintrc in the current directory

Note:  Color/pattern changes affect both primary and secondary palettes.

#POP
#BEGIN range_select "4.7.2. Color Range Selection"
This window pops up when you click the "Select Color Range" button under 
the "Selectors" canvas menu popup. Its purpose is to select a range of 
colors for use with the select region operations.  The color
range is determined by setting a base color and the amount of variance
in each of the RGB values around this color.  Colors are considered in
this range if they match a value based on the base color +/- the given
variance.  Default base color is white.

The "Pixel Delta" button allows the user to choose another color that will
be used to calculate the variance from the base color.

More information on colors and the use of the color wheel may be found
under the "Color and Pattern Selector" on the "Painting Window".

#BEGIN brush_selector "4.7.3. Brush Selector"
The Brush Selector is a small popup window from which the current brush can
be set or changed. The selection of the brush only affects the "Brush"
and "Erase" tools. 

The initial brushes are defined at compile time and loaded from the
'bitmaps/paint*.xpm' included files.

The user can add new brushes through .XPaintrc configuration files.
The syntax is
#NL
	brush BeginData
#NL
	...
#NL
	EndData
#NL
and is entirely similar to the syntax used for black and white patterns.
(A color pattern would also be accepted, but in this case only the black
pixels are used to define the shape of the brush; the other pixels have
the same effect as white pixels, i.e. no effect).

The simplest way is to create a black and white pattern, save it into
a new palette, and then change the identificator 'pattern' by 'brush' 
with a text editor.

#BEGIN font_browser "4.7.4. Font/Text Selector"
The font selector is designed to allow any available font to be used for
painting with the text operation. This widget also incorporates a
small text editor which can be used to edit text samples. It is possible
to include certain formatting commands (selection of fonts, font properties,
color of text, page layout adjustments...), or to load a file which has been
produced with an external text editor.

Do not forget to click on the "Apply" button so that the selection of
font and text becomes really effective.

#BEGIN script_editor "4.7.5. C Script Editor"
The C script Editor can be used to write a script in language C,
defining e.g. a programmable filter. 

This possibility will appeal to programmers who want to design their
own filter routines, or create images and diagrams programmatically.

The "Compile" button compiles the C script as a shared ???.so library,
and, if successfull, links dynamically that library to XPaint.

The C script editor also allows the creation of layered XPaint files
*.lxp, aimed at combining an arbitrary collection of images into a new
merged image. One an appropriate C script has been defined, click on
the the button "Build LXP" to create the *.lxp file.

Several examples will be found in the share/filters subdirectory. Notice 
that you can use this feature only if gcc and a development environment
has been installed on your system.

#BEGIN vxp_editor "4.7.6. VXP vector editor"
The purpose of the VXP vector editor is to process the graphical elements
produced by Xpaint in the form of vector data.

This data can be saved in a * .vxp file, and converted to another vector
format. In particular, the 'vxp2ps' utility (partially) converts the data
into a PostScript file, and the 'vxp2dkw' program turns them into deskwrite
format.

#POP
#BEGIN zoomMenu  "4.8. Zoom Menu"
The "Zoom Menu" changes the zoom resolution of the canvas on the fly.
Values range from 1 to 16 while zooming in, and from 1:2 to 1:9 while
zooming out. When typesetting values in a text box or on the command line
1:3 can be written either :3 or -3 interchangeably.

#BEGIN alphaMenu  "4.9. Alpha Menu"
Gives access to manipulating the alpha channel (i.e. the transparency 
levels of an image). Internally, each pixel is coded as Red, Green, Blue
values from 0 to 255, and optionally a transparency level "Alpha"
from 0 to 255. When unset or equal to 255, the image is fully opaque
(on the other hand, when the alpha level is set and equal to 0, the
image is fully transparent).

#PUSH
#BEGIN mode_alpha_RGB "4.9.1. Mode: RGB"
Shows only the RGB values as when the image is fully opaque.

#BEGIN mode_apha_RGBT "4.9.2. Mode: RGB+transparency"
Shows the image according to its transparency levels, above a background
of the given default background color.

#BEGIN mode_alpha_RGBA "4.9.3. Mode: RGB+alpha"
(Default mode when alpha levels are set). The opaque parts are shown as
usual, but the transparent ones are shown on a grey 12x12 grid which is
suggestive of the transparency.

#BEGIN mode_alpha_alpha "4.9.4. Mode: alpha"
Shows the alpha channel, represented as a grey level image.

#BEGIN mode_alpha_parameters "4.9.5. Alpha parameters"
Defines the alpha channel background and foreground values (defaults
being 0 and 144 respectively), as well as the threshold value used 
to produce a mask of alpha levels for image types which only support 
masks rather than full alpha levels; the default threshold has been
set to 127 for XPaint.

#BEGIN mode_alpha_create "4.9.6. Create Alpha channel"
Creates a uniform alpha channel with the default alpha foreground value.

#BEGIN mode_alpha_save "4.9.7. Set as Alpha channel"
Sets the selected region (which is typically selected from the 
clipboard/memory box) as the alpha channel. If the selected region is
not a grey level image, it is first converted to grey levels by the
standard procedure.

#BEGIN mode_alpha_edit "4.9.8. Edit Alpha channel"
Opens the alpha channel as a grey level image in a separate canvas window.
In this way it can be edited with the full array of all available tools.
That image can then be put in the clipboard/memory box, and can later be
set again as the alpha channel of the original image.

#BEGIN mode_alpha_memory "4.9.9. Memorize Alpha channel"
Saves in the memory box the alpha channel of the canvas as a grey level 
image.

#BEGIN mode_alpha_erase "4.9.10. Erase Alpha channel"
The alpha channel is erased from the image. The image becomes opaque
and appears in pure RGB mode. The erased alpha channel is however 
temporarily saved as a grey level image in the memory box.

#POP
#BEGIN resizeToggle  "4.10. Resize Toggle #"
When set, the "Resize button" marked with the symbol # allows to drag 
the canvas area with the mouse to resize the drawing area; clicks are to
be performed near the right bordure or the lower bordure of the canvas
area.

#BEGIN positionField  "4.11. Position Indicator"
Shows the numerical values (x, y) of the mouse cursor on the canvas,
and/or windows (width, height) when resizing the canvas.

#BEGIN memoryBox  "4.12. Clipboard/Memory Box"
This box (usually shown as empty when starting up XPaint) is used to 
put and recall regions in memory. A right click fires up a menu which
allows to store/recall/edit/delete/scroll items in the memory box.
It is very handy e.g. for exchanging parts of images drawn on different
canvas windows. Also used for handling deleted alpha channels or
saving canvases which are being resized. The clipboard/memory box can
be filled at start up by images specified on the command line, 
right after the option switch /c.

The right click menu gives also access to certain useful operations
such as:
#NL
- extraction of the Alpha Channel of an image;
#NL
- creation of a black & white mask delimiting the part of the 
#NL
  region whose color differs from the selected background color
#NL
  (white by default);
#NL
- extraction of the Red-Green-Blue-(Alpha) components of an image;
#NL
- merging Red-Green-Blue-(Alpha) components into a combined image.

#BEGIN statusButtons  "4.13. Status buttons and widgets"
On the right of the top panel, the 'line widget' shows graphically the
line width, color and style. Clicking on it raises the line parameter
popup. Below are 4 clickable buttons showing the status of current
graphical operations:

- The primary/secondary color selection.
#NL
- The drawing tool being used.
#NL
- The brush being used
#NL
- The size of the currently active font 

Clicking on any of them raises the corresponding menus. 

Below the main menu bar, one finds a widget which gives a quick access to
predefined colors and patterns. The "eye" area launches the color 
look-up action, while the 3 circular areas switch the color selection 
mode between primary/secondary/both colors.

#POP
#BEGIN printMenu "5. Print Utility"
Opens the "Print Utility". From there, the size and position of the image
on a pages can be adjusted arbitrarily. The horizontal and vertical sizes
can be set simultaneously or not.

There are toggles for Portrait and Landscape modes, as well as for
printing to a file or to a printer.  The default PostScript resolution 
is 72 dpi, but this can be increased by using an interpolation of colors
(sub-sampling). A sub-sampling of 5 x 3 means that each screen pixel 
will give rise to 15 pixels on the printing output by interpolating
the colors of the pixels nearby, with 5 subdivisions in the horizontal
direction and 3 subdivisions in the vertical direction (the allowed 
maximal subdivision is 255).

The preview button creates a temporary PostScript file and pipes it
to a PostScript viewer, "gv" by default. The PostScript viewer can be
interactively redefined. It is initialized via the parameter
   "Canvas.print*form*psviewer*string: ..."
in the app-defaults file.

#BEGIN fileformat "6. Image Formats"
XPaint supports a large variety of image file formats, which may depend
on library availability at compile or run time (thus, some of these 
formats may not be accessible in the current running version, such as
e.g. PGF if the pgf and libpgf packages are not installed.)

The table below provides a short summary of the features of each image
format and support provided by XPaint.  Note that not all formats are
supported for both read and write operations.

Color depth is given in terms of the number of bits used to store the
colors in the image.  This means that a color depth of 1-bit can only
store black/white images, while 24-bit color formats can store images
containing up to 2**24 (or approx. 16 million) colors.  Regardless of
the image format, saved images always reflect the ability of current 
display type (i.e., a color image loaded on a greyscale screen will be 
saved as a grey image).  See the Possible Data Loss section for more
details.

The image mask feature of an image format provides the ability to
save/load odd-shaped regions (i.e., regions are not required to be 
rectangular and may have "holes" in them).   See "Save Region" and 
"Load Clipboard..." for more information.

More detailed information about each format follows the next table
at the end of this section.

type	Read	Write	Color Depth		Alpha/Image Mask

PNG	yes	yes	8, 24-bit		yes
#NL
GIF	yes	yes	8-bit		yes
#NL
JPEG	yes	yes	24-bit		no
#NL
JP2K	yes	yes	24-bit		yes
#NL
PGF	yes	yes	24-bit		yes
#NL
TIFF	yes	yes	8, 24-bit		yes
#NL
BMP	yes	yes	24-bit		yes
#NL
ICO	yes	yes	24-bit		yes
#NL
SGI	yes	yes	24-bit		no
#NL
PPM	yes	yes	24-bit		yes**
#NL
XBM	yes	yes	1-bit		no
#NL
XPM	yes	yes	8-bit		yes
#NL
XWD	yes	yes	24-bit		no
#NL
PS	yes	yes*	24-bit		no
#NL
PDF	yes	yes*	24-bit		no
#NL
SVG	yes	no	24-bit		yes
#NL
TEX	yes	no	24-bit		no

* CAUTION : the output of a PostScript or PDF write is just raw bitmap data. 
If an existing PS or PDF file is overwritten, all formatting data and all
other information embedded in the input file are irretrievably lost, 
especially embedded text components, PostScript procedures, fonts, etc.

** Note also that the alpha channel extension of the PPM format is not
universally accepted and somewhat specific to XPaint.

Here is a short explanation of the nature of various image formats:

PNG - Portable Network Graphics Format
#NL
	A new format designed to replace GIF and,
#NL
	to some extent, TIFF.  It has a better
#NL
	compression engine than either GIF or TIFF
#NL
	and is a lossless format (unlike JPEG).
#NL
	We recommend the PNG format in most cases !

GIF - Graphics Interchange Format
#NL
	A popular image format used across a variety
#NL
	of platforms, including PCs. Suffers
#NL
	unfortunately of very restrictive licence
#NL
	by UNISYS, which owns a patent on the
#NL
	compression algorithm used.
#NL
	Just boycott GIF format, PNG is better !

JPEG - Joint Photographic Experts Group Format
#NL
	A standardized, lossy format for storing
#NL
	compressed color and greyscale images
#NL
	of natural scenes.

JP2K - JPEG 2000 Format
#NL
	A standardized, lossy/lossless format
#NL
	for storing compressed color and greyscale
#NL
	images which is based on wavelets rather
#NL
	than DCT (discrete cosine transform).
#NL
	It is still quite recent and not as
#NL
	widespread as JPEG, in spite of a
#NL
	better compression ratio and overall
#NL
	quality. Also allows storing alpha
#NL
	channel, but requires more computing power.

PGF - Progressive Graphics File
#NL
	A format similar to JPEG/JPEG2000, but
#NL
	which is even more recent (and thus even
#NL
	less widespread). Compression is better
#NL
	than JPEG and almost as fast, and the
#NL
	format supports the alpha channel.

TIFF - Tagged Image File Format
#NL
	A large, complex image format used by
#NL
	some applications as their default.

BMP - Bitmap Format (Microsoft)
#NL
	Format quite frequently used on Windows.
#NL
	Compression mediocre except by
#NL
	embedding PNG's inside. Avoid that
#NL
	monster if you can.

ICO - Icon Format (Microsoft)
#NL
	Format used by Microsoft OS for icons,
#NL
	size is restricted to 256x256 at most.
#NL
	Is provided here just for compatibility
#NL
	issues. Avoid this if you can.

SGI - Silicon Graphics, Inc., Format
#NL
	An SGI-specific image format, using
#NL
	RLE compression. This format is rather
#NL
	old and very rarely used nowadays.

PPM - Portable PixMap Format
#NL
	Image format provided by the NetPBM
#NL
	toolkit that allows e.g. conversion
#NL
	to a wide variety of other formats.

XBM - X Window BitMap
#NL
	A black and white image format used by the
#NL
	X Window System.

XPM - X Window PixMap
#NL
	XPM images are stored in an ASCII text
#NL
	format that can be included in programs.

XWD - X Window Dump
#NL
	Used for screen dumps by the X Window
#NL
	System.

PS - PostScript Format
#NL
	PostScript images are normally used by most
#NL
	printers and text-processing packages.
#NL
	Is most often human readable but also
#NL
	quite verbose.

PDF - Portable Document Format
#NL
	PDF is a document format specified by 
#NL
	Adobe Inc. which is widely used for
#NL
	documents involving text and images
#NL
	simultaneously. Is now an ISO specification
#NL
	(ISO 32000-1).

SVG - Scalable Vector Graphics
#NL
	An image vector format defined by the
#NL
	W3C Consortium. Based on XML, it is now
#NL
	a widespread vector format used along
#NL
	with web browsers. Human readable (sort of)
#NL
	but extremely verbose.

TEX - TeX/LaTeX format
#NL
	The great text formatting language
#NL
	designed by Donald Erwin Knuth; the
#NL
	predominant text formatting language
#NL
	used for fundamental science papers.

#BEGIN about "7. About XPaint"
NOTE: Since version 2.6.3, XPaint is released and maintained by
Jean-Pierre Demailly (demailly@univ-grenoble-alpes.fr), except for the PNG
code, which is written and maintained by Greg Roelofs (newt@uchicago.edu). 

The original program was written by David Koblas who pursued development
up to XPaint 2.1.1. In 1995. Torsten Martinsen (torsten@image.dk) took up 
the program and produced versions 2.2.1 to 2.5.7. Versions 2.5.8 up to
2.6.2 were maintained by Torsten Martinsen and Jean-Pierre Demailly.
Please do NOT send bug reports, etc., to David Koblas or Torsten Martinsen.

The message below is the original 'About' message from version 2.1.1.

               ----------------------------

Hopefully, you find this software useful. If you find any bugs or have
any comments, feel free to contact me.

This software is created as DonateWare. If you enjoy using XPaint,
it would be appreciated if you would make a donation to the
author in the form of cookies, money, employment, or whatever.

If you or your firm is looking to hire a skilled consultant, contact
me for more details.

David Koblas (koblas@netcom.com)
#NL
Extra Mile Consulting
#NL
PO Box 1352
#NL
Mountain View, CA 94042-1352 USA

#BEGIN copyright "8. Copyright Information"
This is XPaint, a painting/drawing editing tool,

Copyright (C) 1993 - 1995, David Koblas
#NL
Copyright (C) 1995 - 2000, Torsten Martinsen
#NL
Copyright (C) 1997, Scott D. Nelson
#NL
Copyright (C) 1996 - 2003, Greg Roelofs
#NL
Copyright (C) 2000 - 2020, Jean-Pierre Demailly

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
