Modifying resources in EmuTOS ============================= There are two built-in resource files in EmuTOS: the desktop and the AES/GEM. There is also a set of mouse cursor shapes used by the AES, and a set of icons used by the desktop, both of which are treated as partial resource files. All of these are now maintained in resource files rather than C source code: AES/GEM uses gem.rsc/gem.def and mform.rsc/mform.def, and the desktop uses desktop.rsc/desktop.def and icon.rsc/icon.def. Changes are made "offline" with a standard resource editor, and the changed file(s) replace the existing ones. The make process uses special-purpose resource decompilers erd, grd, ird, and mrd (see below) to convert the .rsc/.def files into C source code which is then compiled into the EmuTOS image(s). All the resource decompilers are built from the same source code, with some compile-time and run-time differences. Conditional inclusion of resource items --------------------------------------- The source code generated by the resource decompilers does not support conditional compilation depending on the configuration options. This means that all items in the resource file are included in the generated C code, even if they are not required due to configuration options. In order to reduce memory usage, a separate program (draft) performs a preprocessing step and excludes items that are not required for the current set of configuration options. The decompiler processes the output of draft rather than the full resource. This extra step is currently only required for the desktop resource. *IMPORTANT* If you add a tree (dialog), alert, free string, or menu item to the desktop resource, and the new item is dependent on a configuration option, you should update the exclude_items[] array in tools/draft.c so that draft can exclude the new item where appropriate. Object alignment in EmuTOS ========================== Translations typically have a length different from the original English text. In order to keep dialogs looking tidy in all languages, it is often useful to centre- or right-align text objects. The AES does not provide an easy way of doing this (alignment in TEDINFO objects affects the text within the object, as well as object positioning). To allow centre- or right-alignment alignment of text objects, we steal unused bits in ob_flags to indicate the required alignment. The following bits are used: 0x8000 centre-aligned 0x4000 right-aligned If both bits are set, centre alignment takes precedence. Note that this does not require any changes to the AES, because this extra function is performed outside the AES, and only for the internal desktop resource. Also note that this aligns the *object*, not the text within the object. It is perfectly reasonable (and common) to have left-aligned text within a right-aligned TEDINFO object. *IMPORTANT* At the lowest level, the AES attempts to align text on screen byte boundaries (see function gr_just()in gemgraf.c). In doing this, it takes into account text justification as specified in the TEDINFO 'te_just' variable, but it does not know that we have pre-aligned objects as described above. This can cause the horizontal position of a pre-aligned string to be adjusted differently from that of a normal string and, if the two types of string appear next to each other, they may not be aligned with each other even though they should be. There is no simple general fix for this without modifying the AES, which is not desirable for compatibility reasons. The problem is most likely to show up with a dialog box that is not an even number of bytes wide: when centered, it will start on a half-byte screen boundary, and typically so will all contained strings (before any AES adjustment). Normally, you can avoid this issue by ensuring that any dialog box containing pre-aligned objects is an even number of bytes wide. If this does not help, increasing or decreasing the length of affected pre-aligned strings by 1 byte should fix the problem. An example of how to use the object alignment bits ================================================== Suppose you have two or more objects (in the same box) that contain a common feature (e.g. a colon). You want to align that feature (i.e. you want to make it appear at the same x-offset within the box), but the text string that appears in front of that feature varies in length for different languages. First, mark each object as right-aligned. Then, for each object, let: s = starting x offset w = width (assumed to be large enough for all languages) t = text length f = offset from start of text to alignment feature The feature should be aligned in all languages if the value of (s+w-t+f) is the same for all the objects. Tips on using a resource editor with the current EmuTOS resources ================================================================= 1. Atari TOS and most resource editors support a maximum of 30 or 31 characters per line in an alert; however, EmuTOS supports up to 40 characters/line. If you need to edit an alert with lines longer than the standard, you may need to make your resource editor treat the alert as a string to avoid mangling due to line truncation. 2. Some resource editors (such as Interface) have an option to optimize spaces in menu items. You may need to disable this to avoid the "Sort by" menu items from being altered. erd/grd/ird/mrd: the EmuTOS Resource Decompilers ================================================ These programs are compiled from the same source code; grd is generated iff the preprocessor symbol GEM_RSC is defined, ird iff the symbol ICON_RSC is defined, and mrd iff the symbol MFORM_RSC is defined. They decompile the various resource files into .c and .h files, which are input to the EmuTOS make process. The programs are similar to a general-purpose resource decompiler, but have a number of EmuTOS-specific additions/changes, as well as a number of deliberate omissions. EmuTOS-specific features ------------------------ 1. For compatibility with EmuTOS multi-language support, text strings (defined as strings containing any character other than a space, a digit or punctuation) are normally output to the .c file enclosed in the N_() macro. This allows the EmuTOS multi-language support to identify this as a string to be translated. This action may cause some strings to be unnecessarily marked as to-be-translated; therefore, before enclosing a string with N_(), the program references a "no translate" array containing strings that should _not_ be so enclosed. 2. The following features reduce ROM memory requirements (not all are applicable to all decompilers): (a) duplicate image data is automatically eliminated; multiple BITBLKs may point to the same image data. (b) duplicate icon data is automatically eliminated; multiple ICONBLKs may point to the same mask/data arrays. (c) strings in objects are trimmed of trailing spaces. (d) duplicate strings (strings that occur in more than one object, such as "OK") may be eliminated by including such strings in a "shared string" array; when this is done, the program will assign them to individual variables which are then pointed to by more than one object. (e) the te_ptext pointer in TEDINFOs is always set to NULL; this field is initialised properly by the resource fixup code elsewhere in EmuTOS. (f) the TEDINFO validation string, pointed to by te_pvalid, is optimized by removing duplicate characters from the end of the string. (g) text objects that consist of all dashes are assumed to be menu separator lines and are truncated to a single dash (they will be set up correctly during EmuDesk resource initialisation). 3. For both erd and grd, all arrays of resource information are globally visible, and the normal resource fixup is performed by code within other parts of EmuTOS. The resource initialisation routine only copies the OBJECT and TEDINFO arrays from initialised variables (which will be located in ROM) to globally-visible arrays, located in RAM. This allows modification of OBJECTs and TEDINFOs. 4. The mouse-form resource decompiler (mrd) decompiles the pseudo-BITBLKs use to store mouse cursors directly into MFORM data. The BITBLKs themselves are not generated. Program omissions ----------------- The programs do not handle CICONBLKs or USERDEFs, since they are not currently found in the resource. If they are added to the resource later, it should be easy to add the appropriate code to the decompiler. Program usage ------------- The programs are invoked from the shell/commandline by: [-d] [-p] [-v] where: is erd, grd, ird, or mrd -d requests debugging output -p specifies the prefix to apply to the names of all globally-visible generated data items -v requests verbose output (start & end messages) identifies the input RSC/definition files identifies the output .c/.h files Notes: 1. Filenames for input and output files File extensions should be omitted for and . The files used for input are .rsc and where is the definition file corresponding to the resource file. Existing resource construction programs generate definition files in one of 3 different formats, with differing extensions: .HRD most recent, supports mixed case names up to 16 bytes .DEF/.RSD original, upper case names up to 8 bytes .DFN slightly simplified version of .DEF/.RSD, with flag values in a different sequence The decompilers attempt to open the files in the above order, stopping when one is opened successfully. 2. The prefix The -p option specifies a prefix to be applied to the names of all the arrays in the .c file. If no prefix is supplied, but the input definition file is an HRD file, and it contains prefix information, that prefix will be used. In either case, an underscore will be inserted between the prefix and the array name. For example, a prefix of "my" will prefix each of the array names in the .c file with "my_". NOTE: for the current EmuTOS source, you should use the following: erd -pdesk grd (no prefix) ird -picon mrd -pmform