diff options
Diffstat (limited to 'doc')
250 files changed, 10777 insertions, 8 deletions
diff --git a/doc/chalk/Makefile.am b/doc/chalk/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/chalk/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/chalk/README.SCREENSHOTS b/doc/chalk/README.SCREENSHOTS new file mode 100644 index 00000000..bc1d55bd --- /dev/null +++ b/doc/chalk/README.SCREENSHOTS @@ -0,0 +1,7 @@ +Note for translators: + +The file "mountains.png" is the original photo used for creating the screenshots +in the Dialogs section. + + +- ASK
\ No newline at end of file diff --git a/doc/chalk/commands-dialogs.docbook b/doc/chalk/commands-dialogs.docbook new file mode 100644 index 00000000..86ef91d1 --- /dev/null +++ b/doc/chalk/commands-dialogs.docbook @@ -0,0 +1,1411 @@ +<sect1 id="commands-dialogs"> +<title>Dialogs</title> + +<para> +This section describes &chalk;'s dialog windows. +</para> + +<sect2 id="commands-dialogs-image"> +<title>Dialogs for working with images</title> + +<sect3 id="commands-dialogs-images-colorrange"> +<title>The <guilabel>Color Range</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Color Range</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-colorrange.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Color Range</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Color Range</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +You can create a selection based on the color values of pixels here. In the +dropdown box, choose which color range you want to select. Pixels will be +selected according to their color value on this scale (⪚ a fully yellow +pixel would score maximally on the yellow scale and on the red and green scales). +If you check the <guilabel>Invert</guilabel> box, the selection becomes inverted: +pixels will become selected if they have a lower value in the specified range instead. +You can choose whether the current selection should be +added to or subtracted from the color range selection by clicking the +respective option: <guilabel>Add to current selection</guilabel> or +<guilabel>Subtract from current selection</guilabel>. Choose +<guibutton>Select</guibutton> to actually perform the selection or +<guibutton>Deselect</guibutton> to remove these pixels from the selection. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-convertimagetype"> +<title>The <guilabel>Convert Image Type</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Convert Image Type</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-convertimagetype.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Convert Image Type</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Convert Image Type</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to convert your image from one color space to another. +The <guilabel>Target color space</guilabel> and <guilabel>Destination ICM +profile</guilabel> are used to set to which colorspace and profile the image +will be converted. You can influence how this conversion is done with the +<guilabel>Rendering Intent</guilabel> option. +</para> +<para> +With <guilabel>Perceptual</guilabel> conversion, the source color space is +mapped linearly to the destination color space. If the destination color space +<quote>accepts</quote> a lesser color range than the source, shifts may occur +because the range is compressed. <guilabel>Relative colorimetric</guilabel> +conversion converts every color to the closest color in the destination color +space. This may mean that a certain color range is mapped to one color in the +destination color space. <guilabel>Saturation</guilabel> means that fully +saturated colors will remain fully saturated, even if this means that the +actual color is changed. With <guilabel>Absolute colorimetric</guilabel> +conversion, the same approach is used as with <guilabel>Relative +colorimetric</guilabel>, but the white point of the color space (the value +designating the color white) is not changed to match the new color space, +which may result in unwanted changes to near colors. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-imageproperties"> +<title>The <guilabel>Image Properties</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Image Properties</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-imageproperties.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Image Properties</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Image Properties</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +In this dialog you can change a couple of image properties. First of all, the +<guilabel>Name</guilabel> of the image. If you did not set a name earlier +(that can also be done when creating the image), it will have a default name +like <quote>Image1</quote>. Then, you can set its size (determined by the +<guilabel>Width</guilabel> and <guilabel>Height</guilabel> in pixels and +the <guilabel>Resolution</guilabel> in dots per inch) and the color profile to +be used (<guilabel>Profile</guilabel>). Finally, you can fill in the +<guilabel>Description</guilabel> field with any information you want to add to +the image. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-imagesize"> +<title>The <guilabel>Image Size</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Image Size</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-imagesize.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Image Size</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Image Size</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog lets you resize your image. In the top part, you can choose the +way the image is resized. If you choose <guilabel>Resize</guilabel>, the size +of the image is changed, but its layers (which contain the actual contents) +will not be modified. So, when you double the height and width of the image, +your original image will occupy the top-left quarter part of your new image. +On decreasing the size of your image, the image layers will stretch out over +the image borders, unless you choose <guilabel>Crop layers on image +resize</guilabel>, which will crop all layers to the new image size. +</para><para> +With <guilabel>Scale</guilabel>, the image layers will be resized with the +image. So increasing the image size will actually enlarge the contents, and +similar for decreasing. +</para><para> +Under <guilabel>Pixel dimensions</guilabel>, you can set which new size you +want the image to have. The original size is given as a reference. The new +size can be set both as pixels or as a percentage, with 100% being the +original size. If you select <guilabel>Constrain proportions</guilabel>, the +new width and height will always be set to the same percentage. For example, +if you have an image of 200 x 100 pixels, and set the width to 20 pixels, the +height will automatically be changed to 10. With this checkbox unselected, you +can also resize the image non-proportionally. +</para><para> +The <guilabel>Filter:</guilabel> dropdown box can be used to select a +different algorithm for determining the colors of the pixels in the newly +resized image that did not correspond to a pixel in the old image (the +calculated corresponding location in the old image was located in between +pixels). <guilabel>BSpline</guilabel> uses a 4 x 4 pixel grid and results into a quite high +blurring. <guilabel>Bell</guilabel> is quite fast while resulting in a reasonably smooth image. +<guilabel>Box</guilabel> is the fastest method, but yields the least appealing result. <guilabel>Hermite</guilabel> +keeps the image quite sharp, while smoothing it as well, and is reasonably +fast. <guilabel>Lanczos3</guilabel> results in sharp images, but is very slow. <guilabel>Mitchell</guilabel> (the +default) is not very fast, but often yields a good intermediate result. +<guilabel>Triangle/Bilinear</guilabel> uses the 2 x 2 pixel grid around the calculated location +resulting in relatively sharp lines. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-rotateimage"> +<title>The <guilabel>Rotate Image</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Rotate Image</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-rotateimage.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Rotate Image</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Rotate Image</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can rotate the image. The top part of the dialog shows +the result of the rotation in the form of a change in dimension (if any). +Under <guilabel>Direction</guilabel> you can choose between +rotating clockwise and counter-clockwise. Under <guilabel>Angle</guilabel>, +you can set the amount of rotation. 90, 180 and 270 degrees can be selected +using the respective option button, other amounts need to be specified with +the <guilabel>Custom</guilabel> spin box. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-separateimage"> +<title>The <guilabel>Separate Image</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Separate Image</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-separateimage.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Separate Image</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Separate Image</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can separate (part of) your image. Every color component +(channel) will be put into a separate layer or image. At the top of the +dialog, the current color model is shown. Below that, a couple of options can +be set. +</para> +<para> +Under <guilabel>Source</guilabel>, you can choose what part of the image to +separate. The two options are <guilabel>Current layer</guilabel>, which +(obviously) only uses the currently selected layer and <guilabel>Flatten all +layers before separation</guilabel>, which uses the entire image. +</para> +<para> +Under <guilabel>Output</guilabel>, you can choose where the result of the +separation should be written to: either to a couple of layers, or to a couple +of images. +</para> +<para> +Under <guilabel>Alpha Options</guilabel>, you can choose what should be done +with the alpha channel of the selected layer(s). It can be copied to each new +channel, be discarded, or separated on its own. +</para> +<para> +The two options at the bottom of the dialog, finally, determine whether the +source should be downscaled to 8 bit colors (if it contains more), and whether +the output should be in color (default is to separate the channels to grayscale +values). +</para> +</sect3> + +<sect3 id="commands-dialogs-image-shearimage"> +<title>The <guilabel>Shear Image</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Shear Image</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-shearimage.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Shear Image</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Shear Image</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to shear your image. By shearing, the bounding +rectangle of your image is transformed into a parallellogram. One pixel +row/column is kept in place, the next one is shifted by a certain amount, the +next one by the same amount relative to the previous one, etcetera. +The X and Y shearing angles can be set using the two spin boxes. +</para> + +</sect3> + +<sect3 id="commands-dialogs-image-substrate"> +<title>The <guilabel>Substrate</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Substrate</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-substrate.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Substrate</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Substrate</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +(This dialog is still to be described.) +</para> + +</sect3> + +</sect2> + +<sect2 id="commands-dialogs-layers"> +<title>Dialogs for working with layers</title> + +<sect3 id="commands-dialogs-layers-convertlayertype"> +<title>The <guilabel>Convert Layer Type</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Convert Layer Type</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-convertlayertype.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Convert Layer Type</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Convert Layer Type</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog is exactly the same as the <link +linkend="commands-dialogs-image-convertimagetype"><guilabel>Convert Image +Type</guilabel> dialog</link>, which converts an entire image instead of a +single layer. See the description there for details. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-dropshadow"> +<title>The <guilabel>Drop Shadow</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Drop Shadow</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-dropshadow.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Drop Shadow</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Drop Shadow</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can add a drop shadow effect to the current layer. +Select the X and Y offsets (displacements) of the shadow relative to the +original layer with the two topmost spin boxes. The <guilabel>Blur +radius</guilabel> spinbox determines the radius in which the shadow will be +blurred (to achieve a smooth transition at the shadow border). If you want +a special color for the shadow, you can choose one with the +<guilabel>Color</guilabel> field. The <guilabel>Opacity</guilabel> slider and +spinbox can be used to make the shadow more or less transparent. Disable the +<guilabel>Allow resizing</guilabel> checkbox if you don't want the layer to be +resized in order to give it a shadow. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-histogram"> +<title>The <guilabel>Histogram</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Histogram</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-histogram.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Histogram</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Histogram</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog shows a histogram for the current layer. With the +<guilabel>Method:</guilabel> settings, you can choose what kind of histogram +to show. You can change the channel(s) to show with the +<guilabel>Channels:</guilabel> listbox, and the scale on which it should be +drawn with the <guilabel>Linear</guilabel> and +<guilabel>Logarithmic</guilabel> radio buttons. Under the preview, there are +buttons available to zoom in to, and move over, the histogram. These are +activated for 16-bit colorspace layers. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-layerproperties"> +<title>The <guilabel>Layer Properties</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Layer Properties</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-layerproperties.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Layer Properties</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Layer Properties</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog is in essence the same as the <link +linkend="commands-dialogs-layers-newlayer">New Layer</link> dialog, with the difference that +you cannot change its colorspace or profile anymore. These properties are +shown, though, to keep the information complete. +</para> +</sect3> + +<sect3 id="commands-dialogs-layers-layersize"> +<title>The <guilabel>Layer Size</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Layer Size</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-layersize.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Layer Size</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Layer Size</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to resize the current layer. +Under <guilabel>Pixel dimensions</guilabel>, you can set which new size you +want the layer to have. The original size is given as a reference. The new +size can be set both as pixels or as a percentage, with 100% being the +original size. If you select <guilabel>Constrain proportions</guilabel>, the +new width and height will always be set to the same percentage. For example, +if you have a layer of 200 x 100 pixels, and set the width to 20 pixels, the +height will automatically be changed to 10. With this checkbox unselected, you +can also resize the layer non-proportionally. The <guilabel>Filter:</guilabel> +dropdown list can be used to select a different algorithm for resizing the +layer. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-newadjustmentlayer"> +<title>The <guilabel>New Adjustment Layer</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>New Adjustment Layer</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-newadjustmentlayer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>New Adjustment Layer</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>New Adjustment Layer</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +In this dialog, you can select the type of adjustment layer to add to the +image. In the left-hand list, you can see the available adjustment layers, +each with a preview. When you select one, the <guilabel>Preview</guilabel> +will change to show a correctly scaled preview of what the result of the +adjustment layer is going to be. +</para><para> +You can then choose to show either the original image or the preview of the +adjustment layer with the radio buttons below the preview window. The buttons +next to these allow you to zoom in, zoom out, and refresh the preview, +respectively. The <guilabel>Autoupdate</guilabel> checkbox determines if the +preview window should update automatically after you made a change. +</para><para> +The various options available for the filter that is used to create the +adjustment layer, are shown at the bottom of the dialog. See the section on +<link linkend="commands-dialogs-filters">filters</link> of this chapter for +descriptions. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-newlayer"> +<title>The <guilabel>New Layer</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>New Layer</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-newlayer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>New Layer</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>New Layer</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +You can add a new layer to your image with this dialog. If you want a +descriptive name for your layer, you can fill one in at +<guilabel>Name:</guilabel>. You can select the desired colorspace for the new +layer from the <guilabel>Colorspace:</guilabel> list, and the specific +color profile for that colorspace at <guilabel>Profile:</guilabel>. +You can preset the layer's <guilabel>Opacity</guilabel> (you can change it later with the slider in +the <guilabel>Layer</guilabel> box), and choose the mode with which the layer should be composited +onto the final image. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-rotatelayer"> +<title>The <guilabel>Rotate Layer</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Rotate Layer</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-rotatelayer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Rotate Layer</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Rotate Layer</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog, similar to the <link +linkend="commands-dialogs-image-rotateimage"><guilabel>Rotate Image</guilabel> +dialog</link>, allows you to rotate the current layer. You can choose the +direction in which to rotate and the amount to rotate the layer by. +</para> + +</sect3> + +<sect3 id="commands-dialogs-layers-shearlayer"> +<title>The <guilabel>Shear Layer</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Shear Layer</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-shearlayer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Shear Layer</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Shear Layer</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog works the same as the <link +linkend="commands-dialogs-image-shearimage"><guilabel>Shear Image</guilabel> +dialog</link>, except that it operates on the current layer instead of on the +entire image. +</para> + +</sect3> + +</sect2> + +<sect2 id="commands-dialogs-filters"> +<title>Dialogs for working with filters</title> + +<para> +All filter dialogs consist of a filter-specific part, at the left, and a +generic part, at the right. The generic part contains a preview window, which +you can configure using the controls below it. Choose +<guilabel>Preview</guilabel> or <guilabel>Original</guilabel> depending on +whether you want the preview window to show the preview of the filter effect +or the original image. The four buttons at the bottom right allow you to zoom +in and zoom out, set the zooming factor to 100% (this shows the image at its +original size), and refresh the preview, respectively. Furthermore, the option +<guilabel>Autoupdate</guilabel> determines if the preview window is updated +automatically. If you uncheck this checkbox, you will have to refresh the +preview yourself. +</para> + +<sect3 id="commands-dialogs-filters-blur"> +<title>The <guilabel>Blur</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Blur</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-blur.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Blur</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Blur</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to customize the way your image is blurred. The +<guilabel>Half-width</guilabel> and <guilabel>Half-height</guilabel> spinboxes +determine the size of the areas of your image that are consecutively blurred. +With the <guilabel>Strength</guilabel> spinbox you can set the strength with which the +blurring should be applied, and with the <guilabel>Angle</guilabel> spinbox +you can add a rotation to the area. The <guilabel>Shape</guilabel> setting, +finally, allows you to choose between circular and rectangular areas +</para> + +</sect3> + + +<sect3 id="commands-dialogs-filters-brightnesscontrast"> +<title>The <guilabel>Brightness / Contrast</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Brightness / Contrast</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-brightnesscontrast.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Brightness / Contrast</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Brightness / Contrast</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can customize the brightness and contrast of your image. +</para><para> +The curve diagram has a histogram-like background that shows you the abundance +of various brightness levels. The curve itself (initially a diagonal line from +bottom left to top right) determines to which new brightness level (on the +vertical axis) pixels with a certain original level (on the horizontal axis) are +to be mapped. For example, the default diagonal line from bottom left to top +right sets every original pixel to its own brightness value, meaning no +change. A horizontal line means that all pixels will get the same brightness. +This means minimal contrast, the brightness itself is indicated by the height +at which the line is placed. +</para><para> +You can click on a handle (red circle) to select it (a selected handle is +indicated by a filled circle) and drag it around to change the shape of the +curve. The curve will be drawn smoothly through the handles (always +strictly from left to right). If you click on the curve, a handle is added to +it at that position. Clicking somewhere else in the image will also add a +handle at that point. You can press <keycap>Delete</keycap> to delete the +currently selected handle. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-bumpmap"> +<title>The <guilabel>Bumpmap</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Bumpmap</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-bumpmap.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Bumpmap</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Bumpmap</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +You can apply a bumpmap effect and customize it using this dialog. One layer +is used as bumpmap layer: it is read as grayscale image and the gray values of +its pixels are used to to distort the other layer for creating the depth +illusion. High grey values, &ie; more white, mean a larger height, small +values, &ie; near black, mean a smaller height — or a larger depth, the +height can get <quote>below sealevel</quote>. A light source, shining +<quote>from above</quote> on the image that lies <quote>on the ground</quote>, +is simulated to determine the depth and direction of the shadows. +</para><para> +The first option in this dialog offers you the selection of the +<guilabel>Bumpmap layer</guilabel>. +</para><para> +Under <guilabel>Type</guilabel>, you can select what kind of bumpmap to be +applied. There are three types, <guilabel>Linear</guilabel> (a normal +application of the bumpmap), <guilabel>Spherical</guilabel> (focusing on the +extremes, that is, the shadow and highlight values) and +<guilabel>Sinusoidal</guilabel> (focusing on the midtone values). +</para><para> +Then, there are three options to modify the bumpmap apart from its +algorithmical application. With <guilabel>Compensate for darkening</guilabel>, +the image is restored to about its original average lightness if using the +bumpmap filter would make it darker. The <guilabel>Invert bumpmap</guilabel> +option creates an inverted bumpmap (high and low are reversed). With +<guilabel>Tile bumpmap</guilabel>, a bumpmap layer that is smaller than the +layer it is applied to, will be tiled (repeatedly) to cover the entire layer. +</para><para> +Under <guilabel>Settings</guilabel>, you can select the mathematical +parameters for the bumpmap. First of all, <guilabel>Azimuth</guilabel> (the +angle of the light source in the X-Y plane), <guilabel>Elevation</guilabel> +(the height of the simulated light source above the surface in degrees, with 0 +degrees being on the ground and 90 degrees being vertically above the image), +and <guilabel>Depth</guilabel> (the maximal vertical distortion of the image). +</para><para> +Then, there are the <guilabel>X offset</guilabel> and <guilabel>Y +offset</guilabel>, with which you can displace the bumpmap layer relative to +the destination layer, <guilabel>Water level</guilabel> (the depth seen as +neutral), and <guilabel>Ambient light</guilabel>, which determines the +relative amount of ambient (environmental) light. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-coloradjustment"> +<title>The <guilabel>Color Adjustment</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Color Adjustment</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-coloradjustment.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Color Adjustment</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Color Adjustment</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to customize the <guilabel>Color Adjustment</guilabel> filter. You can use +the curve (see the section on <link +linkend="commands-dialogs-filters-brightnesscontrast">Brightness / +Contrast</link> for a description on the curve) to determine the mapping +from old to new color levels, for each of the channels separately. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-colortoalpha"> +<title>The <guilabel>Color to Alpha</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Color to Alpha</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-colortoalpha.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Color to Alpha</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Color to Alpha</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can make parts of the image having a certain color +transparent (officially <quote>alpha-transparent</quote>). You can select the +color you want to remove from the image (replacing it with transparency) with +the <guilabel>Color</guilabel> swatch, and how much a color may differ from +the selected one before it is considered not to match, with the +<guilabel>Threshold</guilabel> spinbox. Setting a threshold of zero (0) +ensures that only pixels with the exact matching color will be made +transparent, higher thresholds will make other colors match as well. +</para> + +</sect3> +<sect3 id="commands-dialogs-filters-colortransfer"> +<title>The <guilabel>Color Transfer</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Color Transfer</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-colortransfer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Color Transfer</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Color Transfer</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog lets you copy the colors from one image (the <guilabel>Reference +Image</guilabel>) to the current one. The colors in both images are compared +and each color in the one you are working with, will be replaced by the +nearest one in the reference image. +</para> + +</sect3> + +<!-- +<sect3 id="commands-dialogs-filters-cubism"> +<title>The <guilabel>Cubism</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Cubism</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-cubism.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Cubism</guilabel> dialog</phrase> +</textobject> +<caption><para>The Cubism dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog has two filter-specific options. The <guilabel>Tile +size:</guilabel> slider and spinbox determine how big the tiles are in which +the image is subdivided, the <guilabel>Tile saturation:</guilabel> setting +sets the color saturation of the tiles. +</para> + +</sect3> +--> + +<sect3 id="commands-dialogs-filters-customconvolution"> +<title>The <guilabel>Custom Convolution</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Custom Convolution</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-customconvolution.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Custom Convolution</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Custom Convolution</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this filter, you can apply a customized distortion effect to your image. +The nine spinboxes at the top left determine the distortion. Each pixel is +assigned a new value based on these values: the old color values of the pixel +inself and the eight surrounding pixels are each multiplied by the values in +the respective spinboxes, these results are added, and the final result is the +new color value for the pixel. Before being applied, this final result can be +multiplied with a certain <guilabel>Factor:</guilabel> or a certain +<guilabel>Offset:</guilabel> can be added to it. +</para><para> +In the example screenshot, each pixel is assigned a new value based on its +own (the 1 in the center), to which are added the values of the pixels to its +top right and directly below it (each with a factor of 1, &ie; the actual +value, since multiplying by one has no effect), and from which are subtracted +the values of the pixels to its bottom right and directly above it (added with +a factor of -1, so subtracted by a factor of 1). +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-emboss"> +<title>The <guilabel>Emboss</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Emboss</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-emboss.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Emboss</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Emboss</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog contains just one option, the <guilabel>Depth:</guilabel> slider +and spinbox which determines the depth of the embossing effect. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-filtersgallery"> +<title>The <guilabel>Filters Gallery</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Filters Gallery</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-filtersgallery.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Filters Gallery</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Filters Gallery</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog can be used to get a quick overview of what the various available +filters do. The filters are in turn applied to the current image and the +results are put in the left list box as thumbnails. If you select one, its +options become available in the <guilabel>Configuration</guilabel> section. +See the description of the respective filter for details. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-gaussiannoise"> +<title>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-gaussiannoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog allows you to customize a Gaussian noise reduction. The +<guilabel>Threshold</guilabel> setting is a measure for how much noise should +be removed (&ie; how quickly a <quote>lonely</quote> pixel should be made +equal to its surroundings), while the <guilabel>Window Size</guilabel> setting +determines the radius of the area considered when changing pixels. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-lenscorrection"> +<title>The <guilabel>Lens Correction</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Lens Correction</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-lenscorrection.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Lens Correction</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Lens Correction</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can fix an image which is distorted due to common lens +anomalies. You can specify a <guilabel>Distortion correction</guilabel>, +indicating how much the image should be corrected if its +concaveness / convexness is not right, for areas near the center and areas +near the edges. If you want an asymmetrical correction, you can specify +different <guilabel>X</guilabel> and <guilabel>Y</guilabel> coordinates for +the center (in percentages of the total width and height, measured from the +top left). +</para><para> +You can also correct a too light or too dark image with the +<guilabel>Brightness correction</guilabel> spinbox. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-imagerestoration"> +<title>The <guilabel>Image Restoration</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Image Restoration</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-imagerestoration.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Image Restoration</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Image Restoration</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Using this dialog, you can specify exactly how the image restoration should +be done. This filter tries to increase the quality of an image, for instance +by removing scratches. Various options are available to customize its +behaviour. +</para><para> +(Unfortunately, these are not described as of yet.) +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-oilpaint"> +<title>The <guilabel>Oilpaint</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Oilpaint</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-oilpaint.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Oilpaint</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Oilpaint</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog can configure two parameters for the associated filter. The +<guilabel>Brush size:</guilabel> setting determines the size of the brush that +is used to simulate the oilpaint effect, the <guilabel>Smooth:</guilabel> +setting specifies if the difference in colors between adjacent +<quote>swatches</quote> may be large (low smoothness) or should be small (high +smoothness). +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-pixelize"> +<title>The <guilabel>Pixelize</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Pixelize</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-pixelize.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Pixelize</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Pixelize</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +On this dialog, you can adjust two settings. <guilabel>Pixel width:</guilabel> +and <guilabel>Pixel height:</guilabel> indicate the width and height of the +area that should be taken together and averaged to form one new, large +<quote>pixel</quote>. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-raindrops"> +<title>The <guilabel>Raindrops</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Raindrops</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-raindrops.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Raindrops</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Raindrops</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This filter can be configured using the settings <guilabel>Drop +size:</guilabel> (the average diameter of the raindrops), +<guilabel>Number:</guilabel> (the number of raindrop effects that should be +added to the image), and <guilabel>Fish eyes:</guilabel> (the percentage of +raindrops that should be rendered as fisheye lens effects instead of plain +raindrop effects). +</para> +</sect3> + +<sect3 id="commands-dialogs-filters-randomnoise"> +<title>The <guilabel>Random Noise</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Random Noise</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-randomnoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Random Noise</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Random Noise</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This filter adds random noise (speckles, or something similar) to your image. +There are two customizable settings: the amount of noise +(<guilabel>Level</guilabel>, as a percentage) and the +<guilabel>Opacity</guilabel> of the noise (should the original color still be +a bit visible or not). +</para> + +</sect3> +<sect3 id="commands-dialogs-filters-randompick"> +<title>The <guilabel>Random Pick</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Random Pick</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-randompick.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Random Pick</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Random Pick</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +In this dialog, you can specify parameters for the <guilabel>Random Pick</guilabel> +filter. The <guilabel>Level</guilabel> setting determines how much pixels will +be affected (measured as a percentage), the area which is looked in to take a +new color for a pixel is set with the <guilabel>Size of the window</guilabel> +setting, and the <guilabel>Opacity</guilabel> of the modifications can be set as +well. +</para> + +</sect3> + + +<sect3 id="commands-dialogs-filters-roundcorners"> +<title>The <guilabel>Round Corners</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Round Corners</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-roundcorners.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Round Corners</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Round Corners</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog has one setting: the radius of the rounded corners. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-smalltiles"> +<title>The <guilabel>Small Tiles</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Small Tiles</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-smalltiles.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Small Tiles</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Small Tiles</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +In this dialog, you can set the amount of subdivisions with the +<guilabel>Number of tiles</guilabel> settings. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-sobel"> +<title>The <guilabel>Sobel</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Sobel</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-sobel.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Sobel</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Sobel</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Here, you can set the parameters for the <guilabel>Sobel</guilabel> edge +detection filter. First of all you can determine which directions to sobel in: +horizontally, vertically, or both. The <guilabel>Keep sign of +result</guilabel> setting does not affect regular images. +<guilabel>Make image opaque</guilabel> determines whether the resulting image +is opaque or transparent. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-unsharpmask"> +<title>The <guilabel>Unsharp Mask</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Unsharp Mask</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-unsharpmask.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Unsharp Mask</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Unsharp Mask</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog offers three options for the sharpening filter +<guilabel>Unsharp Mask</guilabel>: the radius (<guilabel>Half-size</guilabel>) +of the mask, the <guilabel>Amount</guilabel> of sharpening that should be +done, and the <guilabel>Threshold</guilabel> level. +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-wave"> +<title>The <guilabel>Wave</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Wave</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-wave.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Wave</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Wave</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +For both the horizontal and the vertical components of the wave distortion +(note: a vertical wave means that the vertical position is dependent on the +horizontal one, and hence looks like a <quote>W</quote>), +you can determine four settings here. The <guilabel>Wavelength</guilabel> (a +shorter wavelength means a more erratical wave), the +<guilabel>Shift</guilabel> (which point of the wave should be started at), the +<guilabel>Amplitude</guilabel> (the amount of distortion), and the +<guilabel>Shape</guilabel> (<guilabel>Sinusoidal</guilabel> or rounded, +versus <guilabel>Triangle</guilabel> or pointy). +</para> + +</sect3> + +<sect3 id="commands-dialogs-filters-waveletnoise"> +<title>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-waveletnoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +The only setting here, <guilabel>Threshold</guilabel>, indicates how easily pixels +are seen as noise that should be removed and made equal to the surrounding area. +</para> + +</sect3> + +</sect2> + +<sect2 id="commands-dialogs-misc"> +<title>Miscellaneous dialogs</title> + +<sect3 id="commands-dialogs-misc-addpalette"> +<title>The <guilabel>Add Palette</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Add Palette</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-addpalette.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Add Palette</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Add Palette</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +With this dialog, you can add a custom color palette to &chalk;. Fill in the +name for your palette in the text field at the top. Then make the palette: use +the button <guibutton>Add New Color...</guibutton> to add a color to the palette +and <guibutton>Remove Selected Color</guibutton> to remove the currently +selected color. Click the button <guibutton>Add to Predefined +Palettes</guibutton> to add your newly created palette to the palette list, or +just choose <guibutton>OK</guibutton> when you're done. +</para> + +</sect3> + +<sect3 id="commands-dialogs-misc-documentinformation"> +<title>The <guilabel>Document Information</guilabel> dialog</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Document Information</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-documentinformation.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Document Information</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Document Information</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This dialog is the same as in other &koffice; programs. You can enter various +information about your document here, which will be saved with the document so +that you can retrieve it later to review or edit. +</para> + +<para> +On the <guilabel>General</guilabel> tab, you can enter the title, subject and +keywords, as well as an abstract. On the bottom of this tab, some statistical +information is displayed. On the <guilabel>Author</guilabel> tab, you can +store information about yourself. The third tab, <guilabel>User-defined +Metadata</guilabel>, allows you to store any other information. +</para> +</sect3> + +</sect2> + + +</sect1> diff --git a/doc/chalk/commands-menus.docbook b/doc/chalk/commands-menus.docbook new file mode 100644 index 00000000..e0a58131 --- /dev/null +++ b/doc/chalk/commands-menus.docbook @@ -0,0 +1,2158 @@ +<sect1 id="commands-menus"> +<title>Menus</title> + +<para> +Some of &chalk;'s menus are standard in &kde; or &koffice;, while others are +particular to &chalk;. The <guimenu>File</guimenu> menu contains commands for +manipluating files. In the <guimenu>Edit</guimenu> menu, you can find commands +that do things with the current selection. With the commands from the +<guimenu>View</guimenu> menu, you can change the way you look at the image. +The <guimenu>Image</guimenu> menu contains commands that change the entire +image, like converting all layers to another color model or resizing or +scaling the image. The <guimenu>Layer</guimenu> menu is like the +<guimenu>Image</guimenu> menu, but the commands only work on the current +layer. The <guimenu>Select</guimenu> menu contains commands to create and +manipulate selections. The <guimenu>Filter</guimenu> menu contains all the +filters you have installed. These work on the current layer. The +<guimenu>Scripts</guimenu> menu contains entries for working with scripts. +The <guimenu>Settings</guimenu> menu is again common to &koffice; and allows +you to manipulate the toolbars, shortcuts and configuration of &chalk;. +Finally, the <guimenu>Help</guimenu> menu gives you access to various +(hopefully helpful) information, such as this handbook. +</para> + +<!-- ====== File ================================================ --> + +<sect2 id="commands-menus-file"> +<title>The <guimenu>File</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new document.</action> This displays the +<guilabel>New document</guilabel> dialog, standard across &koffice;, in which +you can choose to start with a blank document of a certain type, or to open a +recently opened document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>O</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens an existing document.</action> +Because this uses the usual &kde; <guilabel>Open Document</guilabel> +dialog to let you select a file, you can open files via various protocols +(ftp, fish, etcetera). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open Recent</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a recently +opened document.</action> Clicking this menu item will show a +submenu with the ten most recently opened documents in which +you can quickly open an image you have been working on lately.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>S</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem><para><action>Saves the document.</action> If you +haven't saved the document before, you will get the <guilabel>Save +Document As</guilabel> dialog, otherwise the document will be saved under +its current name. </para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Saves the document under a different name.</action> +The default &kde; dialog is used, so saving remotely via ftp +or ssh (fish) is perfectly possible.</para> </listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice></term> +<listitem><para><action>Reloads the current document +from disk.</action> All changes since you last saved the document +will be lost.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Import...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens an existing document.</action> Unlike +<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>, +this does not load the actual document, but only its contents: you receive a +copy of the chosen file as a new document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Export...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Saves the document under a different name.</action> (For +the moment, this is the same as +<menuchoice><guimenu>File</guimenu><guimenuitem>Save +As...</guimenuitem></menuchoice>.) +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Mail...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Sends the document via email.</action> The default &kde; +mail compose window will be used.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>P</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Prints the document.</action> You will see the usual +&kde; print dialog appear.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Print Preview...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Shows a preview of what the printed document +will look like.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Document Information</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-misc-documentinformation"><guilabel>Document +Information</guilabel> dialog</link>.</action> This dialog can be used to add +various information to the image, like title, subject, keywords, author +information, and any other information you want to save with the +image.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice></term> +<listitem><para><action>Closes the document.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits &chalk;.</action></para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Edit ================================================ --> + + +<sect2 id="commands-menus-edit"> +<title>The <guimenu>Edit</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem> +</menuchoice></term> +<listitem><para><action>Undoes the last action carried out.</action> Actions +(like painting a stroke, filling an area, etcetera) are stored on +a <quote>stack</quote>. The last action you did will be undone, and the image is +restored to the state before that. Immediately choosing +<guimenuitem>Undo</guimenuitem> again will undo the action that was carried +out before the one just undone, etcetera.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Redo</guimenuitem> +</menuchoice></term> +<listitem><para><action>Redoes the last action undone.</action> As described at +<guimenuitem>Undo</guimenuitem>, a series of actions can be undone. With +<guimenuitem>Redo</guimenuitem>, an action undone is carried out again, and if +more actions have been undone before that, you can redo these in +turn.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>X</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Cut</guimenuitem> +</menuchoice></term> +<listitem><para><action>Cuts the selection to the +clipboard.</action> The current selection is put on the &kde; +clipboard, and the selection is cleared.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the selection to the +clipboard.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice></term> +<listitem><para><action>Pastes the contents of the +clipboard.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Paste into New Image</guimenuitem> +</menuchoice></term> +<listitem><para><action>Pastes the contents of the +clipboard as a new image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Clear</guimenuitem> +</menuchoice></term> +<listitem><para><action>Clears the selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Alt;&Backspace;</keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Fill with Foreground Color</guimenuitem> +</menuchoice></term> +<listitem><para><action>Fills the selection with the current foreground +color.</action> The current foreground color is shown in the top left color +square of the <guilabel>Colors</guilabel> palette.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut>&Backspace;</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Fill with Background Color</guimenuitem> +</menuchoice></term> +<listitem><para><action>Fills the selection with the current background +color.</action> The current background color is shown in the bottom right color +square in the top left corner of the <guilabel>Colors</guilabel> +palette.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Fill with Pattern</guimenuitem> +</menuchoice></term> +<listitem><para><action>Fills the selection with the current pattern.</action> +The current pattern is shown on the <guilabel>Brush Shapes</guilabel> toolbar, +usually at the top right of the &chalk; window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guisubmenu>Resources</guisubmenu> +</menuchoice></term> +<listitem><para><action>Contains options for working with color +palettes.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guisubmenu>Resources</guisubmenu> +<guimenuitem>Add New Palette...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-misc-addpalette"><guilabel>Add Palette</guilabel> +dialog</link>.</action> You can create a custom color palette +here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guisubmenu>Resources</guisubmenu> +<guimenuitem>Edit Palette...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Edit Palette</guilabel> +dialog.</action> Choose a color palette to edit from this list. You will then be +given the same dialog as with <guilabel>Add Palette</guilabel>, with the +difference that you edit the chosen color palette instead of adding a new +one.</para> +</listitem></varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== View ================================================ --> + + +<sect2 id="commands-menus-view"> +<title>The <guimenu>View</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Full Screen Mode</guimenuitem> +</menuchoice></term> +<listitem><para><action>Switches between normal view +and full screen view.</action> In full screen view, the title +bar is hidden and the actual application window is resized to the entire +screen.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>New View</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a new view for the +current document.</action> A new application window is opened +so that you can have two different views of the same document, for example +to work on different areas at the same time, or to look at an area at different +zoom levels simultaneously. Changes you make to the document in one view are +immediately visible in other views.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>W</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Close All Views</guimenuitem> +</menuchoice></term> +<listitem><para><action>Closes all views.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Split View</guimenuitem> +</menuchoice></term> +<listitem><para><action>Splits the current view.</action> The +drawing area will be split into two parts, which can be used +just like two views in different windows.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Remove View</guimenuitem> +</menuchoice></term> +<listitem><para><action>Unsplits the view.</action> The second +view (the bottom or right one) will be closed and the first one will remain +visible.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Splitter Orientation</guisubmenu> +</menuchoice></term> +<listitem><para><action>Changes the way the split +view is displayed.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Splitter Orientation</guisubmenu> +<guimenuitem>Vertical</guimenuitem> +</menuchoice></term> +<listitem><para><action>Changes the orientation of +the splitter to vertical.</action> The two split +views will be positioned side by side.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Splitter Orientation</guisubmenu> +<guimenuitem>Horizontal</guimenuitem> +</menuchoice></term> +<listitem><para><action>Changes the orientation of +the splitter to horizontal.</action> The two split views will +be positioned above each other.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>+</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Zoom In</guimenuitem> +</menuchoice></term> +<listitem><para><action>Zooms in on the view.</action> The view +will be more detailed, but a smaller area will be visible at the +same time.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>-</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Zoom Out</guimenuitem> +</menuchoice></term> +<listitem><para><action>Zooms out of the view.</action> A larger +area will be visible at the same time, but it will be less +detailed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>0</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Actual Pixels</guimenuitem> +</menuchoice></term> +<listitem><para><action>Zooms the view to actual pixel +level.</action> (1:1 scale)</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Actual Size</guimenuitem> +</menuchoice></term> +<listitem><para><action>Zooms the view to the actual image +size.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Fit to Page</guimenuitem> +</menuchoice></term> +<listitem><para><action>Zooms the view so that the image fills the available +workspace.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show Rulers</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles display of the +rulers on and off.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show Grid</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles display of the +grid lines on and off.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Grid Spacing</guisubmenu> +</menuchoice></term> +<listitem><para><action>Contains various options to set the distance between +grid lines.</action> The available spacing options are +<guimenuitem>1x1</guimenuitem>, <guimenuitem>2x2</guimenuitem>, +<guimenuitem>5x5</guimenuitem>, <guimenuitem>10x10</guimenuitem>, +<guimenuitem>20x20</guimenuitem>, and <guimenuitem>40x40</guimenuitem>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Show Perspective Grid</guisubmenu> +</menuchoice></term> +<listitem><para><action>Toggles display of the perspective grid on and off.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Clear Perspective Grid</guisubmenu> +</menuchoice></term> +<listitem><para><action>Clears the perspective grid.</action> (All grid lines +that were created, are deleted.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +</menuchoice></term> +<listitem><para><action>Allows you to toggle the +display of the various palettes on and off.</action> The +default view of &chalk; shows all palettes, and the items are listed as Hide +<replaceable>palette</replaceable> therefore. When a certain palette is hidden, +the corresponding menu item changes to Show +<replaceable>palette</replaceable>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>H</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide All Palette Windows</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides all palettes.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Overview</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>Overview</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide HSV</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>HSV</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide RGB</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>RGB</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Gray</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>Gray</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Palettes</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>Palettes</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Layers</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the <guilabel>Layers</guilabel> +palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Scripts Manager</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the <guilabel>Scripts Manager</guilabel>. +</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Histogram</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the +<guilabel>Histogram</guilabel> palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Watercolors</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the <guilabel>Watercolors</guilabel> +palette.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Palettes</guisubmenu> +<guimenuitem>Hide Brush, Ellipse, Filter tool, Line, Polygon &etc;</guimenuitem> +</menuchoice></term> +<listitem><para><action>Hides the palette of the selected +<guilabel>Tool</guilabel>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Wetness Visualisation</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles indication of the wetness of watercolor paint +on and off.</action></para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Image =============================================== --> + + +<sect2 id="commands-menus-image"> +<title>The <guimenu>Image</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Image Properties</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-image-imageproperties"><guilabel>Image +Properties</guilabel> dialog</link>, +in which you can change the image name, size, +profile and description.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Resize Image to Size of Current Layer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Resizes the image to the +size of the currently active layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Substrate...</guisubmenu> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-image-substrate"><guilabel>Substrate</guilabel> dialog</link>.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Rotate</guisubmenu> +</menuchoice></term> +<listitem><para><action>Rotates the image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate Image...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-image-rotateimage"><guilabel>Rotate Image</guilabel> +dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate Image CW</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the image 90 degrees +clockwise.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate Image CCW</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the image 90 degrees counterclockwise +(270 degrees clockwise).</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate 180</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the image 180 degrees.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Convert Image Type...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-image-convertimagetype"><guilabel>Convert All +Layers</guilabel> dialog</link>.</action> This allows you to convert the image +to a different color space. Apart from the color space, the profile and +rendering intent can be specified as well.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Separate Image...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="commands-dialogs-image-separateimage"><guilabel>Separate Image</guilabel> +dialog</link>.</action> You can separate the image into layers for each +individual colorspace component there.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Change Image Size...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="commands-dialogs-image-imagesize"><guilabel>Image Size</guilabel> +dialog </link>.</action> You can resize or scale the image using various +algorithms here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Image</guimenu> +<guimenuitem>Shear Image...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-image-shearimage"><guilabel>Shear Image</guilabel> +dialog</link>.</action> You can shear the image in X or Y directions, +or both.</para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Layer =============================================== --> + +<sect2 id="commands-menus-layer"> +<title>The <guimenu>Layer</guimenu> Menu</title> + +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +</menuchoice></term> +<listitem><para><action>Creates a new layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>N</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guimenuitem>Add...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="commands-dialogs-layers-newlayer"><guilabel>New Layer</guilabel> +dialog</link>.</action> This will create a new empty +layer. You can set the name, opacity, composite mode and +layer type.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +</menuchoice></term> +<listitem><para><action>Creates a new layer for a +given &koffice; object type.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Scalable Graphics</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &karbon14; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Text Documents</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &kword; document.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Flowchart & Diagram</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an embedded +&kivio; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Slide Presentations</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an embedded +&kpresenter; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Image Object</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &chalk; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Report Template</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an embedded +&kugar; Designer object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Chart</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &kchart; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Formula Editor</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &kformula; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Report Generator</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &kugar; object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Project Management</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded KPlato object.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guisubmenu>Object Layer</guisubmenu> +<guimenuitem>Spreadsheets</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new layer for an +embedded &kspread; document.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guimenuitem>Adjustment Layer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-newadjustmentlayer"><guilabel>New Adjustment +Layer</guilabel>dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guimenuitem>Insert Image as Layer...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Import Image</guilabel> +dialog.</action> You can browse and select an image file, +which will be inserted in a new layer.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>J</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guimenuitem>Cut Selection to New Layer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Cuts the current selection +and inserts it as a new layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>J</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guisubmenu>New</guisubmenu> +<guimenuitem>Copy Selection to New Layer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the current selection +and inserts it as a new layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Remove</guimenuitem> +</menuchoice></term> +<listitem><para><action>Removes the current layer +and its contents.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Duplicate</guimenuitem> +</menuchoice></term> +<listitem><para><action>Duplicates the current +layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Hide/Show</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles the visibility of +the current layer in the image editing window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +</menuchoice></term> +<listitem><para>Contains actions for working with layer masks.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Create Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Mask From Selection</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Mask To Selection</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Apply Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Remove Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Edit Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Mask</guisubmenu> +<guimenuitem>Show Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>]</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>Raise</guimenuitem> +</menuchoice></term> +<listitem><para><action>Moves the current layer one +level upward.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>[</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>Lower</guimenuitem> +</menuchoice></term> +<listitem><para><action>Moves the current layer one +level downward.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>]</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>To Top</guimenuitem> +</menuchoice></term> +<listitem><para><action>Moves the current layer to the +top.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>[</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>To Bottom</guimenuitem> +</menuchoice></term> +<listitem><para><action>Moves the current layer to +the bottom.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Save Layer as Image...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Export Layer</guilabel> +dialog.</action> The current layer will be saved to the +chosen file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Flip on X Axis</guimenuitem> +</menuchoice></term> +<listitem><para><action>Flips the current layer +horizontally.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Flip on Y Axis</guimenuitem> +</menuchoice></term> +<listitem><para><action>Flips the current layer +vertically.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Properties</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-layerproperties"><guilabel>Layer +Properties</guilabel> dialog</link>.</action> You can change the name, +colorspace, opacity, composite mode and position of the current layer +here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>Merge with Layer Below</guimenuitem> +</menuchoice></term> +<listitem><para><action>Merges the current layer +with the one below it.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>E</keycap></keycombo></shortcut> +<guimenu>Layer</guimenu> +<guimenuitem>Flatten Image</guimenuitem> +</menuchoice></term> +<listitem><para><action>Merges all visible layers.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Rotate</guisubmenu> +</menuchoice></term> +<listitem><para><action>Rotates the current layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate Layer...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-rotatelayer"><guilabel>Rotate Layer</guilabel> +dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate CW</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the current layer 90 degrees +clockwise.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate CCW</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the current layer 90 degrees counterclockwise +(270 degrees clockwise).</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Rotate</guisubmenu> +<guimenuitem>Rotate 180</guimenuitem> +</menuchoice></term> +<listitem><para><action>Rotates the current layer by +180 degrees.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Histogram...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-histogram"><guilabel>Histogram</guilabel> +dialog</link>, in which you can see histograms for the current +layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Convert Layer Type...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="commands-dialogs-layers-convertlayertype"><guilabel>Convert +Current Layer</guilabel> dialog</link>.</action> You can +set various options with respect to the colorspace and +rendering intent.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Scale Layer...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-layersize"><guilabel>Layer +Size</guilabel> dialog</link>.</action> You can choose the new +dimensions and the resize filter to use.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Layer Effects</guisubmenu> +</menuchoice></term> +<listitem><para>Contains commands to add effects to the current layer. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guisubmenu>Layer Effects</guisubmenu> +<guimenuitem>Add Drop Shadow...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-dropshadow"><guilabel>Drop Shadow</guilabel> +dialog</link>.</action> This dialog can be used to add a drop shadow beneath +the current layer.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Layer</guimenu> +<guimenuitem>Shear Layer...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-layers-shearlayer"><guilabel>Shear Layer</guilabel> +dialog</link>.</action> You can select the X and Y angles to shear +by.</para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Select ============================================== --> + + +<sect2 id="commands-menus-select"> +<title>The <guimenu>Select</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the entire +current layer.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guimenuitem>Deselect</guimenuitem> +</menuchoice></term> +<listitem><para><action>Unselects everything.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guimenuitem>Reselect</guimenuitem> +</menuchoice></term> +<listitem><para><action>Reselects the previous +unselected areas.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>I</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guimenuitem>Invert</guimenuitem> +</menuchoice></term> +<listitem><para><action>Inverts the selection.</action> +(Everything that is selected will be unselected and vice +versa.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Alt;&Ctrl;<keycap>D</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guimenuitem>Feather...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Feathers the selection.</action> (Adds +a soft border around it.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Select</guimenu> +<guimenuitem>Similar</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>H</keycap></keycombo></shortcut> +<guimenu>Select</guimenu> +<guisubmenu>Hide Selection</guisubmenu> +</menuchoice></term> +<listitem><para><action>Hides the selection.</action> The selection is still +active, but it is not made visible anymore.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Select</guimenu> +<guisubmenu>Grow Selection...</guisubmenu> +</menuchoice></term> +<listitem><para><action>Grows the selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Select</guimenu> +<guisubmenu>Shrink Selection...</guisubmenu> +</menuchoice></term> +<listitem><para><action>Shrinks the selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Select</guimenu> +<guisubmenu>Border Selection...</guisubmenu> +</menuchoice></term> +<listitem><para><action>Borders the selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Select</guimenu> +<guimenuitem>Color Range...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-images-colorrange"><guilabel>Color Range</guilabel> +dialog</link>.</action></para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Filter ============================================== --> + + +<sect2 id="commands-menus-filter"> +<title>The <guimenu>Filter</guimenu> Menu</title> + +<para>See the <link linkend="filters">Filters</link> chapter for more +information on filters.</para> <para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>J</keycap></keycombo></shortcut> +<guimenu>Filter</guimenu> +<guimenuitem>Apply Filter Again</guimenuitem> +</menuchoice></term> +<listitem><para><action>Repeats the last filter +action.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +</menuchoice></term> +<listitem><para>Contains various options for changing the +colors in your image.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +<guimenuitem>Auto Contrast</guimenuitem> +</menuchoice></term> +<listitem><para><action>Automatically changes the image to obtain as much +contrast as possible.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +<guimenuitem>Brightness/Contrast...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link +linkend="commands-dialogs-filters-brightnesscontrast"><guilabel>Brightness/Contrast</guilabel> +dialog</link>.</action> You can set the +brightness and contrast ratio of your image here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +<guimenuitem>Desaturate</guimenuitem> +</menuchoice></term> +<listitem><para><action>Desaturates the image.</action> This +will effectively convert the current image to grayscale, but all subsequent +painting is done with usual colors.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +<guimenuitem>Invert</guimenuitem> +</menuchoice></term> +<listitem><para><action>Inverts the image or +selection.</action> (Black becomes white, blue becomes yellow, +etcetera.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu> +<guimenuitem>Color Adjustment...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-coloradjustment"><guilabel>Color Adjustment</guilabel> +dialog</link>.</action> You can adjust the colorspace components +of the current image there (for example, in an RGB image, you can change the +contribution of red, green, and blue to the total image).</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +</menuchoice></term> +<listitem><para>Contains various filters for +<quote>artistic</quote> actions.</para></listitem> +</varlistentry> + +<!--<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +<guimenuitem>Cubism...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-cubism"><guilabel>Cubism</guilabel> +dialog</link>.</action> This allows you to add a cubism effect to the +selection or image.</para></listitem> +</varlistentry>--> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +<guimenuitem>Oilpaint...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-oilpaint"><guilabel>Oilpaint</guilabel> +dialog</link> to add +an oilpaint effect to the selection or image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +<guimenuitem>Pixelize...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-pixelize"><guilabel>Pixelize</guilabel> +dialog</link> to pixelize the image.</action> (A block of pixels is +changed so that they all become the same, averaged color.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +<guimenuitem>Raindrops...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-raindrops"><guilabel>Raindrops</guilabel> +dialog</link> to add a raindrops effect to the selection or +image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu> +<guimenuitem>Dry the Paint</guimenuitem> +</menuchoice></term> +<listitem><para><action>Dries wet paint.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Blur</guisubmenu> +</menuchoice></term> +<listitem><para>Contains various blur filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Blur</guisubmenu> +<guimenuitem>Gaussian Blur</guimenuitem> +</menuchoice></term> +<listitem><para><action>Performs a slight blur on the image or +selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu> +</menuchoice></term> +<listitem><para>Contains filters that change the image colors.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu> +<guimenuitem>Color to Alpha</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu> +<guimenuitem>Color Transfer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-colortransfer">Color Transfer</link> dialog +to give the image a new look.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu> +<guimenuitem>Maximize Channel</guimenuitem> +</menuchoice></term> +<listitem><para><action>Adjusts the colors of each pixel by removing color +channels that are less abundant.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu> +<guimenuitem>Minimize Channel</guimenuitem> +</menuchoice></term> +<listitem><para><action>Adjusts the colors of each pixel by removing color +channels that are abundant.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +</menuchoice></term> +<listitem><para>Contains edge detecting filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +<guimenuitem>Bottom Edge Detection</guimenuitem> +</menuchoice></term> +<listitem><para><action>Performs edge detection with the bottom sides of image +parts as references.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +<guimenuitem>Left Edge Detection</guimenuitem> +</menuchoice></term> +<listitem><para><action>Performs edge detection with the left sides of image +parts as references.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +<guimenuitem>Right Edge Detection</guimenuitem> +</menuchoice></term> +<listitem><para><action>Performs edge detection with the right sides of image +parts as references.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +<guimenuitem>Sobel...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Sobel</guilabel> +dialog.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu> +<guimenuitem>Top Edge Detection</guimenuitem> +</menuchoice></term> +<listitem><para><action>Performs edge detection with the top sides of image +parts as references.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +</menuchoice></term> +<listitem><para>Contains image enhancing +filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>CImg Image Restoration...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-imagerestoration"><guilabel>Image +Restoration</guilabel> dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Custom Convolution...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-customconvolution"><guilabel>Custom +Convolution</guilabel> dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Gaussian Noise Reduction...</guimenuitem> +</menuchoice></term> +<listitem><para><action></action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Mean Removal</guimenuitem> +</menuchoice></term> +<listitem><para><action>Sharpens the image or selection by aggravating color +borders.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Sharpen</guimenuitem> +</menuchoice></term> +<listitem><para><action>Sharpens the image or selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Unsharp Mask</guimenuitem> +</menuchoice></term> +<listitem><para><action>Applies an unsharp mask to the image or +selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu> +<guimenuitem>Wavelet Noise Reducer</guimenuitem> +</menuchoice></term> +<listitem><para><action>Reduces noise in the image or +selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +</menuchoice></term> +<listitem><para>Contains emboss filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss Horizontal & Vertical</guimenuitem> +</menuchoice></term> +<listitem><para><action>Embosses the image or selection on the two main +directions.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss with Variable Depth...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-emboss"><guilabel>Emboss</guilabel> +dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss in All Directions</guimenuitem> +</menuchoice></term> +<listitem><para><action>Embosses the image or +selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss Horizontal Only</guimenuitem> +</menuchoice></term> +<listitem><para><action>Embosses the image or selection on the horizontal axis +only.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss Laplascian</guimenuitem> +</menuchoice></term> +<listitem><para><action>Embosses the image or selection using the Laplace +technique.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu> +<guimenuitem>Emboss Vertical Only</guimenuitem> +</menuchoice></term> +<listitem><para><action>Embosses the image or selection on the vertical axis +only.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu> +</menuchoice></term> +<listitem><para>Contains map filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu> +<guimenuitem>Bumpmap...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-bumpmap"><guilabel>Bumpmap</guilabel> +dialog</link>.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu> +<guimenuitem>Round Corners...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-roundcorners"><guilabel>Round +Corners</guilabel> dialog</link> to round off the corners of the image or +selection.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu> +<guimenuitem>Small Tiles...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Shrinks the image or selection and then tiles +it.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu> +</menuchoice></term> +<listitem><para>Contains miscellaneous filters.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu> +<guimenuitem>Lens Correction...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-lenscorrection">Lens Correction</link> +dialog to correct for lens anomalies.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu> +<guimenuitem>Random Noise...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-randomnoise">Random Noise</link> dialog to add +random noise to the image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu> +<guimenuitem>Random Pick...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-randompick">Random Pick</link> dialog to +distort the image.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu> +<guimenuitem>Wave...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <link +linkend="commands-dialogs-filters-wave">Wave</link> dialog to distort the +image</action></para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<guimenu>Filter</guimenu> +<guimenuitem>Filters Gallery</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="commands-dialogs-filters-filtersgallery"><guilabel>Filters +Gallery</guilabel> dialog</link>.</action> This +shows previews of the various filters and allows for easy +comparison.</para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Scripts ============================================= --> + + +<sect2 id="commands-menus-scripts"> +<title>The <guimenu>Scripts</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Scripts</guimenu> +<guimenuitem>Execute Script File</guimenuitem> +</menuchoice></term> +<listitem><para><action>Executes a script file.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Scripts</guimenu> +<guimenuitem>Script Manager</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Script Manager</guilabel> dialog. +</action></para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<!-- ====== Settings ============================================ --> + +<sect2 id="commands-menus-settings"> +<title>The <guimenu>Settings</guimenu> Menu</title> +<para> +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +</menuchoice></term> +<listitem><para>Contains options to display or hide the various +toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +<guimenuitem>File</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays or hides the <guilabel>File</guilabel> +toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +<guimenuitem>Edit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays or hides the <guilabel>Edit</guilabel> +toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +<guimenuitem>Navigation</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays or hides the <guilabel>Navigation</guilabel> +toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +<guimenuitem>&chalk;</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays or hides the +<guilabel>&chalk;</guilabel> toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +<guimenuitem>Brushes and Stuff</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays or hides the +<guilabel>Brushes and Stuff</guilabel> toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Configure Shortcuts +</guilabel> dialog.</action> This dialog is common to most &kde; applications +and allows you to configure shortcuts for all actions &chalk; has to +offer.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the <guilabel>Configure Toolbars</guilabel> +dialog.</action> This dialog is common to most &kde; applications +and allows you to configure &chalk;'s toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &chalk;...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the +<link linkend="settings-preferences"><guilabel>Preferences</guilabel> +dialog</link>.</action> You can configure &chalk; here to match your personal +preferences.</para></listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + + +<!-- ====== Help ================================================ --> + +<sect2 id="commands-menus-help"> +<title>The <guimenu>Help</guimenu> Menu</title> +&help.menu.documentation; +</sect2> + +</sect1> diff --git a/doc/chalk/commands-palettes.docbook b/doc/chalk/commands-palettes.docbook new file mode 100644 index 00000000..f71be732 --- /dev/null +++ b/doc/chalk/commands-palettes.docbook @@ -0,0 +1,769 @@ +<sect1 id="commands-palettes"> +<title>Palettes</title> + +<para> +This section describes &chalk;'s palettes. The palettes are usually found at +the right hand side of &chalk;'s main window. There are three palettes which +help you in customizing your images: +</para> + +<sect2 id="commands-palettes-controlbox"> +<title>The <guilabel>Control box</guilabel> palette</title> +<para>The <guilabel>Control box</guilabel> contains three tabs. You can get an +overview of the image, view a color histogram, and modify options for the +current tool.</para> + +<sect3 id="commands-palettes-controlbox-overview"> +<title><guilabel>Overview</guilabel></title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Overview</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-overview.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Overview</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Overview</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>This tab offers you two settings. With the spinbox, slider, and +<guibutton>1:1</guibutton> button at the bottom, you can set the zoom level +for the document. The <guilabel>Exposure</guilabel> slider and textbox can be +used to choose the exposure level for OpenEXR images. Furthermore, the +<guilabel>X</guilabel> and <guilabel>Y</guilabel> labels indicate the current +pointer position, with (0,0) being the top left corner of the canvas.</para> +</sect3> + +<sect3 id="commands-palettes-controlbox-histogram"> +<title><guilabel>Histogram</guilabel></title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Histogram</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-histogram.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Histogram</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Histogram</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>This tab displays a color histogram showing the distribution of +colors over the image. The histogram is split up in red, green and blue +levels.</para> +</sect3> + +<sect3 id="commands-palettes-controlbox-tool"> +<title><guilabel>Tool</guilabel></title> + +<para>Actually, there is no tab named like this, since the tab name changes to +reflect the name of the currently selected tool. This tab shows the +customization options available for the tools that have them.</para> + +<sect4 id="commands-palettes-controlbox-tool-brush"> +<title><guilabel>Brush</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Brush</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-brush.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Brush</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Brush</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>There are three options available on this tab. +</para><para> +The <guilabel>Opacity</guilabel> slider and spin box are used to set the +opacity when drawing (opacity is the opposite of transparency, i.e. 100% +opaque is 0% transparent, and vice versa). +</para><para> +In the <guilabel>Mode</guilabel> drop down box, you can choose a drawing +mode. This changes the actual effect that results from drawing on the image +(for example, only changing the saturation or lightness). +</para><para> +With the <guilabel>Paint direct</guilabel> option, you can determine whether +you want to paint directly on the current layer, or on a temporary layer which +is then composited onto the actual layer. This makes a difference especially +when using relative low opacity values.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-line"> +<title><guilabel>Line</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Line</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-line.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Line</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Line</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>See <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> +for the description of <guilabel>Opacity</guilabel> and +<guilabel>Mode</guilabel>. The <guilabel>?</guilabel> button shows a tip about +the usage of modifier keys.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-rectangle"> +<title><guilabel>Rectangle</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Rectangle</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-rectangle.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Tool tab for <guilabel>Rectangle</guilabel></phrase> +</textobject> +<caption><para>The Tool tab for <guilabel>Rectangle</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>See <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> for a description of <guilabel>Opacity</guilabel> and +<guilabel>Mode</guilabel>. +</para><para> +The <guilabel>Fill</guilabel> drop down box is used to specify whether the +inside of the rectangle should be filled. You can choose between three fill +options: the current foreground color, background color or pattern is +used.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-bezier"> +<title><guilabel>Bezier</guilabel></title> +<para>See <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> for the +description of <guilabel>Mode</guilabel> and <guilabel>Opacity</guilabel>.</para> +</sect4> + + +<sect4 id="commands-palettes-controlbox-tool-ellipse"> +<title><guilabel>Ellipse</guilabel></title> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-rectangle">Rectangle</link> are +available here.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-polygon"> +<title><guilabel>Polygon</guilabel></title> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-rectangle">Rectangle</link> are +available here.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-polyline"> +<title><guilabel>Polyline</guilabel></title> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-line">Line</link> +are available here.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-star"> +<title><guilabel>Star</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Star</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-star.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Star</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Star</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The options for <link +linkend="commands-palettes-controlbox-tool-rectangle">Rectangle</link> are +available here, as well as two options specific to this tool. +</para><para> +The <guilabel>Vertices</guilabel> drop down box is used to set the amount +of vertices (points) in the star. +</para><para> +The <guilabel>Ratio</guilabel> setting defines the shape of the +star. A ratio of 0% will create a star with no inner area (when drawing the +star, the two lines that make up a star point, overlap). Increasing the ratio +will slowly make the star more outlined (the two lines are <quote>pulled +apart</quote>). A star with a ratio of 100% is a regular polygon. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-duplicate"> +<title><guilabel>Duplicate</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Duplicate</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-duplicate.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Duplicate</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Duplicate</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-line">Line</link> +are available here. In addition, there are three other options. +</para><para> +With the <guilabel>Healing</guilabel> and +<guilabel>Healing radius</guilabel> options, you can specify that the +duplication should not copy the colors, but only the <quote>structure</quote> +of the source area. +</para><para> +If you enable the <guilabel>Correct the perspective</guilabel> option, the +duplicate tool will follow your perspective grid. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-paintwithfilters"> +<title><guilabel>Paint with Filters</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Paint with Filters</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-paintwithfilters.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Paint with Filters</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Paint with Filters</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>Depending on the filter, you can set different options here. The +options you can set are the same as those available in the +<quote>normal</quote> settings dialog for the chosen filter. See the +<link linkend="commands-dialogs-filters">Filters section in the Dialogs +chapter</link> for more information.</para> </sect4> + +<sect4 id="commands-palettes-controlbox-tool-transform"> +<title><guilabel>Transform</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Transform</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-transform.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Transform</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Transform</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<!-- >The <guilabel>Move X</guilabel> and <guilabel>Move Y</guilabel> +spin boxes show, and can be used to set, the displacement of the layer or +selection. The same applies to <guilabel>Scale X</guilabel> and <guilabel>Scale +Y</guilabel> for the scaling of the current layer or selection. Finally, --> +<para>You can choose which transformation algorithm to use in the +<guilabel>Filter</guilabel> drop down box.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-crop"> +<title><guilabel>Crop</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Crop</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-crop.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Crop</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Crop</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>Set the corner coordinates of the area that should remain with the +four spin boxes <guilabel>X</guilabel>, <guilabel>Y</guilabel>, +<guilabel>Width</guilabel> and <guilabel>Height</guilabel>. You can also +fill in <guilabel>Ratio</guilabel> to determine the Y/X ratio. Check one of +the checkboxes to have the respective value remain constant while changing the +size of the area. The drop down box can be used to select whether the entire +image or only the current layer should be cropped. Clicking the +<guibutton>Crop</guibutton> button has the same effect as double-clicking +outside the area in the image.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-contiguousfill"> +<title><guilabel>Contiguous Fill</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Contiguous Fill</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-contiguousfill.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Contiguous Fill</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Contiguous Fill</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> +are available here, as are a couple of other options. +</para><para> +The setting in the <guilabel>Threshold</guilabel> slider and spin box +determines how near the color of a point should be to the color of the +starting point of the fill, in order for the fill to spread out over the +former point. A higher threshold will therefore fill areas that have less +similar colors, a lower threshold limits the spread. +</para><para> +If you check the <guilabel>Fill entire selection</guilabel> checkbox, the +entire selection will be filled instead of only the neighboring area. +</para><para> +Checking the <guilabel>Limit to current layer</guilabel> checkbox changes the +behavior of the fill: the extent to which the fill is done, is determined from +the current layer only instead of the entire image. +</para><para> +By checking the <guilabel>Use pattern</guilabel> checkbox you can choose to +fill with the currently selected pattern instead of with the foreground color. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-gradient"> +<title><guilabel>Gradient</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Gradient</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-gradient.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Gradient</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Gradient</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> +are available here, as are a couple of other options. +</para><para> +The <guilabel>Shape</guilabel> drop down box can be used to select the gradient +type: <guilabel>Linear</guilabel>, <guilabel>Bi-Linear</guilabel>, <guilabel>Radial</guilabel>, +<guilabel>Square</guilabel>, <guilabel>Conical</guilabel> and <guilabel>Conical Symmetric</guilabel>. +</para><para> +The <guilabel>Repeat</guilabel> option determines whether the gradient is +repeated if it does not fill the entire image. With <guilabel>None</guilabel>, the colors on the +ends of the gradient are used to fill the remaining space. With <guilabel>Forwards</guilabel>, the +gradient is normally repeated (connecting the back end of one occurrence with +the front end of the next). With <guilabel>Alternating</guilabel>, the gradient is repeated with +every second occurrence being drawn from back to front (linking front to front +and back to back). +</para><para> +Check the <guilabel>Reverse</guilabel> checkbox to have the gradient drawn +reversed (from back to front). +</para><para> +The final setting is <guilabel>Anti-alias threshold</guilabel>, which +determines how smooth the gradient will become. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-text"> +<title><guilabel>Text</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Text</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-text.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Text</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Text</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The same options as for <link +linkend="commands-palettes-controlbox-tool-brush">Brush</link> +are available here. Furthermore there is an option <guilabel>Font</guilabel>, +which shows the font that will be used for the text. Click the +<guibutton>...</guibutton> button to change the font. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-colorpicker"> +<title><guilabel>Color Picker</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Color Picker</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-colorpicker.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Color Picker</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Color Picker</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The first option is a dropdown box in which you can choose which +layer to pick the color from. If you choose a specific layer, +the color of the point in that layer will be retrieved. With <guilabel>Sample +All Visible Layers</guilabel>, the topmost visible layer which is not +transparent at that point is used. +</para><para> +If the <guilabel>Update current color</guilabel> checkbox is checked, then the +current foreground color (when clicking with the &LMB;) or background color +(when clicking with the &RMB;) is set to the picked color. +</para><para> +The checkbox <guilabel>Add to palette</guilabel> and the accompanying +dropdown box determine whether the picked color should be added to an existing +palette. Check the checkbox, and choose the desired palette from the list, if +you want to do so. +</para><para> +The checkbox <guilabel>Show colors as percentages</guilabel> switches the +range of color values displayed from the <quote>normal</quote> range (e.g. 0 to +255) to a scaled value between 0% and 100%. +</para><para> +With the <guilabel>Sample radius</guilabel> option, you can choose the area +size to use when picking the color. A radius of one just picks one pixel, +larger radii will make the picker average over the colors of the circle-shaped +area with the chosen radius that is centered around the chosen pixel. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-select"> +<title><guilabel>Select</guilabel> tools</title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Select</guilabel> tools</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-select.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Select</guilabel> tools</phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Select</guilabel> tools</para></caption> +</mediaobject> +</screenshot> +</para> +<para>The <guilabel>Paint Selection</guilabel>, <guilabel>Erase Selection</guilabel>, +<guilabel>Select Rectangular</guilabel>, <guilabel>Select Elliptical</guilabel>, <guilabel>Select Polygonal</guilabel> and <guilabel>Select Outline</guilabel> tools have one option: +the <guilabel>Action</guilabel> to perform. You can choose between <guilabel>Add</guilabel> to, or +<guilabel>Subtract</guilabel> from the selection.</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-selectcontiguous"> +<title><guilabel>Select Contiguous Area</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Select Contiguous</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-selectcontiguous.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Select Contiguous</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Select Contiguous</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The <guilabel>Action</guilabel> is the same as discussed with the +<link linkend="commands-palettes-controlbox-tool-select">Select +operations</link>. +</para><para> +The slider and spin box at <guilabel>Fuzziness</guilabel> determine how near +colors must be to the color at the clicked point to be added to the selection. +</para><para> +When the <guilabel>Sample merged</guilabel> checkbox is checked, the +bounds of the selection are determined by looking at the entire image instead +of at the current layer. +</para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-selectsimilar"> +<title><guilabel>Similar Select</guilabel></title> +<para>The <guilabel>Action</guilabel> and <guilabel>Fuzziness</guilabel> +options are the same as with <link +linkend="commands-palettes-controlbox-tool-selectcontiguous">Select +contiguous</link>. </para> +</sect4> + +<sect4 id="commands-palettes-controlbox-tool-selectmagnetic"> +<title><guilabel>Select Magnetic</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Tool</guilabel> tab for <guilabel>Select Magnetic</guilabel></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-controlbox-selectmagnetic.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tool</guilabel> tab for <guilabel>Select Magnetic</guilabel></phrase> +</textobject> +<caption><para>The <guilabel>Tool</guilabel> tab for <guilabel>Select Magnetic</guilabel></para></caption> +</mediaobject> +</screenshot> +</para> +<para>The <guilabel>Action</guilabel> option is the same as with the other +<link linkend="commands-palettes-controlbox-tool-select">Select tools</link>. +</para> +<para> +The <guilabel>Distance</guilabel> option determines the maximal distance at +which boundaries to attach to, are searched for. The <guibutton>To +Selection</guibutton> button has the same effect as double-clicking the &LMB;: +the selection is finished. +</para> +</sect4> + +</sect3> + +</sect2> + +<sect2 id="commands-palettes-colors"> +<title>The <guilabel>Colors</guilabel> palette</title> +<para>In this palette you can choose the foreground and background colors +that should be used for painting. You can choose these in five different +ways. Each of these has its own tab on this palette. +</para><para> +You can choose which color to set by clicking the corresponding +buttons at the top left. The topmost color is the foreground color, the +bottom one is the background color. You can click the double-headed arrow +to swap the colors: foreground color becomes background color and vice +versa. You can reset the colors to the default (foreground black, background +white) by clicking the small black/white icon. +</para> + +<sect3 id="commands-palettes-colors-hsv"> +<title><guilabel>HSV</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>HSV</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-colors-hsv.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>HSV</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>HSV</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>On this tab, you can select a color via the Hue / Saturation / Value +system. +</para><para> +The hue determines the major color and starts at red with 0, then increases +along the color spectrum (that is, along the <quote>line</quote> yellow, green, +blue, violet) to a maximum of 359. This is represented in the circle on the tab +as the angle component (starting at the top, rotate along the circle +in clockwise direction to increase the hue). +</para><para> +The saturation determines the pureness of the color. A saturation of 255 +yields the pure color, while a saturation of 0 yields a gray. This is the +radius component of the color circle on the tab: the center corresponds to +no saturation, the circle boundary corresponds to fully saturated. +</para><para> +The value determines the lightness of the color. This darkens or lightens the +color, as can be set using the vertical slider on the tab. A value of 0 gives +black, a value of 255 gives the pure color. +</para> +</sect3> + +<sect3 id="commands-palettes-colors-rgb"> +<title><guilabel>RGB</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>RGB</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-colors-rgb.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>RGB</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>RGB</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>On this tab, colors can be selected using their Red / Green / Blue +components. +</para><para> +You can set red, green and blue components on a scale of 0 to 255. At 0 that +color component is absent, at 255 it is used at maximum intensity. The sliders +will change color to give you a hint about which color you will produce by +altering the corresponding value. +</para> +</sect3> + +<sect3 id="commands-palettes-colors-gray"> +<title><guilabel>Gray</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Gray</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-colors-gray.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Gray</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Gray</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>On this tab, you can choose a gray value (indicated with a K for Key, +the usual designation for black).</para> +<para>The gray value can be chosen on a scale from 0 (pure white) to 255 +(pure black).</para> +</sect3> + +<sect3 id="commands-palettes-colors-palettes"> +<title><guilabel>Palettes</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Palettes</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-colors-palettes.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Palettes</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Palettes</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>On this tab, you can select a color from one of several predefined +color palettes.</para> +<para>You can choose which color palette to pick from in the drop down +box at the top.</para> +</sect3> + +<sect3 id="commands-palettes-colors-watercolors"> +<title><guilabel>Watercolors</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Watercolors</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-colors-watercolors.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Watercolors</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Watercolors</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>This tab offers you a selection of watercolors for painting with <quote>wet +paint</quote>. +</para><para> +You can set two options to modify the painting behaviour: <guilabel>Paint +strength</guilabel> influences how much paint you will apply to the canvas, +and <guilabel>Wetness</guilabel> determines how wet the paint is when it is +applied. You can dry the paint later. +</para> +</sect3> + +</sect2> + +<sect2 id="commands-palettes-layers"> +<title>The <guilabel>Layers</guilabel> palette</title> +<para>This palette offers two tabs.</para> + +<sect3 id="commands-palettes-layers-layers"> +<title><guilabel>Layers</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Layers</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-layers-layers.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Layers</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Layers</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>This tab offers you access to various operations on layers. +</para><para> +On the top left, you can select what blending mode should be used for the +selected layer. These are the same possibilities as you can choose from for +drawing modes. +</para><para> +The slider/textbox at the top right determines the opacity of the selected +layer. 0% opacity corresponds to 100% transparency, and vice versa. +</para><para> +The list shows all layers and their names, and offers various controls for each +layer. The eye icon toggles whether the layer is visible or not. The link icon +is used to link layers together. The lock icon determines if the layer is +locked or not. Locked layers cannot be edited. +</para><para> +Below the layer list, there are some other controls. You can create a new +layer, move the current layer up or down, show the layer's properties and +delete it. +</para> +<para> +There are some more handy tricks you can do with the mouse within the list. +Right-click on the layer list and select <guilabel>New Folder</guilabel> to +create a new layer folder, which you can use to group layers in. You can also +drag and drop layers to change their order. To do so, click on the bottom part +of the list item representing the layer, drag the mouse, and release the mouse +button at the desired position. If you click at the top part of the list item +instead, you will get a text field so that you can rename the layer. +</para> +</sect3> + +<sect3 id="commands-palettes-layers-scriptsmanager"> +<title><guilabel>Scripts Manager</guilabel></title> +<para> +<screenshot> +<screeninfo>The <guilabel>Script Manager</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="palettes-layers-scriptsmanager.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Script Manager</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Script Manager</guilabel> tab</para></caption> +</mediaobject> +</screenshot> +</para> +<para>This tab is a smaller version of the <guilabel>Script +Manager</guilabel> dialog. See the description over there for more +information. +</para> +</sect3> + +</sect2> + +</sect1> diff --git a/doc/chalk/commands-toolbars.docbook b/doc/chalk/commands-toolbars.docbook new file mode 100644 index 00000000..b99457f1 --- /dev/null +++ b/doc/chalk/commands-toolbars.docbook @@ -0,0 +1,752 @@ +<sect1 id="commands-toolbars"> +<title>Toolbars</title> + +<para>This section describes &chalk;'s toolbars. By default, the +<guilabel>Chalk</guilabel> toolbar is located to the left of the drawing area, +while the others can be found at the top, below the menu bar.</para> + +<para>You can customize your toolbars by choosing +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Toolbars...</guimenuitem></menuchoice> or by clicking with the &RMB; on a +toolbar and choosing <guimenuitem>Configure Toolbars...</guimenuitem>.</para> + +<sect2 id="commands-toolbars-file"> +<title>The <guilabel>File</guilabel> Toolbar</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>File</guilabel> toolbar</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-file.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>File</guilabel> toolbar</phrase> +</textobject> +<caption><para>The <guilabel>File</guilabel> toolbar</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>This toolbar contains actions for working with files. In &chalk;'s +default, there are five buttons on this toolbar: <guilabel>New</guilabel>, +<guilabel>Open</guilabel>, <guilabel>Save</guilabel>, <guilabel>Print +Preview</guilabel>, and <guilabel>Print</guilabel>.</para> + +<para>These actions all correspond to entries in the <link +linkend="commands-menus-file"><guimenu>File</guimenu> menu</link>.</para> + +</sect2> + +<sect2 id="commands-toolbars-edit"> +<title>The <guilabel>Edit</guilabel> Toolbar</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Edit</guilabel> toolbar</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-edit.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Edit</guilabel> toolbar</phrase> +</textobject> +<caption><para>The <guilabel>Edit</guilabel> toolbar</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>This toolbar contains editing actions. With default settings this +toolbar offers four buttons: <guilabel>Undo</guilabel>, +<guilabel>Redo</guilabel>, <guilabel>Cut</guilabel>, and +<guilabel>Copy</guilabel>.</para> + +<para>These actions all correspond to entries in the <link +linkend="commands-menus-edit"><guimenu>Edit</guimenu> menu</link>.</para> +</sect2> + +<sect2 id="commands-toolbars-navigation"> +<title>The <guilabel>Navigation</guilabel> Toolbar</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Navigation</guilabel> toolbar</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-navigation.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Navigation</guilabel> toolbar</phrase> +</textobject> +<caption><para>The <guilabel>Navigation</guilabel> toolbar</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>This toolbar offers easy access to navigation actions. The two +default actions available are <guilabel>Zoom In</guilabel> and +<guilabel>Zoom Out</guilabel>. With <guilabel>Zoom In</guilabel>, the zoom +level is increased. You will see less, but in higher detail. With +<guilabel>Zoom Out</guilabel>, the zoom level is decreased, so that you see +more at less detail. </para> + +</sect2> + +<sect2 id="commands-toolbars-chalk"> +<title>The <guilabel>Chalk</guilabel> Toolbar</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Chalk</guilabel> toolbar</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-chalk.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Chalk</guilabel> toolbar</phrase> +</textobject> +<caption><para>The <guilabel>Chalk</guilabel> toolbar</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This toolbar contains painting operations and tools, as well as editing and +selecting tools. The available actions and some controls are listed below. You +can change the behaviour of most tools (and with that, usually the resulting +effect) by setting their <link +linkend="commands-palettes-controlbox-tool">options</link>. +</para> + +<variablelist> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-brush.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Brush</guilabel></term> +<listitem><para> +With this tool you can paint freely. Click the &LMB; to paint a +single instance of the currently selected brush, or hold the &LMB; and drag +your mouse around to paint. The mouse movements you make are directly used for +painting. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-line.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Line</guilabel></term> +<listitem><para> +This tool is used to draw lines. Click the &LMB; to indicate the first +endpoint, keep the button pressed, drag to the second endpoint and release the +button. +</para><para> +Use &Shift; while holding the mouse button to restrict drawing to only +horizontal or vertical lines. You can press &Alt; while still keeping the &LMB; +down to move the line to a different location. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-rectangle.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Rectangle</guilabel></term> +<listitem><para> +This tool can be used to paint rectangles. Click and hold the &LMB; to indicate +one corner of the rectangle, drag to the opposite corner, and release the +button. +</para><para> +If you hold &Shift; while drawing, a square will be drawn instead of a +rectangle. Holding &Ctrl; will change the way the rectangle is constructed. +Normally, the first mouse click indicates one corner and the second click the +opposite. With &Ctrl;, the initial mouse position indicates the center of the +rectangle, and the final mouse position indicates a corner. +You can press &Alt; while still keeping the &LMB; down to move the rectangle to +a different location. +</para><para> +You can change between the corner/corner and center/corner drawing +methods as often as you want by pressing or releasing &Ctrl;, provided that you +keep the &LMB; pressed. With &Ctrl; pressed, mouse movements will affect all +four corners of the rectangle (relative to the center), without &Ctrl;, one +of the corners is unaffected. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-ellipse.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Ellipse</guilabel></term> +<listitem><para> +Use this tool to paint an ellipse. The currently selected brush is used for +drawing the ellipse outline. Click and hold the &LMB; to indicate one corner of +the <quote>bounding rectangle</quote> of the ellipse, then move your mouse to +the opposite corner. &chalk; will show a preview of the ellipse using a thin +line. Release the button to draw the ellipse. +</para><para> +If you hold &Shift; while drawing, a circle will be drawn instead of an +ellipse. Holding &Ctrl; will change the way the ellipse is constructed: instead +of two corners, the initial mouse position indicates the ellipse center, and the +final mouse position indicates one of the corners of the bounding rectangle. +You can press &Alt; while still keeping the &LMB; down to move the ellipse to a +different location. +</para><para> +You can change between the corner/corner and center/corner drawing +methods as often as you want by pressing or releasing &Ctrl;, provided that you +keep the &LMB; pressed. With &Ctrl; pressed, mouse movements will +affect all four corners of the bounding rectangle (relative to the center), +without &Ctrl;, the corner opposite to the one you are moving remains still. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-polygon.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Polygon</guilabel></term> +<listitem><para> +With this tool you can draw polygons. Click the &LMB; to indicate the +starting point and successive vertices, then double-click or press &Enter; to +connect the last vertex to the starting point. +</para></listitem></varlistentry> + +<varlistentry> <term><inlinemediaobject><imageobject><imagedata +fileref="tool-polyline.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Polyline</guilabel></term> +<listitem><para> +Polylines are drawn like polygons, with the difference that the double-click +indicating the end of the polyline does not connect the last vertex to the +first one. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-star.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Star</guilabel></term> +<listitem><para> +This tool creates star-shaped objects. Press the &LMB; to indicate the center, +and drag the mouse to change the size and rotation of the star. +</para><para> +You can press &Alt; while still keeping the &LMB; down to move the star to a +different location. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-bezier.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Bezier</guilabel></term> +<listitem><para> +You can draw Bezier curves by using this tool. Click the &LMB; to indicate the +starting point of the curve, then click again for consecutive control points +of the curve. +</para> +<para> +<screenshot> +<screeninfo>Drawing a Bezier curve</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tool-bezier-example.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Drawing a Bezier curve</phrase> +</textobject> +<caption><para>Drawing a Bezier curve</para></caption> +</mediaobject> +</screenshot> +</para> +<para> +&chalk; will show a blue line with two handles when you add a control point. +You can drag these handles to change the direction of the curve in that point. +</para> +<para> +<screenshot> +<screeninfo>Modifying a Bezier curve</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tool-bezier-example2.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Modifying a Bezier curve</phrase> +</textobject> +<caption><para>Modifying a Bezier curve</para></caption> +</mediaobject> +</screenshot> +</para> +<para> +You can click on a previously inserted control point to modify it. With an intermediate +control point (&ie; a point that is not the starting point and not the ending +point), you can move the direction handles seperately to have the curve enter +and leave the point in different directions. After editing a point, you can +just click on the canvas to continue adding points to the curve. +</para> +<para> +Pressing <keycap>Delete</keycap> will remove the currently selected control +point from the curve. Double-click the &LMB; on any point of the curve or +press &Enter; to finish drawing, or press &Esc; to cancel the entire curve. +You can use &Ctrl; while keeping the &LMB; pressed to move the entire curve to +a different position. +</para> +<para> +<screenshot> +<screeninfo>A finished Bezier curve</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tool-bezier-example3.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>A finished Bezier curve</phrase> +</textobject> +<caption><para>A finished Bezier curve</para></caption> +</mediaobject> +</screenshot> +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-duplicate.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Duplicate</guilabel></term> +<listitem><para> +You can use this tool to duplicate parts of an image. Press &Shift; and click +with the &LMB; on the location you want to duplicate from. &chalk; will +indicate this location by an outline of your current brush. Then click with +the &LMB; to designate the location where you want to duplicate to, and drag +with the mouse. You will then duplicate whatever is at the source location to +the current (destination) location. +</para><para> +While you are painting the duplicate, both your cursor in the destination +location and the brush outline in the source location will move, in order to +give you visual feedback. +</para><para> +You can also use this tool to correct colors in a part of the image: use the +<guilabel>Healing</guilabel> option for that. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-paintwithfilters.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Paint with +filters</guilabel></term> +<listitem><para> +This tool allows you to pick a filter and draw with it. The image below shows +the effect of using a large circular brush and painting with, from left to +right, the Maximize Channel, Minimize Channel, Invert, and Desaturate filters. +</para> +<para> +<screenshot> +<screeninfo>Painting with filters</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tool-paintwithfilters-example.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Painting with filters</phrase> +</textobject> +<caption><para>Painting with filters</para></caption> +</mediaobject> +</screenshot> +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-crop.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Crop</guilabel></term> +<listitem><para> +With this tool you can crop a layer or an image to a certain rectangular area. +Click and drag with the &LMB; to define an area. This area is designated by an +outline with 8 handles. You can then use the handles to change the size of the +area which the image or layer is to be cropped to. You can also click and drag +inside the area to move the outline in its entirety. +</para><para> +Double-click outside the area (i.e. on a part of the image that is to be removed) +to confirm the cropping operation. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-move.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Move</guilabel></term> +<listitem><para> +With this tool, you can move the current layer or selection by dragging the +mouse. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata fileref="tool-transform.png" +format="PNG"></imagedata> </imageobject></inlinemediaobject> Transform</term> +<listitem><para> +With this tool you can quickly transform the current selection or layer. +Handles will appear at the corners and sides, with which you can resize the +selection or layer. You can perform rotations by moving the mouse above or to +the left of the handles and dragging it. You can also click anywhere inside +the selection or layer and move it by dragging the mouse. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-perspectivetransform.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Perspective Transform</guilabel></term> +<listitem><para> +This tool allows you to change the perspective of an image. Designate the area +which should become the new image by clicking at its top-left, top-right, +bottom-right and bottom-left corners. The area given by these four corners +will then be transformed so that the given corners become the corners of the +actual image. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-contiguousfill.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Contiguous Fill</guilabel></term> +<listitem><para> +Use this tool to fill a contiguous area of one color with the current +foreground color or a pattern. Simply click to fill up the area. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-gradient.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Gradient</guilabel></term> +<listitem><para> +This tool fills the current layer or selection with the currently selected +gradient. Click the &LMB;, hold it, and drag the mouse to define two endpoints. +The gradient will be drawn along this line. If the line does not extend to the +border of the selection or layer, the color at the corresponding endpoint of +the gradient will be used to fill up the rest of the area at that side. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-text.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Text</guilabel></term> +<listitem><para> +With this tool you can add simple text to your image. Click the &LMB; on the +location at which you want have the text. Then enter the desired text in the +dialog window that appears. The text will be horizontally centered on, and +the top of the text will be at the same height as, the chosen location. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-colorpicker.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Color Picker</guilabel></term> +<listitem><para> +With this tool you can find the color values of a point. Click the &LMB; +somewhere in the image to see color information about that point in the +<guilabel>Control box</guilabel>. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-pan.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Pan</guilabel></term> +<listitem><para> +This tool can be used to navigate through your image. Click and hold the &LMB; +and move the mouse to scroll in a certain direction. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-zoom.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Zoom</guilabel></term> +<listitem><para> +Use this tool to zoom in and out. Click the &LMB; to increase the zoom by +a factor 2 (e.g. 1:1 to 2:1), click the &RMB; to decrease the zoom by a factor +2 (e.g. 1:1 to 1:2). +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-perspectivegrid.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Perspective Grid</guilabel></term> +<listitem><para> +You can create and edit a perspective grid with this tool. Click the &LMB; and +drag the mouse to indicate the first two corners of the grid, then click for +the third and fourth corners. The outline of the grid is now shown and you can +edit it if you are not completely happy. When you switch to a different tool, +the perspective grid will be subdivided and shown as thin gray lines. +</para> +<note><para>If you only see three corners instead of four, you probably +clicked instead of dragging initially. In this case you can still click the +handle of your now combined first and second corners and drag it to get four +separate corners.</para></note> +<para> +Clicking the <guilabel>Perspective Grid</guilabel> tool again later will allow +you to modify the grid. You can hide or remove the grid by choosing the +<guimenuitem>Hide Perspective Grid</guimenuitem> or <guimenuitem>Clear +Perspective Grid</guimenuitem> options from the <guimenu>View</guimenu> menu. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-paintselection.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Paint Selection</guilabel></term> +<listitem><para> +This tool can be used to select custom areas. The currently selected brush is +used to select areas: instead of painting on the image, the area is selected. +For more information on selections, see <link +linkend="selections">the Selections chapter</link>. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-eraseselection.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Erase Selection</guilabel></term> +<listitem><para> +This tool works almost the same as the <guilabel>Paint Selection</guilabel> +tool, but a selection, if it exists at the mouse location, is removed instead +of created. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectrectangular.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Select Rectangular</guilabel></term> +<listitem><para> +You can use this tool to select rectangular areas. Operation is similar to the +<guilabel>Rectangle</guilabel> tool, and &Shift;, &Ctrl; and &Alt; can be used +like when painting rectangles. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectelliptical.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Select Elliptical</guilabel></term> +<listitem><para> +You can use this tool to select elliptical areas. Operation is similar to the +<guilabel>Ellipse</guilabel> tool, and &Shift;, &Ctrl; and &Alt; can be used +like when painting ellipses. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectpolygonal.png" +format="PNG"></imagedata> </imageobject></inlinemediaobject> <guilabel>Select +Polygonal</guilabel></term> +<listitem><para> +You can use this tool to select polygonal areas. Operation is similar to the +<guilabel>Polygon</guilabel> tool, and &Shift;, &Ctrl; and &Alt; can be used +like when painting polygons. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectoutline.png" +format="PNG"></imagedata> </imageobject></inlinemediaobject> <guilabel>Select +Outline</guilabel></term> +<listitem><para> +You can use this tool to select custom outlined areas. Click the &LMB; and drag +with your mouse, like when painting with the <guilabel>Brush</guilabel> tool, +to define the outline. When you release the mouse button, the outline will be +finished with a straight line between the current position and the start +position. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectcontiguous.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Select Contiguous</guilabel></term> +<listitem><para> +With this tool you can select contiguous areas of a color. Click with the +&LMB; to select an area. +</para></listitem></varlistentry> + +<varlistentry> +<term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectsimilar.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Select Similar</guilabel></term> +<listitem><para> +With this tool you can select multiple areas with the same color. Detection is +done the same as with the contiguous fill, but the areas do not need to be +adjacent. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectmagnetic.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Magnetic Selection</guilabel></term> +<listitem><para> +With this tool you can easily select a visually distinct area. Click with the +&LMB; and move the mouse around the area that you want to select. If the area +has a well enough defined boundary, the selection will be drawn nicely around +it. You will see a number of control points appear, which connect the various +parts of the selection boundary. +</para><para> +If you want more control over the area that is selected, press &Ctrl; to +switch to manual mode. You will now have to click for each control point. +In manual mode, you can also move control points by clicking on them with the +&LMB; and dragging with the mouse. +</para><para> +When you want to return to automatic mode, simply press &Ctrl; again. You can +switch between these two modes as often as you like. +</para></listitem></varlistentry> + +<varlistentry><term><inlinemediaobject><imageobject><imagedata +fileref="tool-selectbezier.png" format="PNG"></imagedata> +</imageobject></inlinemediaobject> <guilabel>Select Bezier</guilabel></term> +<listitem><para> +With this tool you can select an area by drawing a Bezier outline. See the +description of the Bezier tool for details. +</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="commands-toolbars-brushesandstuff"> +<title>The <guilabel>Brushes and Stuff</guilabel> Toolbar</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Brushes and Stuff</guilabel> toolbar</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushesandstuff.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Brushes and Stuff</guilabel> toolbar</phrase> +</textobject> +<caption><para>The <guilabel>Brushes and Stuff</guilabel> toolbar</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>This toolbar contains dropdown <quote>palettes</quote> in which you +can choose brush shapes, gradients, and fill patterns. It also contains a +dropdown box for painter's tools, and a tablet pressure setting.</para> + +<sect3 id="commands-toolbars-brushesandstuff-brushshapes"> +<title><guilabel>Brush Shapes</guilabel></title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Brush Shapes</guilabel> palette</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-brushshapes-predefined.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Brush Shapes</guilabel> palette</phrase> +</textobject> +<caption><para>The <guilabel>Brush Shapes</guilabel> palette</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>In the <guilabel>Brush Shapes</guilabel> palette, you can choose +which brush to paint with. This brush is used for painting operations +like <guilabel>Freehand</guilabel>, <guilabel>Rectangle</guilabel>, +<guilabel>Ellipse</guilabel>, etcetera. You can choose a predefined +brush (in the <guilabel>Predefined Brushes</guilabel> tab, shown above), or +customize or create one.</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Autobrush</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-brushshapes-autobrush.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Autobrush</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Autobrush</guilabel> +tab</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>The <guilabel>Autobrush</guilabel> tab allows you to create a customized +rectangular or ellipsoid brush. You can set its height and width using +the <guilabel>Size</guilabel> spin boxes. The link icon controls whether +the height and width are forced to be the same or not. If a connected link +picture is shown, changing one value will automatically change the other one +as well. A disconnected link indicates that both values can be set +independently. The fuzziness of the brush can be set with the +<guilabel>Fade</guilabel> spin boxes. Again, horizontal and vertical values can +be allowed to differ or not, depending on the state of the link button.</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Custom Brush</guilabel> tab</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-brushshapes-custombrush.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Custom Brush</guilabel> tab</phrase> +</textobject> +<caption><para>The <guilabel>Brush Shapes</guilabel> palette with the <guilabel>Custom Brush</guilabel> +tab</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>The <guilabel>Custom Brush</guilabel> tab of this palette lets you +use the current image as a brush. With the <guibutton>Add to +Predefined Brushes</guibutton> button, you can save it for later use.</para> + +</sect3> + +<sect3 id="commands-toolbars-brushesandstuff-gradients"> +<title>Gradients</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Gradients</guilabel> palette</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-gradients.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Gradients</guilabel> palette</phrase> +</textobject> +<caption><para>The <guilabel>Gradients</guilabel> palette</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>In the <guilabel>Gradients</guilabel> palette, you can choose a gradient +to paint with using the <guilabel>Gradient</guilabel> tool. Clicking once on a gradient in the +palette will show a larger preview. Click it again to make it the current +gradient.</para> +<para>You can create your own gradients with the <guibutton>Custom +Gradient</guibutton> button.</para> + +</sect3> + +<sect3 id="commands-toolbars-brushesandstuff-patterns"> +<title>Patterns</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Patterns</guilabel> palette</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-patterns.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Patterns</guilabel> palette</phrase> +</textobject> +<caption><para>The <guilabel>Patterns</guilabel> palette</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>The <guilabel>Patterns</guilabel> palette allows you to choose a pattern +for operations like Pattern fill. Click a pattern to see a preview at +actual size, then click it again to select it.</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>Patterns</guilabel> palette with the <guilabel>Custom Pattern</guilabel> tab selected</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="toolbar-brushes-patterns-custompattern.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Patterns</guilabel> palette with the <guilabel>Custom Pattern</guilabel> tab selected</phrase> +</textobject> +<caption><para>The <guilabel>Patterns</guilabel> palette with the <guilabel>Custom Pattern</guilabel> tab selected</para></caption> +</mediaobject> +</screenshot> +</para> + +<para>You can also create a custom pattern, as is shown above.</para> + +</sect3> + +<sect3 id="commands-toolbars-brushesandstuff-painterstools"> +<title>Painter's tools</title> + +<para>With the <guilabel>Painter's tools</guilabel> dropdown box, you can +select the tool your painting operation should simulate. For example, you can +paint with a normal brush, an airbrush, or a filter.</para> + +</sect3> + +<sect3 id="commands-toolbars-brushesandstuff-pressurevariation"> +<title>Pressure variation</title> + +<para>This setting allows you to change &chalk;'s behaviour when you use a +tablet to paint with. When you change the pressure on the tablet, you can +choose between changing the line width (<guilabel>size</guilabel>), the +opacity, and the darkness.</para> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/chalk/commands.docbook b/doc/chalk/commands.docbook new file mode 100644 index 00000000..cc50aa29 --- /dev/null +++ b/doc/chalk/commands.docbook @@ -0,0 +1,14 @@ +<chapter id="commands"> +<title>Command Reference</title> + +<para> +This chapter explains &chalk;'s user interface in detail. Each of the menus, +toolbars, palettes, and dialogs will be discussed. +</para> + +&commands-menus; +&commands-toolbars; +&commands-palettes; +&commands-dialogs; + +</chapter> diff --git a/doc/chalk/createdocument.png b/doc/chalk/createdocument.png Binary files differnew file mode 100644 index 00000000..79047af8 --- /dev/null +++ b/doc/chalk/createdocument.png diff --git a/doc/chalk/credits.docbook b/doc/chalk/credits.docbook new file mode 100644 index 00000000..d6c3defc --- /dev/null +++ b/doc/chalk/credits.docbook @@ -0,0 +1,63 @@ +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&chalk; +</para> +<para> +Program copyright © 1999-2006 The &chalk; Team +</para> + +<para> +Contributors: + +<itemizedlist> +<listitem><para>Adrian Page +<email>Adrian.Page@tesco.net</email></para></listitem> +<listitem><para>Andrew Richards +<email>physajr@phys.canterbury.ac.nz</email></para></listitem> +<listitem><para>Bart Coppens <email>kde@bartcoppens.be</email></para></listitem> +<listitem><para>Boudewijn Rempt +<email>boud@valdyas.org</email> (current maintainer)</para></listitem> +<listitem><para>Carsten Pfeiffer +<email>pfeiffer@kde.org</email></para></listitem> +<listitem><para>Casper Boemann <email>cbr@boemann.dk</email></para></listitem> +<listitem><para>Cyrille Berger <email>cyb@lepi.org</email></para></listitem> +<listitem><para>Danny Allen +<email>dannya40uk@yahoo.co.uk</email></para></listitem> +<listitem><para>Dirk Schoenberger +<email>dirk.schoenberger@sz-online.de</email></para></listitem> +<listitem><para>Gábor Lehel +<email>illissius@gmail.com</email></para></listitem> +<listitem><para>John Califf +<email>jcaliff@compuzone.net</email></para></listitem> +<listitem><para>Matthias Elter <email>elter@kde.org</email></para></listitem> +<listitem><para>Melchior Franz <email>melchior@kde.org</email></para></listitem> +<listitem><para>Michael Koch <email>koch@kde.org</email></para></listitem> +<listitem><para>Michael Thaler +<email>michael.thaler@ph.tum.de</email></para></listitem> +<listitem><para>Patrick Julien +<email>freak@codepimps.org</email></para></listitem> +<listitem><para>Roger Larsson +<email>roger.larsson@norran.net</email></para></listitem> +<listitem><para>Sven Langkamp +<email>longamp@reallygood.de</email></para></listitem> +</itemizedlist> +</para> + +<para> +Documentation copyright © 2005-2006 Boudewijn Rempt +<email>boud@valdyas.org</email>, Sander Koning +<email>sanderkoning@kde.nl</email> +with contributions from Casper Boemann, Bart Coppens, Cyrille Berger, Burkhard +Lueck, and Anne-Marie Mahfouf. +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + + diff --git a/doc/chalk/crocusses-autocontrast.png b/doc/chalk/crocusses-autocontrast.png Binary files differnew file mode 100644 index 00000000..3e73db57 --- /dev/null +++ b/doc/chalk/crocusses-autocontrast.png diff --git a/doc/chalk/crocusses-blur.png b/doc/chalk/crocusses-blur.png Binary files differnew file mode 100644 index 00000000..3b31dbe1 --- /dev/null +++ b/doc/chalk/crocusses-blur.png diff --git a/doc/chalk/crocusses-brightnesscontrast.png b/doc/chalk/crocusses-brightnesscontrast.png Binary files differnew file mode 100644 index 00000000..b60ad77d --- /dev/null +++ b/doc/chalk/crocusses-brightnesscontrast.png diff --git a/doc/chalk/crocusses-bumpmap.png b/doc/chalk/crocusses-bumpmap.png Binary files differnew file mode 100644 index 00000000..cd1037c1 --- /dev/null +++ b/doc/chalk/crocusses-bumpmap.png diff --git a/doc/chalk/crocusses-coloradjustment.png b/doc/chalk/crocusses-coloradjustment.png Binary files differnew file mode 100644 index 00000000..8efbc9db --- /dev/null +++ b/doc/chalk/crocusses-coloradjustment.png diff --git a/doc/chalk/crocusses-colortoalpha.png b/doc/chalk/crocusses-colortoalpha.png Binary files differnew file mode 100644 index 00000000..232aab29 --- /dev/null +++ b/doc/chalk/crocusses-colortoalpha.png diff --git a/doc/chalk/crocusses-colortransfer.png b/doc/chalk/crocusses-colortransfer.png Binary files differnew file mode 100644 index 00000000..a6abfb6a --- /dev/null +++ b/doc/chalk/crocusses-colortransfer.png diff --git a/doc/chalk/crocusses-customconvolution.png b/doc/chalk/crocusses-customconvolution.png Binary files differnew file mode 100644 index 00000000..6a1da4fc --- /dev/null +++ b/doc/chalk/crocusses-customconvolution.png diff --git a/doc/chalk/crocusses-desaturate.png b/doc/chalk/crocusses-desaturate.png Binary files differnew file mode 100644 index 00000000..e2add125 --- /dev/null +++ b/doc/chalk/crocusses-desaturate.png diff --git a/doc/chalk/crocusses-edgebottom.png b/doc/chalk/crocusses-edgebottom.png Binary files differnew file mode 100644 index 00000000..4c42077f --- /dev/null +++ b/doc/chalk/crocusses-edgebottom.png diff --git a/doc/chalk/crocusses-edgeleft.png b/doc/chalk/crocusses-edgeleft.png Binary files differnew file mode 100644 index 00000000..4b384320 --- /dev/null +++ b/doc/chalk/crocusses-edgeleft.png diff --git a/doc/chalk/crocusses-edgeright.png b/doc/chalk/crocusses-edgeright.png Binary files differnew file mode 100644 index 00000000..e2071f65 --- /dev/null +++ b/doc/chalk/crocusses-edgeright.png diff --git a/doc/chalk/crocusses-embossall.png b/doc/chalk/crocusses-embossall.png Binary files differnew file mode 100644 index 00000000..eb937422 --- /dev/null +++ b/doc/chalk/crocusses-embossall.png diff --git a/doc/chalk/crocusses-embosshorvert.png b/doc/chalk/crocusses-embosshorvert.png Binary files differnew file mode 100644 index 00000000..685e34b1 --- /dev/null +++ b/doc/chalk/crocusses-embosshorvert.png diff --git a/doc/chalk/crocusses-embossvariable.png b/doc/chalk/crocusses-embossvariable.png Binary files differnew file mode 100644 index 00000000..cfeabd1a --- /dev/null +++ b/doc/chalk/crocusses-embossvariable.png diff --git a/doc/chalk/crocusses-gaussianblur.png b/doc/chalk/crocusses-gaussianblur.png Binary files differnew file mode 100644 index 00000000..bf1633eb --- /dev/null +++ b/doc/chalk/crocusses-gaussianblur.png diff --git a/doc/chalk/crocusses-gaussiannoise.png b/doc/chalk/crocusses-gaussiannoise.png Binary files differnew file mode 100644 index 00000000..cc0605c5 --- /dev/null +++ b/doc/chalk/crocusses-gaussiannoise.png diff --git a/doc/chalk/crocusses-invert.png b/doc/chalk/crocusses-invert.png Binary files differnew file mode 100644 index 00000000..9f1d9eb5 --- /dev/null +++ b/doc/chalk/crocusses-invert.png diff --git a/doc/chalk/crocusses-lenscorrection.png b/doc/chalk/crocusses-lenscorrection.png Binary files differnew file mode 100644 index 00000000..7bc8087f --- /dev/null +++ b/doc/chalk/crocusses-lenscorrection.png diff --git a/doc/chalk/crocusses-maximizechannel.png b/doc/chalk/crocusses-maximizechannel.png Binary files differnew file mode 100644 index 00000000..9e6dc3f9 --- /dev/null +++ b/doc/chalk/crocusses-maximizechannel.png diff --git a/doc/chalk/crocusses-meanremoval.png b/doc/chalk/crocusses-meanremoval.png Binary files differnew file mode 100644 index 00000000..a1df0ac0 --- /dev/null +++ b/doc/chalk/crocusses-meanremoval.png diff --git a/doc/chalk/crocusses-minimizechannel.png b/doc/chalk/crocusses-minimizechannel.png Binary files differnew file mode 100644 index 00000000..14e9fe07 --- /dev/null +++ b/doc/chalk/crocusses-minimizechannel.png diff --git a/doc/chalk/crocusses-oilpaint.png b/doc/chalk/crocusses-oilpaint.png Binary files differnew file mode 100644 index 00000000..d005ef3e --- /dev/null +++ b/doc/chalk/crocusses-oilpaint.png diff --git a/doc/chalk/crocusses-pixelize.png b/doc/chalk/crocusses-pixelize.png Binary files differnew file mode 100644 index 00000000..3fb5ba60 --- /dev/null +++ b/doc/chalk/crocusses-pixelize.png diff --git a/doc/chalk/crocusses-raindrops.png b/doc/chalk/crocusses-raindrops.png Binary files differnew file mode 100644 index 00000000..bdee271c --- /dev/null +++ b/doc/chalk/crocusses-raindrops.png diff --git a/doc/chalk/crocusses-randomnoise.png b/doc/chalk/crocusses-randomnoise.png Binary files differnew file mode 100644 index 00000000..d7525a3f --- /dev/null +++ b/doc/chalk/crocusses-randomnoise.png diff --git a/doc/chalk/crocusses-randompick.png b/doc/chalk/crocusses-randompick.png Binary files differnew file mode 100644 index 00000000..d3fb496d --- /dev/null +++ b/doc/chalk/crocusses-randompick.png diff --git a/doc/chalk/crocusses-roundcorners.png b/doc/chalk/crocusses-roundcorners.png Binary files differnew file mode 100644 index 00000000..d997aca7 --- /dev/null +++ b/doc/chalk/crocusses-roundcorners.png diff --git a/doc/chalk/crocusses-sharpen.png b/doc/chalk/crocusses-sharpen.png Binary files differnew file mode 100644 index 00000000..18998da9 --- /dev/null +++ b/doc/chalk/crocusses-sharpen.png diff --git a/doc/chalk/crocusses-smalltiles.png b/doc/chalk/crocusses-smalltiles.png Binary files differnew file mode 100644 index 00000000..0dcd880d --- /dev/null +++ b/doc/chalk/crocusses-smalltiles.png diff --git a/doc/chalk/crocusses-sobel.png b/doc/chalk/crocusses-sobel.png Binary files differnew file mode 100644 index 00000000..90506e6a --- /dev/null +++ b/doc/chalk/crocusses-sobel.png diff --git a/doc/chalk/crocusses-topedge.png b/doc/chalk/crocusses-topedge.png Binary files differnew file mode 100644 index 00000000..e52c0878 --- /dev/null +++ b/doc/chalk/crocusses-topedge.png diff --git a/doc/chalk/crocusses-unsharpmask.png b/doc/chalk/crocusses-unsharpmask.png Binary files differnew file mode 100644 index 00000000..7760cb74 --- /dev/null +++ b/doc/chalk/crocusses-unsharpmask.png diff --git a/doc/chalk/crocusses-wave.png b/doc/chalk/crocusses-wave.png Binary files differnew file mode 100644 index 00000000..053cd4e6 --- /dev/null +++ b/doc/chalk/crocusses-wave.png diff --git a/doc/chalk/crocusses-waveletnoise.png b/doc/chalk/crocusses-waveletnoise.png Binary files differnew file mode 100644 index 00000000..4088373d --- /dev/null +++ b/doc/chalk/crocusses-waveletnoise.png diff --git a/doc/chalk/crocusses.png b/doc/chalk/crocusses.png Binary files differnew file mode 100644 index 00000000..9b8913c3 --- /dev/null +++ b/doc/chalk/crocusses.png diff --git a/doc/chalk/developers-plugins.docbook b/doc/chalk/developers-plugins.docbook new file mode 100644 index 00000000..81a4ef49 --- /dev/null +++ b/doc/chalk/developers-plugins.docbook @@ -0,0 +1,1553 @@ +<sect1 id="developers-plugins"> +<title>Developing &chalk; Plugins</title> + +<sect2 id="developers-plugins-introduction"> +<title>Introduction</title> + +<para> +&chalk; is infinitely extensible with plugins. Tools, filters, large +chunks of the user interface and even colorspaces are plugins. In fact, +&chalk; recognizes these six types of plugins: +</para> + +<itemizedlist> +<listitem><para>colorspaces — these define the channels that constitute +a single pixel</para></listitem> +<listitem><para>tools — anything that is done with a mouse or tablet +input device</para></listitem> +<listitem><para>paint operations — pluggable painting effects for +tools</para></listitem> +<listitem><para>image filters — change all pixels, or just the selected +pixels in a layer</para></listitem> +<listitem><para>viewplugins — extend Chalk’s user interface with new +dialog boxes, palettes and operations</para></listitem> +<listitem><para>import/export filters — read and write all kinds of +image formats</para></listitem> +</itemizedlist> + +<para> +&chalk; itself consists of three layered libraries and a directory with some +common support classes: chalkcolor, chalkimage and chalkui. Within +&chalk;, objects can by identified by a <classname>KisID</classname>, that is +the combination of a unique untranslated string (used when saving, for +instance) and a translated string for GUI purposes. +</para><para> +A word on compatibility: &chalk; is still in development. From &chalk; 1.5 to +1.6 not many API changes are expected, but there may be some. From &chalk; 1.6 +to 2.0 we will move from &Qt;3 to &Qt;4, from &kde;3 to &kde;4, from +<command>automake</command> to <command>cmake</command>: many changes are to +be expected. If you develop a plugin for &chalk; and choose to do so in +&chalk;’s subversion repository, chances are excellent that we’ll help you +porting. These changes may also render parts of this document out of date. +Always check with the latest API documentation or the header files installed +on your system. +</para> + +<sect3 id="developers-plugins-introduction-chalkcolor"> +<title>ChalkColor</title> + +<para> +The first library is chalkcolor. This library loads the colorspace plugins. +</para><para> +A colorspace plugin should implement the <classname>KisColorSpace</classname> +abstract class or, if the basic capabilities of the new colorspace will be +implemented by <command>lcms</command> (<ulink url="http://www.littlecms.com/" +/>), extend <classname>KisAbstractColorSpace</classname>. The chalkcolor +library could be used from other applications and does not depend on +&koffice;. +</para> +</sect3> + +<sect3 id="developers-plugins-introduction-chalkimage"> +<title>ChalkImage</title> + +<para> +The libchalkimage library loads the filter and paintop plugins and is +responsible for working with image data: changing pixels, compositing and +painting. Brushes, palettes, gradients and patterns are also loaded by +libchalkimage. It is our stated goal to make libchalkimage independent of +&koffice;, but we currently share the gradient loading code with &koffice;. +</para><para> +It is not easy at the moment to add new types of resources such as brushes, +palettes, gradients or patterns to &chalk;. (Adding new brushes, palettes, +gradients and patterns is easy, of course.) &chalk; follows the guidelines of +the Create project (<ulink url="http://create.freedesktop.org/" />) for these. +Adding support for Photoshop's brush file format needs libchalkimage hacking; +adding more gimp brush data files not. +</para><para> +<classname>ChalkImage</classname> loads the following types of plugins: +</para> + +<itemizedlist> +<listitem><para>&chalk; filters must extend and implement the abstract class +<classname>KisFilter</classname>, +<classname>KisFilterConfiguration</classname> and possibly +<classname>KisFilterConfigurationWidget</classname>. +An example of a filter is Unsharp Mask.</para></listitem> +<listitem><para>Paint operations or paintops are the set of operations +painting tools suchs as freehand or circle have access to. Examples of +paintops are pen, airbrush or eraser. Paintops should extend the +<classname>KisPaintop</classname> base class. Examples of new paintops could +be a chalk brush, an oilpaint brush or a complex programmable +brush.</para></listitem> +</itemizedlist> + +</sect3> + +<sect3 id="developers-plugins-introduction-chalkui"> +<title>ChalkUI</title> + +<para> +The libchalkui library loads the tool and viewplugins. This library is a +&koffice; Part, but also contains a number of widgets that are useful for +graphics applications. Maybe we will have to split this library in chalkpart +and chalkui in the 2.0 release. For now, script writers are not given access +to this library and plugin writers are only allowed to use this library when +writing tools or viewplugins. <classname>ChalkUI</classname> loads the +following types of plugins: +</para> + +<itemizedlist> +<listitem><para>Tools are derived from <classname>KisTool</classname> or one +of the specialized tool base classes such as +<classname>KisToolPaint</classname>, <classname>KisToolNonPaint</classname> or +<classname>KisToolFreehand</classname>. A new tool could be a foreground +object selection tool. Painting tools (and that includes tools that paint on +the selection) can use any paintop to determine the way pixels are +changed.</para></listitem> +<listitem><para>Viewplugins are ordinary KParts that use +<command>kxmlgui</command> to insinuate themselves into &chalk;'s user +interface. Menu options, dialogs, toolbars — any kind of user interface +extension can be a viewplugin. In fact, important functionality like &chalk;'s +scripting support is written as a viewplugin.</para></listitem> +</itemizedlist> + +</sect3> + +<sect3 id="developers-plugins-introduction-importexport"> +<title>Import/Export filters</title> + +<para> +Import/Export filters are &koffice; filters, subclasses of +<classname>KoFilter</classname>. Filters read and write image data in any of +the myriad image formats in existence. And example of a new &chalk; +import/export filter could be a PDF filter. Filters are loaded by the +&koffice; libraries. +</para> + +</sect3> + +</sect2> + +<sect2 id="developers-plugins-creating"> +<title>Creating plugins</title> + +<para> +Plugins are written in C++ and can use all of &kde; and &Qt; and the &chalk; +developer API. Only viewplugins should use the &koffice; API. Don’t worry: +&chalk;’s API’s are quite clear and rather extensively documented (for free +software) and coding your first filter is really easy. +</para><para> +If you do not want to use C++, you can write scripts in Python or Ruby; that +is a different thing altogether, though, and you cannot currently write tools, +colorspaces, paintops or import/export filters as scripts. +</para><para> +&chalk; plugins use &kde;'s parts mechanism for loading, so the parts +documentation at <ulink url="http://developer.kde.org" /> is relevant here, too. +</para><para> +Your distribution should have either installed the relevant header files with +&chalk; itself, or might have split the header files into either a &koffice; +dev or a &chalk; dev package. You can find the API documentation for &chalk;'s +public API at <ulink url="http://koffice.org/developer/apidocs/chalk/html/" />. +</para> + +<sect3 id="developers-plugins-creating-automake"> +<title>Automake (and CMake)</title> + +<para> +&kde; 3.x and thus &koffice; 1.5 and 1.6 use <command>automake</command>; +&kde; 4.0 and &koffice; 2.0 use <command>cmake</command>. This tutorial +describes the <command>automake</command> way of creating plugins. +<!-- If I have not updated this manual when we release KOffice 2.0, please +remind me to do so. --> +</para><para> +Plugins are &kde; modules and should be tagged as such in their +<filename>Makefile.am</filename>. Filters, tools, paintops, colorspaces and +import/export filters need <literal role="extension">.desktop</literal> files; +viewplugins need a <application>KXMLGui</application> +<filename>pluginname.rc</filename> file in addition. The easiest way to get +started is to checkout the chalk-plugins project from the &koffice; Subversion +repository and use it as the basis for your own project. We intend to prepare +a skeleton &chalk; plugin pack for KDevelop, but haven’t had the time to do +so yet. +</para> + +<sect4 id="d-p-c-a-makefile"> +<title><filename>Makefile.am</filename></title> + +<para> +Let's look at the skeleton for a plugin module. First, the +<filename>Makefile.am</filename>. This is what &kde; uses to generate the +makefile that builds your plugin: + +<programlisting> +kde_services_DATA = chalkLIBRARYNAME.desktop + +INCLUDES = $(all_includes) + +chalkLIBRARYNAME_la_SOURCES = sourcefile1.cc sourcefile2.cc + +kde_module_LTLIBRARIES = chalkLIBRARYNAME.la +noinst_HEADERS = header1.h header2.h + +chalkLIBRARYNAME_la_LDFLAGS = $(all_libraries) -module $(KDE_PLUGIN) +chalkLIBRARY_la_LIBADD = -lchalkcommon + +chalkextensioncolorsfilters_la_METASOURCES = AUTO +</programlisting> + +This is the makefile for a filter plugin. Replace +<replaceable>LIBRARYNAME</replaceable> with the name of your work, and you are +set. +</para><para> +If your plugin is a viewplugin, you will likely also install a <literal +role="extension">.rc</literal> file with entries for menubars and toolbars. +Likewise, you may need to install cursors and icons. That is all done through +the ordinary &kde; <filename>Makefile.am</filename> magic incantantions: + +<programlisting> +chalkrcdir = $(kde_datadir)/chalk/chalkplugins +chalkrc_DATA = LIBRARYNAME.rc +EXTRA_DIST = $(chalkrc_DATA) + +chalkpics_DATA = \ + bla.png \ + bla_cursor.png +chalkpicsdir = $(kde_datadir)/chalk/pics +</programlisting> + +</para> +</sect4> + +<sect4 id="d-p-c-a-desktop"> +<title>Desktop files</title> + +<para> +The <literal role="extension">.desktop</literal> file announces the type of plugin: + +<programlisting> +[Desktop Entry] +Encoding=UTF-8 +Icon= +Name=User-visible Name +ServiceTypes=Chalk/Filter +Type=Service +X-KDE-Library=chalkLIBRARYNAME +X-KDE-Version=2 +</programlisting> +</para><para> +Possible ServiceTypes are: +</para> + +<itemizedlist> +<listitem><para>Chalk/Filter</para></listitem> +<listitem><para>Chalk/Paintop</para></listitem> +<listitem><para>Chalk/ViewPlugin</para></listitem> +<listitem><para>Chalk/Tool</para></listitem> +<listitem><para>Chalk/ColorSpace</para></listitem> +</itemizedlist> + +<para> +File import and export filters use the generic &koffice; filter framework and +need to be discussed separately. +</para> +</sect4> + +<sect4 id="d-p-c-a-boilerplate"> +<title>Boilerplate</title> + +<para> +You also need a bit of boilerplate code that is called by the &kde; part +framework to instantiate the plugin — a header file and an implementation file. +</para><para> +A header file: +<programlisting> +#ifndef TOOL_STAR_H_ +#define TOOL_STAR_H_ + +#include <kparts/plugin.h> + +/** +* A module that provides a star tool. +*/ +class ToolStar : public KParts::Plugin +{ + Q_OBJECT +public: + ToolStar(QObject *parent, const char *name, const QStringList &); + virtual ~ToolStar(); + +}; + +#endif // TOOL_STAR_H_ +</programlisting> +</para> + +<para> +And an implementation file: +<programlisting> +#include <kinstance.h> +#include <kgenericfactory.h> + +#include <kis_tool_registry.h> + +#include "tool_star.h" +#include "kis_tool_star.h" + + +typedef KGenericFactory<ToolStar> ToolStarFactory; +K_EXPORT_COMPONENT_FACTORY( chalktoolstar, ToolStarFactory( "chalk" ) ) + + +ToolStar::ToolStar(QObject *parent, const char *name, const QStringList &) + : KParts::Plugin(parent, name) +{ + setInstance(ToolStarFactory::instance()); + if ( parent->inherits("KisToolRegistry") ) + { + KisToolRegistry * r = dynamic_cast<KisToolRegistry*>( parent ); + r -> add(new KisToolStarFactory()); + } + +} + +ToolStar::~ToolStar() +{ +} + +#include "tool_star.moc" +</programlisting> +</para> +</sect4> + +<sect4 id="d-p-c-a-registries"> +<title>Registries</title> + +<para> +Tools are loaded by the tool registry and register themselves with the tool +registry. Plugins like tools, filters and paintops are loaded only once: view +plugins are loaded for every view that is created. Note that we register +factories, generally speaking. For instance, with tools a new instance of a +tool is created for every pointer (mouse, stylus, eraser) for every few. And a +new paintop is created whenever a tool gets a mouse-down event. +</para> + +<para> +Filters call the filter registry: +<programlisting> + if (parent->inherits("KisFilterRegistry")) { + KisFilterRegistry * manager = dynamic_cast<KisFilterRegistry *>(parent); + manager->add(new KisFilterInvert()); + } +</programlisting> +</para><para> +Paintops the paintop registry: +<programlisting> + if ( parent->inherits("KisPaintOpRegistry") ) { + KisPaintOpRegistry * r = dynamic_cast<KisPaintOpRegistry*>(parent); + r -> add ( new KisSmearyOpFactory ); + } +</programlisting> +</para><para> +Colorspaces the colorspace registry (with some complications): +<programlisting> + if ( parent->inherits("KisColorSpaceFactoryRegistry") ) { + KisColorSpaceFactoryRegistry * f = dynamic_cast<isColorSpaceFactoryRegistry*>(parent); + + KisProfile *defProfile = new KisProfile(cmsCreate_sRGBProfile()); + f->addProfile(defProfile); + + KisColorSpaceFactory * csFactory = new KisRgbColorSpaceFactory(); + f->add(csFactory); + + KisColorSpace * colorSpaceRGBA = new KisRgbColorSpace(f, 0); + KisHistogramProducerFactoryRegistry::instance() -> add( + new KisBasicHistogramProducerFactory<KisBasicU8HistogramProducer> + (KisID("RGB8HISTO", i18n("RGB8 Histogram")), colorSpaceRGBA) ); + } +</programlisting> +</para><para> +View plugins do not have to register themselves, and they get access to a +<classname>KisView</classname> object: +<programlisting> + if ( parent->inherits("KisView") ) + { + setInstance(ShearImageFactory::instance()); + setXMLFile(locate("data","chalkplugins/shearimage.rc"), true); + + (void) new KAction(i18n("&Shear Image..."), 0, 0, this, SLOT(slotShearImage()), actionCollection(), "shearimage"); + (void) new KAction(i18n("&Shear Layer..."), 0, 0, this, SLOT(slotShearLayer()), actionCollection(), "shearlayer"); + + m_view = (KisView*) parent; + } +</programlisting> +</para><para> +Remember that this means that a view plugin will be created for every view the +user creates: splitting a view means loading all view plugins again. +</para> +</sect4> + +<sect4 id="d-p-c-a-versioning"> +<title>Plugin versioning</title> + +<para> +&chalk; 1.5 loads plugins with <literal>X-KDE-Version=2</literal> set in the +<literal role="extension">.desktop</literal> file. &chalk; 1.6 plugins will +probably be binary incompatible with 1.5 plugins and will need the version +number 3. &chalk; 2.0 plugins will need the version number 3. Yes, this is not +entirely logical. +</para> + +</sect4> +</sect3> +</sect2> + +<sect2 id="developers-plugins-colorspaces"> +<title>Colorspaces</title> + +<para> +Colorspaces implement the <classname>KisColorSpace</classname> pure virtual +class. There are two types of colorspaces: those that can use +<command>lcms</command> for transformations between colorspaces, and those +that are too weird for <command>lcms</command> to handle. Examples of the +first are cmyk, rgb, yuv. An example of the latter is watercolor or wet & +sticky. Colorspaces that use <command>lcms</command> can be derived from +<classname>KisAbstractColorSpace</classname>, or of one of the base classes +that are specialized for a certain number of bits per channel. +</para><para> +Implementing a colorspace is pretty easy. The general principle is that +colorspaces work on a simple array of bytes. The interpretation of these bytes +is up to the colorspace. For instance, a pixel in 16-bit GrayA consists of +four bytes: two bytes for the gray value and two bytes for the alpha value. +You are free to use a struct to work with the memory layout of a pixel in your +colorspace implementation, but that representation is not exported. The only +way the rest of &chalk; can know what channels and types of channels your +colorspace pixels consist of is through the +<classname>KisChannelInfo</classname> class. +</para><para> +Filters and paintops make use of the rich set of methods offered by +<classname>KisColorSpace</classname> to do their work. In many cases, the +default implementation in <classname>KisAbstractColorSpace</classname> will +work, but more slowly than a custom implementation in your own colorspace +because <classname>KisAbstractColorSpace</classname> will convert all pixels +to 16-bit L*a*b and back. +</para> + +<sect3 id="developers-plugins-colorspaces-kischannelinfo"> +<title><classname>KisChannelInfo</classname></title> + +<programlisting> +(http://websvn.kde.org/trunk/koffice/chalk/chalkcolor/kis_channelinfo.h) +</programlisting> +<para> +This class defines the channels that make up a single pixel in a particular +colorspace. A channel has the following important characteristics: +</para> +<itemizedlist> +<listitem><para>a name for display in the user interface</para></listitem> +<listitem><para>a position: the byte where the bytes representing this channel +start in the pixel.</para></listitem> +<listitem><para>a type: color, alpha, substance or substrate. Color is plain +color, alpha is see-throughishness, substance is a representation of amount of +pigment or things like that, substrate is the representation of the canvas. +(Note that this may be refactored at the drop of a hat.)</para></listitem> +<listitem><para>a valuetype: byte, short, integer, float — or +other.</para></listitem> +<listitem><para>size: the number of bytes this channel takes</para></listitem> +<listitem><para>color: a <classname>QColor</classname> representation of this +channel for user interface visualization, for instance in +histograms.</para></listitem> +<listitem><para>an abbreviaton for use in the GUI when there’s not much +space</para></listitem> +</itemizedlist> +</sect3> + +<sect3 id="developers-plugins-colorspaces-kiscompositeop"> +<title><classname>KisCompositeOp</classname></title> + +<para> +As per original Porter-Duff, there are many ways of combining pixels to get a +new color. The <classname>KisCompositeOp</classname> class defines most of +them: this set is not easily extensible except by hacking the chalkcolor +library. +</para><para> +A colorspace plugin can support any subset of these possible composition +operations, but the set must always include "OVER" (same as "NORMAL") and +"COPY". The rest are more or less optional, although more is better, of +course. +</para> +</sect3> + +<sect3 id="developers-plugins-colorspaces-kiscolorspace"> +<title><classname>KisColorSpace</classname></title> + +<para> +The methods in the <classname>KisColorSpace</classname> pure virtual classs +can be divided into a number of groups: conversion, identification and +manipulation. +</para><para> +All classes must be able to convert a pixel from and to 8 bit RGB (i.e., a +<classname>QColor</classname>), and preferably also to and from 16 bit L*a*b. +Additionally, there is a method to convert to any colorspace from the current +colorspace. +</para><para> +Colorspaces are described by the <classname>KisChannelInfo</classname> vector, +number of channels, number of bytes in a single pixel, whether it supports +High Dynamic Range images and more. +</para><para> +Manipulation is for instance the combining of two pixels in a new +pixel: bitBlt, darkening or convolving of pixels. +</para><para> +Please consult the API documentation for a full description of all methods you +need to implement in a colorspace. +</para><para> +<classname>KisAbstractColorSpace</classname> implements many of the virtual +methods of <classname>KisColorSpace</classname> using functions from the +<command>lcms</command> library. On top of +<classname>KisAbstractColorSpace</classname> there are base colorspace classes +for 8 and 16 bit integer and 16 and 32 bit float colorspaces that define +common operations to move between bit depths. +</para> + +</sect3> +</sect2> + +<sect2 id="developers-plugins-filters"> +<title>Filters</title> + +<para> +Filters are plugins that examine the pixels in a layer and them make changes +to them. Although &chalk; uses an efficient tiled memory backend to store +pixels, filter writers do not have to bother with that. When writing a filter +plugin for the &Java; imaging API, Photoshop or The Gimp, you need to take care +of tile edges and <quote>cobble</quote> tiles together: &chalk; hides that +implementation detail. +</para> +<note><para>Note that it is theoretically easy to replace the current tile +image data storage backend with another backend, but that backens are not true +plugins at the moment, for performance reasons.</para></note> +<para> +&chalk; uses iterators to read and write pixel values. Alternatively, you can +read a block of pixels into a memory buffer, mess with it and then write it +back as a block. But that is not necessarily more efficient, it may even be +slower than using the iterators; it may just be more convenient. See the API +documentation. +</para><para> +&chalk; images are composed of layers, of which there are currently four +kinds: paint layers, group layers, adjustment layers (that contain a filter +that is applied dynamically to layers below the adjustment layer) and part +layers. Filters always operate on paint layers. Paint layers contain paint +devices, of the class <classname>KisPaintDevice</classname>. A paint device in +its turn gives access to the actual pixels. +</para><para> +<classname>PaintDevice</classname>s are generally passed around wrapped in +shared pointers. A shared pointer keeps track of in how many places the paint +device is currently used and deletes the paint device when it is no longer +used anywhere. You recognize the shared pointer version of a paint device +through its <literal>SP</literal> suffix. Just remember that you never have to +explicitly delete a <classname>KisPaintDeviceSP</classname>. +</para><para> +Let's examine a very simple filter, one that inverts every pixel. The code for +this filter is in the <filename +class="directory">koffice/chalk/plugins/filters/example</filename> directory. +The main method is +<programlisting> +KisFilterInvert::process(KisPaintDeviceSP src, KisPaintDeviceSP dst, + KisFilterConfiguration* /*config*/, const QRect& rect). +</programlisting> +The function gets passed two paint devices, a configuration object (which is +not used in this simple filter) and a <varname>rect</varname>. The +<varname>rect</varname> describes the area of the +paint device which the filter should act on. This area is described by +integers, which means no sub-pixel accuracy. +</para><para> +The <varname>src</varname> paint device is for reading from, the +<varname>dst</varname> paint device for writing to. These parameters may point +to the same actual paint device, or be two different paint devices. (Note: +this may change to only one paint device in the future.) +</para><para> +Now, let's look at the code line by line: +</para> +<programlisting> +void KisFilterInvert::process(KisPaintDeviceSP src, KisPaintDeviceSP dst, + KisFilterConfiguration* /*config*/, const QRect& rect) +{ + Q_ASSERT(src != 0); + Q_ASSERT(dst != 0); + + KisRectIteratorPixel srcIt = src->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), false); <co id="invert1" /> + KisRectIteratorPixel dstIt = dst->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), true ); <co id="invert2" /> + + int pixelsProcessed = 0; + setProgressTotalSteps(rect.width() * rect.height()); + + KisColorSpace * cs = src->colorSpace(); + Q_INT32 psize = cs->pixelSize(); + + while( ! srcIt.isDone() ) + { + if(srcIt.isSelected()) <co id="invert3" /> + { + memcpy(dstIt.rawData(), srcIt.oldRawData(), psize); <co id="invert4" /> + + cs->invertColor( dstIt.rawData(), 1); <co id="invert5" /> + } + setProgress(++pixelsProcessed); + ++srcIt; + ++dstIt; + } + setProgressDone(); // Must be called even if you don't really support progression +} +</programlisting> + +<calloutlist> +<callout arearefs="invert1"> +<para>This creates an iterator to read the existing pixels. Chalk has three +types of iterators: horizontal, vertical and rectangular. The rect iterator +takes the most efficient path through the image data, but does not guarantee +anything about the location of the next pixel it returns. That means that you +cannot be sure that the pixel you will retrieve next will be adjacent to the +pixel you just got. The horizontal and vertical line iterators do guarantee +the location of the pixels they return. +</para></callout> +<callout arearefs="invert2"><para> +(2) We create the destination iterator with the <literal>write</literal> +setting to <literal>true</literal>. This means that if the destination paint +device is smaller than the rect we write, it will automatically be enlarged to +fit every pixel we iterate over. Note that we have got a potential bug here: +if <varname>dst</varname> and <varname>src</varname> are not the same device, +then it is quite possible that the pixels returned by the iterators do not +correspond. For every position in the iterator, <varname>src</varname> may be, +for example, at 165,200, while <varname>dst</varname> could be at 20,8 — +and therefore the copy we perform below may distort the image... +</para></callout> +<callout arearefs="invert3"><para> +Want to know if a pixel is selected? That is easy — use the +<methodname>isSelected</methodname> method. But selectedness is not a binary +property of a pixel, a pixel can be half selected, barely selected or almost +completely selected. That value you can also got from the iterator. Selections +are actually a mask paint device with a range between 0 and 255, where 0 is +completely unselected and 255 completely selected. The iterator has two +methods: <methodname>isSelected()</methodname> and +<methodname>selectedNess()</methodname>. The first returns true if a pixel is +selected to any extent (i.e., the mask value is greater than 1), the other +returns the maskvalue. +</para></callout> +<callout arearefs="invert4"><para> +As noted above, this <literal>memcpy</literal> is a big bad bug... +<methodname>rawData()</methodname> returns the array of bytes which is the +current state of the pixel; <methodname>oldRawData()</methodname> returns the +array of bytes as it was before we created the iterator. However, we may be +copying the wrong pixel here. In actual practice, that will not happen too +often, unless <varname>dst</varname> already exists and is not aligned with +<varname>src</varname>. +</para></callout> +<callout arearefs="invert5"><para> +But this is correct: instead of figuring out which byte represents which +channel, we use a function supplied by all colorspaces to invert the current +pixel. The colorspaces have a lot of pixel operations you can make use of. +</para></callout> +</calloutlist> + +<para> +This is not all there is to creating a filter. Filters have two other +important components: a configuration object and a configuration widget. The +two interact closely. The configuration widget creates a configuration object, +but can also be filled from a pre-existing configuration object. Configuration +objects can represtent themselves as XML and can be created from XML. That is +what makes adjustment layers possible. +</para> + +<sect3 id="developers-plugins-filters-iterators"> +<title>Iterators</title> + +<para> +There are three types of iterators: +</para> + +<itemizedlist> +<listitem><para>Horizontal lines</para></listitem> +<listitem><para>Vertical lines</para></listitem> +<listitem><para>Rectangular iterors</para></listitem> +</itemizedlist> + +<para> +The horizontal and vertical line iterators have a method to move the iterator +to the next row or column: <methodname>nextRow()</methodname> and +<methodname>nextCol()</methodname>. Using these is much faster than creating a +new iterator for every line or column. +</para><para> +Iterators are thread-safe in &chalk;, so it is possible to divide the work +over multiple threads. However, future versions of &chalk; will use the +<methodname>supportsThreading()</methodname> method to determine whether your +filter can be applied to chunks of the image (&ie;, all pixels modified +independently, instead of changed by some value determined from an examination +of all pixels in the image) and automatically thread the execution your +filter. +</para> +</sect3> + +<sect3 id="developers-plugins-filters-kisfilterconfiguration"> +<title><classname>KisFilterConfiguration</classname></title> + +<para> +<classname>KisFilterConfiguration</classname> is a structure that is used to +save filter settings to disk, for instance for adjustment layers. The +scripting plugin uses the property map that’s at the back of +<classname>KisFilterConfigaration</classname> to make it possible to script +filters. Filters can provide a custom widget that &chalk; will show in the +filters gallery, the filter preview dialog or the tool option tab of the +paint-with-filters tool. +</para> +<para> +An example, taken from the oilpaint effect filter: +</para> +<programlisting> +class KisOilPaintFilterConfiguration : public KisFilterConfiguration +{ + +public: + + KisOilPaintFilterConfiguration(Q_UINT32 brushSize, Q_UINT32 smooth) + : KisFilterConfiguration( "oilpaint", 1 ) + { + setProperty("brushSize", brushSize); + setProperty("smooth", smooth); + }; +public: + + inline Q_UINT32 brushSize() { return getInt("brushSize"); }; + inline Q_UINT32 smooth() {return getInt("smooth"); }; + +}; +</programlisting> +</sect3> + +<sect3 id="developers-plugins-filters-kisfilterconfigurationwidget"> +<title><classname>KisFilterConfigurationWidget</classname></title> + +<para> +Most filters can be tweaked by the user. You can create a configuration widget +that Chalk will use where-ever your filter is used. An example: +</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>Oilpaint</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dialogs-oilpaint.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Oilpaint</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Oilpaint</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Note that only the left-hand side of this dialog is your responsibility: +&chalk; takes care of the rest. There are three ways of going about creating +an option widget: +</para> + +<itemizedlist> +<listitem><para>Use &Qt; Designer to create a widget base, and subclass it for +your filter</para></listitem> +<listitem><para>Use one of the simple widgets that show a number of sliders +for lists of integers, doubles or bools. These are useful if, like the above +screenshot, your filter can be configured by a number of integers, doubles or +bools. See the API dox for <classname>KisMultiIntegerFilterWidget</classname>, +<classname>KisMultiDoubleFilterWidget</classname> and +<classname>KisMultiBoolFilterWidget</classname>.</para></listitem> +<listitem><para>Hand-code a widget. This is not recommended, and if you do so +and want your filter to become part of &chalk;’s official release, then I’ll ask +you to replate your hand-coded widget with a &Qt; Designer +widget.</para></listitem> +</itemizedlist> + +<para> +The oilpaint filter uses the multi integer widget: +</para> + +<programlisting> +KisFilterConfigWidget * KisOilPaintFilter::createConfigurationWidget(QWidget* parent, KisPaintDeviceSP /*dev*/) +{ + vKisIntegerWidgetParam param; + param.push_back( KisIntegerWidgetParam( 1, 5, 1, i18n("Brush size"), "brushSize" ) ); + param.push_back( KisIntegerWidgetParam( 10, 255, 30, i18n("Smooth"), "smooth" ) ); + return new KisMultiIntegerFilterWidget(parent, id().id().ascii(), id().id().ascii(), param ); +} + +KisFilterConfiguration* KisOilPaintFilter::configuration(QWidget* nwidget) +{ + KisMultiIntegerFilterWidget* widget = (KisMultiIntegerFilterWidget*) nwidget; + if( widget == 0 ) + { + return new KisOilPaintFilterConfiguration( 1, 30); + } else { + return new KisOilPaintFilterConfiguration( widget->valueAt( 0 ), widget->valueAt( 1 ) ); + } +} + +std::list<KisFilterConfiguration*> KisOilPaintFilter::listOfExamplesConfiguration(KisPaintDeviceSP ) +{ + std::list<KisFilterConfiguration*> list; + list.insert(list.begin(), new KisOilPaintFilterConfiguration( 1, 30)); + return list; +} +</programlisting> + +<para> +You can see how it works: fill a vector with your integer parameters and +create the widget. The <methodname>configuration()</methodname> method +inspects the widget and creates the right filter configuration object, in this +case, of course, <classname>KisOilPaintFilterConfiguration</classname>. The +<methodname>listOfExamplesConfiguration</methodname> method (which should be +renamed to correct English...) returns a list with example configuration +objects for the filters gallery dialog. +</para> +</sect3> + +<sect3 id="developers-plugins-filters-conclusion"> +<title>Filters conclusion</title> + +<para> +There’s more to coding interesting filters, of course, but with this +explanation, the API documentation and access to our source code, you should +be able to get started. Don’t hesitate to contact the &chalk; developers on +IRC or on the mailing list. +</para> +</sect3> + +</sect2> + +<sect2 id="developers-plugins-tools"> +<title>Tools</title> + +<para> +Tools appear in &chalk;’s toolbox. This means that there is limited space for +new tools — think carefully whether a paint operation isn’t enough for +your purposes. Tools can use the mouse/tablet and keyboard in complex ways, +which paint operations cannot. This is the reason that Duplicate is a tool, +but airbrush a paint operation. +</para><para> +Be careful with static data in your tool: a new instance of your tool is +created for every input device: mouse, stylus, eraser, airbrush — whatever. +Tools come divided into logical groups: +</para> +<itemizedlist> +<listitem><para>shape drawing tools (circle, rect)</para></listitem> +<listitem><para>freehand drawing tools (brush)</para></listitem> +<listitem><para>transform tools that mess up the geometry of a +layer</para></listitem> +<listitem><para>fill tools (like bucket fill or gradient)</para></listitem> +<listitem><para>view tools (that don’t change pixels, but alter the way you +view the canvas, such as zoom)</para></listitem> +<listitem><para>select tools (that change the selection +mask)</para></listitem> +</itemizedlist> + +<para> +The tool interface is described in the API documentation for +<classname>KisTool</classname>. There are three subclasses: +<classname>KisToolPaint</classname>, <classname>KisToolNonPaint</classname> +and <classname>KisToolShape</classname> (which is actually a subclass of +<classname>KisToolPaint</classname>) that specialize +<classname>KisTool</classname> for painting tasks (i.e., changing pixels) , +non-painting tasks and shape painting tasks. +</para><para> +A tool has an option widget, just like filters. Currently, the option widgets +are shown in a tab in a dock window. We may change that to a strip under the +main menu (which then replaces the toolbar) for &chalk; 2.0, but for now, +design your option widget to fit in a tab. As always, it’s best to use &Qt; +Designer for the design of the option widget. +</para><para> +A good example of a tool is the star tool: +</para> + +<screen> +kis_tool_star.cc Makefile.am tool_star_cursor.png wdg_tool_star.ui +kis_tool_star.h Makefile.in tool_star.h +chalktoolstar.desktop tool_star.cc tool_star.png +</screen> + +<para> +As you see, you need two images: one for the cursor and one for the toolbox. +<filename>tool_star.cc</filename> is just the plugin loader, similar to what +we have seen above. The real meat is in the implementation: +</para> + +<programlisting> +KisToolStar::KisToolStar() + : KisToolShape(i18n("Star")), + m_dragging (false), + m_currentImage (0) +{ + setName("tool_star"); + setCursor(KisCursor::load("tool_star_cursor.png", 6, 6)); + m_innerOuterRatio=40; + m_vertices=5; +} +</programlisting> + +<para> +The constructor sets the internal name — which is not translated +— and the call to the superclass sets the visible name. We also load the +cursor image and set a number of variables. +</para> + +<programlisting> +void KisToolStar::update (KisCanvasSubject *subject) +{ + KisToolShape::update (subject); + if (m_subject) + m_currentImage = m_subject->currentImg(); +} +</programlisting> + +<para> +The <methodname>update()</methodname> method is called when the tool is +selected. This is not a <classname>KisTool</classname> method, but a +<classname>KisCanvasObserver</classname> method. Canvas observers are notified +whenever something changes in the view, which can be useful for tools. +</para><para> +The following methods (<methodname>buttonPress</methodname>, +<methodname>move</methodname> and <methodname>buttonRelease</methodname>) are +called by &chalk; when the input device (mouse, stylus, eraser etc.) is +pressed down, moved or released. Note that you also get move events if the +mouse button isn’t pressed. The events are not the regular &Qt; events, but +synthetic &chalk; events because we make use of low-level trickery to get +enough events to draw a smooth line. By default, toolkits like &Qt; (and GTK) +drop events if they are too busy to handle them, and we want them all. +</para> + +<programlisting> +void KisToolStar::buttonPress(KisButtonPressEvent *event) +{ + if (m_currentImage && event->button() == LeftButton) { + m_dragging = true; + m_dragStart = event->pos(); + m_dragEnd = event->pos(); + m_vertices = m_optWidget->verticesSpinBox->value(); + m_innerOuterRatio = m_optWidget->ratioSpinBox->value(); + } +} + +void KisToolStar::move(KisMoveEvent *event) +{ + if (m_dragging) { + // erase old lines on canvas + draw(m_dragStart, m_dragEnd); + // move (alt) or resize star + if (event->state() & Qt::AltButton) { + KisPoint trans = event->pos() - m_dragEnd; + m_dragStart += trans; + m_dragEnd += trans; + } else { + m_dragEnd = event->pos(); + } + // draw new lines on canvas + draw(m_dragStart, m_dragEnd); + } +} + +void KisToolStar::buttonRelease(KisButtonReleaseEvent *event) +{ + if (!m_subject || !m_currentImage) + return; + + if (m_dragging && event->button() == LeftButton) { + // erase old lines on canvas + draw(m_dragStart, m_dragEnd); + m_dragging = false; + + if (m_dragStart == m_dragEnd) + return; + + if (!m_currentImage) + return; + + if (!m_currentImage->activeDevice()) + return; + + KisPaintDeviceSP device = m_currentImage->activeDevice ();; + KisPainter painter (device); + if (m_currentImage->undo()) painter.beginTransaction (i18n("Star")); + + painter.setPaintColor(m_subject->fgColor()); + painter.setBackgroundColor(m_subject->bgColor()); + painter.setFillStyle(fillStyle()); + painter.setBrush(m_subject->currentBrush()); + painter.setPattern(m_subject->currentPattern()); + painter.setOpacity(m_opacity); + painter.setCompositeOp(m_compositeOp); + KisPaintOp * op = + KisPaintOpRegistry::instance()->paintOp(m_subject->currentPaintop(), m_subject->currentPaintopSettings(), &painter); + painter.setPaintOp(op); // Painter takes ownership + + vKisPoint coord = starCoordinates(m_vertices, m_dragStart.x(), m_dragStart.y(), m_dragEnd.x(), m_dragEnd.y()); + + painter.paintPolygon(coord); + + device->setDirty( painter.dirtyRect() ); + notifyModified(); + + if (m_currentImage->undo()) { + m_currentImage->undoAdapter()->addCommand(painter.endTransaction()); + } + } +} +</programlisting> + +<para> +The <methodname>draw()</methodname> method is an internal method of +<classname>KisToolStar</classname> and draws the outline of the star. We call +this from the <methodname>move()</methodname> method to give the user feedback +of the size and shape of their star. Note that we use the +<varname>Qt::NotROP</varname> raster operation, which means that calling +<methodname>draw()</methodname> a second time with the same start and end +point the previously drawn star will be deleted. +</para> + +<programlisting> +void KisToolStar::draw(const KisPoint& start, const KisPoint& end ) +{ + if (!m_subject || !m_currentImage) + return; + + KisCanvasController *controller = m_subject->canvasController(); + KisCanvas *canvas = controller->kiscanvas(); + KisCanvasPainter p (canvas); + QPen pen(Qt::SolidLine); + + KisPoint startPos; + KisPoint endPos; + startPos = controller->windowToView(start); + endPos = controller->windowToView(end); + + p.setRasterOp(Qt::NotROP); + + vKisPoint points = starCoordinates(m_vertices, startPos.x(), startPos.y(), endPos.x(), endPos.y()); + + for (uint i = 0; i < points.count() - 1; i++) { + p.drawLine(points[i].floorQPoint(), points[i + 1].floorQPoint()); + } + p.drawLine(points[points.count() - 1].floorQPoint(), points[0].floorQPoint()); + + p.end (); +} +</programlisting> + +<para> +The <methodname>setup()</methodname> method is essential: here we create the +action that will be plugged into the toolbox so users can actually select the +tool. We also assign a shortcut key. Note that there’s some hackery going on: +remember that we create an instance of the tool for every input device. This +also means that we call <methodname>setup()</methodname> for every input +device and that means that an action with the same name is added several times +to the action collection. However, everything seems to work, so why worry? +</para> + +<programlisting> +void KisToolStar::setup(KActionCollection *collection) +{ + m_action = static_cast<KRadioAction *>(collection->action(name())); + + if (m_action == 0) { + KShortcut shortcut(Qt::Key_Plus); + shortcut.append(KShortcut(Qt::Key_F9)); + m_action = new KRadioAction(i18n("&Star"), + "tool_star", + shortcut, + this, + SLOT(activate()), + collection, + name()); + Q_CHECK_PTR(m_action); + + m_action->setToolTip(i18n("Draw a star")); + m_action->setExclusiveGroup("tools"); + m_ownAction = true; + } +} +</programlisting> + +<para> +The <methodname>starCoordinates()</methodname> method contains some funky math +— but is not too interesting for the discussion of how to create a tool +plugins. +</para> + +<programlisting> +KisPoint KisToolStar::starCoordinates(int N, double mx, double my, double x, double y) +{ + double R=0, r=0; + Q_INT32 n=0; + double angle; + + vKisPoint starCoordinatesArray(2*N); + + // the radius of the outer edges + R=sqrt((x-mx)*(x-mx)+(y-my)*(y-my)); + + // the radius of the inner edges + r=R*m_innerOuterRatio/100.0; + + // the angle + angle=-atan2((x-mx),(y-my)); + + //set outer edges + for(n=0;n<N;n++){ + starCoordinatesArray[2*n] = KisPoint(mx+R*cos(n * 2.0 * M_PI / N + angle),my+R*sin(n *2.0 * M_PI / N+angle)); + } + + //set inner edges + for(n=0;n<N;n++){ + starCoordinatesArray[2*n+1] = KisPoint(mx+r*cos((n + 0.5) * 2.0 * M_PI / N + angle),my+r*sin((n +0.5) * 2.0 * M_PI / N + angle)); + } + + return starCoordinatesArray; +} +</programlisting> + +<para> +The <methodname>createOptionWidget()</methodname> method is called to create +the option widget that &chalk; will show in the tab. Since there is a tool per +input device per view, the state of a tool can be kept in the tool. This +method is only called once: the option widget is stored and retrieved the next +time the tool is activated. +</para> + +<programlisting> +QWidget* KisToolStar::createOptionWidget(QWidget* parent) +{ + QWidget *widget = KisToolShape::createOptionWidget(parent); + + m_optWidget = new WdgToolStar(widget); + Q_CHECK_PTR(m_optWidget); + + m_optWidget->ratioSpinBox->setValue(m_innerOuterRatio); + + QGridLayout *optionLayout = new QGridLayout(widget, 1, 1); + super::addOptionWidgetLayout(optionLayout); + + optionLayout->addWidget(m_optWidget, 0, 0); + + return widget; +} +</programlisting> + +<sect3 id="developers-plugins-tools-conclusions"> +<title>Tool Conclusions</title> + +<para> +Tools are relatively simple plugins to create. You need to combine the +<classname>KisTool</classname> and <classname>KisCanvasObserver</classname> +interfaces in order to effectively create a tool. +</para> + +</sect3> + +</sect2> + +<sect2 id="developers-plugins-paintoperations"> +<title>Paint operations</title> + +<para> +PaintOps are one of the more innovative types of plugins in Chalk (together +with pluggable colorspaces). A paint operation defines how tools change the +pixels they touch. Airbrush, aliased pencil or antialiased pixel brush: these +are all paint operations. But you could — with a lot of work — +create a paintop that reads Corel Painter XML brush definitions and uses those +to determine how painting is done. +</para><para> +Paint operations are instantiated when a paint tool receives a +<literal>mouseDown</literal> event and are deleted when the mouseUp event is +received by a paint tool. In between, the paintop can keep track of previous +positions and other data, such as pressure levels if the user uses a tablet. +</para><para> +The basic operation of a paint operation is to change pixels at the cursor +position of a paint tool. That can be done only once, or the paint op can +demand to be run at regular intervals, using a timer. The first would be +useful for a pencil-type paint op, the second, of course, for an +airbrush-type paintop. +</para><para> +Paintops can have a small configuration widget which is placed in a toolbar. +Thus, paintop configuration widgets need to have a horizontal layout of +widgets that are not higher than a toolbar button. Otherwise, &chalk; will +look very funny. +</para><para> +Let’s look at a simple paintop plugin, one that shows a little bit of +programmatic intelligence. First, in the header file, there’s a factory +defined. This factory creates a paintop when the active tool needs one: +</para> + +<programlisting> +public: + KisSmearyOpFactory() {} + virtual ~KisSmearyOpFactory() {} + + virtual KisPaintOp * createOp(const KisPaintOpSettings *settings, KisPainter * painter); + virtual KisID id() { return KisID("paintSmeary", i18n("Smeary Brush")); } + virtual bool userVisible(KisColorSpace * ) { return false; } + virtual QString pixmap() { return ""; } + +}; +</programlisting> + +<para> +The factory also contains the <classname>KisID</classname> with the public and +private name for the paintop — make sure your paintop’s private name +does not clash with another paintop! — and may optionally return a +pixmap. &chalk; can then show the pixmap together with the name for visual +identifcation of your paintop. For instance, a painter’s knife paintop would +have the image of such an implement. +</para><para> +The implementation of a paintop is very straightforward: +</para> + +<programlisting> +KisSmearyOp::KisSmearyOp(KisPainter * painter) + : KisPaintOp(painter) +{ +} + +KisSmearyOp::~KisSmearyOp() +{ +} +void KisSmearyOp::paintAt(const KisPoint &pos, const KisPaintInformation& info) +{ +</programlisting> + +<para> +The <methodname>paintAt()</methodname> method really is where it’s at, with +paintops. This method receives two parameters: the current position (which is +in floats, not in whole pixels) and a +<classname>KisPaintInformation</classname> object. which contains the +pressure, x and y tilt, and movement vector, and may in the future be extended +with other information. +</para> + +<programlisting> + if (!m_painter->device()) return; + + KisBrush *brush = m_painter->brush(); +</programlisting> + +<para> +A <classname>KisBrush</classname> is the representation of a Gimp brush file: +that is a mask, either a single mask or a series of masks. Actually, we don’t +use the brush here, except to determine the <quote>hotspot</quote> under the +cursor. +</para> + +<programlisting> + Q_ASSERT(brush); + + if (!brush) return; + + if (! brush->canPaintFor(info) ) + return; + + KisPaintDeviceSP device = m_painter->device(); + KisColorSpace * colorSpace = device->colorSpace(); + KisColor kc = m_painter->paintColor(); + kc.convertTo(colorSpace); + + KisPoint hotSpot = brush->hotSpot(info); + KisPoint pt = pos - hotSpot; + + // Split the coordinates into integer plus fractional parts. The integer + // is where the dab will be positioned and the fractional part determines + // the sub-pixel positioning. + Q_INT32 x, y; + double xFraction, yFraction; + + splitCoordinate(pt.x(), &x, &xFraction); + splitCoordinate(pt.y(), &y, &yFraction); + + KisPaintDeviceSP dab = new KisPaintDevice(colorSpace, "smeary dab"); + Q_CHECK_PTR(dab); +</programlisting> + +<para> +We don’t change the pixels of a paint device directly: instead we create a +small paint device, a dab, and composite that onto the current paint device. +</para> + +<programlisting> + m_painter->setPressure(info.pressure); +</programlisting> + +<para> +As the comments say, the next bit code does some programmatic work to create +the actual dab. In this case, we draw a number of lines. When I am done with +this paintop, the length, position and thickness of the lines will be +dependent on pressure and paint load, and we’ll have create a stiff, smeary +oilpaint brush. But I haven’t had time to finish this yet. +</para> + +<programlisting> + // Compute the position of the tufts. The tufts are arranged in a line + // perpendicular to the motion of the brush, i.e, the straight line between + // the current position and the previous position. + // The tufts are spread out through the pressure + + KisPoint previousPoint = info.movement.toKisPoint(); + KisVector2D brushVector(-previousPoint.y(), previousPoint.x()); + KisVector2D currentPointVector = KisVector2D(pos); + brushVector.normalize(); + + KisVector2D vl, vr; + + for (int i = 0; i < (NUMBER_OF_TUFTS / 2); ++i) { + // Compute the positions on the new vector. + vl = currentPointVector + i * brushVector; + KisPoint pl = vl.toKisPoint(); + dab->setPixel(pl.roundX(), pl.roundY(), kc); + + vr = currentPointVector - i * brushVector; + KisPoint pr = vr.toKisPoint(); + dab->setPixel(pr.roundX(), pr.roundY(), kc); + } + + vr = vr - vl; + vr.normalize(); +</programlisting> + +<para> +Finally we blt the dab onto the original paint device and tell the painter +that we’ve dirtied a small rectangle of the paint device. +</para> + +<programlisting> + if (m_source->hasSelection()) { + m_painter->bltSelection(x - 32, y - 32, m_painter->compositeOp(), dab.data(), + m_source->selection(), m_painter->opacity(), x - 32, y -32, 64, 64); + } + else { + m_painter->bitBlt(x - 32, y - 32, m_painter->compositeOp(), dab.data(), m_painter->opacity(), x - 32, y -32, 64, 64); + } + + m_painter->addDirtyRect(QRect(x -32, y -32, 64, 64)); +} + + +KisPaintOp * KisSmearyOpFactory::createOp(const KisPaintOpSettings */*settings*/, KisPainter * painter) +{ + KisPaintOp * op = new KisSmearyOp(painter); + Q_CHECK_PTR(op); + return op; +} +</programlisting> + +<para> +That’s all: paintops are easy and fun! +</para> + +</sect2> + +<sect2 id="developers-plugins-viewplugins"> +<title>View plugins</title> + +<para> +View plugins are the weirdest of the bunch: a view plugin is an ordinary KPart +that can provide a bit of user interface and some functionality. For instance, +the histogram tab is a view plugin, as is the rotate dialog. +</para> + +</sect2> + +<sect2 id="developers-plugins-importexport"> +<title>Import/Export filters</title> + +<para> +&chalk; works with the ordinary &koffice; file filter architecture. There is a +tutorial, a bit old, but still useful, at: <ulink +url="http://koffice.org/developer/filters/oldfaq.php" />. It is probably best +to cooperate with the &chalk; team when developing file filters and do the +development in the &koffice; filter tree. Note that you can test your filters +without running &chalk; using the <command>koconverter</command> utility. +</para><para> +Filters have two sides: importing and exporting. These are usually two +different plugins that may share some code. +</para><para> +The important <filename>Makefile.am</filename> entries are: +</para> + +<programlisting> +service_DATA = chalk_XXX_import.desktop chalk_XXX_export.desktop +servicedir = $(kde_servicesdir) +kdelnk_DATA = chalk_XXX.desktop +kdelnkdir = $(kde_appsdir)/Office +libchalkXXXimport_la_SOURCES = XXXimport.cpp +libchalkXXXexport_la_SOURCES = XXXexport.cpp +METASOURCES = AUTO +</programlisting> + +<para> +Whether you are building an import filter or an export filter, your work always +boils down to implementing the following function: +</para> + +<programlisting> +virtual KoFilter::ConversionStatus convert(const QCString& from, const QCString& to); +</programlisting> + +<para> +It is the settings in the <literal role="extension">.desktop</literal> files +that determine which way a filter converts: +</para><para> +Import: +</para> + +<programlisting> +X-KDE-Export=application/x-chalk +X-KDE-Import=image/x-xcf-gimp +X-KDE-Weight=1 +X-KDE-Library=libchalkXXXimport +ServiceTypes=KOfficeFilter +</programlisting> + +<para> +Export: +</para> + +<programlisting> +X-KDE-Export=image/x-xcf-gimp +X-KDE-Import=application/x-chalk +ServiceTypes=KOfficeFilter +Type=Service +X-KDE-Weight=1 +X-KDE-Library=libchalkXXXexport +</programlisting> + +<para> +And yes, the mimetype chosen for the example is a hint. Please, pretty please, +implement an xcf filter? +</para> + +<sect3 id="plugins-developers-importexport-import"> +<title>Import</title> + +<para> +The big problem with import filters is of course your code to read the data on +disk. The boilerplate for calling that code is fairly simple: +</para> + +<note><para>Note: we really, really should find a way to enable &chalk; to keep +a file open and only read data on a as-needed basis, instead of copying the +entire contents to the internal paint device representation. But that would +mean datamanager backends that know about tiff files and so on, and is not +currently implemented. It would be ideal if some file filters could implement +a class provisionally named <classname>KisFileDataManager</classname>, create +an object of that instance with the current file and pass that to KisDoc. But +&chalk; handles storage per layer, not per document, so this would be a hard +refactor to do.</para></note> + +<programlisting> +KoFilter::ConversionStatus XXXImport::convert(const QCString&, const QCString& to) +{ + if (to != "application/x-chalk") <co id="import1" /> + return KoFilter::BadMimeType; + + KisDoc * doc = dynamic_cast<KisDoc*>(m_chain -> outputDocument()); <co id="import2" /> + KisView * view = static_cast<KisView*>(doc -> views().getFirst()); <co id="import3" /> + + QString filename = m_chain -> inputFile(); <co id="import4" /> + + if (!doc) + return KoFilter::CreationError; + + doc -> prepareForImport(); <co id="import5" /> + + if (!filename.isEmpty()) { + + KURL url(filename); + + if (url.isEmpty()) + return KoFilter::FileNotFound; + + KisImageXXXConverter ib(doc, doc -> undoAdapter()); <co id="import6" /> + + if (view != 0) + view -> canvasSubject() -> progressDisplay() -> setSubject(&ib, false, true); + + switch (ib.buildImage(url)) <co id="import7" /> { + case KisImageBuilder_RESULT_UNSUPPORTED: + return KoFilter::NotImplemented; + break; + case KisImageBuilder_RESULT_INVALID_ARG: + return KoFilter::BadMimeType; + break; + case KisImageBuilder_RESULT_NO_URI: + case KisImageBuilder_RESULT_NOT_LOCAL: + return KoFilter::FileNotFound; + break; + case KisImageBuilder_RESULT_BAD_FETCH: + case KisImageBuilder_RESULT_EMPTY: + return KoFilter::ParsingError; + break; + case KisImageBuilder_RESULT_FAILURE: + return KoFilter::InternalError; + break; + case KisImageBuilder_RESULT_OK: + doc -> setCurrentImage( ib.image()); <co id="import8" /> + return KoFilter::OK; + default: + break; + } + + } + return KoFilter::StorageCreationError; +} +</programlisting> + +<calloutlist> +<callout arearefs="import1"><para>This is supposed to be an importfilter, so +if it is not called to convert to a &chalk; image, then something is +wrong.</para></callout> +<callout arearefs="import2"><para>The filter chain already has created an +output document for us. We need to cast it to <classname>KisDocM</classname>, +because &chalk; documents need special treatment. It would not, actually, be +all that bad an idea to check whether the result of the cast is not 0, because +if it is, importing will fail.</para></callout> +<callout arearefs="import3"><para>If we call this filter from the GUI, we try +to get the view. If there is a view, the conversion code can try to update the +progressbar.</para></callout> +<callout arearefs="import4"><para>The filter has the filename for our input +file for us.</para></callout> +<callout arearefs="import5"><para><classname>KisDoc</classname> needs to be +prepared for import. Certain settings are initialized and undo is disabled. +Otherwise you could undo the adding of layers performed by the import filter +and that is weird behaviour.</para></callout> +<callout arearefs="import6"><para>I have chosed to implement the actual +importing code in a separate class that I instantiate here. You can also put +all your code right in this method, but that would be a bit +messy.</para></callout> +<callout arearefs="import7"><para>My importer returns a statuscode that I +can then use to set the status of the import filter. &koffice; takes care of +showing error messages.</para></callout> +<callout arearefs="import8"><para>If creating the +<classname>KisImage</classname> has succeeded we set the document's current +image to our newly created image. Then we are done: <literal>return +KoFilter::OK;</literal>.</para></callout> +</calloutlist> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/chalk/developers-scripting.docbook b/doc/chalk/developers-scripting.docbook new file mode 100644 index 00000000..fec163db --- /dev/null +++ b/doc/chalk/developers-scripting.docbook @@ -0,0 +1,534 @@ +<sect1 id="developers-scripting"> +<title>Scripting</title> + +<para> +In &chalk;, you can write scripts in Ruby or Python (the availability of the +interpreters might depend on what your distributions or the administrator of +your machine did install). Here you will find a description of the scripting +API. +</para><para> +Some examples are distributed with &chalk;, and you might find them in +<filename>/usr/share/apps/chalk/scripts</filename> (or +<filename>/opt/kde/share/apps/chalk/scripts</filename>). +</para> + +<sect2 id="developers-scripting-variables"> +<title>Variables in the <classname>Krosschalkcore</classname> module</title> + +<itemizedlist> +<listitem><para><varname>ChalkDocument</varname> returns a +<classname>Document</classname> object</para></listitem> +<listitem><para><varname>ChalkScript</varname> returns a +<classname>ScriptProgress</classname> object</para></listitem> +</itemizedlist> + +<para> +You can retrieve an object using the <function>get</function> function of the +<classname>Krosschalkcore</classname> module, in Ruby you will have to write something like that: +<programlisting> +doc = Krosschalkcore::get("ChalkDocument") +script = Krosschalkcore::get("ChalkScript") +</programlisting> +</para> + +</sect2> + +<sect2 id="developers-scripting-functions"> +<title>Functions in the <classname>Krosschalkcore</classname> module</title> + +<itemizedlist> +<listitem><para>Function: <function>getBrush</function></para><para> +This function returns a <classname>Brush</classname> taken from the list of +&chalk; resources. It takes one argument: the name of the brush. +For example (in Ruby): +<programlisting> +Krosschalkcore::getBrush("Circle (05)") +</programlisting></para></listitem> + +<listitem><para>Function: <function>getFilter</function></para><para> +This function returns a <classname>Filter</classname> taken from the list of +&chalk; resources. It takes one argument: the name of the filter. +For example (in Ruby): +<programlisting> +Krosschalkcore::getFilter("invert") +</programlisting></para></listitem> + +<listitem><para>Function: <function>getPattern</function></para><para> +This function returns a <classname>Pattern</classname> taken from the list of +&chalk; resources. It takes one argument: the name of the pattern. +For example (in Ruby): +<programlisting> +Krosschalkcore::getPattern("Bricks") +</programlisting></para></listitem> + +<listitem><para>Function: <function>loadBrush</function></para><para> +This function loads a <classname>Brush</classname> and then returns it. +It takes one argument: the filename of the brush.</para></listitem> + +<listitem><para>Function: <function>loadPattern</function></para><para> +This function loads a <classname>Pattern</classname> and then returns it. +It takes one argument: the filename of the pattern.</para></listitem> + +<listitem><para>Function: <function>newCircleBrush</function></para><para> +This function returns a <classname>Brush</classname> with a circular shape. It +takes at least two arguments: width and height. It can take two other +arguments: width of the shading, and height of the shading. If the shading +is not specified, no shading will be used. +For example (in Ruby): +<programlisting> +Krosschalkcore::newCircleBrush(10,20) # create a plain circle +Krosschalkcore::newCircleBrush(10,20,5,10) # create a gradient +</programlisting></para></listitem> + +<listitem><para>Function: <function>newHSVColor</function></para><para> +This function returns a new <classname>Color</classname> with the given HSV +triplet. It takes three arguments: hue component (0 to 255), saturation +component (0 to 255), value component (0 to 255). + +For example (in Ruby): +<programlisting> +Krosschalkcore::newHSVColor(255,125,0) +</programlisting></para></listitem> + +<listitem><para>Function: <function>newImage</function></para><para> +This function returns a new <classname>Image</classname>. It takes four arguments: +width, height, colorspace id, name of the image. And in return you get an +<classname>Image</classname> object. +For example (in Ruby): +<programlisting> +Krosschalkcore::newImage(10,20, "RGBA", "kikoo") +</programlisting></para></listitem> + +<listitem><para>Function: <function>newRectBrush</function></para><para> +This function returns a <classname>Brush</classname> with a rectangular shape. +It takes at least two arguments: width and height. It can take two other +arguments: width of the shading and height of the shading. If the shading is +not specified, no shading will be used. +For example (in Ruby): +<programlisting> + Krosschalkcore::newRectBrush(10,20) # create a plain rectangle + Krosschalkcore::newRectBrush(10,20,5,10) # create a gradient +</programlisting></para></listitem> + +<listitem><para>Function: <function>newRGBColor</function></para><para> +This function returns a new <classname>Color</classname> with the given RGB +triplet. It takes three arguments: red component (0 to 255), blue component (0 to +255), green component (0 to 255). +For example (in Ruby): +<programlisting> +Krosschalkcore::newRGBColor(255,0,0) # create a red color +Krosschalkcore::newRGBColor(255,255,255) # create a white color +</programlisting></para></listitem> +</itemizedlist> +</sect2> + +<sect2 id="developers-scripting-objects"> +<title>Descriptions and function lists for various objects in +<classname>Krosschalkcore</classname></title> + +<itemizedlist> +<listitem><para>Object: PaintLayer</para> + +<itemizedlist> +<listitem><para>Function: <function>beginPainting</function></para></listitem> + +<listitem><para>Function: <function>convertToColorspace</function></para><para> +Convert the image to a colorspace. This function takes one argument: the name +of the destination colorspace. +For example (in Ruby): +<programlisting> +image.convertToColorspace("CMYK") +</programlisting></para></listitem> + +<listitem><para>Function: <function>createHistogram</function></para><para> +This function creates a Histogram for this layer. It takes two arguments: +the type of the histogram ("RGB8HISTO"), and 0 if the histogram is linear, or +1 if it is logarithmic.</para></listitem> + +<listitem><para>Function: <function>createHLineIterator</function></para><para> +Create an iterator over a layer, it will iterate on a row. This function takes three arguments: +<varname>x</varname> (start in the row), <varname>y</varname> (vertical +position of the row), width of the row.</para></listitem> + +<listitem><para>Function: <function>createPainter</function></para><para> +This function creates a <classname>Painter</classname> which will allow you to +paint on the layer. </para></listitem> + +<listitem><para>Function: <function>createRectIterator</function></para><para> +Create an iterator over a layer, it will iterate on a rectangular area. This +function takes four arguments: <varname>x</varname>, <varname>y</varname>, +width of the rectangle, height of the rectangle.</para></listitem> + +<listitem><para>Function: <function>createVLineIterator</function></para><para> +Create an iterator over a layer, it will iterate on a column. This function +takes three arguments: <varname>x</varname> (horizontal position of the +column), <varname>y</varname> (start in the column), height of the column.</para></listitem> + +<listitem><para>Function: <function>endPainting</function></para><para> +This function closes the current undo entry and adds it to the history.</para></listitem> + +<listitem><para>Function: <function>fastWaveletTransformation</function></para><para> +Returns the fast wavelet transformation of the layer.</para></listitem> + +<listitem><para>Function: <function>fastWaveletUntransformation</function></para><para> +Untransforms a fast wavelet into this layer. It takes one argument: a wavelet +object. +For example (in Ruby): +<programlisting> +wavelet = layer.fastWaveletTransformation() +layer.fastWaveletUntransformation(wavelet) +</programlisting></para></listitem> + +<listitem><para>Function: <function>getHeight</function></para><para> +Return the height of the layer.</para></listitem> + +<listitem><para>Function: <function>getWidth</function></para><para> +Return the width of the layer.</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>Filter</classname></para> +<itemizedlist> + +<listitem><para>Function: <function>getFilterConfiguration</function></para><para> +This function returns the <classname>FilterConfiguration</classname> +associated with this filter.</para></listitem> + +<listitem><para>Function: <function>process</function></para><para> +This function will apply the filter. It takes at least one argument: the +source layer. You can also use these four aguments: <varname>x</varname>, +<varname>y</varname>, <varname>width</varname>, <varname>height</varname>. +(<varname>x</varname>,<varname>y</varname>,<varname>width</varname>,<varname>height</varname>) +defines the rectangular area on which the filter +will be computed. If the rectangle is not defined, then the filter will be +applied on the entire source layer. +For example (in Ruby) +<programlisting> +doc = Krosschalkcore::get("ChalkDocument") +image = doc.getImage() +layer = image.getActivePaintLayer() +width = layer.getWidth() +height = layer.getHeight() +filter = Krosschalkcore::getFilter("invert") +filter.process(layer, layer) +filter.process(layer, layer, 10, 10, 20, 20 ) +</programlisting></para></listitem> +</itemizedlist></listitem> + +<listitem><para>Object: <classname>FilterConfiguration</classname></para> +<itemizedlist> + +<listitem><para>Function: <function>getProperty</function></para><para> +This function returns the value of a parameter of the associated +<classname>Filter</classname>. It takes one argument: the name of the +parameter.</para></listitem> + +<listitem><para>Function: <function>setProperty</function></para><para> +This function defines a parameter of the associated +<classname>Filter</classname>. It takes two arguments: the name of the +parameter and the value, whose type depends on the +<classname>Filter</classname>.</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>Histogram</classname></para> + +<para>This class allows you to access the histogram of a +<classname>PaintLayer</classname>. +Example (in Ruby): +<programlisting> + doc = krosschalkcore::get("ChalkDocument") + image = doc.getImage() + layer = image.getActiveLayer() + histo = layer.createHistogram("RGB8HISTO",0) + min = layer.getMin() * 255 + max = layer.getMax() * 255 + for i in min..max + print layer.getValue(i) + print "\n" + end +</programlisting> +</para> + +<itemizedlist> +<listitem><para>Function: <function>getChannel</function></para><para> +Return the selected channel.</para></listitem> + +<listitem><para>Function: <function>getCount</function></para><para> +This function returns the number of pixels used by the histogram.</para></listitem> + +<listitem><para>Function: <function>getHighest</function></para><para> +This function returns the highest value of the histogram.</para></listitem> + +<listitem><para>Function: <function>getLowest</function></para><para> +This function returns the lowest value of the histogram.</para></listitem> + +<listitem><para>Function: <function>getMax</function></para><para> +This function returns the maximum bound of the histogram (values at greater +position than the maximum are null). The value is in the range 0.0 – 1.0.</para></listitem> + +<listitem><para>Function: <function>getMean</function></para><para> +This function returns the mean of the histogram.</para></listitem> + +<listitem><para>Function: <function>getMin</function></para><para> +This function returns the minimum bound of the histogram (values at smaller +position than the minimum are null). The value is in the range 0.0 – 1.0.</para></listitem> + +<listitem><para>Function: <function>getNumberOfBins</function></para><para> +Return the number of bins of this histogram. </para></listitem> + +<listitem><para>Function: <function>getTotal</function></para><para> +This function returns the sum of all values of the histogram.</para></listitem> + +<listitem><para>Function: <function>getValue</function></para><para> +Return the value of a bin of the histogram. This function takes one argument: +index, in the range [0..255].</para></listitem> + +<listitem><para>Function: <function>setChannel</function></para><para> +Select the channel of the layer on which to get the result of the histogram. +This function takes one argument: the channel number.</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>ScriptProgress</classname></para> +<para><classname>ScriptProgress</classname> is used to manage the progress bar +of the status bar in &chalk;. +For example (in Ruby): +<programlisting> +script = Krosschalkcore::get("ChalkScript") +script.setProgressTotalSteps(1000) +script.setProgressStage("progressive", 0) +for i in 1..900 + script.incProgress() +end +script.setProgressStage("brutal", 1000) +</programlisting></para> + +<itemizedlist> +<listitem><para>Function: <function>incProgress</function></para><para> +This function increments the progress by one step.</para></listitem> + +<listitem><para>Function: <function>setProgress</function></para><para> +This function sets the value of the progress. It takes one argument: +the value of the progress.</para></listitem> + +<listitem><para>Function: <function>setProgressStage</function></para><para> +This function sets the value of the progress and displays the text.</para></listitem> + +<listitem><para>Function: <function>setProgressTotalSteps</function></para><para> +This function set the number of steps that the script will require. It takes +one argument: the maximum value of the progress</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>Wavelet</classname></para><para> +This object holds the coefficients of a wavelet transformation of a +<classname>PaintLayer</classname>.</para> +<itemizedlist> + +<listitem><para>Function: <function>getDepth</function></para><para> +Returns the depth of the layer.</para></listitem> + +<listitem><para>Function: <function>getNCoeff</function></para><para> +Returns the value of the Nth coefficient. The function takes one argument: the +index of the coefficient.</para></listitem> + +<listitem><para>Function: <function>getNumCoeffs</function></para><para> +Returns the number of coefficients in this wavelet (= size * size * depth).</para></listitem> + +<listitem><para>Function: <function>getSize</function></para><para> +Returns the size of the wavelet (size = width = height).</para></listitem> + +<listitem><para>Function: <function>getXYCoeff</function></para><para> +Returns the value of a coefficient. The function takes two arguments: +<varname>x</varname> and <varname>y</varname>.</para></listitem> + +<listitem><para>Function: <function>setNCoeff</function></para><para> +Set the value of the Nth coefficient. The function takes two arguments: the +index of the coefficient and the new value of the coefficient.</para></listitem> + +<listitem><para>Function: <function>setXYCoeff</function></para><para> +Set the value of a coefficient. The function takes three arguments: +<varname>x</varname>, <varname>y</varname>, and the new value of the +coefficient.</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>Painter</classname></para> +<itemizedlist> + +<listitem><para>Function: <function>convolve</function></para><para> +This function applies a convolution kernel to an image. It takes at least three arguments: +a list of kernels (all lists need to have the same size), +factor, and offset. +</para><para> +The value of a pixel will be given by the following function: K * P / factor + offset, +where K is the kernel and P is the neighbourhood. +</para><para> +It can take the following optional arguments: <varname>borderOp</varname> +(control how to convolve the pixels on the border of an image: 0 = use the +default color, 1 = use the pixel on the opposite side of the image, 2 = use +the border pixel, 3 = avoid border pixels), <varname>channel</varname> (1 for +color, 2 for alpha, 3 for both), <varname>x</varname>, <varname>y</varname>, +<varname>width</varname>, <varname>height</varname>.</para></listitem> + +<listitem><para>Function: <function>setFillThreshold</function></para><para> +Sets the fill threshold. It takes one argument: the threshold.</para></listitem> + +<listitem><para>Function: <function>fillColor</function></para><para> +Starts filling with a color. It takes two arguments: <varname>x</varname> and +<varname>y</varname>.</para></listitem> + +<listitem><para>Function: <function>fillPattern</function></para><para> +Starts filling with a pattern. It takes two arguments: <varname>x</varname> +and <varname>y</varname>.</para></listitem> + +<listitem><para>Function: <function>paintPolyline</function></para><para> +This function will paint a polyline. It takes two arguments: a list of x +positions, and a list of y positions.</para></listitem> + +<listitem><para>Function: <function>paintLine</function></para><para> +This function will paint a line. It takes five arguments: +<varname>x1</varname>, <varname>y1</varname>, <varname>x2</varname>, +<varname>y2</varname>, and <varname>pressure</varname>. +</para></listitem> + +<listitem><para>Function: <function>paintBezierCurve</function></para><para> +This function will paint a Bezier curve. It takes ten arguments: +<varname>x1</varname>, <varname>y1</varname>, <varname>p1</varname>, +<varname>cx1</varname>, <varname>cy1</varname>, <varname>cx2</varname>, +<varname>cx2</varname>, <varname>x2</varname>, <varname>y2</varname>, +<varname>p2</varname>, where (<varname>x1</varname>,<varname>y1</varname>) is +the start position, <varname>p1</varname> is the pressure at the start, +(<varname>x2</varname>,<varname>y2</varname>) is the end position, +<varname>p2</varname> is the pressure at the end. +(<varname>cx1</varname>,<varname>cy1</varname>) and +(<varname>cx2</varname>,<varname>cy2</varname>) are the positions of the +control points.</para></listitem> + +<listitem><para>Function: <function>paintEllipse</function></para><para> +This function will paint an ellipse. It takes five arguments: +<varname>x1</varname>, <varname>y1</varname>, <varname>x2</varname>, +<varname>y2</varname>, <varname>pressure</varname>, where +(<varname>x1</varname>,<varname>y1</varname>) and +(<varname>x2</varname>,<varname>y2</varname>) are the positions of the two +centers.</para></listitem> + +<listitem><para>Function: <function>paintPolygon</function></para><para> +This function will paint a polygon. It takes two arguments: a list of x +positions and a list of y positions.</para></listitem> + +<listitem><para>Function: <function>paintRect</function></para><para> +This function will paint a rectangle. It takes five arguments: +<varname>x</varname>, <varname>y</varname>, <varname>width</varname> +<varname>height</varname>, <varname>pressure</varname>.</para></listitem> + +<listitem><para>Function: <function>paintAt</function></para><para> +This function will paint at a given position. +It takes three arguments: <varname>x</varname>, <varname>y</varname>, +<varname>pressure</varname>.</para></listitem> + +<listitem><para>Function: <function>setPaintColor</function></para><para> +This function sets the paint color (also called foreground color). It takes +one argument: a <classname>Color</classname>.</para></listitem> + +<listitem><para>Function: <function>setBackgroundColor</function></para><para> +This function sets the background color. It takes one argument: a +<classname>Color</classname>.</para></listitem> + +<listitem><para>Function: <function>setPattern</function></para><para> +This function sets the pattern used for filling. It takes one argument: a +<classname>Pattern</classname> object.</para></listitem> + +<listitem><para>Function: <function>setBrush</function></para><para> +This function sets the brush used for painting. It takes one argument: a +<classname>Brush</classname> object.</para></listitem> + +<listitem><para>Function: <function>setPaintOp</function></para><para> +This function defines the paint operation. It takes one argument: the name of +the paint operation.</para></listitem> + +<listitem><para>Function: <function>setDuplicateOffset</function></para><para> +This function defines the duplicate offset. It takes two arguments: the +horizontal offset and the vertical offset.</para></listitem> + +<listitem><para>Function: <function>setOpacity</function></para><para> +This function set the opacity of the painting. It takes one argument: the +opacity, in the range 0 to 255.</para></listitem> + +<listitem><para>Function: <function>setStrokeStyle</function></para><para> +This function sets the style of the stroke. It takes one argument: 0 for none, +or 1 for brush.</para></listitem> + +<listitem><para>Function: <function>setFillStyle</function></para><para> +This function sets the fill style of the <classname>Painter</classname>. +It takes one argument: 0 for none, 1 for fill with foreground color, 2 for +fill with background color, 3 for fill with pattern.</para></listitem> +</itemizedlist> +</listitem> + +<listitem><para>Object: <classname>Iterator</classname></para><para> +This object allows you to change pixel values one by one. +The name of some functions depends on the colorspace, for instance, if the +colorspace of the layer is RGB, you will have <function>setR</function>, +<function>setG</function> and <function>setB</function>, and for +CMYK: <function>setC</function>, <function>setM</function>, +<function>setY</function> and <function>setK</function>. In the documentation +below we will assume that the colorspace is called ABC, with three channels: +A, B and C.</para> + +<itemizedlist> +<listitem><para>Functions: <function>setA</function>, +<function>setB</function>, <function>setC</function></para><para> +Those functions take one argument: the new value of one of the channels of +this pixel.</para></listitem> + +<listitem><para>Function: <function>setABC</function></para><para> +Set the value of all channels. This function takes one argument: an array with +the new values for all channels.</para></listitem> + +<listitem><para>Functions: <function>getA</function>, +<function>getB</function>, <function>getC</function></para><para> +Return the value of one of the channels of this pixel.</para></listitem> + +<listitem><para>Function: <function>getABC</function></para><para> +Return an array with the values of all channels.</para></listitem> + +<listitem><para>Function: <function>darken</function></para><para> +Darken a pixel. This function takes at least one argument: +<varname>shade</varname> (amount used to darken all color channels). This +function can take the following optional argument: +<varname>compensation</varname> (to limit the darkening).</para></listitem> + +<listitem><para>Function: <function>invertColor</function></para><para> +Invert the color of a pixel.</para></listitem> + +<listitem><para>Function: <function>next</function></para><para> +Increment the position, go to the next pixel.</para></listitem> + +<listitem><para>Function: <function>isDone</function></para><para> +Return true if the iterator is at the end (no more pixels are +available).</para></listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="developers-scripting-resources"> +<title>Resources</title> + +<para> +Here are hints or partial lists of resources for &chalk;. +</para><para> +For <classname>Brush</classname> and <classname>Pattern</classname>: You can get +the name and the associated brush or pattern from the selector in &chalk;'s +toolbar. +</para><para> +A list of ids for colorspaces in &chalk;: LABA, RGBA, RGBA16, RGBAF32, +RGBAF16HALF, LMSAF32, GRAYA, GRAYA16, CMYK, CMYKA16. +</para> +</sect2> + +</sect1> + diff --git a/doc/chalk/developers.docbook b/doc/chalk/developers.docbook new file mode 100644 index 00000000..212bb9fa --- /dev/null +++ b/doc/chalk/developers.docbook @@ -0,0 +1,13 @@ +<chapter id="developers"> +<title>Developer's information</title> + +<para> +This chapter contains information for developers or other enthousiasts who +want to get more out of &chalk;. +</para> + +&developers-scripting; +&developers-plugins; + +</chapter> + diff --git a/doc/chalk/dialogs-addpalette.png b/doc/chalk/dialogs-addpalette.png Binary files differnew file mode 100644 index 00000000..6f249d96 --- /dev/null +++ b/doc/chalk/dialogs-addpalette.png diff --git a/doc/chalk/dialogs-blur.png b/doc/chalk/dialogs-blur.png Binary files differnew file mode 100644 index 00000000..3318d844 --- /dev/null +++ b/doc/chalk/dialogs-blur.png diff --git a/doc/chalk/dialogs-brightnesscontrast.png b/doc/chalk/dialogs-brightnesscontrast.png Binary files differnew file mode 100644 index 00000000..39d8c652 --- /dev/null +++ b/doc/chalk/dialogs-brightnesscontrast.png diff --git a/doc/chalk/dialogs-bumpmap.png b/doc/chalk/dialogs-bumpmap.png Binary files differnew file mode 100644 index 00000000..5c20347f --- /dev/null +++ b/doc/chalk/dialogs-bumpmap.png diff --git a/doc/chalk/dialogs-coloradjustment.png b/doc/chalk/dialogs-coloradjustment.png Binary files differnew file mode 100644 index 00000000..b18a8023 --- /dev/null +++ b/doc/chalk/dialogs-coloradjustment.png diff --git a/doc/chalk/dialogs-colorrange.png b/doc/chalk/dialogs-colorrange.png Binary files differnew file mode 100644 index 00000000..6f11b374 --- /dev/null +++ b/doc/chalk/dialogs-colorrange.png diff --git a/doc/chalk/dialogs-colortoalpha.png b/doc/chalk/dialogs-colortoalpha.png Binary files differnew file mode 100644 index 00000000..bc99c3e8 --- /dev/null +++ b/doc/chalk/dialogs-colortoalpha.png diff --git a/doc/chalk/dialogs-colortransfer.png b/doc/chalk/dialogs-colortransfer.png Binary files differnew file mode 100644 index 00000000..00d86095 --- /dev/null +++ b/doc/chalk/dialogs-colortransfer.png diff --git a/doc/chalk/dialogs-convertimagetype.png b/doc/chalk/dialogs-convertimagetype.png Binary files differnew file mode 100644 index 00000000..3df33c65 --- /dev/null +++ b/doc/chalk/dialogs-convertimagetype.png diff --git a/doc/chalk/dialogs-convertlayertype.png b/doc/chalk/dialogs-convertlayertype.png Binary files differnew file mode 100644 index 00000000..85f6977c --- /dev/null +++ b/doc/chalk/dialogs-convertlayertype.png diff --git a/doc/chalk/dialogs-cubism.png b/doc/chalk/dialogs-cubism.png Binary files differnew file mode 100644 index 00000000..b2e3b741 --- /dev/null +++ b/doc/chalk/dialogs-cubism.png diff --git a/doc/chalk/dialogs-customconvolution.png b/doc/chalk/dialogs-customconvolution.png Binary files differnew file mode 100644 index 00000000..ee15631b --- /dev/null +++ b/doc/chalk/dialogs-customconvolution.png diff --git a/doc/chalk/dialogs-documentinformation.png b/doc/chalk/dialogs-documentinformation.png Binary files differnew file mode 100644 index 00000000..2462853f --- /dev/null +++ b/doc/chalk/dialogs-documentinformation.png diff --git a/doc/chalk/dialogs-dropshadow.png b/doc/chalk/dialogs-dropshadow.png Binary files differnew file mode 100644 index 00000000..c2e0b15f --- /dev/null +++ b/doc/chalk/dialogs-dropshadow.png diff --git a/doc/chalk/dialogs-emboss.png b/doc/chalk/dialogs-emboss.png Binary files differnew file mode 100644 index 00000000..552d4676 --- /dev/null +++ b/doc/chalk/dialogs-emboss.png diff --git a/doc/chalk/dialogs-filtersgallery.png b/doc/chalk/dialogs-filtersgallery.png Binary files differnew file mode 100644 index 00000000..492a506b --- /dev/null +++ b/doc/chalk/dialogs-filtersgallery.png diff --git a/doc/chalk/dialogs-gaussiannoise.png b/doc/chalk/dialogs-gaussiannoise.png Binary files differnew file mode 100644 index 00000000..3de3ace9 --- /dev/null +++ b/doc/chalk/dialogs-gaussiannoise.png diff --git a/doc/chalk/dialogs-histogram.png b/doc/chalk/dialogs-histogram.png Binary files differnew file mode 100644 index 00000000..252e3a31 --- /dev/null +++ b/doc/chalk/dialogs-histogram.png diff --git a/doc/chalk/dialogs-imageproperties.png b/doc/chalk/dialogs-imageproperties.png Binary files differnew file mode 100644 index 00000000..893cf95d --- /dev/null +++ b/doc/chalk/dialogs-imageproperties.png diff --git a/doc/chalk/dialogs-imagerestoration.png b/doc/chalk/dialogs-imagerestoration.png Binary files differnew file mode 100644 index 00000000..16b1ae2c --- /dev/null +++ b/doc/chalk/dialogs-imagerestoration.png diff --git a/doc/chalk/dialogs-imagesize.png b/doc/chalk/dialogs-imagesize.png Binary files differnew file mode 100644 index 00000000..5028a38e --- /dev/null +++ b/doc/chalk/dialogs-imagesize.png diff --git a/doc/chalk/dialogs-layerproperties.png b/doc/chalk/dialogs-layerproperties.png Binary files differnew file mode 100644 index 00000000..83c6738d --- /dev/null +++ b/doc/chalk/dialogs-layerproperties.png diff --git a/doc/chalk/dialogs-layersize.png b/doc/chalk/dialogs-layersize.png Binary files differnew file mode 100644 index 00000000..afab719f --- /dev/null +++ b/doc/chalk/dialogs-layersize.png diff --git a/doc/chalk/dialogs-lenscorrection.png b/doc/chalk/dialogs-lenscorrection.png Binary files differnew file mode 100644 index 00000000..c550758c --- /dev/null +++ b/doc/chalk/dialogs-lenscorrection.png diff --git a/doc/chalk/dialogs-newadjustmentlayer.png b/doc/chalk/dialogs-newadjustmentlayer.png Binary files differnew file mode 100644 index 00000000..67ff729b --- /dev/null +++ b/doc/chalk/dialogs-newadjustmentlayer.png diff --git a/doc/chalk/dialogs-newlayer.png b/doc/chalk/dialogs-newlayer.png Binary files differnew file mode 100644 index 00000000..acb22f10 --- /dev/null +++ b/doc/chalk/dialogs-newlayer.png diff --git a/doc/chalk/dialogs-oilpaint.png b/doc/chalk/dialogs-oilpaint.png Binary files differnew file mode 100644 index 00000000..71d277cd --- /dev/null +++ b/doc/chalk/dialogs-oilpaint.png diff --git a/doc/chalk/dialogs-pixelize.png b/doc/chalk/dialogs-pixelize.png Binary files differnew file mode 100644 index 00000000..6ae16526 --- /dev/null +++ b/doc/chalk/dialogs-pixelize.png diff --git a/doc/chalk/dialogs-raindrops.png b/doc/chalk/dialogs-raindrops.png Binary files differnew file mode 100644 index 00000000..65e462aa --- /dev/null +++ b/doc/chalk/dialogs-raindrops.png diff --git a/doc/chalk/dialogs-randomnoise.png b/doc/chalk/dialogs-randomnoise.png Binary files differnew file mode 100644 index 00000000..405d4313 --- /dev/null +++ b/doc/chalk/dialogs-randomnoise.png diff --git a/doc/chalk/dialogs-randompick.png b/doc/chalk/dialogs-randompick.png Binary files differnew file mode 100644 index 00000000..8eb4f47d --- /dev/null +++ b/doc/chalk/dialogs-randompick.png diff --git a/doc/chalk/dialogs-rotateimage.png b/doc/chalk/dialogs-rotateimage.png Binary files differnew file mode 100644 index 00000000..2f18b18e --- /dev/null +++ b/doc/chalk/dialogs-rotateimage.png diff --git a/doc/chalk/dialogs-rotatelayer.png b/doc/chalk/dialogs-rotatelayer.png Binary files differnew file mode 100644 index 00000000..ebbdfc0b --- /dev/null +++ b/doc/chalk/dialogs-rotatelayer.png diff --git a/doc/chalk/dialogs-roundcorners.png b/doc/chalk/dialogs-roundcorners.png Binary files differnew file mode 100644 index 00000000..141ed039 --- /dev/null +++ b/doc/chalk/dialogs-roundcorners.png diff --git a/doc/chalk/dialogs-separateimage.png b/doc/chalk/dialogs-separateimage.png Binary files differnew file mode 100644 index 00000000..9e807a44 --- /dev/null +++ b/doc/chalk/dialogs-separateimage.png diff --git a/doc/chalk/dialogs-shearimage.png b/doc/chalk/dialogs-shearimage.png Binary files differnew file mode 100644 index 00000000..384486b7 --- /dev/null +++ b/doc/chalk/dialogs-shearimage.png diff --git a/doc/chalk/dialogs-shearlayer.png b/doc/chalk/dialogs-shearlayer.png Binary files differnew file mode 100644 index 00000000..bf6903c8 --- /dev/null +++ b/doc/chalk/dialogs-shearlayer.png diff --git a/doc/chalk/dialogs-smalltiles.png b/doc/chalk/dialogs-smalltiles.png Binary files differnew file mode 100644 index 00000000..5581d6a3 --- /dev/null +++ b/doc/chalk/dialogs-smalltiles.png diff --git a/doc/chalk/dialogs-sobel.png b/doc/chalk/dialogs-sobel.png Binary files differnew file mode 100644 index 00000000..b2a8e0e4 --- /dev/null +++ b/doc/chalk/dialogs-sobel.png diff --git a/doc/chalk/dialogs-substrate.png b/doc/chalk/dialogs-substrate.png Binary files differnew file mode 100644 index 00000000..e9fbf0fa --- /dev/null +++ b/doc/chalk/dialogs-substrate.png diff --git a/doc/chalk/dialogs-unsharpmask.png b/doc/chalk/dialogs-unsharpmask.png Binary files differnew file mode 100644 index 00000000..882faf39 --- /dev/null +++ b/doc/chalk/dialogs-unsharpmask.png diff --git a/doc/chalk/dialogs-wave.png b/doc/chalk/dialogs-wave.png Binary files differnew file mode 100644 index 00000000..ab1559be --- /dev/null +++ b/doc/chalk/dialogs-wave.png diff --git a/doc/chalk/dialogs-waveletnoise.png b/doc/chalk/dialogs-waveletnoise.png Binary files differnew file mode 100644 index 00000000..d126eff5 --- /dev/null +++ b/doc/chalk/dialogs-waveletnoise.png diff --git a/doc/chalk/faq.docbook b/doc/chalk/faq.docbook new file mode 100644 index 00000000..1e4f4fe4 --- /dev/null +++ b/doc/chalk/faq.docbook @@ -0,0 +1,51 @@ +<chapter id="faq"> +<title>Questions and Answers</title> + +<para> +Sometimes, stuff does not work as one would like. &chalk; can crash — not all +that often, these days, but still. So you might need some help. The first thing +to do is trying to determine what was going on, exactly. Try to reproduce the +problem and write down what you did before the problem occurred. +</para><para> +Then you can create a bug report: go to the <guimenu>Help</guimenu> menu and select +<guimenuitem>Report Bug</guimenuitem>. That way, we know exactly which version of +&chalk; you are using. Please try to make reasonably sure that your problem has +not been reported already! Also, please try to be as complete as possible in +describing your problem. +</para><para> +You can also, if it is just that you cannot figure out how to do something +that you can do using Photoshop (or any other drawing program) using &chalk;, +or if you have some other question, e-mail the &chalk; developers at our +mailing list <email>kimageshop@kde.org</email>, or e-mail the program or +documentation maintainer directly at <email>boud@valdyas.org</email> or +<email>sanderkoning@kde.nl</email>, respectively. +</para> + +<!-- TODO Add a set of Q&As? --> + +&reporting.bugs; +&updating.documentation; + +<!-- <qandaset id="faqlist"> +<qandaentry> +<question> +<para>My Mouse doesn't work. How do I quit &kmyapplication;?</para> +</question> +<answer> +<para>You silly goose! Check out the <link linkend="commands">Commands +Section</link> for the answer.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>Why can't I twiddle my documents?</para> +</question> +<answer> +<para>You can only twiddle your documents if you have the foobar.lib +installed.</para> +</answer> +</qandaentry> +</qandaset> --> + +</chapter> + diff --git a/doc/chalk/index.docbook b/doc/chalk/index.docbook new file mode 100644 index 00000000..faa92a1a --- /dev/null +++ b/doc/chalk/index.docbook @@ -0,0 +1,138 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&chalk;"> + <!ENTITY chalk '<application>chalk</application>'> + <!ENTITY package "koffice"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> + <!ENTITY introduction SYSTEM "introduction.docbook"> + <!ENTITY tutorial SYSTEM "tutorial.docbook"> + <!ENTITY tutorial-starting SYSTEM "tutorial-starting.docbook"> + <!ENTITY tutorial-select-layer SYSTEM "tutorial-select-layer.docbook"> + <!ENTITY tutorial-quick-starts SYSTEM "tutorial-quick-starts.docbook"> + <!ENTITY tutorial-tablet SYSTEM "tutorial-tablet.docbook"> + <!ENTITY images SYSTEM "using-images.docbook"> + <!ENTITY views SYSTEM "using-views.docbook"> + <!ENTITY layers SYSTEM "using-layers.docbook"> + <!ENTITY selections SYSTEM "using-selections.docbook"> + <!ENTITY filters SYSTEM "using-filters.docbook"> + <!ENTITY colorspaces SYSTEM "using-colorspaces.docbook"> + <!ENTITY commands SYSTEM "commands.docbook"> + <!ENTITY commands-toolbars SYSTEM "commands-toolbars.docbook"> + <!ENTITY commands-palettes SYSTEM "commands-palettes.docbook"> + <!ENTITY commands-menus SYSTEM "commands-menus.docbook"> + <!ENTITY commands-dialogs SYSTEM "commands-dialogs.docbook"> + <!ENTITY settings SYSTEM "settings.docbook"> + <!ENTITY developers SYSTEM "developers.docbook"> + <!ENTITY developers-scripting SYSTEM "developers-scripting.docbook"> + <!ENTITY developers-plugins SYSTEM "developers-plugins.docbook"> + <!ENTITY faq SYSTEM "faq.docbook"> + <!ENTITY credits SYSTEM "credits.docbook"> + <!ENTITY installation SYSTEM "installation.docbook"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &chalk; Handbook</title> + +<authorgroup> +<author> +<personname> +<firstname>Boudewijn</firstname> +<surname>Rempt</surname> +</personname> +<email>boud@valdyas.org</email> +</author> +<author> +<personname> +<firstname>Casper</firstname> +<surname>Boemann</surname> +</personname> +<email>cbr@boemann.dk</email> +</author> +<author> +<personname> +<firstname>Cyrille</firstname> +<surname>Berger</surname> +</personname> +<email>cberger@cberger.net</email> +</author> +<author> +<personname> +<firstname>Sander</firstname> +<surname>Koning</surname> +</personname> +<email>sanderkoning@kde.nl</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2005-2006</year> +<holder>Boudewijn Rempt</holder> +<holder>Casper Boemann</holder> +<holder>Cyrille Berger</holder> +<holder>Sander Koning</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation --> + +<date>2006-09-13</date> +<releaseinfo>1.6</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&chalk; is part of the &koffice; package. &chalk; is a photo retouching, image +editing application, but above all, a paint application that will allow you to +create original art on your computer as if you were working with paint and +brushes, pencils, pen and ink — or, at least, it will one day. We are +continually working on extending &chalk; and making it better in every respect. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>koffice</keyword> +<keyword>Chalk</keyword> +<keyword>image manipulation</keyword> +<keyword>graphics</keyword> +<keyword>painting</keyword> +</keywordset> + +</bookinfo> + +&introduction; +&tutorial; +&images; +&views; +&layers; +&selections; +&filters; +&colorspaces; +&commands; +&settings; +&developers; +&faq; +&credits; +&installation; + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +kate: space-indent on; indent-width 2; tab-width 2; indent-mode none; +--> diff --git a/doc/chalk/installation.docbook b/doc/chalk/installation.docbook new file mode 100644 index 00000000..88b94e47 --- /dev/null +++ b/doc/chalk/installation.docbook @@ -0,0 +1,73 @@ +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kapp"> +<title>How to obtain &chalk;</title> + +<!-- This first entity contains boiler plate for applications that are +part of KDE CVS. You should remove it if you are releasing your +application --> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<!-- +List any special requirements for your application here. This should include: +.Libraries or other software that is not included in kdesupport, +kdelibs, or kdebase. +.Hardware requirements like amount of RAM, disk space, graphics card +capabilities, screen resolution, special expansion cards, etc. +.Operating systems the app will run on. If your app is designed only for a +specific OS, (you wrote a graphical LILO configurator for example) put this +information here. +--> + +<para> +&chalk; depends on the following libraries, apart from what &koffice; needs +itself: +</para> +<itemizedlist> +<listitem><para><ulink url="http://www.imagemagick.org/">Image +Magick</ulink> — X11 Image Processing and Display +Package</para></listitem> +<listitem><para><ulink url="http://www.littlecms.com/">Little CMS</ulink> +— A free color management system in 100K</para></listitem> +<listitem><para><ulink +url="http://www.openexr.com/">OpenEXR</ulink></para></listitem> +</itemizedlist> + +<!-- For a list of updates, you may refer to the application web site +or the ChangeLog file, or ... --> +<para> +You can find a list of changes in the <filename>ChangeLog</filename> file or on +<ulink url="http://koffice.org/chalk/">&chalk;'s website</ulink>. +</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +<!-- This entity contains the boilerplate text for standard --> +<!-- compilation instructions. If your application requires any --> +<!-- special handling, remove it, and replace with your own text. --> + +&install.compile.documentation; + +</sect1> + +<!-- +<sect1 id="configuration"> +<title>Configuration</title> + +<para>Don't forget to tell your system to start the <filename>dtd</filename> +dicer-toaster daemon first, or &kmyapplication; won't work !</para> + +</sect1> +--> + +</appendix> + diff --git a/doc/chalk/introduction.docbook b/doc/chalk/introduction.docbook new file mode 100644 index 00000000..9384bcbc --- /dev/null +++ b/doc/chalk/introduction.docbook @@ -0,0 +1,153 @@ +<chapter id="introduction"> +<title>Introduction</title> + +<sect1 id="introduction-chalk"> +<title>What is &chalk;?</title> +<para> +&chalk;, part of &koffice;, can do everything you want with images — or +it will be able to one day. Everything from photo retouching, image editing, +and last but not least creating original art on your computer as if you were +working with real paint and brushes, pencils, pen and ink. Every day +&chalk; becomes a little better, a little more useful. We are working on it, +anyway. We, that is, Adrian, Bart, Boudewijn, Casper, Cyrille, Michael and Sven. +It could be you, too — whether you would like to help with some artwork +for the user interface, cool ideas for the todo, helpful bug reports, usability +reviews or even actual code, you will not be snubbed by us. +</para> +<para> +&chalk; is as much yours as it is ours. It should be fun, innovative, and +experimental — first and foremost a pleasure to use and to hack on. +</para> +</sect1> + +<sect1 id="introduction-keyfeatures"> +<title>Key features</title> + +<para>The most important features &chalk; currently has to offer, are:</para> +<itemizedlist> + +<listitem><para>Plugins: Chalk is extensible through plugins. There are tools, +colorspaces, paint operations, filters and kpart-based user interface plugins. +</para></listitem> + +<listitem><para>Scriptable: &chalk; is scriptable in Python and Ruby using +Kross, the cross language scripting engine that originated in Kexi. The +scripting is compatible with PyQt/KDE and Korundum for adding GUI +items, such as dialog boxes.</para></listitem> + +<listitem><para>Color models: &chalk; uses lcms for a dependable color +workflow using icc profiles for importing, exporting, selecting paint colors, +printing, cutting and pasting. 8, 16, and 32 bit colorspaces are available +(RGB, CMYK, L*a*b*, ...) and colors can be selected from a color wheel, rgb or +grayscale sliders or with a palette.</para></listitem> + +<listitem><para>Editing and viewing: Unlimited undo and redo are available. +You can cut, copy and paste between lagers and images, with conversion through +icc profiles if this is necessary. OpenGL is supported for display. The view +can be made fullscreen and can be split. Rulers are available, the +image can be zoomed, and for maximizing the workspace all palette windows can +be hidden in one go. Also a histogram palette is available.</para></listitem> + +<listitem><para>Images and layers: Layers and entire images can be mirrored, +sheared, rotated and scaled, converted between colorspaces, and layers in +different colorspaces can be merged. An image can be separated into colorspace +channels.</para></listitem> + +<listitem><para>Layers: Layers can be added, removed, grouped, locked, made +(in)visible, and re-ordered. Adjustment layers (layers which perform a filter +function) can be added as well. A layer can be saved as a separate image and +its colorspace can be changed.</para></listitem> + +<listitem><para>Tools: Through the innovative paintOp plugin system, all +painting tools (brush, ellipse, line, etc.) can paint aliased, anti-aliased, +erase, airbrush and more.</para></listitem> + +<listitem><para>Filters: &chalk; can multithread the operation of some +filters. Filters can be previewed in the filter gallery. Available filters +include color adjustment, sharpen or blur, emboss, raindrops, and +more.</para></listitem> + +<listitem><para>Brushes: The GIMP brush shapes can be used, both colored and +grayscale brushes and pipe brushes. Custom brushes can be created, even from +entire layers or images. Colored brushes can also be used as +masks.</para></listitem> + +</itemizedlist> + +<sect2 id="introduction-keyfeatures-colormanagement"> +<title>Color management</title> +<para> +One of the most distinguishing features in &chalk; is its color management. +If you put two screens side to side, you will notice that there is often a lot +of difference in the way they display colors. Even white, especially white, is +often not the same thing at all. On one screen it can be a dirty yellow, on +another screen a sickly bluish. Very seldom is it a creamy milk-white. The same +holds, unfortunately, for scanners, printers and digital cameras. So, if you +want to see the right colors on screen and on paper, being the colors that you +saw when taking your snapshot, you will have to compensate. +</para><para> +&chalk; can do this for you: in &chalk;, a color is (almost) never just a set of +numbers, one for each color channel; it is a set of numbers with information +attached. And that extra information is contained in a profile: your image has a +profile, your scanner has a profile, your camera should have a profile and your +screen has a profile. When passing information from your image to your screen, +the profiles are checked and the correct color is computed. This may cause a +little slowness, now and then, but the result is that you can work with colors, +instead of almost meaningless RGB triplets. +</para><para> +Available colorspaces are: 8 bit/channel RGB, CMYK, grayscale and wet +watercolors, 16 bit/channel RGB, CMYK, grayscale and L*a*b*, <quote>half</quote> +RGB, and 32 bit float RGB (HDR) and LMS. +</para> +</sect2> + +<sect2 id="introduction-keyfeatures-imageformats"> +<title>Image formats</title> +<para> +&chalk; currently supports the following image formats, both for importing and +exporting, apart from its own: PNG, TIFF, JPEG, Dicom, XCF, PSD, GIF, BMP, +XPM, Targa, RGB, and OpenEXR. Additionally, &chalk; can import +ICO files. PSD (the Photoshop file format) is only supported up to version 6, +from version 7 on, the Photoshop file format is closed. +</para><para> +Embedded icc profiles and exif information are preserved on export to +supporting file formats. &chalk;'s native file format stores icc and exif +information. +</para> +</sect2> + +</sect1> + +<sect1 id="introduction-manual"> +<title>About this manual</title> +<para> +We are assuming you have got a good working knowledge of &kde; and of your +operating system. The first chapter will give you a quick tour of &chalk;'s +cool features; the other chapters will expand on that information. +</para> +<note><para> +This manual is not complete. The invitation to join us and help out extends to +the manual, too! +</para></note> +<para> +Should you have any questions, comments or suggestions, please contact the +documentation maintainer at <email>sanderkoning@kde.nl</email>. +</para> +</sect1> + +<sect1 id="introduction-maintainer"> +<title>About the application maintainer</title> +<para> +Hi! I'm Boudewijn Rempt — the current maintainer of &chalk;. I was +educated as a linguist, retrained as a database developer, work as a Java +hacker, study theology and I have always liked to paint and sketch a little. +Conspiciously absent in my life have been two important things for a developer +of an image app: mathematics and experience with graphic design. That means that +I am probably not the best person to explain the niceties of using an image +editor or a paint application to you. If you catch me in an error, please don't +hesitate to mail me: <email>boud@valdyas.org</email>. +</para> +</sect1> + +</chapter> + diff --git a/doc/chalk/mainscreen.png b/doc/chalk/mainscreen.png Binary files differnew file mode 100644 index 00000000..cce13569 --- /dev/null +++ b/doc/chalk/mainscreen.png diff --git a/doc/chalk/mountains-burn.png b/doc/chalk/mountains-burn.png Binary files differnew file mode 100644 index 00000000..812c89d2 --- /dev/null +++ b/doc/chalk/mountains-burn.png diff --git a/doc/chalk/mountains-color.png b/doc/chalk/mountains-color.png Binary files differnew file mode 100644 index 00000000..aa34bece --- /dev/null +++ b/doc/chalk/mountains-color.png diff --git a/doc/chalk/mountains-darken.png b/doc/chalk/mountains-darken.png Binary files differnew file mode 100644 index 00000000..3b1ba616 --- /dev/null +++ b/doc/chalk/mountains-darken.png diff --git a/doc/chalk/mountains-divide.png b/doc/chalk/mountains-divide.png Binary files differnew file mode 100644 index 00000000..b2778f65 --- /dev/null +++ b/doc/chalk/mountains-divide.png diff --git a/doc/chalk/mountains-dodge.png b/doc/chalk/mountains-dodge.png Binary files differnew file mode 100644 index 00000000..47f198a9 --- /dev/null +++ b/doc/chalk/mountains-dodge.png diff --git a/doc/chalk/mountains-hue.png b/doc/chalk/mountains-hue.png Binary files differnew file mode 100644 index 00000000..09adb913 --- /dev/null +++ b/doc/chalk/mountains-hue.png diff --git a/doc/chalk/mountains-lighten.png b/doc/chalk/mountains-lighten.png Binary files differnew file mode 100644 index 00000000..8149ef33 --- /dev/null +++ b/doc/chalk/mountains-lighten.png diff --git a/doc/chalk/mountains-multiply.png b/doc/chalk/mountains-multiply.png Binary files differnew file mode 100644 index 00000000..a8769394 --- /dev/null +++ b/doc/chalk/mountains-multiply.png diff --git a/doc/chalk/mountains-normal.png b/doc/chalk/mountains-normal.png Binary files differnew file mode 100644 index 00000000..675eb53b --- /dev/null +++ b/doc/chalk/mountains-normal.png diff --git a/doc/chalk/mountains-original.png b/doc/chalk/mountains-original.png Binary files differnew file mode 100644 index 00000000..1927e618 --- /dev/null +++ b/doc/chalk/mountains-original.png diff --git a/doc/chalk/mountains-overlay.png b/doc/chalk/mountains-overlay.png Binary files differnew file mode 100644 index 00000000..4351c1b6 --- /dev/null +++ b/doc/chalk/mountains-overlay.png diff --git a/doc/chalk/mountains-saturation.png b/doc/chalk/mountains-saturation.png Binary files differnew file mode 100644 index 00000000..2893ed9e --- /dev/null +++ b/doc/chalk/mountains-saturation.png diff --git a/doc/chalk/mountains-screen.png b/doc/chalk/mountains-screen.png Binary files differnew file mode 100644 index 00000000..4d0f9223 --- /dev/null +++ b/doc/chalk/mountains-screen.png diff --git a/doc/chalk/mountains-value.png b/doc/chalk/mountains-value.png Binary files differnew file mode 100644 index 00000000..29714b93 --- /dev/null +++ b/doc/chalk/mountains-value.png diff --git a/doc/chalk/mountains.png b/doc/chalk/mountains.png Binary files differnew file mode 100644 index 00000000..78c9ca86 --- /dev/null +++ b/doc/chalk/mountains.png diff --git a/doc/chalk/newimage.png b/doc/chalk/newimage.png Binary files differnew file mode 100644 index 00000000..210f0912 --- /dev/null +++ b/doc/chalk/newimage.png diff --git a/doc/chalk/palettes-colors-gray.png b/doc/chalk/palettes-colors-gray.png Binary files differnew file mode 100644 index 00000000..23bd973a --- /dev/null +++ b/doc/chalk/palettes-colors-gray.png diff --git a/doc/chalk/palettes-colors-hsv.png b/doc/chalk/palettes-colors-hsv.png Binary files differnew file mode 100644 index 00000000..2ff42357 --- /dev/null +++ b/doc/chalk/palettes-colors-hsv.png diff --git a/doc/chalk/palettes-colors-palettes.png b/doc/chalk/palettes-colors-palettes.png Binary files differnew file mode 100644 index 00000000..4f0b379a --- /dev/null +++ b/doc/chalk/palettes-colors-palettes.png diff --git a/doc/chalk/palettes-colors-rgb.png b/doc/chalk/palettes-colors-rgb.png Binary files differnew file mode 100644 index 00000000..bbf64883 --- /dev/null +++ b/doc/chalk/palettes-colors-rgb.png diff --git a/doc/chalk/palettes-colors-watercolors.png b/doc/chalk/palettes-colors-watercolors.png Binary files differnew file mode 100644 index 00000000..63fae210 --- /dev/null +++ b/doc/chalk/palettes-colors-watercolors.png diff --git a/doc/chalk/palettes-controlbox-bezier.png b/doc/chalk/palettes-controlbox-bezier.png Binary files differnew file mode 100644 index 00000000..4e42caee --- /dev/null +++ b/doc/chalk/palettes-controlbox-bezier.png diff --git a/doc/chalk/palettes-controlbox-brush.png b/doc/chalk/palettes-controlbox-brush.png Binary files differnew file mode 100644 index 00000000..c3c3ed08 --- /dev/null +++ b/doc/chalk/palettes-controlbox-brush.png diff --git a/doc/chalk/palettes-controlbox-colorpicker.png b/doc/chalk/palettes-controlbox-colorpicker.png Binary files differnew file mode 100644 index 00000000..7733c18d --- /dev/null +++ b/doc/chalk/palettes-controlbox-colorpicker.png diff --git a/doc/chalk/palettes-controlbox-contiguousfill.png b/doc/chalk/palettes-controlbox-contiguousfill.png Binary files differnew file mode 100644 index 00000000..57777af9 --- /dev/null +++ b/doc/chalk/palettes-controlbox-contiguousfill.png diff --git a/doc/chalk/palettes-controlbox-crop.png b/doc/chalk/palettes-controlbox-crop.png Binary files differnew file mode 100644 index 00000000..79091134 --- /dev/null +++ b/doc/chalk/palettes-controlbox-crop.png diff --git a/doc/chalk/palettes-controlbox-duplicate.png b/doc/chalk/palettes-controlbox-duplicate.png Binary files differnew file mode 100644 index 00000000..74ec92e4 --- /dev/null +++ b/doc/chalk/palettes-controlbox-duplicate.png diff --git a/doc/chalk/palettes-controlbox-ellipse.png b/doc/chalk/palettes-controlbox-ellipse.png Binary files differnew file mode 100644 index 00000000..14ab3733 --- /dev/null +++ b/doc/chalk/palettes-controlbox-ellipse.png diff --git a/doc/chalk/palettes-controlbox-fill.png b/doc/chalk/palettes-controlbox-fill.png Binary files differnew file mode 100644 index 00000000..1120d06b --- /dev/null +++ b/doc/chalk/palettes-controlbox-fill.png diff --git a/doc/chalk/palettes-controlbox-gradient.png b/doc/chalk/palettes-controlbox-gradient.png Binary files differnew file mode 100644 index 00000000..857824c3 --- /dev/null +++ b/doc/chalk/palettes-controlbox-gradient.png diff --git a/doc/chalk/palettes-controlbox-histogram.png b/doc/chalk/palettes-controlbox-histogram.png Binary files differnew file mode 100644 index 00000000..1dccaecd --- /dev/null +++ b/doc/chalk/palettes-controlbox-histogram.png diff --git a/doc/chalk/palettes-controlbox-line.png b/doc/chalk/palettes-controlbox-line.png Binary files differnew file mode 100644 index 00000000..c0671204 --- /dev/null +++ b/doc/chalk/palettes-controlbox-line.png diff --git a/doc/chalk/palettes-controlbox-overview.png b/doc/chalk/palettes-controlbox-overview.png Binary files differnew file mode 100644 index 00000000..483e3ec3 --- /dev/null +++ b/doc/chalk/palettes-controlbox-overview.png diff --git a/doc/chalk/palettes-controlbox-paintwithfilters.png b/doc/chalk/palettes-controlbox-paintwithfilters.png Binary files differnew file mode 100644 index 00000000..2a0ca8ef --- /dev/null +++ b/doc/chalk/palettes-controlbox-paintwithfilters.png diff --git a/doc/chalk/palettes-controlbox-polygon.png b/doc/chalk/palettes-controlbox-polygon.png Binary files differnew file mode 100644 index 00000000..47cfbbc1 --- /dev/null +++ b/doc/chalk/palettes-controlbox-polygon.png diff --git a/doc/chalk/palettes-controlbox-polyline.png b/doc/chalk/palettes-controlbox-polyline.png Binary files differnew file mode 100644 index 00000000..c0671204 --- /dev/null +++ b/doc/chalk/palettes-controlbox-polyline.png diff --git a/doc/chalk/palettes-controlbox-rectangle.png b/doc/chalk/palettes-controlbox-rectangle.png Binary files differnew file mode 100644 index 00000000..14ab3733 --- /dev/null +++ b/doc/chalk/palettes-controlbox-rectangle.png diff --git a/doc/chalk/palettes-controlbox-select.png b/doc/chalk/palettes-controlbox-select.png Binary files differnew file mode 100644 index 00000000..0d5e0010 --- /dev/null +++ b/doc/chalk/palettes-controlbox-select.png diff --git a/doc/chalk/palettes-controlbox-selectcontiguous.png b/doc/chalk/palettes-controlbox-selectcontiguous.png Binary files differnew file mode 100644 index 00000000..591c8096 --- /dev/null +++ b/doc/chalk/palettes-controlbox-selectcontiguous.png diff --git a/doc/chalk/palettes-controlbox-selectmagnetic.png b/doc/chalk/palettes-controlbox-selectmagnetic.png Binary files differnew file mode 100644 index 00000000..4fb3ac1b --- /dev/null +++ b/doc/chalk/palettes-controlbox-selectmagnetic.png diff --git a/doc/chalk/palettes-controlbox-selectsimilar.png b/doc/chalk/palettes-controlbox-selectsimilar.png Binary files differnew file mode 100644 index 00000000..8eb14a9e --- /dev/null +++ b/doc/chalk/palettes-controlbox-selectsimilar.png diff --git a/doc/chalk/palettes-controlbox-star.png b/doc/chalk/palettes-controlbox-star.png Binary files differnew file mode 100644 index 00000000..a14f709e --- /dev/null +++ b/doc/chalk/palettes-controlbox-star.png diff --git a/doc/chalk/palettes-controlbox-text.png b/doc/chalk/palettes-controlbox-text.png Binary files differnew file mode 100644 index 00000000..98691950 --- /dev/null +++ b/doc/chalk/palettes-controlbox-text.png diff --git a/doc/chalk/palettes-controlbox-transform.png b/doc/chalk/palettes-controlbox-transform.png Binary files differnew file mode 100644 index 00000000..19ff42ba --- /dev/null +++ b/doc/chalk/palettes-controlbox-transform.png diff --git a/doc/chalk/palettes-layers-layers.png b/doc/chalk/palettes-layers-layers.png Binary files differnew file mode 100644 index 00000000..06e20ff6 --- /dev/null +++ b/doc/chalk/palettes-layers-layers.png diff --git a/doc/chalk/palettes-layers-scriptsmanager.png b/doc/chalk/palettes-layers-scriptsmanager.png Binary files differnew file mode 100644 index 00000000..07cea20e --- /dev/null +++ b/doc/chalk/palettes-layers-scriptsmanager.png diff --git a/doc/chalk/preferences-color.png b/doc/chalk/preferences-color.png Binary files differnew file mode 100644 index 00000000..77cc9b86 --- /dev/null +++ b/doc/chalk/preferences-color.png diff --git a/doc/chalk/preferences-display.png b/doc/chalk/preferences-display.png Binary files differnew file mode 100644 index 00000000..7c4dfa36 --- /dev/null +++ b/doc/chalk/preferences-display.png diff --git a/doc/chalk/preferences-general.png b/doc/chalk/preferences-general.png Binary files differnew file mode 100644 index 00000000..38232182 --- /dev/null +++ b/doc/chalk/preferences-general.png diff --git a/doc/chalk/preferences-grid.png b/doc/chalk/preferences-grid.png Binary files differnew file mode 100644 index 00000000..48a9376a --- /dev/null +++ b/doc/chalk/preferences-grid.png diff --git a/doc/chalk/preferences-performance.png b/doc/chalk/preferences-performance.png Binary files differnew file mode 100644 index 00000000..045f3585 --- /dev/null +++ b/doc/chalk/preferences-performance.png diff --git a/doc/chalk/preferences-sidebar.png b/doc/chalk/preferences-sidebar.png Binary files differnew file mode 100644 index 00000000..cc72e177 --- /dev/null +++ b/doc/chalk/preferences-sidebar.png diff --git a/doc/chalk/preferences-tablet.png b/doc/chalk/preferences-tablet.png Binary files differnew file mode 100644 index 00000000..366a46d4 --- /dev/null +++ b/doc/chalk/preferences-tablet.png diff --git a/doc/chalk/settings.docbook b/doc/chalk/settings.docbook new file mode 100644 index 00000000..01fecf88 --- /dev/null +++ b/doc/chalk/settings.docbook @@ -0,0 +1,229 @@ +<chapter id="settings"> + +<title>Settings</title> + +<para>This chapter describes the various settings that affect the way &chalk; +functions and looks.</para> + +<sect1 id="settings-preferences"> +<title>The <guilabel>Preferences</guilabel> dialog</title> + +<para> +A number of options to configure &chalk; are available via the +<guilabel>Preferences</guilabel> dialog, which is available via +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&chalk;...</guimenuitem></menuchoice>. The dialog is divided into several +sections, which you can open via the sidebar at the left, shown below. +</para> + +<para> +<screenshot> +<screeninfo>The available <guilabel>Preferences</guilabel> sections</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-sidebar.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The available <guilabel>Preferences</guilabel> sections</phrase> +</textobject> +<caption><para>The available <guilabel>Preferences</guilabel> sections</para></caption> +</mediaobject> +</screenshot> +</para> + +<sect2 id="settings-preferences-general"> +<title>The <guilabel>General</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>General</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-general.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>General</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>General</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This section offers three options. First of all, the setting in the +<guilabel>Cursor shape:</guilabel> dropdown box determines what the drawing +cursor looks like. You can choose between a cursor resembling the actual tool +you are working with, a normal cursor, a crosshair, and a brush-shaped cursor. +Then you can select the <guilabel>Palette Behavior</guilabel>. You can set +here when palettes may be <quote>docked</quote> (set aside at a window +border): always (<guilabel>Allow docking</guilabel>), never +(<guilabel>Allow only floating</guilabel>), or when there is enough space +(<guilabel>Allow docking only on large screens</guilabel>). The last option is +<guilabel>Palette font size:</guilabel> which determines the text size used in +the palettes. Set this to a larger value if you have trouble reading the text, +with the side effect that the palettes will take more space. +</para> + +</sect2> + +<sect2 id="settings-preferences-display"> +<title>The <guilabel>Display</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Display</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-display.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Display</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>Display</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This section contains just one option. If your graphics card and driver have +OpenGL support, you can enable it here to make drawing faster (the +processor of yor graphics card will take over part of the calculations). Be +warned, though: there are a few cases where enabling OpenGL is known to +introduce erratic behavior. +</para> + +</sect2> + +<sect2 id="settings-preferences-colormanagement"> +<title>The <guilabel>Color Management</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Color Management</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-color.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Color Management</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>Color Management</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Here you can set various options related to colorspaces in rendering, editing +and printing of images. The topmost option can be used to set the default +color model for creating new images (useful if you usually want to create CMYK +images, for instance). Use the <guilabel>Display</guilabel> options to let +&chalk; know what color profile your monitor uses, and how rendering should be +done. Under <guilabel>Printing</guilabel>, you can set the color model and +profile for your printer. The next option determines what &chalk; should do +when you paste an image into it that was copied from another application. If +<guilabel>Use Blackpoint compensation</guilabel> is checked, whenever a +colorspace conversion is needed, the black points of the source and +destination colorspaces are matched. +</para> + +</sect2> + +<sect2 id="settings-preferences-performance"> +<title>The <guilabel>Performance</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Performance</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-performance.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Performance</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>Performance</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Two options are available here. The <guilabel>Maximum number of tiles kept in +memory</guilabel> setting indicates how many tiles (image subparts) &chalk; +will keep in memory. The default setting should be reasonable, if you are low +or very high on memory, you may want to decrease or increase this option, +respectively. The <guilabel>Swappiness:</guilabel> option determines how eager +&chalk; will be to swap to disk. +</para> + +</sect2> + +<sect2 id="settings-preferences-tablet"> +<title>The <guilabel>Tablet</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Tablet</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-tablet.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Tablet</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>Tablet</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +If you have a tablet device attached, you can enable it and set its pressure +sensitivity in this section. +</para><para> +You need to activate the tablet devices you want to use with &chalk;. There +are three supported devices: the cursor, the eraser and the stylus. You can +activate them using the tablet sections. Only use the configuration options of +a device if you use a non-Wacom tablet, and if the behavior of the tablet is +unexpected, like moving when you press on the tablet for instance. In this +situation, you can use the dialog to make sure you have a correct interaction: +values (position, pressure, tilt...) are sent from the tablet to the computer +in a given order, it might happen that some tablets do not use the default +order. You can set this in the configuration options of a device. +</para> + +</sect2> + +<sect2 id="settings-preferences-grid"> +<title>The <guilabel>Grid</guilabel> section</title> + +<para> +<screenshot> +<screeninfo>The <guilabel>Grid</guilabel> section</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="preferences-grid.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Grid</guilabel> section</phrase> +</textobject> +<caption><para>The <guilabel>Grid</guilabel> section</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +In this section, you can fine-tune &chalk;'s grid. The line styles for the +grid can be set in the <guilabel>Styles</guilabel> option set. +<guilabel>Colors</guilabel> allows you to choose the line colors for the grid. +The horizontal and vertical spacing between the main lines can be set under +<guilabel>Spacing</guilabel>, as well as the amount of subdivisions (in how +many smaller parts a grid section is subdivided). Furthermore you can set the +<guilabel>Offset</guilabel>: usually the grid is painted starting at the top +left corner, if you want the first main grid lines not to start there, you can +enter an offset (displacement) here. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/chalk/tool-bezier-example.png b/doc/chalk/tool-bezier-example.png Binary files differnew file mode 100644 index 00000000..111ac2fc --- /dev/null +++ b/doc/chalk/tool-bezier-example.png diff --git a/doc/chalk/tool-bezier-example2.png b/doc/chalk/tool-bezier-example2.png Binary files differnew file mode 100644 index 00000000..607ef541 --- /dev/null +++ b/doc/chalk/tool-bezier-example2.png diff --git a/doc/chalk/tool-bezier-example3.png b/doc/chalk/tool-bezier-example3.png Binary files differnew file mode 100644 index 00000000..7bbc917e --- /dev/null +++ b/doc/chalk/tool-bezier-example3.png diff --git a/doc/chalk/tool-bezier.png b/doc/chalk/tool-bezier.png Binary files differnew file mode 100644 index 00000000..357cfa80 --- /dev/null +++ b/doc/chalk/tool-bezier.png diff --git a/doc/chalk/tool-brush.png b/doc/chalk/tool-brush.png Binary files differnew file mode 100644 index 00000000..9b6c79c3 --- /dev/null +++ b/doc/chalk/tool-brush.png diff --git a/doc/chalk/tool-colorpicker.png b/doc/chalk/tool-colorpicker.png Binary files differnew file mode 100644 index 00000000..daf5a94e --- /dev/null +++ b/doc/chalk/tool-colorpicker.png diff --git a/doc/chalk/tool-contiguousfill.png b/doc/chalk/tool-contiguousfill.png Binary files differnew file mode 100644 index 00000000..ddd1b6b1 --- /dev/null +++ b/doc/chalk/tool-contiguousfill.png diff --git a/doc/chalk/tool-crop.png b/doc/chalk/tool-crop.png Binary files differnew file mode 100644 index 00000000..829727dd --- /dev/null +++ b/doc/chalk/tool-crop.png diff --git a/doc/chalk/tool-duplicate.png b/doc/chalk/tool-duplicate.png Binary files differnew file mode 100644 index 00000000..968e7961 --- /dev/null +++ b/doc/chalk/tool-duplicate.png diff --git a/doc/chalk/tool-ellipse.png b/doc/chalk/tool-ellipse.png Binary files differnew file mode 100644 index 00000000..ba945656 --- /dev/null +++ b/doc/chalk/tool-ellipse.png diff --git a/doc/chalk/tool-eraseselection.png b/doc/chalk/tool-eraseselection.png Binary files differnew file mode 100644 index 00000000..f26b0f62 --- /dev/null +++ b/doc/chalk/tool-eraseselection.png diff --git a/doc/chalk/tool-gradient.png b/doc/chalk/tool-gradient.png Binary files differnew file mode 100644 index 00000000..22239a52 --- /dev/null +++ b/doc/chalk/tool-gradient.png diff --git a/doc/chalk/tool-line.png b/doc/chalk/tool-line.png Binary files differnew file mode 100644 index 00000000..3efd3608 --- /dev/null +++ b/doc/chalk/tool-line.png diff --git a/doc/chalk/tool-move.png b/doc/chalk/tool-move.png Binary files differnew file mode 100644 index 00000000..7a588bbe --- /dev/null +++ b/doc/chalk/tool-move.png diff --git a/doc/chalk/tool-paintselection.png b/doc/chalk/tool-paintselection.png Binary files differnew file mode 100644 index 00000000..654bfbd9 --- /dev/null +++ b/doc/chalk/tool-paintselection.png diff --git a/doc/chalk/tool-paintwithfilters-example.png b/doc/chalk/tool-paintwithfilters-example.png Binary files differnew file mode 100644 index 00000000..7e10f5d1 --- /dev/null +++ b/doc/chalk/tool-paintwithfilters-example.png diff --git a/doc/chalk/tool-paintwithfilters.png b/doc/chalk/tool-paintwithfilters.png Binary files differnew file mode 100644 index 00000000..9eb5a824 --- /dev/null +++ b/doc/chalk/tool-paintwithfilters.png diff --git a/doc/chalk/tool-pan.png b/doc/chalk/tool-pan.png Binary files differnew file mode 100644 index 00000000..63adf1c5 --- /dev/null +++ b/doc/chalk/tool-pan.png diff --git a/doc/chalk/tool-perspectivegrid.png b/doc/chalk/tool-perspectivegrid.png Binary files differnew file mode 100644 index 00000000..30d671fe --- /dev/null +++ b/doc/chalk/tool-perspectivegrid.png diff --git a/doc/chalk/tool-perspectivetransform.png b/doc/chalk/tool-perspectivetransform.png Binary files differnew file mode 100644 index 00000000..611947f6 --- /dev/null +++ b/doc/chalk/tool-perspectivetransform.png diff --git a/doc/chalk/tool-polygon.png b/doc/chalk/tool-polygon.png Binary files differnew file mode 100644 index 00000000..b4fabae1 --- /dev/null +++ b/doc/chalk/tool-polygon.png diff --git a/doc/chalk/tool-polyline.png b/doc/chalk/tool-polyline.png Binary files differnew file mode 100644 index 00000000..f59b09bf --- /dev/null +++ b/doc/chalk/tool-polyline.png diff --git a/doc/chalk/tool-rectangle.png b/doc/chalk/tool-rectangle.png Binary files differnew file mode 100644 index 00000000..83ddd599 --- /dev/null +++ b/doc/chalk/tool-rectangle.png diff --git a/doc/chalk/tool-selectbezier.png b/doc/chalk/tool-selectbezier.png Binary files differnew file mode 100644 index 00000000..33690580 --- /dev/null +++ b/doc/chalk/tool-selectbezier.png diff --git a/doc/chalk/tool-selectcontiguous.png b/doc/chalk/tool-selectcontiguous.png Binary files differnew file mode 100644 index 00000000..acf04cd3 --- /dev/null +++ b/doc/chalk/tool-selectcontiguous.png diff --git a/doc/chalk/tool-selectelliptical.png b/doc/chalk/tool-selectelliptical.png Binary files differnew file mode 100644 index 00000000..e7cba67f --- /dev/null +++ b/doc/chalk/tool-selectelliptical.png diff --git a/doc/chalk/tool-selectmagnetic.png b/doc/chalk/tool-selectmagnetic.png Binary files differnew file mode 100644 index 00000000..63489bcd --- /dev/null +++ b/doc/chalk/tool-selectmagnetic.png diff --git a/doc/chalk/tool-selectoutline.png b/doc/chalk/tool-selectoutline.png Binary files differnew file mode 100644 index 00000000..5646f6b1 --- /dev/null +++ b/doc/chalk/tool-selectoutline.png diff --git a/doc/chalk/tool-selectpolygonal.png b/doc/chalk/tool-selectpolygonal.png Binary files differnew file mode 100644 index 00000000..dded2a46 --- /dev/null +++ b/doc/chalk/tool-selectpolygonal.png diff --git a/doc/chalk/tool-selectrectangular.png b/doc/chalk/tool-selectrectangular.png Binary files differnew file mode 100644 index 00000000..217f6b5d --- /dev/null +++ b/doc/chalk/tool-selectrectangular.png diff --git a/doc/chalk/tool-selectsimilar.png b/doc/chalk/tool-selectsimilar.png Binary files differnew file mode 100644 index 00000000..4177294b --- /dev/null +++ b/doc/chalk/tool-selectsimilar.png diff --git a/doc/chalk/tool-star.png b/doc/chalk/tool-star.png Binary files differnew file mode 100644 index 00000000..72a68a21 --- /dev/null +++ b/doc/chalk/tool-star.png diff --git a/doc/chalk/tool-text.png b/doc/chalk/tool-text.png Binary files differnew file mode 100644 index 00000000..b1ac269d --- /dev/null +++ b/doc/chalk/tool-text.png diff --git a/doc/chalk/tool-transform.png b/doc/chalk/tool-transform.png Binary files differnew file mode 100644 index 00000000..c00eeebb --- /dev/null +++ b/doc/chalk/tool-transform.png diff --git a/doc/chalk/tool-zoom.png b/doc/chalk/tool-zoom.png Binary files differnew file mode 100644 index 00000000..99eb7496 --- /dev/null +++ b/doc/chalk/tool-zoom.png diff --git a/doc/chalk/toolbar-brushes-brushshapes-autobrush.png b/doc/chalk/toolbar-brushes-brushshapes-autobrush.png Binary files differnew file mode 100644 index 00000000..c39cacad --- /dev/null +++ b/doc/chalk/toolbar-brushes-brushshapes-autobrush.png diff --git a/doc/chalk/toolbar-brushes-brushshapes-custombrush.png b/doc/chalk/toolbar-brushes-brushshapes-custombrush.png Binary files differnew file mode 100644 index 00000000..bd57d6e9 --- /dev/null +++ b/doc/chalk/toolbar-brushes-brushshapes-custombrush.png diff --git a/doc/chalk/toolbar-brushes-brushshapes-predefined.png b/doc/chalk/toolbar-brushes-brushshapes-predefined.png Binary files differnew file mode 100644 index 00000000..677d0e27 --- /dev/null +++ b/doc/chalk/toolbar-brushes-brushshapes-predefined.png diff --git a/doc/chalk/toolbar-brushes-gradients.png b/doc/chalk/toolbar-brushes-gradients.png Binary files differnew file mode 100644 index 00000000..89ae348e --- /dev/null +++ b/doc/chalk/toolbar-brushes-gradients.png diff --git a/doc/chalk/toolbar-brushes-patterns-custompattern.png b/doc/chalk/toolbar-brushes-patterns-custompattern.png Binary files differnew file mode 100644 index 00000000..29d0fe1c --- /dev/null +++ b/doc/chalk/toolbar-brushes-patterns-custompattern.png diff --git a/doc/chalk/toolbar-brushes-patterns.png b/doc/chalk/toolbar-brushes-patterns.png Binary files differnew file mode 100644 index 00000000..367fa3ef --- /dev/null +++ b/doc/chalk/toolbar-brushes-patterns.png diff --git a/doc/chalk/toolbar-brushesandstuff.png b/doc/chalk/toolbar-brushesandstuff.png Binary files differnew file mode 100644 index 00000000..e37d1a83 --- /dev/null +++ b/doc/chalk/toolbar-brushesandstuff.png diff --git a/doc/chalk/toolbar-chalk.png b/doc/chalk/toolbar-chalk.png Binary files differnew file mode 100644 index 00000000..e39c6777 --- /dev/null +++ b/doc/chalk/toolbar-chalk.png diff --git a/doc/chalk/toolbar-edit.png b/doc/chalk/toolbar-edit.png Binary files differnew file mode 100644 index 00000000..c65c1969 --- /dev/null +++ b/doc/chalk/toolbar-edit.png diff --git a/doc/chalk/toolbar-file.png b/doc/chalk/toolbar-file.png Binary files differnew file mode 100644 index 00000000..5b8293bd --- /dev/null +++ b/doc/chalk/toolbar-file.png diff --git a/doc/chalk/toolbar-navigation.png b/doc/chalk/toolbar-navigation.png Binary files differnew file mode 100644 index 00000000..6fd40b6a --- /dev/null +++ b/doc/chalk/toolbar-navigation.png diff --git a/doc/chalk/toolbar-transformationtools.png b/doc/chalk/toolbar-transformationtools.png Binary files differnew file mode 100644 index 00000000..07e41208 --- /dev/null +++ b/doc/chalk/toolbar-transformationtools.png diff --git a/doc/chalk/toolbars-button-zoomin.png b/doc/chalk/toolbars-button-zoomin.png Binary files differnew file mode 100644 index 00000000..896f1c12 --- /dev/null +++ b/doc/chalk/toolbars-button-zoomin.png diff --git a/doc/chalk/toolbars-button-zoomout.png b/doc/chalk/toolbars-button-zoomout.png Binary files differnew file mode 100644 index 00000000..124ab6fb --- /dev/null +++ b/doc/chalk/toolbars-button-zoomout.png diff --git a/doc/chalk/tutorial-quick-starts.docbook b/doc/chalk/tutorial-quick-starts.docbook new file mode 100644 index 00000000..b22d3250 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts.docbook @@ -0,0 +1,183 @@ +<sect1 id="tutorial-quickstarts"> +<title>Quick start guides</title> +<sect2 id="tutorial-quickstarts-cropimage"> +<title>Crop an area and save it</title> + +<para>Aim: from a picture, crop an area and save that area in a new file</para> + +<para>Open &chalk; with the original picture.</para> + +<screenshot> +<screeninfo>The original picture</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts1.png" format="PNG"/> +</imageobject> +<textobject><phrase>The original picture</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Select the <guiicon>Select Rectangular</guiicon> tool in the +&chalk; toolbar.</para> + +<screenshot> +<screeninfo>The Select a rectangular area tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts2.png" format="PNG"/> +</imageobject> +<textobject><phrase>The Select a rectangular area tool</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Select the area you want to make a new picture with. &chalk; makes the +outside area grey.</para> + +<screenshot> +<screeninfo>The selected area</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts3.png" format="PNG"/> +</imageobject> +<textobject><phrase>The selected area</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Then use the +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Copy</guimenuitem></menuchoice> +menu item or <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> to +copy the selected area.</para> + +<para>Click again on the <guimenu>Edit</guimenu> menu.</para> +<para>Use the <guimenuitem>Paste into new image</guimenuitem> item.</para> + +<screenshot> +<screeninfo>The <guimenu>Edit</guimenu> menu</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts4.png" format="PNG"/> +</imageobject> +<textobject><phrase>The <guimenu>Edit</guimenu> menu</phrase></textobject> +</mediaobject> +</screenshot> + +<para>&chalk; opens a new window with the selected area as new image.</para> + +<screenshot> +<screeninfo>The new image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts5.png" format="PNG"/> +</imageobject> +<textobject><phrase>The new image</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Save the new image.</para> + +</sect2> +<sect2 id="tutorial-quickstarts-drawrectangle"> +<title>Draw a rectangle on your picture</title> + +<para>Aim: draw a coloured rectangle on your picture</para> + +<para>Open &chalk; with the original picture. My picture consists of a view of +a toolbar in which I want to point an icon by putting a red rectangle around +it.</para> + +<screenshot> +<screeninfo>The original picture</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts6.png" format="PNG"/> +</imageobject> +<textobject><phrase>The original picture</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Enable the <guilabel>Brushes and Stuff</guilabel> toolbar using +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Toolbars</guimenuitem></menuchoice> +menu.</para> +<para>Also make sure the palettes are viewed. If not, use the +<menuchoice><guimenu>View</guimenu><guimenuitem>Palettes</guimenuitem></menuchoice> +menu.</para> + +<screenshot> +<screeninfo>&chalk; view</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts7.png" format="PNG"/> +</imageobject> +<textobject><phrase>&chalk; view</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Click on the <guiicon>Brush Shapes</guiicon> icon in the +<guilabel>Brushes and Stuff</guilabel> toolbar.</para> + +<screenshot> +<screeninfo>The <guiicon>Brush Shapes</guiicon> icon</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts8.png" format="PNG"/> +</imageobject> +<textobject><phrase>The <guiicon>Brush Shapes</guiicon> icon</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Select which brush shape you want to use among the predefined +brushes.</para> + +<screenshot> +<screeninfo>Selecting a brush shape</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts9.png" format="PNG"/> +</imageobject> +<textobject><phrase>Selecting a brush shape</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Select the drawing shape on the &chalk; toolbar. I choose a +rectangle.</para> + +<screenshot> +<screeninfo>Selecting the <guiicon>Rectangle</guiicon> icon</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts10.png" format="PNG"/> +</imageobject> +<textobject><phrase>Selecting the <guiicon>Rectangle</guiicon> icon</phrase></textobject> +</mediaobject> +</screenshot> + +<para>In the <guilabel>Colors</guilabel> palette, select the color you want by clicking on one of the +tabs and then choosing the color.</para> + +<screenshot> +<screeninfo>Choosing the color</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts11.png" format="PNG"/> +</imageobject> +<textobject><phrase>Choosing the color</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Finally draw your shape on your picture and save the new picture!</para> + +<screenshot> +<screeninfo>Drawing</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-quick-starts12.png" format="PNG"/> +</imageobject> +<textobject><phrase>Drawing</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Thanks go to Anne-Marie Mahfouf for providing this tutorial.</para> + +</sect2> + +</sect1> diff --git a/doc/chalk/tutorial-quick-starts1.png b/doc/chalk/tutorial-quick-starts1.png Binary files differnew file mode 100644 index 00000000..562e1595 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts1.png diff --git a/doc/chalk/tutorial-quick-starts10.png b/doc/chalk/tutorial-quick-starts10.png Binary files differnew file mode 100644 index 00000000..fc76f188 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts10.png diff --git a/doc/chalk/tutorial-quick-starts11.png b/doc/chalk/tutorial-quick-starts11.png Binary files differnew file mode 100644 index 00000000..7cd5f601 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts11.png diff --git a/doc/chalk/tutorial-quick-starts12.png b/doc/chalk/tutorial-quick-starts12.png Binary files differnew file mode 100644 index 00000000..a74ea54f --- /dev/null +++ b/doc/chalk/tutorial-quick-starts12.png diff --git a/doc/chalk/tutorial-quick-starts2.png b/doc/chalk/tutorial-quick-starts2.png Binary files differnew file mode 100644 index 00000000..fe54bf6a --- /dev/null +++ b/doc/chalk/tutorial-quick-starts2.png diff --git a/doc/chalk/tutorial-quick-starts3.png b/doc/chalk/tutorial-quick-starts3.png Binary files differnew file mode 100644 index 00000000..b1f4223b --- /dev/null +++ b/doc/chalk/tutorial-quick-starts3.png diff --git a/doc/chalk/tutorial-quick-starts4.png b/doc/chalk/tutorial-quick-starts4.png Binary files differnew file mode 100644 index 00000000..1d6fcacb --- /dev/null +++ b/doc/chalk/tutorial-quick-starts4.png diff --git a/doc/chalk/tutorial-quick-starts5.png b/doc/chalk/tutorial-quick-starts5.png Binary files differnew file mode 100644 index 00000000..ceb18de9 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts5.png diff --git a/doc/chalk/tutorial-quick-starts6.png b/doc/chalk/tutorial-quick-starts6.png Binary files differnew file mode 100644 index 00000000..69176011 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts6.png diff --git a/doc/chalk/tutorial-quick-starts7.png b/doc/chalk/tutorial-quick-starts7.png Binary files differnew file mode 100644 index 00000000..92c6ab18 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts7.png diff --git a/doc/chalk/tutorial-quick-starts8.png b/doc/chalk/tutorial-quick-starts8.png Binary files differnew file mode 100644 index 00000000..fb2bed36 --- /dev/null +++ b/doc/chalk/tutorial-quick-starts8.png diff --git a/doc/chalk/tutorial-quick-starts9.png b/doc/chalk/tutorial-quick-starts9.png Binary files differnew file mode 100644 index 00000000..db763b6c --- /dev/null +++ b/doc/chalk/tutorial-quick-starts9.png diff --git a/doc/chalk/tutorial-select-layer-1.png b/doc/chalk/tutorial-select-layer-1.png Binary files differnew file mode 100644 index 00000000..29f8b0bf --- /dev/null +++ b/doc/chalk/tutorial-select-layer-1.png diff --git a/doc/chalk/tutorial-select-layer-10.png b/doc/chalk/tutorial-select-layer-10.png Binary files differnew file mode 100644 index 00000000..a2d92fc6 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-10.png diff --git a/doc/chalk/tutorial-select-layer-11.png b/doc/chalk/tutorial-select-layer-11.png Binary files differnew file mode 100644 index 00000000..75a6c10c --- /dev/null +++ b/doc/chalk/tutorial-select-layer-11.png diff --git a/doc/chalk/tutorial-select-layer-12.png b/doc/chalk/tutorial-select-layer-12.png Binary files differnew file mode 100644 index 00000000..95487fa7 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-12.png diff --git a/doc/chalk/tutorial-select-layer-13.png b/doc/chalk/tutorial-select-layer-13.png Binary files differnew file mode 100644 index 00000000..449ec903 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-13.png diff --git a/doc/chalk/tutorial-select-layer-2.png b/doc/chalk/tutorial-select-layer-2.png Binary files differnew file mode 100644 index 00000000..4552f0af --- /dev/null +++ b/doc/chalk/tutorial-select-layer-2.png diff --git a/doc/chalk/tutorial-select-layer-3.png b/doc/chalk/tutorial-select-layer-3.png Binary files differnew file mode 100644 index 00000000..a9a7a9bd --- /dev/null +++ b/doc/chalk/tutorial-select-layer-3.png diff --git a/doc/chalk/tutorial-select-layer-4.png b/doc/chalk/tutorial-select-layer-4.png Binary files differnew file mode 100644 index 00000000..a3506440 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-4.png diff --git a/doc/chalk/tutorial-select-layer-5.png b/doc/chalk/tutorial-select-layer-5.png Binary files differnew file mode 100644 index 00000000..f0e88e46 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-5.png diff --git a/doc/chalk/tutorial-select-layer-6.png b/doc/chalk/tutorial-select-layer-6.png Binary files differnew file mode 100644 index 00000000..eac0b247 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-6.png diff --git a/doc/chalk/tutorial-select-layer-7.png b/doc/chalk/tutorial-select-layer-7.png Binary files differnew file mode 100644 index 00000000..6580b54b --- /dev/null +++ b/doc/chalk/tutorial-select-layer-7.png diff --git a/doc/chalk/tutorial-select-layer-8.png b/doc/chalk/tutorial-select-layer-8.png Binary files differnew file mode 100644 index 00000000..503c0223 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-8.png diff --git a/doc/chalk/tutorial-select-layer-9.png b/doc/chalk/tutorial-select-layer-9.png Binary files differnew file mode 100644 index 00000000..cebfde39 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-9.png diff --git a/doc/chalk/tutorial-select-layer-sample.png b/doc/chalk/tutorial-select-layer-sample.png Binary files differnew file mode 100644 index 00000000..4def7ed3 --- /dev/null +++ b/doc/chalk/tutorial-select-layer-sample.png diff --git a/doc/chalk/tutorial-select-layer.docbook b/doc/chalk/tutorial-select-layer.docbook new file mode 100644 index 00000000..65a7b6ee --- /dev/null +++ b/doc/chalk/tutorial-select-layer.docbook @@ -0,0 +1,263 @@ +<sect1 id="tutorial-select-layer"> +<title>A Small selections and layers tutorial</title> + +<!-- Does someone know a better way to do this? --> +<screenshot> +<screeninfo>The starting image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-sample.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The starting image</phrase> +</textobject> +<caption><para>The starting image</para></caption> +</mediaobject> +</screenshot> + +<para> +The image above is the image we will work with. Start chalk with this +image (in the documentation folder +<filename>$<envar>KDEDIR</envar>/share/doc/HTML/en/chalk/tutorial-select-layer-sample.png</filename>) +and save it to your Home folder (by choosing <guilabel>Save Image As...</guilabel>). + +Then open it in &chalk; — your screen will look a bit like this (we have +zoomed in): +</para> + +<screenshot> +<screeninfo>Chalk with the starting image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-1.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The starting image</phrase> +</textobject> +<caption><para>The starting image</para></caption> +</mediaobject> +</screenshot> + +<para> +Now try to select the outline of the head with the <guilabel>Select Outline</guilabel> tool: +</para> + +<screenshot> +<screeninfo>The <guilabel>Select Outline</guilabel> tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-2.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Select Outline</guilabel> tool</phrase> +</textobject> +<caption><para>The <guilabel>Select Outline</guilabel> tool</para></caption> +</mediaobject> +</screenshot> + +<para> +After you select it, it should look a bit like this picture: +</para> + +<screenshot> +<screeninfo>The picture after selecting the head</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-3.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The picture after selecting the head</phrase> +</textobject> +<caption><para>The picture after selecting the head</para></caption> +</mediaobject> +</screenshot> + +<para> +If you accidently select too much, you can cut that part easily off by switching the tool to <guilabel>Subtract</guilabel> mode: +</para> + +<screenshot> +<screeninfo>The <guilabel>Subtract</guilabel> mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-4.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Subtract</guilabel> mode</phrase> +</textobject> +<caption><para>The <guilabel>Subtract</guilabel> mode</para></caption> +</mediaobject> +</screenshot> + +<para> +Now it's time to make the edges of the selection a bit fuzzy. This can be done by applying <guilabel>Feather</guilabel> to the selection. +</para> + +<screenshot> +<screeninfo><guilabel>Feather</guilabel> selection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-5.png" format="PNG" /> +</imageobject> +<textobject> +<phrase><guilabel>Feather</guilabel> selection</phrase> +</textobject> +<caption><para><guilabel>Feather</guilabel> selection</para></caption> +</mediaobject> +</screenshot> + +<para> +Now cut the selection, using +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Cut</guimenuitem></menuchoice>. +Delete the current layer with +<menuchoice><guimenu>Layer</guimenu><guimenuitem>Remove +Layer</guimenuitem></menuchoice>. Paste your selection, with +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice>. +Now we give ourselves a bit more room to work in by resizing the image a bit. +Use the <menuchoice><guimenu>Image</guimenu><guimenuitem>Change Image +Size...</guimenuitem></menuchoice> dialog for this. +</para> + +<screenshot> +<screeninfo>The <guilabel>Image Size</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-6.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Image Size</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Image Size</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> + +<para> +Add a new layer, and place it below the old layer. You do this by selecting +the new layer in the layerbox, and then pressing the little 'down' arrow at the bottom. +Now we are going to select the area around the head with a contiguous select +(the tool has a selection-with-bucketfill icon at the border). +</para> + +<screenshot> +<screeninfo>The <guilabel>Select Contiguous</guilabel> tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-7.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Select Contiguous</guilabel> tool</phrase> +</textobject> +<caption><para>The <guilabel>Select Contiguous</guilabel> tool</para></caption> +</mediaobject> +</screenshot> + +<para> +Make sure to select <guilabel>Sample merged</guilabel> in the tool options: +</para> + +<screenshot> +<screeninfo>The <guilabel>Sample merged</guilabel> option</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-8.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Sample merged</guilabel> option</phrase> +</textobject> +<caption><para>The <guilabel>Sample merged</guilabel> option</para></caption> +</mediaobject> +</screenshot> + +<para> +Feather the selection again, and invert it. +Select the <guilabel>Contiguous Fill</guilabel> tool (this is a different tool than +the <guilabel>Contiguous Select</guilabel> tool) and use it on the layer. +</para> + +<screenshot> +<screeninfo>The <guilabel>Contiguous Fill</guilabel> tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-9.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Contiguous Fill</guilabel> tool</phrase> +</textobject> +<caption><para>The <guilabel>Contiguous Fill</guilabel> tool</para></caption> +</mediaobject> +</screenshot> + +<para> +Deselect with <menuchoice><guimenu>Select</guimenu><guimenuitem>Deselect</guimenuitem></menuchoice>. +You'll notice some artefacts of the feathering at the sides. You can select them easily with a rectangular selection and then cut them. +</para> + +<screenshot> +<screeninfo>The <guilabel>Select Rectangular</guilabel> tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-10.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Select Rectangular</guilabel> tool</phrase> +</textobject> +<caption><para>The <guilabel>Select Rectangular</guilabel> tool</para></caption> +</mediaobject> +</screenshot> + +<para> +Move the shadow layer a bit down and to the right to make it look nice. +</para> + +<screenshot> +<screeninfo>Moving the shadow layer</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-11.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Moving the shadow layer</phrase> +</textobject> +<caption><para>Moving the shadow layer</para></caption> +</mediaobject> +</screenshot> + +<para> +Now you can use the <guilabel>Crop</guilabel> tool to make the image better fit around the head. +</para> + +<screenshot> +<screeninfo>The <guilabel>Crop</guilabel> tool</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-12.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Crop</guilabel> tool</phrase> +</textobject> +<caption><para>The <guilabel>Crop</guilabel> tool</para></caption> +</mediaobject> +</screenshot> + +<para> +Save the image, and you're done :-) +</para> + +<screenshot> +<screeninfo>The resulting image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-select-layer-13.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The resulting image</phrase> +</textobject> +<caption><para>The resulting image</para></caption> +</mediaobject> +</screenshot> + +<para> +Thanks go to Bart Coppens for providing this tutorial. The original is available at <ulink url="http://www.bartcoppens.be/chalk/hackergotchi.html">http://www.bartcoppens.be/chalk/hackergotchi.html</ulink>. +</para> + +</sect1> diff --git a/doc/chalk/tutorial-starting.docbook b/doc/chalk/tutorial-starting.docbook new file mode 100644 index 00000000..bed91f24 --- /dev/null +++ b/doc/chalk/tutorial-starting.docbook @@ -0,0 +1,117 @@ +<sect1 id="tutorial-starting"> +<title>Starting to know &chalk;</title> + +<para> +So, let's show you all the niceties. You can start &chalk; either on its own +or from the &koffice; shell. In your &kde; menus, &chalk; should be placed +either under Graphics or under Office — it depends a bit on who packaged +&koffice; for you. Or do what I do: press +<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> (which opens the +minicli), type <userinput><command>chalk</command></userinput> and +press <guibutton>OK</guibutton>. +</para> + +<para> +A little later, you'll be greeted by a dialog: +</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>Create Document</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="createdocument.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Create Document</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>Create Document</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +This is standard for &koffice;: you can create a new document, choose a +document from among your files or select a document you had opened in an earlier +session. We have got a bunch of templates here, ordered by color model. &chalk; +is a very flexible application and can handle many different types of images: +<acronym>CMYK</acronym> images for printers, <acronym>RGB</acronym> images for +the web, <acronym>RGB</acronym> images with high channel depths for +photographers, watercolor images for painters — and more. For now, choose +<guilabel>Custom Document</guilabel>. That will allow +us to see the <guilabel>New Image</guilabel> dialog box: +</para> + +<para> +<screenshot> +<screeninfo>The <guilabel>New Image</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="newimage.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>New Image</guilabel> dialog</phrase> +</textobject> +<caption><para>The <guilabel>New Image</guilabel> dialog</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +Here you can give your document a name, determine the dimensions and the +resolution. The combination of width/height and resolution determines how big +your image will be on screen or on paper: if your image has a resolution of +100x100 dpi, and your image is 1000x1000 pixels big, then, if everything is +configured correctly, your image will be exactly 10 inches long and 10 inches +wide if you check with a ruler, no matter the resolution of your screen or of +your printer — if shown at 100%. However, life is seldom so well-regulated +that this actually works out. For now, just think pixels, not inches. +</para> + +<para> +The next group of options is a lot more interesting than resolution: &chalk; +is an enormously flexible application and you can work with many kinds of +images. For this tutorial, just select <guilabel>RGB (8 +bits/channel)</guilabel>. You can also select a profile. For now, we leave this +at the default setting of <guilabel>sRGB built-in - (lcms internal)</guilabel>. +</para> + +<para> +In the third option group, you can select the initial canvas color and the +amount of opacity/transparency of this color. Furthermore you can +add a description of the contents. We leave these options at their default +settings as well, so click <guibutton>Create</guibutton> to actually create the new +image. +</para> + +<para> +You will now see the main &chalk; screen. +</para> + +<para> +<screenshot> +<screeninfo>&chalk;'s main screen</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mainscreen.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>&chalk;'s main screen</phrase> +</textobject> +<caption><para>&chalk;'s main screen</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +On the left hand side and on the top, there are toolbars which offer you access +to tools for painting, editing, and selecting. +You can find a more detailed description of these toolbars <link +linkend="commands-toolbars">here</link>. The actual painting area is in the +middle. On the right side of your screen, there are various palettes, which you +can read more about in <link linkend="commands-palettes">this section</link>. +Finally, there is a menu bar at the top of the screen, as usually. Read more +about it <link linkend="commands-menus">here</link>. +</para> + +</sect1> diff --git a/doc/chalk/tutorial-tablet-1.png b/doc/chalk/tutorial-tablet-1.png Binary files differnew file mode 100644 index 00000000..5ab3d648 --- /dev/null +++ b/doc/chalk/tutorial-tablet-1.png diff --git a/doc/chalk/tutorial-tablet-2.png b/doc/chalk/tutorial-tablet-2.png Binary files differnew file mode 100644 index 00000000..a2cf0023 --- /dev/null +++ b/doc/chalk/tutorial-tablet-2.png diff --git a/doc/chalk/tutorial-tablet-3.png b/doc/chalk/tutorial-tablet-3.png Binary files differnew file mode 100644 index 00000000..4986cbde --- /dev/null +++ b/doc/chalk/tutorial-tablet-3.png diff --git a/doc/chalk/tutorial-tablet.docbook b/doc/chalk/tutorial-tablet.docbook new file mode 100644 index 00000000..05a57504 --- /dev/null +++ b/doc/chalk/tutorial-tablet.docbook @@ -0,0 +1,141 @@ +<sect1 id="tutorial-tablet"> +<title>Working with tablets</title> + +<para>This tutorial is intended to describe you the first steps with working +with a tablet with &chalk;. The tutorial assumes you are using &Linux;.</para> + +<sect2 id="tutorial-tablet-configuring"> +<title>Configuring it</title> + +<para> +As any hardware it nearly works out of the box. &Linux; should recognize it +fine, but you might have to configure the X11 server by hand. The best way to +do this is to follow the instruction on the Wacom &Linux; howto: <ulink +url="http://linuxwacom.sourceforge.net/index.php/howto/main" />. +</para><para> +Then, in &chalk;, you need to enable the various tools (in the +<guilabel>Tablet</guilabel> section of the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&chalk;...</guimenuitem></menuchoice> dialog) — you can find more +information in the <link linkend="settings-preferences-tablet">tablet settings +section</link>. +</para> + +</sect2> + +<sect2 id="tutorial-tablet-firstcontact"> +<title>First contact with the tablet</title> + +<para> +There are three devices of your tablet that you can use with &chalk;: +</para> + +<itemizedlist> +<listitem><para>the cursor, the mouse that was shipped with the Wacom +tablet</para></listitem> +<listitem><para>the eraser, the round part on the top of the pen</para></listitem> +<listitem><para>the stylus, the thin point on the bottom of the pen</para></listitem> +</itemizedlist> + +<para> +By default, when you use the stylus or the cursor on the tablet, the Brush +tool and the pixel brush painting operation will get selected. The eraser +device is associated to the <quote>pixel eraser</quote> painting operation. +But if you select a different tool or a different painting operation with one +device, &chalk; will remember the association when you switch between devices. +</para> + +</sect2> + +<sect2 id="tutorial-tablet-outlines"> +<title>Outlines of a flower</title> + +<para> +Even if you knew how to draw before you started with a tablet, you will need +to adapt to the tablet. It doesn't feel the same. So I suggest to start with +something simple, like a flower, and to use a picture as a model: +</para> + +<para> +<screenshot> +<screeninfo>A flower</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-tablet-1.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>A flower</phrase> +</textobject> +<caption><para>A flower</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +First, you will need to create a new layer for the outline. I advise you to +lock the layer with the picture, it will prevent you from making mistakes. +</para><para> +Drawing the outline of the flower seems pretty easy, but for your first +experience you will have a great difficulty to precisely follow the line on +the screen while your hand has to move on the tablet. Eventually you will get +something like this: +</para> + +<para> +<screenshot> +<screeninfo>The outline of the flower</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-tablet-2.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The outline of the flower</phrase> +</textobject> +<caption><para>The outline of the flower</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="tutorial-tablet-colorization"> +<title>Colorization</title> + +<para> +For the colorization, you will need to create a third layer. You will +have to move it below the layer with the outlines, and do not forget to lock +the outline layer. +</para><para> +It's mostly easier than the outline part, just select the color you want to +use (either with the color selector or with the color picker), then for most +of the work you can use the fill tool: with the mouse, click on the part you +want to fill, as by default the fill tool will take the outline into +consideration. On the following image, the different colors of the heart of +the flower are not seperated by outlines, to do them I just completed the +missing outline with a yellow or brown line to create the separation between +the different colors. +</para> + +<para> +<screenshot> +<screeninfo>The colored flower</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-tablet-3.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The colored flower</phrase> +</textobject> +<caption><para>The colored flower</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +The resulting image looks and feels like old fashion clipart, mostly because +it lacks shadows and illumination, which are not covered by this tutorial. +</para> + +</sect2> + +</sect1> diff --git a/doc/chalk/tutorial.docbook b/doc/chalk/tutorial.docbook new file mode 100644 index 00000000..fbf0ea5b --- /dev/null +++ b/doc/chalk/tutorial.docbook @@ -0,0 +1,14 @@ +<chapter id="tutorial"> +<title>Tutorial</title> + +<note><para> +The toolbars and palettes shown in these tutorials may not match your +installation of &chalk;. Our apologies for this inconvenience. +</para></note> + +&tutorial-starting; +&tutorial-select-layer; +&tutorial-quick-starts; +&tutorial-tablet; + +</chapter> diff --git a/doc/chalk/using-colorspaces.docbook b/doc/chalk/using-colorspaces.docbook new file mode 100644 index 00000000..6a3c5481 --- /dev/null +++ b/doc/chalk/using-colorspaces.docbook @@ -0,0 +1,149 @@ +<chapter id="colorspaces"> +<title>Colorspaces</title> + +<para> +This chapter gives information on what colorspaces are, which colorspaces +&chalk; offers, and what you should keep in mind when using them. +</para> + +<sect1 id="colorspaces-intro"> +<title>Introduction to colorspaces</title> + +<sect2 id="colorspaces-intro-whatis"> +<title>What is a colorspace?</title> + +<para> +In short, a colorspace is a way to represent colors by specifying a number of +parameters. As parameters, one can choose for example the amounts of red, +green and blue light needed for the color. This results in the commonly known +RGB colorspace. One can visualize this as a three-dimensional space, with each +of the red, green, and blue light components being an axis in the colorspace. +A color then corresponds to a certain point in this colorspace, defined by its +coordinates on the three axes. +</para> +<note><para> +To be more precise, a colorspace is a combination of a color model (indicating +which axes are present) and a mapping function (indicating which values +correspond to which colors). +</para></note> +<para> +Not every color can be represented in every colorspace. Some colorspaces +define more, or different, colors than others. The set of colors that can be +represented in a certain colorspace is called its gamut. Because gamuts +can differ widely, it is not guaranteed that images in a certain colorspace +can be converted to another colorspace without having to substitute certain +colors for others, even if they are based on the same color model. +</para> + +</sect2> + +</sect1> + +<sect1 id="colorspaces-list"> +<title>Available colorspaces</title> + +<para> +&chalk; offers colorspaces based on RGB, CMYK, Lab, LMS, YCbCr, and Gray +color models. These are shortly discussed in this section. +</para> + +<sect2 id="colorspaces-list-rgb"> +<title>The RGB color models</title> + +<para> +The abbreviation RGB stands for Red, Green, Blue, and the color model with +this name refers to the three light components that are emitted in displays +(televisions, computer monitors, etcetera) to create a certain color. This +color model is used by default in virtually any standard painting application. +</para><para> +When defining a color in the RGB model, its red, green and blue components are +specified. If all components are absent (each component is emitted at 0 +percent intensity, so no light at all), the color is pure black. If all +components are fully present (100 percent intensity), the color is pure white. +If one component is present at full intensity and the other two are absent, +the pure respective color is obtained. +</para><para> +Two more examples: if both red and green are emitted at 100 percent and blue +is not emitted, pure yellow is obtained. A color with all three components at +the same intensity is a shade of gray. +</para><para> +There are various colorspaces that implement the RGB model. For example, the +so-called RGB8 colorspace represents each color with 8 bits per component. +Since 8 bits allow for 256 distinct values, the total number of different +colors that can be specified in this colorspace is 256 (red) * 256 (green) * +256 (blue), or about 16.7 million colors. In &chalk;, a couple of RGB +colorspaces are available, for example RGB32, which is able to distinguish +between 4.2 billion values per component. +</para> + +</sect2> + +<sect2 id="colorspaces-list-cmyk"> +<title>The CMYK color model</title> + +<para> +CMYK is the abbreviation for Cyan, Magenta, Yellow, blacK (although officially +the K stands for Key, black is much more commonly used). This color model is +based on ink: a color is specified by the amount of ink needed for a point +to be perceived as having that color. +</para><para> +Since CMYK colors are used by printers while RGB colors are used on-screen, +one often wants to convert RGB colors to CMYK colors. As this cannot always be +done correctly, printed images may turn out to look quite different than what +is perceived on-screen. +</para> + +</sect2> + +<sect2 id="colorspaces-list-lab"> +<title>The L*a*b* color model</title> + +<para> +This color model uses three parameters for a color: its +luminance or lightness (L*, which lies between 0 for black and +100 for white), its position between absolute red and absolute green (a*, +which is negative for colors closer to green and positive for colors closer to +red), and its position between yellow and blue (b*, which is negative for +colors closer to blue and positive for colors closer to yellow). +</para> + +</sect2> + +<sect2 id="colorspaces-list-LMS"> +<title>The LMS color model</title> + +<para> +This model is based on the contribution of actual light wave lengths to the +color. The human eye is sensitive to three types of light waves, distinguished +by their wave lengths: long (L), middle (M) and short (S) waves. The eye's +sensitivity for a certain color on these three wavelengths can be expressed in +L, M and S coordinates. +</para> + +</sect2> + +<sect2 id="colorspaces-list-YCbCr"> +<title>The YCbCr color model</title> + +<para> +The YCbCr model is often used for video systems. The Y parameter indicates the +luminance or lightness of the color (which can be seen as a gray-tone), the Cb +and Cr parameters indicate the chrominance (color tone): Cb places the color +on a scale between blue and yellow, Cr indicates the place of the color +between red and green. +</para> + +</sect2> + +<sect2 id="colorspaces-list-Gray"><title>The Gray color model</title> + +<para> +The Gray color model simply represents colors as shades of gray (with black +and white being the extremes). +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/chalk/using-filters.docbook b/doc/chalk/using-filters.docbook new file mode 100644 index 00000000..7dd8cf8d --- /dev/null +++ b/doc/chalk/using-filters.docbook @@ -0,0 +1,923 @@ +<chapter id="filters"> +<title>Filters</title> + +<para> +&chalk; comes with a number of filters. These can be used to enhance or +otherwise modify the image, either in whole or in part. Some filters are +applied directly, others are customizable, meaning that you are presented with +a dialog in which you can tune the result to your liking before the filter is +applied. If a selection is active, a filter is applied on the selected part of +the image. If no selection is active, the entire image is modified. +</para><para> +This chapter describes the available filters in detail. To make comparing the +filters easier, each filter has been applied to the same image and each description +contains a comparison image, showing the result of applying the filter described. +The original image (with thanks to the photographer, Christian Peper) is shown +below at half the original size. The sample images demonstrating the +results of applying the filters, with the original image at the left and the +modified image at the right, are shown at 25% of the original size. +</para> +<note><para>Some filters yield reasonable results for most images. For +other filters though, quite some tweaking needs to be done before the desired +outcome is achieved. If a filter does not do what you want, it might need +more or less customising. The examples in this chapter are exaggerated to +give a good impression of the filters. You will usually want to have more +<quote>gentle</quote> modifications.</para></note> +<para> +Tip: If you want to apply a filter to everything except a certain part of your +image (for example, you want to desaturate your image except for the centre), +select the part you do not want to apply the filter to, use the +<menuchoice><guimenu>Select</guimenu><guimenuitem>Invert</guimenuitem></menuchoice> +menu option, and then apply the filter. +</para> +<para> +See the <link linkend="commands-dialogs-filters">Dialogs for working with +filters</link> section for descriptions of the settings available for the +customizable filters. +</para> + +<screenshot> +<screeninfo>The original image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The original image</phrase> +</textobject> +<caption><para>The original image</para></caption> +</mediaobject> +</screenshot> + +<sect1 id="filters-autocontrast"> +<title>The Auto Contrast filter</title> +<para> +The Auto Contrast filter changes the contrast of your image to what should be +the best settings. Usually this works out fine, but in some cases (for example +photos taken under unusual lighting circumstances), the filter will not yield +satisfying results. +</para> +<para> +You can find the Auto Contrast filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu></menuchoice> menu. This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Auto Contrast filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-autocontrast.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Auto Contrast filter applied to it</phrase> +</textobject> +<caption><para>The image with the Auto Contrast filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-blur"> +<title>The Blur filter</title> +<para> +You can use the Blur filter to blur your image (give it a fuzzy look). +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Blur</guisubmenu></menuchoice> menu. +See the section on <link linkend="commands-dialogs-filters-blur">the +<guilabel>Blur</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Blur filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-blur.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Blur filter applied to it</phrase> +</textobject> +<caption><para>The image with the Blur filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-brightnesscontrast"> +<title>The Brightness / Contrast filter</title> +<para> +With this filter, you can adjust the brightness and contrast of your image. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-brightnesscontrast">the +<guilabel>Brightness / Contrast</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Brightness / Contrast filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-brightnesscontrast.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Brightness / Contrast filter applied to it</phrase> +</textobject> +<caption><para>The image with the Brightness / Contrast filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-bumpmap"> +<title>The Bumpmap filter</title> +<para> +The Bumpmap filter takes two layers and uses one of these to convert the other +one so that it will give an illusion of depth. The object layer (the layer to be +transformed) is the actual layer that should receive the three-dimensional +looks. The bumpmap layer is a grayscale layer, which is read and used to +determine the height for each point of the object layer. Alternatively, the +same layer can be used as both object layer and bumpmap layer. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-bumpmap">the +<guilabel>Bumpmap</guilabel> dialog</link> for more information on its +settings. +</para> +<screenshot> +<screeninfo>The image with the Bumpmap filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-bumpmap.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Bumpmap filter applied to it</phrase> +</textobject> +<caption><para>The image with the Bumpmap filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-cimg"> +<title>The CImg Image Restoration filter</title> +<para> +With this filter, you can perform minor enhancements to your image, for +example removing small scratches or adding a slight blur. The difference +between our sample original image and the result of applying this filter with +standard settings is virtually none. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-imagerestoration">the +<guilabel>Image Restoration</guilabel> dialog</link> +for more information on its settings. +</para> +</sect1> + +<sect1 id="filters-coloradjustment"> +<title>The Color Adjustment filter</title> +<para> +This filter allows you to change the looks of your image by increasing or +decreasing the abundance of certain colors. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-coloradjustment">the +<guilabel>Color Adjustment</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Color Adjustment filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-coloradjustment.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Color Adjustment filter applied to it</phrase> +</textobject> +<caption><para>The image with the Color Adjustment filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-colortoalpha"> +<title>The Color to Alpha filter</title> +<para> +This filter changes a color or color range in your image to become +transparent, effectively clearing regions with those colors. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-colortoalpha">the +<guilabel>Color to Alpha</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Color to Alpha filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-colortoalpha.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Color to Alpha filter applied to it</phrase> +</textobject> +<caption><para>The image with the Color to Alpha filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-colortransfer"> +<title>The Color Transfer filter</title> +<para> +With this filter, you can re-color an image using the colors from another +image. Each color in your current image will be replaced by the most alike +color used in the other image. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-colortransfer">the +<guilabel>Color Transfer</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Color Transfer filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-colortransfer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Color Transfer filter applied to it</phrase> +</textobject> +<caption><para>The image with the Color Transfer filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-customconvolution"> +<title>The Custom Convolution filter</title> +<para> +This filter allows you to distort your image by setting a number of +parameters. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-customconvolution">the +<guilabel>Custom Convolution</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Custom Convolution filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-customconvolution.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Custom Convolution filter applied to it</phrase> +</textobject> +<caption><para>The image with the Custom Convolution filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-desaturate"> +<title>The Desaturate filter</title> +<para> +This filter converts your image to grayscale by setting the saturation of each +pixel's color to zero. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Desaturate filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-desaturate.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Desaturate filter applied to it</phrase> +</textobject> +<caption><para>The image with the Desaturate filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-edgedetection"> +<title>The Edge Detection filters</title> +<para> +These filters try to detect <quote>edges</quote> (boundaries) in the picture +and modify the image such that only these edges retain their respective colors, +while the rest of the image is turned gray. Through the use of lighting the +image will then get a three-dimensional look. +</para><para> +There are four edge detection filters available. Each of these detects edges +from a different side (possibly considering other parts of the image as being +edges) and will therefore obtain a different resulting image. +</para> +<para> +You can find the filters in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu></menuchoice> menu. +These filters are not customizable. +</para> +<screenshot> +<screeninfo>The image with the Bottom Edge Detection filter applied to +it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-edgebottom.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Bottom Edge Detection filter applied to it</phrase> +</textobject> +<caption><para>The image with the Bottom Edge Detection filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-emboss"> +<title>The Emboss filters</title> +<para> +Emboss filters work somewhat like edge detection filters, with the difference +that embossed images are entirely gray. Areas in the picture are detected and +are given a certain <quote>height level</quote>, which is made visible by using +grayscale borders, making the image look like it is three-dimensional. +</para> +<para> +You can find the filters in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Emboss</guisubmenu></menuchoice> menu. +Except for the Emboss with Variable Depth filter, these filters are not +customizable. See the section on <link +linkend="commands-dialogs-filters-emboss">the +<guilabel>Emboss</guilabel> dialog</link> +for more information on the settings of the Emboss with Variable Depth filter. +</para> +<screenshot> +<screeninfo>The image with the Emboss in All Directions filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-embossall.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Emboss in All Directions filter applied to it</phrase> +</textobject> +<caption><para>The image with the Emboss in All Directions filter applied to +it</para></caption> +</mediaobject> +</screenshot> +<screenshot> +<screeninfo>The image with the Emboss with Variable depth filter applied to +it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-embossvariable.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Emboss with Variable depth filter applied to it</phrase> +</textobject> +<caption><para>The image with the Emboss with Variable depth filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-gaussianblur"> +<title>The Gaussian Blur filter</title> +<para> +This filter makes the image a little fuzzy by blurring it in a pseudo-random +way. A gaussian algorithm is used for finding the extent to which each part of +the image should be blurred. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Blur</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Gaussian Blur filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-gaussianblur.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Gaussian Blur filter applied to it</phrase> +</textobject> +<caption><para>The image with the Gaussian Blur filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-gaussiannoise"> +<title>The Gaussian Noise Reduction filter</title> +<para> +With this filter, you can remove noise from your image. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-gaussiannoise">the +<guilabel>Gaussian Noise Reduction</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Gaussian Noise Reduction filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-gaussiannoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Gaussian Noise Reduction filter applied to it</phrase> +</textobject> +<caption><para>The image with the Gaussian Noise Reduction filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-invert"> +<title>The Invert filter</title> +<para> +This filter inverts all colors. The Red, Green and Blue component of each pixel +are taken and subtracted from 255. This means that red becomes cyan, green +becomes purple, and blue becomes yellow. The resulting values form the new +pixel color. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Adjust</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Invert filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-invert.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Invert filter applied to it</phrase> +</textobject> +<caption><para>The image with the Invert filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-lenscorrection"> +<title>The Lens Correction filter</title> +<para> +This filter can fix distortions in your image resulting from for example +<quote>pincushion</quote> lens effects, and modify some lighting. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-lenscorrection">the +<guilabel>Lens Correction</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Lens Correction filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-lenscorrection.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Lens Correction filter applied to it</phrase> +</textobject> +<caption><para>The image with the Lens Correction filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-maximizechannel"> +<title>The Maximize Channel filter</title> +<para> +This filter gives each pixel in your image a new color: only the color channel +that contributes the most to the color of a pixel is retained (except for +gray pixels, which are kept gray). +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Maximize Channel filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-maximizechannel.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Maximize Channel filter applied to it</phrase> +</textobject> +<caption><para>The image with the Maximize Channel filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-meanremoval"> +<title>The Mean Removal filter</title> +<para> +This filter sharpens the image by changing the colors of neighboring pixels +with approximately the same color, so that small differences are evened out. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Mean Removal filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-meanremoval.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Mean Removal filter applied to it</phrase> +</textobject> +<caption><para>The image with the Mean Removal filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-minimizechannel"> +<title>The Minimize Channel filter</title> +<para> +This filter gives each pixel in your image a new color: the color channel +that contributes the most to the color of a pixel is removed (except for +gray pixels, which are kept gray). +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Colors</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Minimize Channel filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-minimizechannel.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Minimize Channel filter applied to it</phrase> +</textobject> +<caption><para>The image with the Minimize Channel filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-oilpaint"> +<title>The Oilpaint filter</title> +<para> +An oilpaint effect is given to the image by creating patch-shaped areas in which +the most important color is applied to the entire area. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-oilpaint">the +<guilabel>Oilpaint</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Oilpaint filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-oilpaint.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Oilpaint filter applied to it</phrase> +</textobject> +<caption><para>The image with the Oilpaint filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-pixelize"> +<title>The Pixelize filter</title> +<para> +The image is pixelated by taking a square area and giving it the mean color +value of the pixels it contains. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-pixelize">the +<guilabel>Pixelize</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Pixelize filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-pixelize.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Pixelize filter applied to it</phrase> +</textobject> +<caption><para>The image with the Pixelize filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-raindrops"> +<title>The Raindrops filter</title> +<para> +This filter makes it look like raindrops have fallen on the image by distorting +drop-shaped areas with a lens-like effect as one would see when looking +at the image through a real raindrop. Some raindrops will have a fish-eye lens +effect. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Artistic</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-raindrops">the +<guilabel>Raindrops</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Raindrops filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-raindrops.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Raindrops filter applied to it</phrase> +</textobject> +<caption><para>The image with the Raindrops filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-randomnoise"> +<title>The Random Noise filter</title> +<para> +With this filter, random noise can be added to your image. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-randomnoise">the +<guilabel>Random Noise</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Random Noise filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-randomnoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Random Noise filter applied to it</phrase> +</textobject> +<caption><para>The image with the Random Noise filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-randompick"> +<title>The Random Pick filter</title> +<para> +This filter distorts the image by interchanging pixels. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-randompick">the +<guilabel>Random Pick</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Random Pick filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-randompick.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Random Pick filter applied to it</phrase> +</textobject> +<caption><para>The image with the Random Pick filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-roundcorners"> +<title>The Round Corners filter</title> +<para> +This filter just rounds off the corners of the image. This is done by making +the outside of the rounded corner transparent. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-roundcorners">the +<guilabel>Round Corners</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Round Corners filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-roundcorners.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Round Corners filter applied to it</phrase> +</textobject> +<caption><para>The image with the Round Corners filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-sharpen"> +<title>The Sharpen filter</title> +<para> +This filter sharpens the image. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +This filter is not customizable. +</para> +<screenshot> +<screeninfo>The image with the Sharpen filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-sharpen.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Sharpen filter applied to it</phrase> +</textobject> +<caption><para>The image with the Sharpen filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-smalltiles"> +<title>The Small Tiles filter</title> +<para> +The picture is reduced in size and repeated multiple times. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Map</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-smalltiles">the +<guilabel>Small Tiles</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Small Tiles filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-smalltiles.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Small Tiles filter applied to it</phrase> +</textobject> +<caption><para>The image with the Small Tiles filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-sobel"> +<title>The Sobel filter</title> +<para> +This is a more enhanced edge detection filter. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Edge Detection</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-sobel">the +<guilabel>Sobel</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Sobel filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-sobel.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Sobel filter applied to it</phrase> +</textobject> +<caption><para>The image with the Sobel filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-unsharpmask"> +<title>The Unsharp Mask filter</title> +<para> +This filter sharpens part of your image. (The name <quote>unsharp</quote> is +historical: parts would be masked off while the rest would be made less sharp.) +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-unsharpmask">the +<guilabel>Unsharp Mask</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Unsharp Mask filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-unsharpmask.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Unsharp Mask filter applied to it</phrase> +</textobject> +<caption><para>The image with the Unsharp Mask filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-wave"> +<title>The Wave filter</title> +<para> +This filter transforms your image into a wave shape. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Other</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-wave">the +<guilabel>Wave</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Wave filter applied to it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-wave.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Wave filter applied to it</phrase> +</textobject> +<caption><para>The image with the Wave filter applied to it</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="filters-waveletnoise"> +<title>The Wavelet Noise Reduction filter</title> +<para> +This filter reduces noise in the image by giving loose pixels a color close to +the surrounding area. This causes small details to be lost, but can enhance the +general view of the image when this is hampered by too many unnecessary details. +</para> +<para> +You can find the filter in the <menuchoice><guimenu>Filter</guimenu> +<guisubmenu>Enhance</guisubmenu></menuchoice> menu. +See the section on <link +linkend="commands-dialogs-filters-waveletnoise">the +<guilabel>Wavelet Noise Reduction</guilabel> dialog</link> +for more information on its settings. +</para> +<screenshot> +<screeninfo>The image with the Wavelet Noise Reduction filter applied to +it</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="crocusses-waveletnoise.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The image with the Wavelet Noise Reduction filter applied to it</phrase> +</textobject> +<caption><para>The image with the Wavelet Noise Reduction filter applied to +it</para></caption> +</mediaobject> +</screenshot> +</sect1> + + +</chapter> diff --git a/doc/chalk/using-images.docbook b/doc/chalk/using-images.docbook new file mode 100644 index 00000000..4def5a41 --- /dev/null +++ b/doc/chalk/using-images.docbook @@ -0,0 +1,66 @@ +<chapter id="images"> +<title>Images</title> + +<para> +Creating and modifying images is one of &chalk;'s core functionalities. While +most of the other chapters in this manual focus on the things you can do when +painting or editing, this chapter shows you what you can do with respect to +the images themselves. +</para> + +<sect1 id="images-files"> +<title>Working with files</title> + +<para> +Unless you are doing some quick sketching, working with &chalk; will most +likely involve files. You can open existing images — &chalk; can work +with a large number of file formats, see <link +linkend="introduction-keyfeatures-imageformats">Image formats</link> — +or start &chalk; to create a new one. When you are done or if you want to +continue at a later time, you can easily save your work. +</para> + +<variablelist> + +<varlistentry><term>Opening existing files</term> +<listitem><para>When you start &chalk;, you can open an existing image with +the <guibutton>Open Existing Document</guibutton> button at the lower left of +the opening dialog. You can also use the +<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice> +menu option (<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>). +This will bring up the <guilabel>Open Document</guilabel> dialog in which you +can choose an image to open. The opening dialog and the +<guimenu>File</guimenu> menu also contain a list of the most recently used +files for quick access.</para></listitem> +</varlistentry> + +<varlistentry><term>Saving your work in progress</term> +<listitem><para>With the +<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> +and <menuchoice><guimenu>File</guimenu><guimenuitem>Save As...</guimenuitem></menuchoice> +menu options (or their respective shortcuts <keycombo +action="simul">&Ctrl;<keycap>S</keycap></keycombo> and <keycombo +action="simul">&Ctrl;&Shift;<keycap>S</keycap></keycombo>), you can save your +work. The former option will save the modifications to the current image, the +latter option will show the <guilabel>Save Document</guilabel> dialog in which +you can give a new file name for the image. If this is the first time you save +the image, <guimenuitem>Save</guimenuitem> will ask for a file name as well. +</para></listitem> +</varlistentry> + +<varlistentry><term>Creating a new image</term> +<listitem><para>From the opening dialog (available via the +<menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice> +menu option or the <keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo> keys), you can create a +fully custom document or choose one of the image templates. These templates +offer a quick way of creating a new image. See the <link +linkend="tutorial-starting">Starting to know &chalk;</link> tutorial. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/chalk/using-layers.docbook b/doc/chalk/using-layers.docbook new file mode 100644 index 00000000..3ca80291 --- /dev/null +++ b/doc/chalk/using-layers.docbook @@ -0,0 +1,620 @@ +<chapter id="layers"> +<title>Layers</title> + +<para> +This chapter gives an overview of how layers work in &chalk;. +</para> + +<sect1 id="layers-background"> +<title>Background information on layers</title> + +<para> +Extensive use of &chalk; will almost require you to have some knowledge of +layers. Using layers, you can work on one part of the image without touching +the rest of it, and most effects are best applied on a layer, instead of on +the whole image. Of course, if you do want to apply an effect to an entire +image, &chalk; does offer you that possibility, and there is nothing against +it. +</para><para> +The idea behind layers is quite simple. As the name suggests, layers lie on +top of each other, and together form the layer stack. The final resulting +image is that what you see when looking through the stack from top to bottom. +This means that usually the upper layers of your image will have more or less +transparency, since you cannot look through a layer which has no transparency. +(&chalk; works with opaqueness instead of transparency. A layer that is 100 +percent opaque is 0 percent transparent, and vice versa.) A layer higher in +the stack gets applied later than one lower in the stack. For example, if your +image contains four layers, numbered from 1 (lowest) to 4 (highest), the +effect that layer number 4 adds to the image, is applied to the result from +applying layers 1 through 3. +</para><para> +Every image you edit in &chalk; contains layers. When you create a new image, +the layer box (usually shown at the bottom right of your screen, see <link +linkend="commands-palettes-layers-layers">this section</link>) will contain +one layer. The painting and editing you do is then applied to that layer. Once +you add more layers, you can choose on which part of the image you want to +work, by selecting the respective layer. All further painting is then applied +to that layer, until you select another one. +</para><para> +Layers are also an excellent way to check whether adding certain effects (or +applying certain image modifications) come out right. Add a layer which +contains what you want to try out, and show or hide it with the eye icon in +the layer box. You can especially profit from this method if you have multiple +effects to check out: show and hide them in any combination, and decide which +you like best. And since you can move the layers around, you can also +experiment with the order in which the effects are applied. +</para><para> +See the <link linkend="tutorial-select-layer">Selections and layers +tutorial</link> for a small hands-on introduction. +</para> +</sect1> + +<sect1 id="layers-layerbox"> +<title>The layer box</title> + +<para>The layer box is the instrument you will use most to work with layers. It +gives an overview of the layers that are present in your image, and using it +you can manage layers by adding, removing, reordering or modifying them. +</para><para> +The layer box consists of three parts. The middle part gives an overview of the +layers in the image. At the top, you can set some properties for the current +layer. At the bottom, a couple of layer management options can be found. The +next sections describe these three parts in more detail. +</para> + +<sect2 id="layers-layerbox-overview"> +<title>Layer overview</title> + +<para>This part shows you which layers are present in your image. In a tree-like +structure, the layer group hierarchy is shown: layers that are contained within +a layer group are displayed a bit to the right to indicate their belonging to +that group. +</para><para> +For each layer, a thumbnail preview and its name are shown. The layer name +is preceded by a folder icon if it is a group layer. Furthermore, two +indicators are present: the eye icon shows whether the layer is currently +visible (an open eye indicates that the layer is visible, a closed eye +indicates that it is not), and the lock icon shows whether the layer is +locked. No changes can be made to a locked layer. +</para><para> +When you click on a layer's eye icon, its visibility is switched from on to +off or vice versa. Clicking on the lock icon enables or disables editing of +that layer. You can click on the name of the current layer to rename it. +Note that to rename a layer, it has to be the current one. You do not need to +activate a layer in order to make it (in)visible or (un)locked via the eye and +lock icons, respectively: these work directly. +</para><para> +Doubleclick on a layer entry in the list to open the <link +linkend="commands-dialogs-layers-layerproperties"><guilabel>Layer +Properties</guilabel></link> dialog. This dialog shows a layer's colorspace and +profile. You can also change its name, opacity and composite mode here. +</para> +</sect2> + +<sect2 id="layers-layerbox-options"> +<title>Layer options</title> +<para> +The top of the layer box contains two controls for setting properties of the +currently selected layer. The list box at the left allows you to quickly set +the layer's composite mode. The spin field and slider at the right can be used +to change the layer's opacity. +</para><para> +At the bottom of the layer box, there are five buttons. From left to right, +these are as follows. The <guibutton>New Layer</guibutton> icon brings up a +submenu from which you can choose which type of layer you want to add. This +menu can also be opened by clicking with the &RMB; on the layer box. The +<guibutton>Move Layer Down</guibutton> and <guibutton>Move Layer Up</guibutton> +buttons move the current layer one level down and up, respectively, within the +current layer group. If the layer is already the last or first within the +layer group, trying to move it further will move it out of the layer group. +The <guibutton>Layer Properties</guibutton> button opens the <link +linkend="commands-dialogs-layers-layerproperties"><guilabel>Layer +Properties</guilabel></link> dialog, just as when you would have doubleclicked +on the layer. The <guibutton>Delete Layer</guibutton> button deletes the +current layer. +</para> +</sect2> + +</sect1> + +<sect1 id="layers-working"> +<title>Working with layers</title> + +<para> +Because layers are quite important when extensively using &chalk;, you can +perform a lot of operations on them. These are all available via the <link +linkend="commands-menus-layer"><guimenu>Layer</guimenu> menu</link>. Some of +the possibilities: +</para> + +<variablelist> +<varlistentry><term></term><listitem><para>Add, remove, and duplicate layers;</para></listitem></varlistentry> +<varlistentry><term></term><listitem><para>Create and edit layer masks;</para></listitem></varlistentry> +<varlistentry><term></term><listitem><para>Flip, rotate, scale and shear layers;</para></listitem></varlistentry> +<varlistentry><term></term><listitem><para>Convert layers between colorspaces;</para></listitem></varlistentry> +<varlistentry><term></term><listitem><para>Save layers as images;</para></listitem></varlistentry> +<varlistentry><term></term><listitem><para>View layer histograms.</para></listitem></varlistentry> +</variablelist> + +</sect1> + +<sect1 id="layers-adjustment"> +<title>Adjustment Layers</title> + +<para>Adjustment layers are layers that consist of a filter and an optional +selection. The filter effect is applied to the composite image of all +layers under the adjustment layer in the current layer group. The big +thing is, adjustment layers apply these effects non-destructively. The +original image data is not modified. +</para><para> +Almost all &chalk; filters are suitable for use in adjustment +layers -- even filters that would downgrade the image quality. For instance, +the raindrops filter converts to 8-bit RGB before working its magic. If you +would try to use this filter directly on a 16-bit L*a*b* layer, &chalk; would +warn you about the conversion to RGB and back again this filter would cause. +Not so with adjustment layers: the original data isn't touched, so applying +the filter is safe. +</para><para> +What about the colorspace of an adjustment layer then? In order to examine +this issue, you need to know what happens when &chalk; renders an adjustment +layer. +</para> + +<sect2 id="layers-adjustment-selections"> +<title>Adjustment layers and selections</title> + +<para>If the currently active layer has an active selection, then that selection +will be copied and used as a mask for the adjustment layer. If there is no +active selection, then there will be no mask and the adjustment will apply to +the entire extent of the layers under the adjustment layer in the current +group. There is <emphasis>no</emphasis> way of adding a mask to an existing +adjustment layer. +</para><para> +If there is a mask in the adjustment layer, you can edit the mask using the +ordinary painting tools and painting operations. +</para> + +</sect2> + +<sect2 id="layers-adjustment-projection"> +<title>A note on projections</title> + +<para> +&chalk; composites the layers bottom to top, within each layer group. The +aggregate -- or the projection as it is also called -- is then filtered by +the adjustment layer. If there are layers on top of the adjustment layer, +those are composited onto the projection. &chalk; converts all layer data before +compositing, so if the bottom-most layer in an image is grayscale, all layers +are converted to grayscale before compositing -- and that means that the +adjustment layer projection will be grayscale, too. +</para><para> +With this knowledge you'll understand why &chalk; can often offer better +performance working with layers on top of an adjustment layer which is on top +of a complex layer structure: &chalk; uses the projection and doesn't even look +anymore at the layers under the adjustment layer. Unless, of course, you +change one of them. +</para> +</sect2> + +</sect1> + +<sect1 id="layers-composite"> +<title>Compositing modes</title> + +<para> +Layers can be composited in various ways, each yielding a different effect. +This section describes the available compositing modes. Each description is +accompanied by an example: on top of an original image (see below), a rainbow +gradient is added. +</para> + +<para> +<screenshot> +<screeninfo>The original image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-original.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The original image</phrase> +</textobject> +<caption><para>The original image</para></caption> +</mediaobject> +</screenshot> +</para> + +<sect2 id="layers-composite-normal"> +<title><guilabel>Normal</guilabel></title> + +<para> +The <guilabel>Normal</guilabel> mode does nothing special. It adds the layer +to the image, and if no other special effects like opacity are changed, the +underlying layers will only be visible at places where the new layer is +itself transparent. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Normal</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-normal.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Normal</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Normal</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-multiply"> +<title><guilabel>Multiply</guilabel></title> + +<para> +The <guilabel>Multiply</guilabel> mode blends the two layers so that the +bottom layer gets <quote>colorized</quote> by the new layer. The resulting +image is generally quite dark. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Multiply</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-multiply.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Multiply</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Multiply</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-burn"> +<title><guilabel>Burn</guilabel>, <guilabel>Dodge</guilabel>, +<guilabel>Divide</guilabel> and <guilabel>Screen</guilabel></title> + +<para> +The <guilabel>Burn</guilabel>, <guilabel>Dodge</guilabel>, +<guilabel>Divide</guilabel> and <guilabel>Screen</guilabel> modes all add an +extra <quote>burning</quote> effect by following contours instead of using +straight lines. In addition, <guilabel>Burn</guilabel> and +<guilabel>Divide</guilabel> use the inverted colors instead of the actual +colors of the composited layer. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Burn</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-burn.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Burn</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Burn</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Dodge</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-dodge.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Dodge</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Dodge</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Divide</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-divide.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Divide</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Divide</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Screen</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-screen.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Screen</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Screen</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-overlay"> +<title><guilabel>Overlay</guilabel></title> + +<para> +Like <guilabel>Multiply</guilabel>, the <guilabel>Overlay</guilabel> mode +colorizes the underlying layer. The resulting image is about as light as +the original layer. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Overlay</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-overlay.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Overlay</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Overlay</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-darken"> +<title><guilabel>Darken</guilabel></title> + +<para> +The <guilabel>Darken</guilabel> mode darkens the underlying layer while +colorizing it to match the colors in the composited layer. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Darken</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-darken.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Darken</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Darken</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-lighten"> +<title><guilabel>Lighten</guilabel></title> + +<para> +The <guilabel>Lighten</guilabel> mode lightens the underlying layer while +colorizing it to match the colors in the composited layer. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Lighten</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-lighten.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Lighten</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Lighten</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-hue"> +<title><guilabel>Hue</guilabel>, <guilabel>Saturation</guilabel> and +<guilabel>Value</guilabel></title> + +<para> +The <guilabel>Hue</guilabel>, <guilabel>Saturation</guilabel> and +<guilabel>Value</guilabel> modes respectively apply the hue, saturation and +value components of the composited layer to the underlying layer. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Hue</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-hue.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Hue</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Hue</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Saturation</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-saturation.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Saturation</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Saturation</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Value</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-value.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Value</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Value</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +<sect2 id="layers-composite-color"> +<title><guilabel>Color</guilabel></title> + +<para> +The <guilabel>Color</guilabel> mode colorizes the underlying layer, yielding +very strong colors. +</para> + +<para> +<screenshot> +<screeninfo>The gradient applied with the <guilabel>Color</guilabel> compositing +mode</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mountains-color.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The gradient applied with the <guilabel>Color</guilabel> compositing +mode</phrase> +</textobject> +<caption><para>The gradient applied with the <guilabel>Color</guilabel> compositing +mode</para></caption> +</mediaobject> +</screenshot> +</para> + +</sect2> + +</sect1> + +<sect1 id="layers-masks"> +<title>Layer Masks</title> + +<para> +Basically, a layer mask is a mask that you place on your paint layer. This +will literally mask areas of the layer, so that the content underneath shows +through. You can paint on it with greyscale colors: the more black the color, +the less the layer under it will shine through, the more white, the less the +layer under it will be shown. So complete white will let nothing through, +complete black will let everything through. Basically, it is a bit like +selecting a piece of your image, and then cutting it, so that the selected +bits go away. So what is the use for a mask here? The big advantage is that it +is non-destructive: if you decide that you masked out the wrong part of your +layer, you can easily remove the mask and start anew, something a lot harder +(not to say near impossible, especially in between sessions) with regular +selection-cutting. +</para><para> +So, how to create a mask? There are 2 ways: +</para> + +<itemizedlist> +<listitem><para> +Start from scratch. +<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Create +Mask</guimenuitem></menuchoice>. The mask starts with everything being +retained, that is, a complete white mask. Basically you will not see any +changes as long as you do not paint on it. +</para></listitem> +<listitem><para> +Start from the current selection. +<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Mask +From Selection</guimenuitem></menuchoice>. The selectedness will be converted +to whiteness. This means that fully selected area will be visible, fully +unselected areas will be invisible, and the rest will be partially visible, +depending on how much the area was selected. +</para></listitem> +</itemizedlist> + +<sect2 id="layers-masks-editing"> +<title>Editing the mask</title> + +<para> +First, make sure you are editing the mask, not the layer, by making sure +<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Edit +Mask</guimenuitem></menuchoice> is checked. (This is checked by default.) Then +you can paint on the layer just like before, only now you are +painting on the mask, instead of on the layer itself. To stop painting on the +mask, you can uncheck the <guilabel>Edit Mask</guilabel> checkbox. There's +also the option to show the mask, through checking +<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Show +Mask</guimenuitem></menuchoice>. (This is not checked by +default). This option will render the entire layer as a visual representation +of the mask in greyscale, instead of the actual layer. This can be handy to +see where your mask is, but it might be not as handy when you want to edit it, +since you cannot look at the actual layer. +</para><para> +Other actions: you can also remove the mask if you are not satisfied with it, +and want to start over again, or just want to remove it, with +<menuchoice><guimenu>Layer</guimenu><guisubmenu>Mask</guisubmenu><guimenuitem>Remove +Mask</guimenuitem></menuchoice>. You can also <quote>apply</quote> the mask, +meaning that the mask will be made permanently. This means that the mask is +removed, but that its effect of transparency will be committed to the layer. +</para> + +</sect2> +</sect1> + +</chapter> diff --git a/doc/chalk/using-selections-1.png b/doc/chalk/using-selections-1.png Binary files differnew file mode 100644 index 00000000..3efc76bb --- /dev/null +++ b/doc/chalk/using-selections-1.png diff --git a/doc/chalk/using-selections-2.png b/doc/chalk/using-selections-2.png Binary files differnew file mode 100644 index 00000000..f2e3febc --- /dev/null +++ b/doc/chalk/using-selections-2.png diff --git a/doc/chalk/using-selections-3.png b/doc/chalk/using-selections-3.png Binary files differnew file mode 100644 index 00000000..059d2983 --- /dev/null +++ b/doc/chalk/using-selections-3.png diff --git a/doc/chalk/using-selections-4.png b/doc/chalk/using-selections-4.png Binary files differnew file mode 100644 index 00000000..0cfec2cb --- /dev/null +++ b/doc/chalk/using-selections-4.png diff --git a/doc/chalk/using-selections-5.png b/doc/chalk/using-selections-5.png Binary files differnew file mode 100644 index 00000000..c220306d --- /dev/null +++ b/doc/chalk/using-selections-5.png diff --git a/doc/chalk/using-selections-6.png b/doc/chalk/using-selections-6.png Binary files differnew file mode 100644 index 00000000..7c99accd --- /dev/null +++ b/doc/chalk/using-selections-6.png diff --git a/doc/chalk/using-selections.docbook b/doc/chalk/using-selections.docbook new file mode 100644 index 00000000..675088ec --- /dev/null +++ b/doc/chalk/using-selections.docbook @@ -0,0 +1,200 @@ +<chapter id="selections"> +<title>Selections</title> + +<para> +This chapter gives a short introduction on selections. +</para><para> +You can select a part of an image masking off the rest. This is handy when +you want to cut, copy or just modify a part of the image without affecting +the rest. For processing selected objects &chalk; applies a mask. Each pixel of +the selection is processed based on a value of its mask, or the <quote>level +of the selection</quote>, that can range from 0 (unselected) to 255 +(selected). Yes, that is right, you can have fractionally selected pixels. +And by working on individual pixels you can <quote>paint</quote> your selection. +</para><para> +The selection mask is visualized with unselected pixels having a blueish +tint, and selected pixels looking like normal. Fractionally selected pixels +are shown as something in between. Additionally a red border is drawn around +the selected areas. Fractionally selected pixels are inside the border, so +even inside the red border you can possibly see the blueish tint on some pixels. +</para> + +<sect1 id="selections-making"> +<title>Making a selection</title> +<para> +A whole range of tools exist to make selections. From rectangles, ellipses +and freehand to the more exotic like color range select. When you make +several selections they add up. So a rectangle select followed by an +ellipse select select both areas. Later on, you can subtract areas from +the selection by using, for example, the <guilabel>Erase Selection</guilabel> tool. +</para><para> +To get back to normal (no active selection), choose +<menuchoice><guimenu>Select</guimenu><guimenuitem>Deselect</guimenuitem> +</menuchoice>. To select all pixels, choose +<menuchoice><guimenu>Select</guimenu><guimenuitem>Select All</guimenuitem> +</menuchoice>. +</para><para> +You may think that those two actions give the same result, but it +is much more efficient to have no active selection than to have selected +everything. +</para><para> +After having deselected you can bring your selection back by choosing +<menuchoice><guimenu>Select</guimenu><guimenuitem>Reselect</guimenuitem> +</menuchoice>. +</para> +</sect1> + +<sect1 id="selections-painting"> +<title>Painting your selection</title> +<para> +As said above you can essentially paint your selection, and just like +when you paint normally you can choose to paint your selection freehand or +guided with rectangles, ellipses, &etc;. You also have the choice of different +paint tools like pen, brush, airbrush, &etc;. Choose the guide tool, and the +paint tool in the toolbox, and go ahead and <quote>paint</quote> your +selection. +</para><para> +The guide tools work just like you may be used to from other applications. So +holding down shift while drawing a rectangle or an ellipse still forces them to +be a square or a circle respectively. +</para> + +<screenshot> +<screeninfo>Painting a selection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-1.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Painting a selection</phrase> +</textobject> +<caption><para>Painting a selection</para></caption> +</mediaobject> +</screenshot> +<screenshot> +<screeninfo>Painting a selection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-2.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Painting a selection</phrase> +</textobject> +<caption><para>Painting a selection</para></caption> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="selections-unselecting"> +<title>Unselecting</title> +<para> +All the selection paint tools have an option to add or subtract from the +selection. This means that you can use all your familiar tools to both select +and unselect. There is also a true selection eraser among the selection paint +tools. +</para> + +<screenshot> +<screeninfo>Unselecting</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-3.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Unselecting</phrase> +</textobject> +<caption><para>Unselecting</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="selections-making-new"> +<title>Making a new selection</title> +<para> +When you want to make a new selection, replacing the currently active one, you +first need to deselect the active selection. Choose +<menuchoice><guimenu>Select</guimenu><guimenuitem>Deselect</guimenuitem> +</menuchoice>. +</para> +</sect1> + +<sect1 id="selections-contigious"> +<title>Selecting a contiguous area (magic wand)</title> +<para> +To follow the analogy of painting your selection &chalk; also provides an +equivalent to filling a contiguous area. Some paint applications call this +selection tool the magic wand tool. What it does is select the nearby +pixels as long as they have nearly the same color as the pixel you click +on. The selection floods out from the point you click on. In the fuzziness +option you can set how different the colors are allowed to be before the +flooding stops. +</para> + +<screenshot> +<screeninfo>Before the magic wand</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-4.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Before the magic wand</phrase> +</textobject> +<caption><para>Before the magic wand</para></caption> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>A magic wand selection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-5.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>A magic wand selection</phrase> +</textobject> +<caption><para>A magic wand selection</para></caption> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="selections-similar"> +<title>Selecting similar colors</title> +<para> +The <guilabel>Select Similar</guilabel> tool lets you pick a pixel and then select all pixels that +have a similar color. Picking a color in one corner of the image may select a +pixel in another corner if they have similar color. +With the <guilabel>Fuzziness</guilabel> option you can set how similar the colors must be to become +selected. +</para> + +<screenshot> +<screeninfo>Selecting similar colors</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="using-selections-6.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Selecting similar colors</phrase> +</textobject> +<caption><para>Selecting similar colors</para></caption> +</mediaobject> +</screenshot> +</sect1> + +<sect1 id="selections-inverting"> +<title>Inverting the selection</title> +<para> +In some cases it is easier to specify your selection the other way around. That +is, first you select the parts that ultimately should not be selected and then +then you choose +<menuchoice><guimenu>Select</guimenu><guimenuitem>Invert</guimenuitem> +</menuchoice>. +What invert does, is that for every pixel it flips the selection level so to +speak, by setting it to 256 minus the current selection level. Thus what was +selected becomes unselected and vice versa. +</para> +</sect1> + +</chapter> diff --git a/doc/chalk/using-views.docbook b/doc/chalk/using-views.docbook new file mode 100644 index 00000000..e9d184a9 --- /dev/null +++ b/doc/chalk/using-views.docbook @@ -0,0 +1,167 @@ +<chapter id="views"> +<title>Views</title> + +<para> +One of the most important things you need to know when working with a painting +or image editing application, is how to adapt the view of your image to your +(changing) needs. This chapter describes the various possibilities &chalk; +offers. +</para> + +<sect1 id="views-zooming"> +<title>Zooming</title> + +<para> +By zooming, you can view your images at various levels of detail. Zooming out +will show a larger part of the image, but with less detail. &chalk; offers a +couple of options that affect which part of the image is shown: +</para> + +<variablelist> + +<varlistentry><term>Zooming in</term> +<listitem><para>Zooming in allows you to see more details, but you will only +see a smaller part of the image. You can zoom in by choosing the +<menuchoice><guimenu>View</guimenu><guimenuitem>Zoom +in</guimenuitem></menuchoice> menu item, by clicking the +<inlinemediaobject><imageobject><imagedata +fileref="toolbars-button-zoomin.png" format="PNG"/> +</imageobject></inlinemediaobject> <guilabel>Zoom in</guilabel> button on the +toolbar, or by pressing the <keycombo +action="simul">&Ctrl;<keycap>+</keycap></keycombo> keys. +You can zoom in up to 1600% (a 16:1 ratio) via a number of fixed zoom levels. +</para></listitem> +</varlistentry> + +<varlistentry><term>Zooming out</term> +<listitem><para>Zooming out allows you to see a larger part of the image while +losing some detail. Zooming out can be done by choosing the +<menuchoice><guimenu>View</guimenu><guimenuitem>Zoom +out</guimenuitem></menuchoice> menu item, by clicking the +<inlinemediaobject><imageobject><imagedata +fileref="toolbars-button-zoomout.png" format="PNG"/> +</imageobject></inlinemediaobject> <guilabel>Zoom out</guilabel> button on the +toolbar, or by pressing the <keycombo +action="simul">&Ctrl;<keycap>-</keycap></keycombo> keys. +You can zoom out up to 0.2% (a 1:500 ratio) via a number of fixed zoom levels. +</para></listitem> +</varlistentry> + +<varlistentry><term>Going back to 100%</term> +<listitem><para>As viewing your image at its real size is quite handy at +times, you can do so via the +<menuchoice><guimenu>View</guimenu><guimenuitem>Actual +pixels</guimenuitem></menuchoice> menu item or by pressing <keycombo +action="simul">&Ctrl;<keycap>0</keycap></keycombo>. +</para></listitem> +</varlistentry> + +<varlistentry><term>Zooming in and out from the <guilabel>Overview</guilabel> +tab</term> +<listitem><para>The <guilabel>Overview</guilabel> tab of the control box +(usually found at the right hand side of the &chalk; window) also allows you +to change the zoom level by using the slider or the spinbox. Slightly +different zoom levels are available here, so if zooming in or out as described +above does not produce a view you want, you can try using this option. The +<guibutton>1:1</guibutton> button offers another way of getting back to a 100% +zoom.</para></listitem> +</varlistentry> + +<varlistentry><term>Special zooms</term> +<listitem><para>There are two more special ways of zooming. The +<menuchoice><guimenu>View</guimenu><guimenuitem>Fit to +Page</guimenuitem></menuchoice> menu item zooms your image such that it is +as large as possible while remaining entirely visible. The +<menuchoice><guimenu>View</guimenu><guimenuitem>Full Screen +Mode</guimenuitem></menuchoice> menu item (pressing <keycombo +action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo> will also activate +this mode) enlarges the &chalk; window to fill your entire screen, removing +the title bar as well. Although this is not a <quote>real</quote> way of +zooming, it can help you by showing just that little bit more of your +image.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="views-views"> +<title>Working with views</title> + +<para> +Apart from changing the zoom level of your view, you can also open different +views for the same image. This way, you can for example look at two different +parts of your image that would not fit on your screen together otherwise. +</para> + +<variablelist> + +<varlistentry><term>New view windows</term> +<listitem><para>You can open a new &chalk; window for your image by choosing +<menuchoice><guimenu>View</guimenu><guimenuitem>New +View</guimenuitem></menuchoice> Both windows are independent from each other +(so you can select different tools, view different parts of your image, +&etc;), but changes you make to the image in one window are immediately +visible in the other. To close a window, use the normal window closing button. +There is also an option <menuchoice><guimenu>View</guimenu><guimenuitem>Close +All Views</guimenuitem></menuchoice>, which closes all newly created views and +leaves only the original window open.</para></listitem> +</varlistentry> + +<varlistentry><term>Splitting views</term> +<listitem><para>You can also split a window into two views. Like a new window, +one view of a split window has its own settings for brushes, zoom levels and +the like, but both views are shown in the same window. To split your window, +choose <menuchoice><guimenu>View</guimenu><guimenuitem>Split +View</guimenuitem></menuchoice>. The viewing area of the &chalk; window will +then be divided into two halves. You can switch between horizontal and +vertical division with the +<menuchoice><guimenu>View</guimenu><guisubmenu>Splitter +Orientation</guisubmenu></menuchoice> menu, and get back to one view by +choosing <menuchoice><guimenu>View</guimenu><guimenuitem>Remove +View</guimenuitem></menuchoice>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="views-miscellaneous"> +<title>Miscellaneous view options</title> + +<para> +&chalk; also offers two options that can help you with knowing where you are. +</para> + +<variablelist> + +<varlistentry><term>Rulers</term> +<listitem><para>You can have &chalk; show rulers along the sides of your +image, indicating x and y coordinates. To do so, choose +<menuchoice><guimenu>View</guimenu><guimenuitem>Show +Rulers</guimenuitem></menuchoice> or press <keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo>. The rulers will +automatically adapt to your zoom level to show a proper amount of +subdivisions. To remove the rulers, choose the same menu option (now called +<guimenuitem>Hide Rulers</guimenuitem>) or press <keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo> again. </para></listitem> +</varlistentry> + +<varlistentry><term>Grid</term> +<listitem><para>In order to see grid lines, choose +<menuchoice><guimenu>View</guimenu><guimenuitem>Show +Grid</guimenuitem></menuchoice>. You can set the distance between grid lines +with <menuchoice><guimenu>View</guimenu><guisubmenu>Grid +Spacing</guisubmenu></menuchoice> and you can choose different colours for the +lines in the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&chalk;...</guimenuitem></menuchoice> dialog (see <link +linkend="settings-preferences-grid">the Grid section of the Settings +chapter</link>). +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/kchart/index.docbook b/doc/kchart/index.docbook index 8fdfac40..3d9414f7 100644 --- a/doc/kchart/index.docbook +++ b/doc/kchart/index.docbook @@ -1,6 +1,7 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&kchart;"> + <!ENTITY chalk '<application>chalk</application>'> <!ENTITY package "koffice"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> @@ -764,11 +765,11 @@ menu and quit &kchart; with </para> </sect2> <sect2> -<title>Exporting to Graphic Formats: SVG, PNG, JPG, &krita;, &karbon14;, Gimp and +<title>Exporting to Graphic Formats: SVG, PNG, JPG, &chalk;, &karbon14;, Gimp and more</title> <para> For further processing, the chart can also be exported as a graphics file. -Many formats are available. Using either PNG, SVG, JPG or &krita; will likely +Many formats are available. Using either PNG, SVG, JPG or &chalk; will likely produce the best result. </para> <para> @@ -971,7 +972,7 @@ The original document will not be modified.</action> </menuchoice></term> <listitem><para><action>Saves a document to any supported format.</action> The original document will not be modified. You can also choose -among many image formats like PNG, SVG, &krita;, Gimp or JPG. +among many image formats like PNG, SVG, &chalk;, Gimp or JPG. </para></listitem> </varlistentry> diff --git a/doc/kivio/working.docbook b/doc/kivio/working.docbook index 809b8aeb..eb883b67 100644 --- a/doc/kivio/working.docbook +++ b/doc/kivio/working.docbook @@ -83,7 +83,7 @@ <listitem><para>SGI Image (RGB) (.rgb)</para></listitem> <listitem><para>X PixMap Image (.xpm)</para></listitem> <listitem><para>JPEG 2000 Image (.jp2)</para></listitem> -<listitem><para>Krita Document (.kra)</para></listitem> +<listitem><para>Chalk Document (.kra)</para></listitem> <listitem><para>Adobe Illustrator Document (.ai)</para></listitem> <listitem><para>TIFF Image (.tiff)</para></listitem> <listitem><para>ILM EXR Image (.exr)</para></listitem> diff --git a/doc/koffice/index.docbook b/doc/koffice/index.docbook index 4c194a7f..48b90f08 100644 --- a/doc/koffice/index.docbook +++ b/doc/koffice/index.docbook @@ -1,6 +1,7 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&koffice;"> + <!ENTITY chalk '<application>chalk</application>'> <!ENTITY package "koffice"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE" > <!-- change language only here --> @@ -60,7 +61,7 @@ <listitem><para>&kpresenter; (screen and slide presentations)</para></listitem> <listitem><para>&kivio; (a flowchart application)</para></listitem> <listitem><para>Karbon14 (a vector drawing application)</para></listitem> -<listitem><para>&krita; (a pixel based drawing application)</para></listitem> +<listitem><para>&chalk; (a pixel based drawing application)</para></listitem> <listitem><para>&kugar; (a tool for generating business quality reports)</para></listitem> <listitem><para>Kexi (an integrated environment for managing data)</para></listitem> <listitem><para>&kchart; (a charts/graphs generation application)</para></listitem> diff --git a/doc/koshell/index.docbook b/doc/koshell/index.docbook index dc43b5d9..364c925d 100644 --- a/doc/koshell/index.docbook +++ b/doc/koshell/index.docbook @@ -1,6 +1,7 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&koshell;"> + <!ENTITY chalk '<application>chalk</application>'> <!ENTITY package "koffice"> <!ENTITY % English "INCLUDE" > <!ENTITY % addindex "IGNORE"> @@ -57,7 +58,7 @@ Please respect the format of the date (DD/MM/YYYY) and of the version <keyword>KChart</keyword> <keyword>KPlato</keyword> <keyword>Kexi</keyword> -<keyword>Krita</keyword> +<keyword>Chalk</keyword> <keyword>Kivio</keyword> <keyword>Kugar</keyword> <keyword>KFormula</keyword> @@ -85,7 +86,7 @@ Word-processor/Desktop Publishing Program.)</para></listitem> <listitem><para>Kexi (An integrated environment for databases.) </para></listitem> <listitem><para>&kivio; (A flowchart creator.)</para></listitem> <listitem><para><application>Karbon14</application> (A vector drawing program.)</para></listitem> -<listitem><para>&krita; (A pixel based drawing program.)</para></listitem> +<listitem><para>&chalk; (A pixel based drawing program.)</para></listitem> <listitem><para>&kchart; (A chart and graph creator.)</para></listitem> <listitem><para>&kformula; (A formula editor.)</para></listitem> <listitem><para>&kugar; (A report generation tool.) </para></listitem> diff --git a/doc/kword/index.docbook b/doc/kword/index.docbook index 3a07e5c8..0c71b947 100644 --- a/doc/kword/index.docbook +++ b/doc/kword/index.docbook @@ -1,6 +1,7 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&kword;"> + <!ENTITY chalk '<application>chalk</application>'> <!ENTITY % addindex "IGNORE"> <!ENTITY fundamentals SYSTEM "fundimentals.docbook"> <!ENTITY tutorial SYSTEM "tutorial.docbook"> @@ -117,7 +118,7 @@ Environment. Other applications in &koffice; include: <listitem><para>&kpresenter; (A presentation creator.)</para></listitem> <listitem><para>&karbon14; (A vector drawing program.)</para></listitem> <listitem><para>&kivio; (A flowchart creator)</para></listitem> -<listitem><para>&krita; (A pixel based drawing program.)</para></listitem> +<listitem><para>&chalk; (A pixel based drawing program.)</para></listitem> <listitem><para>&kugar; (A report generation tool.) </para></listitem> <listitem><para>&kexi; (An integrated environment for databases.) </para></listitem> <listitem><para>&kchart; (A chart and graph creator.)</para></listitem> |
