MyChoices
=========
This module allows you to store a variety of data types into a file stored in the Risc OS choices directory. This is where programs typically store users settings.

All values can be given a name for easy reference. Names must not start with the pipe symbol '|'.

Reading a value back that does not exist will result in a default value being returned. This defaults are explained in each SWI. To check if a value exists, the SWI MyChoices_Exist is provided if you require this.

The SWIs are designed to be simple and the file format has already been designed.

There are three main types of reading and writing values:

Type 1: Integers and Strings
----------------------------
 Reading and writing integers and strings are interchangeable.
 You can set an integer and read it back as a string.
 You can set a string and read it back as an integer.

Type 2: Floating Point Values
-----------------------------
 Floating point values can be set using several different formats.
 Reading a floating point value back in a different type will convert the type.
 Note that if a value cannot be represented at all, an error will be returned.
 If a value can be read, precision may be lost if reading at a lower accuracy.
 Types currently supported:
  FPA / FPA : Single (32-bit) and Double (64-bit)
  VFP       : Single (32-bit) and Double (64-bit)
  BBC format: Standard (40-bit)

Type 3: Memory
--------------
 A block of memory.
 Note that pointers should not be saved with memory blocks.
 Offset values can be saved.

SWIs
====
MyChoices_Open = &05AB80
MyChoices_Close = &05AB81
MyChoices_SetInt = &05AB82
MyChoices_SetString = &05AB83
MyChoices_GetInt = &05AB84
MyChoices_GetString = &05AB85
MyChoices_Exist = &05AB86
MyChoices_Delete = &05AB87
MyChoices_Print = &05AB88
MyChoices_Safe = &05AB89
MyChoices_SetF32 = &05AB8A
MyChoices_SetV32 = &05AB8B
MyChoices_SetF64 = &05AB8C
MyChoices_SetV64 = &05AB8D
MyChoices_SetBBC = &05AB8E
MyChoices_GetF32 = &05AB8F
MyChoices_GetV32 = &05AB90
MyChoices_GetF64 = &05AB91
MyChoices_GetV64 = &05AB92
MyChoices_GetBBC = &05AB93
MyChoices_GetMem = &05AB94
MyChoices_SetMem = &05AB95
MyChoices_EstimatedSize = &05AB96
MyChoices_Enumerate = &05AB97

SWI Details
===========
MyChoices_Open = &05AB80
 Open a file
 Entry R0: Application name
       R1: Filename (just the leafname eg "settings" or "choices")
 Exit  R0: MyChoices handle

MyChoices_Close = &05AB81
 Close a file
 Entry R0: MyChoices handle



MyChoices_SetInt = &05AB82
 Save an integer value
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Value

MyChoices_GetInt = &05AB84
 Gets an integer value from a file or a default if it does not exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Default value
 Exit  R2: Updated value if exists



MyChoices_SetString = &05AB83
 Save an integer value
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: String pointer to save

MyChoices_GetString = &05AB85
 Gets an integer value from a file or a default if it does not exist
 Note that you must copy the string before calling another MyChoices SWI if
  you wish to keep the result
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Default value string pointer
 Exit  R2: Updated pointer to string value



MyChoices_SetF32 = &05AB8A
 Save a floating point value (FPA 32-bit or FPE 32-bit)
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to save

MyChoices_SetV32 = &05AB8B
 Save a floating point value (VFP 32-bit)
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to save

MyChoices_SetF64 = &05AB8C
 Save a floating point value (FPA 64-bit or FPE 64-bit)
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to save

MyChoices_SetV64 = &05AB8D
 Save a floating point value (VFP 64-bit)
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to save

MyChoices_SetBBC = &05AB8E
 Save a floating point value (BBC BASIC standard 40-bit)
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to save

MyChoices_GetF32 = &05AB8F
 Load a floating point value (FPA 32-bit or FPE 32-bit) or zero if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to load

MyChoices_GetV32 = &05AB90
 Load a floating point value (VFP 32-bit) or zero if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to load

MyChoices_GetF64 = &05AB91
 Load a floating point value (FPA 64-bit or FPE 32-bit) or zero if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to load

MyChoices_GetV64 = &05AB92
 Load a floating point value (VFP 64-bit) or zero if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to load

MyChoices_GetBBC = &05AB93
 Load a floating point value (BBC BASIC standard 40-bit), zero if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory containing the value to load



MyChoices_SetMem = &05AB95
 Save a block of memory
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory start
       R3: Length of memory to save

MyChoices_GetMem = &05AB94
 Load a block of memory. Block will be all zeros if doesn't exist
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
       R2: Pointer to memory start
       R3: Length of memory to load



MyChoices_Exist = &05AB86
 Check if a variable exists
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
 Exit  R2: Zero or one. One if the variable exists, zero if does not

MyChoices_EstimatedSize = &05AB96
 Get memory size this variable will fit into
 Note that currently integers always return 4
 Strings are the length of the string+1
 Memory blocks give the exact size, floating points always return 8
 These values could change in future releases
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)
 Exit  R2: Memory size required to load the value back in



MyChoices_Delete = &05AB87
 Deletes a variable from the Choices file
 Entry R0: MyChoices handle
       R1: Variable name pointer (choose your own name)



MyChoices_Enumerate = &05AB97
 Returns all variables in the file except those that start with an asterisk
 Entry R0: MyChoices handle
       R1: Zero for first call or returned R1 from previous call
 Exit  R0: MyChoices handle, preserved
       R1: Value for next call or -1 if completed
       R2: Variable name pointer (you must copy this before the next call*)
       R3: Variable type number #
Note that:
*Most high level languages such as BASIC and Python will do this for you
 Lower level languages such as C/C++ and assembler will not copy automatically
#Types:
 1 = Integer
 2 = String
 3 = Memory
 4 = Floating point value (type not specified, read converts to correct type)
It is best not to set values during an enumerate loop. Reading and deleting
will function as expected



MyChoices_Print = &05AB88
 Prints details of open files

MyChoices_Safe = &05AB89
 Physically closes the file. The MyChoices handle remains active and MyChoices
 will reopen the file if you access it again using any SWI
 Can be used before a Wimp_Poll loop to ensure the user does not see an open
 file.


Technical Details
=================
MyChoices may open and close the file when it sees fit and may not keep the file open at all times. Using programs to see if the file is open may provide information that may not reflect the status of MyChoices. Use MyChoices_Print to see details of files that MyChoices may open at any time.

There are virtually no limits to how many files MyChoies can have 'open' at the same time.

Although you can keep a file open during Wimp_Poll loops, it is recommended that you use MyChoices_Close and reopen when required. This is due to other programs which may load in a newer version of MyChoices which will lose your handle in the current version.