diff options
Diffstat (limited to 'doc/themes.howto.txt')
| -rw-r--r-- | doc/themes.howto.txt | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/themes.howto.txt b/doc/themes.howto.txt new file mode 100644 index 00000000..ac04de35 --- /dev/null +++ b/doc/themes.howto.txt @@ -0,0 +1,123 @@ +Starting from the release 3.0.0 KVIrc supports user interface themeing. + +A KVIrc theme is basically: +- a subset of the options that controls the visual appearance + of the user interface +- a set of icons that override the default ones + +The skeleton for a new theme can be produced by simply saving your current +theme. Open the options dialog and go to the Look & Feel / Theme page. +Click on "Save current theme", enter the description in the dialog that +appears and select "Ok". The theme skeleton is now saved in your home +directory.The confirmation dialog +should have told you exactly where: it should be a directory like +$HOME/.kvirc/<kvircversion>/theme/<yourthemename>-<yourthemeversion>. +Cd to that directory and look around. You should see two configuration *.kvc +files and a lot of *.png images. + +themeinfo.kvc contains the informations that the user can see when browsing +the themes in the options dialog. The format of this file should be obvious: +you can edit it manually if you want to make some changes. +(The %20 strings are url-encoded spaces, KVirc will accept also plain spaces). + +themedata.kvc contains the visual settings. It looks more or less like this: + + .... + uintGlobalTransparencyParentFadeFactor=10 + boolObtainGlobalBackgroundFromKde=false + pixmapLabelBackground= + msgtypeMotd=30,1,100,1,1 + fontIrcView=helvetica,10,5,50 + colorIrcToolBarAppletForegroundLowContrast=180,180,180 + boolUseGuiEffectFadeMenu=false + pixmapGlobalTransparencyBackground=pixmapGlobalTransparencyBackground.png + pixmapTreeTaskBarBackground= + iccolor2=0,0,200 + mirccolor13=200,0,200 + .... + +You can *carefully* edit it by hand, if you wish. +Each option starts with a prefix that defines the "type" of that option. + +pixmap defines an image and thus should contain an image path (see below) +color defines an user interface color and is an R,G,B triplet +font defines an user interface font: you usually need to change only the + first two values: font family and size +msgtype defines the icon, text color, background color, log level and + alert level of the messages +uint is an unsigned integer value +bool is a boolean value: true or false +mirccolor defines the colors used by the CTRL+K escape and is an + R,G,B triplet like color. +iccolor defines the default color of an irc context and is again an + R,G,B triplet. + +Hints: + - When changing the pixmap entries remember to use filenames + without path. KVIrc will lookup the filenames in the directory + of your the me. + + - The options stringIconThemeSubdir reflects the name of the + directory in which the theme images are stored. + If you change the directory name, you must also change this option. + +The theme directory contains also a set of *.png files. +KVIrc will load these files instead of the default ones shipped in the +distribution. You can modify/replace them, but keep in mind the +following simple rules: + - you can't modify the image size: if you do it, + the images will look bad + - the image format must be *.png: it is the only + format granted to be loaded by all the versions of KVIrc. + +If you don't want to "override" an image (and thus you want to leave +the "default" one) you can delete it from the theme directory. KVIrc will +fallback to the default image shipped in the distribution. + +If you look at the global kvirc installation directory (usually +/usr/local/share/kvirc/version/pics/) you will notice that there are other +images that KVIrc loads. You can override each image by placing your version +with the same name in your theme directory. + +Hints: + - All the small icons have a meaning and a name: + you should reflect it when painting. + This small script will show you the associations between + the icons and their names: + + %i = 0 + do { + %name = $iconname(%i) + echo The icon by id %i is named %name + %i++ + } while(%name != "") + + - The id's of the icons are just their ZERO_BASED indexes. + The kvi_smallicon_<number>.png files are numbered in increasing + order and contain 16 images each one. kvi_smallicon_00.png + contains images from 0 to 15, kvi_smallicon_01.png contains images + 16 to 31 etc... Thus the third icon in kvi_smallicon_02.png + has id (2*16)+(3)-1 = 34. + + + + +What happens when an user installs a theme +----------------------------------------------------------------------------- + +When an user attempts to install a theme from the options dialog, +KVIrc reads the themedata.kvc file and applies all the visual settings. +This is an one-time action: the settings are applied only once from the +themedata.kvc file and then are saved to the user's configuration files. +In this way the user can alter the theme by freely changing the individual +settings. One of the applied options is stringIconThemeSubdir that contains +the directory of the theme images. KVIrc uses this option to lookup the +image files before looking at any other directory. If the image file is found +there, it is loaded and used, otherwise KVIrc falls back to the images +shipped in the distribution. + + +Have fun :) + +Szymon Stefanek + |