<h2>Documentation for fbpanel project</h2>
<ol>
  <li><a href="#buildingf">Building fbpanel</a></li>
  <li><a href="#running">Running</a></li>
  <li><a href="#config">Configuring</a>
    <ol>
      <li><a href="#configstructure">Configuration file structure</a></li>
      <li><a href="#configglobal">Global section</a></li>
      <li><a href="#configplugin">Plugin section</a></li>
      <li><a href="#configpluginextra">Plugins with additional configuration</a></li>
    </ol>
  </li>
</ol>
<br/>
<hr/>
<a name="buildingf"><h3>Building fbpanel</h3></a>

The following is what you will need to compile fbpanel:
  <ul>
    <li><a href="http://www.gtk.org">GTK+-2.4</a> headers and libraries
        (development package)</li>
  
  </ul>


<p>
Once you have the above dependancies installed, you are ready to build
fbpanel.
</p>


<pre>
% <b>tar zxvf fbpanel-x.y.tgz</b>     #...untar the fbpanel archive 
% <b>cd fbpanel-x.y</b>               #...cd inside the source tree
% <b>./configure</b>                  #...prepare source for compiling
% <b>make</b>                         #...fbpanel builds...
% <b>su</b>                           #...become root
% <b>make install</b>                 #...do install
</pre>

<br/><br/><a href="#top"><img src="images/top.png" alt="top"/></a><hr/>


<a name="running"><h3>Running</h3></a>
Simple like that...
<pre>
% <b>fbpanel &amp;</b>          # use default profile
% <b>fbpanel -p abc &amp;</b>   # use profile abc, create it if needed
</pre>

<br/><br/><a href="#top"><img src="images/top.png" alt="top"/></a><hr/>


<a name="config"><h3>Configuring</h3></a>
fbpanel stores its configurations in <tt>~/.config/fbpanel</tt> directory. Every profile
is represented by a single text file with a same name. Name of default profile
is <tt>default</tt>. Edit relevant file and restart fbpanel. You can also tell
running fbpanel to reload its configuration by sending it USR1 signal.
<pre>
% <b>vi ~/.config/fbpanel/default</b>  
% <b>killall -USR1 fbpanel       </b>  # tell fbpanel to reload configuration
</pre>
In addition, there is configuration GUI that covers all panel's options, but not plugins yet.
To get it, click <tt><b>Ctrl-Button2</b></tt> anywhere in panel or run it with <tt>-C</tt> option
<br/>
<br/>
<h4><a name="configstructure">Configuration file structure</h4></a>
Configuration file consists from one <b>Global</b> section, that covers panel
options, and one or more <b>Plugin</b> sections.<br/>The syntax is following: 
<ul>
<li>Spaces at the begining and at the end of a line are ignored</li>
<li>Lines strarting with '#' or blank lines are ignored. '#' in any other place
is NOT treated as comment</li>
<li>Variable's name is NOT case sensitive</li>
<li>Variable's value IS case sensitive</li>
<li>Variable's value is a text from first non-blank char after '='  till the last non-blank char.</li>
<li>Section starts by its type (Global or Plugin) and "{' on a same line, 
    then inner variables and sections, and ends with '}' on separate line.</li>
</ul>

<h4><a name="configglobal">Global section</h4></a>
It describes global panel parameters like position, size and some NETWM settings.<br/>
If variable has default value, it can be omited.
The full variable list is:
<ul>
  <li><b>Edge</b> - screen edge<br/>
    Legal values are left, right, top or bottom. <br/>Default is bottom.
  </li>

  <li><b>Allign</b> - allignment of a panel<br/>
    Legal values are left, right or center. <br/>Default is center.
  </li>
  
  <li><b>WidthType</b> - units of width<br/>
    Legal values are
    <ul>
      <li>pixel - width is number of pixels</li>
      <li>percent - width is percent of an edge</li>
      <li>request - follow widgets' size requests. can shrink or grow dynamically</li>
    </ul>
    Default is percent.
  </li>
  
  <li><b>Width</b> - panel width in widthtype units<br/>
    Legal values are numbers. <br/>Default is 100.
  </li>
  
   <li><b>HeightType</b> - units of height<br/>
    Legal values are
    <ul>
      <li>pixel - height is number of pixels</li>
    </ul>
    Default is pixel.
  </li>
  
  <li><b>Height</b> - panel height in heighttype units<br/>
    Legal values are numbers. <br/>Default is 26.
  </li>
  
  <li><b>Margin</b> - margin from screen edge for left or right allignment.
    Legal values are numbers. <br/>Default is 0.
  </li>
  
  <li><b>SetDockType</b> - set panel's NETWM window type to Dock
    Legal values are true or false. <br/>Default is true.
  </li>
  <li><b>SetPartialStrut</b> - ask NETWM compliant window manager to not cover panel
    by maximized windows. 
    Legal values are true or false. <br/>Default is true.
  </li>
 
  <li><b>Transparent</b> - enable transparent background
    Legal values are true or false. <br/>Default is false.
  </li>
  
  <li><b>TintColor</b> - color to composite on root background
    Legal values are colors, eg 0xRRGGBB or red, black etc. <br/>Default is white.
  </li>
  <li><b>Alpha</b> - transparency of the tint color
    Legal values are numbers from 0 to 255. <br/>Default is 127.
  </li>
  <li><b>Autohide</b> - hide panel when mouse is far enough
    Legal values are true or false.<br/>Default is false.
  </li>
  <li><b>RoundCorners</b> - panel has rounded corners
    Legal values are true or false.<br/>Default is true.
  </li>
  <li><b>RoundCornersRadius</b> - radius of ronded corners.
    Legal values are numbers from 0 to 25. <br/>Default is 7.
  </li>
  <li><b>Layer</b> - stacking layer of a panel
    Legal values are above or below. <br/>Default is above.
  </li>
  <li><b>SetLayer</b> - set or not stacking layer of panel. If not, defaul WM policy
    is used.
    Legal values are true or false.<br/>Default is false.
  </li>
  <li><b>MaxElemHeight</b> - maximal height of plugins' lements, like icons, messages etc.
    If plugin has more space, it can place elements in multiple rows.
    Legal values are numbers from 10 to 200.<br/>Default is 200
  </li>
</ul>
For example:
<pre>
Global {
    edge = bottom
    allign = center
    margin = 0
    widthtype = percent
    width = 92
    height = 48
    transparent = true
    tintcolor = #ffffff
    alpha = 32
    setdocktype = true
    setpartialstrut = true
    autohide = false
    heightWhenHidden = 2
    roundcorners = false
    roundcornersradius = 7
    layer = above
    setlayer = false
    maxelemheight = 24
}
</pre>
<br/>
<h4><a name="configplugin">Plugin section</h4></a>
It describes which plugin to load, how to position it and has plugin specific configuration
section. If variable has default value, it can be omited.
The full variable list is:
<ul>
  <li><b>type</b> - plugin type<br/>
    Legal values are battery, cpu, dclock, deskno, deskno2, genmon, icons,
    image, launchbar, mem, menu, net, pager, separator, space, systray,
    taskbar, tclock, volume, wincmd <br/>Mandatory.
  </li>
   <li><b>expand</b> - expand plugin if extra space is available<br/>
    Legal values are true or false<br/>Default is false
   </li>
  <li><b>padding</b> - padding around plugin in pixels<br/>
    Legal values are numbers<br/>Default is 0
  </li>
  <li><b>config</b> - a section with plugin specific configuration.
  </li>
</ul>  
For example:
<pre>
Plugin {
    type = space
    expand = false
    padding = 0
    config {
        size = 2
    }
}

Plugin {
    type = cpu
}
</pre>
<br/>
<h4><a name="configpluginextra">Plugins with additional configuration</h4></a>
<h4><a name="xx">Cpu</h4></a>
<ul>
  <li><b>color</b> - chart color<br/>
    Legal values are colors eg 0xRRGGBB or red, black etc. <br/>Default is green.
  </li>
</ul>  
For example:
<pre>
Plugin {
    type = cpu
    config {
        Color = green
    }
}
</pre>
<h4><a name="xx">Net</h4></a>
<ul>
  <li><b>interface</b> - interface to watch<br/>
    Legal values are network interface names.<br/>Default is eth0.
  </li>
  <li><b>TxColor</b> - color of Tx traffic<br/>
    Legal values are colors.<br/>Default is violet.
  </li>
  <li><b>RxColor</b> - color of Rx traffic<br/>
    Legal values are colors.<br/>Default is blue.
  </li>
  <li><b>TxLimit</b> - Tx limit of the connection, in KB/s.
    Used to scale chart properly<br/>
    Legal values are numbers.<br/>Default is 12.
  </li>
  <li><b>RxLimit</b> - Rx limit of the connection, in KB/s.
    Used to scale chart properly<br/>
    Legal values are numbers.<br/>Default is 120.
  </li>
</ul>
For example:
<pre>
Plugin {
    type = net
    config {
        interface = eth0
        TxLimit = 20
        RxLimit = 190
        TxColor = violet
        RxColor = blue
    }
}
</pre>
<h4><a name="xx"></a>Pager</h4>
<ul>
  <li><b>ShowWallpaper</b> - show desktop wallpaper in pager window or not<br/>
    Legal values are true or false.<br/>Default is true.
  </li>
</ul>
For example:
<pre>
Plugin {
    type = pager
    config {
        showwallpaper = true
    }
}
</pre>

<h4><a name="xx"></a>Space</h4>
<ul>
  <li><b>size</b> - size of space to occupy in pixels<br/>
    Legal values are numbers.<br/>Default is 1.
  </li>
</ul>
For example:
<pre>
Plugin {
    type = space
    config {
        size = 15
    }
}
</pre>


<h4><a name="xx"></a>Mem</h4>
<ul>
  <li><b>ShowSwap</b> - show swap usage or not<br/>
    Legal values are true or false<br/>Default is false.
  </li>
</ul>
For example:
<pre>
Plugin {
    type = mem
    config {
        ShowSwap = true
    }
}
</pre>

<h4><a name="xx"></a>dclock</h4>
<ul>
  <li><b>ShowSeconds</b> - show secondsor not<br/>
    Legal values are true or false<br/>Default is false.
  </li>
  <li><b>HoursView</b> - 24h or 12h hours view<br/>
    Legal values are 12 or 24<br/>Default is 24.
  </li>
  <li><b>TooltipFmt</b> - tooltip content<br/>
    Legal values are strftime formats<br/>Default is %A %x.
  </li>
  <li><b>Action</b> - command to run on mouse click<br/>
    Legal values are bash commands<br/>Default is none.
  </li>
  <li><b>Color</b> - digits color<br/>
    Legal values are colors, eg 0xRRGGBB or red, black etc. <br/>Default is blue.
  </li>
</ul>
For example:
<pre>
Plugin {
    type = dclock
    config {
        ShowSeconds = false
        HoursView = 24
        Action = xmessage Please define some command 
    }
}
</pre>


<h4><a name="xx"></a>tclock</h4>
<ul>
  <li><b>ClockFmt</b> - Clock format string. May contain strftime conversion
    specifications and Pango markup information.<br/>
    Legal values are strings<br/>Default is "<b>%R</b>".
  </li>
  <li><b>TooltipFmt</b> - Tooltip format string. May contain strftime conversion
    specifications and Pango markup information.<br/>
    Legal values are strings<br/>Default is "%A %x".
  </li>
  <li><b>Action</b> - command to run on mouse click<br/>
    Legal values are bash commands<br/>Default is none.
  </li>
  <li><b>ShowCalendar</b> - Show a GTK calendar widget when the clock is clicked.
    Only valid if Action is unset.<br/>
    Legal values are true or false<br/>Default is true.
  </li>
  <li><b>ShowTooltip</b> - Show tooltip for clock<br/>
    Legal values are true or false<br/>Default is true.
  </li>
</ul>
<pre>
Plugin {
    type = tclock
    config {
        # 2 line view, time in bold above and date below
        ClockFmt = <span font="Sans 8"><b>%-l:%M</b> %P&amp;#xA;%a %B %-e</span>
        TooltipFmt = %A %x
        #Action = xmessage Please define some command 
        ShowCalendar = false
        ShowTooltip = true
    }
}
</pre>

<h4><a name="xx"></a>Taskbar</h4>
<ul>
   <li><b>TBD</b>
  </li>
</ul>
For example:
<pre>
plugin {
    type = taskbar
    expand = true
    config {
        ShowIconified = true
        ShowMapped = true
        ShowAllDesks = false
        tooltips = true
        IconsOnly = false
        MaxTaskWidth = 150
    }
}
</pre>

<h4><a name="xx"></a>Launchbar</h4>
<ul>
  <li><b>TBD</b>
  </li>
</ul>
For example:
<pre>
plugin {
    type = launchbar
    expand = false
    padding = 0
    config {
        button {
            icon = gnome-terminal
            tooltip = Terminal
            action = xterm
        }
        button {
            image = /opt/google/chrome/product_logo_48.png
            tooltip = Google Chrome
            action = google-chrome
        }     
    }
}
</pre>

<h4><a name="xx"></a>Menu</h4>
<ul>
   <li><b>TBD</b>
  </li>
</ul>
For example:
<pre>
plugin {
    type = menu
    config {
        icon = start-here
        systemmenu {
        }
        separator {
        }
        menu {
            name = Computer
            icon = computer
            item {
                name = Terminal
                icon = terminal
                action = x-terminal
            }
            item {
                name = Lock Display
                icon = gnome-lockscreen
                action = xtrlock2
            }
            separator {
            }
            item {
                name = Reboot
                icon = gnome-session-reboot
                action = sudo reboot
            }
        
        }
    }
}
</pre>

<h4><a name="xx"></a>Icons</h4>
<ul>
  <li><b>TBD</b>
  </li>
</ul>
For example:
<pre>
plugin {
    type = icons
    expand = false
    padding = 0
    config {
        DefaultIcon = /usr/share/fbpanel/images/default.xpm
        application {
            icon = gnome-terminal
            ClassName = XTerm
        }
        application {
            icon = gnome-terminal
            ClassName = mlterm
        }
        application {
            icon = gnome-terminal
            ClassName = URxvt
        }
        application {
            icon = gnome-emacs
            ClassName = Emacs
        }
        application {
            icon = mozilla-firefox
            ClassName = Firefox-bin
        }
        application {
            icon = mozilla-firefox
            ClassName = Firefox
        }
        application {
            image = /usr/share/icons/yasis/scalable/apps/gnome-ppp.svg
            AppName = minicom
        }
    }
}

</pre>

<a href="#top"><img src="images/top.png" alt="top"/></a>
