Fix error message spam when no player is running
[dockapps.git] / wmcdplay / ARTWORK
blob9173f4ab9e6532ab1b775063966cc4df3fba1e5e
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.
9 ARTWORK
10 =======
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                              ----------------------------------------
17 This file trys to explain how to create artwork files. Please feel free to send
18 me comments or improved versions.
21 BASICS
22 ======
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
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
47 PIXMAPS
48 =======
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
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):
74 /* XPM */
75 static const char * led_xpm[] = {
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):
87 /* XPM */
88 static const char * ledsym_xpm[] = {
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):
101 /* XPM */
102 static const char * ledtsel_xpm[] = {
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):
114 /* XPM */
115 static const char * symbols_xpm[] = {
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):
130 /* XPM */
131 static const char * cdplayer_xpm[] = {
134 THE DATA FILE - artwork.dat
135 ===========================
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:
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?
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).
153 How many buttons?
154 -----------------
155    eg.
157    int art_nbtns=5;
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.
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.
171    eg.
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 };
179    Each line defines 1 button:
180    symbol_x , symbol_y , num_vertices , x1 , y1 , x2 , y2 , x3 , y3 , x4 , y4 , x5 , y5
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.
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):
191    wmcdplay state:     0   1   2   3   4   5
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
203    eg.
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 };
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.
217    eg.
219    bool art_hidebtns=false;
221 Which led displays are there?
222 -----------------------------
224    eg.
226    bool style_leds[4]={ true, true, false, false};
228    That's basically:
229    show_time=true , show_track=true , show_status=false , show_trksel=false
231 Where are they?
232 ---------------
233    eg.
235    int art_ledpos[3][2]={ 8 , 7 , 37 , 45 , 0 , 0 , 0 , 0 };
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
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.
246 ARTWORK FILES
247 =============
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.