Updated README

1 files changed, 143 insertions, 34 deletions

diff --git a/README b/README
index 4a66b05..0c61ccb 100644
--- a/README
+++ b/README
@@ -52,7 +52,12 @@ or vdr.pc).
 During a "make install" the Icons are automatically copied from <SkinSourceDirectory>/icons/
 to the default path. Included Theme files are also copied from  <SkinSourceDirectory>/themes/
 to <ConfigDirectory>/themes/ 
-    
+
+Additionally with a "make install" also the theme specific configuration files 
+(see chapter "Theme specific configurations" below) are copied automatically
+from  <SkinSourceDirectory>/conf/ to the plugin config directory 
+(<VDRConfigDir>/plugins/skinnopacity/themeconfigs).
+
 I recommend to use channel logos from https://github.com/3PO/Senderlogos
 To download them just change in the directory you want to place the logos
 and do a:
@@ -107,7 +112,7 @@ the name of a channel logo (may be by inserting a space or a hyphen) so that it
 the channel name, only use lower case letters, and not the name of the channel with upper 
 and lower letters as displayed inside VDR.
 If no logo is found for the channel name, additionally a search for a logo named as the
-ChannelID is performed. Analog to the channel name the ChannelID is also convertted to lower 
+ChannelID is performed. Analog to the channel name the ChannelID is also converted to lower 
 case letters. This allows channel logos for channels with changing names (for instance
 Sky Feed Channels).
 Additional hint: some channels have slashes in their name (in germany nick/comedy for instance).
@@ -120,15 +125,65 @@ config variables in the header of the script according to your needs. If you pla
 created logos in a subfolder of your logo directory named exactly as the used Theme name, 
 nOpacity uses these logos only for the appropriate theme automatically.
 
-Themes and theme specific Icons
--------------------------------
+Themes, Theme types, Theme specific Configurations and Icons
+------------------------------------------------------------
+
+nOpacity is fully themable with different "theme types". Examples for theme files with all 
+possible color settings are included in <SkinSourceDirectory>/themes/. As already mentioned 
+these themes are automatically copied during a "make install" into the VDR themes directory 
+and can be choosed in VDRs OSD setup menu.
+
+The following skin characteristics are theme dependend:
+- theme default configuration
+- theme configuration
+- theme colors
+- graphical skin elements (for "graphical" themes, see below)
+- theme icons and images
+
+Theme types:
+............
+
+nOpacity supports three different theme types named "flat", "blending" and "graphical". This
+type can be set with the config option "displayType" (flat: displayType = 0, blending: 
+displayType = 1, graphical: displayType = 2) which has to be provided via the theme specific
+configuration file (see below). If this value is not provided by the theme designer, the default 
+value "blending" is used.
+
+flat style: "basic" skin type with almost no effects, areas are just filled with plain colors
+blended style: skin elemements like menu items are drawn with a main and a blended color which
+are provided via the color theme file, skin elements are drawn with a blended effect.
+graphical style: almost all skin elements are drawn by using dedicated PNG images. These PNGs
+have to be placed in the <themename>/skinElements/ icon directory. See the default theme for 
+examples for this style and the used images.
+
+Theme specific configuration:
+.............................
+
+Because the "look&feel" of nOpacity is strongly dependend of the choosen setup configuration
+options.
+
+On the one hand it is possible for the theme designer to provide a dedicated default 
+config for every theme. This theme configuration has to be named "theme-<themename>.conf" and
+has to be placed in <VDRConfigDir>/plugins/skinnopacity/themeconfigs. As already mentioned all 
+theme configs which are available in the skin source directory <SkinSourceDirectory>/conf/ are
+copied automatically to the destination directory with a "make install". The syntax for this 
+theme configuration file is just straight forward a "configoption = value" per line. The possible 
+configuration options and the default values can be checked in the file config.c in the function
+cNopacityConfig::LoadDefaults(void).
+
+On the other hand, all configuration changes done by the user are only valid for the currently 
+choosen theme. That means that every theme has it's individual configuration. If the theme is 
+changed via the VDR Setup/OSD Menu, the configuration for this theme is loaded in the following way:
+
+- first the general default settings from cNopacityConfig::LoadDefaults() are used
+- after that the settings from the theme config file (if available) are looked up, every available
+  config option in this file replaces the default config option
+- after that the settings the user has individually customized are used and replace the corresponding
+  default settings
+
+Theme specific icons and images:
+................................
 
-nOpacity is fully themable. Examples for theme files with all possible color settings are
-included in <SkinSourceDirectory>/themes/. As already mentioned these themes are automatically
-copied during a "make install" into the VDR themes directory and can be choosed in VDRs
-OSD setup menu.
-
-Beside colors also the icons and images shown in the different menus are theme dependend. 
 Icons and images are first looked up in <IconPath>/<ThemeName>/. If there is no appropriate
 icon found, <IconPath>/ is used. With that it is possible to use specific icons for every
 different theme.
@@ -140,6 +195,25 @@ Two types of icons are used:
       has to be named as the plugin name so that the appropriate icon will be shown in the
       main menu.
 
+Image Caching
+-------------
+
+nOpacity uses an image cache to achieve best performance also on systems with low performance.
+The image cache loads all necessary images (icons, skin elements, channel logos) at startup and
+also after a change in screen resolution or leaving the nOpacity setup menu. Depending on the 
+system hardware and the configured number of channel logos to cache (see below) this cache reload
+can need some seconds.
+
+In the plugin setup menu in the submenu "image caching" it is possible to configure the number of 
+channel logos to be cached at startup and the maximum number of channel logos to cache. Channel logos
+are always cached in the order the channels appear in your channels.conf file. If you configure for
+example to cache 50 logos and you set the maximum number of logos to 100, the logos for the first 50
+channels in your channels.conf are cached at startup. If logos from channels 51 - 100 are needed,
+the image is created once, all further requests for that logo are fulfilled by the cache. Logos for
+channels > 100 are not cached and are always created from the source PNGs on your storage medium.
+
+In the "image cache" setup sub menu the current cache usage for the different types of images and the
+memory used is displayed as additional information.
 
 Customizing, Skin Setup Options
 -------------------------------
@@ -150,12 +224,14 @@ Customizing, Skin Setup Options
 
 * VDR menu: Common Settings:
 
+- Create Log Messages for image loading: show log message for each image loading process. Usefull
+  for debugging, but causes many log entries
 - Number of Default Menu Entries: Number of menu items for the default menu view.
 - Adjust Font Size - Default Menu Item
 - Adjustment of narrow menus: the narrow menus (main, schedules, channels, timers,
   setup) can either be adjusted left or right.
-- Scale Video size to fit into menu window: no / yes / auto: with "auto" the video  window is resized when the detailed EPG Window is displayed in Schedules and
-  Recordings menu to be completely visible.
+- Scale Video size to fit into menu window: no / yes / auto: with "auto" the video  window is resized 
+  when the detailed EPG Window is displayed in Schedules and Recordings menu to be completely visible.
 - Header Height (% of OSD Height): Default: 7%
 - Header Icon Size (Square Header Menu Icons)
 - Footer Height (% of OSD Height): Default: 7%
@@ -164,6 +240,7 @@ Customizing, Skin Setup Options
 - Fade-In Time in ms (Zero for switching off fading): Default 0, active fading
   for main menu caused sometimes trouble in some special setups. Activate on
   own risk ;)
+- Menu Items Scroll Style: "Carriage Return" after scrolling is complete, or "Forward and Back again"
 - Menu Items Scrolling Speed
 - Menu Items Scrolling Delay in s: period which menu element has to be selected
   till scrolling starts
@@ -182,33 +259,34 @@ Customizing, Skin Setup Options
   - Width (Percent of OSD Width): if displayed narrow, width of this menu
 - Use narrow setup menu: display setup menu in narrow or standard style
   - Width (Percent of OSD Width): if displayed narrow, width of this menu
-- Use menu icons
-  - Icon Size (Square): if icons are used, size of the icons. Even if no icons
-    are used, the height of the menu items is determinated by this value.
+- Number of entires per page: number of menu items shown per screen
+- Use menu icons: yes/no
+- Main menu title style: way how VDR version in menu header is displayed:
+  "VDR" plus VDR version, only VDR version, no title
 - Display Disk Usage: Display Disk Usage in Main Menu
   - Size (square, Percent of OSD Width)
+  - Free Disc Display: free time in hours (estimated) or free disc space in GB
   - Adjust Font Size - free
   - Adjust Font Size - percent
-- Display Timers: Display active Tiers in Main Menu
-  - Width of Timers (Percent of OSD Width)
-  - Channel Logo Width (at the top of the timers displayed in main menu)
-  - Channel Logo Height (at the top of the timers displayed in main menu)
+- Display Timers: Display active Timers in Main Menu: "yes", "small without channel
+  logos", "no"
+  - Maximum number of timers to show in main menu
+  - Width of Timers (% of OSD Width)
+  - Width of channel logos (% of timers width)
   - Adjust Font Size - Header
   - Adjust Font Size - Title
 - Show Timer Conflicts
-- Header Logo Width: Default 104px
-- Header Logo Height: Default 78px
+- Header Logo Width / Height: Header Logo is scaled to fit into the header, these
+  values are used for correct scaling
 - Adjust Font Size - Menu Items
 
 * VDR Menu: Schedules Menu
 
 - Use narrow menu: display menu in narrow or standard style
   - Width (Percent of OSD Width): if displayed narrow, width of this menu
-- Channel Logo Width (Menu Buttons): width of channel logos shown in scheduling
-  "what's on" and "what's next" menus and channels menu. 
-- Channel Logo Height (Menu Buttons): height of channel logos shown in scheduling
-  "what's on" and "what's next" menus and channels menu. This size determinates 
-  the number of menu entries in schedules and channels menu.
+- Number of entires per page
+- Mode of EPG Window: "small window" with settings for fade in and scroll speed / delay
+  or "full screen" 
 - EPG Window Fade-In Time in ms (Zero for switching off fading)
 - EPG Window Display Delay in s: period which schedules menu element has to be
   selected till fade in of epg window starts
@@ -216,6 +294,7 @@ Customizing, Skin Setup Options
   window text starts to scroll
 - Height of EPG Info Window (Percent of OSD Height): Height of text window which
   is shown for schedules menu elements
+- Border around detailed EPG view: border to be displayed in detailed EPG view
 - Display Reruns in detailed EPG View: via epgsearch service
   - Number of reruns to display: Default 5
   - Use Subtitle for reruns
@@ -223,8 +302,6 @@ Customizing, Skin Setup Options
   EPG pictures will be shown at the end of the detailed EPG view. The pictures have
   to be named as eventid_number.jpg with number from 1 to 9.
   - Number of EPG pictures to display
-- Detail EPG View Logo Width: Default 260px
-- Detail EPG View Logo Height: Default 200px
 - Detail EPG View EPG Image Width: Default 210px
 - Detail EPG View EPG Image Height: Default 160px
 - Detail EPG View additional EPG Image Width: Default: 525 px
@@ -232,11 +309,22 @@ Customizing, Skin Setup Options
 - Adjust Font Size - Menu Item
 - Adjust Font Size - Menu Item Small
 - Adjust Font Size - EPG Info Window
+- Adjust Font Size - EPG Info Window Header
 
 * VDR Menu: Channels Menu
 
 - Use narrow menu: display menu in narrow or standard style
   - Width (Percent of OSD Width): if displayed narrow, width of this menu
+- Menu Items display mode: Transponder Information / Current Schedule / None
+  - If "Current Schedule": Schedules with time information
+- Number of EPG Entries in Schedules Info Window
+- Adjust Font Size - Menu Item
+- Adjust Font Size - Menu Item Small
+
+* VDR Menu: Timers Menu
+
+- Use narrow menu: display menu in narrow or standard style
+  - Width (Percent of OSD Width): if displayed narrow, width of this menu
 - Adjust Font Size - Menu Item
 - Adjust Font Size - Menu Item Small
 
@@ -244,11 +332,15 @@ Customizing, Skin Setup Options
 
 - Use narrow menu: display menu in narrow or standard style
   - Width (Percent of OSD Width): if displayed narrow, width of this menu
+- Number of entires per page
+- Mode of recording Window: window / full screen
+- Border around detailed recording view: analogue to "detailed EPG Info"
 - Display additional EPG Pictures in detailed recording View: if set to yes, additional
   pictures will be shown at the end of the detailed recording view. All jpegs in the
   recording directory will be used.
   - Number of EPG pictures to display
-- Folder Icon Size: size of the folder image used in recordings list
+- Use folder poster if available: use folder poster provided by tvscraper
+- Width / Height of manually set recording poster: used for correct scaling
 - Adjust Font Size - Menu Item
 - Adjust Font Size - Menu Item Small
   
@@ -258,20 +350,28 @@ Customizing, Skin Setup Options
 - Height of Channel Display (% of OSD Height): Default 25%
 - Left & Right Border Width: Default 15px
 - Bottom Border Height: Default 15px
+- Background Transparency in Percent: for graphical themes, sets transparency of background
+- Background Style: only for non graphical themes, transparent logo background or not
 - Channel Logo Position: left / right / do not display. If set to "do not display",
   the whole screen width is used for channel display.
-  - Channel Logo Width: Default 260px
-  - Channel Logo Height: Default 200px
-  - Channel Logo Border: Default 15px
+  - Channel Logo original Width: Default 260px (used for correct scaling)
+  - Channel Logo original Height: Default 200px (used for correct scaling)
+- Kind of time display for current schedule: elapsed or remaining time
+- Display Source Information: display Channel Source Information (used Satelite)
 - Display Signal Strength & Quality: Set this to Zero if you want to disable the
   display of signal strength & quality (for instance if your dvb drivers does not
   deliver this values)
-- Screen Resolution Icon Size: Default 100px
-- Status Icon Size: Default 64px
+- Display Poster or Fanart from TVScraper
+  - Border in px around poster / fanart
+- Display previous and next Channel Group
 - Adjust Font Size - Header: Font for Channel / Channelgroup Name
 - Adjust Font Size - Date
 - Adjust Font Size - EPG Text
 - Adjust Font Size - EPG Infotext
+- Adjust Font Size - Channel Source Info
+- Adjust Font Size - Channel Group
+- Adjust Font Size - Next/Prev Channel Group
+
 
 * Replay:
 
@@ -322,3 +422,12 @@ Customizing, Skin Setup Options
   Remark: the volume display is always positioned in the center of the screen,
   with bottom border it can be moved to the top.
 - Adjust Font Size
+
+
+Changes: 
+- Main Menu: Original Header Icon size
+- Schedules: EPG Window Settings nur für modus "window", "full screen" als default
+- Gleiches bei Recording
+
+Legal Remark: some of the menu icons used in this skin are from http://icons8.com/
+Thanks @icons8.com for provide these icons for free.
\ No newline at end of file