Standard callbacks

Solution10 in the Visual ClearWin demonstration pack illustrates standard callbacks.

Standard callbacks are callbacks that are provided by Visual ClearWin. They are defined by one of the following strings.

In order to use the clipboard for images, your main Fortran program must have the System.STAThreadAttribute attribute. This can be assigned by including the following line in your main program.

ATTRIBUTE(class="System.STAThreadAttribute",target="ROUTINE")

Standard callbacks are normally invoked by clicking on a menu item or a toolbar button. This can be programmed by extending the name of the item in the design view.

For example, if the menu item with name menuItem1 is to be used to exit from the form then the name menuItem1 is extended to menuItem1_Exit . Here an underscore is followed by the name of the callback. Similarly, if a toolbar has a collection of buttons that includes one with the name toolBarButton1, extending this to toolBarButton1_Print attaches the button to the standard Print callback.

Alternatively you can use a Fortran statement of the form:

CALL vcOnClick@(dlg, "toolBarButton1", "Print")

If you use a menu item with a Shortcut then there is no need to attach a callback that merely emulates this Shortcut.

Within a callback function you can make a direct call to a standard callback function by using a statement of the form:

CALL vcStandardCallback@(dlg, "Font")

This is useful when you want to add other instructions before or after the standard callback.

If you call a standard callback by extending the name of a standard menu item or toolbar button (or by using an extended menu) and also CALL vcOnClick@ to add your own callback, then both callbacks are executed in turn with the standard callback coming first (in the case of a menu item you can add more than one callback in addition to the standard callback).

The standard callbacks Open, Save/SaveAs and Print/PrintPreview require additional programming. The callback New may also require additional programming. For example, Open causes the standard Open file dialog to be displayed and needs a process to apply to the file selected by the user (in order words, Open requires a callback to specify what is to be done with the file). Visual ClearWin allows you to provide a suitable process by raising an event. In the case of the Open callback the event is called Open_Child and you must include a Fortran statement of the form:

CALL vcOnEvent@(dlgChild, "Open_Child", LoadFile)

This statement normally appears between vcCreateDialog@ and vcShowDialog@ statements or between vcCreateMdiChild@ and vcShow@ statements. dlgChild is the Dialog, Open_Child is the Visual ClearWin event, and LoadFile is your Fortran callback that provides the process that is to be applied to the file. Within this callback you can get the name of the file by calling vcGetStringData@(dlgChild, "#FileName") or you can call a Visual ClearWin method (such as vcLoadText@ or vcLoadImage@) that uses this name automatically.

Both the standard callbacks New and Open raise a Visual ClearWin event called Create_Child. Open raises Create_Child before Open_Child. New raises only Create_Child. In the callback that you attach to Create_Child you can interrogate either #FileName or #FileType before creating a suitable object (a certain kind of MDI child for example). #FileType provides the extension of the selected file name (e.g. "txt", "rtf", "bmp" etc.). #FileType is set to "[None]" when Create_Child is raised by a call to New.

Both Save and SaveAs raise the event called Save_Child. The callback that you provide defines the saving process. It also uses #FileName for the name of the file and this information is used internally in the Visual ClearWin method vcSaveText@.

Both Print and PrintPreview use an existing Microsoft event that you can link into using the name Print_Child. Print uses a standard Print dialog that must be provided in the design view of your form. Similarly PrintPreview uses a standard PrintPreview dialog that appears in the design view. Both types of dialog must have an attached PrintDocument component selected from the Toolbox.

In the callback that you associate with Print_Child, you can make a single call to a Visual ClearWin method such as vcPrintText@ or PrintImage@. In other cases you must work at a lower level as follows.

Print_Child automatically handles the page numbering of printed documents associated with collating and multiple copies and provides you with the number of the current page and the number of the current copy. This and other information is obtained by a Fortran statement of the form:

pageNo = vcGetIntegerData@(dlgChild, "#PageNumber")

In this context, in addition to #PageNumber you can also use: #CopyNumber, #LeftMargin, #RightMargin, #TopMargin, #BottomMargin, #Height and #Width.

The standard callbacks Exit and Close can be used to fire up a warning message when a document has been changed but not saved. This requires you to set integer data using a statement of the form:

CALL vcSetIntegerData@(dlgChild, "#Modified", 1)

Any non-zero data value will do. In the case of a Text_Box control, for example, you could respond to the TextChanged event with:

CALL vcOnEvent@(dlgChild,"text_Box1","TextChanged",OnChange)

and call vcSetIntegerData@ in the OnChange callback.

For further information see MDI applications.