Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

2 files changed, 235 insertions, 0 deletions

diff --git a/doc/kcontrol/icons/Makefile.am b/doc/kcontrol/icons/Makefile.am
new file mode 100644
index 000000000..9de711f69
--- /dev/null
+++ b/doc/kcontrol/icons/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = kcontrol/icons
diff --git a/doc/kcontrol/icons/index.docbook b/doc/kcontrol/icons/index.docbook
new file mode 100644
index 000000000..199a35275
--- /dev/null
+++ b/doc/kcontrol/icons/index.docbook
@@ -0,0 +1,233 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
+"dtd/kdex.dtd" [
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<article lang="&language;">
+<articleinfo>
+
+<authorgroup>
+<author>&Mike.McBride; &Mike.McBride.mail;</author>
+<author>&Jost.Schenck; &Jost.Schenck.mail;</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2003-09-22</date>
+<releaseinfo>3.2</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KControl</keyword>
+<keyword>icon</keyword>
+</keywordset>
+</articleinfo>
+<sect1 id="icons">
+<title>Icons</title>
+
+<sect2 id="icons-intro">
+<title>Introduction</title>
+
+<para>&kde; comes with a full set of icons in several sizes. These icons
+are being used all over &kde;: the desktop, the panel, the &konqueror; file
+manager, in every toolbar of every &kde; application, etc. The icons
+control module offers you very flexible ways of customizing the way &kde;
+handles icons. You can:</para>
+
+<itemizedlist>
+<listitem><para>install and choose icon themes</para></listitem>
+<listitem><para>choose different icon sizes</para></listitem>
+<listitem><para>assign effects to icons (for example make them
+semi-transparent or colorize them) </para></listitem>
+<listitem><para>configure these settings for each of the different places
+icons will be used in: for example the desktop, toolbars &etc;
+</para></listitem>
+</itemizedlist>
+
+<important><para>Please note that some of these settings may depend on
+your selected icon theme. &kde; comes with two icon themes by default,
+&kde;-Classic (HiColor) and Crystal SVG.  There is also a low color theme
+in the kdeartwork package, along with others.</para></important>
+
+</sect2>
+
+<sect2 id="icon-theme">
+<title><guilabel>Theme</guilabel></title>
+
+<para>Starting at the top, you can see some example icons.  These change
+in appearance depending on the icon theme you select. Most default
+installations will have only one icon theme available, the &kde; default
+Crystal SVG theme.  There are others contained separately in the
+kdeartwork package, and you can download more from the Internet.</para>
+
+<para>Use the <guibutton>Install New Theme...</guibutton> to browse to the
+location of newly downloaded themes, and they will then become available 
+to select from above.</para>
+
+</sect2>
+
+<sect2 id="icons-use">
+<title>Advanced</title>
+
+<para>Looking at this second page of the icons control module, you
+will see two areas:</para>
+
+<itemizedlist> 
+<listitem> 
+<para>An area labelled <guilabel>Use of Icon</guilabel>. Here you can
+choose which particular usage of icons you want to configure, for
+example <guilabel>Toolbar</guilabel> or <guilabel>Panel</guilabel>.</para> 
+</listitem> 
+
+<listitem> <para>A preview area where you can see how
+icons of the selected kind will look using the current
+settings. Note that the state of this preview also depends on the icon
+state selected in the effects below (do not worry
+about that now, we will explain that below). </para> </listitem>
+</itemizedlist>
+
+<para>When you want to configure icons, first select the usage of icons
+you want to configure. Change the settings until you like the
+preview. You can then choose a different icon usage and configure
+that. At the end, if you are satisfied with your settings, click
+<guibutton>OK</guibutton> or <guibutton>Apply</guibutton> to take the
+changes in effect.</para>
+
+<para>There are two further options to consider,
+<guilabel>Size</guilabel> and <guilabel>Effects</guilabel>. </para>
+
+<sect3 id="icons-use-size">
+<title>Icon Size</title>
+
+<para>You have two options relating to icon sizes. First, you can choose
+from a list of icon sizes. Second, you can tell &kde; to draw all icons
+using double sized pixels. The largest icon sizes are especially useful
+for visually impaired people.</para>
+
+<para>Which sizes will be offered by the icon size listbox depends on
+the icon theme you have selected in the icon themes control module. For
+example, the low color icon theme only offers the sizes 16 and 32 for
+desktop icons and 16, 22 and 32 for toolbar icons. The HiColor theme
+offers icon sizes 16, 32 and 48 as well as sizes from 64 to 128.
+However, as &kde; can not have all these icon sizes in store, icons
+using size 64 to 128 will be automatically generated which may result in
+a loss of quality.</para>
+
+<para>If the icon sizes offered by your chosen icon theme are not enough
+for you, there is still the option <guilabel>Double-sized
+pixels</guilabel>. If this option is selected, all icons will have
+double sized pixels, &ie; a 2x2 block instead of normal pixels. While
+this makes it possible to achieve very large icon sizes, the quality is
+poor: icons will look <quote>blocky</quote>, an effect you may remember
+if you've grown up using a Sinclair ZX Spectrum or similar. If this is
+an option for you, using the large sizes offered by &kde;'s HiColor
+icon theme will always result in a much better quality than using the
+low color icon theme with double sized pixels.</para> 
+<!-- 
+<para>You can also choose to have smoothed icons, an effect similar to
+anti-aliasing of fonts.  Enable the checkbox <guilabel>Blend alpha
+channel</guilabel> to see this in action, but note that it will slow
+down graphics on a slower computer.</para>
+-->
+
+<para>You can also choose animated icons. Many of the icons have
+animations associated with them.  Enable the checkbox labelled
+<guilabel>Animate Icons</guilabel>, to enable this effect, but note
+that it may appear slow or jerky if your graphics card is old or you
+are low on memory.</para>
+
+</sect3>
+
+<sect3 id="icons-use-effects">
+<title>Effects</title>
+
+<para>Finally you can configure certain <quote>filters</quote> to be
+applied on icons which are in one of three states:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Default</guilabel></term>
+<listitem><para>This is how the icon will look normally.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Active</guilabel>:</term>
+<listitem><para>This is how the icon will look when the mouse cursor is over the icon.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Disabled</guilabel>:</term>
+<listitem><para>This is how the icon will look if its corresponding action is
+disabled, &ie; clicking on it will not lead to any
+result.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Select one of these states, and press the <guibutton>Set
+Effect...</guibutton> button to configure a corresponding icon effect.
+Please note that this configuration will only affect icons of the
+currently selected <guilabel>Use of Icon</guilabel> category (see
+above): configuring an effect for active icons, while
+<guilabel>Toolbar</guilabel> icon usage is selected, will
+<emphasis>not</emphasis> affect active icons used in other
+places.</para>
+
+<para>Below the list of icon states there are two options: you can
+configure an effect and you can select the
+<guilabel>Semi-transparent</guilabel> option, which will make the
+background <quote>shine through</quote> the icon. To the right of the
+effects list box there is a slider button to pass additional parameters to
+a filter for colours and <guilabel>Amount</guilabel>.</para>
+<!-- TODO: Figure out what 'amount' really means -->
+
+<para>The following effects can be applied to icons:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>No Effect</guilabel>:</term>
+<listitem><para>Icons will be used without applying any
+effect.</para></listitem> 
+</varlistentry>
+<varlistentry>
+<term><guilabel>To Gray</guilabel>:</term>
+<listitem><para>This filter will apply a grayish look to the icon. Click
+<guibutton>Setup...</guibutton> to configure the intensity of this filter. Note
+that it is customary for most user interfaces to use this effect for disabled
+icons only.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Colorize</guilabel>:</term>
+<listitem><para>Icons will be colorized using a custom color. For example, you
+may configure active icons (&ie; the icon the mouse cursor is over) to
+shine golden. Use the color and <guilabel>Amount</guilabel> buttons to configure the used color and the intensity of the colorization.</para></listitem> 
+</varlistentry>
+<varlistentry>
+<term><guilabel>Gamma</guilabel>:</term>
+<listitem><para>A different gamma value will be applied to all icons. If you're
+no photographer and don't know what Gamma is: it's quite similar to what people
+call contrast. Just play around with the gamma settings by clicking on
+<guibutton>Setup...</guibutton> to get a feeling for this
+effect.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Desaturate</guilabel>:</term>
+<listitem><para>Icons will be drawn desaturated. This is quite similar to the
+<quote>Color</quote> setting on your television. Click
+<guibutton>Setup...</guibutton> to configure the amount of desaturation.
+</para></listitem> 
+</varlistentry>
+<varlistentry>
+<term><guilabel>To Monochrome:</guilabel></term>
+<listitem>
+<para>Icons will be drawn using only the two colours selected.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+</article>