When is a handle not a handle?

(subtitled) All handles are created equal, but some handles are more equal than others.

When greating a %gr graphics region, and elsewhere, for example in OPEN_PRINTER@, a handle must be [u:fa6d91b73c]supplied[/u:fa6d91b73c]. In numerous other places, a handle is [u:fa6d91b73c]returned[/u:fa6d91b73c] from Windows. These are quite definitely not the same things. For example, the programmer-handle for %gr is quite useless when it comes to SET_MOUSE_CURSOR_POSITION@ - to locate oneself relative to (0,0) in a %gr region it is necessary to have a windows-handle obtained using %lc.

FTN95.CHM quite correctly (and clearly, I'll grudgingly admit) states that the programmer [u:fa6d91b73c]supplies[/u:fa6d91b73c] the handle for %gr and OPEN_PRINTER@ etc, but (for example) in the description of SET_MOUSE_CURSOR_POSITION@ it does not state what sort of handle is required. It is stated that if the handle has the value zero, coordinates are relative to the screen. This seems to be the case also if the handle is unrecognised - which it is likely to be if one uses the programmer-handle instead of the windows-handle.

May I suggest a note to this effect in the next version of FTN95.CHM?

Eddie

ClearWin+ provides an interface into the Microsoft Windows API. A window (or control) has a unique ID called its handle and this is supplied by the API. Many ClearWin+ routines use this handle including SET_MOUSE_CURSOR_POSITION@.

%gr is a ClearWin+ object that has an associated 'graphics block'. When ClearWin+ creates a graphics block it attaches a unique ID to the block but the user is also allowed to provide the value of the ID (via a grave modifier on %gr). I guess we ought to have a way to get the current automatic ID but we don't at the moment.

The word 'handle' is usually used to denote a unique integer that identifies a particular object within a set of similar objects with the same attributes.

I understand the point about the documentation and I do make changes from time to time when I can. But I do not have the resources nor the time to carry out a systematic update of the help files.

Paul,

On the grounds that this still causes difficulties, may I respectfully suggest that there is room for an error message if an application attempts to open a second %gr Clearwin+ object with the same programmer-supplied handle as an already open %gr object?

Since the object is a Clearwin+ object, I would have thought this was an internal matter for Clearwin+, and should therefore be possible comparatively easily.

I suppose that this also applies to %dw and %pl (new type) objects.

The documentation for %gr is very clear - up to a point. It does not state that the given handle must be unique or the areas will be muddled up:

If more than one drawing surface is to be drawn (either within one window, or on different windows) then a grave accent modifier is supplied to %gr and a third argument is required to input an integer (called a handle) that you provide. This handle is used in the subroutine select_graphics_object@ in order to select the current drawing surface.

But the documentation in FTN95.CHM for (e.g. for SET_MOUSE_CURSOR_POSITION@) still does not point out that the handle required is the Windows handle returned by %lc and not the Clearwin+ handle specified by the user for the %gr area.

Eddie

Thanks Eddie

I have added the check along the lines that you suggest but now, thinking further, I am not sure that this is always an error. There may be working programs with graphics regions and non-unique identifiers where there is no conflict. Dare we risk breaking existing code?

There are quite a number of routines that take a Microsoft HANDLE as an argument and these are listed in ftn95.chm under x64 Platform->Using Microsoft handles. Also, when I search for INTEGER(7), I get over 60 items, all of which would need reviewing.

Eddie

There may be some mileage to our adding a check within select_graphics_object@

This function returns 1 on success and zero on failure. It could be made to return an error condition when the supplied argument is not a unique identifier for the object.

Also ClearWin+ might be able to keep a record of the address of the user's graphics identifier. Then, on a call to select_graphics_object@, if the value of the identifier is not unique, its address might serve the same purpose.

Paul,

The breaking of existing code is always a problem. In this case, an early warning would prevent the spread of the issue and the 'well, it always worked before I made the last 200 changes ...' sort of post. Naturally, I respect your knowledge of the inner workings of Clearwin+, and of course, now I think about it, the call to SELECT_GRAPHICS_OBJECT@ is where a problem would start to arise. But the problem will have existed since the second or subsequent %gr was initiated with a previously defined and currently active handle.

Without a change of graphics object, graphics output continues to go to the last created %gr (I think), so multiple objects with the same handle can coexist as long as one doesn't wish to change between them, as in there is a %gr object in a dialog, which is written to but eventually closed before graphics are written to the earlier defined object that had the same handle (which is probably 0).

It is no longer a problem to me, although I did let out an exasperated gasp when I realised what was going on in the other post, which got me a rather severe look from 'er indoors.

I think we are all in your hands here.

Regarding Microsoft handles, I'm not sure that they ever need checking, but I may be wrong. The thrust of my note was that there is such a thing as a Clearwin+ handle and (a) it differs from the Windows one, and (b) enough people trip over it to make it worth thinking about how to manage that.

Eddie

Eddie

Having explored this further, I am now contemplating adding a new function like select_graphics_object@ called select_graphics_region@. This will serve the same purpose but will work with %gr and %pl and operate as a 'handle' in the way that users often assume by default.

In other words, the 'handle' will be the address of the user-supplied variable and not its value.

I have not got beyond 'contemplating'.

Dan and John,

I am an avid documentation reader, but the problem appears to me that users either do not read the documentation thoroughly or at all, or don't understand the difference if they have read it. (Or they forgot).

It does not seem to me that anyone ever got into trouble actually specifying the same handle twice, either by using the same variable, or assigning the same value (non-zero, but maybe zero) - because in that case they would have realised that the Clearwin+ handle was user-specified.

The problem primarily arises (in my view) because users imagine that the handle will be returned, like a Windows handle. They therefore use different variable names, but do not pre-set the values in each, so they all start out having the value 0.

In my view, Paul is wise not to rush in, and his contemplation phase is essential to getting the right solution. We can see a subset of the likely problems in breaking existing Fortran code, but only he can determine the risks in altering Clearwin.

My own preference would be a warning message if a new %gr (or %dw or %pl - please don't let any graphics region function differently to any other) object was created with an existing handle, with a more strongly worded message variant if the pre-existing and new handles were both 0. Paul's initial suggestion was to put the warning in SELECT_GRAPHICS_OBJECT@, because the problem only arises when we switch between %gr (etc) objects. His new suggestion is to create a parallel process.

My tentative new suggestion is to have a routine (say) SELECT_ALTERNATIVE_CLEARWIN_HANDLE_METHOD@ (MODE), where the default or MODE=0 is to do as at present and use user-supplied handles, but MODE=1 is to return a unique handle like is done with Windows handles (or vice versa). This is analogous to the option to select RGB mode when VGA was the norm.

Ultimately, however, the issue lies in the documentation and how users interact with it. FTN95.CHM is not a user instruction manual. There's nothing wrong with the current method if you know how to use it properly, and when you have that knowledge, it is simple to find justification in FTN95.CHM.

John, I suggest you think deeply about Paul's answer you highlighted in bold: when the user currently gives different handle names that are all zero, he/she doesn't think about what they contain.

Eddie

Here is the outcome of the present review. Its aim is to make things clearer and simpler and hence to avoid misunderstanding.

1. There will be a review of the documentation. Some sentences can be presented in bold font. The use of 'handle' for a graphics region can be avoided where this is not already the case.

2. A ClearWin+ check will be made on the supplied user-ID of a graphics region and an error will be generated when /UNDEF is used and when a value is not assigned.

3. There is an existing undocumented function (for use with %gr, and hence %pl) called SELECT_GRAPHICS_OBJ_BY_WINDOW@. This works like SELECT_GRAPHICS_OBJECT@ but the argument is the Windows HWND given by %hw. This will be extended so that it will also work for the HWND of the child given by %lc (so it can be used when the main window contains more than one %gr/%pl).

If these are not sufficient to settle the matter then there is one remaining option and that is to provide two new routines, one routine to get a 'proper' handle to the current graphics region when it is created and the other to select the current region using this handle when the region needs to be changed.

Thanks Paul.

Eddie

As a matter of discussion for further understanding;

• Is there a guarantee that two running programs with the same user-defined ID will not be interfering and even crashing each other?

• In how many Clearwin+ controls are using grave accent which means to use Windows defined handle?

• What else 'not a handle handle' be used besides the purpose of regular handle i.e. to be unique identifier to switch output between windows

• Was the initial choice of user defined graphics eindow handle a design mistake ? How about potential problems in future?