From kde-commits  Sun Oct 21 06:48:58 2007
From: Clarence Dang <dang () kde ! org>
Date: Sun, 21 Oct 2007 06:48:58 +0000
To: kde-commits
Subject: branches/KDE/3.5/kdegraphics/kolourpaint
Message-Id: <1192949338.513329.5500.nullmailer () svn ! kde ! org>
X-MARC-Message: https://marc.info/?l=kde-commits&m=119294934417270

SVN commit 727599 by dang:

+APIDoc adapted from trunk/


 M  +24 -0     kpmainwindow.h  
 M  +11 -1     kpselectiontransparency.h  


--- branches/KDE/3.5/kdegraphics/kolourpaint/kpmainwindow.h #727598:727599
@@ -224,6 +224,30 @@
     bool toolIsTextTool () const;
 
     kpSelectionTransparency selectionTransparency () const;
+    // The drawing background color is set to <transparency>.transparentColor()
+    // if the <transparency> is in Transparent mode or if <forceColorChange>
+    // is true (not the default).  [x]
+    //
+    // If <transparency> is in Opaque mode and <forceColorChange> is false,
+    // the background color is not changed because:
+    //
+    //   1. It is ignored by the selection in Opaque mode anyway.
+    //   2. This avoids irritating the user with an unnecessary background
+    //      color change.
+    //
+    // The only case where you should set <forceColorChange> to true is in
+    // kpToolSelectionTransparencyCommand to ensure that the state
+    // is identical to when the command was constructed.
+    // Later: I don't think setting it to true is ever necessary since:
+    //
+    //          1. The background color only counts in Transparent mode.
+    //
+    //          2. Any kpToolSelectionTransparencyCommand that switches to
+    //             Transparent mode will automatically set the background
+    //             color due to the first part of [x] anyway.
+    //
+    // The other fields of <transparency> are copied into the main window
+    // as expected.
     void setSelectionTransparency (const kpSelectionTransparency &transparency,
                                    bool forceColorChange = false);
     int settingSelectionTransparency () const;
--- branches/KDE/3.5/kdegraphics/kolourpaint/kpselectiontransparency.h #727598:727599
@@ -39,10 +39,18 @@
     kpSelectionTransparency ();
     // Selection that's transparent at pixels with <color>
     kpSelectionTransparency (const kpColor &transparentColor, double colorSimilarity);
+    // If <isOpaque>, <transparentColor> is allowed to be anything
+    // (including invalid) as the color would have no effect.
+    // However, you are encouraged to set it as you would if !<isOpaque>,
+    // because setTransparent(true) might be called later, after which
+    // the <transparentColor> would suddenly become important.
+    //
+    // It is a similar case with <colorSimilarity>, although <colorSimilarity>
+    // must be in-range (see kpColorSimilarityDialog).
     kpSelectionTransparency (bool isOpaque, const kpColor &transparentColor, double colorSimilarity);
     // Returns whether they are visually equivalent.
     // This is the same as a memcmp() except that if they are both opaque,
-    // this function will return true regardless of the transaprentColor's.
+    // this function will return true regardless of the transparentColor's.
     bool operator== (const kpSelectionTransparency &rhs) const;
     bool operator!= (const kpSelectionTransparency &rhs) const;
     ~kpSelectionTransparency ();
@@ -52,6 +60,8 @@
     void setOpaque (bool yes = true);
     void setTransparent (bool yes = true);
 
+    // If isOpaque(), transparentColor() is generally not called because
+    // the transparent color would have no effect.
     kpColor transparentColor () const;
     void setTransparentColor (const kpColor &transparentColor);