# $EPIC: window_activity_handling.txt,v 1.3 2007/02/19 03:20:46 jnelson Exp $
======Synopsis:======
[[windowctl]](SET //<winref>// CURRENT_ACTIVITY //<number>//) \\
[[windowctl]](SET //<winref>// ACTIVITY_FORMAT //<number>// //<string>//) \\
[[windowctl]](SET //<winref>// ACTIVITY_DATA //<number>// //<string>//)

======Description:======
This feature gives you, through the %E [[set status_format|status line expando]]
a fully customizable replacement for the %F status line expando.  This is 
specifically intended to be able to create irssi-like colorized window
activity notification on your status bar.  See the [[activity]] script for 
a sample use of these features.

The %F status line expando tells you which [[window_hide|hidden windows]] 
have had output since they were hidden.  You can always turn this feature off
for each window with [[window notify]].  You cannot control the
appearance of the window's refnum with %F

The %E status line expando performs the same task, but you can control how
the window refnum appears on a per-window basis.

Each window has associated with itself 11 **activity levels**, numbered 0 
to 11.  Activity level 0 is special, because it stores default values.
There is nothing special about the other levels, you can make them mean 
whatever you wish.  For each activity level, you may associate one 
**activity format**, and one **activity data**.   It is expected you will 
ordinarily not change the **activity format** often, but will change the 
**activity data**.

Each time the status bar is regenerated, for each window that is hidden, 
that has had output since it was hidden, the client looks at the 
**current activity** level.  It expands the corresponding **activity format**
using the corresponding **activity data** as the value of $*, and then 
uses the resulting value as the name of the window, in %E.

The default values for all these values are the empty string.  If you set
the **activity_format** or **activity_data** for level 0, that acts as a 
default for all the other levels that don't have values.  Unless you actually
set values, nothing will appear in %E.

======What is the point of all this?======
This allows you to have colorific notify levels in the way irssi does:

	on #window_create -110 *  {
	   @windowctl(set $0 activity_format 0 ^C3$$*);
	   @windowctl(set $1 activity_format 1 ^C4$$*);
	   @windowctl(set $1 activity_format 2 ^C7<$$*>);

	   @windowctl(set $0 activity_data 0 booya)
	   @windowctl(set $0 activity_data 2 hazmat)
	}

======Let's consider a few examples:======

=====Example 1:=====
If I were to 
	@windowctl(SET //<refnum>// CURRENT_ACTIVITY 1)
then it would use
	^C3$$*
as the format string (because it is specifically set), and
	booya
as the data string (because it is **not** specifically set, so it uses level 0)
which would result in a green "booya" for this window.

=====Example 2:=====
If I were to
	@windowctl(SET //<refnum>// CURRENT_ACTIVITY 2)
then it would use
	^C4$$*
as the format string (because it is specifically set), and
	hazmat
as the data string (because it is specifically set), which would result in a
bold red "hazmat" for this window.

======Summary:======
This feature gives you full control to customize everything that %F does.
You could associate an event with each level (msgs = 1, publics = 2, 
notices = 3, joins = 4, etc), a color with each level (red = 1, blue = 2,
green = 3, yellow = 4, etc), and any string you desire for each window.
Then using some very simple [[on]]s,
	on #-public -110 * {
	   if (windowctl(GET $winchan($1) CURRENT_ACTIVITY) < 2) {
	      @windowctl(SET $winchan($1) CURRENT_ACTIVITY 2)
	   }
	}
	on #-join -110 * {
	   if (windowctl(GET $winchan($1) CURRENT_ACTIVITY) < 4) {
		@windowctl(SET $winchan($1) CURRENT_ACTIVITY 4)
	   }
	}
it would all automagically allow you to have different windows show up in 
different colors on your status bar, depending on what happened last!

======History:======
Window activity handling first appeared in EPIC5-0.0.6.