group: Added some comments and descriptions to the functions in tab.c -- not finished yet... still a lot of work needed..

git-svn-id: file:///beryl/trunk@4057 d7aaf104-2d23-0410-ae22-9d23157bf5a3

1 files changed, 85 insertions, 3 deletions

diff --git a/beryl-plugins/src/group/tab.c b/beryl-plugins/src/group/tab.c
index 75ca2b3..73ee521 100644
--- a/beryl-plugins/src/group/tab.c
+++ b/beryl-plugins/src/group/tab.c
@@ -27,6 +27,10 @@
 /*
  * groupGetCurrentMousePosition
  *
+ * Description:
+ * Return the current function of the pointer at the given screen.
+ * The position is queried trough XQueryPointer directly from the xserver.
+ *
  */
 Bool groupGetCurrentMousePosition(CompScreen *s, int *x, int *y)
 {
@@ -50,6 +54,13 @@ Bool groupGetCurrentMousePosition(CompScreen *s, int *x, int *y)
 /*
  * groupGetWindowTitle - mostely copied from state.c
  *
+ * Description:
+ * Gets the title of a window. It uses the XGetWindowProperty
+ * method which gets several paramters and returns a utf8-string
+ * which is important for other languages.
+ * This function is mostely used to get the title of a window for the
+ * hover-text in the tab bar.
+ *
  */
 static char *groupGetWindowTitle(CompWindow *w)
 {
@@ -83,8 +94,8 @@ static char *groupGetWindowTitle(CompWindow *w)
 	}
 
 
-	retval = (char *)malloc(sizeof(char) * (nitems + 1));
-	strncpy(retval, (char *)val, nitems);
+	retval = (char *) malloc(sizeof(char) * (nitems + 1));
+	strncpy(retval, (char *) val, nitems);
 	retval[nitems] = '\0';
 
 	XFree(val);
@@ -95,6 +106,15 @@ static char *groupGetWindowTitle(CompWindow *w)
 /*
  * groupGetClippingRegion
  *
+ * Description:
+ * This function returns a clipping region which is used to clip
+ * several events involving window stack such as hover detection
+ * in the tab bar or Drag'n'Drop. It creates the clipping region
+ * with getting the region of every window above the given window
+ * and then adds this region to the clipping region using
+ * XUnionRectWithRegion. w->region won't work since it doesn't include
+ * the window decoration.
+ *
  */
 Region groupGetClippingRegion(CompWindow *w)
 {
@@ -123,6 +143,14 @@ Region groupGetClippingRegion(CompWindow *w)
 /*
  * groupTabBarTimeout
  *
+ * Description:
+ * This function is called when the time expired (== timeout).
+ * We use this to realize a delay with the bar hiding after tab change.
+ * groupHandleAnimation sets up a timer after the animation has finished.
+ * This function itself basically just sets the tab bar to a PaintOff status
+ * through calling groupSetTabBarVisibility. The PERMANENT mask allows you to fore
+ * a hiding of even PaintPermanentOn tab bars.
+ *
  */
 static Bool 
 groupTabBarTimeout(void *data)
@@ -139,6 +167,13 @@ groupTabBarTimeout(void *data)
 /*
  * groupCheckForVisibleTabBars
  *
+ * Description:
+ * This function is used to update the gs->tabBarVisible
+ * attribute which is used in groupPaintScreen to do add
+ * a PAINT_SCREEN_WITH_TRANSFORMED_WINDOWS_MAS mask to the
+ * screen mask. It checks if there are any tab bar's with
+ * a PaintState which is no PaintOff on the given screen.
+ *
  */
 void
 groupCheckForVisibleTabBars(CompScreen *s)
@@ -159,6 +194,18 @@ groupCheckForVisibleTabBars(CompScreen *s)
 /*
  * groupTabSetVisibility
  *
+ * Description:
+ * This function is used to set the visibility of the tab bar.
+ * The "visibility" is indicated through the PaintState, which
+ * can be PaintOn, PaintOff, PaintFadeIn, PaintFadeOut
+ * and PaintPermantOn.
+ * Currently the mask paramater is mostely used for the PERMANENT mask.
+ * This mask affects how the visible parameter is handled, for example if
+ * visibule is set to TRUE and the mask to PERMANENT state it will set
+ * PaintPermanentOn state for the tab bar. When visibile is FALSE, mask 0
+ * and the current state of the tab bar is PaintPermanentOn it won't do anything
+ * because its not strong enough to disable a Permanent-State, for those you need
+ * the mask.
  */
 void groupTabSetVisibility(GroupSelection *group, Bool visible, unsigned int mask)
 {
@@ -213,6 +260,10 @@ void groupTabSetVisibility(GroupSelection *group, Bool visible, unsigned int mas
 /*
  * groupGetDrawOffsetForSlot
  *
+ * Description:
+ * Its used when the draggedSlot is dragged to another viewport.
+ * It calculates a correct offset to the real slot position.
+ *
  */
 void
 groupGetDrawOffsetForSlot(GroupTabBarSlot *slot, int *hoffset, int *voffset)
@@ -258,6 +309,11 @@ groupGetDrawOffsetForSlot(GroupTabBarSlot *slot, int *hoffset, int *voffset)
 /*
  * groupHandleHoverDetection
  *
+ * Description:
+ * This function is called from groupPreparePaintScreen to handle
+ * the hover detection. This is needed for the text showing up,
+ * when you hover a thumb on the thumb bar.
+ *
  */
 void groupHandleHoverDetection(GroupSelection *group)
 {
@@ -273,8 +329,10 @@ void groupHandleHoverDetection(GroupSelection *group)
 		int mouseX, mouseY;
 		Bool mouseOnScreen;
 		
+		// first get the current mouse position
 		mouseOnScreen = groupGetCurrentMousePosition(group->screen, &mouseX, &mouseY);
 
+		// then check if the mouse is in the last hovered slot -- this saves a lot of CPU usage
 		if (mouseOnScreen && !(bar->hoveredSlot && XPointInRegion(bar->hoveredSlot->region, mouseX, mouseY)))
 		{
 			bar->hoveredSlot = NULL;
@@ -285,6 +343,9 @@ void groupHandleHoverDetection(GroupSelection *group)
 			GroupTabBarSlot *slot;
 			for (slot = bar->slots; slot; slot = slot->next)
 			{
+				// We need to clip the slot region with the clip region first.
+				// This is needed to respect the window stack, so if a window
+				// covers a port of that slot, this part won't be used for in-slot-detection.
 				Region reg = XCreateRegion();
 				XSubtractRegion(slot->region, clip, reg);
 
@@ -299,6 +360,7 @@ void groupHandleHoverDetection(GroupSelection *group)
 
 			XDestroyRegion(clip);
 			
+			// trigger a FadeOut of the text
 			if ((bar->textLayer->state == PaintFadeIn || bar->textLayer->state == PaintOn) &&
 			    bar->hoveredSlot != bar->textSlot)
 			{
@@ -307,6 +369,7 @@ void groupHandleHoverDetection(GroupSelection *group)
 				bar->textLayer->state = PaintFadeOut;
 			}
 			
+			// or trigger a FadeIn of the text
 			else if (bar->textLayer->state == PaintFadeOut && bar->hoveredSlot == bar->textSlot && bar->hoveredSlot)
 			{
 				bar->textLayer->animationTime = (gs->opt[GROUP_SCREEN_OPTION_FADE_TEXT_TIME].value.f * 1000)
@@ -320,6 +383,11 @@ void groupHandleHoverDetection(GroupSelection *group)
 /*
  * groupHandleTabBarFade
  *
+ * Description:
+ * This function is called from groupPreparePaintScreen
+ * to handle the tab bar fade. It checks the animationTime and updates it,
+ * so we can calculate the alpha of the tab bar in the painting code with it.
+ *
  */
 void groupHandleTabBarFade(GroupSelection *group, int msSinceLastPaint)
 {
@@ -333,6 +401,7 @@ void groupHandleTabBarFade(GroupSelection *group, int msSinceLastPaint)
 		if (bar->animationTime < 0)
 			bar->animationTime = 0;
 
+		// Fade finished
 		if (bar->animationTime == 0)
 		{
 			if (bar->state == PaintFadeIn) {
@@ -360,6 +429,11 @@ void groupHandleTabBarFade(GroupSelection *group, int msSinceLastPaint)
 /*
  * groupHanldeTextFade
  *
+ * Description:
+ * This function is called from groupPreparePaintScreen
+ * to handle the text fade. It checks the animationTime and updates it,
+ * so we can calculate the alpha of the text in the painting code with it.
+ *
  */
 void groupHandleTextFade(GroupSelection *group, int msSinceLastPaint)
 {
@@ -370,6 +444,7 @@ void groupHandleTextFade(GroupSelection *group, int msSinceLastPaint)
 	if (!textLayer)
 		return;
 
+	// Fade in progress...
 	if ((textLayer->state == PaintFadeIn || textLayer->state == PaintFadeOut) &&
 	    textLayer->animationTime > 0)
 	{
@@ -377,7 +452,8 @@ void groupHandleTextFade(GroupSelection *group, int msSinceLastPaint)
 		
 		if (textLayer->animationTime < 0)
 			textLayer->animationTime = 0;
-			
+		
+		// Fade has finished.
 		if (textLayer->animationTime == 0) {
 			if (textLayer->state == PaintFadeIn)
 				textLayer->state = PaintOn;
@@ -408,6 +484,11 @@ void groupHandleTextFade(GroupSelection *group, int msSinceLastPaint)
 /*
  * groupHandleTabChange
  *
+ * Description:
+ * This function is also called from groupPreparePaintScreen to handle
+ * the tab change. It moved the new topTab on the screen as well as doing
+ * the initial set for the tab change animation.
+ *
  */
 static void
 groupHandleTabChange(CompScreen *s, GroupSelection *group)
@@ -417,6 +498,7 @@ groupHandleTabChange(CompScreen *s, GroupSelection *group)
 	if (!group || !HAS_TOP_WIN(group) || !group->changeTab)
 		return;
 
+	// exit when there is a rotate or plane animation
 	if (screenGrabExist(s, "rotate", "plane", 0))
 		return;