Rick's b.log - 2015/06/26
It is the 3rd of May 2024 You are 3.128.79.88, pleased to meet you!

DeskLib update proposal

My fork of DeskLib v2.30 predates the current v2.80. It was originally done because the (new mostly forgotten) DeskLib v3.20 changed many many things in a highly incompatible way (listed near the top of this page). It was at this point that I started expanding v2.30 with some of the fixes and features in v3.20.

Note, however, that the two versions of DeskLib are going in different directions. My version will ultimately concentrate on RISC OS 5.xx facilities, which attempting to run on RISC OS 3.5 or later (possibly RISC OS 3.10 too, but this is no longer a stated design goal).
What I can promise you is that my version of DeskLib will ALWAYS work with the DDE. It would appear that "the other branch" ☺ will, in the future, be GCC only and an ELF library. As ELF is not native to RISC OS, there will be dependencies.
My library? Ought to work on straight plain regular RISC OS without issue. That's the plan.

There is, obviously, likely to be a growing disparity between some of the more recent functions. I do not currently know what to do regarding this. It may be like RISC OS Select vs RISC OS 5 - you choose your preferred incarnation and stick with it. Certainly, the future pretty much dictates that if you like gcc you will use the other DeskLib, and if you like the DDE you'll either use mine or the "probably won't be updated further" pre-ELF release of DeskLib v2.80.

Thankfully, neither version is GPL so at least we don't have that headache...

Okay. Here's a list of proposed changes. Comments welcome.

• Backtrace - merge in modifications present in my server to search for the backtrace frame correctly on StrongARM processors; plus to also terminate backtracing at main() (as anything prior is within CLib).
• ColourTran - support ReadPalette, [Set|Return]FontColours, and Set[Opp]TextColour.
• CPU - [note: this is low importance] Extend CPU_ID() and CPU_Type() to understand ARMv4+. Add CPU_HALType() which will return NULL (no HAL present) or a composite word describing the hardware, or bit 31 set if a HAL but hardware not identifiable. Update CPU_Class()?
• Debug - rename as DebugOld.
• Debug (new) - more or less the same thing, but works with DADebug and is to be included in the main library.
• Env (new library for miscellaneous "environment" things): Add all of...
  OSgeneric() to return generic OS version (300 - RISC OS 3.xx; 350 - 3.50 to 3.70; 400 - RISC OS 4 *and* 6 :-P ; 500 - RISC OS 5).
  OSversion() to return exact OS version.
  WimpVersion() to return Wimp version.
  IsModule() returns TRUE if the module specified is presently loaded, else FALSE.
  IsTask() returns TRUE if the specified task is presently running, else FALSE.
  IsHAL() returns TRUE if a HAL version, else FALSE.
  PlatformType() returns NULL or a value defining the current platform type. The platform type is read from the HAL. Older versions of RISC OS will be NULL; but you can probably make some guesses based upon the OSversion.
  IsPi() returns TRUE if this is a RaspberryPi, else FALSE. [determine by processor type; as the Pi family keeps getting larger...]
  IsVFP() returns TRUE if VFP extensions are present, else FALSE.
  IsNEON() returns TRUE if NEON extensions are present, else FALSE.
  ReadUID() returns machine unique ID [usu. MAC address on later machines]
  DelayMicro() will ask the HAL to delay a specified number of MICROseconds. Has no effect on non-HAL machines.
• Error - add Error_ReportFancy() to support RISC OS 3.5 extended options.
  Standard Error_Report will call Error_ReportFancy if running on a capable machine; the default icon will be an exclamation mark and the app's icon.
  Add Error_ReportWithButtons() to provide buttons other than OK and Cancel.
  Add Error_AskQuestion() to veneer to ReportWithButtons.
• Event - remove RISC OS 2 compatibility. Event_Initialise() will perform a startup suitable for RISC OS 3.10 upwards.
  Event_InitCustom() will do the same thing but allow you to specify the desired Wimp version, such as for the nested WindowManager.
  Add Event_PollIdle() to perform the same thing as Event_Poll(), only with the idle delay.
• File - add File_ReadString() to read a [CR]LF terminated string from the file.
  File_WriteString() will call File_WriteBytes() as necessary.
  Expand File_CreateDirectory() with File_EnsurePath() which will step through the path given creating directories until the path is valid.
  File_Canonicalise() will convert a file reference to an absolute path, ie "Choices:Boot" will become something like "SDFS::RISCOSpi.$.!BOOT.Choices.boot". [actually, this will just call Filing_CanonicalisePath() ;-)]
  File_CanonicaliseAndParse() will determine the full correct path and also return a struct with a pointer to the start of the filesystem (and its length), the start of the disc name (and its length), the start of the path (and length) and the start of the filename (and length).
  [to check - File_IsDirectory() behaviour on image files with relevant FS loaded / not loaded]
• Font - ConvertToOS and ConvertToPoints to veneer to existing (mostly in lowercase for some reason).
  Add Font_PaintBlended() and Font_Paint3Blended() to support background blending. Note that the original Font_Paint() may internally call Font_Paint3() [so is not going to be RISC OS 2 compatible any more], it is retained purely because the API is simpler - put this text at this location, for when no fancy stuff is required.
• Font (more) - Add Font_EnumerateCharacters() to allow Unicode characters to be looked up.
  [would it be feasible to do a Font_PaintUTF() which will output in the current font but if it finds a UTF-8 character that is not supported in the file, to try to switch to Cyberbit (?or?) to display it [use Font_ReadDefn to match current font size] (otherwise fall back to '?')?]
  [does Font_LookupFont return more in R2 nowadays?]
• Icon - add ShadeAll(), UnshadeAll, and DeselectAll() as quick ways to set a known state.
• Kbd - [do we need any changes to support extra keys like WinKey?]
• Menu - FontMenu[3] and FontMenuDecode[3] will be the same. No more RISC OS 2 code.
  Add Menu_ForceClose() to remove an open menu.
• Net - (new library) add all of...
  Lookup() - convert hostname to IP address.
  LaunchURL() - try to start the *http* URL in various ways for various browsers.
  [if OS is RISC OS 5, it will use a simpler system; I recall getting a URL started with Browse, Fresco, and Oregano could be a bit convoluted]
  EncodeURL - given an input consisting of domain and path, it will build an http compliant URL (including escaping stuff in the path if need be). Will have an option to select https instead.
• Resource - Add ChoicesRead() and ChoicesWrite() to build appropriate filenames for accessing your choices file based upon "group" name (given), your application name (assumed), and a leafname (given). If the input is NULL,NULL then there will be no group, your application will be the subdir, and the file will be called "Choices".
  Will cope correctly with reading from Choices$Dir and writing to Choices$Write. ;-)
• Screen - add ReadModeVariable() to read display information. Add ReadState() to return a struct giving screen dimensions, colours, etc.
• Serial - [check NonZeroPollWord code as it is probably NOT 32 bit safe due to being entered by word values - fix this]
  What sort of level of serial support is present on HAL devices? Can we talk to the serial port of Beagle or Pi? Can it be handled via this code? [though, note, these serial ports are Tx/Rx only]
• SerialBlk - ? proposal to support serial blockdrivers?
• Sprite - duplicate every SpriteOp veneer with "Ptr" suffix to accept a pointer to a sprite (the current routines expect a sprite name).
  Check if MemorySize correctly calculates size requirements for "deep" sprites.
  Modify MemorySize and Create to handle mode specifiers.
• Time - ReadClock() to actually read the current system time.
  ConvertTimeToOrdinals() to convert a five byte time to a localtime ordinals block.
  ConvertTimeToUTCOrdinals() as above, but UTC time.
  ConvertTimeFormats() to convert many to many (more flexible; but RISC OS 5.20+ only). Returns with -1 if SWI not supported; else returns with R0 = NULL or pointer to error block.
  ReadOffsetFromUTC() to read offset from UTC in centi-seconds; including daylight savings correction if applicable.
• UTF8 - ? Support of UTF-8 may implicate a new library, for things such as counting characters in a UTF-8 string, working out a byte position for a given character, and so on.
• Wimp - ProcessKey should strip apart UTF-8 codes to send them as multiples.
  Add new functions for enhanced ReportError use.
  Add ResizeIcon().
  Is it feasible to fix SetCaretPosition() to work correctly on UTF-8 strings?
  Look at SetMode() re. mode selector blocks.
  Add TextOp().
• Window - add IsOpen() to return TRUE if window is open, else FALSE, and HasFocus() to return TRUE if window has input focus, else FALSE.

Your comments:

Rick, 27th June 2015, 13:42

I may also do some "simple app" tutorials here, to show how to get started with DeskLib.