summaryrefslogtreecommitdiffstats
path: root/doc/themes.howto.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/themes.howto.txt')
-rw-r--r--doc/themes.howto.txt123
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
+