wmcdplay/ARTWORK

   1 wmcdplay - A cd player designed for WindowMaker
   2 Copyright (C) 1998  Sam Hawker <shawkie@geocities.com>
   3 This software comes with ABSOLUTELY NO WARRANTY
   4 This software is free software, and you are welcome to redistribute it
   5 under certain conditions
   6 See the README file for a more complete notice.
   7
   8
   9 ARTWORK
  10 =======
  11
  12 The artwork mechanism allows you to customise the appearance (and more) of
  13 wmcdplay at run-time, by loading an artwork file with the "-f artwork_file"
  14 command line argument - yes, THIS IS A CHANGE!!!!! IT USED TO BE "-a"
  15                              ----------------------------------------
  16
  17 This file trys to explain how to create artwork files. Please feel free to send
  18 me comments or improved versions.
  19
  20
  21 BASICS
  22 ======
  23
  24 wmcdplay can be in any one of 6 states:
  25    Data     0
  26    Stopped  1
  27    Playing  2
  28    Paused   3
  29    NoCD     4
  30    TrayOpen 5
  31
  32 wmcdplay buttons can perform any of 10 actions, and the action can
  33 depend on the current state of wmcdplay:
  34    NOTHING 0
  35    Stop    1
  36    Play    2
  37    Pause   3
  38    Resume  4
  39    Prev    5
  40    Next    6
  41    Rewd    7
  42    FFwd    8
  43    Eject   9
  44    Close   10
  45
  46
  47 PIXMAPS
  48 =======
  49
  50 The following symbolic color names may be used in any pixmaps:
  51    led_color_high
  52    led_color_med
  53    led_color_low
  54    color_back
  55 and should be used appropriately to ensure that the led and background
  56 colors can be set at runtime with the "-l led_color" and "-back_color"
  57 command line arguments
  58
  59 led.xpm
  60 -------
  61    This pixmap is used by wmcdplay to draw the digits of the time and
  62    track displays
  63    It represents the string of characters: "00112233445566778899  DDAATTNNOOCC--PPEE:;_"
  64    "00" means the character "0" but states that it is double width (eg 7+1 pixels wide)
  65    ":" means the character ":" which is only single width (eg 3+1 pixels wide)
  66    ";" means an unlit ":" single width character
  67    "_" means a single width "-" character
  68    The digit size used does not matter, but ensure that 1 pixel spaces are left between
  69    digits and that (double width + 1 space) = 2 * (single width + 1 space)
  70    eg.                            ( 7 + 1 ) = 2 * ( 3 + 1 )
  71    Transparency is _NOT_ interpreted
  72    This file must begin with these 2 lines (character perfect):
  73
  74 /* XPM */
  75 static const char * led_xpm[] = {
  76
  77 ledsym.xpm
  78 ----------
  79    This pixmap is used by wmcdplay to draw the symbols illustrating the current status
  80    It should contain symbols for the following (in sequence):
  81       Data, Stopped, Playing, Paused, NoCD, TrayOpen
  82    The symbol size used does not matter, but ensure that 1 pixel spaces are left between
  83    symbols
  84    Transparency is _NOT_ interpreted
  85    This file must begin with these 2 lines (character perfect):
  86
  87 /* XPM */
  88 static const char * ledsym_xpm[] = {
  89
  90 ledtsel.xpm
  91 -----------
  92    This pixmap is used by wmcdplay to draw the symbols illustrating the current track
  93    selection mode
  94    It should contain symbols for the following (in sequence):
  95       None, Next, Repeat, RepeatCD, Random
  96    The symbol size used does not matter, but ensure that 1 pixel spaces are left between
  97    symbols
  98    Transparency is _NOT_ interpreted
  99    This file must begin with these 2 lines (character perfect):
 100
 101 /* XPM */
 102 static const char * ledtsel_xpm[] = {
 103
 104 symbols.xpm
 105 -----------
 106    This pixmap contains the symbols to be drawn onto the buttons
 107    It should contain symbols for the following (in sequence):
 108       NOTHING, Stop, Play, Pause, Resume, Prev, Next, Rewd, FFwd, Eject, Close
 109    The symbol size used does not matter, but ensure that 1 pixel spaces are left between
 110    symbols
 111    Transparency _IS_ interpreted
 112    This file must begin with these 2 lines (character perfect):
 113
 114 /* XPM */
 115 static const char * symbols_xpm[] = {
 116
 117 cdplayer.xpm
 118 ------------
 119    This pixmap provides the basic background for wmcdplay
 120    It _must_ be 64x64 pixels
 121    It should provide solid areas (the size and color of which will depend on the
 122    led.xpm, ledsym.xpm and ledtsel.xpm files used), for any required displays to
 123    be drawn onto
 124    These areas are usually bordered in some way
 125    It can also be used to provide solid areas which can form buttons
 126    (Although the button symbols can themselves form the buttons)
 127    Transparency _IS_ interpreted
 128    This file must begin with these 2 lines (character perfect):
 129
 130 /* XPM */
 131 static const char * cdplayer_xpm[] = {
 132
 133
 134 THE DATA FILE - artwork.dat
 135 ===========================
 136
 137 So far, all we have in our artwork file is a set of pixmaps. But we also
 138 need a data file (artwork.dat), to answer the following questions:
 139
 140    How many buttons are there?
 141    Where exactly is each button?
 142    What does each button do?
 143    Should do-NOTHING buttons be hidden?
 144    Which led displays are there?
 145    Where are they?
 146
 147 The formats of entries in this file must follow the examples given quite closely.
 148 Basically, anything before an '=' must appear exactly as shown and at the
 149 beginning of the line (not indented as here). Also, all entries must be on a single
 150 line unless shown otherwise here.
 151 Comments and blank lines are, however, perfectly legal (between entries).
 152
 153 How many buttons?
 154 -----------------
 155    eg.
 156
 157    int art_nbtns=5;
 158
 159 Where exactly is each button?
 160 -----------------------------
 161    Buttons must be shaped as convex polygons, so you give the position
 162    (and shape) of each as a list of coordinates of its verticies.
 163    The polygon defined by these points is used to interpret mouse clicks,
 164    and also (optionally) to hide do-NOTHING buttons.
 165
 166    Also, tell wmcdplay where on the button to put the symbol. This is in the
 167    form of the co-ordinates of the top-left corner of the symbol, relative
 168    to the top-left corner of wmcdplay.
 169    A single entry, defines all buttons.
 170
 171    eg.
 172
 173    int art_btns[]={ 8  , 38 , 5  , 5  , 27 , 7  , 27 , 20 , 40 , 7  , 54 , 5  , 54 ,
 174                     19 , 26 , 5  , 6  , 22 , 28 , 22 , 28 , 39 , 22 , 39 , 6  , 24 ,
 175                     19 , 50 , 5  , 6  , 57 , 21 , 42 , 28 , 42 , 28 , 59 , 6  , 59 ,
 176                     35 , 26 , 5  , 31 , 22 , 52 , 22 , 52 , 24 , 37 , 39 , 31 , 39 ,
 177                     51 , 31 , 5  , 42 , 36 , 56 , 22 , 59 , 22 , 59 , 39 , 42 , 39 };
 178
 179    Each line defines 1 button:
 180    symbol_x , symbol_y , num_vertices , x1 , y1 , x2 , y2 , x3 , y3 , x4 , y4 , x5 , y5
 181
 182    Different buttons may have different numbers of vertices, so different numbers of fields.
 183    The button must be a _convex_ polygon, and the vertices must be given in sequence, going
 184    _clockwise_ around the button.
 185
 186 What does each button do?
 187 -------------------------
 188    This is answered with a set of integer actions (see list given earlier) for each button,
 189    for each state (see list given earlier):
 190
 191    wmcdplay state:     0   1   2   3   4   5
 192
 193                        D   S   P   P   N   T
 194                        A   T   L   A   O   R
 195                        T   O   A   U       A
 196                        A   P   Y   S   C   Y
 197                            P   I   E   D
 198                        T   E   N   D       O
 199                        R   D   G           P
 200                        K                   E
 201                                            N
 202
 203    eg.
 204
 205    int art_actions[]={ 0 , 2 , 3 , 4 , 0 , 0  ,
 206                        5 , 5 , 5 , 0 , 0 , 0  ,
 207                        6 , 6 , 6 , 0 , 0 , 0  ,
 208                        0 , 0 , 1 , 1 , 0 , 0  ,
 209                        9 , 9 , 9 , 9 , 9 , 10 };
 210
 211 Should do-NOTHING buttons be hidden?
 212 ------------------------------------
 213    This can be set so that whenever a button has NOTHING assigned to it, it is hidden
 214    (using the region defined by style_btns). Otherwise it is left and the symbol
 215    representing NOTHING is drawn onto it.
 216
 217    eg.
 218
 219    bool art_hidebtns=false;
 220
 221 Which led displays are there?
 222 -----------------------------
 223
 224    eg.
 225
 226    bool style_leds[4]={ true, true, false, false};
 227
 228    That's basically:
 229    show_time=true , show_track=true , show_status=false , show_trksel=false
 230
 231 Where are they?
 232 ---------------
 233    eg.
 234
 235    int art_ledpos[3][2]={ 8 , 7 , 37 , 45 , 0 , 0 , 0 , 0 };
 236
 237    That's basically:
 238    time_x=8 , time_y=7 , track_x=37 , track_y=45 , status_x=0 , status_y=0 , trksel_x=0 , trksel_y=0
 239
 240    These are the co-ordinates of the top-left corner of each display
 241    relative to the top-left corner of wmcdplay.
 242    You should enter valid integers even for displays which you have
 243    chosen not to use.
 244
 245
 246 ARTWORK FILES
 247 =============
 248
 249 All the above files should be placed in an appropriately named directory and the
 250 "makeart" script (installed by default in /usr/local/share/wmcdplay) should be
 251 executed in the parent directory.  You should end up with a new .art file.  You
 252 should be able to load wmcdplay with this artwork using the "-f artwork_file"
 253 command line argument.
 254 You should also be able to make your new artwork the compile-time default by
 255 using the "--with-art" option to the "configure" script.