Note: This is English translation of habak's documentation.
      It was written by Bartosz Fenski <fenio@o2.pl> for 
      the Debian GNU/Linux distribution (but it may be used by others).
      Radoslaw Antoniuk fixed some mistakes but as English isn't my 
      (and his) native language, further fixes are welcome.

Habak - "Ha" Background (*lat. "mentha longifolia")
=========

Compilation:
    You will need compiler, X and Imlib2. Standard.
	Just type "make".
	You can change default options in src/defaults.h.

Installation:
    Just put binary wherever you want.

Short description:

Habak uses layered model. Lowermost layer is just black screen. You can put
other objects on it and these objects are called habaks.
There are three kinds of habaks: graphic files (images), texts and "internal
objects". Final background image consists of one or more habaks positioned on the
black screen. The order of habaks in the command line is also the order of
displaying them on screen. So last habak would be drawn on the top of previous.

Usage:
Habak can be handled by command line options. It can distinguish two kinds
of options: modifiers and habaks. Modifiers have -mX form, where "X" is
indicator of the specific modifier. Modifiers are divided to those which
get arguments and those which don't.

Habaks have -hX form, where "X" is indication of the specific habak. Habaks
usually need an argument, but there is one exception from this rule and it will be
explained later. 

Remember: There are two kind of options. Those started with -m are
modifiers, and those with -h are habaks.

Types of habaks:

FIle habaks (graphic) -hi:

Files with graphic (images) can be handled using -hi option. e.g.

./habak -hi ~/graphic/wallpaper.jpg

will add wallpaper.jpg file on the screen. If -hi option indicates directory
instead of file, habak will recursively generate list of files and choose
one of them. So if you have a bunch of images in ~/gfx/nice_wallpapers/ then
you can use habak to load random image. You just have to type:
'./habak -hi ~/gfx/nice_wallpapers/'

If you're using habak with a -hi option and you'll not pass any file to
load, habak will use last used file (from the previous -hi option) or start
searching your $HOME for files.

Option "-hi" can be usually skipped. You can pass a name of directory/file at
sight. So you can simply enter:

./habak ~/graphic/wallpaper.jpg

Text habaks -ht:
You can as well draw texts on screen. That's what text habak, option -ht, is
for. Its argument is one line of text. It doesn't matter what kind of text
it would be. You can use kernel version, date, your name, favourite
distribution or name of cat which is basking on your printer now. Choose
whatever you want. I like date. The text will be antialiased, but if you want to
use non-ASCII characters make sure you're encoding it with utf-8.

If you'll use -ht option without arguments, habak will use last used text
(from the previous -ht option) or default text included in program.

Internal habaks -hI:
Third (and last) type of habaks are internal habaks. They can be enabled
with -hI option. They don't get any external data, but generating some
pattern themselves. Right now there are only two patterns, "int" and "INT".
They're doing interlace. Here is example of usage:

./habak -hI int

Internal habak "int" makes interlace by fading out even lines of screen.
It's a cool effect, especially when wallpaper is put on to a colorful other
wallpaper. "INT" habak is almost identical, but it fades out uneven lines
(using "int" and "INT" together you can change all lines of screen).

By default lines aren't turned off but only faden out to the very dark colour
(IMO it looks better). You can of course change that behaviour using colour
modifier -mc (will be explained later).

If you're using -hI option without passing type of habak, by default last
used habak will be used or default "int".

REMEMBER: There are three kinds of habaks:
-hi File habak, designed to load image files. If you won't pass any
    argument, it will use last appeared one or try to load "./logo.png".

-ht	Text habak, give it line of text to draw on screen.
    If you won't pass any argument it will use last given text or default
    ("Habak v.x.y.z").

-hI Internal habak, generates some pattern itself. Again, if you won't
    pass it any argument, it will use last used. If it can't find anyone
    then default "int" will be used.

PHILOSOPHY OF USAGE
Habaks can (and should) be combined. For example:

./habak -hi ~/gfx/cool.jpg -hI int -hi ~/gfx/small_logo.png -ht "Foo bar"

means that file cool.jpg will be drawn first, then internal habak
"interlace" will be used, then another image small_logo.png, and finally
text "Foo bar" will be added. Simple.

MODIFIERS
Of course habaks themselves wouldn't be very flexible, so there are many
modifiers which can change their look. Some of the modifiers are even
must-use to get something useful on screen. There is a general group of
properties which habaks own. In the beginning, the program has some defaults which
can be changed later with various modifiers. If you launch habak from the
command line, it makes a "snapshot" of the current properties. You can change
them later and add next habak. Changing habak's options after putting it on
screen doesn't work. Treat it like you would be a photographer - you
arrange some scenario and make snapshot of it. Then you change something in
arrangement and make another snapshot. This way habak generates successive
frames of the screen which will be rendered later.

Modifier -mC
-mC is a centering modifier. It will enforce habak to be centered on
screen. Its activity will be disabled if you use option -mp later.
This modifier is disabled by default.

Modifier -mS 
-mS is a scaling modifier. Habak will be rescaled to use whole screen (but
saving its proportions). It is useful only for file habaks (images). It is
disabled by default. Its activity can be negated using -mp later.

Modifier -ms
-ms is a scaling modifier too, but it ignores propotions of the image.
Image will use whole screen but will be probably deformed (on of its
dimension will be stretched). By default it is disabled, can be negated by
-mp too.

Modifier -mp
-mp is a position modifier. It specifies exact position of the habak on
screen. It needs additional argument 'x,y', for example:

./habak -mp 10,50 ~/gfx/ala.jpg 

will render file ala.jpg in the way that its top left corner will be
rendered at 10,50 point of screen. Coordinates can be negative, so
position is being counted from the opposite side of screen. For example:

./habak -mp -10,50 ~/gfx/ala.jpg 

will render habak ten pixels from right side of screen and 50 pixels from
top edge. To render habak at the top right corner you have to use '-mp -0,0'

Using this modifier will disable -mC, -ms or -mS

If you don't use -mp then by default screen will be centered.

Modifier -mc
-mc is a colour modifier. Some of the habaks can react on colour settings
(for example text or internal habaks which make interlace). This habak gets
argument describing colour in the format R,G,B,A. For example:

./habak -mc 50,60,70,190 -hI int

means using internal "int" habak with colour:
- red channel set to 50
- green channel set to 60
- blue channel set to 70
- alpha channel (transparency level) set to 190

All numbers can be from 0 (minimal saturation) to 255 (maximal saturation)
range.

For example '-mc 0,0,0,255' means black colour without transparency, and
'-mc 255,255,255,0' means white with completely transparent (so unvisible).
'-mc 200,0,0,128' means bright red colour with transparency set to 50%.

By default (before you use -mc) colour is set to something like lightly
dirty, transparently white.

Modifier -mf
This modifier selects font (used to draw texts). 
You can choose TrueType font with it, for example:

./habak -mf ~/.fonts/fajny_font.ttf

You can also select directory with fonts. Then habak will choose one random 
font from this directory.

If you use text habak with -ht option, and you don't define font, habak
will try to load random font from ~/.fonts directory. But if you
don't have any fonts there, habak will stop working. So remember if you
want to draw some texts make sure you've defined font correctly.

Modifier -mh
This modifier will set needed font size (in pixels). For example:

./habak -mh 50 -mf ~/.fonts/cool_font.ttf

will choose font "cool_font.ttf" with the 50 pixels size

If you don't use -mh, then default size will be used. AFAIR 30 pixels.

REMEMBER: habak stores default "properties" list related to habaks. Those
properties can be changed with modifiers. Habak will "get" current settings
when you run it. You have the following modifiers:

-mC centering modifier. Habaks will be centered on screen. It disables
    activity of the last used -mp modifier. By default disabled.

-mp positioning modifier. You pass it coordinates X,Y for habak. It
    disables activity of the last used -mC modifier. By default disabled.

-mS scaling modifier (with proportions). By default disabled.

-ms scaling modifier (without proportions). By default disabled.

-mc Colour modifier R,G,B,A. By default it's set to lightly dirty,
    transparent white.

-mf Font modifier. Pass it path to some .ttf file. By default it's set
    to $HOME/.fonts directory.

-mh Font size modifier. Pass it needed font size in pixels.
	By default it's set to 30 pixels.



*** EXAMPLES *** EXAMPLES *** EXAMPLES *** EXAMPLES *** EXAMPLES ***

Ok. Here goes some examples:

./habak -mf ~/.fonts/deltafont.ttf -mh 15 -mp 0,-0 -mc 240,240,240,200 \
-ht "User $USER on day `date +%Y-%m-%d`" 

will for example render string "User grzegorz on day 2003-12-21", using
font deltafont.ttf with 15 pixels size. String will be placed in the top
left corner and will be drawn with grey colour and little transparency.

Of course it was very easy example, we can complicate it a little:

./habak -mC -hi /usr/local/share/backgrounds/lens \
-mf ~/.fonts/deltafont.ttf -mh 15 -mp 0,-0 -mc 240,240,240,200 \
-ht "User $USER on day `date +%Y-%m-%d`"

Now we put centered, randomly chosen image from
/usr/local/share/backgrounds/lens first. Then we render text on it.
We can complicate it a little bit more:

./habak -mC -hi /usr/local/share/backgrounds/lens \
-mp 5,-0 -mc 240,240,240,100 -mf ~/.fonts/deltafont.ttf -mh 15 \
-ht "User $USER on day `date +%Y-%m-%d`" \
-mp 0,-5 -mc 240,240,240,255 -ht

This is similar situation, but I complicated text behaviour a little.
I'm generating *two* font habaks with the same text, but one of them is
moved and has less transparency. It appears as nice shadow effect. 
Using *several* such shadows with random sizes and transparency you can get
very nice effects. Consider that I'm using inheritance(?) here - font and 
its size is set only once, then when I have to generate second time the
same text I can change only its place and colour, -ht is being used without
argument - so it takes argument from the previous instance of -ht.

Ok. Let's rock:

./habak -mC -hi ~/gfx/new/ \
-hI int \
-mf ~/.fonts/deltafont.ttf -mh 50 -mC -ht\
-mh 15 -mp 5,-0 -mc 240,240,240,100 \
-ht "User $USER on day `date +%Y-%m-%d`" \
-mp 0,-5 -mc 240,240,240,255 -ht

Here I added internal "interlace" habak between image from
/usr/local/share/backgrounds/lens and font habaks. Thanks to it image is
a little interlaced, but text is not (cause it's laying above interlace).
In addition between main wallpaper and interlace there is "default text"
drawn with big font.

Maybe some simple example with putting logo?

./habak -mC -hi ~/utena_4_1024.jpg \
-mp 0,0 -hi ~/logo.png \
-mp 0,-0 -hi \
-mp -0,0 -hi \
-mp -0,-0 -hi \
-mp -15,-15 -hi \
-mp -30,-30 -hi

We're loading centered background utena_4_1024.jpg first. Then in the
corner 0,0 we're putting logo.png. Then we're doing the same for every
corner, but we're using "-hi" without arguments to simplify it. At the end
we're putting logo in the -0,-0 corner and two more times the same logo but
moved 15 pixels on the both X,Y axises. Then we can see how different
transparencies are merged together.

We can simplify it a bit, skipping some options:

./habak ~/utena_4_1024.jpg \
-mp 0,0 ~/logo.png \
-mp 0,-0 -hi \
-mp -0,0 -hi \
-mp -0,-0 -hi \
-mp -15,-15 -hi \
-mp -30,-30 -hi

I skipped -mC -hi before main picture, cause centering is default behaviour
and we know that it's a picture from the context. Habak will handle it.
I've removed -hi before ~/logo.png from the same manner.


