PC World 2000 August/PCWorld_2000-08_cd.bin/Software/TemaCD/xbasic/xbpro.exe/xb/new.hlp

Text File | 2000-01-15 | 31.1 KB | 880 lines

'
'
' ####################  Max Reason
' #####  XBasic  #####  copyright 1988-2000
' ####################  features not in documentation
'
' subject to GPL and GPLL licenses - see gpl.txt, gpll.txt
'
' http://www.maxreason.com/software/xbasic/xbasic.html
' http://www.egroups.com/group/xbasic
' [e-mail]
'
' for Windows XBasic
' for Linux XBasic
'
'
' The following information may or may not be included
' in the printed documentation or other documentation.
'
'
' #####################
' #####  v6.0000  #####  20000115
' #####################
'
'
' #####  v6.0000  #####  20000115
'
' Linux XBasic brought into sync with Windows XBasic
' and both are released under GPL and GPLL licenses.
'
'
' #####  v5.0023  #####  20000111
'
' The last two arguments to the XgrDrawImage() functions
' were supposed to specify x,y indent - which is how far
' left,down from the top-left corner of the target grid
' to draw the image.  But the XgrDrawImage() functions
' were ignoring those arguments, and drawing the image
' at the current "drawpoint" - which should have no
' effect on those function.
'
' These functions are now fixed - the drawpoint is
' ignored and the last two arguments are x,y indent.
'
'
' #####  v5.0022  #####  19991230
'
' The LTRIM$(), RTRIM$(), TRIM$() intrinsics trim
' all characters with values <= 0x20 and >= 0x80 .
'
' This usually produces the appropriate and desired
' result on English language text.  But most other
' languages have more characters than English, and
' those extra characters are often put in the range
' >= 0x80 and occasionally in the range <= 0x20 .
'
' Functions XstLTRIM(), XstRTRIM(), XstTRIM() were
' added to the "xst" library as alternatives to the
' intrinsic trim functions.  These functions require
' two arguments, the string to trim, and a 256 element
' XLONG array that contains zero in every location
' corresponding to a character that should be trimmed.
'
' XstLTRIM (@string$, @array[])
' XstRTRIM (@string$, @array[])
' XstTRIM (@string$, @array[])
'
' IMPORTANT NOTE:  These functions return 0 = success
' and -1 = failure, NOT a result string.  For efficiency,
' these functions work on the first argument in place,
' so the string argument must be passed by reference,
' or the string will not be modified.  The second
' argument must be passed by reference because arrays
' must always be passed by reference in XBasic.
'
' The new "atrim.x" sample program illustrates and
' contrasts the intrinsics and the new functions.
'
'
' #####  v5.0022  #####  19991225
'
' Added ROTATEL() "rotate left" intrinsic for symmetry with
' the ROTATER() intrinsic - at request of XBasic programmer.
' The new "arotate.x" sample program illustrates rotates.
'
'
' #####  v5.0021  #####  19991220
'
' The following line in sample program "acrc32.x" worked
' in the development environment, but not in executables.
'
' sum = (sum >> 1) XOR 0xEDB88320
'
' The problem was in the XBasic "spasm.exe" assembler,
' which generated improper binary for "xor" instructions
' when the second operand was a literal number instead
' of a register or memory.
'
' This problem is fixed in the "spasm.exe" assembler.
'
'
' #####  v5.0021  #####  19991220
'
' XBasic programs containing the ROTATER() intrinsic
' worked correctly in the development environment, but
' not in executables.  In the assembly language XBasic
' generated for ROTATER, the shift-count register for
' the "ror" opcode was "ecx".  The "spasm.exe" assembler
' expected "cl" and therefore reported an error and did
' not emit the necessary "ror" machine instruction.
'
' This problem is now fixed in the XBasic compiler,
' which now calls the shift-count register "cl".
'
'
' #####  v5.0021  #####  19991220
'
' Though disfavored because the readability is much
' worse than the RETURN statement, functions have
' been able to return values as follows:
'
' END FUNCTION  value_or_expression
'
' But when XBasic programs were loaded into the development
' environment everything following END FUNCTION was lost.
'
' This problem is now fixed.
'
'
' #####  v5.0020  #####  19991214
'
' A minor problem with XgrGetClipboard() was fixed.
'
'
' #####  v5.0019  #####  19991213
'
' A minor problem with ULONG type conversion was fixed.
'
'
' #####  v5.0018  #####  19991212
'
' A new sample program was added, called "aspread.x".
' This program illustrates the case where you want to
' create a window containing a huge number of grids.
'
' This sample program contains a 40x40 "spreadsheet"
' or array containing 1600 grids.  Even with the
' "another" button on the GuiDesigner toolkit, the
' time and effort required to create and position
' 1600 grids is substantial.
'
' This program shows how to create and position the
' grids in a loop within the Resize subroutine, which
' is called at the end of the Create subroutine anyway.
'
' This program also shows how individual elements can
' be conveniently selected, moved and highlighted with
' mouse-clicks and arrow-keys.  When a string is entered
' in the XuiTextLine grid, the first character is drawn
' in the selected spreadsheet grid.
'
' This program toggles the keyboard focus back and forth
' between the XuiTextLine grid and the selected grid in
' the spreadsheet whenever an escape-key is pressed.
'
' Windows with many display-fields but only one input-field
' are very convenient in a wide variety of applications.
' This sample program illustrates some reasonable ways
' to implement and operate such windows.
'
'
' #####  v5.0018  #####  19991212
'
' Composite variables and arrays whose scope was specified
' to be SHARED by its # prefix caused compile-time errors.
' These errors did not occur for composite variables and
' arrays declared in SHARED statments.
'
' This problem is now fixed.
'
'
' #####  v5.0018  #####  19991212
'
' The XstStringToNumber() function returned the wrong
' datatype on numbers with the most-significant-bit set.
' For example, the following assignment to a GIANT variable
' did not work correctly, as the PRINT illustrated.
'
'    giant$$ = 2147483648 : PRINT g;; HEX$(g,16)
'
' This problem is now fixed.
'
'
' #####  v5.0018  #####  19991212
'
' In certain situation, the first floating-point value
' in a semi-colon separated list of print arguments
' would not be printed, for example:
'
'   PRINT INT(a); INT(b)
'
' This rarely encountered problem is now fixed.
'
'
' #####  v5.0017  #####  19991125
'
' Some people without TCP/IP networking on Windows95/98/NT
' have startup problems caused by some kind of problem with
' initialization of the "xin" function library.  Apparently
' these people can start XBasic when dial-up networking is
' currently connected, but not otherwise.
'
' By default, the file "c:/windows/xb.ini" now contains
' the line "xin=false" which disables "xin" initialization.
' To program with the "xin" library, add a comment character
' to that line to enable the "xin" library - "' xin = false".
'
'
' #####  v5.0017  #####  19991125
'
' Added #GetCharacterMapEntry and #SetCharacterMapEntry
' messages and tested them in XuiTextArea grids.  Without
' these messages it was impossible to change character maps
' of grids in "/xb/xxx/property.xxx".
'
'
' #####  v5.0016  #####  19991120
'
' Added two more standard cursors to the sequence of
' XgrRegisterCursor() lines in the InitGui() function
' of GuiDesigner programs.  These two new cursors are
'
'   XgrRegisterCursor (@"hand",         @#cursorHand)
'   XgrRegisterCursor (@"help",         @#cursorHelp)
'
' Note that #cursorHand is not supported in versions
' of Windows prior to 5.0 - which means WindowsNT 5.0
' and maybe Windows2000.
'
'
' #####  v5.0015  #####  19991115
'
' XBasic has a new main window.  Now XBasic looks "more modern"
' and more like some of those brand-X development environments.
'
' Some of you will now complain, "Hey, I just learned how to
' operate the XBasic environment efficiently and you have to
' go and change it".  What's worse, the hot buttons have no
' writing on them anymore.  Will this start a riot?
'
' Hopefully not.  All the hot buttons and other grids on
' the main window have "hint strings".  When you pause
' the mouse cursor over any grid, a little "hint window"
' will appear just above the upper-left corner of the grid,
' with a few words that describe what that grid is and does.
'
' If you want more elaboration information, remember the
' built-in InstantHelp that has always been there - just
' click the right mouse button on any grid to display
' the InstantHelp window with more elaborate information
' on that grid.  You can add/delete/modify the contents of
' the InstantHelp window, then click the "update" button.
' This updates the help-text for that grid, so from then on
' you'll see the modified text for that grid whenever you
' request InstantHelp for that grid again.
'
' You can still execute "dot commands", but now you enter
' them in the command grid instead of the upper TextArea.
' The command grid has a pulldown list of previous commands
' you executed so you can recover and repeat them easily.
' XBasic sometimes puts information in the command grid,
' for example the steps of compilation as they progress.
'
' Escape keystrokes still toggle the text cursor back
' and forth between the lower TextArea and command grid.
'
' The sample program "anewlook.x" is nearly identical to
' the new XBasic main window, so you can examine the code.
' You can load "anewlook.x" into the environment and run it.
'
' All the icons for "anewlook.x" and the new main window
' are in the "\xb\xxx" directory - all have .BMP extents.
' If you dislike some of the icons, all you have to do is
' make new ones you like, name them the same as the ones
' you want to replace in the XBasic main window, and put
' them in the "\xb\xxx" directory (overwrite the old one).
' Maybe you should back up all the .BMP files in "\xb\xxx"
' first - just in case your icons look even worse!  :-O
'
' You can see what your new icons will look like in XBasic
' without changing XBasic.  Just change the icon names in
' the XuiSendMessage (g, #SetImage, ...) functions in the
' MainWindow() function in the "anewlook.x" sample program.
' Change the existing icon names to new icon names.  Perhaps
' the easiest technique is to make a \xb\xxx\xxx subdirectory,
' copy all the existing .BMP files to that directory, then
' replace every occurrence of "D:\\xb\\xxx\\" in MainWindow()
' to "D:\\xb\\xxx\\xxx\\".  Then you can do your icon work
' in "D:\\xb\\xxx\\xxx\\" and freely test with "anewlook.x"
' without changing the XBasic main window --- until later.
' To do this, view MainWindow(), then enter this dot command:
'
'  .r D:\\\\xb\\\\xxx    D:\\\\xb\\\\xxx\\\\xxx
'
' Make all your replacement icons exactly 16x16 pixels.
' If you're totally convinced you have more recognizable
' and/or attractive replacement icons, send them to me.
' If I agree, I'll put them in future XBasic releases.
'
'
' #####  v5.0015  #####  19991115
'
' The XuiDropButton and XuiListButton generate a #Notify
' callback message when the button is clicked.  This lets
' programs update the XuiPullDown or XuiList grid that
' drops below the button.  This generally useful feature
' had to be added to support the convenient FUNCTION list
' in the new XBasic main window.  When the function button
' is clicked, XBasic sends a #SetTextArray message to the
' XuiListButton grid with a sorted list of function names.
'
' The #Notify message was not previous defined, so you
' need add a line to your InitGui() function to register
' that message in any program you want to process #Notify.
'
'
' #####  v5.0015  #####  19991115
'
' The XuiListButton grid sizes more intelligently and
' decides whether to display the list above or below
' more intelligently.  The XuiListBox has not been
' similarly updated yet.
'
'
' #####  v5.0014  #####  19991110
'
' Several people have asked for a sample program that
' shows how to create a window and draw simple graphics
' with only GraphicsDesigner AKA "xgr" functions - and
' no GuiDesigner AKA "xui".
'
' A new sample program called "agraphic.x" is now
' included in the XBasic distribution to demonstrate
' simple GraphicsDesigner capabilities.
'
'
' #####  v5.0014  #####  19991110
'
' All three versions of the XgrDrawCircle() function
' cleared the area inside the circle after drawing it.
' That is now fixed.
'
'
' #####  v5.0012  #####  19991001
'
' Several GuiDesigner grid-types have been enhanced,
' modified or tweaked, including:
'
' XuiProgress - supports styles 0 to 2
' XuiScrollBarH - supports styles 0 to 3
' XuiScrollBarV - supports styles 0 to 3
' XuiDropBox - pulldown is now an accessible kid grid
' XuiDropButton - pulldown is now an accessible kid grid
' XuiListBox - pulldown is now an accessible kid grid
' XuiListButton - pulldown is now an accessible kid grid
' XuiList - supports styles 0 to 3 (passes to scroll-bars)
' XuiTextArea - supports styles 0 to 3 (passes to scroll-bars)
' XuiCheckBox - supports styles 0 to 3
' XuiRadioBox - supports styles 0 to 3
'
' None of the above are extensively tested.
' Please report any bugs or peculiarities.
'
'
' #####  v5.0011  #####  19990925
'
' When a new font is set in XuiPullDown, XuiList, XuiTextArea,
' and XuiTextLine grids, the interline spacing is now correct.
' Previously the interline spacing would not always adjust in
' the appropriate manner.
'
'
' #####  v5.0011  #####  19990925
'
' When programs set the font of XuiDropBox and XuiDropButton
' grids with #SetFont or #SetFontNumber, the font propogates
' to the pulldown list.  Previously programs were not able to
' set the font in the pulldown list.
'
' Another change has been made on a provisional basis, but
' may be made permanent if no adverse consequences occur.
' The pulldown list is now accessible as an additional kid
' of the XuiDropBox and XuiDropButton grids.  Because the
' pulldown list is in a separate window, this violates one
' GuiDesigner convention - that kid grids must be in the
' same window as their parents.  This makes it possible
' to set font and other properties on the pulldown list
' of these grids in the Appearance Window - by selecting
' the pulldown list kid and setting the desired properties.
' If undesired consequences or problems are found with this
' approach, this aspect may be changed, in which case the
' pulldown list will probably share at least color and font
' properties with the XuiDropBox or XuiDropButton grid.
'
'
' #####  v5.0011  #####  19990925
'
' XBasic and executables created from XBasic programs
' do not work [properly] on some computers that do not
' have networking configured or enabled.  Now you can
' stop the "xin" function library from initializing
' [and potentially failing or locking-up] by putting
' a "xin=false" line in text file "c:/windows/xb.ini".
' If "xb.ini" does not already exist on your system,
' go ahead and create it and add the line.
'
'
' #####  v5.0010  #####  19990902
'
' XgrGrabPoint() was not fixed properly in v5.0009,
' but hopefully is correct now.
'
'
' #####  v5.0009  #####  19990821
'
' XgrGrabPoint() was not working properly, always
' returning 0, 0, 0, 0 for red, green, blue, color.
' This is now fixed.  NOTE:  Not every video card
' supports reading the color of arbitrary pixels.
'
'
' #####  v5.0007  #####  19990725
'
' Support for two new border styles has been added to
' GraphicsDesigner - $$BorderRise2 and $$BorderSink2.
' These styles are simple 2-pixel wide raise and lower
' borders like $$BorderRaise2 and $$BorderLower2, but
' the 2 adjacent lines are drawn in different colors.
' One line is drawn in lowlight and lowtext color,
' and the other in highlight and hightext color.
'
' The GuiDesigner AppearanceWindow does not support
' these new styles yet, so you'll need to set the
' border style to something else, then change the
' arguments of the #SetBorder message appropriately.
'
'
' #####  v5.0007  #####  19990725
'
' The XstGetCommand(@line$) function was added
' to the XBasic standard function library.
'
' This function returns the entire command line
' in a single string argument.  This makes cgibin
' programs slightly easier to write in XBasic.
'
'
' #####  v5.0006  #####  19990715
'
' GuiDesigner grids have always had a HintString property,
' but previously it had no effect on program operation.
' Now the HintString is active.
'
' When the mouse cursor pauses for about 1 second over
' a grid that has a HintString property, a "hint window"
' containing the HintString is displayed just above the
' upper-left corner of the grid.  The hint window is
' hidden when the mouse moves or 4 seconds expires.
'
'
' #####  v5.0005  #####  19990611
'
' XuiPushButton grids can now be configured as "flat buttons"
' by setting the style attribute to 2, which can be done with:
'
'   XuiSendMessage (grid, #SetStyle, 2, 0, 0, 0, $Kid, 0)
'
' where $Kid is the kid-number of the button grid you want
' to change.
'
'
' #####  v5.0005  #####  19990611
'
' The XuiMenu and XuiMenuBar now highlight the menubar entry
' the mouse is above, even when no mouse button is not down.
'
'
' #####  v5.0005  #####  19990611
'
' A new sample application is included called "anewlook.x".
' This is a new look for the XBasic development environment
' that you can improve upon and submit for review.  The look
' selected as the best new design will become the new look
' of XBasic for future releases.  Submit your "anewlook.x"
' files to [e-mail] before 1999/07/31.
'
'
' #####  v5.0004  #####  19990522
'
' XBasic GuiDesigner now has two new messages that affect
' character and line spacing of [multi-line] text in grids.
'
' new message : #GetTextSpacing
' new message : #SetTextSpacing
'
' XBasic GuiDesigner programs send these messages as usual:
'
' XuiSendMessage (grid, #GetTextSpacing, @xgap, @ygap, 0, 0, kid, 0)
' XuiSendMessage (grid, #SetTextSpacing, @xgap, @ygap, 0, 0, kid, 0)
'
' xgap : positive or negative to increase or decrease character spacing.
' ygap : positive or negative to increase or decrease line spacing.
'
' xgap currently has no effect of text drawing
' ygap currently does effect text drawing
'
' As a simple demonstration, #SetTextSpacing currently reduces
' the line spacing of the XBasic startup window by 4 pixels.
'
'
' #####  v5.0002  #####  19990513
'
' XBasic now recognizes two new command line arguments:
'
'  -ft filename.ext
'  -fl filename.ext
'
' -ft means "File TextLoad"
' -fl means "File Load"
'
' This means you can now associate files with a .x extent
' to XBasic.  Once you do this, selecting any file with a
' .x extent will start XBasic and have XBasic load the file.
'
' To associate an extent with XBasic, start Windows Explorer,
' select "View FolderOptions FileTypes NewType", then enter
' the following information:
'
'   description of file : XBasic program
'   associated extension : .x
'
' Then click the "New" button and enter:
'
'   action : open
'   application to perform action : c:\xb\xb.exe -fl
'
' If you want to have XBasic load .x files as text-files
' instead of programs, enter "c:\xb\xb.exe -ft" instead.
' If you want to associate any other type of file with
' XBasic, you must have XBasic load them as text-files.
'
' If XBasic is not installed on your "c:" drive, change
' "c:" in the above examples to the appropriate drive.
'
'
' #####  v5.0001  #####  19990512
'
' On some Windows98 systems, some button images in the
' XBasic main window would sometimes appear solid black
' with no image.  This Windows98 bug is worked around
' in v5.0001 and should no longer occur.
'
'
' #####  v4.0020  #####
'
' A "sockets" function library has been added to provide
' a portable interface to sockets and networks in general
' and the internet in particular.  This is not documented
' currently, but you can look at "xin.dec" for function
' prototypes and demo programs "aclient.x" and "aserver.x"
' for examples of how simple clients and servers call the
' the "xin" library functions.
'
'
' #####  v4.0018  #####
'
' Before v4.0018, a bug would sometimes occur when
' a function argument is both passed by @reference
' AND of a different data type than the declared
' type that requires reconversion to the argument
' type after the function returns.
'
'
' #####  v4.0017  #####
'
' Before v4.0017, intrinsic a$ = CHR$(byte,length)
' will sometimes return a string in a$ that is not
' terminated by a zero byte aka null terminator.
'
'
' #####  v4.0017  #####
'
' Before v4.0017, the following three standard library
' functions take and return the year argument in 1900
' relative form, as in 97 instead of 1997.  Since these
' functions all treat the year the same, programs that
' call these functions may work properly, but probably
' will produce errors when run on other implementations.
'
' XstGetDateAndTime ()
' XstDateAndTimeToFileTime ()
' XstFileTimeToDateAndTime ()
'
' XstGetDateAndTime (@year, @month, @day, ... )
' returned (year-1900) in the year argument instead
' of the year.  In other words, if the date today is
' 1997 March 15, the year argument would return a
' value of 97 instead of 1997.  This error has been
' fixed as of v4.0017.
'
' XstDateAndTimeToFileTime (@year, @month, ... )
' expected (year-1900) in the year argument instead
' of year.  This error has been fixed as of v4.0017.
'
' XstFileTimeToDateAndTime (filetime$$, @year, ... )
' returned (year-1900) in the year argument instead
' of year.  This error has been fixed as of v4.0017.
'
'
' #####  v4.0016  #####
'
' A few of the math library routines have been rewritten
' in assembly language for increased speed and precision.
' Since most of the other math functions functions call
' these rewritten functions, almost every function in the
' math library is faster and/or slightly more accurate.
' Some functions are 3x to 4x faster than before.
'
' The functions moved into assembly language include:
'
' SIN()  :  COS()  :  TAN()  :  ATAN()
' SQRT() :  EXP()  :  EXP2() :  EXP10()  :  POWER()
'
' POWER() is called whenever a number is raised to
' a power by the ** operator, as in "a# = b# ** c#",
' which means "raise b# to the c# power".
'
'
' #####  v4.0015  #####
'
' The initial properties of grids are the defaults for
' the grids or those set by the program.  A feature was
' added recently that lets users change the properties
' of grids after a program is running.  Now a new feature
' lets users specify initial values for specific grids,
' or whole classes of grids.
'
' The initial properties of a specific grid or group of
' grids can be specified in "$XBDIR/xxx/property.xxx".
' After a program creates a new window and all the grids
' in that window, it will now send a #SetGridProperties
' message to the main window grid.  The window grid will
' then propogate the message to its kids and so forth if
' the v0 argument is -1, which it will generally be.
'
' The default message processing function function for
' #SetGridProperties is XuiSetGridProperties().  This
' function looks for matches between entries in the
' "default property database" and the grid.  Each entry
' that matches the grid and has valid syntax "executes"
' the entry to change properties of that grid.
'
' Entries match on the basis of program, gridtype, and
' gridname.  Since the program, gridtype, and gridname
' fields can be "wildcarded" with "*", properties of
' every grid of a given gridtype can be specified in
' a single entry.  For example, it takes only one line
' to change the border of all XuiLabel grids in one,
' or even all programs.
'
' The "$XBDIR/xxx/property.xxx" file contains examples
' and more information.  This feature is new and still
' under development.
'
'
' #####  v4.0013  #####
'
' The following feature is "work in progress" that
' does not operate properly in every circumstance.
' This feature is described here so you may sample
' it and have an early chance to report bugs and
' annoying aspects so we can fix them soon.
'
' The appearance properties of ANY GuiDesigner grid
' can be interactively modified at any time by means
' of the Appearance Window.  This includes any grid
' in programs you are running in the environment, any
' grid in the development environment itself, and any
' grid created by .EXE and .DLL programs and libraries
' you create from XBasic programs.  In other words,
' this capability is fully available to people who
' use your programs.  If you want, you can disable
' this feature in programs you distribute as follows:
'
' XgrGridTypeNameToNumber (@"Appearance", @gridType)
' XuiGetGridTypeGrids (gridType, @g[])
' IF g[] THEN Appearance (g[0], #SetStyle, 0x01, 0, 0, 0, 0, 0)
'
' Certain problems exist when you set properties of
' XuiTextArea and XuiTextLine grids unless you set
' the attributes on the "outer" parent grid.  These
' grid types contain a featureless grid that fills
' the innards of the XuiTextArea and XuiTextLine
' grid and displays the text.  Thus if you click
' anywhere in the body of the grid you will select
' the "innard" grid and set the properties of that
' grid without the knowledge of its parent.  This
' can cause problems in certain situations, which
' you may see.  If you click on the pixel in the
' bottom right corner of these grids you can select
' the XuiTextArea or XuiTextLine grid itself and
' setting appearance properties should work okay.
'
' Not implemented at this time, but intended for
' the final release of this feature is the ability
' to set the appearance attributes of any grid TYPE.
' Once grid TYPE attributes are changed, all grids
' of that grid type are created with the new values.
'
'
' #####  v4.0013  #####
'
' Previous implementations of XBasic padded fixed
' length strings in composite variables differently.
' Furthermore, the documentation was inconsistent.
'
' When a normal string was assigned to a longer fixed
' length string in a composite variable, the extra bytes
' in the fixed length string were filled with 0x00 in
' some implementations and with 0x20 in others.
'
' This difference caused a different behavior when the
' fixed length composite string was assigned to a normal
' string.  When the extra bytes in fixed length strings
' were filled with 0x20 bytes, then those 0x20 bytes were
' also assigned to the normal string and thus the length
' of the normal string was always the same as the fixed
' length string that was assigned to it.  When the extra
' bytes in fixed length strings were filled with 0x00,
' only the bytes before the first 0x00 were assigned to
' the normal string, and the normal string could be any
' length from zero bytes up to the size of the composite
' fixed length string.
'
' From v4.0013 onward, all versions and implementations
' of XBasic fill extra bytes in composites with a 0x00.
' In the other method, it was usually necessary to apply
' the TRIM$() intrinsic to a normal variable after a
' fixed length string was assigned to it.  Now this is
' generally not necessary.
'
'
' #####  v4.0012  #####
'
' Each time XBasic or an XBasic program is started, a
' "fonts.xxx" file is built in the "xxx" subdirectory.
' This file contains a list of non-scalable fonts.
'
' If you do not like the default font for some reason,
' you can specify a new "default font" by putting any
' name you find in the "fonts.xxx" file in a "font.xxx"
' file in the same "xxx" subdirectory.  Henceforth the
' default font for all grids is initialized to the font
' you specified.
'
' If the character mapping is wrong on your system, it
' may be that the default font is intended for another
' locale or country.  You should be able to solve this
' problem by creating a "font.xxx" file.  If "font.xxx"
' does not exist, the normal default font is selected.
'
' The "font.xxx" file may contain more than one line
' and more than one font name.  Lines that begin with
' a ' comment character are ignored.  The first line
' that is not empty and not commented out is assumed
' to be the specified default font.  If the specified
' default font cannot be created, the normal default
' font is selected.
'
'
' #####  v4.0011  #####
'
' Add : XgrGetKeystateModify (state, @modify, @edit)
'
' Programs can pass the v2 aka state argument in #KeyDown
' messages to XgrGetKeystateModify() to find out whether
' the #KeyDown message will modify text by inserting or
' deleting one or more characters.
'
' Currently this function treats Cntl+Insert as an edit
' keystroke that modifies the text, even though the usual
' action for this keystroke combination is to copy the
' selected text to the clipboard without modifying the
' text itself in any way.  Cntl+Insert may cease to
' claim a modify in the future, so programs that need
' to be precise about this issue should check for this
' case separately.
'
' XgrGetKeystateModify() reports modify for keystrokes
' that normally have the POTENTIAL to modify text without
' consideration of whether the keystroke will modify text
' in any particular grid.  For example, if the text cursor
' is at the start of text when a Backspace key is entered,
' there is no "previous" character to delete.  Likewise,
' if the text cursor is at the end of text when a Delete
' key is entered, there is no "next" character to delete.
' If the clipboard is empty when the Insert key is entered,
' there is no text to insert at the text cursor position.
' In all these cases text is not modified, but the modify
' argument is returned TRUE aka non-zero.
'
' This function is provided as a "normal case" convenience
' function, but cannot be relied upon by all programs in
' all situations.  Where precise information is required,
' or when non-standard keyboards or keystroke combinations
' will occur, programmers must determine the degree of
' applicability of this function and suppliment or replace
' it as appropriate.
'
'
' #####  v4.0011  #####
'
' Add : XgrGetGridCharacterMapArray (grid, @map[])
' Add : XgrSetGridCharacterMapArray (grid, @map[])
'
' Programs can now install and examine a "character map"
' for each grid to change the character printed for any
' character value.  map[] must be an XLONG array and must
' contain at least elements 0x00 to 0xFF.  When a program
' calls any GraphicsDesigner function that draws text in
' a grid, the map array converts every character in the
' text string to the corresponding character in the array
' before it displays the string.  The following code makes
' lower case characters display as upper case equivalents:
'
'   DIM map[255]
'   FOR i = 0 TO 255
'     SELECT CASE TRUE
'       CASE (i < 'a') : map[i] = i
'       CASE (i > 'z') : map[i] = i
'       CASE ELSE      : map[i] = i - 0x20
'   NEXT i
'   XgrSetCharacterMapArray (grid, @map[])
'
' acharmap.x is a sample character map program included
' with all XBasic releases of v4.0011 and higher.
'
'
' #####  v4.0011  #####
'
' Mod : XgrGetCommandLineArguments (@argc, @argv$[])
' Add : XgrSetCommandLineArguments ( argc, @argv$[])
'
' Programs can now alter the command line arguments with
' XgrSetCommandLineArguments().  This is convenient for
' debugging programs in the development environment where
' the command line arguments are not appropriate to the
' program begin debugged.
'
' Even after the command line arguments are changed,
' programs can get the original values of the command
' line arguments by passing a negative value as the
' first argument to XgrGetCommandLineArguments().
'
'   argc = 3
'   DIM argv$[2]
'   argv$[0] = "zap"
'   argv$[1] = "zap.x"
'   argv$[2] = "zap.zap"
'   XstSetCommandLineArguments ( argc, @argv$[])
' '
' ' get original command line arguments : argc < 0
' '
'   argc = -1
'   XstGetCommandLineArguments (@argc, @argv$[])
' '
' ' get current command line arguments : argc >= 0
' '
'   argc = 0
'   XstGetCommandLineArguments (@argc, @argv$[])