home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / Docs / Updates < prev   
Encoding:
Text File  |  1993-07-15  |  19.7 KB  |  441 lines
  1. Updates between DeskLib versions:
  2.  
  3. 2.03 (July 1993) -------------------------------------------------------------
  4.  
  5. Important - Please note that Event_ and Wimp.h now support more RISC OS 3
  6. functionality. Specifically, Wimp_Initialise has a new parameter (message
  7. list) on the end - to re-link with this version of the library, you will need
  8. to upgrade any Wimp_Initialise calls in your code (add a NULL onto the end of
  9. the list of parameters to Wimp_Initialise). You can of course take this
  10. opportunity to upgrade your code to use the new features the RISC OS 3
  11. makes available. Note that you'll also need to use LibFile to re-make the
  12. WimpLib if you use it separately.
  13.  
  14. Along similar lines, you can now call Event_Initialise3() in place of
  15. Event_Initialise to do a proper RISC OS 3 Wimp_Initialise, passing in a
  16. list of accepted messages, etc. Event_Initialise provides the same (RISC OS 2)
  17. functionality as before.
  18.  
  19.  
  20. MISCELLANEOUS modifications
  21.   Modified the Libraries.!MakeDLib obey file. Each sublibrary is now compiled
  22.   by invoking an alias 'DLibMake', which makes the file shorter and more
  23.   readable, and also allows you to more easily modify the way in which
  24.   sublibraries are compiled.
  25.  
  26.   Modified the Clean obey files - they now won't abort if a file is missing.
  27.  
  28.   Modified the Makefiles to make everything tidier.
  29.   Now, in the obey file Libraries.!MakeDLib, you can set 3 amu variables:
  30.     x_cflags - c compiler extra flags
  31.     x_aflags - objasm extra flags
  32.     do       - What to do to create the sublibrary
  33.  
  34.   This allows you to do some important things:
  35.     x_cflags=-Ff
  36.       This is the new default, which reduces the library code size by about 5%.
  37.       However, when debugging, you may like to recompile the library with the
  38.       'f' removed, so that you can find the names of the functions being
  39.       called as you debug.
  40.  
  41.     do="Create $@ 1"
  42.       This will minimise disc space used by the library (by creating 1-byte
  43.       'sublibraries' instead of compiling them properly - the file is needed
  44.       so amu knows the sublibrary is up to date)
  45.  
  46.     do="LibFile -c -o $@ @.o.*"
  47.       This will create each sublibrary - you can then use the sublibrary files
  48.       to link with instead of the main DeskLib library (eg WimpLib is quite
  49.       handy on its own, and is only 18kB rather than DeskLib's >100kB, a very
  50.       useful thing if you're developing of floppies!)
  51.  
  52.  
  53.   Updated the TestApp- now does the following extra things:
  54.     * Uses outline fonts, and gets them right if you change screen modes
  55.     * Changes the window title if you click the menu item 'Change title'
  56.       when you brought the menu up from a window (else that item is shaded)
  57.  
  58.  
  59. BUGS which have been fixed:
  60.   Font
  61.     Fixed a major set of bugs due to a small and harmless-looking typo in the
  62.     Font sublibrary - most of the font calls would return a non-zero value
  63.     if no error occurred, and a zero value if an error occurred (i.e. the
  64.     opposite of what they should have been doing: MOVVS r0, #0 instead of
  65.     MOVVC r0, #0)
  66.     This affects most font calls, but you'll only notice a difference if you
  67.     check the returned error - the SWIs worked fine, but returned incorrect
  68.     error-return-values - all other return values were unaffected.
  69.  
  70.   ColourTrans, DragASprite
  71.     Similar problems were also removed from the assembler veneers for the
  72.     ColourTrans, DragASprite, and PopUp sublibraries - namely that the return
  73.     values were not consistent with the definitions given in the headers.
  74.     I'll keep a closer eye on this in future!
  75.  
  76.   Icon
  77.     Icon_BarIcon, Icon_GetText, Icon_Set(Integer/Double/Text), Icon_printf
  78.     previously did not correctly terminate strings correctly if they were too
  79.     long to fit in the icon.
  80.     Icon_BarIcon now uses sprite_MAXNAME rather than wimp_MAXNAME for copying
  81.     the sprite name (though these constants are both 12, so there is no
  82.     effective difference)
  83.  
  84.   Menu
  85.     No longer trashes your machine with indirected menu items (Menu_New)
  86.  
  87.   PopUps
  88.     'bugs' removed from the PopUp.h header file's example code segments
  89.     SWI veneers fixed up - they didn't quite correspond to the prototypes
  90.     given in the headers.
  91.  
  92.   Template_Clone
  93.     Now terminates copied strings properly.
  94.  
  95.  
  96. MODIFICATIONS
  97.   Error
  98.     Upgraded OtherSrc.c.Error and Error.h to new code submitted by P.Colmer.
  99.     Now Error_Report and Error_ReportFatal (and "Internal" versions of these)
  100.     take variable arguments - they can still be used exactly as before, but
  101.     you can now include any 'printf' style arguments to save having to
  102.     pre-assemble a string to pass in.
  103.  
  104.   Event
  105.     Upgraded Event_Initialise to call the new function Event_Initialise3
  106.     with a required WIMP version of 200 (RISC OS 2 WIMP), to add support
  107.     for RISC OS 3, and the new non-zero-pollword events.
  108.  
  109.   Resource
  110.     This has now been moved from Misc to its own (Resource) sublibrary.
  111.     Also added replacement call for Resource_Initialise,
  112.     Resource_InitialisePath, which allows you to use DeskLib functions
  113.     to load Templates, messages, etc. from a path ("AppName:Templates")
  114.     rather than a directory ("<AppName$Dir>.Templates") - useful for adding
  115.     support for internationalisation.
  116.  
  117.   Template
  118.     Added support into Template_Clone for a new 'maxtitlesize' value of
  119.     template_TITLEMIN (-1) which will allocate as much room for the title
  120.     as declared in the template definition.
  121.  
  122.     Added support for outline fonts into Template loading.
  123.     (See the end of Template.h for details of the new calls)
  124.  
  125.   Template, Handler, Window
  126.     Added code to fix any windows/templates you are using which contain icons
  127.     using outline fonts whenever a mode change necessitates it (On some mode
  128.     changes outline fonts will otherwise become the wrong size as the font
  129.     manager doesn't re-cache them).
  130.  
  131.     This functionality required addition of:
  132.     Font.c.LoseAll         Lose all fonts in a Template_Load style font
  133.                            usage array
  134.     Handler.c.ModeChange   Replacement for old ModeChange handler - does the
  135.                            same as before, but if you are using outline fonts
  136.                            (you have called Template_UseOutlineFonts()) it
  137.                            fixes all your fonts if necessary. Note that this
  138.                            only works on templates loaded with Template_ calls
  139.                            and windows opened with Window_ calls.
  140.     Template.c.UseOutFont  Function to call BEFORE Template_LoadFile to set up
  141.                            a font usage array and exit-handler to lose any fonts
  142.                            you were using.
  143.     Window.c.ModeChange    Function to call to fix outline fonts in all windows
  144.                            and templates. Called by Handler_ModeChange()
  145.  
  146.     Appropriate changes have been made to the relevant header files.
  147.  
  148.   Wimp SWI veneers
  149.     WimpSWIs.s.Wimp01 (Wimp_Initialise) has now been modified to support
  150.     the new RISC OS 3 parameter (the message list). This call is still
  151.     RISC OS 2 compatible, but those of you calling Wimp_Initialise directly
  152.     will need to add a NULL onto the end of your initialise call, e.g.
  153.       Wimp_Initialise(&version, "MyTask", &taskhandle);
  154.     will become:
  155.       Wimp_Initialise(&version, "MyTask", &taskhandle, NULL);
  156.  
  157.   Window
  158.     As well as the additions mentioned in the bit above,
  159.     changes have also been made to the internal window information structure
  160.     as used by the Window.c files. (The window template name is now
  161.     WIMP_MAXNAME+1 characters long (13) rather than 9 characters long)
  162.  
  163.  
  164.  
  165. ADDITIONS
  166.   Event
  167.     Added Event_Initialise3() to Event.c.Event. This more or less replaces
  168.     Event_Initialise with a new call that will initialise the RISC OS 3 WIMP
  169.     and allow you to pass in the list of desired messages. You should not use
  170.     Event_Initialise with WIMP version numbers greater than 200 - use
  171.     Initialise3 instead. [If you desire RISC OS 2 compatability, you MUST
  172.     call Event_Initialise]
  173.     This also allows the support for non-zero pollword events now available
  174.     under RISC OS 3. Thanks to P.Colmer.
  175.  
  176.   File
  177.     Added File sublibrary, which gives calls for opening, closing, reading and
  178.     writing (bytes, words, words with endian-conversion, chunks),
  179.     getting/setting the file position, and misc operations (reading file size,
  180.     deleting a file, checking if a file exists). These are all veneers for
  181.     OS_File/GBPB/BGet SWIs, and may be preferable to stdio functions in some
  182.     circumstances, as they are faster than stdio calls, and also are easier
  183.     to use in conjunction with other systems that work with RISC OS file
  184.     handles (rather than C's (FILE *))
  185.  
  186.     Added some test code for File_ calls to TestApp. This test code can be
  187.     found in "!TestApp.Test c" - you can add it back into the test app if you
  188.     feel keen to try it out! It also might be of use as an example of use of
  189.     the file calls, though they're pretty simple!
  190.  
  191.   GFX
  192.     Added GFX_VDU (and alias VDU), an OS_WriteC veneer
  193.  
  194.   Mem
  195.     Added Mem_MoveAnchor, which allows you to move the anchor for a memory
  196.     chunk into another variable. Very convenient in some circumstances
  197.     (i.e. I had an anchor in an array, and wanted to allocate a new chunk,
  198.      and some time later replace the old chunk with it in the array - this is
  199.      now possible by simply moving the anchors for the two blocks into new
  200.      storage locations as appropriate)
  201.  
  202.   PopUps
  203.     Added Docs.ModuleNote.PopUps which gives a bit more help and example code
  204.     on using PopUp windows from DeskLib C code.
  205.  
  206.   Sprite
  207.     Added 3 new Sprite functions - a veneer for SpriteOp 62 (read save area
  208.     size) and functions to return the size (in bytes) of a sprite, given its
  209.     vital parameters, and the size of a sprite needed to fill a window's icon.
  210.     Thanks to Tom Kirby-Green for this submission.
  211.  
  212.   Wimp.h
  213.     Wimp.h has been upgraded: icon_flags now include a third struct in
  214.     the union which allows you to directly access the font handle with
  215.     icon.font.handle instead of having to mask it out of icon.value
  216.  
  217.     Wimp.h now has extra support for RISC OS 3, relating mainly to wimp
  218.     pollwords and non-zero pollword events. Some new event mask bit
  219.     definitions have been added.
  220.  
  221.   Window
  222.     Added Window.c.SetTitle, which allows you to set the text of a window title
  223.     and update the correct bit of the screen, even when using odd sized
  224.     toolsprites, etc. (And better than win_settitle because it doesn't crash if
  225.     the icon is non-indirected, it bothers to terminate the string if it had
  226.     to truncate it to make it fit, and it doesn't try to force redraw part of
  227.     the screen if the window isn't actually OPEN!)
  228.  
  229.     Also added Window_ModeChange, as described above (Modifications to
  230.     Template)
  231.  
  232.  
  233. 2.01 (May 1993) --------------------------------------------------------------
  234. Apologies to all DeskLib users out there for the long (1 year) delay between
  235. releases, and for all the bugs and missing bits in the library. This delay
  236. was caused by my thesis and other things taking too much of my time. I hope
  237. that I will be able to continue DeskLib updates at a more reasonable pace
  238. in the future... I have jumped from version 1.04 to version 2.00 to reflect
  239. the reasonably large update, to stress the newness of this version, and
  240. to make you feel as if something must have been done between this and the
  241. last release! ;-)
  242.  
  243. Note that although DeskLib is now supporting RISC OS 3 functions, it is still
  244. RISC OS 2 compatible. Also, some things (such as Wimp_Initialise under RISC
  245. OS 3) have not yet been implemented, mainly due to a total lack of any
  246. documentation on the subject. This will hopefully change for the better in
  247. the not too distant future...)
  248.  
  249. Apologies to anyone who needs to adjust their code because of changes to the
  250. library headers. These changes were deemed necessary for one or more of the
  251. following reasons in each case:
  252.   * To make it work!
  253.   * To remove unnecessary incompatabilities with compilers other than Desktop C
  254.   * (as a side effect) To improve consistency/readability
  255.  
  256. You can, of course, stick with the old definitions in the headers if you
  257. prefer them. Most people I know have their own random perturbations of the
  258. original header files anyway!
  259.  
  260.  
  261.   Additions
  262.     Added sublibraries:
  263.       ColTrans       Assembler interfaces to 4 ColourTrans SWIs
  264.  
  265.       DragASpr       3 Routines for using DragASprite
  266.                      I especially direct your attention to
  267.                      DragASprite_DragIcon() which is excellent!
  268.                      (c.f. macro "Icon_StartSolidDrag" defined in icon.h)
  269.                      
  270.       Filter         Assembler interfaces to RISC OS 3 FilterManager SWIs
  271.  
  272.       Font           Assembler interfaces to 23 Font SWIs
  273.  
  274.       Kbd            Assembler function to check if a key (e.g  SHIFT, CTRL)
  275.                      is currently depressed. (No function yet to cheer it
  276.                      up if it is, though ;-)
  277.  
  278.       Menu           Simple menu creation and manipulation functions along
  279.                      similar lines to those in RISC OS lib. (A proper menu
  280.                      template system is planned in conjunction with Glazier
  281.                      for the future, but I needed to fill this gap NOW!)
  282.  
  283.       Mem            'flex'-like dynamic memory manager for multitasking
  284.                      applications. However, 'better' than flex, as it
  285.                      compacts its heap much more efficiently than the
  286.                      equivalent operation from flex (you call the Mem_Compact
  287.                      function just before Wimp_Poll). It also guarantees
  288.                      that blocks will not move around to a much higher degree
  289.                      than flex does, giving you more freedom.
  290.  
  291.       Sound          Routine to sound a system beep (VDU 7!)
  292.  
  293.     Added functions to:
  294.       GFX            Added GFX_Write0() and GFX_WriteN()
  295.  
  296.       Icon           Added Icon_SetSelect(), Icon_SetShade(), and
  297.                      Icon_DisposeIndData()
  298.  
  299.       Misc           Added Dispatch(), a generic function dispatcher, and
  300.                      new stringcr functions (strcmpcr, strcatcr, strcpycr)
  301.  
  302.       Sprite         Added 6 new SWI veneers
  303.  
  304.     Added more definitions to:
  305.       KeyCodes.h
  306.  
  307.   Subtractions
  308.     The REDRAW (3-d icon border redraw) code has been discontinued because:
  309.       a) RISC OS 3.10 includes this feature for you, and
  310.       b) DeskLib actively supports RISC OS 3.10 onwards and no longer has
  311.          any sympathy for people without it! (though all non-RISC-OS-3
  312.          specific portions of it still work fine with RO2, this cannot be
  313.          guaranteed for the future)
  314.      For this reason, Icon_Select3d, Icon_Deselect3d, and Handler_Redraw3d
  315.      have also been removed.
  316.      If you have code which uses any of the above, then either copy them
  317.      forward from your old DeskLib or convert your program to use RISC OS
  318.      3.10 borders!
  319.  
  320.  
  321.   BugFixes/Modifications
  322.     Generally:
  323.       Touched up the docs. PLEASE NOTE my change of email address!
  324.  
  325.       Rewrote all the makefiles. Now much smaller, tidier, and easier to both
  326.       understand and maintain, as well as more informative during Makes.
  327.       Redirected LibFile through a 'via' file (!Objects).
  328.       (It's wonderful what you can find out by reading the manual ;-)
  329.  
  330.       Moved "Template.c.strlencr" to "Misc.c.strlencr" (see strlencr.h, below)
  331.  
  332.       Slightly improved some of the Docs and quickrefs.
  333.  
  334.     Coord:
  335.       Fixed some stunningly obvious and totally wrong prototypes and
  336.       #defines in Coord.h, particularly the Coord_YTo... macros.
  337.  
  338.     GFX:
  339.       Most GFX commands have been converted to more efficient assembler
  340.       versions. The header reflects slight changes (e.g. GFX calls now no
  341.       longer return os_errors).
  342.       Fixed a harmless bug in GFX_CLG.
  343.       Made some GFX macros in GFX.h a bit nicer to read
  344.       Fixed GFX_Circle and GFX_CircleFill (used to use x+r instead of r!)
  345.  
  346.     Handler.ClickOK.c:
  347.       Now doesn't do anything if icon clicked with MENU.
  348.  
  349.     Icon:
  350.       BarIcon.c fixed to take icon size from the sprite correctly
  351.       Macro Icon_StartSolidDrag added as an alias for DragASprite_DragIcon
  352.       SetDouble modified to correctly fill in the right number of decimal
  353.       places.
  354.       SetCaret will now refuse to place the caret into a shaded icon.
  355.  
  356.     LinkList.h:
  357.       InitItem macros added - now use Init() to init an anchor and InitItem()
  358.       to init an item, which will make it easier to replace the workings of
  359.       the list manager seamlessly.
  360.       Also modified these macros so that they will function corrrectly in the
  361.       following code:
  362.         if (whatever)
  363.           LinkList_InitItem(blah);
  364.       Redefined LinkList_{Next|Previous}Item() to make them nicer to use -
  365.       instead of using LinkList_NextItem(&thing.header), you can now use
  366.       LinkList_NextItem(&thing); (note that both syntaxes are fine now)
  367.       The Makefile for ListLib now also includes ListLength.c
  368.  
  369.     Misc Resource.c:
  370.       Now adds terminator to string after strncat to ensure that the string
  371.       is terminated if you supply too long a name.
  372.  
  373.       **** Important
  374.       strlencr has been moved into the Misc sublibrary.
  375.       strlencr() has been modified to make it functionally equivalent to
  376.       the ANSI function strlen() - that is, it now returns a value 1 LESS
  377.       than it did under 1.04 (i.e. it doesn't include the terminator any more)
  378.       All routines within DeskLib which use this function have been modified
  379.       accordingly.
  380.  
  381.     Sprite:
  382.       Sprite.h tidied up, and parameter types slightly modified. 'sprite' and
  383.       'sprite_area' pointer typedefs fixed (previously used old names for the
  384.       definitions, so were totally incorrect)
  385.  
  386.     strlencr.h
  387.       This has been renamed to 'stringcr.h', and now includes more than one
  388.       cr-terminated string handling function. (Correspondingly, a slight
  389.       modification of Template.h.TemplDefs to #include this new header)
  390.  
  391.     Wimp.h:
  392.       window_ICONBAR changed from -1 to -2
  393.       message_destinee changed to a 'typedef int' instead of a union
  394.  
  395.       window_block structure used to use shorts for minwidth and minheight.
  396.       This has been changed to minsize.x and minsize.y (both for consistency
  397.       and compatability with the Risc Developments compiler)
  398.  
  399.       window_flags structure modified to use the normal DeskLib form for
  400.       flag-words (flag.value plus flag.data.*)
  401.  
  402.       iconvalid_BORDERTYPE changed from 'B' to 'R' (RISC OS 3, 3.10 onwards)
  403.  
  404.       Added definitions for message_WINDOWINFO (used for iconisation)
  405.       and message_MENUSDELETED (warning when a menu is closed)
  406.  
  407.       Added windowcol_XXXX defines to make accessing a window's colours
  408.       easier (i.e. window->colour[windowcol_WORKBACK] = colour_RED)
  409.  
  410.       Added colour_TRANSPARENT (= 255)
  411.  
  412.       Added message_menuwarn structure definition
  413.  
  414.     WimpSWIS:
  415.       Several function prototypes changed. Some were prototyped as accepting
  416.       a union which contained either a data set or a 'value' int. Unfortunately
  417.       the compiler baulks at this, so these have been changed to 'int's. This
  418.       now means that you need to pass in 'whatever.value' to these functions.
  419.  
  420.       Added Wimp_CommandWindow prototype, which somehow got missed out
  421.       last time!
  422.       Wimp_DeleteWindow fixed (now actually deletes the window! Wow!) 
  423.  
  424.     Window:
  425.       GetInfo.c: '&block' changed to '&block[0]'
  426.       Show.c:    Showing a window with open_NEARLAST now modified to open
  427.                  the very first such window centered. Also, only windows
  428.                  opened with NEARLAST will now affect the position of
  429.                  succeeding NEARLAST windows.
  430.  
  431.     Template.Clone.c
  432.       Modified to use the new form of strlencr()
  433.  
  434.  
  435. 1.04 31/05/92 ----------------------------------------------------------------
  436.   BugFixes/Modifications:
  437.     A minus changed to a plus in Coord_Convert routine (should now work!)
  438.     Extra fields added to the menu_flagword struct
  439.     Incorrect definitions of message_Data(Load/Save/SaveAck) fixed
  440.       -replaced incorrect "wimp_box" with "wimp_point"
  441.