Copyright (c) Hyperion Entertainment and contributors.
Difference between revisions of "Preferences"
Steven Solie (talk | contribs) |
Steven Solie (talk | contribs) |
||
(31 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
+ | {{WIP}} |
||
== Preferences == |
== Preferences == |
||
− | To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and associated data files known collectively as Preferences. Preferences allows the user to set system-wide configuration options such as the printer driver to use, serial port baud rate and other items. To make an application appealing to the user, the system-wide Preferences settings should be respected as much as possible by applications. This |
+ | To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and associated data files known collectively as Preferences. Preferences allows the user to set system-wide configuration options such as the printer driver to use, serial port baud rate and other items. To make an application appealing to the user, the system-wide Preferences settings should be respected as much as possible by applications. This article describes how to use the Preferences system in your programs. |
− | |||
− | In Release 2 the number of Preference items and the way they are handled is very different from 1.3 and earlier versions, though there is backward compatibility with old Preferences items. This chapter describes both the old 1.3 and the new Release 2 Preferences. |
||
− | |||
− | == Preferences in 1.3 and Older Versions of the OS == |
||
− | |||
− | In 1.3, the Preferences program allows the user to see and change many system wide parameters, like the Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can be used temporarily (until a reset occurs) or stored permanently in the ‚Äúdevs:system-configuration‚Äù file. Under 1.3, all Preferences items are stored in this file which the system reads at boot time to find out how to set various system-wide options. |
||
− | |||
− | The 1.3 Preferences system allows the user to change the following items: |
||
− | |||
− | * Date and time of day. These are automatically saved in the battery-backed clock, if one is present. |
||
− | * Key repeat speed - the speed at which a key repeats when held down. |
||
− | * Key repeat delay - the amount of delay before a key begins repeating. |
||
− | * Mouse speed - how fast the pointer moves when the user moves the mouse. |
||
− | * Double-click delay - maximum time allowed between the two clicks of a mouse double click. For information about how to test for double-click timeout, see the description of the DoubleClick() function in the ''Amiga ROM Kernel Reference Manual: Includes and Autodocs''. |
||
− | * Text size - size of the default font characters. The user can choose 64-column mode (64 characters on a line in high-resolution and 32 characters in low-resolution mode) or 80 column mode (80 characters on a line in high-resolution and 40 characters in low-resolution mode). The first variable in the Preferences structure is FontHeight, which is the height of the characters in display lines. If this is equal to the constant TOPAZ_EIGHTY, the user has chosen the 80-column mode. If it is equal to TOPAZ_SIXTY, the user has chosen the 64-column mode. Note that certain utility programs allow the user to change the default font under 1.3, so you cannot rely on the default font being Topaz 8 or 9. |
||
− | * Display centering - allows the user to center the image on the video display. |
||
− | * Serial port - the user can change the baud rate and other serial port parameters to accommodate whatever device is attached to the serial connector. Normally you use these values as defaults when you open the serial device. If you change the baud rate or other serial port options locally, it is good practice to reset them to the values specified in Preferences before quitting. |
||
− | * Workbench colors - the user can change any of the four colors in the 1.3 Workbench screen by adjusting the amounts of red, green and blue in each color. |
||
− | * Printer - the user can select from a number of printers supported by the Amiga and also indicate whether the printer is connected to the serial connector or the parallel connector. |
||
− | * Print characteristics - the user can select paper size, right and left margin, continuous feed or single sheets, draft or letter quality, pitch and line spacing. For graphic printing, the user can specify the density, scaling method, select a vertical or horizontal dump, etc. |
||
− | |||
− | === Reading 1.3 Preferences === |
||
− | |||
− | Applications can obtain a copy of Preferences by calling the Intuition function GetPrefs(). In a system in which there is no ‚Äúdevs:system-configuration‚Äù file, GetDefPrefs() can be used to obtain the Intuition default Preference settings. |
||
− | |||
− | |||
− | |||
− | <pre>struct Preferences *GetPrefs(struct Preferences *preferences, LONG size); |
||
− | struct Preferences *GetDefPrefs(struct Preferences *preferences, LONG size);</pre> |
||
− | GetPrefs() |
||
− | |||
− | and GetDefPrefs() have two arguments, a pointer to a buffer to receive the copy of the user Preferences and the size of this buffer. The most commonly used data is grouped near the beginning of the Preferences structure and you are free to read only as much as you need. So, if you are only interested in the first part of the Preferences structure, you do not need to allocate a buffer large enough to hold the entire structure. These functions return a pointer to your buffer if successfull, NULL otherwise. |
||
− | |||
− | |||
− | |||
− | If you are using Intuition IDCMP for input, you can set the IDCMP flag IDCMP_NEWPREFS (formerly the NEWPREFS flag under V34 and earlier versions of the OS). With this flag set, your program will receive an IntuiMessage informing you changes have been made to Preferences. To get the latest settings, you would again call GetPrefs(). |
||
− | |||
− | === Preferences Structure in 1.3 === |
||
− | |||
− | The Preferences structure in 1.3 and earlier versions of the OS is a static 232 byte data structure defined in <intuition/preferences.h> as follows: |
||
− | |||
− | |||
− | |||
− | <pre>struct Preferences |
||
− | { |
||
− | /* the default font height */ |
||
− | BYTE FontHeight; /* height for system default font */ |
||
− | |||
− | /* constant describing what's hooked up to the port */ |
||
− | UBYTE PrinterPort; /* printer port connection */ |
||
− | |||
− | /* the baud rate of the port */ |
||
− | UWORD BaudRate; /* baud rate for the serial port */ |
||
− | |||
− | /* various timing rates */ |
||
− | struct timeval KeyRptSpeed; /* repeat speed for keyboard */ |
||
− | struct timeval KeyRptDelay; /* Delay before keys repeat */ |
||
− | struct timeval DoubleClick; /* Interval allowed between clicks */ |
||
− | |||
− | /* Intuition Pointer data */ |
||
− | UWORD PointerMatrix[POINTERSIZE]; /* Definition of pointer sprite */ |
||
− | BYTE XOffset; /* X-Offset for active 'bit' */ |
||
− | BYTE YOffset; /* Y-Offset for active 'bit' */ |
||
− | UWORD color17; /***********************************/ |
||
− | UWORD color18; /* Colours for sprite pointer */ |
||
− | UWORD color19; /***********************************/ |
||
− | UWORD PointerTicks; /* Sensitivity of the pointer */ |
||
− | |||
− | /* Workbench Screen colors */ |
||
− | UWORD color0; /***********************************/ |
||
− | UWORD color1; /* Standard default colours */ |
||
− | UWORD color2; /* Used in the Workbench */ |
||
− | UWORD color3; /***********************************/ |
||
− | |||
− | /* positioning data for the Intuition View */ |
||
− | BYTE ViewXOffset; /* Offset for top lefthand corner */ |
||
− | BYTE ViewYOffset; /* X and Y dimensions */ |
||
− | WORD ViewInitX, ViewInitY; /* View initial offset values */ |
||
− | |||
− | BOOL EnableCLI; /* CLI availability switch (OBSOLETE)*/ |
||
− | |||
− | /* printer configurations */ |
||
− | UWORD PrinterType; /* printer type */ |
||
− | UBYTE PrinterFilename[FILENAME_SIZE]; /* file for printer */ |
||
− | |||
− | /* print format and quality configurations */ |
||
− | UWORD PrintPitch; /* print pitch */ |
||
− | UWORD PrintQuality; /* print quality */ |
||
− | UWORD PrintSpacing; /* number of lines per inch */ |
||
− | UWORD PrintLeftMargin; /* left margin in characters */ |
||
− | UWORD PrintRightMargin; /* right margin in characters */ |
||
− | UWORD PrintImage; /* positive or negative */ |
||
− | UWORD PrintAspect; /* horizontal or vertical */ |
||
− | UWORD PrintShade; /* b&w, half-tone, or color */ |
||
− | WORD PrintThreshold; /* darkness ctrl for b/w dumps */ |
||
− | |||
− | /* print paper descriptors */ |
||
− | UWORD PaperSize; /* paper size */ |
||
− | UWORD PaperLength; /* paper length in number of lines */ |
||
− | UWORD PaperType; /* continuous or single sheet */ |
||
− | |||
− | /* Serial device settings: These are six nibble-fields in three bytes */ |
||
− | /* (these look a little strange so the defaults will map out to zero) */ |
||
− | UBYTE SerRWBits; /* upper nibble = (8-number of read bits) */ |
||
− | /* lower nibble = (8-number of write bits) */ |
||
− | UBYTE SerStopBuf; /* upper nibble = (number of stop bits - 1) */ |
||
− | /* lower nibble = (table value for BufSize) */ |
||
− | UBYTE SerParShk; /* upper nibble = (value for Parity setting) */ |
||
− | /* lower nibble = (value for Handshake mode) */ |
||
− | UBYTE LaceWB; /* if workbench is to be interlaced */ |
||
− | |||
− | UBYTE WorkName[FILENAME_SIZE]; /* temp file for printer */ |
||
− | |||
− | BYTE RowSizeChange; /* affect NormalDisplayRows/Columns */ |
||
− | BYTE ColumnSizeChange; |
||
− | |||
− | UWORD PrintFlags; /* user preference flags */ |
||
− | UWORD PrintMaxWidth; /* max width of printed picture in 10ths/in */ |
||
− | UWORD PrintMaxHeight; /* max height of printed picture in 10ths/in */ |
||
− | UBYTE PrintDensity; /* print density */ |
||
− | UBYTE PrintXOffset; /* offset of printed picture in 10ths/inch */ |
||
− | |||
− | UWORD wb_Width; /* override default workbench width */ |
||
− | UWORD wb_Height; /* override default workbench height */ |
||
− | UBYTE wb_Depth; /* override default workbench depth */ |
||
− | |||
− | UBYTE ext_size; /* extension information -- do not touch! */ |
||
− | /* extension size in blocks of 64 bytes */ |
||
− | };</pre> |
||
− | === Setting 1.3 Preferences === |
||
− | |||
− | The instance of the Preferences structure in memory can be changed with the Intuition SetPrefs() function: |
||
− | |||
− | |||
− | |||
− | <pre>struct Preferences *SetPrefs( struct Preferences *preferences, |
||
− | LONG size, BOOL inform );</pre> |
||
− | In addition to a buffer, holding the Preferences structure, and the buffer size, this function takes an argument which indicates whether an IDCMP_NEWPREFS message should be broadcast to windows which have this flag set in the Window.IDCMPFlags field of their window. |
||
− | |||
− | <sub>b</sub>oxAvoid Using SetPrefs().This function is normally only used by Preferences-like utilities. There should be no need for a normal application to set the system Preferences with SetPrefs(). |
||
− | |||
− | === Preferences and the Printer Device === |
||
− | |||
− | |||
− | |||
− | When opened, the printer device makes a local copy of the Preferences structure which is placed in the PrinterData.pd_Preferences field. If the user changes printer settings after the device is opened, the local copy won‚Äôt match the new settings. To get the latest copy of the Preferences structure, either close and re-open the printer device or call GetPrefs() and copy the fields to PrinterData.pd_Preferences before printing. Or provide printer controls in your application changing the local copy of the Preferences structure as needed. |
||
− | |||
− | == Preferences in Release 2 == |
||
− | |||
− | Under Release 2 (V36), the way Preferences are handled is significantly different. No longer is there one Preferences program with one configuration file. Instead there can be any number of Preferences editors (there are currently 13), each with its own separate configuration file covering a specific area. All these Preferences editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding new Preferences items (and editors) in future versions of the OS. |
||
− | |||
− | === Preferences Editors and Storage === |
||
+ | == Preferences Editors and Storage == |
||
+ | In AmigaOS there can be any number of Preferences editors each with its own separate configuration file covering a specific area. All these Preferences editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding new Preferences items (and editors) in future versions of the OS. |
||
− | + | Preferences are store in various ".prefs" files located in the "ENV:sys" and "ENVARC:sys" directories. Preferences options currently in use are located in "ENV:sys". Permanent, saved copies of Preferences files are stored in "ENVARC:sys". These are copied to "ENV:" on an as-needed basis. Applications may also store their own preference files in "ENV:" but should use a sub-directory for that purpose. |
|
Currently the following Preferences editors and files are available: |
Currently the following Preferences editors and files are available: |
||
+ | {| class="wikitable" |
||
− | [h] Preferences Editors in Release 2 |
||
+ | |+ Preferences Editors |
||
− | |||
+ | ! Preferences Editor |
||
− | <table> |
||
+ | ! Preferences Configuration File |
||
− | <tbody> |
||
+ | |- |
||
− | <tr class="odd"> |
||
+ | | IControl |
||
− | <td align="left">'''Preferences Editor'''</td> |
||
+ | | icontrol.prefs |
||
− | <td align="left">'''Preferences Configuration File'''</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | Input |
||
− | <tr class="even"> |
||
+ | | input.prefs |
||
− | <td align="left">IControl</td> |
||
+ | |- |
||
− | <td align="left">icontrol.prefs</td> |
||
+ | | Palette |
||
− | </tr> |
||
+ | | palette.ilbm |
||
− | <tr class="odd"> |
||
+ | |- |
||
− | <td align="left">Input</td> |
||
+ | | Pointer |
||
− | <td align="left">input.prefs</td> |
||
+ | | pointer.ilbm |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="even"> |
||
+ | | Printer |
||
− | <td align="left">Palette</td> |
||
+ | | printer.prefs |
||
− | <td align="left">palette.ilbm</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | PrinterGfx |
||
− | <tr class="odd"> |
||
+ | | printergfx.prefs |
||
− | <td align="left">Pointer</td> |
||
+ | |- |
||
− | <td align="left">pointer.ilbm</td> |
||
+ | | Overscan |
||
− | </tr> |
||
+ | | overscan.prefs |
||
− | <tr class="even"> |
||
+ | |- |
||
− | <td align="left">Printer</td> |
||
+ | | ScreenMode |
||
− | <td align="left">printer.prefs</td> |
||
+ | | screenmode.prefs |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="odd"> |
||
+ | | Serial |
||
− | <td align="left">PrinterGfx</td> |
||
+ | | serial.prefs |
||
− | <td align="left">printergfx.prefs</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | - |
||
− | <tr class="even"> |
||
+ | | wbconfig.prefs |
||
− | <td align="left">Overscan</td> |
||
+ | |- |
||
− | <td align="left">overscan.prefs</td> |
||
+ | | Font |
||
− | </tr> |
||
+ | | wbfont.prefs, sysfont.prefs and screenfont.prefs |
||
− | <tr class="odd"> |
||
+ | |- |
||
− | <td align="left">ScreenMode</td> |
||
+ | | Time |
||
− | <td align="left">screenmode.prefs</td> |
||
+ | | - |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="even"> |
||
+ | | WBPattern |
||
− | <td align="left">Serial</td> |
||
+ | | wb.pat and win.pat |
||
− | <td align="left">serial.prefs</td> |
||
+ | |} |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">‚Äì</td> |
||
− | <td align="left">wbconfig.prefs</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">Font</td> |
||
− | <td align="left">wbfont.prefs, sysfont.prefs and screenfont.prefs</td> |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">Time</td> |
||
− | <td align="left">‚Äì</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">WBPattern</td> |
||
− | <td align="left">wb.pat and win.pat</td> |
||
− | </tr> |
||
− | </tbody> |
||
− | </table> |
||
Each .prefs file is managed by editor with the same name, except for wbconfig.prefs, which is written directly by Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes directly to the battery backed clock. |
Each .prefs file is managed by editor with the same name, except for wbconfig.prefs, which is written directly by Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes directly to the battery backed clock. |
||
+ | When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either "ENV:sys" or ''both'' "ENV:sys" and "ENVARC:sys" depending on whether the user saves the changes with the "Use" gadget or "Save" gadget of the Preferences editor. |
||
+ | The "Use" gadget is for making temporary changes and the new preferences will be stored only in "ENV:sys". If the user reboots, the old preferences will be restored from the permanent copy in "ENVARC:sys". |
||
+ | The "Save" gadget is for making permanent changes and the new preferences will be stored in both "ENV:sys" and "ENVARC:sys". That way, if the user reboots, the new preferences will still be in effect since the system looks in "ENVARC:sys" to find out what preferences should be set to at boot time. |
||
− | When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either ‚ÄúENV:sys‚Äù or ''both'' ‚ÄúENV:sys‚Äù and ‚ÄúENVARC:sys‚Äù depending on whether the user saves the changes with the ‚ÄúUse‚Äù gadget or ‚ÄúSave‚Äù gadget of the Preferences editor. |
||
+ | === The ENV: Directory and Notification === |
||
− | The ‚ÄúUse‚Äù gadget is for making temporary changes and the new preferences will be stored only in ‚ÄúENV:sys‚Äù. If the user reboots, the old preferences will be restored from the permanent copy in ‚ÄúENVARC:sys‚Äù. |
||
+ | One advantage of the new Preferences system is file notification. File notification is a form of inter-process communication that allows an application to be automatically notified if a change is made to a specific file or directory. This makes it easy for the application to react to changes the user makes to Preferences files. See [[Notification]] for more complete information about the notification feature. |
||
− | The ‚ÄúSave‚Äù gadget is for making permanent changes and the new preferences will be stored in both ‚ÄúENV:sys‚Äù and ‚ÄúENVARC:sys‚Äù. That way, if the user reboots, the new preferences will still be in effect since the system looks in ‚ÄúENVARC:sys‚Äù to find out what preferences should be set to at boot time. |
||
+ | File notification is also used by the system itself. The Preferences control program, IPrefs, sets up notification on most of the Preferences files in "ENV:sys". If the user alters a Preferences item (normally this is done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the user's environment to reflect the change. |
||
− | === The ‚ÄúENV:‚Äù Directory and Notification === |
||
+ | For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to high-resolution, the new settings are saved in "screenmode.prefs" in the "ENV:sys" directory. IPrefs sets up notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the Screenmode.prefs file and reset the Workbench screen to high resolution mode. |
||
+ | Here's a short example showing how to set up notification on the "serial.prefs" file in "ENV:sys". The program displays a message in a window whenever this file is changed (e.g., when the user selects the "Use" or "Save" gadget in the Serial Preferences editor). |
||
+ | <syntaxhighlight> |
||
− | One advantage of the new Preferences system in Release 2 is file notification. File notification is a form of interprocess communication available in Release 2 that allows an application to be automatically notified if a change is made to a specific file or directory. This makes it easy for the application to react to changes the user makes to Preferences files. |
||
+ | /* |
||
− | |||
− | File notification is also used by the system itself. The Release 2 Preferences control program, IPrefs, sets up notification on most of the Preferences files in ‚ÄúENV:sys‚Äù. If the user alters a Preferences item (normally this is done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the user‚Äôs environment to reflect the change. |
||
− | |||
− | For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to high-resolution, the new settings are saved in ‚Äúscreenmode.prefs‚Äù in the ‚ÄúENV:sys‚Äù directory. IPrefs sets up notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the Screenmode.prefs file and reset the Workbench screen to high resolution mode. |
||
− | |||
− | Here‚Äôs a short example showing how to set up notification on the ‚Äúserial.prefs‚Äù file in ‚ÄúENV:sys‚Äù. The program displays a message in a window whenever this file is changed (e.g., when the user selects the ‚ÄúUse‚Äù or ‚ÄúSave‚Äù gadget in the Serial Preferences editor). |
||
− | |||
− | |||
− | |||
− | <pre>;/* prefnotify.c. - Execute me to compile me with SAS/C 5.10 |
||
− | lc -cfistq -v -y -j73 prefnotify.c |
||
− | blink from LIB:c.o,prefnotify.o to prefnotify lib LIB:LC.lib LIB:amiga.lib |
||
− | quit |
||
− | |||
** prefnotify.c - notified if serial prefs change |
** prefnotify.c - notified if serial prefs change |
||
*/ |
*/ |
||
− | #include |
+ | #include <exec/types.h> |
− | #include |
+ | #include <exec/memory.h> |
− | #include |
+ | #include <dos/dos.h> |
− | #include |
+ | #include <dos/notify.h> |
− | #include |
+ | #include <proto/exec.h> |
+ | #include <proto/dos.h> |
||
+ | #define PREFSFILENAME "ENV:sys/serial.prefs" |
||
− | #include <clib/exec_protos.h> |
||
− | #include <clib/dos_protos.h> |
||
+ | int main(int argc, char **argv) |
||
− | #ifdef LATTICE |
||
+ | { |
||
− | int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */ |
||
+ | /* Allocate a NotifyRequest structure */ |
||
− | int chkabort(void) { return(0); } /* really */ |
||
+ | struct NotifyRequest *notifyrequest = IExec->AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR); |
||
− | #endif |
||
+ | if (notifyrequest != NULL) |
||
− | #define PREFSFILENAME "ENV:sys/serial.prefs" |
||
+ | { |
||
+ | /* And allocate a signalsbit */ |
||
+ | int8 signum; |
||
+ | if ((signum = IExec->AllocSignal(-1L)) != -1) |
||
+ | { |
||
+ | /* Initialize notifcation request */ |
||
+ | CONST_STRPTR filename = PREFSFILENAME; |
||
+ | notifyrequest->nr_Name = filename; |
||
+ | notifyrequest->nr_Flags = NRF_SEND_SIGNAL; |
||
+ | /* Signal this task */ |
||
+ | notifyrequest->nr_stuff.nr_Signal.nr_Task = (struct Task *) IExec->FindTask(NULL); |
||
+ | /* with this signals bit */ |
||
+ | notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signum; |
||
+ | if ((IDOS->StartNotify(notifyrequest)) == DOSTRUE) |
||
− | static UBYTE *VersTag = "\0$VER: prefnot 37.1 (09.07.91)"; |
||
+ | { |
||
+ | IDOS->Printf("Select Serial Prefs SAVE or USE to notify this program\n"); |
||
+ | IDOS->Printf("CTRL-C to exit\n\n"); |
||
+ | BOOL done = FALSE; |
||
− | extern struct Library *DOSBase; |
||
+ | /* Loop until Ctrl-C to exit */ |
||
− | |||
+ | while(!done) |
||
− | void main(int argc, char **argv) |
||
− | { |
||
− | BOOL done=FALSE; |
||
− | struct NotifyRequest *notifyrequest; |
||
− | UBYTE *filename; |
||
− | LONG signum; |
||
− | ULONG signals; |
||
− | |||
− | /* We need at least V37 for notification */ |
||
− | if (DOSBase->lib_Version >= 37) |
||
− | { |
||
− | /* Allocate a NotifyRequest structure */ |
||
− | if (notifyrequest = AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR)) |
||
− | { |
||
− | /* And allocate a signalsbit */ |
||
− | if ((signum = AllocSignal(-1L)) != -1) |
||
{ |
{ |
||
+ | uint32 signals = IExec->Wait( (1L << signum) | SIGBREAKF_CTRL_C ); |
||
− | /* Initialize notifcation request */ |
||
− | + | if (signals & (1L << signum)) |
|
+ | IDOS->Printf("Notification signal received.\n"); |
||
− | notifyrequest->nr_Name = filename; |
||
− | notifyrequest->nr_Flags = NRF_SEND_SIGNAL; |
||
− | /* Signal this task */ |
||
− | notifyrequest->nr_stuff.nr_Signal.nr_Task = (struct Task *) FindTask(NULL); |
||
− | /* with this signals bit */ |
||
− | notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signum; |
||
− | if ( |
+ | if (signals & SIGBREAKF_CTRL_C) |
{ |
{ |
||
+ | IDOS->EndNotify(notifyrequest); |
||
− | printf("Select Serial Prefs SAVE or USE to notify this program\n"); |
||
− | + | done = TRUE; |
|
− | /* Loop until Ctrl-C to exit */ |
||
− | while(!done) |
||
− | { |
||
− | signals = Wait( (1L << signum) | SIGBREAKF_CTRL_C ); |
||
− | if (signals & (1L << signum)) |
||
− | printf("Notification signal received.\n"); |
||
− | if (signals & SIGBREAKF_CTRL_C) |
||
− | { |
||
− | EndNotify(notifyrequest); |
||
− | done=TRUE; |
||
− | } |
||
− | } |
||
} |
} |
||
− | else printf("Can't start notification\n"); |
||
− | FreeSignal(signum); |
||
} |
} |
||
− | else printf("No signals available\n"); |
||
− | FreeMem(notifyrequest, sizeof(struct NotifyRequest)); |
||
} |
} |
||
+ | else IDOS->Printf("Can't start notification\n"); |
||
− | else printf("Not enough memory for NotifyRequest.\n"); |
||
+ | IExec->FreeSignal(signum); |
||
} |
} |
||
+ | else IDOS->Printf("No signals available\n"); |
||
− | else printf("Requires at least V37 dos.library\n"); |
||
− | }</pre> |
||
− | === Preference File Format in Release 2 === |
||
+ | IExec->FreeMem(notifyrequest, sizeof(struct NotifyRequest)); |
||
− | To understand the format of Preferences files, you must be familiar with IFF file standard (see the ''Amiga ROM Kernel Reference Manual: Devices'' for the complete specification). |
||
+ | } |
||
+ | else IDOS->Printf("Not enough memory for NotifyRequest.\n"); |
||
+ | |||
+ | return 0; |
||
+ | } |
||
+ | </syntaxhighlight> |
||
+ | |||
+ | === Preference File Format === |
||
+ | |||
+ | To understand the format of Preferences files, you must be familiar with IFF file standard (see [[IFF_Standard|IFF Standard]] for the complete specification). |
||
In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). Each file contains at least two Chunks, a header Chunk and a data Chunk. |
In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). Each file contains at least two Chunks, a header Chunk and a data Chunk. |
||
Line 340: | Line 153: | ||
The PRHD header chunk, contains a PrefHeader structure: |
The PRHD header chunk, contains a PrefHeader structure: |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct PrefHeader |
||
− | |||
− | <pre>struct PrefHeader |
||
{ |
{ |
||
UBYTE ph_Version; |
UBYTE ph_Version; |
||
UBYTE ph_Type; |
UBYTE ph_Type; |
||
ULONG ph_Flags; |
ULONG ph_Flags; |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
+ | |||
Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular version and contents of a PREF chunk. |
Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular version and contents of a PREF chunk. |
||
Line 354: | Line 168: | ||
The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The types of Preferences data Chunks that are currently part of the system are: |
The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The types of Preferences data Chunks that are currently part of the system are: |
||
+ | {| class="wikitable" |
||
− | |||
+ | |+ IFF Chunk Types in Preferences Data Files |
||
− | |||
+ | ! Chunk Name |
||
− | [h] IFF Chunk Types in Release 2 Preferences Data Files |
||
+ | ! Used With |
||
− | |||
+ | |- |
||
− | <table> |
||
+ | | FONT |
||
− | <tbody> |
||
+ | | Fonts, used for all font Preferences files. In future the PrefHeader may indicate what the font is used for. |
||
− | <tr class="odd"> |
||
+ | |- |
||
− | <td align="left">'''Chunk Name'''</td> |
||
+ | | ICTL |
||
− | <td align="left">'''Used With'''</td> |
||
+ | | IControl |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="even"> |
||
+ | | INPT |
||
− | <td align="left">FONT</td> |
||
+ | | Input |
||
− | <td align="left">Fonts, used for all font Preferences files. In future the</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | OSCN |
||
− | <tr class="odd"> |
||
+ | | Overscan |
||
− | <td align="left"></td> |
||
+ | |- |
||
− | <td align="left">PrefHeader may indicate what the font is used for.</td> |
||
+ | | PGFX |
||
− | </tr> |
||
+ | | PrinterGfx |
||
− | <tr class="even"> |
||
+ | |- |
||
− | <td align="left">ICTL</td> |
||
+ | | PTXT |
||
− | <td align="left">IControl</td> |
||
+ | | PrinterText |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="odd"> |
||
+ | | SCRM |
||
− | <td align="left">INPT</td> |
||
+ | | ScreenMode |
||
− | <td align="left">Input</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | SERL |
||
− | <tr class="even"> |
||
+ | | Serial |
||
− | <td align="left">OSCN</td> |
||
+ | |} |
||
− | <td align="left">Overscan</td> |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">PGFX</td> |
||
− | <td align="left">PrinterGfx</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">PTXT</td> |
||
− | <td align="left">PrinterText</td> |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">SCRM</td> |
||
− | <td align="left">ScreenMode</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">SERL</td> |
||
− | <td align="left">Serial</td> |
||
− | </tr> |
||
− | </tbody> |
||
− | </table> |
||
Each chunk contains a structure applicable to the type. |
Each chunk contains a structure applicable to the type. |
||
Line 407: | Line 202: | ||
=== FONT === |
=== FONT === |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct FontPrefs |
||
− | |||
− | <pre>struct FontPrefs |
||
{ |
{ |
||
LONG fp_Reserved[4]; |
LONG fp_Reserved[4]; |
||
Line 417: | Line 211: | ||
struct TextAttr fp_TextAttr; |
struct TextAttr fp_TextAttr; |
||
BYTE fp_Name[FONTNAMESIZE]; /* Font name */ |
BYTE fp_Name[FONTNAMESIZE]; /* Font name */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
− | === ICTL === |
||
+ | === ICTL === |
||
+ | <syntaxhighlight> |
||
− | |||
− | + | struct IControlPrefs |
|
{ |
{ |
||
LONG ic_Reserved[4]; /* System reserved */ |
LONG ic_Reserved[4]; /* System reserved */ |
||
Line 432: | Line 227: | ||
UBYTE ic_ReqTrue; /* CKey: Requester TRUE */ |
UBYTE ic_ReqTrue; /* CKey: Requester TRUE */ |
||
UBYTE ic_ReqFalse; /* CKey: Requester FALSE */ |
UBYTE ic_ReqFalse; /* CKey: Requester FALSE */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
+ | |||
The ic_Flags field can have the following values: |
The ic_Flags field can have the following values: |
||
+ | ; ICF_COERCE_COLORS |
||
− | This indicates that a displaymode with a matching number of colors has preference over a correct aspect ration when screen coerceing takes place. |
||
+ | : This indicates that a displaymode with a matching number of colors has preference over a correct aspect ration when screen coercing takes place. |
||
+ | ; ICF_COERCE_LACE |
||
− | This indicates that chosing an interlaced display mode is allowed when coercing screens. Otherwise a non-interlaced display mode will be selected. |
||
+ | : This indicates that choosing an interlaced display mode is allowed when coercing screens. Otherwise a non-interlaced display mode will be selected. |
||
+ | ; ICF_STRGAD_FILTER |
||
− | This indicates that control characters should be filtered out of string gadget user input. |
||
+ | : This indicates that control characters should be filtered out of string gadget user input. |
||
+ | ; ICF_MENUSNAP |
||
− | This indicates that an autoscroll screen should be snapped back to origin when the mouse menu-button is selected. |
||
+ | : This indicates that an auto-scroll screen should be snapped back to origin when the mouse menu-button is selected. |
||
Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not RAWKEY codes. |
Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not RAWKEY codes. |
||
Line 447: | Line 248: | ||
=== INPT === |
=== INPT === |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct InputPrefs |
||
− | |||
− | <pre>struct InputPrefs |
||
{ |
{ |
||
LONG ip_Reserved[4]; |
LONG ip_Reserved[4]; |
||
Line 457: | Line 257: | ||
struct timeval ip_KeyRptSpeed; /* Keyboard repeat speed */ |
struct timeval ip_KeyRptSpeed; /* Keyboard repeat speed */ |
||
WORD ip_MouseAccel; /* Mouse acceleration */ |
WORD ip_MouseAccel; /* Mouse acceleration */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
− | === OSCN === |
||
− | |||
+ | === OSCN === |
||
+ | <syntaxhighlight> |
||
− | <pre>struct OverscanPrefs |
||
+ | struct OverscanPrefs |
||
{ |
{ |
||
ULONG os_Reserved[4]; |
ULONG os_Reserved[4]; |
||
Line 469: | Line 270: | ||
Point os_Text; /* TEXT overscan dimension */ |
Point os_Text; /* TEXT overscan dimension */ |
||
struct Rectangle os_Standard; /* STANDARD overscan dimension */ |
struct Rectangle os_Standard; /* STANDARD overscan dimension */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
+ | |||
=== PGFX === |
=== PGFX === |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct PrinterGfxPrefs |
||
− | |||
− | <pre>struct PrinterGfxPrefs |
||
{ |
{ |
||
LONG pg_Reserved[4]; |
LONG pg_Reserved[4]; |
||
Line 490: | Line 292: | ||
UBYTE pg_PrintXOffset; /* X Offset */ |
UBYTE pg_PrintXOffset; /* X Offset */ |
||
UBYTE pg_PrintYOffset; /* Y Offset */ |
UBYTE pg_PrintYOffset; /* Y Offset */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
+ | |||
The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for checking if the supplied values are valid. |
The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for checking if the supplied values are valid. |
||
=== PTXT === |
=== PTXT === |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct PrinterTxtPrefs |
||
− | |||
− | <pre>struct PrinterTxtPrefs |
||
{ |
{ |
||
LONG pt_Reserved[4]; /* System reserved */ |
LONG pt_Reserved[4]; /* System reserved */ |
||
Line 512: | Line 315: | ||
UWORD pt_RightMargin; /* Right margin */ |
UWORD pt_RightMargin; /* Right margin */ |
||
UWORD pt_Quality; /* Draft or Letter */ |
UWORD pt_Quality; /* Draft or Letter */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
+ | |||
=== SCRM === |
=== SCRM === |
||
+ | <syntaxhighlight> |
||
− | |||
+ | struct ScreenModePrefs |
||
− | |||
− | <pre>struct ScreenModePrefs |
||
{ |
{ |
||
ULONG sm_Reserved[4]; |
ULONG sm_Reserved[4]; |
||
Line 525: | Line 329: | ||
UWORD sm_Depth; /* Screen depth */ |
UWORD sm_Depth; /* Screen depth */ |
||
UWORD sm_Control; /* BIT 0, Autoscroll yes/no */ |
UWORD sm_Control; /* BIT 0, Autoscroll yes/no */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
− | === SERL === |
||
− | |||
+ | === SERL === |
||
+ | <syntaxhighlight> |
||
− | <pre>struct SerialPrefs |
||
+ | struct SerialPrefs |
||
{ |
{ |
||
LONG sp_Reserved[4]; /* System reserved */ |
LONG sp_Reserved[4]; /* System reserved */ |
||
Line 544: | Line 349: | ||
UBYTE sp_BitsPerChar; /* I/O bits per character */ |
UBYTE sp_BitsPerChar; /* I/O bits per character */ |
||
UBYTE sp_StopBits; /* Stop bits */ |
UBYTE sp_StopBits; /* Stop bits */ |
||
− | }; |
+ | }; |
+ | </syntaxhighlight> |
||
− | === Other Preferences File Formats in Release 2 === |
||
+ | |||
+ | === Other Preferences File Formats === |
||
Not every Preferences file is stored as an IFF file of type PREF. The palette.ilbm and pointer.ilbm files contain a regular ILBM FORM to store their imagery. The win.pat and wb.pat files use a raw format with 16 bytes reserved, followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays (currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private. |
Not every Preferences file is stored as an IFF file of type PREF. The palette.ilbm and pointer.ilbm files contain a regular ILBM FORM to store their imagery. The win.pat and wb.pat files use a raw format with 16 bytes reserved, followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays (currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private. |
||
Line 553: | Line 360: | ||
The following example shows a way to read a Preferences file. |
The following example shows a way to read a Preferences file. |
||
+ | <syntaxhighlight> |
||
− | <pre>;/* showprefs.c - Execute me to compile me with SAS C 5.10 |
||
+ | /* |
||
− | LC -b0 -d0 -cfis -v -j73 showprefs.c |
||
− | Blink FROM showprefs.o TO showprefs LIBRARY LIB:Amiga.lib |
||
− | quit |
||
− | |||
** showprefs.c - parse and show some info from an IFF Preferences file |
** showprefs.c - parse and show some info from an IFF Preferences file |
||
− | ** NOTE: This example requires upcoming 2.1 prefs/ include files. |
||
** |
** |
||
− | ** IMPORTANT!! This example is not linked with startup code (eg. c.o). |
||
− | ** It uses strictly direct AmigaDOS stdio, and also demonstrates |
||
− | ** direct ReadArgs argument parsing. Therefore it is a CLI-only |
||
− | ** example. If launched from Workbench, packet errors would occur |
||
− | ** since the WbStartup message is still sitting in the process's |
||
− | ** pr_MsgPort, and the code would never be unloaded from memory. |
||
*/ |
*/ |
||
− | #include |
+ | #include <exec/types.h> |
− | #include |
+ | #include <dos/dos.h> |
− | #include |
+ | #include <libraries/dos.h> |
− | #include |
+ | #include <libraries/iffparse.h> |
− | #include |
+ | #include <prefs/prefhdr.h> |
− | #include |
+ | #include <prefs/font.h> |
− | #include |
+ | #include <prefs/icontrol.h> |
− | #include |
+ | #include <prefs/input.h> |
− | #include |
+ | #include <prefs/overscan.h> |
− | #include |
+ | #include <prefs/printergfx.h> |
− | #include |
+ | #include <prefs/printertxt.h> |
− | #include |
+ | #include <prefs/screenmode.h> |
− | #include |
+ | #include <prefs/serial.h> |
− | #include |
+ | #include <proto/exec.h> |
− | #include |
+ | #include <proto/dos.h> |
− | #include |
+ | #include <proto/iffparse.h> |
− | struct |
+ | struct IFFParseIFace *IIFF; |
− | struct Library *DOSBase; |
||
− | struct Library *IFFParseBase; |
||
− | static |
+ | static uint8 *IFFErrTxt[] = { |
− | + | "EOF", /* (end of file, not an error) */ |
|
− | + | "EOC", /* (end of context, not an error) */ |
|
− | + | "no lexical scope", |
|
− | + | "insufficient memory", |
|
− | + | "stream read error", |
|
− | + | "stream write error", |
|
− | + | "stream seek error", |
|
− | + | "file corrupt", |
|
− | + | "IFF syntax error", |
|
− | + | "not an IFF file", |
|
− | + | "required call-back hook missing", |
|
NULL, /* (return to client, never shown) */ |
NULL, /* (return to client, never shown) */ |
||
}; |
}; |
||
− | + | int main() |
|
{ |
{ |
||
struct RDArgs *readargs; |
struct RDArgs *readargs; |
||
− | + | int32 rargs[2]; |
|
struct IFFHandle *iffhandle; |
struct IFFHandle *iffhandle; |
||
struct ContextNode *cnode; |
struct ContextNode *cnode; |
||
struct StoredProperty *hdrsp; |
struct StoredProperty *hdrsp; |
||
struct StoredProperty *sp; |
struct StoredProperty *sp; |
||
− | + | uint8 *filename; |
|
− | + | int32 ifferror, error = 0, rc = RETURN_OK; |
|
+ | struct Library *IFFParseBase = IExec->OpenLibrary ("iffparse.library", 50); |
||
− | /* We must set up SysBase (we are not linked with startup code) */ |
||
− | + | IIFF = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL); |
|
+ | |||
− | |||
+ | if (IIFF != NULL) { |
||
− | /* This no-startup-code example may not be used from Workbench */ |
||
+ | if (readargs = IDOS->ReadArgs("FILE/A", rargs, NULL)) { |
||
− | if ((((struct Process *)FindTask(NULL))->pr_CLI)==NULL) |
||
− | return(RETURN_FAIL); |
||
− | |||
− | if (DOSBase = OpenLibrary("dos.library", 33)) { |
||
− | if (IFFParseBase = OpenLibrary ("iffparse.library", 36)) { |
||
− | |||
− | if (readargs = ReadArgs("FILE/A", rargs, NULL)) { |
||
/* Test later if valid */ |
/* Test later if valid */ |
||
− | filename = ( |
+ | filename = (uint8 *)rargs[0]; |
/* allocate an IFF handle */ |
/* allocate an IFF handle */ |
||
− | if (iffhandle = AllocIFF()) { |
+ | if (iffhandle = IIFF->AllocIFF()) { |
/* Open the file for reading */ |
/* Open the file for reading */ |
||
− | if (iffhandle- |
+ | if (iffhandle->iff_Stream = (int32)IDOS->Open(filename, MODE_OLDFILE)) { |
/* initialize the iff handle */ |
/* initialize the iff handle */ |
||
− | InitIFFasDOS (iffhandle); |
+ | IIFF->InitIFFasDOS (iffhandle); |
− | if ((ifferror = OpenIFF (iffhandle, IFFF_READ)) == 0) { |
+ | if ((ifferror = IIFF->OpenIFF (iffhandle, IFFF_READ)) == 0) { |
− | PropChunk(iffhandle, ID_PREF, ID_PRHD); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_PRHD); |
− | PropChunk(iffhandle, ID_PREF, ID_FONT); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_FONT); |
− | PropChunk(iffhandle, ID_PREF, ID_ICTL); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_ICTL); |
− | PropChunk(iffhandle, ID_PREF, ID_INPT); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_INPT); |
− | PropChunk(iffhandle, ID_PREF, ID_OSCN); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_OSCN); |
− | PropChunk(iffhandle, ID_PREF, ID_PGFX); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_PGFX); |
− | PropChunk(iffhandle, ID_PREF, ID_PTXT); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_PTXT); |
− | PropChunk(iffhandle, ID_PREF, ID_SCRM); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_SCRM); |
− | PropChunk(iffhandle, ID_PREF, ID_SERL); |
+ | IIFF->PropChunk(iffhandle, ID_PREF, ID_SERL); |
for (;;) { |
for (;;) { |
||
− | ifferror = ParseIFF(iffhandle, IFFPARSE_STEP); |
+ | ifferror = IIFF->ParseIFF(iffhandle, IFFPARSE_STEP); |
if (ifferror == IFFERR_EOC) |
if (ifferror == IFFERR_EOC) |
||
Line 662: | Line 451: | ||
* chunk. |
* chunk. |
||
*/ |
*/ |
||
− | if (cnode = CurrentChunk(iffhandle)) |
+ | if (cnode = IIFF->CurrentChunk(iffhandle)) |
− | if (cnode- |
+ | if (cnode->cn_ID == ID_PRHD || cnode->cn_ID == ID_FORM) |
continue; |
continue; |
||
/* Get the preferences header, stored previously */ |
/* Get the preferences header, stored previously */ |
||
− | hdrsp = FindProp(iffhandle, ID_PREF, ID_PRHD); |
+ | hdrsp = IIFF->FindProp(iffhandle, ID_PREF, ID_PRHD); |
− | if (sp = FindProp(iffhandle, ID_PREF, ID_FONT)) { |
+ | if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_FONT)) { |
− | Printf( |
+ | IDOS->Printf("FrontPen: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_FrontPen); |
− | Printf( |
+ | IDOS->Printf("BackPen: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_BackPen); |
− | Printf( |
+ | IDOS->Printf("DrawMode: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_DrawMode); |
− | Printf( |
+ | IDOS->Printf("Font: %s\n", |
− | (LONG)((struct FontPrefs *)sp- |
+ | (LONG)((struct FontPrefs *)sp->sp_Data)->fp_Name); |
− | Printf( |
+ | IDOS->Printf("ta_YSize: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_YSize); |
− | Printf( |
+ | IDOS->Printf("ta_Style: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Style); |
− | Printf( |
+ | IDOS->Printf("ta_Flags: %ld\n", |
− | ((struct FontPrefs *)sp- |
+ | ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Flags); |
} else if (sp = FindProp(iffhandle, ID_PREF, ID_ICTL)) { |
} else if (sp = FindProp(iffhandle, ID_PREF, ID_ICTL)) { |
||
− | Printf( |
+ | IDOS->Printf("TimeOut: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_TimeOut); |
− | Printf( |
+ | IDOS->Printf("MetaDrag: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_MetaDrag); |
− | Printf( |
+ | IDOS->Printf("WBtoFront: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_WBtoFront); |
− | Printf( |
+ | IDOS->Printf("FrontToBack: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_FrontToBack); |
− | Printf( |
+ | IDOS->Printf("ReqTrue: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_ReqTrue); |
− | Printf( |
+ | IDOS->Printf("ReqFalse: %ld\n", |
− | ((struct IControlPrefs *)sp- |
+ | ((struct IControlPrefs *)sp->sp_Data)->ic_ReqFalse); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_INPT)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_INPT)) { |
− | Printf( |
+ | IDOS->Printf("PointerTicks: %ld\n", |
− | ((struct InputPrefs *)sp- |
+ | ((struct InputPrefs *)sp->sp_Data)->ip_PointerTicks); |
− | Printf( |
+ | IDOS->Printf("DoubleClick/Secs: %ld\n", |
− | ((struct InputPrefs *)sp- |
+ | ((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_secs); |
− | Printf( |
+ | IDOS->Printf("DoubleClick/Micro: %ld\n", |
− | ((struct InputPrefs *)sp- |
+ | ((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_micro); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_OSCN)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_OSCN)) { |
− | Printf( |
+ | IDOS->Printf("DisplayID: 0x%lx\n", |
− | ((struct OverscanPrefs *)sp- |
+ | ((struct OverscanPrefs *)sp->sp_Data)->os_DisplayID); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_PGFX)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PGFX)) { |
− | Printf( |
+ | IDOS->Printf("Aspect: %ld\n", |
− | ((struct PrinterGfxPrefs *)sp- |
+ | ((struct PrinterGfxPrefs *)sp->sp_Data)->pg_Aspect); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_PTXT)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PTXT)) { |
− | Printf( |
+ | IDOS->Printf("Driver: %s\n", |
− | (LONG)((struct PrinterTxtPrefs *)sp- |
+ | (LONG)((struct PrinterTxtPrefs *)sp->sp_Data)->pt_Driver); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_SCRM)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SCRM)) { |
− | Printf( |
+ | IDOS->Printf("DisplayID: 0x%lx\n", |
− | ((struct ScreenModePrefs *)sp- |
+ | ((struct ScreenModePrefs *)sp->sp_Data)->sm_DisplayID); |
/* etc */ |
/* etc */ |
||
− | } else if (sp = FindProp(iffhandle, ID_PREF, ID_SERL)) { |
+ | } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SERL)) { |
− | Printf( |
+ | IDOS->Printf("BaudRate: %ld\n", |
− | ((struct SerialPrefs *)sp- |
+ | ((struct SerialPrefs *)sp->sp_Data)->sp_BaudRate); |
/* etc */ |
/* etc */ |
||
} |
} |
||
} |
} |
||
− | CloseIFF(iffhandle); |
+ | IIFF->CloseIFF(iffhandle); |
} |
} |
||
if (ifferror != IFFERR_EOF) { |
if (ifferror != IFFERR_EOF) { |
||
rargs[1] = (LONG)IFFErrTxt[-ifferror - 1]; |
rargs[1] = (LONG)IFFErrTxt[-ifferror - 1]; |
||
− | VFPrintf(Output(), |
+ | IDOS->VFPrintf(IDOS->Output(), "%s: %s\n", rargs); |
rc = RETURN_FAIL; |
rc = RETURN_FAIL; |
||
} |
} |
||
− | Close(iffhandle- |
+ | IDOS->Close(iffhandle->iff_Stream); |
} else |
} else |
||
error = IoErr(); |
error = IoErr(); |
||
− | FreeIFF(iffhandle); |
+ | IIFF->FreeIFF(iffhandle); |
} else { |
} else { |
||
− | VFPrintf(Output(), |
+ | IDOS->VFPrintf(Output(), "Can't allocate IFF handle\n", NULL); |
rc = RETURN_FAIL; |
rc = RETURN_FAIL; |
||
} |
} |
||
− | FreeArgs(readargs); |
+ | IDOS->FreeArgs(readargs); |
} else |
} else |
||
error = IoErr(); |
error = IoErr(); |
||
− | CloseLibrary(IFFParseBase); |
||
+ | IDOS->SetIoErr(error); |
||
− | |||
− | SetIoErr(error); |
||
if (error) { |
if (error) { |
||
rc = RETURN_FAIL; |
rc = RETURN_FAIL; |
||
− | PrintFault(error, filename); |
+ | IDOS->PrintFault(error, filename); |
} |
} |
||
+ | } else { |
||
+ | rc = RETURN_FAIL; |
||
+ | } |
||
+ | IExec->DropInterface((struct Interface*)IIFF); |
||
− | } else { |
||
+ | IExec->CloseLibrary(IFFParseBase); |
||
− | rc = RETURN_FAIL; |
||
− | Write(Output(), "Kickstart 2.0 required\n", 23); |
||
− | } |
||
− | CloseLibrary(DOSBase); |
||
− | } |
||
return(rc); |
return(rc); |
||
+ | } |
||
− | }</pre> |
||
+ | </syntaxhighlight> |
||
− | == Function Reference == |
||
+ | == Preferences in 1.3 and Older Versions of the OS == |
||
− | The following are brief descriptions of the system functions that relate to the use of Preferences. See the ''Amiga ROM Kernel Reference Manual: Includes and Autodocs'' for details on each function call. |
||
+ | In 1.3, the Preferences program allows the user to see and change many system wide parameters, like the Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can be used temporarily (until a reset occurs) or stored permanently in the "DEVS:system-configuration" file. Under 1.3, all Preferences items are stored in this file which the system reads at boot time to find out how to set various system-wide options. |
||
+ | <syntaxhighlight> |
||
+ | struct Preferences *GetPrefs(struct Preferences *preferences, LONG size); |
||
+ | struct Preferences *GetDefPrefs(struct Preferences *preferences, LONG size); |
||
+ | struct Preferences *SetPrefs( struct Preferences *preferences, LONG size, BOOL inform ); |
||
+ | </syntaxhighlight> |
||
+ | |||
+ | None of these functions should be used in any new programs. They are only present for backwards compatibility. |
||
+ | |||
+ | == Function Reference == |
||
+ | The following are brief descriptions of the system functions that relate to the use of Preferences. See the SDK for details on each function call. |
||
− | [h] Functions Used with Preferences |
||
+ | {| class="wikitable" |
||
− | <table> |
||
+ | ! Function |
||
− | <thead> |
||
+ | ! Description |
||
− | <tr class="header"> |
||
+ | |- |
||
− | <th align="left">'''Function'''</th> |
||
+ | | GetPrefs() |
||
− | <th align="left">'''Description'''</th> |
||
+ | | Old 1.3 (V34) function for making a copy of the Preferences structure |
||
− | </tr> |
||
+ | |- |
||
− | </thead> |
||
+ | | SetPrefs() |
||
− | <tbody> |
||
+ | | Old 1.3 (V34) function for overwriting Preferences with new data |
||
− | <tr class="odd"> |
||
+ | |- |
||
− | <td align="left">GetPrefs()</td> |
||
+ | | GetDefPrefs() |
||
− | <td align="left">Old 1.3 (V34) function for making a copy of the Preferences structure</td> |
||
+ | | Old 1.3 (V34) function for copying default Preferences from ROM |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="even"> |
||
+ | | StartNotify() |
||
− | <td align="left">SetPrefs()</td> |
||
− | + | | DOS library function for monitoring a .prefs file for changes |
|
+ | |- |
||
− | </tr> |
||
+ | | EndNotify() |
||
− | <tr class="odd"> |
||
+ | | Ends notification started with StartNotify() |
||
− | <td align="left">GetDefPrefs()</td> |
||
+ | |- |
||
− | <td align="left">Old 1.3 (V34) function for copying default Preferences from ROM</td> |
||
+ | | AllocIFF() |
||
− | </tr> |
||
+ | | IFFParse library function that creates an IFFHandle for parsing |
||
− | <tr class="even"> |
||
+ | |- |
||
− | <td align="left">StartNotify()</td> |
||
+ | | InitIFFasDOS() |
||
− | <td align="left">Release 2 DOS library function for monitoring a .prefs file for changes</td> |
||
+ | | Initialize the IFFHandle as a DOS stream |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="odd"> |
||
+ | | OpenIFF() |
||
− | <td align="left">EndNotify()</td> |
||
+ | | Initialize an IFFHandle for reading or writing a new stream |
||
− | <td align="left">Ends notification started with StartNotify()</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | PropChunk() |
||
− | <tr class="even"> |
||
+ | | Specify a property chunk to store |
||
− | <td align="left">AllocIFF()</td> |
||
+ | |- |
||
− | <td align="left">IFFParse library function that creates an IFFHandle for parsing</td> |
||
+ | | ParseIFF() |
||
− | </tr> |
||
+ | | Parse an IFF file from the IFFHandle stream |
||
− | <tr class="odd"> |
||
+ | |- |
||
− | <td align="left">InitIFFasDOS()</td> |
||
+ | | CurrentChunk() |
||
− | <td align="left">Initialize the IFFHandle as a DOS stream</td> |
||
+ | | Returns the top level context of an IFF stream |
||
− | </tr> |
||
+ | |- |
||
− | <tr class="even"> |
||
+ | | FindProp() |
||
− | <td align="left">OpenIFF()</td> |
||
+ | | Search for a property chunk previously declared with PropChunk() |
||
− | <td align="left">Initialize an IFFHandle for reading or writing a new stream</td> |
||
+ | |- |
||
− | </tr> |
||
+ | | CloseIFF() |
||
− | <tr class="odd"> |
||
+ | | Closes an IFF context opened with OpenIFF() |
||
− | <td align="left">PropChunk()</td> |
||
+ | |- |
||
− | <td align="left">Specify a property chunk to store</td> |
||
+ | | FreeIFF() |
||
− | </tr> |
||
+ | | Frees the IFFHandle created with AllocIFF() |
||
− | <tr class="even"> |
||
+ | |} |
||
− | <td align="left">ParseIFF()</td> |
||
− | <td align="left">Parse an IFF file from the IFFHandle stream</td> |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">CurrentChunk()</td> |
||
− | <td align="left">Returns the top level context of an IFF stream</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">FindProp()</td> |
||
− | <td align="left">Search for a property chunk previously declared with PropChunk()</td> |
||
− | </tr> |
||
− | <tr class="odd"> |
||
− | <td align="left">CloseIFF()</td> |
||
− | <td align="left">Closes an IFF context opened with OpenIFF()</td> |
||
− | </tr> |
||
− | <tr class="even"> |
||
− | <td align="left">FreeIFF()</td> |
||
− | <td align="left">Frees the IFFHandle created with AllocIFF()</td> |
||
− | </tr> |
||
− | </tbody> |
||
− | </table> |
Latest revision as of 20:25, 9 November 2015
This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally. |
Contents
Preferences
To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and associated data files known collectively as Preferences. Preferences allows the user to set system-wide configuration options such as the printer driver to use, serial port baud rate and other items. To make an application appealing to the user, the system-wide Preferences settings should be respected as much as possible by applications. This article describes how to use the Preferences system in your programs.
Preferences Editors and Storage
In AmigaOS there can be any number of Preferences editors each with its own separate configuration file covering a specific area. All these Preferences editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding new Preferences items (and editors) in future versions of the OS.
Preferences are store in various ".prefs" files located in the "ENV:sys" and "ENVARC:sys" directories. Preferences options currently in use are located in "ENV:sys". Permanent, saved copies of Preferences files are stored in "ENVARC:sys". These are copied to "ENV:" on an as-needed basis. Applications may also store their own preference files in "ENV:" but should use a sub-directory for that purpose.
Currently the following Preferences editors and files are available:
Preferences Editor | Preferences Configuration File |
---|---|
IControl | icontrol.prefs |
Input | input.prefs |
Palette | palette.ilbm |
Pointer | pointer.ilbm |
Printer | printer.prefs |
PrinterGfx | printergfx.prefs |
Overscan | overscan.prefs |
ScreenMode | screenmode.prefs |
Serial | serial.prefs |
- | wbconfig.prefs |
Font | wbfont.prefs, sysfont.prefs and screenfont.prefs |
Time | - |
WBPattern | wb.pat and win.pat |
Each .prefs file is managed by editor with the same name, except for wbconfig.prefs, which is written directly by Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes directly to the battery backed clock.
When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either "ENV:sys" or both "ENV:sys" and "ENVARC:sys" depending on whether the user saves the changes with the "Use" gadget or "Save" gadget of the Preferences editor.
The "Use" gadget is for making temporary changes and the new preferences will be stored only in "ENV:sys". If the user reboots, the old preferences will be restored from the permanent copy in "ENVARC:sys".
The "Save" gadget is for making permanent changes and the new preferences will be stored in both "ENV:sys" and "ENVARC:sys". That way, if the user reboots, the new preferences will still be in effect since the system looks in "ENVARC:sys" to find out what preferences should be set to at boot time.
The ENV: Directory and Notification
One advantage of the new Preferences system is file notification. File notification is a form of inter-process communication that allows an application to be automatically notified if a change is made to a specific file or directory. This makes it easy for the application to react to changes the user makes to Preferences files. See Notification for more complete information about the notification feature.
File notification is also used by the system itself. The Preferences control program, IPrefs, sets up notification on most of the Preferences files in "ENV:sys". If the user alters a Preferences item (normally this is done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the user's environment to reflect the change.
For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to high-resolution, the new settings are saved in "screenmode.prefs" in the "ENV:sys" directory. IPrefs sets up notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the Screenmode.prefs file and reset the Workbench screen to high resolution mode.
Here's a short example showing how to set up notification on the "serial.prefs" file in "ENV:sys". The program displays a message in a window whenever this file is changed (e.g., when the user selects the "Use" or "Save" gadget in the Serial Preferences editor).
/* ** prefnotify.c - notified if serial prefs change */ #include <exec/types.h> #include <exec/memory.h> #include <dos/dos.h> #include <dos/notify.h> #include <proto/exec.h> #include <proto/dos.h> #define PREFSFILENAME "ENV:sys/serial.prefs" int main(int argc, char **argv) { /* Allocate a NotifyRequest structure */ struct NotifyRequest *notifyrequest = IExec->AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR); if (notifyrequest != NULL) { /* And allocate a signalsbit */ int8 signum; if ((signum = IExec->AllocSignal(-1L)) != -1) { /* Initialize notifcation request */ CONST_STRPTR filename = PREFSFILENAME; notifyrequest->nr_Name = filename; notifyrequest->nr_Flags = NRF_SEND_SIGNAL; /* Signal this task */ notifyrequest->nr_stuff.nr_Signal.nr_Task = (struct Task *) IExec->FindTask(NULL); /* with this signals bit */ notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signum; if ((IDOS->StartNotify(notifyrequest)) == DOSTRUE) { IDOS->Printf("Select Serial Prefs SAVE or USE to notify this program\n"); IDOS->Printf("CTRL-C to exit\n\n"); BOOL done = FALSE; /* Loop until Ctrl-C to exit */ while(!done) { uint32 signals = IExec->Wait( (1L << signum) | SIGBREAKF_CTRL_C ); if (signals & (1L << signum)) IDOS->Printf("Notification signal received.\n"); if (signals & SIGBREAKF_CTRL_C) { IDOS->EndNotify(notifyrequest); done = TRUE; } } } else IDOS->Printf("Can't start notification\n"); IExec->FreeSignal(signum); } else IDOS->Printf("No signals available\n"); IExec->FreeMem(notifyrequest, sizeof(struct NotifyRequest)); } else IDOS->Printf("Not enough memory for NotifyRequest.\n"); return 0; }
Preference File Format
To understand the format of Preferences files, you must be familiar with IFF file standard (see IFF Standard for the complete specification).
In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). Each file contains at least two Chunks, a header Chunk and a data Chunk.
The Header Chunk
The PRHD header chunk, contains a PrefHeader structure:
struct PrefHeader { UBYTE ph_Version; UBYTE ph_Type; ULONG ph_Flags; };
Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular version and contents of a PREF chunk.
The Data Chunk
The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The types of Preferences data Chunks that are currently part of the system are:
Chunk Name | Used With |
---|---|
FONT | Fonts, used for all font Preferences files. In future the PrefHeader may indicate what the font is used for. |
ICTL | IControl |
INPT | Input |
OSCN | Overscan |
PGFX | PrinterGfx |
PTXT | PrinterText |
SCRM | ScreenMode |
SERL | Serial |
Each chunk contains a structure applicable to the type.
FONT
struct FontPrefs { LONG fp_Reserved[4]; UBYTE fp_FrontPen; /* Textcolor */ UBYTE fp_BackPen; /* Character background color */ UBYTE fp_DrawMode; struct TextAttr fp_TextAttr; BYTE fp_Name[FONTNAMESIZE]; /* Font name */ };
ICTL
struct IControlPrefs { LONG ic_Reserved[4]; /* System reserved */ UWORD ic_TimeOut; /* Verify timeout */ WORD ic_MetaDrag; /* Meta drag mouse event */ ULONG ic_Flags; /* IControl flags (see below) */ UBYTE ic_WBtoFront; /* CKey: WB to front */ UBYTE ic_FrontToBack; /* CKey: front screen to back */ UBYTE ic_ReqTrue; /* CKey: Requester TRUE */ UBYTE ic_ReqFalse; /* CKey: Requester FALSE */ };
The ic_Flags field can have the following values:
- ICF_COERCE_COLORS
- This indicates that a displaymode with a matching number of colors has preference over a correct aspect ration when screen coercing takes place.
- ICF_COERCE_LACE
- This indicates that choosing an interlaced display mode is allowed when coercing screens. Otherwise a non-interlaced display mode will be selected.
- ICF_STRGAD_FILTER
- This indicates that control characters should be filtered out of string gadget user input.
- ICF_MENUSNAP
- This indicates that an auto-scroll screen should be snapped back to origin when the mouse menu-button is selected.
Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not RAWKEY codes.
INPT
struct InputPrefs { LONG ip_Reserved[4]; UWORD ip_PointerTicks; /* Sensitivity of the pointer */ struct timeval ip_DoubleClick; /* Interval between clicks */ struct timeval ip_KeyRptDelay; /* keyboard repeat delay */ struct timeval ip_KeyRptSpeed; /* Keyboard repeat speed */ WORD ip_MouseAccel; /* Mouse acceleration */ };
OSCN
struct OverscanPrefs { ULONG os_Reserved[4]; ULONG os_DisplayID; /* Displaymode ID */ Point os_ViewPos; /* View X/Y Offset */ Point os_Text; /* TEXT overscan dimension */ struct Rectangle os_Standard; /* STANDARD overscan dimension */ };
PGFX
struct PrinterGfxPrefs { LONG pg_Reserved[4]; UWORD pg_Aspect; /* Horizontal or vertical */ UWORD pg_Shade; /* B&W, Greyscale, Color */ UWORD pg_Image; /* Positive or negative image */ WORD pg_Threshold; /* Black threshold */ UBYTE pg_ColorCorrect; /* RGB color correction */ UBYTE pg_Dimensions; /* Dimension type */ UBYTE pg_Dithering; /* Type of dithering */ UWORD pg_GraphicFlags; /* Rastport dump flags */ UBYTE pg_PrintDensity; /* Print density 1 - 7 */ UWORD pg_PrintMaxWidth; /* Maximum width */ UWORD pg_PrintMaxHeight; /* Maximum height */ UBYTE pg_PrintXOffset; /* X Offset */ UBYTE pg_PrintYOffset; /* Y Offset */ };
The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for checking if the supplied values are valid.
PTXT
struct PrinterTxtPrefs { LONG pt_Reserved[4]; /* System reserved */ UBYTE pt_Driver[DRIVERNAMESIZE]; /* printer driver filename */ UBYTE pt_Port; /* printer port connection */ UWORD pt_PaperType; /* Fanfold or single */ UWORD pt_PaperSize; /* Standard, Legal, A4, A3 etc. */ UWORD pt_PaperLength; /* Paper length in # of lines */ UWORD pt_Pitch; /* Pica or Elite */ UWORD pt_Spacing; /* 6 or 8 LPI */ UWORD pt_LeftMargin; /* Left margin */ UWORD pt_RightMargin; /* Right margin */ UWORD pt_Quality; /* Draft or Letter */ };
SCRM
struct ScreenModePrefs { ULONG sm_Reserved[4]; ULONG sm_DisplayID; /* Displaymode ID */ UWORD sm_Width; /* Screen width */ UWORD sm_Height; /* Screen height */ UWORD sm_Depth; /* Screen depth */ UWORD sm_Control; /* BIT 0, Autoscroll yes/no */ };
SERL
struct SerialPrefs { LONG sp_Reserved[4]; /* System reserved */ ULONG sp_BaudRate; /* Baud rate */ ULONG sp_InputBuffer; /* Input buffer: 0 - 64K */ ULONG sp_OutputBuffer; /* Future: Output: 0 - 64K, def 0 */ UBYTE sp_InputHandshake; /* Input handshaking */ UBYTE sp_OutputHandshake; /* Future: Output handshaking */ UBYTE sp_Parity; /* Parity */ UBYTE sp_BitsPerChar; /* I/O bits per character */ UBYTE sp_StopBits; /* Stop bits */ };
Other Preferences File Formats
Not every Preferences file is stored as an IFF file of type PREF. The palette.ilbm and pointer.ilbm files contain a regular ILBM FORM to store their imagery. The win.pat and wb.pat files use a raw format with 16 bytes reserved, followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays (currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private.
Reading a Preferences File
The following example shows a way to read a Preferences file.
/* ** showprefs.c - parse and show some info from an IFF Preferences file ** */ #include <exec/types.h> #include <dos/dos.h> #include <libraries/dos.h> #include <libraries/iffparse.h> #include <prefs/prefhdr.h> #include <prefs/font.h> #include <prefs/icontrol.h> #include <prefs/input.h> #include <prefs/overscan.h> #include <prefs/printergfx.h> #include <prefs/printertxt.h> #include <prefs/screenmode.h> #include <prefs/serial.h> #include <proto/exec.h> #include <proto/dos.h> #include <proto/iffparse.h> struct IFFParseIFace *IIFF; static uint8 *IFFErrTxt[] = { "EOF", /* (end of file, not an error) */ "EOC", /* (end of context, not an error) */ "no lexical scope", "insufficient memory", "stream read error", "stream write error", "stream seek error", "file corrupt", "IFF syntax error", "not an IFF file", "required call-back hook missing", NULL, /* (return to client, never shown) */ }; int main() { struct RDArgs *readargs; int32 rargs[2]; struct IFFHandle *iffhandle; struct ContextNode *cnode; struct StoredProperty *hdrsp; struct StoredProperty *sp; uint8 *filename; int32 ifferror, error = 0, rc = RETURN_OK; struct Library *IFFParseBase = IExec->OpenLibrary ("iffparse.library", 50); IIFF = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL); if (IIFF != NULL) { if (readargs = IDOS->ReadArgs("FILE/A", rargs, NULL)) { /* Test later if valid */ filename = (uint8 *)rargs[0]; /* allocate an IFF handle */ if (iffhandle = IIFF->AllocIFF()) { /* Open the file for reading */ if (iffhandle->iff_Stream = (int32)IDOS->Open(filename, MODE_OLDFILE)) { /* initialize the iff handle */ IIFF->InitIFFasDOS (iffhandle); if ((ifferror = IIFF->OpenIFF (iffhandle, IFFF_READ)) == 0) { IIFF->PropChunk(iffhandle, ID_PREF, ID_PRHD); IIFF->PropChunk(iffhandle, ID_PREF, ID_FONT); IIFF->PropChunk(iffhandle, ID_PREF, ID_ICTL); IIFF->PropChunk(iffhandle, ID_PREF, ID_INPT); IIFF->PropChunk(iffhandle, ID_PREF, ID_OSCN); IIFF->PropChunk(iffhandle, ID_PREF, ID_PGFX); IIFF->PropChunk(iffhandle, ID_PREF, ID_PTXT); IIFF->PropChunk(iffhandle, ID_PREF, ID_SCRM); IIFF->PropChunk(iffhandle, ID_PREF, ID_SERL); for (;;) { ifferror = IIFF->ParseIFF(iffhandle, IFFPARSE_STEP); if (ifferror == IFFERR_EOC) continue; else if (ifferror) break; /* Do nothing is this is a PrefHeader chunk, * we'll pop it later when there is a pref * chunk. */ if (cnode = IIFF->CurrentChunk(iffhandle)) if (cnode->cn_ID == ID_PRHD || cnode->cn_ID == ID_FORM) continue; /* Get the preferences header, stored previously */ hdrsp = IIFF->FindProp(iffhandle, ID_PREF, ID_PRHD); if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_FONT)) { IDOS->Printf("FrontPen: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_FrontPen); IDOS->Printf("BackPen: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_BackPen); IDOS->Printf("DrawMode: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_DrawMode); IDOS->Printf("Font: %s\n", (LONG)((struct FontPrefs *)sp->sp_Data)->fp_Name); IDOS->Printf("ta_YSize: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_YSize); IDOS->Printf("ta_Style: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Style); IDOS->Printf("ta_Flags: %ld\n", ((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Flags); } else if (sp = FindProp(iffhandle, ID_PREF, ID_ICTL)) { IDOS->Printf("TimeOut: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_TimeOut); IDOS->Printf("MetaDrag: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_MetaDrag); IDOS->Printf("WBtoFront: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_WBtoFront); IDOS->Printf("FrontToBack: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_FrontToBack); IDOS->Printf("ReqTrue: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_ReqTrue); IDOS->Printf("ReqFalse: %ld\n", ((struct IControlPrefs *)sp->sp_Data)->ic_ReqFalse); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_INPT)) { IDOS->Printf("PointerTicks: %ld\n", ((struct InputPrefs *)sp->sp_Data)->ip_PointerTicks); IDOS->Printf("DoubleClick/Secs: %ld\n", ((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_secs); IDOS->Printf("DoubleClick/Micro: %ld\n", ((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_micro); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_OSCN)) { IDOS->Printf("DisplayID: 0x%lx\n", ((struct OverscanPrefs *)sp->sp_Data)->os_DisplayID); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PGFX)) { IDOS->Printf("Aspect: %ld\n", ((struct PrinterGfxPrefs *)sp->sp_Data)->pg_Aspect); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PTXT)) { IDOS->Printf("Driver: %s\n", (LONG)((struct PrinterTxtPrefs *)sp->sp_Data)->pt_Driver); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SCRM)) { IDOS->Printf("DisplayID: 0x%lx\n", ((struct ScreenModePrefs *)sp->sp_Data)->sm_DisplayID); /* etc */ } else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SERL)) { IDOS->Printf("BaudRate: %ld\n", ((struct SerialPrefs *)sp->sp_Data)->sp_BaudRate); /* etc */ } } IIFF->CloseIFF(iffhandle); } if (ifferror != IFFERR_EOF) { rargs[1] = (LONG)IFFErrTxt[-ifferror - 1]; IDOS->VFPrintf(IDOS->Output(), "%s: %s\n", rargs); rc = RETURN_FAIL; } IDOS->Close(iffhandle->iff_Stream); } else error = IoErr(); IIFF->FreeIFF(iffhandle); } else { IDOS->VFPrintf(Output(), "Can't allocate IFF handle\n", NULL); rc = RETURN_FAIL; } IDOS->FreeArgs(readargs); } else error = IoErr(); IDOS->SetIoErr(error); if (error) { rc = RETURN_FAIL; IDOS->PrintFault(error, filename); } } else { rc = RETURN_FAIL; } IExec->DropInterface((struct Interface*)IIFF); IExec->CloseLibrary(IFFParseBase); return(rc); }
Preferences in 1.3 and Older Versions of the OS
In 1.3, the Preferences program allows the user to see and change many system wide parameters, like the Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can be used temporarily (until a reset occurs) or stored permanently in the "DEVS:system-configuration" file. Under 1.3, all Preferences items are stored in this file which the system reads at boot time to find out how to set various system-wide options.
struct Preferences *GetPrefs(struct Preferences *preferences, LONG size); struct Preferences *GetDefPrefs(struct Preferences *preferences, LONG size); struct Preferences *SetPrefs( struct Preferences *preferences, LONG size, BOOL inform );
None of these functions should be used in any new programs. They are only present for backwards compatibility.
Function Reference
The following are brief descriptions of the system functions that relate to the use of Preferences. See the SDK for details on each function call.
Function | Description |
---|---|
GetPrefs() | Old 1.3 (V34) function for making a copy of the Preferences structure |
SetPrefs() | Old 1.3 (V34) function for overwriting Preferences with new data |
GetDefPrefs() | Old 1.3 (V34) function for copying default Preferences from ROM |
StartNotify() | DOS library function for monitoring a .prefs file for changes |
EndNotify() | Ends notification started with StartNotify() |
AllocIFF() | IFFParse library function that creates an IFFHandle for parsing |
InitIFFasDOS() | Initialize the IFFHandle as a DOS stream |
OpenIFF() | Initialize an IFFHandle for reading or writing a new stream |
PropChunk() | Specify a property chunk to store |
ParseIFF() | Parse an IFF file from the IFFHandle stream |
CurrentChunk() | Returns the top level context of an IFF stream |
FindProp() | Search for a property chunk previously declared with PropChunk() |
CloseIFF() | Closes an IFF context opened with OpenIFF() |
FreeIFF() | Frees the IFFHandle created with AllocIFF() |