New Help File (Build 13)

[dragonjim]

The latest version of the HTML format GFABasic help file (Build 13 - released 1st December 2021) can now be downloaded from one of the two following links:

1. If you do not already have the help file, you can get it, the GLL extension which links it to the GFABasic IDE and a ReadMe.txt file which describes how to install and register both files, from this link (non-operable at the moment). (Mirror here: Mirror 1)
2. If you are simply updating to the new build, you can get it from here (non-operable at the moment). (Mirror here: Mirror 1)

Once you have downloaded the help file you will have to activate it: Right click on the GfaWin32.chm file and select 'Properties'; at the bottom right you will see a command button 'Unblock'; click this and you are ready to go.

If you find any errors within the Help File, please email them to [e-mail].

The new Build 13 has all Direct2D and GfaWinX library routines included, plus a new Variant array library, in addition to numerous corrections and page amendments. Thanks to Jean-Marie Melanson for reporting errors.

Major changes in Build 11:

1. Comprehensive cover of the new Direct2D library functions.
2. All the new GfaWinX library functions
3. Updated pages on IDE Overview, Sidebar tabs, Properties and other Menu Items
4. Different layout and font size.
5. Over 70 small edits, comments, amendments, bug reports

Major changes in Build 10:

1. Expanded page on handling HTML/chm help files.
2. Tidied and expanded information on Variant variable type (more to come).
3. Added workaround for missing CVErr function.
4. Added known shortcut keys that work with RichEdit boxes.
5. Functions, Procedures and Subs are now dealt with on one page, with more detailed information.
6. Page on LG32 Libraries expanded and example added to show how to use forms in them.
7. New page dealing with Manifest File and Common Controls.
8. A new page on Form Scaling added.
9. Hundreds of dud and erroneous links corrected.
10. Over 70 other minor corrections.
    

The following is a list of major changes in Build 9:

1. A fuller description of LG32 Libraries.
2. Articles on SafeArrays, ByteArrays and Arrays in Variants.
3. Additional ways to control and shape ComboBoxes
4. Tidied and expanded page on User-defined Types.
5. New page on Memory Allocation.
6. Plus over 100 corrections and amendments to many different articles.

The following is a list of major changes in Build 8:

1. Edited and Improved Multithreading pages.
2. Removed identical index reference tags from pages, so it is now clearer which page you need when searching.
3. Re-written and combined all menu related pages into two: Menu Bars and Popup Menus,  Added sections to each on how to create/edit menus with APIs.
4. Added the 'Step' variants of the Box, PBox, RBox and PRBox commands.
5. Added diagrams to Circle, PCircle, Ellipse and PEllipse to show drawing direction and arc angle references.
6. Added workaround to DateDblClick event in MonthView which does not work.
7. Enhanced description on BulletIndent for RichEdit boxes.
8. And another 90+ corrections and edits to articles.

If you have any problems, queries or comments, post below.

For anyone interested in old German help file converted to .chm format (this is a rough copy), you can find one here.

Edit 15th January 2016: updated to Build 8.1.
Edit 27th January 2016: updated to Build 8.2.
Edit 12th March 2016: links fixed.
Edit 13th July 2016: updated to Build 8.3
Edit 4th March 2017: updated to Build 9
Edit 6th March 2018: updated to Build 10
Edit 16th July 2020: updated to Build 11

[troycheek]

Great job, as always!  Now, on to the criticism! 

FileCopy/CopyFile:

The example includes a subroutine which is called after every 32 KB of data is copied to calculate the percent complete and update the progress bar.  The sub includes a "Pause 1" toward the end.  This has the effect of pausing the copy operation for a 1/18th of a second every 32 KB which greatly increases copy time.  I do not understand what purpose this pause serves.  Perhaps in the days of floppies you needed to pause every so often to keep the computer from becoming unresponsive?  Perhaps the author didn't want the progress bar to be updated too often and bog down the program?  Regardless, I replaced the "Pause 1" with "DoEvents" because some of my copy operations were going on long enough to make Windows 7 think the program had gone non-responsive.  My version now looks something like this:

Sub check_it(bytes_copied%, ident%)
 If ident% = 1 And Time$ <> lt$ Then
   lt$ = Time$
   prg.Value = 100 * (bytes_copied% / LE)
   DoEvents
   'Pause 1
 EndIf
EndSub
lt$ is a global variable (yes, I know, bad programming practice).  This has the effect of only doing the Value calculation and updating the progress bar every second or so, which can't possibly bog down the program, IF that's the reason for the Pause 1.  The LE is the length of the file being copied, another global variable.  Speaking of the length of a file...

Help file says "bytes_copied: Integer or Large (depending on the size of the file)" but if I try to write the sub with bytes_copied not explicitly %, I get a parameter error at the FileCopy line.  If I use bytes_copied%, it eventually wraps around to negative numbers if the file being copied is larger than _MaxInt.  I haven't found a workaround for this yet.

FileLen:

The workaround given for FileLen returning a 32 bit integer instead of a 64 bit integer works, but is too complicated for me to remember.  I've been using the following:

Dim LE as Large
Open Filename$ for Input Shared As # 17 : LE = LOF(# 17) : Close # 17

I don't know if it's possible for another program to lock a file in such a way that GB32 can't open it for shared read access, but that would of course cause an error.  I don't think opening a file this way (and for a tiny fraction of a second) would interfere with another program's use of the file.

ProgressBar OCX:

Using the Align property with the ProgressBar control (to automatically place the bar at the bottom/top/etc of the window/form/whatever) overrides some of the other properties like Width and Height.  In other words, you can't define a progress bar to be half the width of a window and then automatically align it to the bottom while retaining that width.  It will expand to fill the entire width, reset to the standard height, and possibly other things I haven't discovered yet.  I'm sure this is the intended behavior and probably very obvious to someone who's spent more time with OCX controls than I have, but it confused the heck out of me for a while.  There is mention that Align overrules the Orientation property.  Perhaps another mention that Align overrides Width and Height as well?

[dragonjim]

TroyCheek,

Thanks for the comments and apologies for not getting back to you sooner.

To answer your questions:

FileCopy/CopyFile

1. If I remember correctly, when I re-jigged the example for this page, I included the Pause 1 purely so that you could see that something had happened as, otherwise, the example ran through so quickly all you saw was a completed Progress Bar - there was no other reason for its inclusion and I will add a comment to the example so that is clear in the future.

2. Not really a question you asked, but if you want to use lt$ as a local variable within the Sub and don't want to use a Global variable, you could try making lt$ a Static local variable instead.

3. When I am likely to be copying files larger than MaxInt, I use a global large variable which is reset externally before the FileCopy/CopyFile starts and is incremented by 32768 every time the command calls the associated Sub, and I completely ignore the value in bytes_copied%. This will work as long as only one file is being copied at any specific time; if more than one FileCopy operation is likely, it may be better to use a Large array with the relevant element defined by the ident% parameter. I will try and add an example of this to the relevant page(s) in the near future.

FileLen

Your alternative to the FileLen large workaround is good but, as you guessed, will not work in the form you use when a file is opened. However, to get around that, you could place it in a Try/Catch as below so that it reads the file length whether open or closed.

Local a$ = "12345678", LE As Large
Open App.Path & "\example.dat" for Output As # 1 : Print # 1; a$ : Close # 1
Try
    Open App.Path & "\example.dat" for Input Shared As # 17 : LE = LOF(# 17) : Close # 17
Catch
    LE = LOF(# 17)
EndCatch
Close # 1
Print LE

ProgressBar OCX

Well noted: I'll update the help page(s) accordingly.

Once again, thanks for your feedback and I hope you enjoy the rest of the festive season.

[troycheek]

1. I am currently copying video files over a network, so I have plenty of time to see the progress bar update. I recently got a new router and now can copy large files without timing out or other errors, which is why I had been calling the external program TeraCopy as explained in a previous message.

2. I had completely overlooked Static local variables. I had it stuck in my head that there was no way to maintain local variables between calls and that I had to use globals all the time or pass values as an extra parameter every call. I now have to re-think some of the code I've written lately.

3. Good idea with incrementing a global Large with each sub call during FileCopy. I should have thought of that myself. Followup question: What's the use of ident% anyway? How does one even have more than one FileCopy operation running at one time? When I use FileCopy/CopyFile, program execution stops until the copy is completed.

4. I was playing around with code and when run on my system (Windows 7 Home Premium 64 bit) FileLen does seem to return a Large like it's supposed to. At least, it reported the proper size of several video files larger than _maxint.

From DOS dir command "dir k:\27*.mpg > test.txt"

Volume in drive K is Seagate Expansion Drive
Volume Serial Number is F49A-B585

Directory of K:\

12/30/2015  04:04 AM     6,044,703,866 27Dresses-14525265-0.mpg
              1 File(s)  6,044,703,866 bytes
              0 Dir(s)  2,031,565,144,064 bytes free
From inside GB32 IDE:

Dim LE as Large
LE = FileLen("K:\27*.mpg")
Print LE
Open "temp.txt" for Output As # 1
Print # 1; LE
Close # 1

Output:

6044703866
If I'm counting my decimal places correctly, that's nearly 6 GB.  Am I crazy, or is this not supposed to work? Isn't the known issue that FileLen does NOT return a Large as expected and is therefor limited to 2 GB? I realize now that I don't remember ever actually trying it before. I just took the word of the help file that it wouldn't work and worked around it.

5. Again under FileLen: "FileLen% is GFA-BASIC 16 compatible, because it returns a 32-bit integer. However, it will return the wrong result for files larger than 2 MB." Do we mean 2 GB instead of MB here?

As an aside, I was on the GFA BASIC ST Facebook page the other day, found a fellow GB32 user, and directed him here for a current help file.

[dragonjim]

3. FileCopy: ident% can be used to define the behaviour of the sub-routine depending upon what type of operation is being performed and it's inclusion means that you don't have to write separate routines to cover all eventualities - it is simply an aid to customisation and, although it must be included in the FileCopy statement if the sub-routine is referenced, can be safely ignored.

As to having more than one FileCopy operation going at one time...maybe through multi-threading, but I've never tried it. However, I am assured that it is possible.

4. FileLen: Interesting results you got with FileLen...on my old Win8/64 and new Win10/64, I still get incorrect return values with FileLen; however, as you don't seem to be so affected, I shall re-word the help file to reflect this.

5. FileLen%: Well spotted again - on testing, the limit is 2GB not 2MB. I have added a note to update the help file.

Thanks again for the feed back - keep it coming...

[troycheek]

3. I was thinking of multithreading as a way to do more than one FileCopy operation at a time, but can't think of a reason for it. I'm not much on menus and event handling, but I suppose if you put a DoEvents or similar statement in the subroutine, you could pick up a menu/mouseclick/something event and start another FileCopy in another sub? I never liked menus and event handling and the like because they messed up my old fashioned linear program flow.

4. EDIT:  I checked FileLen on another couple of systems and got inconsistent results, so I made some test cases.

S:\file01.txt              FileLen = 1073741824        per LOF = 1073741824
S:\file02.txt              FileLen = -2147483648       per LOF = 2147483648
S:\file03.txt              FileLen = -1073741824       per LOF = 3221225472
S:\file04.txt              FileLen = 4294967296        per LOF = 4294967296
S:\file05.txt              FileLen = 5368709120        per LOF = 5368709120
S:\file06.txt              FileLen = -2147483648       per LOF = 6442450944
S:\file07.txt              FileLen = -1073741824       per LOF = 7516192768
S:\file08.txt              FileLen = 8589934593        per LOF = 8589934593
S:\file09.txt              FileLen = 9663676417        per LOF = 9663676417
S:\file10.txt              FileLen = -2147483647       per LOF = 10737418241
S:\file11.txt              FileLen = -1073741823       per LOF = 11811160065
S:\file12.txt              FileLen = 12884901889       per LOF = 12884901889
The files are supposed to hold exactly the number of GB (1024 * 1024 * 1024) indicated in the file name, but I messed up somewhere and got some odd numbers.  2 GB being 1 more than _MaxInt, we can expect that an Int32 can't hold that number.  The same with 3 GB.  Yet somehow 4 and 5 GB register properly, as do 8 and 9 GB, 12 GB and probably higher.  I think this is sufficient to prove that FileLen only returns the proper value sometimes and a workaround needs to be used.

[dragonjim]

3. If you wish to try using multithreading with FileCopy, you will need to start the threads first and then call FileCopy from each thread, referencing the sub-routine in each statement (which, if I understand it correctly, is a separate thread in itself). All the usual caveats apply when using file access through multithreading, the main one being that, unless each copy operation is between drives that are not being used in any other operation, there is very little increase in performance and, sometimes, a decrease.

4. Thanks for the test results - it seems from them that GB32 is bugging out if the DWord returned for the Lo part of the FileSize is negative and just returning that; when it's positive, then the correct value is returned. I'll pass this on to Sjouke as it should be a reasonably easy fix...

[troycheek]

3. Started adding 32768 and ignoring bytes_copied% in the check_it sub when doing FileCopy of large files. Works like a charm. I've thought of a couple of ways of doing multiple FileCopy operations at once but absolutely no good reason to, so I might do it just once to prove that I can and then forget about it. Let's keep the help file mentioning that it's possible and leave the rest as an exercise for the reader.

4. I knew there was some pattern in there that I just couldn't put my finger on.

[dragonjim]

Build 9 is now out. See the download page at the top of this thread.

[dragonjim]

Build 10 is now out. See the download page at the top of this thread.

[titi66]

Bonjour 
j'ai un petit problème avec le fichier chm, je ne voie que l'index pas de texte sur le coté droit

merci de votre aide 

Thierry



Hello

I have a small problem with the file chm, I see only the index no text on the right side



Thank you for your help



Thierry

[dragonjim]

Bonjour,

The reason you can see no text on the right hand side is because Windows automatically blocks the help file when you download it.
To unblock, right click the chm file, select properties and in the pop up box that appears, look for a command button labelled "Unblock" towards the bottom of the box.
There are fuller instructions on how to unblock in the read me file which comes with the help file.

[scalion]

Hi Dragon Jim,
In first Thank's for your very helpfull Chm File.
I have a suggestion : Is it possible to add a new content in table of content named "How to..." ?
And next, you can put pages concerning for example : Copy to clipboard, calculate complex, change rtf color, etc...
I can help you if you want to writing some page of course.
Have a nice day.

[titi66]

 ça fonctionne pas

It does not work

Attachments:

[titi66]

J'ai extrait le dossier html c'est déjà ça 

merci pour l'aide


I extracted the file html it's already that



thanks for the help

Attachments:

[dragonjim]

Hi scalion.

Thank you for your comments regarding the help file.

There are three problems with maintaining the help file:

1. the large number of supported commands and functions which all need to be documented;

2. the fact that, as the original writers of GFABASIC32 are no longer contactable, sometimes the only way to find out how a command or function works (or on occasions doesn't) is through trial and error or disassembly;

3. Where to stop adding pages and sub-topics.

I have slowly started adding "How to" examples to some sections but this is not my main priority (which is ensuring content is correct and up to date) and my time is limited these days.

If you wish to write some pages of your own which you feel would be useful to other users, may I suggest adding them as topics in this forum to begin with, and if and when I get time I'll format a new page and add it to the help file.

[scalion]

Ok no worries, and thanks for your prompt answer.
In fact I had already started a help in French and I quickly realized what you say: it is a titanic work. So I stopped and I told myself that the best would be to contribute to the help in English which is already very exhaustive.
I'll do as you suggested: post topics here.
Just one thing to lighten up the work as much as possible, which file format do you prefer? Html, Rtf, or text?
Do you have a Help Page Building Chart?

I decompiled the chm with Html WorkShop and looking at the source code html I found that you use a css style in the header, including the display of syntax highlighting which is a good idea.

I know it's a lot of questions but to be short if you want I could really provide you with a directory \ howto of files html that you will only have to integrate in your directory of files html and all you will have to do will be to recompile to make it appear. I can even provide you with the list of keywords (howto.hhk) and the table of contents (howto.hhc). All in a zip file of course. What do you think ?

[dragonjim]

Hi scalion,

Please accept my apologies - I missed your reply.

Either RTF or HTML would be preferable for help pages as I can then quickly transfer them into the help file. I use a custom, self-written program to write, format and manage the help pages and this takes care of most of the CSS formatting, which as you noticed is common across all pages and makes it easier to reformat the whole file.

If you wish to send me articles, please be aware that there is a thorough vetting and editing process before anything is actually added to the file - this covers many areas but includes whether the page is worth putting in as a further difficulty not mentioned in my previous post is trying to keep the file to a manageable size. Even pages which make it through this are sometimes amended or cut, as recently happened with pages on LG32 libraries and Functions.

So, if you still wish to send me some How To files, please contact me at (deleted). This is a junk email address so please be aware I shall reply using a different one.

[scalion]

Hi DragonJim,
Have you received my mail i've just send to your email?
Thank you.

[dragonjim]

Hi Scalion,
Checked my email and no, I have not received your message.
Please try again (worth checking that you have it right - there are more 'i's than most people expect...)

[scalion]

In this case, send me an e-mail on [e-mail] and I will answer you at your personal address.
Have a good day.

[scalion]

Thank'you Now i have your mail.
I just sent you a first try and some additional info.
Good evening (here the night come ...).

[scalion]

Hi all,
Here a special help files i started to write named "GB32HowTo.chm".
In Future i hope we can add this section in the actual GFABasic Help Build 10.
For the moment it's more complicated but we discuss about with Dragon Jim.

And in fact there is not much for the moment. I still make it available to you to share.

Download here : GB32HowTo.chm (139.79 KB)

Have a nice day, see you soon.

[dragonjim]

Hi.
A new build of the help file is now available in the first entry in this post. Any comments or corrections are always welcome.