Mimic Version: 1.10, Jan 10/2000 ===== (C)2000 Steve J. Gray http://www.ryerson.ca/~sgray Skins Format Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduction ------------ Skins let you totally change the look of the program to almost anything you want. Skins are replacement images for all the buttons text and digits in the window. A skin consists of two or three files: 1) A text file that defines the placement of elements of the skin. 2) A "main" bitmap that represents the graphical "up" and "off" state of all the elements. 3) An optional "resource" bitmap that contains the "down" or "on" state of each element PLUS other images, such as digits. A basic skin only needs the first two files, however it will have limited user feedback (ie: when you click on a button the image does not change) and you are limited to standard text. By including the optional resource bitmap you can define the look of each button when depressed plus you can define graphic digits for the time, track number, or clock. Mimic is not limited to a rectangular form. In the skin file you can also define an irregular-shaped outline, or specify a specific colour to be transparent in your main bitmap for your skin. Mimic also includes a screen saver, which uses the same skin engine as Mimic itself. Because screen savers are not interactive you are limited to certain elements (labels etc). In the elements reference below, those marked with a "+" can be included in screen saver skins. All other elements will be ignored. How to make your own skin ------------------------- Tip: Look at the "default.skin" file. It is an example of an advanced skin using just almost all of the different skin features (except regions). First, think about the layout of your skin. Where will the elements go? How big will the buttons be? Do you want your own digits or are standard text fonts okay? There are a few different elements that will make up your skin. All elements are optional. If you don't define them they will not appear. These are the different types of elements available: * Animations * Buttons * Text * Digital Displays * Playlist * Sliders * Other (Bitmaps etc) The elements are placed in the program "window" which we will refer to as the "form". The background (static graphics that do not change), and buttons will be drawn on the main form. Other elements (such as text) will be placed on the form in the position you specify. Text placed on the form will have no background of its own (IE: your graphics will show through). You can use just about any graphics editor to create the bitmap(s). Bitmaps can be saved in either BMP, GIF, or JPEG format and can contain from 16 to 16 million colours. Keep in mind that if you try to display 16 million colours on a 256 colour or less screen mode, MS Windows will adjust the image and it may not appear as you intended! Also, note that JPEG images are good for life-like images with lots of colour but are not good for text or cartoon-like images. For these type images use GIF. The Main Bitmap --------------- The main bitmap is the image that appears on your form and gives the skin it's look. You can draw whatever you want and it will appear as-is on the form. Draw all the buttons in their "up" state. You could create buttons with labels on them or you could put the label outside the button. If all your buttons were the same size and you put the labels on the form (instead of inside the button) you could save some work since you would only need to draw one "down" button on the resource bitmap. If each button is labeled you will need to draw the "down" version of each button in the resource bitmap. Buttons can be any shape you want. They do not have to be rectangular, however the definition for the button area will be rectangular so you need to be careful how the buttons are placed so that the button areas do not overlap. Overlapping buttons are possible but you would need to do some creative drawing in the resource bitmap... The Resource Bitmap ------------------- The "resource" bitmap contains all the buttons in their "down" state, sliders and any digital display digits or text. An easy way to make the resource bitmap is to copy the main bitmap then modify the buttons to look depressed. A common technique with "standard" buttons is to reverse the highlighting. IE, in the "up" button the top and left are light coloured, whereas the bottom and right are dark. When depressed those are reversed so that the top and left are now dark and the others are light. Another common technique is to make the button darker and to slightly offset the label down and to the right to give the appearance of being pushed in. The resource bitmap does not need to be the same size as the main bitmap. If you have a large-sized form with large areas and/or you need to create room for the digital display digits then you might need to re-arrange the "down" buttons on the resource form. If you do this you will need to specify the new coordinates in the skin file. To create the digital display digits, draw each digit in a single line like this: 0123456789 .: (there is a "space" between the "9" and "."!) Make sure ALL characters are all exactly the same width. The "space" character can be blank, a "zero", or the segments that make up the digit in an "unlit" state. The "." and ":" are special cases. Even though they take the same width in the bitmap as the others they can be thinner than the other digits by specifying their width (w2) in the parameter list (they will need to be aligned to the left). The Skin file ------------- The skin file is a text file that ties everything together. In the skin file you define everything that makes the skin work. You define the size of the form in it's normal, expanded, and small modes. You define the location of the buttons and text, their sizes, colour, and font etc. You define where in the resource bitmap the digital digits are located and what size they are. You can also define all the points that make up the outline of the form if you choose to make your skin non-rectangular. The format: The first FIVE lines must be in the following format. NO extra comments or blank lines can appear above them! * Line1 is a string that indicates this is a Mimic skin. The line must start with the string: "Mimic Skin" You may optionally follow (on the same line) any or all of the following strings to indicate the type of skin: "/Player", "/FMTuner", "/Calculator", "/Clock", "/Notepad", "/Browser", "/Karaoke", "/WebRadio" "/Favorite", "/Combo" For example, if the skin was a player skin with clock you would use: "Mimic Skin/Player/Clock" * Line2 is a line for the skin name, your name, copyright etc that will be displayed in the info tab * Line3 are 3 pairs of Width/Height values corresponding to the size of the normal form, extended form, and small form, like this: w1,h1,w2,h2,w3,h3 NOTE: All dimensions are in pixels! * Line4 is the bitmap or import control line. > For standard skins it contains the bitmap filenames like this: main,resource (Files can be bmp, gif, or jpeg format. If you don't have a resource file then use the same filename as main) > For import skins the format is: *,directory,filter,defaultfile - The directory is the default location for importing. - The filter determines the type(s) of files to show. - The defaultfile is the name of the main file. * Line5 contains option settings: Bmode,ScnPos,BgRed,BgGreen,BgBlue,xx,xx,xx - Bmode: Defines the action when the mouse pointer goes over a button on the form: 0=No action 1=Draw border rectangle 2=Display down-button image - ScnPos: Defines if the skin should appear in a specific position on the screen: 0=No change (use last position) 1=Top Left corner 2=Top Right corner 3=Bottom Right corner 4=Bottom Left corner 5=Centred - Bg[Red/Green/Blue]: Background Color of main form - xx: extra elements for future use (use "0" for now) The rest of the file defines the elements in the skin. If you wish to add comments to the file put a semi-colon followed by a comma (";,") at the beginning of the line. Everything after the comma up to the end of the line will be ignored. You can include skin comments, which are displayed in the "info" tab of the prefs screen by starting the line(s) with "/," characters. Eg: /, This is a skin comment /, This is another comment Comments will be appended one after another and displayed exactly as entered on the line. Elements -------- Different elements are defined using a unique identifier consisting of a letter and number (for example: B12). Following the identifier are one or more parameters depending on the type of element. The following are the element codes: * A - Animations * B - Buttons * C - Pictures and Video Area * D - Digital displays * I - Indicator Lights * K - Link Buttons * L - Labels * S - Sliders * T - Text Input field * X - Other (listboxes etc) The Following are control codes: * N - Single Region initialization * M - Multiple Region initialization * O - Transparent Bitmap initialization * P - Point in region * R - Read bitmap (0=main,1=resource,2=temp) * ? - Conditional jump based on success of "R" command * W - Set width/height of bitmap * Z - Blit from temp to main or resource bitmap * /,- Skin comment * ;,- Comment * : - Label (target for "?" commnad) * USE - use bitmaps The following are possible parameters: * X, Y - Coordinate of the top left of an element. * W, H - The Width and Height of an element. * X2, Y2 - Coordinate of corresponding image in resource bitmap. (if you use 0,0 then the main X,Y coordinates are used) * W2, H2 - Extra Width and Height (ie: for a sub-image). * key - The Keyboard command. * tooltip - Text that appears when the mouse is over the element. NOTE: if the text contains a comma you must enclose the entire string in quotations! Tooltips starting with "~" will not be displayed * r, g, b - The Red,Green,Blue colour components (Range is 0 to 255). * pt - The Point Size for the font. * font - The Font Name. To specify any of Bold, Italic or Underlined append a colon then one or more letters: B, I, or U, like this: MS Sans Serif:BIU Small Fonts:B NOTE: Make sure the font is available in the desired style! * f - Numeric Format type. NOTE: All coordinates and dimensions are in PIXELS! If you DO NOT specify an element, or its Width or Height are zero it will NOT appear. The following describes the format of the parameters for each element and the function of each element: Elements are listed in the format: Xnn - Description Where X is the Element Code, nn is the element number. The character before the Description indicates the status: - = The function is implemented + = The function can also be used in the screensaver * = The function is NOT implemented in the current version but is reserved for future use (A) Animations -------------- These are animation elements. When an animation is stopped the first frame is displayed. When active it will loop from the second frame to the last frame then back to the second frame, and so on. Format: Ann,x,y,x2,y2,w,h,r,c,speed,tooltip A01 + General Animation (always active if included) A02 - Player Animation A03 - Web Browser Animation A04 - Web Radio Animation Where: - x2,y2 is the location in resource bitmap - w,h are size of one frame - r,c are number of rows/columns (note: you must have at least 2 columns!) - speed is the speed of animation (1=fastest, higher=slower) (B) Buttons ----------- Format: Bnn,x,y,w,h,x2,y2,key,tooltip General Buttons: B01 - Power button B02 - Minimize (hide) window B03 - Toggle Large Mode (window size 2) B04 - Toggle Small Mode (window size 3) B05 - About/Preferences B06 - Select Skin B07 - Volume Down B08 - Volume Up B09 - Volume Mute Player Buttons: B10 - Stop B11 - Pause B12 - Play B13 - Eject B14 - Previous Track B15 - Next Track B16 - Info B17 - Delete Track B18 - Move Track Down B19 - Move Track Up B20 - Clear Playlist B21 - Load Playlist B22 - Save Playlist B23 - Add Track B24 - Add Directory B25 - Toggle Intro B26 - Toggle STP B27 - Toggle Repeat B28 - Toggle Shuffle B29 - Show Mixer B30 - Set A point (or toggle A/B/Off if B31 not visible) B31 - Set B point B32 - Reverse B33 - Forward B34 - Toggle Cover Window B35 - Visual Playlist Selector B36 - Play/Pause Toggle B37 * Mode Select (Media / CD) B38 - Menu (same as right click on form) B39 - Jump to Selected Track (Number displayed via L23) Calculator/Keypad Buttons: B40-B50 - Numeric Keys: 0 to 9, period B51-B59 - +, -, x, /, =, +/-, %, sqrt, 1/x B60-B69 - BACKSPACE, CLEAR, CE, MC, MS, MR, M+ Convert-To, Convert-From, Select Conversion Timer Buttons: B70-B75 - Sel+, Sel-, Start/Stop, Reset, Lap, Reset All Notepad Buttons: B76-B79 - Load, Save, New, Print FMTuner Buttons: B80-B83 - Scan Down, Scan Up, Tune Down, Tune Up B84-B87 - Preset: Prev, Next, Add, Delete B88-B90 - Preset: Move Down, Move Up, Store (*) B91-B100- Preset: Preset 1 to 10 (to tune to a specific preset) Web Browser Buttons: B101-B109 - Home, Refresh, Back, Forward, Stop, Search, Print, Add Bookmark, Add to URL Button, Bookmarks Menu B111-B120 - URL Buttons: 1 to 10 Web Radio Buttons: B130-B139 - WebRadio Station Presets: 1 to 10 B140-B146 - Preset: Prev, Next, Add, Delete, Move Down, Move Up, Store B147 - Play B148 - Stop B149 * Reserved Misc Buttons: B150 - Player Quick Find/Play B151 - Load Previous Skin *** The following are planned for the future: Dual Playlist Buttons: B200 - Copy selected to PL1 B201 - Copy selected to PL2 B202 - Move selected to PL1 B203 - Move selected to PL2 B204 - Swap selected PL1/PL2 entries Dual-Player Buttons: B210 - Stop B211 - Pause B212 - Play B213 - Eject B214 - Previous Track B215 - Next Track B216 - Info B217 - Delete Track B218 - Move Track Down B219 - Move Track Up B220 - Clear Playlist B221 - Load Playlist B222 - Save Playlist B223 - Add Track B224 - Add Directory Notes: - You can have multiple buttons with the same function by specifying the button more than once in the skin file. - There can be a maximum of 120 buttons in the skin including "Link" buttons. (C) Pictures / Video Area ------------------------- These are picture elements. Bitmaps are scaled to fit the specified size. Format: Cnn,x,y,w,h,ToolTip C01 + Album Cover bitmap (Screensaver=General picture displayer) C02 - Web Browser C03 - Video Playback Area (D) Digital Displays -------------------- These are digital displays using graphics digits/letters of any size. Format: Dnn,x,y,x2,y2,w,h,w2,g,s,f,ToolTip D01 - Track Time D02 - Track Number D03 + Current Time - HH:MM D04 - kbps setting D05 - kHz setting D06 - Track Title D07 - Track to Play / Calculator Display D08 * Current Timer D09 - FM Frequency D10 - FM Preset# D11 + Current Time - SS (seconds) D12 - Web Radio Play Time Where: - w,h are for a SINGLE digit - w2 is the width of the period and colon. - g is the source bitmap format 0=Numeric Only (0123456789 .:-) (the space can be blank, a "zero", or "unlit" form of the digit) (cannot be used for element D6!) 1=Alphanumeric (Full ascii) 2=Alphanumeric (Uppercase ascii) 3=WinAmp Standard (Uppercase ascii) - s is additional spacing for destination - f is the display format number: -1 to -15 = number of digits 0 = "MM:SS" (elapsed time) 1 = "HH:MM" (time) 2 = "HH:MM:SS" (time) 3 = "999.9" (frequency) 4 = "999.999" (frequency) 10 or higher = length of track title (I) Indicator Lights -------------------- Format: Inn,x,y,w,h,r,g,b,shape,comment I01 - FM Stereo Station Tuned Light I02 - Player Stopped Light I03 - Player Paused Light I04 - Player Playing Light I05 - Player Intro Light I06 - Player STP Light I07 - Player Repeat Light I08 - Player AB Repeat Light I09 - Player Random Play Light I10 * Player Shuffle Play Light I11 - Player NOT Intro I12 - Player NOT STP I13 - Player NOT Repeat I14 - Player NOT AB Repeat I15 - Player NOT Random I16 - Player NOT Shuffle I17 - Player Mute I18 - Player NOT Mute I19 * Web Radio Buffering I20 * Web Radio NOT Buffering Where: - Shape values are: 0=Rectangle 1=Square 2=Oval 3=Circle 4=Rounded Rect 5=Rounded Square - Comments are only for reference Note: The "NOT" indicators can be used to hide parts of the display, or to simulate a single indicator with different colours. (K) Link Buttons ---------------- These buttons perform special functions when pressed. The "Skin Link" buttons let you load a specific named skin. They can be used when you want to switch between your favorite skins or to have elements appear to move around etc. The "Web Link" buttons take you to the specified URL using your default browser. Format: Knn,x,y,w,h,x2,y2,key,tooltip,link K01-K10 Skin Link Button 1 to 10 K11-K20 Web Link Button 1 to 10 link = The name of the skin or URL to load (Note: Skin links should include the extension but not the path!) If you link to a "full-screen" skin and you have created a skin for each screen resolution you may use the format "name*" for the skinname. Mimic will substitute the current screen width into the name when the button is clicked. Example: Element definition: K01,.......,"deluxe*" Screen Skin to load ------ ------------ 640x400 "deluxe640.skin" 800x600 "deluxe800.skin" 1024x768 "deluxe1024.skin" ...and so on Make sure you have a skin that matches your screen resolution otherwise you will get an error message. Web Links can be used to open the default browser and use it to connect to the specified location. For example, to link to the Mimic home page you could do this: K11,......,"http://www.ryerson.ca/~sgray/mimic.htm" Note: Skin links can also be used effectively to create "dynamic" skins. If several skins use the same resource bitmap file there is no need to re-load the file, which means skins can change quickly. You could design a set of skins that work together to create a complex user interface using a series of ".skin" files. (L) Labels ---------- These are text labels that have a transparent background so that the graphics on the form show through. Format: Lnn,x,y,w,h,r,g,b,pt,font,tooltip L01 - Time (elapsed/remain) L02 - Track Title L03 + Current Time L04 - Track Number L05 - Snooze Time indicator L06 + Full Date L07 + Day of week L08 - Mute indicator L09 + AM/PM indicator (blank when in 24hr mode) L10 - Kbps L11 - KHz L12 - Stereo/Mono L13 - Total Track Time L14 - Playlist Title L15 - Status (playing/paused etc) L16 - Total entries in playlist L17 * Total time of all playlist entries L18 - Volume (0-100%) L19 * Jukebox Current Page L20 * Jukebox Max Page L21 * Jukebox Credits L22 * Jukebox Status L23 - Track to Play / Calculator Display L24 - Playback Rate (%) L25 - Balance (%left/right, centre) L26 - Mode (CD/Media) L27 - Current Conversion Description L28 - Currently Selected Timer L29 * Current Timer Status (Stopped/Running) L30 - Current Timer Value L31-40 - Timer 1 to 10 Value L41 - FM Frequency L42 - FM Station Name L43 - FM Preset Number L44 * Reserved L45 - Browser Document Title L46 - Browser Status L47 * Browser Download Status L48 * Reserved L49 * Reserved L50-L59 - Browser URL 1 to 10 L60 - Web Radio Station Name L61 - Web Radio Title L62 - Web Radio Author L63 - Web Radio Status (Stopped/Playing/Buffering etc) L64 - Web Radio Buffer % L65 - Web Radio Stream Rate (bps) L66 - Web Radio Elapsed Time L67-L68 * Reserved L69 - Media Filetype (extension) L70 - Lyric; Current Line L71 - Lyric; Next Line L72 - Lyric; Previous Line (S) Sliders / Graphic Indicator ------------------------------- These are analog sliders that can be dragged to any position and Graphic Indicators whos width or height changes proportionally in sync with another slider. Format: Snn,x,y,w,h,x2,y2,w2,h2,tooltip S01 - Playback 1 position S02 - Main Volume S03 - Main Balance S04 - Main Volume Indicator (graphic) S05 * Playback Rate (Speed) S06 - FM Frequency Dial S07 * Playback 2 position Notes: - x,y are the position of the top left of the slider - w,h determine the length of the slider. One MUST be zero! - x2,y2,w2,h2 is the position of the slider image in the res bitmap. - For graphics indicators w2 and h2 should be the same as w and h! (T) Text Input Field -------------------- Format: Tnn,x,y,w,h,r,g,b,pt,font,tooltip T01 - FM Station Description T02 - Web Browser URL T03 - Web Radio Description and URL (Desc @URL) (X) Other Elements ------------------ Format: Xnn,x,y,w,h,r1,g1,b1,r2,g2,b2,pt,font,tooltip X01 - Playlist 1 (PL1) X02 - Notepad Area X03 * Playlist 2 (PL2) X04 - Lyrics Area X05 - Calculator Conversion List X06 - FM Preset List X07 - URL Entry/History List X08 - WebRadio Station List Where: - r1,g1,b1 are foreground colours - r2,g2,b2 are background colours - Note: Not all elements support all properties Import skins ============ Import skins are standard skins with additional commands to read bitmap files and assemble them into a format that Mimic understands. To indicate an import skin, line 4 of the skin definition file must start with a "*". The format is: *,directory,filter,defaultfile - The directory is the default location for importing. - The filter determines the type(s) of files to show. - The defaultfile is the name of the main file. There are three temporary bitmaps (0 to 2) that you can use: 0 - Corresponds to the main bitmap 1 - Corresponds to the resource bitmap 2 - Temp bitmap. Used as the source for blitting to 0 or 1. The following extra commands are available: * Rn,filename - Read bitmap (0=main,1=resource,2=temp) * ?c,label - Conditional forward jump based on success of R cmd Where c is: 0=false, 1=true * :label - Label (target of ? cmd) * Wn,w,h - Set width/height of bitmap (0 or 1) * Zn,x,y,w,h,x2,y2 - Blits from temp to main or resource bitmap * USE - use bitmaps (copy 0 to main, 1 to resource) The "R" command reads in a bitmap from the import path. You can use the "?" command to test if the read command was successful (1=yes,0=no). The command can be used to skip other commands/elements that depend on the bitmap existing (ie: blit commands and buttons). Example: R1,playlist.bmp ;read the playlist bitmap file ?0,skip ;if it doesn't exist (0=false) jump to the line labelled "skip" ... ;do whatever you need here (ie: blit and define elements) :skip ;this is the label it jumps to if false ... ;continue normal processing Note: The "?" command only jumps FORWARD. Labels do not have to be unique. How to make a non-rectangular skin (Window Regions) -------------------------------------------------------------- Method 1: Bitmap with "transparent" colour For the main bitmap pick a colour, then draw any area to become transparent in that color. Make sure you do not use that color anywhere in the bitmap that you want to be visible. In the skin use the letter "O" command to specify the transparent colour like this: O,r,g,b - where r,g,b are the red/green/blue values of the transparent colour Method 2: Vector Region Co-ordinates You must define all the points that make up the bounding area (region) or areas. Points are connected by straight lines, so to make a circular section you will need to specify many points. If you specify multiple regions that overlap a "cutout" (or hole) will be produced. For Single Regions you must first specify the number of points in the region, like this: Nnn - Where: nn is the total number of points For Multiple Regions you must specify the number of points in total, the number of regions and the number of points in EACH region, like this: Mnn,xx,R1,R2...Rxx Where: - nn is the total number of points - xx is the number of regions - R1 to Rxx are the number of points in each region Then, you must follow with the appropriate number of coordinate points in a list like this: Px,y Px,y Px,y etc... Coordinates are specified in pixels. If you list extra coordinates they will be ignored. If you list fewer coordinates the entire region(s) will be ignored! Note: Your form should be bigger than the entire region otherwise points outside the form rectangle will not produce the desired effect (the edge will be straight where the form ends). This could also be a good thing if used properly (for example with the "toggle large" button). In a Single region skin the last point will automatically be joined to the first point. In multiple region skins you must join them yourself in EACH region! Ending the skin --------------- The skin file must end with the single line: END Linking Skins ------------- There may be a situation where you need to "link" skins together to achieve the desired look or functionality for your skin. Example 1: You want to have a simple skin with minimal controls but sometimes need the ability to use the other controls, which you want to be located to the right. You could use the "toggle large" button to make the window wider but what if you had the power button in the "title bar" at the top right of the normal window? The button would now be in the middle of the titlebar and wouldn't look right. What you need to do is create another bitmap with the power button in the new location, which means you need a new skin file with new coordinates. You can do this by creating a new skin and "linking" the first skin to the new skin, then the second skin links back to the first one. Example 2: You would like to have the album cover bitmap normally visible but then when you click on a button you want the cover to be replaced by the playlist and the playlist editing buttons (move up/down del etc). You need to create two skin files each linking to the other. Example 3: You have a really outrageous non-rectangular skin, and like example#1 you want to display some controls only occasionally. One skin can't have two different region outlines, so you must link two skins. To link skins use link buttons K01 to K10 in the skin file. These buttons are just like normal buttons with the addition of the name of the skin file added to the end of the parameter list. The complete name of the skin file must be specified, however the name does not have to end in ".skin" (this lets you "hide" the skin from the standard select skin requester box). In the main file you link to the second skin (ie with button K01) then in the second skin link back to the original skin (also with button K01). In this way pressing the button appears to cause a transformation of the skin. For complicated skins you may need to use more than one link button. Some final tips when creating a skin ------------------------------------ * Use a bitmap editor with a pixel coordinate info display. Have the skin file open at the same time and use the mouse to help you locate the points for your elements. * By using the selection tool you can select a single "button" image to find out it's width and height. * Try to avoid moving the buttons around in the resource file. Remember, large areas that don't contain buttons can be used for the digital display digits. * The resource bitmap can be larger than the main bitmap. You can increase the width or hight of the resource bitmap to make room for the digital display digits. * If the main bitmap is large with lots of open areas you can also decrease the size of the resource bitmap by rearranging the elements into a small area. This will also reduce the memory requirement of the skin, however it means you will need to specify the new coordinates of each element (those that are moved only) in the skin file. Finally, if you think of a new or innovative way to improve the skin capabilities, don't hesitate to e-mail me. Thanks! Steve.