Page 1 of 1

Theme file format

Posted: Thu Nov 09, 2017 3:09 pm
by pjw
As you may know, Wman2 offers four inbuilt system palettes, 0..3. These help to ensure some semblance of aesthetical sanity, in that all programs using Wman will sport only one of four liveries. (It is, however, also possible to create liveries on a per job basis if you wish.)

It is easy to create your own colour schemes - or themes - by using the excellent QCoCo app by Bob Spelten and Wolfgang Uhlig ( The same format as produced by QCoCo can be used to change the inbuilt system palettes according to taste and to create bespoke palettes for specific programs.

You can test various system palettes from within QCoCo, and once satisfied, save them to disk and load them at boot time. I use the following routine, called from my stage 1 boot program:

Code: Select all

100 REMark Set all four Wman palettes
110 :
120 home$ = 'win2_util_col_coco_thms_'
130 ext$ = '_thm'
140 :
150 SetPal "grey", 0
160 SetPal "copper", 1
170 SetPal "meanie", 2
180 SetPal "blue", 3
190 QUIT
200 :
210 DEFine PROCedure SetPal(fnm$, palno%)
220 ch = FOP_IN(home$ & fnm$ & ext$): ERT ch
230 num = SP_GETCOUNT
240 mem = ALCHP(num * 2)
250 :
260 FOR adr = mem TO mem + (num - 1) * 2 STEP 2
270  INPUT#ch; col$
280  POKE_W adr, HEX(col$(2 TO))
290 END FOR adr
300 :
310 SP_SET palno%, mem, 0, num
320 RECHP mem
330 CLOSE#ch
340 END DEFine SetPal
350 :

This loads and sets the four system palettes that all PE program on my system use. You will have noticed that the format for these themes is simply a text file with a list of hex numbers:

.. etc, SP_GETCOUNT (currently 57) items long in all.

This may be convenient, but not very efficient, as a list of 57 binary words may be loaded in a jiffy by LBYTES. Faster and consuming less space.

After discussion with Bob, I proposed the following additional format which, once finalised, will be supported by QCoCo too:

The file extension will be _thb - for theme binary

The proposed THB File Definition will be (described in assembler):

Code: Select all

dc.l 'TH01'   ; Flag and version number
dc.w $200     ; sp_winbd% - Window border
..            ; etc

the new SetPalB procedure might then look like this:

Code: Select all

100 DIM thv$(4): thv$(0) = 4
110 :
120 REMark Set all four Wman palettes
130 :
140 home$ = 'win2_util_col_coco_thms_'
150 ext$ = '_thb'
160 :
170 ERT SetPalB("grey", 0):       REMark System palette 0
180 ERT SetPalB("copper", 1):     REMark System palette 1
190 ERT SetPalB("meanie", 2):     REMark etc
200 ERT SetPalB("blue", 3)
210 QUIT
220 :
230 DEFine FuNction SetPalB(fnm$, palno%)
240 thc = FOP_IN(home$ & fnm$ & ext$)
250 IF thc < 0: RETurn thc
260 BGET#thc; thv$(1 TO 4): thl = FLEN(#thc): CLOSE#thc
270 IF NOT (thv$ = 'TH01' AND thl = SP_GETCOUNT * 2 + 4): RETurn -12
280 tha = ALCHP(thl)
290 LBYTES home$ & fnm$ & ext$, tha
300 SP_SET palno%, tha + 4, 0, SP_GETCOUNT
310 RECHP tha
320 RETurn 0
330 END DEFine SetPalB
340 :

In a program where youd like to have a job-specific palette, you could use something like:

Code: Select all

DIM thv$(4): thv$(0) = 4
thc = FOP_IN(theme$)
BGET#thc; thv$(1 TO 4): thl = FLEN(#thc): CLOSE#thc
IF thv$ = 'TH01' AND thl = SP_GETCOUNT * 2 + 4 THEN
 tha = ALCHP(thl)
 LBYTES theme$, tha
 SP_JOBOWNPAL -1, tha + 4

Now it might be argued that the extra ID is an unnecessary security feature. After all we already have the extension, _thb, and know the expected file size, SP_GETCOUNT x 2. Also you wont crash the computer if you happen to have a thb file with 114 bytes of nonsense.. Besides, so many other formats in QL land dont have any ID (sprites, screens, etc).

We thought it was a good idea to have the extras ID, but now I waiver..

Any views on this?

Re: Theme file format

Posted: Thu Nov 09, 2017 7:18 pm
A good idea - I like the idea of an identifier at the start however, so that it would be possible to load a single theme file format with several sets of palettes if necessary - eg to have a different system palette for a secondary program running within the main one; or maybe to allow a different system palette dependent on whether text or icons are being displayed to control a program....

Re: Theme file format

Posted: Thu Nov 09, 2017 8:30 pm
by NormanDunbar
I agree, the flag and version word makes sense, especially as it could happen that progress takes us on to new versions of wman etc with a different number of words required for a theme. Unlikely, I admit, but still possible. We could increment the version then to ensure, along with flen, that we are loading a correct theme.


Re: Theme file format

Posted: Fri Nov 10, 2017 4:16 pm
by pjw
Rich suggests the following improvement, with which I concur:

dc.w 'TH' ; identifier
dc.b 1 ; version number
dc.b 57 ; number of word entries in the table
dc.w $200

Should be good until the turn of the century..

Re: Theme file format

Posted: Sat Nov 11, 2017 4:01 pm
by pjw
I know some people must find this incredibly unimportant and boring, but Im on the cusp of having to commit, so I need to be sure that Ive made a future-proof choice. I know, we could just go to one of our Oracles for a "best answer", but that would be a cop out. Anyway, Ive been thinking some more, and Ive come up with the following suggestion:

dc.b "THB", 57

dc.w $0400
dc.w $FFFF

The reasoning is as follows: The header is only required so we know we have the correct file type and that the data is likely to conform with what we expect. If WMAN2 were expanded to use a palette of say 58 items, the new value of SP_GETCOUNT would warn us that the file was the wrong version.

If for any reason, in the future, it would be necessary to indicate that a completely new and incompatible version was in effect, it would be simple enough to adopt a new header for the format, say:

dc.b "THC", xxx

If the THC format also turned out to have 57 entries we'd be fcuked, of course, but using the version number of n wouldnt have helped either. So to my mind, THB, 57 is just simpler and cleaner, without any adverse effect on the integrity of the format.

Unless there are any objections within the next 7 days, this will be what I commit to.

Re: Theme file format

Posted: Fri Nov 17, 2017 11:14 am
by pjw
Ok, after all the fuss, Im inclined to go with a header-less binary file after all. That is, currently, 57 * 2 = 114 bytes of palette information in the same order as that currently used by Wman2 (and _thm files as used by QCoCo). The order is unlikely to change, and should the number of items change, the length of the file will give the game away. Where the wrong file to be loaded, no calamity will ensue, provided the programmer reserves sufficient memory, ie: memory >= size of the actual file (rather than the expected size of the file). With this announcement, I wish to claim the thb extension for this purpose and format!

Thanks to all for your input. It helped clarify the issue.

PS: ModView is a minor utility by me that uses this format. It simply lists all the modules contained in an SMSQ/E binary. ModView06_zip is available from Dilwyn's at