NetNews Usenet Archive 1992 #31

home *** CD-ROM | disk | FTP | other *** search

/ NetNews Usenet Archive 1992 #31 / NN_1992_31.iso / spool / comp / sys / acorn / tech / 1144 < prev next >

Wrap

Internet Message Format | 1993-01-01 | 29.3 KB

Path: sparky!uunet!pipex!demon!kernow.demon.co.uk!vulch Newsgroups: comp.sys.acorn.tech From: vulch@kernow.demon.co.uk (Anthony Frost) Reply-To: vulch@kernow.demon.co.uk Subject: New Template format discussion document Organization: VCS Kernow X-Mailer: ReaderS for the Acorn Archimedes Date: Fri, 1 Jan 1993 20:04:48 +0000 Message-ID: <930101200448@kernow.demon.co.uk> Sender: usenet@demon.co.uk Lines: 712 Following the discussion before christmas about Template files, I've been asked to post the following by Tim Browse, author of !Glazier. He has given a couple of addresses he can be reached at, in addition if you want to mail to TimB@kernow.demon.co.uk I'll forward things to him. Anthony --------------------------------------------------------------------------- WARNING - THIS IS A LONG MESSAGE ! IGNORE IF YOU'RE NOT INTERESTED IN A NEW TEMPLATE FILE FORMAT. Proposed Glass File Format ========================== This file/message concerns the proposal of a new Template file format. The present Risc OS format for window and icon definitions, while useful, can be restricting, and a standard for centralising resources would be a boon to many people. In the absence of action by Acorn, I've decided to come up with standard for people to comment on, partly encouraged by a number of other people expressing a desire for such a facility. (By 'absence of action by Acorn', I mean that when I asked for a filetype to do this, no-one at Acorn said "Hang on, we're about to do something like that!", and, as I assume this is half the point of Acorn being the organisation that allocates filetypes, I guess nothing is happening soon. This may be a nave assumption but it's all I've got to go on. I guess if I asked Acorn outright (like I did about C++ etc) I'd get the usual "Acorn has a continuous product upgrade policy blahblahblah" (like I got about C++ etc). I'd certainly welcome comment from Acorn, but I'm not holding my breath. The filetype is called, in case you're wondering, "Glass". This is because it was obtained to be used by my freeware Template editor 'Glazier' (plug). However, I see no reason to restrict its use in any way. The name stays, though :-) Objectives ~~~~~~~~~~ * An alternative to the current Template file. * Facility to hold information about entities other than windows and icons e.g. menus, icon names, meta-icons etc. * Make it simple to use, namely: + Provide a template editor that can create Glass files and convert Glass <-> Template files. + Provide support code to use any special features (e.g. meta-icons, position independent menus etc) + Provide a program to create Template files from Glass files so Risc OS Lib will work ok, and generally ease the transition. * Reasonably efficient format, within reason - e.g. 32-bit words will be used for number storage as opposed to bytes - I think we can handle an overhead of a few hundred bytes in our files (at worst). Unless lots of numbers are stored. * Make it an extensible tagged file format. Divide information into chunks, and have keys + file offsets to find them. Then if you don't understand a certain chunk, it's ignored. Also, a chunk must only contain relative file offsets *within* itself so that chunks may just be copied verbatim from one file to another. This means someone could write a simple filter to map the font chunk entries to different fonts and still preserve the rest of the Glass data. i.e. it should be possible to divide up the chunks of a Glass format file, and write them back in any order and the file would still be a legal Glass file, as long as the header entries point to the correct data. * As you may have noticed, the above is very similar to Acorn's chunk file format, and hence I propose to get an official chunk prefix from Acorn, and use the Chunk file format. The format of the chunks themselves will of course be defined by myself and others. The reason I intend to use the chunk file format is that everything it does is needed by Glass files, and I see no reason to re-invent wheels. A filetype is still needed so I and all the other lazy people can just double click on the file to edit it :-) A considerable amount of file structure will be present in the chunks themselves, and it may seem unncessary to bother with chunk files with this first standard, but bear in mind that this format is meant to be extended. If you feel strongly that chunk files should not be used, I am open to suggestions. Remember that if this standard is adopted, you're stuck with it - so it had better be able to handle what you might want to do in the future. * Make people *want* to use it by providing features they want(!) * Where necessary, a chunk will be timestamped to indicate when it was last edited. This may seem strange but it's necessary. Consider the following: Without timestamps ~~~~~~~~~~~~~~~~~~ Kate edits a window definition by moving an icon. Kate tests new layout. Kate edits source to add a new feature. Kate makes the project, only to find that because the Glass file has been edited, amu thinks the icon header file should be regenerated, and it is, and so half the source is re-compiled as a result. Kate yawns a lot. With timestamps, whatever program generates header files from Glass files (a command line version will be available for use with amu) will only generate from those chunks that, according to the chunks' timestamps, are newer than the files they generate. This means that in the above example, the icon header file is not re-created, and so only the source that needs to be is compiled. I don't care if you don't like this - I need it so it's going in! The timestamp will have to go at the head of the chunk itself as Acorn's chunk file format doesn't support this, but I don't consider that a good enough reason to discard the chunk format. Tell me if you disagree. Obviously, this assumes some intelligence on the part of the Template Editor, but that shouldn't be too much of a problem. * Don't use icon validation strings - there's already too much crap in them. * Structure the file so that it's reasonably quick to load. i.e. don't make it necessary to have to guess memory requirements (can you say Wimp_LoadTemplate?) or to do excessive disc thrashing. I have, in a number of places, made various trade-offs between efficiency and convenience. To establish a standard ~~~~~~~~~~~~~~~~~~~~~~~ I have a filetype allocated from Acorn for this purpose. I'd rather obtain a consensus of opinion on the subject than impose my own ideas (barring time-stamping of chunks - that's going in no matter what! :-). For this reason, this message will be posted to comp.sys.acorn for comment, and publicised anywhere else I can think of. Please feel free to show this to anyone who may be interested or have some ideas, or may even be doing the same thing themselves - let's not waste effort! If you see anything missing, or horrific causes for concern re: efficiency or you think that 40 characters is too much/little for window identifiers, or if you find anything that's just plain wrong, please tell me. Just try not to prefix your communications with "You wazzocking great twonk!" or similar, as defenestration often offends. For the first standard, the objective is simple. The format will allow storage of Templates as in a normal Template file, and also a system for naming Icons, so that names rather than icon numbers can be used to identify icons in programs. Most programmers use #defines (or their equivalent) instead of numbers at the moment, but this will automate the process, by generating one or more header files containing the #defines/equates necessary. The programmer would use a template editor to associate names with icons. The reasoning behind this is: * People are more likely to adopt a standard if it is initially simple and provides some feature they like (e.g. like saving them the trouble of checking icon numbers). I certainly need it - some of Glazier's windows have in excess of 100 icons. * People are more likely to *comment* on a standard if the basic framework is put in place and then extensions are added as and when required. People are, I think, less likely to wade through a 35-page document that comes at them from nowhere, like some electronic custard pie. And if people don't comment on it, some important feature may be missed, causing the standard to fall from favour, and hence from use. * If a simple standard is put forward, it will be agreed on reasonably quickly (I hope!) and it can start to be used. If some huge standard is introduced it will be argued over for ages and will probably die. I don't want this - I want something I can use, without having to keep on re-inventing wheels. This concept may pass over the heads of ARM assembler programmers ;-) * I don't have time at present to think in depth about all the features required and produce a *complete* standard. And if I can't think about it in depth, I'll probably get it wrong, and I don't want to do that. * The important thing is to have an extensible standard! Chunk files make this possible. The Proposed Standard ===================== Basic Format ~~~~~~~~~~~~ As mentioned, the file will be a chunk file as specified in the Acorn C (and, I assume, Objasm) manuals. For Desktop C, it's on pp226-228 of the "Acorn Desktop Development Environment" manual. If anyone doesn't have access to it I'm sure myself or someone else could outline the format if necessary. In this explanation, the chunk file offset for Glass files is assumed to be "GLS_". This depends on Acorn. In fact, if they get unhelpful, I'll just use it anyway - won't really make much difference as the file will be filetyped too. Chunks in Glass files ~~~~~~~~~~~~~~~~~~~~~ Name Use ~~~~ ~~~ GLS_INFO Miscellaneous info about this file and the Glass version it conforms to. GLS_FONT Maps fonthandles used in Glass file to Risc OS font names. GLS_WIND Window and icon definitions (much the same as Templates) GLS_NAME Names used to refer to icons. Chunk formats ~~~~~~~~~~~~~ Bear in mind throughout these descriptions that we know the total size of each chunk from the chunk file header. Also, please bear in mind that although some structures may seem slightly wasteful of memory, this is the format of a disc file, and these wastages may not necessarily translate into memory wastages (e.g. indexes will only be used while loading the file, and then discarded). GLS_INFO ======== Chunk Field Field Name & Offset: Size: Meaning: 0 4 Info_GlassVersion This is the version of the Glass Format that this file conforms to. An unsigned word, at present assigned as follows: MSB LSB AAAABBCC where: AA = reserved BB = Major version number CC = Minor version number So version 2.12 would be encoded as &0000020C. 4 16 Info_Reserved Reserved bytes - should be 0. 20 ? Info_CreatorName A null-terminated string indicating the program that created this Glass file. e.g. "TemplateEd" or "Glazier" Comments ~~~~~~~~ None. GLS_FONT ======== Chunk Field Field Name & Offset: Size: Meaning: Header: 0 4 Font_Num (0 => no fonts used in Glass file) Number of font handles defined in this chunk. Font handles always numbered 0 to Font_Num-1. 4 16 Font_Reserved Reserved bytes - should be 0. 20 Start of font handle index - see below. Font handle index: i+0 4 Font_Offset 0 Chunk offset to font data for handle 0. i+4 4 Font_Offset 1 Chunk offset to font data for handle 1. ... i+(n-1*4) 4 Font_Offset n-1 Chunk offset to font data for handle n-1. Font data entries: (pointed to by index entries) d+0 4 Font_XSize x point size * 16 d+4 4 Font_YSize y point size * 16 d+8 ? Font_Name A null-terminated string. (e.g. "Trinity.Medium.Italic\0") Comments ~~~~~~~~ None. GLS_WIND ======== Chunk Field Field Offset: Size: Meaning: Header: 0 4 Wind_NumWindows - number of windows defined in this chunk. 4 4 Wind_WindDefnSize Size of the Wind_WindDefn Fields in window data blocks (see below). At present 88, but may change. 8 4 Wind_IconDefnSize Size of the IconDefn fields in window data blocks (see below). At present 32, but may change. 12 4 Wind_IndDataOffset Chunk offset of indirected data table for this window. 16 16 Wind_Reserved Reserved bytes - should be 0. 32 Index: i+0 40 Wind_Id A null-terminated string identifying the window. e.g. "ProgInfo". i+40 4 Wind_Offset Chunk offset for data for this window entry. i+44 4 Wind_Size Size of data for this window entry i+48 16 Wind_Reserved Reserved bytes - should be 0. i+64 Start of next index entry (i.e. Wind_Id). Window Data blocks: d+0 88 Wind_WindDefn A window definition block as passed to the SWI Wimp_CreateWindow, with the exceptions noted below. d+88 32 Wind_IconDefn 0 Icon definition for first icon of this window (if any). Block is as passed to the SWI Wimp_CreateIcon, with the exceptions noted below. d+120 32 Wind_IconDefn 1 etc... Indirected Data tables: t+0 4 Ind_NumEntries Number of data entries in this table. t+4 4 Ind_ChunkOffset 0 Chunk offset for indirected data entry 0 t+8 4 Ind_ChunkOffset 1 Chunk offset for indirected data entry 1 ... t+ 4 Ind_ChunkOffset Ind_NumEntries-1 4*Ind_NumEntries Chunk offset for indirected data entry number (Ind_NumEntries-1). Indirected Data blocks: id+0 ? Ind_Data Can be a validation string, or text string, or sprite name. Null-terminated - NOT control terminated! Comments ~~~~~~~~ Window data blocks ~~~~~~~~~~~~~~~~~~ Offsets in these blocks should not be taken to be valid forever - use Wind_WindDefnSize and Wind_IconDefnSize to ensure any embarrassments are avoided. Window data blocks need not be in the order they appear in the index, so long as the chunk offsets are correct. They need not be contiguous in the chunk either. The exceptions in window/icon definition blocks are as follows: Sprite area control block pointers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Glass files, two possible values are used: 0 => Local application sprite area 1 => Wimp sprite area Indirected data ~~~~~~~~~~~~~~~ When indirected icons (including the window title bar) occur, the datum for a sprite name, text buffer or a validation string is actually an index into the indirected data table. Use this datum to find the chunk offset of the data. E.g. An indirected text icon has a validation string entry of 2. Look up the third entry (as index starts from 0) in the indirected table index. This gives the chunk offset of the data. Thus looking in the file at position (ChunkStart+ChunkOffset) will yield the required data. This additional level of indirection is intended to make it slightly easier to generate Glass files (as you'll know if you've ever tried to generate Template files :-( ). Font handles ~~~~~~~~~~~~ These are, of course, the internal font handles used throughout the Glass file, and not font handles as understood by the Risc OS FontManager module. The GLS_FONT chunk can be used to convert them to real font handles - this will usually be done by the library routines that support Glass files. GLS_NAME ======== Chunk Field Field Offset: Size: Meaning: Header: 0 5 Name_TimeStamp Standard 5-byte Risc OS Time stamp. See Risc OS 2 PRMs, p550, "Real time". 5 4 Name_IconPrefix Chunk offset of null-terminated string specifying the global prefix for icon names. 0 => no prefix. 9 4 Name_IconSuffix Chunk offset of null-terminated string specifying the global suffix for icon names. 0 => no suffix. 13 Window name block: (assuming n icons in window) w+0 40 Name_WindowId Window Id of the window this naming block refers to. (see GLS_WIND chunk details). w+40 4 Name_WindowPrefix Chunk offset of null-terminated string specifying the prefix for names of icons in this window. 0 => no prefix. w+44 4 Name_WindowSuffix Chunk offset of null-terminated string specifying the suffix for names of icons in this window. 0 => no suffix. w+48 4 Name_IconName 0 Chunk offset of null-terminated string specifying the name of icon 0 of this window 0 => anonymous icon w+52 4 Name_IconName 1 Chunk offset of null-terminated string specifying the name of icon 1 of this window 0 => anonymous icon ... w+48+4*n 4 Name_IconName n-1 Chunk offset of null-terminated string specifying the name of icon (n-1) of this window 0 => anonymous icon w+52+4*n ? Data for icon names... Comments ~~~~~~~~ There is a window name block for each window that contains icons referenced by name. Hence a window with no icons referenced by name (eg a window with no icons such as Edit's main window) would not have a window name block. Icon names have 5 components, all but one of which, the actual icon name, may be null. An full icon name is a string constructed as follows: Name_IconPrefix + Name_WindowPrefix + Name_IconName + Name_WindowSuffix + Name_IconSuffix This allows for (almost) any naming scheme the user can think of. e.g. The scheme I use at present in Glazier would be defined as: Name_IconPrefix = "ICON_" Name_IconSuffix = "" And for the ProgInfo window: Name_WindowPrefix = "PROGINFO_" Name_WindowSuffix = "" And Icon names... Name_IconName = "VERSION" giving a name of "ICON_PROGINFO_VERSION", which is what I in fact use. Thus any naming scheme can be used, or, if the user sets all suffixes and prefixes to be null, they can just use a unique name for each icon in the program. Or they could have: IconOK IconCANCEL or OkButton_windowQUIT CancelButton_windowQUIT or anything really... End Of Proposed Standard ------ oOo ------ Just so we're clear, my philosophy is as follows: I would like to see something on the Arc which is an extension of the Template concept. Templates are already very useful (much better than the way X windows does things) - something along the lines of MS-Windows resources would be nice, although I'd prefer it to be not quite as grotesque and obscene to use (I fight with Borland C++/MS-Windows for a living). I have written a freeware template editor, Glazier (which I may have mentioned before :-) which will support as many features of the Glass format as I have time for. I will probably provide the source as freeware at some point so you can add your own features if you so desire, and possibly send them to me for inclusion in a future release. The source is in C, and uses the DeskLib library (try changing from RiscOSLib to DeskLib for your next project - it's like taking off a strait-jacket). The Glass format will be completely public, and if someone wants to implement a feature I consider relevant to it, I won't put up too much opposition, even if Glazier isn't updated to use it. I may object if I think it could or should be done better some other way. I am *not* interested in a "my template editor is better than your template editor" argument (users of Arcade BBS may detect an undercurrent here). I am *not* interested in slagging off Acorn for the fun of it (well, maybe just a bit), although it would have been nice for them to have introduced larger data blocks for icons in Risc OS 3. I am keen to get a group of people involved in this (so far, it's me and thee, TMOTA) as I do have other things to do (like writing programs using the fantabulous new Glass format), so the more the merrier, as long as it's organised properly. As I have the filetype, I'll be the moderator for the time being. This may change if someone really keen comes along. I'm not interested in crippling other author's template editors etc - if I implement a new feature, I'll distribute the source to whoever's interested so they can see how it works easily, and can use the source in their own programs (as long as (a) it's non-commercial or (b) they get my written permission first). While we're at it, I'm useless at defining icons - anyone feel like defining one for Glass files? I've had a go, but my effort's a bit specific to Glazier. +=============+ |FLAME WARNING| +=============+ Could we PLEASE have a little restraint in quoting on comp.sys.acorn??? Your message should ideally contain no more than one third quoted material (unless your message is short ie <20 lines in which case two thirds is about right). Some people have to *PAY* to read comp.sys.acorn and seeing the point-and-grunt users who have fallen into a University quoting banal (and frankly very tedious after the third time of seeing them) signatures to three levels of nesting is rather frustrating. Is it ever necessary to quote a signature??? If you wonder why British Telecom (substitute local Telephonic Company here) makes so much damn money, it's partly down to you! I know some people think big signatures are great but most people grew out of them ages ago (I must admit I never found them appealing). Here's a good rule of thumb: Count the characters you typed in response to a message, and then count the characters involved any quoting and signatures (including yours). If the percentage of junk out of total message size is more than 50%, do something about it. The worst case I saw at University was a message of about 1000 characters, of which 3 were relevant(!) +==========+ |FLAME ENDS| +==========+ Having said that, sorry this is such a long message, but it's a bit tricky to define a standard otherwise. Some individual messages: ========================= To Jason Williams: ~~~~~~~~~~~~~~~~~~ Thanks for forgetting my name (:-) and for the ideas on menus etc - I may even get around to it one day. I'm sure you'll have a lot to say on this standard :-) Feel free to post Glazier to comp.mumble.binaries/newky server/wherever - I don't mind and I'd rather people didn't have to use FormEd >:-) You may find some people hate it mind you - some people have said it's awful to use; FormEd is much better; Glazier's full of bugs and I should junk it and re-write it from scratch. It's funny, but I've never seen such vitriolic reactions to a piece of FREE software before - is there something about Template Editors that really gets the blood of a manly Archimedes programmer boiling? :-) To D.Pead: ~~~~~~~~~~ > The problem with using a new template file standard is (a) I don't think > you could ever get it to work with RISC-OS lib without horrendous kludges. > (Yes, RISC-OS Lib is c**p, but I wrote a few programs before I realised > that and I don't fancy re-writing them!) and (b) If those lads and lasses > at Acorn & Norcroft sort us out with a nice C++ compiler and class > library, you'd be back to square one. (a) I don't agree with this. I originally conceived this for use with RISC_OSlib. You just have a Glass file containing the templates and icon names in one place. Part of the make process could be to generate a 'vanilla' Acorn Template file and a header file for icon name constants. There's no reason why this should then not be used with Risc OS Lib. The point is that the Glass file is the repository for resources - whether it's actually used directly at run-time is not important. The important thing is automating things that the programmer shouldn't have to worry about. Note that when using RISC_OSlib the Glass file would not need to be distributed with the final program, only the Template file. A program that used Glass-specific features, on the other hand, would have the Glass file but probably not the Template file. You don't have to worry about redundant information being in the Glass file of your final application (e.g. icon names) cos you can just filter it out, and very easily too, due to the autonomous nature of the chunks. (b) Quite possibly, but the classes would still be based on Risc OS windows, and all we're really providing is a more convenient way of using resources. Icon name constants etc would still be needed. Hopefully, Acorn might be a bit more professional and provide the library sources (seeing how much they charge for Desktop C), so Glass features could be added with a minimum of fuss, as long as the code is reasonably modular, like RISC_OSlib...ahhh...oh dear...damage alert! To Dick Alstein: ~~~~~~~~~~~~~~~~ I did get your message, but my reply bounced. I'd like to see a copy of your editor; I'll send you the latest version of Glazier in return. To John Tytgat: ~~~~~~~~~~~~~~~ I gave a copy of Glazier to a member of BASS at the meet after the '92 BAU show. He said he wrote !Dissi - I thought this was you? Do you really have such a short memory, or was it not you, and BASS members just don't talk to each other? :-) He even looked like the picture of you in the info window of Dissi... Scene of the Crime ================== If anyone wants to contact me, I read comp.sys.acorn, but usually don't post to it (my local feed is read-only). I am omni-present on Arcade BBS's message areas (in the words of another user :-). Arcade is a UK ANSI board: 081-654-2212/081-655-4412, most speeds. Prefix with international code if outside UK, and probably lose the 0 from the front of 081 too, I shouldn't wonder. Failing that you might be able to get me on internet: tb@liszt.thorn-emi-crl.co.uk which probably won't work, but this might: tb%liszt.thorn-emi-crl.co.uk@ukc.ac.uk (I am indebted to Andy Mell for this information). Failing that, Snailmail: 1, Arkle House, 6, Chiltern View Road, Uxbridge, Middlesex. UB8 2PA United Kingdom. I think that's it - I await your comments - I hope they are as interesting as some very interesting things. When I've got a reasonable number of ideas, I'll collect them altogether, throw away any I didn't think of (ha ha, only kidding) and post the results. When we eventually agree on a format, I'll post the filetype+format and an example file or two. Cheers, Tim Browse PS. Note short signature. I know I provided a lot of contact points which could have gone in a signature, but they're not normally needed. What's wrong with people asking for contacts when they're needed? Hasn't anyone ever heard of providing/using resources on demand? Are there any computer scientists out there? PPS. Stop press: I just uploaded this to Arcade BBS and here's some things I've already thought of that are missing/wrong: :-( GLS_NAME chunk: No room for expansion in header. Need filenames to specify where icon constants should go. Need a global one, and one for each window. This allows for putting all icon names into one file, or for having different headers for each window. Time-stamps: may as well time-stamp all chunks just to keep it simple, and also to avoid unnecessary re-generation of template files. Round time-stamp fields up to 8 bytes so that when headers are loaded into memory, words are actually word-aligned - bit obvious this one! (blush) ...message ends...