Introduction to XFT

Xeffort Library

Introduction to Xeffort

Xeffort library (previously known as XFT) is used for easy building Win32 GUI applications with Compaq and Intel Visual Fortran compilers. It seamlessly integrates with Microsoft Visual Studio (.NET) IDE providing:

• | Application wizard, for quick creating of skeleton MDi, SDI or dialog-based applications
• | Handler wizard, for creation of prototypes of most-frequently used routines
• | This online help, which can be run from Visual Studio "Tools" menu

Xeffort is distributed as free, open source resource.

Xeffort is both a framework (meaning that you can build GUI applications using solely Xeffort APIs) and a library (meaning that you can call selected Xeffort routines from any Win32 application without using full set.)

Currently, Xeffort is available only for Compaq/(Intel) Visual Fortran compiler since it partially depends on some extensions, namely, integer (Cray) pointers and DEC$ metacommands. Your possible effort to port it to other compilers is welcome.

Please refer to the release notes for the latest information about Xeffort library updates.

Versions and Compatibility

Xeffort can be used in two flavors: "Lite" and "Full". "Lite" version consists of a limited set of modules which present useful functions in any kind of application without additional overhead. Currently, the following modules are provided in "Lite" flavor: XFTGDI, XFTFile, XFTMenu, XFTStrings and XFTReg. These modules can be included into your projects and compiled separately of the rest of Xeffort library.

"Full" version of the package presents a complete framework built on top of Win32 API, and it provides functions able to build an entire GUI application of moderate complexity. However, the open architecture of Xeffort enables that both - "Lite" and "Full" flavors can be used on top of existing code, regardless whether it's a console, QuickWin, dll or Win32 application - in just few steps you're able to bind Xeffort windows with your existing application windows and add new functionality.

Xeffort Full version carries along an independent set of interfaces for Win32 functions and structures so that it is not dependent on DFWIN upgrades throughout CVF development, thus it should work on any CVF version.

Xeffort Full version is most easily used as a static library (Xeffort.lib) along with a set of modules (*.mod). Xeffort Lite modules can be used as separate .f90 files inserted into your projects.

Name Change

Since mid-August 2005, Xeffort has undergone a name change from "XFT". There are several reasons for that, mostly of "commercial" nature:

• | There already exists another (and more popular) XFT library (X FreeType interface library)
• | Domain XFT.com was already taken
• | XFT was acronym for rather stupid name of "eXtended Fortran Types". That was actually retrofitted to the acronym, which... never mind...
• | It sounds better. and is similar to the old name
• | It can be retrofitted to acronym of "eXtremely Easy Fantastic gui's in FORTran"
• | Its developers have put an Xtreme effort to assemble it.

Xeffort is backward-compatible with XFT. That means that all old codes using XFT can be built without change. Users are encouraged to use name "Xeffort" for new applications.

Important Notes

Main development of Xeffort is done on CVF6.6C. You are encouraged to upgrade your compiler to the highest version available. CVF updates are available at HP Visual Fortran Updates.

Intel Visual Fortran 8/9 Users: Minimal required version of IVF is 8.1.021. When building, make sure your application is built with default calling convention and default string argument passing (Project Properties/Fortran/External Procedures category). For compatibility with CVF 6.0/6.1, Xeffort routines do not have defined !DEC$ATTRIBUTES DEFAULT (as they should).

Compaq Visual Fortran 6.0/6.1 Users: To use Xeffort, you should rebuild the Xeffort library after installation; open <XFTRoot>\Xeffort.dsp file in the Visual Studio and build the release configuration.

License

Xeffort is available under the following license:

You are free to use the code for both commercial and non-commercial use. The code is provided as-is without warranties. You are free to distribute and modify this source code provided that the list of original author(s) remains untouched and your revisions are indicated as such. Contributions are welcome.

Author

Jugoslav Dujic

University of Novi Sad, Yugoslavia

Institute for Power, Electronics and Telecommunications

Fruskogorska 11, Novi Sad

jdujic@uns.ns.ac.yu

Xeffort.com


Xeffort Release Notes

Release Notes (1.2.24-25)

ATTENTION CVF 6.0/6.1/6.5 USERS: CVF 6.0 and 6.1 is not supported anymore. Try installing XFT 1.2.14 and rebuild the sources (open Program Files\Xeffort\Xeffort.dsp and build Release configuration.)

ATTENTION IVF USERS:Minimal required version of IVF is 9.0. When building, make sure your application is built with default calling convention and default string argument passing (after all items) (Project Properties/Fortran/External Procedures category). For compatibility with CVF 6.0/6.1, Xeffort routines do not have defined !DEC$ATTRIBUTES DEFAULT (as they should).

The source consists of the following files:

.\Source\Xeffort.f90 - Main Xeffort Module

.\Source\XFT.f90 - XFT Module for compatibility with old XFT codes

.\Source\XFTAPI.f90 - INTERFACEs to Win32 API Routines

.\Source\XFTAPIty.f90 - TYPEs and PARAMETERs of Win32 API

.\Source\XFLOGM2.f90 - XFLOGM Module v. 2

.\Source\XFTApp.f90 - XFTApp Module

.\Source\XFTcaret.f90 - XFTCaret Module

.\Source\XFTCtrl.f90 - XFTCtrl Module

.\Source\XFTDialog.f90 - XFTDialog Module

.\Source\XFTExtra.f90 - Module of supplemental routines

.\Source\XFTIntrf.fi - INTERFACEs to user-defined handlers

.\Source\XFTListView.f90 - ListView controls

.\Source\XFTFile.f90 - XFTFile Module

.\Source\XFTGDI.f90 - XFTGDI Module

.\Source\XFTMDI.f90 - XFTMDI Module

.\Source\XFTMenu.f90 - XFTMenu Module

.\Source\XFTMenuTy.f90 - XFTMenuTy Module

.\Source\XFTNotify.f90 - INTERFACEs to X_NM_ macros

.\Source\XFTPrint.f90 - XFTPrint Module

.\Source\XFTReg.f90 - XFTReg Module

.\Source\XFTTypes.f90 - Xeffort-specific TYPEs and PARAMETERs

.\Source\XFTToolbar.f90 - XFTToolbar Module

.\Source\XFTWnd.f90 - XFTWnd Module

.\Source\XFTStrings.f90 - XFTStrings Module

.\Source\EXCheckStack.f90 - EXCheckStack routine

.\Source\EXEpilog.f90 - Dummy XEpilog routine

.\Source\EXGetCmdData.f90 - EXGetCmdData routine

.\Source\EXWinMain.f90 - WinMain for Xeffort Applications

.\Source\XYPlotMod.90 - X-Y Plotting module

The package is downloadable from www.xeffort.com/xeffort/home.htm.

Revision History

= fixed

= added

= changed

JD = Jugoslav Dujic

MG = Mike Gaitens

GC = Greg Charlton

Xeffort 1.2.25 (November 18 2009.)

18.11.2009. | JD | Release for IVF 11.0 / 11.1 and VS2008
14.04.2008. | MG | XMenuSetLog returned .FALSE. on success (XFTMenu.f90).
14.04.2008. | JD | Fixed several issues related with toolbar's dragging and docking. (XFTToolbar.f90)
14.04.2008. | JD | XToolbarSet(CTL_STYLE) was breaking toolbar's dockability. Fixed (XFTToolbar.f90)

Xeffort 1.2.24 (April 08 2008.)

08.04.2008. | JD | Added tentative (untested) support for Visual Studio 2008.
07.04.2008. | MG | Fixed XCreateMetafile (forgotten Char(0)-termination) (XFTExtra.f90)
26.01.2008. | MG | Added XYPlotComplex to plot complex arrays in magnitude and phase-angle form. Unassociated elements in an XYCURVE array are no longer considered an error. Fixed some minor bugs in the XYPlot module having to do with custom margins and custom labels on log axes.
21.01.2008. | MG | Modified XFTToolBar to allow multiple rows of buttons in a toolbar, and to not overlay the status bar (if any). Added XToolbarRemoveAllButtons
08.01.2008. | MG | Added XSystemPath, XEnvironmentString to XFTFile.f90

Xeffort 1.2.23 (December 19 2007.)

19.12.2007. | JD | Setup now supports IVF 10.1. For Visual Studio PPE and 64-bit, it will install the Xeffort.lib, module files and XWizard.exe; user should append the LIB and INCLUDE path manually.
18.12.2007. | MG | XToolbarRemoveButtons worked only when bById is both present and .FALSE. (XFTWnd.f90).
13.12.2007. | MG | Added semi-documented FXNotifySysReturnValue, which can be used from the command callback to return a non-default (1) value from the window procedure (XFTWnd.f90).
13.12.2007. | MG | When a ListView row is selected from code, it did not automatically scroll. (XftCtrl.f90)
25.11.2007. | MG | Added XYPlot X-Y plotting package. It is capable of producing either a quick plot or a presentation-quality plot.
10.11.2007. | MG | Added XCreateMetaFile, XCloseMetaFile.
08.11.2007. | MG | Imported XNumber, XSqueeze, XTimerStart, XTimerStop, XUserWarn, XUserInfo, XUserStop, XUserAsk, XPlaySound, XSetDialogFocus, XOneInstance, XPickFont, XPickCtlFont, XPickColor from the Xeffort Extras site. (XFTextra.f90)
05.11.2007. | MG | Limited output of XView2Client to 2**27 to agree with GDI "page" limits. (XFTGDI.f90)
02.11.2007. | JD MG | Fixed font resource leak in XSetFont (XFTGDI.f90)
30.10.2007. | MG | Added XNowAt, XMoveRelative, XLineToRelative to XFTGDI.f90.
16.10.2007. | JD | Changed value of toolbar CCS_DOCKABLE to avoid conflict with CCS_ADJUSTABLE
06.09.2007. | JD | Fixed return value from XScrollbarSet (XFTWnd.f90)

Xeffort 1.2.22 (August 02 2007.)

08.06.2007. JD Minor aesthetic change in XFTAPIty.f90 back in June had broken XMessageBox. Fixed.

Xeffort 1.2.21 (June 12 2007.)

08.06.2007. | JD | Setup now supports IVF 10. Application wizards for all installations are stored in a separate directory "AppWizard" under installation root directory. Due to new VF10 registry nomenclature, reinstallation of Xeffort may be required after VF updating.
14.02.2007. | JD | Added SW_TOP, SW_BOTTOM, SW_TOPMOST and SW_NOTOPMOST flags to XSetWindowPos (XFTWnd.f90)
05.12.2006. | JD | xWnd and xWndDeact arguments to WM_MDIACTIVATEHANDLER now match the docs (same arguments were passed to child window being deactivated) (XFTWnd.f90)
11.09.2006. | JD | Added sWorkingDir argument to XCreateShortcut. (XFTFile.f90)
25.07.2006. | JD | XShorten hangs in endless loop with certain strings. (XFTStrings.f90)
17.07.2006. | GC | XCtlGetInt did not work for CTL_RANGEMAX and CTL_RANGEMIN for spin (updown) controls (XFTCtrl.f90)
17.07.2006. | GC | XCtlSetInt did not return success for CTL_RANGEMAX for spin controls, and CTL_RANGEMIN for sliders. (XFTCtrl.f90)

Xeffort 1.2.20 (May 30 2006.)

30.05.2006. | JD | XCtlGet for classic listview control returned zero for integer item with i0, j0 or k0 format. Fixed. (XFTListView.f90)
30.05.2006. | JD | When a classic listview control was resorted, XCtlSetItem and XCtlGetItem worked with a wrong item (the one in display order rather than the one in original order). (XFTListView.f90)
30.05.2006. | JD | When a virtual listview control was resorted, XLVUpdate for specified selection did not redraw the correct item due to wrong ordering. (XFTListView.f90)
30.05.2006. | MG JD | Subsequent setting of CTL_FORMAT for a listview control appended the columns. Now, it erases all the contents instead (XFTListView.f90)
23.05.2006. | JD | Uninstallation tasks implemented in InnoSetup script. XUninstall*.exe is not necessary anymore.
23.05.2006. | JD | Added support for IVF9.1 (tested) and VS2005 (untested). The setup is modified so that it will bind Xeffort with all VF/VS combinations it encounters (not only for newest as before).
25.04.2006. | MG | Due to a uninitialized variable bHandled in FXWndProc, menus and scrolling (and maybe also few other things) would ocasionally stop working. (XFTWnd.f90)
21.04.2006. | GC JD | Added support for CTL_KILLFOCUS and CTL_GAINFOCUS for combo boxes, list boxes and drop-down lists (XFTCtrl.f90/XFTWnd.f90)
07.04.2006. | MG | XDeleteMenuItem did not work at all. Fixed. (XFTMenu.f90)
03.04.2006. | MG | XRegRead for real argument caused an access violation. (XFTReg.f90)

Xeffort 1.2.19 (February 27 2006.)

27.02.2006. | JD | The package is built with /fpscomp:logicals. Some APIs on Win9x (notably, IsWindow) return a positive non-1 value for BOOL, which was misinterpreted by Xeffort as .FALSE. (Xeffort.dsp). However, as result, non-standard expressions as "if(aLogical.EQ..TRUE.)" may cease to behave - use "if(aLogical)" instead.
27.02.2006. | JD | When the XW_FRAME is closed, Xeffort automatically posts WM_QUIT message. However, that causes all subsequent message loops to quit, so XModalDialog and XMessageBox will also return immediately. Instead, these function will now operate normally, but "store & retrieve" WM_QUIT. XProcessMessages is not changed, i.e. it will return immediately as before. (XFTDialog.f90)
01.11.2005. | JD | Fixed bug in CVF MDI skeleton code where = > should be used instead of = in xChild=XMDIGetActive(). (IVF was OK).
01.11.2005. | JD | WM_LBUTTONDOWN on a native Xeffort window now does SetFocus by default. That affects WM_MOUSEWHEEL handling, as well as WM_KEY* handling, as the keyboard focus will now be directed as users expect. (XFTWnd.f90)
01.11.2005. | MG | iScanCode argument to WM_KEY* handlers extended by 1 bit to match the documentation. (XFTWnd.f90)
01.11.2005. | MG | Added XF2C. (XFTStrings.f90)
31.10.2005. | JD | Added bPopup optional argument to XLoadMenu. (XFTMenu.f90)

Xeffort 1.2.18 (October 26 2005.)

26.10.2005. | MG | Added "Keyboard and Character Codes" page to documentation.
26.10.2005. | JD | Partially fixed situation where libifcorert.dll is not in PATH. XWizard now works from VS menu, but uninstallation will not be complete.
25.10.2005. | JD | CTS_CLIENTEDGE and CTS_WINDOWEDGE for XCtlCreate now work (XFTCtrl.f90)
24.10.2005. | JD | WM_MOUSEWHEEL should not do the Xeffort default scrolling for subclassed windows (XFTWnd.f90)
24.10.2005. | JD | Integer values of edit controls (same as *etDlgItemInt) now supported as CTL_STATE. CTL_SELECTION must be specified explicitly (XFTCtrl.f90)
24.10.2005. | JD | Introduced CTL_APPEND constant to mean the same as zero/DLG_ADDSTRING (XFTCtrl.f90)
24.10.2005. | JD | PXCreateBitmap_File now returns .FALSE. when it fails (XFTGDI.f90)
21.10.2005. | JD | XRegWriteChar will now correctly store entire untrimmed string; before the fix, it stored trimmed version but indicated full length, resulting in ERROR_MORE_DATA on retrieval (XFTReg.f90)
21.10.2005. | JD | XMenuGetChar did not retrieve menu item title because of forgotten MENUITEMINFO.cch member; fixed. (XFTMenu.f90)
20.10.2005. | JD | Added XMenuSetItem/XMenuGetItem, but not published (XFTMenu.f90)
17.10.2005. | JD | Added replacement possibility to XInsertMenuItem (XFTMenu.f90)
17.10.2005. | JD | Added generic interface and documentation for XDeleteMenuItem (XFTMenu.f90)
17.10.2005. | JD | Added XMENU_ID and XMENU_INDEX features for XMenuGet (XFTMenu.f90)
17.10.2005. | JD | Added SEQUENCE keyword to all Xeffort types so they could be included in common blocks (XFTTypes.f90)
11.10.2005. | JD | XCtlGetChar fills the output string with blanks even when it fails. Some old CVF (ShowFont) codes depended on that feature (XFTCtrl.f90)

Xeffort 1.2.17 (October 06 2005.)

06.10.2005. | JD | Fixed bug in AppWizard where Back or Next buttons could cause VS to crash if "Dialog-based application" is selected.
06.10.2005. | JD | "Concepts" page added into help file and several overviews (XFTCtrl, XFTWnd, XFTDialog, Getting Started) enhanced.
05.10.2005. | JD | Selection of items in list-boxes using "old" (dflogm) style fixed to match dflogm one (XFTCtrl.f90).
03.10.2005. | JD | Fixed default IDOK/IDCANCEL callback for dialogs so that it propagates WM_QUIT correctly when the dialog is XW_FRAME (XFTWnd.f90).
03.10.2005. | JD | Added capability of appending text to edit controls and retrieving lines from multi-line edit controsl (XFTCtrl.f90).
26.09.2005. | JD | Added XProcessMessages (XFTApp.f90).
26.09.2005. | JD | Added XEnableWindow (XFTWnd.f90).
26.09.2005. | JD | Extended documentation for message handlers.

Xeffort 1.2.16 (September 26. 2005.)

26.09.2005. | JD | Added sUserButton argument to XMessageBox (XFTDialog.f90).
26.09.2005. | JD | Setup for IVF 8.1 did not install the AppWizard correctly. Fixed. Presence of multiple IVF versions (8.1+9.0) with various combinations of VS.NET 2002/2003 can still be an issue; in that case, the Xeffort is (allegedly) installed only on the "newest" combination.
26.09.2005. | JD | Due to a change of function return type (XLOWORD) in 1.2.15, command handlers for IDs greater than 32767 ceased to work. That included default menu IDs in Wizard-generated code. Fixed (hopefully for good). (XFTWnd.f90)
23.09.2005. | JD | DLGINIT resources are now parsed. That means that combo/list data entered in "Data" fields of the resource editor now appear in the dialog. (XFTDialog.f90::PXParseDlgInit)
22.09.2005. | JD | Added XSetCanvas and XGetCanvas (XFTWnd.f90). WM_*SCROLL, WM_SIZE and WM_PAINT default handling changed accordingly.
18.09.2005. | JD | Fixed wrong appearance of icon in XMessageBox, as well as occasional text truncating (XFTDialog.f90)
18.09.2005. | JD | XCtlGetChar truncated last character if the supplied string is of exact necessary length. (XFTCtrl.f90)

Xeffort 1.2.15 (August 31 2005.)

26.08.2005. | JD | Changed WM_KEYUP and WM_KEYDOWN prototypes (XFTWnd.f90).
23.08.2005. | JD | Added enhanced XFTStrings.
23.08.2005. | JD | Added XMessageBox.
11.08.2005. | JD | Accelerator keys in MDI skeleton code made working by fixing nCode from 1 to 0 (FXWindowProc::XftWnd.f90).
11.08.2005. | JD | Fixed the bug in XCreateWindow where windows with non-default class (i.e. PRESENT(sClassName)) were not bound. (XFTWnd.f90)
11.08.2005. | JD | Added WM_MDIDESTROY handler (XFTWnd.f90). XWizard.f90 updated accordingly and Wizard-generated code for MDI application updated to catch for case where there are no child windows.
11.08.2005. | JD | Package renamed to Xeffort. All sources reorganized.

1.2.14 (August 08 2005.)

08.08.2005. | JD | Setup modified to (allegedly) support all VS.NET (2002/2003) and IVF (8.1/9.0) combinations (but untested).
05.08.2005. | JD | Changed X_MENU structure and added appropriate code so that the main menu bar is properly redrawn after change (XFTMenu.f90).
05.08.2005. | MG JD | Added XBeep and XMessageBeep routines (XFTApp.f90).
01.08.2005. | MG | Handled the case of file extension given as .* in XGetSaveFile (XFTFile.f90).
01.08.2005. | MG | Added optional bExtend argument to XTextOut and XGetTextExtent (XFTGDI.f90).
01.08.2005. | MG | Fixed type of xWndAfter argument of XSetWindowPos routine to agree with documentation (XFTWnd.f90).
01.08.2005. | MG | Implemented forgotten XPostMessage (XFTWnd.f90).
01.08.2005. | MG | Added XStdCursor. (XFTWnd.f90)
01.08.2005. | MG | Added XScrollWindow. (XFTGDI.f90)
01.08.2005. | MG | Added XFTCaret module.
01.08.2005. | JD | Added .NET Application Wizard for IVF Release.
09.07.2005. | JD | CVF AppWizard enhanced with "Additional Features" tab.
09.07.2005. | JD | Added WM_DROPFILES handler (XFTWnd.f90 and XWizard.f90).
09.07.2005. | JD | Added code comments and return values for XWizard-generated code (XWizard.f90).
09.07.2005. | JD | Implemented WM_QUERYENDSESSION (XFTWnd.f90).
09.07.2005. | JD | Implemented bClip argument to XSetViewport and added XSetClipping routine (XFTGDI.f90).
07.07.2005. | JD | Added XWrite routine (XFTGDI.f90).
04.07.2005. | MG JD | Fixed wrong WM_KEYUP prototype in XWizard and documentation.
04.07.2005. | MG JD | Fixed various documentation errors. (XFTGDI)
19.06.2005. | JD | Added XSetScaling routine. (XFTGDI)

1.1.12 (June 2005.)

03.06.2005. | JD | XMenuGetLog retrieved inverse result for checked/unchecked state (XMENU_STATE). Fixed. (XFTMenu)
01.06.2005. | JD | Added XFTToolbar.f90. Documentation appended.
31.05.2005. | JD | PXCreateBitmap_Rsrc now properly returns .FALSE. when it fails (XFTGDI.f90).
12.02.2004. | JD | Removed CS_HREDRAW and CS_VREDRAW styles from XFT Window class (XFTWnd.f90)
10.01.2004. | MG | Added XCtlGetPos routine. Documentation appended. (XFTCtrl.f90)
20.12.2004. | MG | Added calls to FXLV_BackMap, FXLV_FwdMap (XFTCtrl).
20.12.2004. | MG | Added extra argument to XCtlGetInt for ListView control selections. (XFTCtrl).
20.12.2004. | MG | Added CTL_COLUMNORDER processing. (XFTCtrl).
20.12.2004. | MG | Added LVS_EX_HEADERDRAGDROP style to ListView control. (XFTListView::FXLV_Init)
20.12.2004. | MG | Added to XLV_OnColumnClick to maintain selections across sort (XFTListView).
20.12.2004. | MG | Additions to PXLV_ParseItem, PXLV_SortCallback, and PXLV_VirtualSortCallback to accommodate T_SYSTEMTIME variables (XFTListView).
20.12.2004. | MG | Added subroutine PXDateTime; also FXLV_BackMap and FXLV_FwdMap to insure row communication w/ pgmr is in terms of the original usertype array (XFTListView).

1.1.11 (November 30. 2004.)

30.11.2004. | JD | Added ListView support both in XFTCtrl and XFLOGM2.0. Documentation appended.
15.11.2004. | JD | XCtlGetArray now accepts only a POINTER array. This fixes potential sizing problems, but the user application must be careful to DEALLOCATE it.
15.11.2004. | JD | XSetCursor fixed (missing LOWORD test for lparam in XFTWnd::FXWindowProc/WM_SETCURSOR).
12.11.2004. | JD | Fixed reallocation of xWnd%xCtl array (UBOUND was required instead of SIZE; XCTL property had to be reassigned) in XFTCtrl::XCtlCreate.>
12.11.2004. | JD | XCtlCreate did not work within dialogs, because return value from FXWndProc should have been returned via DWL_MSGRESULT, not directly.

1.0.10 (October 5. 2004.)

05.10.2004. | JD | WORKING IVF8.1 VERSION RELEASED
05.10.2004. | JD | Static owner-drawn controls fixed (forgot to apply copying of DRAWITEMSTRUCT%hDC into X_DC%hDC in XFTWND::FXCtlCallback).
05.10.2004. | JD | All internal uses of XGetWindow() fixed to use a temporary pointer variable, in order to workaround 245385 IVF8.1 bug (which is partially fixed as of IVF 8.1.021).
04.10.2004. | JD | Fixed MDI Wizard skeleton code which produced a memory leak on child window destruction, because UD%xWnd% members were not deallocated properly. XFreeWindow made public (to be documented one day).
04.10.2004. | JD | Fixed AppWizard bug where premature "Finish" button has caused an exception. AppWizard now retrieves custom settings in the registry, sharing entries with XFT Wizard.
04.10.2004. | JD | Fixed WM_NCDESTROY handler, which has never been called because window binding was released prematurely (on WM_DESTROY) (XFTWnd::FXWindowProc)
04.10.2004. | JD | Fixed XMDIDestroy, which has never worked due to wrong intent(OUT) & interchanged WM_MDIDESTROY params (XFTMDI::XMDIDestroy)
04.10.2004. | JD | Fixed MDI applications, which were screwed since 1.0.6 due to changed window-binding behaviour (XFTWnd::FXWindowProc)

1.0.9 (August 17. 2004.)

17.08.2004. | JD | Change in 1.0 RC6 has screwed Window menu of MDI applications. Fixed.
17.08.2004. | MG | Added optional ID argument to XCreateWindow. Fixed the documentation.
16.08.2004. | MG | Support for BS_CHECKBOX (as opposed to BS_AUTOCKECKBOX) added to XFTCtrl::FXResolveClassName
16.08.2004. | JD | Fixed WM_COMMAND/WM_NOTIFY forwarding for dialogs with embedded dialogs or controls containing other controls.

1.0.8 (July 23. 2004.)

22.07.2004. | JD | Due to (stillborn) introduction of XFT for IV8, registry values changed from HKLM/Software/XFT to HKLM/Software/XFT/CVF6. It might lead that it is not uninstalled properly (but I've seen far worse). Also, setup file name is changed to XFT_CVF6.exe
22.07.2004. | JD | Fixed XFT Wizard's prototype for XFLOGM-based handler (Dlg instead of xWnd)
22.07.2004. | JD | Added IMPLICIT NONE check-box to XFT Wizard
22.07.2004. | JD | XFT Wizard generates correct calls to XSetHandler etc. functions instead of CALL
22.07.2004. | JD | New bAppModal argument to XModalDialog fixed :-D
12.07.2004. | JD | New bAppModal argument to XModalDialog.
12.07.2004. | MG | XModalDialog now obeys WM_QUIT message by exiting from the subroutine and posting message up until it reaches the main message loop
08.07.2004. | JD | Dialogs now "identify" themselves via lParam of WM_EXITDLG message. With previous behaviour, closing an owned modeless dialog via [X] or XExitDialog would cause exit of the parent dialog as well.
08.07.2004. | MG | Fixed XCtlGetArray for multiple&extended-selection list-boxes
08.07.2004. | MG | Fixed XCtlGetInt to allow retrieval of multiple-selection list-boxes using "compatibility" method
08.07.2004. | JD | When there's no requested selected item, XCtlGetInt returns .FALSE. for multiple-selection list-boxes (DFLOGM still don't behave that way, but that is consistent with documentation on "Control properties" help pages)
29.06.2004. | JD | Just another GetFocus problem -- callbacks for simple combo boxes were not called because the ComboLBox (list part) window has focus (XFTWND:FXCtlCallback)

1.0 RC7 (June 26. 2004.)

26.06.2004. | JD | Module XFTMenuTy moved to separate file.
26.06.2004. | JD | X_NM_ macros fixed (EXGetCmdData.f90) and moved to MODULE XFTNotify.
18.06.2004. | MG | Removed GetFocus() test for button WM_COMMAND handlers which caused that the callback is not invoked when the button is "pressed" via Enter or Esc.
18.06.2004. | JD | Dialogs without IDCANCEL button now close by default by pressing [X] button, returning IDCANCEL to DlgModal.

1.0 RC6 (May 27. 2004.)

27.05.2004. | JD | Fixed nasty bug, discovered by Mike Gaitens, related with too late association of X_WINDOW structure with a dialog (XFTDialog:XLoadDialog and XFTWND:FXWindowProc). The bug was exposed as misalignment of dialog's client area when XP Themes are enabled.
27.05.2004. | JD | Fixed CTL_HELP/DLG_HELP callbacks. Behaviour tested with new XContextHelp sample.

1.0 RC5 (May 24. 2004.)

24.05.2004. | JD | Added Mike Gaitens's suggestion of allowing DLG_SELECTION for XCtlSetChar for combo boxes.
21.05.2004. | JD | DlgSetChar, DlgSetInt, DlgSetLog made PUBLIC in XFLOGM2.
14.05.2004. | JD | Revised stack overflow problem "solved" in RC4 screwed up combo box callback. Hopefully fixed, but I'm open-minded.
13.05.2004. | JD | Fixed CTL_COLOR and CTL_BKCOLOR for progress bars
13.05.2004. | JD | Fixed bug with callback for trackbars and updowns never being invoked

1.0 RC4 (May 11. 2004.)

11.05.2004. | JD | Behaviour of DLG_NUMITEMS synchronized with the one from DFLOGM. Now DLG_NUMITEMS retains the existing items insread of deleting them.(XFTCtrl::XCtlSetInt). Note that LBS_SORT style affects ordering of items.
11.05.2004. | JD | Fixed DLG_KILLFOCUS callback (XFTWnd::FXCtlCallback)
11.05.2004. | JD | Fixed the issue with possible stack overflow when DlgSet is called from an edit-control callback (XFTWnd::FXWndProc/WM_COMMAND).
11.05.2004. | JD | Fixed bug with retrieving selection from LBS_MULTIPLESEL list box. DlgGet now returns zero if index>no. of selected items (XFTCtrl::XCtlGetInt)
10.05.2004. | JD | Fixed bug that scrollbar controls don't "stick" when dragged using mouse. (XFTWnd::FXWndProc)
04.05.2004. | JD | Fixed bug with combo boxes where CTL_SELECTION when invoked from CTL_SELCHANGE callback returns the "old" value instead of "new".
04.05.2004. | JD | "XFT Application Wizard" should go to "Common\MSDev98\Bin\IDE" directory instead of ...\Templates.

1.0 RC3 (Apr 6. 2004.)

17.03.2004. | JD | XSizeWindow was behaving the same as XMoveWindow. Fixed.
17.03.2004. | JD | Added XGetWindowMenu
17.03.2004. | JD | Fixed wrong XSetWindowMenu entry in help
17.03.2004. | JD | Deleted spurious iStyle argument of XGetWindowStyle
17.03.2004. | JD | Fixed reversal of iX2 and iY2 arguments to WM_PAINT_Handler

1.0 RC2 (Feb 12. 2004.)

11.02.2004. | JD | Added missing declarations in XFTMenu.f90 and XFTFile.f90 for purpose of compiling lite version on older CVF's.
06.02.2004. | JD | Added forgotten DLG_FONT and DLG_PAGE into online documentation, XFLOGM chapter
06.02.2004. | JD | Deleted spurious iColor argument from XGetPixel (copypasto :-))
05.02.2004. | JD | Lite version of XFTGDI did not compile under CVF 6.0 due to stupid declaration of DFWINTY:T_LOGFONT%lfFaceName. Fixed using preprocessor & TRANSFER.
02.02.2004. | JD | WM_HSCROLL did not pass correct value of nPos (XFTWND:FXWindowProc). That caused WM_HSCROLL_Handler to misbehave. (VSCROLL was OK all the time)
02.02.2004. | JD | nFlag in WM_VSCROLL and WM_HSCROLL enhanced to pass SB_VERT and SB_HORZ respectively (XFTWND:FXWindowProc)
27.01.2004. | JD | Unininitialized bHandled variable in WM_SIZE block of (XFTWND:FXWindowProc) fixed. That caused random calling of WM_SIZE handler
24.01.2004. | JD | Added CS_OWNDC into XWindow class creation (EXWinMain)
24.01.2004. | JD | When a child dialog has WS_EX_CONTROLPARENT, WM_COMMAND messages were not sent to it but to its parent. WM_COMMAND forwarding is now fixed (XFTWND:FXWindowProc).
23.01.2004. | JD | Fixed bug that XWM_CREATECONTROL = WM_EXITDLG.
20.01.2004. | JD | Added XSetWindowStyle/XGetWindowStyle

1.0 RC1 (Jan 15. 2004.)

15.01.2004. JD XFT Library is developed and tested using CVF 6.6C. It is supposed to be compilable with any CVF 6.x compiler. 5.0D is not supported anymore, but should be compilable as well with minor changes (!DEC$ATTRIBUTES NO_ARG_CHECK is one that I know of). The setup will continue only if CVF 6.x is present.


Xeffort Installation

Installation

The setup installs the following items and modifies the following registry keys:

Installation for CVF 6

File | Meaning
<XRoot>/BinCVF/XWizard.exe | Xeffort Wizard, used to ease writing of handler routines
<XRoot>/BinCVF/Xeffort.chm | This help file
<XRoot>/LibCVF/Xeffort.lib | Xeffort Library code. In order to use Xeffort Library Full, you must add Xeffort.lib into Project/Settings/Link or insert it in the project using Project/Add to Project/Files
<XRoot>/IncludeCVF/*.mod | Module-definition (.mod) files for Xeffort Modules. Setup program also appends this directory to Visual Studio Tools/Options/Directories/Include files, so there's no need to extend your include paths if building from VS IDE. These files are created using CVF 6.6C. If you use a 6.0 or 6.1 compiler you have to rebuild the library (Release Configuration) by opening provided Xeffort.dsp file.
<XRoot>/Source/*.f90 | Xeffort Library source files. If you want to use Xeffort Lite version, copy appropriate files from this folder into your project directory
<XRoot>/Xeffort.dsp | CVF project file for building Xeffort.lib from sources
<VSRoot>/Common/ MSDev98/Template/ Fortran Xeffort Application.* | Xeffort AppWizard for easy creation of startup sources.

Registry Key | Meaning
<VSKey>\Build System\Components\Platforms\Win32 (x86)\Directories\Include Dirs | Append <XRoot>\IncludeCVF directory
<VSKey>\Build System\Components\Platforms\Win32 (x86)\Directories\Library Dirs | Append <XRoot>\LibCVF directory
<VSKey>\Build System\Components\Platforms\Win32 (x86)\Directories\Path Dirs | Append <XRoot>\BinCVF directory
<VSKey>\Build System\Components\Platforms\Win32 (x86)\Directories\Source Dirs | Append <XRoot>\Source directory
<VSKey>\Tools\numTools | Add two more items for Xeffort Wizard and Xeffort Help
<VSKey>\Tools\<*>#<numTools+1> | Append Xeffort Wizard to the list in VS Tools menu
<VSKey>\Tools\<*>#<numTools+2> | Append Xeffort Help to the list in VS Tools menu

where

<VSRoot> is Visual Studio installation directory (by default C:\Program Files\Microsoft Visual Studio)

<XRoot> is Xeffort Installation directory (by default <VSRoot>\Xeffort)

<VSKey> is Visual Studio HKCU Key (HKCU\Software\Microsoft\DevStudio\6.0)

Installation for IVF 8/9/10

File | Meaning
<XRoot>/BinIVF/XWizard.exe | Xeffort Wizard, used to ease writing of handler routines
<XRoot>/BinIVF/Xeffort.chm | This help file
<XRoot>/BinIVF/DFORRT.dll | CVF 6.6B Fortran runtime dll.
<XRoot>/LibIVF/Xeffort.lib | Xeffort Library code. In order to use Xeffort Library Full, you must add Xeffort.lib into Project/Settings/Link or insert it in the project using Project/Add to Project/Files
<XRoot>/LibIVF/XFT.lib | Dummy XFT Library for compatibility with old XFT projects.
<XRoot>/IncludeIVF/*.mod | Module-definition (.mod) files for Xeffort Modules. Setup program also appends this directory to Visual Studio Tools/Options/Directories/Include files, so there's no need to extend your include paths if building from VS IDE.
<XRoot>/Source/*.f90 | Xeffort Library source files. If you want to use Xeffort Lite version, copy appropriate files from this folder into your project directory
<XRoot>/Xeffort.vfproj | IVF solution file for building Xeffort.lib from sources
<XRoot>/AppWizard/XeffortAppWizNet/* | Implementation files of Xeffort application wizard
<XRoot>/AppWizard/<VSver>/ XeffortAppWiz.* | Xeffort application wizard .vsz and .vsdir files, binding the wizard into "New project" Visual Studio dialog

Registry Value | Meaning
<VSKey>\Intel Fortran\VFToolOpt\ <VFVer>\<VFVer>\IA32_IA32\IncludeDir | Append <XRoot>\IncludeIVF directory to the user-specific include path
<VSKey>\Intel Fortran\VFToolOpt\ <VFVer>\<VFVer>\IA32_IA32\LibDir | Append <XRoot>\LibIVF directory
<VFKey>\<VFVer>\IA32\IncludeDir | Append <XRoot>\IncludeIVF directory to the default include path
<VFKey>\<VFVer>\IA32\LibDir | Append <XRoot>\LibIVF directory to the default include path
<VSKey>\External Tools\ToolNumKeys | Add two more items for Xeffort Wizard and Xeffort Help
<VSKey>\External Tools\ <*>#<numTools+1> | Append Xeffort Wizard to the list in VS Tools menu
<VSKey>\External Tools\ <*>#<numTools+2> | Append Xeffort Help to the list in VS Tools menu
<VSKey>\NewProjectTemplates\ TemplateDirs\{B68A201D-CB9B-47AF-A52F-7EEC72E217E4}\2 | Add the path to Xeffort application wizard, so that Visual studio

where

HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0\Intel Fortran\VFToolOpt\100\100.025

<VSRoot> is Visual Studio installation directory (by default C:\Program Files\Microsoft Visual Studio .NET)

<XRoot> is Xeffort Installation directory (by default C:\Program Files\Xeffort)

<VSKey> is Visual Studio HKCU Key (HKCU\Software\Microsoft\VisualStudio\7.0, 7.1 or 8.0)

<VFKey> is Intel Visual Fortran HKLM key (HKLM\Software\Intel\Compilers\Fortran\)

<VFVer> is Intel Visual Fortran version (90, 91 or 100)


Getting Started

Getting Started

Understanding the Xeffort Library Concepts

If you are familiar with native Win32 API programming, you will probably recognize the patterns used in Xeffort library as wrappers which make many aspects of Win32 API easier to use.

If you're familiar with dialog programming using DFLOGM, or QuickWin programming, you can imagine the Xeffort library as an enhancement of the concept. The main application window can be viewed as a main dialog, in which you can create other windows or controls. However, callbacks (handlers in Xeffort terminology) can be defined for a plethora of events (instead of only control callbacks in DFLOGM, or menu and mouse callbacks in QuickWin), having the application behavior under firmer control of the programmer.

If you're not familiar with either of the above, keep on reading; Xeffort is not so difficult to use once you get accustomed to concepts of event-driven programming.

Suggested Reading

In any case, consult the brief concepts page to get an idea of what's in Xeffort library first. After reading this page, you can proceed by creating your own Xeffort application using Xeffort AppWizard. Best, start with a dialog-based application because they're simplest to develop. Introductory pages of XFTDialog and XFTCtrl modules describe how to deal with dialogs and their controls.

When you decide it is time to go for more powerful applications, you can start with simple SDI applications generated by the AppWizard. Introductory pages of XFTWND module are, admittedly, not the easiest reading in the world, but they describe the most fundamental issues in Windows GUI programming. Especially, Window Messages Overview, although rather difficult to grab, discusses the underlying mechanisms of event processing in Windows. If you cannot understand everything, don't give up; take a look at Xeffort samples and get back to these pages occasionally.

Xeffort Lite

If you want to use one of modules from Xeffort Lite version (XFTGDI, XFTFile, XFTMenu, or XFTReg), you have to add appropriate .f90 file from <XFTRoot>\Source into your project (by copying or direct inclusion), and USE corresponding module from the code that requires it. In addition, you must define preprocessor symbol XLITE, otherwise you will get compile-time errors (by defining XLITE, the code in above-mentioned modules is "isolated" from its dependencies in the rest of Xeffort library). Most easily, you can type XLITE in Project/Settings/Fortran/Predefined preprocessor symbols (/define:XLITE compiler switch); alternatively, you can ensure that !DEC$DEFINE XLITE is the first line in appropriate Xeffort source file.

Xeffort Full

To create a full-blown Xeffort application, you have to write a XInit function first. Xeffort Library routines are accessible by USEing module Xeffort from your code; also, you have to link with Xeffort.lib in Project/Settings/Link. Within XInit, you should create main application window, called XW_FRAME, using XCreateWindow; as a shortcut, one of XCreateSDIApp, XCreateMDIApp, or XCreateDialogApp will do it for you. Next, you can define main application's menu by drawing it in VS Resource Editor and load it using XLoadMenu. The next step is to write your callback routines (command handlers) which will respond to menu commands, and to register them using XSetCommand.

By default, Xeffort windows are not painted, and probably the next task is to draw appropriate image on main application's window (in case of a SDI application) or MDI child windows (in case of a MDI application). You should write a WM_PAINT message handler, containing drawing code, and register it using XSetHandler. Drawing usually starts with erasing the background via XFillViewport; see routines in XFTGDI module for other drawing functions. Note that non-trivial SDI applications usually have a separate child window dedicated for drawing, which fills in frame's client area; such design eases the handling of scrollbars, status bar, and toolbars; in this case, you should create it using XCreateWindow and specifying WS_CHILD as a style; to size it correctly, write a WM_SIZE handler for the frame window and adjust layout of all child windows there according to frame window's size. On WM_SIZE you can also adjust frame or child window's scrollbars.

Most of the tasks above are automated by Xeffort AppWizard (select "Fortran Xeffort Application" in File/New/Projects VS Menu). It generates skeleton code for simple SDI, MDI, or dialog-based applications. Xeffort AppWizard places the code in MODULEs, encouraging modularization and encapsulation of your code.

An application often requires that some of dialog boxes are launched, typically as response to menu commands. You can design your dialogs in VS resource editor, and load and display them using XFTDialog routines. Controls within these dialogs are managed using routines from module XFTCtrl.

If your application is meant to work with files, you can provide menu items such as Open, Save, and Save As. You can find helper routines in XFTFile module.

In order to preserve settings, such as window layout or any options user can customize, between subsequent invocations, you should store them as variables in system registry after your program exits, and restore them (usually in XInit) using one of XFTReg routines.

Happy programming!


Concepts

Concepts

This page describes some basic concepts of Windows programming and their implementation in Xeffort library.

Program Structure

A typical console Fortran application usually reads data from a file or other source, performs computation and writes data to screen, file or printer. On the way, it may stop to ask user a few questions and, depending on response and/or on structure of input data it continues execution in some branch. That can be expressed by a linear flow chart.

This approach cannot be applied to Windows application, which continuously interacts with the user. A Windows application is better represented as a black box which changes its state whenever user performs some action, like choosing a command from a menu, typing a letter or moving the mouse. Here, state should be understood as a set of programmer-defined variables (and their visible represents on screen) which change their values depending on user's actions. Apart from direct user's actions, the program may change its state whenever something other happens in the system, for example, when system resolution changes, or when screen saver starts. All user actions, along with changes that occur in the system for whatever reason, are referred to as events. Every event under Win32 is directed to a window.

Thus, a Windows application just barely has a main program in the usual sense. Structure of a Xeffort application typically consists of many small routines which handle events:

  • An entry-point routine is referred to as XInit in Xeffort. This routine is first called by the Xeffort framework, and its task is to perform all initialization and create at least one window - the main application window. In Xeffort, this window is always referred to as XW_FRAME. Apart from main window creation, the XInit routine typically loads application's menu, icon, accelerators and other resources and sets up some message handlers for the main window.

  • A number of message handlers. Message handler is a programmer-defined routine which is automatically invoked when an event, such as menu or control activation, mouse click, window resizing etc. occurs in the application. The most common message handlers are command handlers and control handlers, and only they are typically used in a dialog-based application. Applications whose main window is not a dialog will also typically set up a WM_PAINT handler, which renders its graphic output in main or child windows, and a WM_SIZE handler, which should rearrange or refresh application's windows when the main window is resized.

  • An optional termination routine, invoked when the application is about to exit. It can be implemented by handling WM_NCDESTROY message for the main window, or by writing a XEpilog routine.

Windows

A window is the fundamental object of all Win32 GUI programming; even the name of the operating system stresses their importance. In Xeffort, a window is represented by a TYPE X_WINDOW. XFTWnd module is used for handling of windows.

Dialogs and Controls

Dialogs are a special case of windows; their most important characteristics is that their layout is designed in resource editor rather than directly from Fortran source code. XFTDialog module is used for loading, displaying in destroying dialogs. Other than these routines, all routines from XFTWnd are also applicable to dialogs.

Xeffort supports source-level compatibility with Intel/Compaq module IFLOGM/DFLOGM through module XFLOGM. XFLOGM is actually just a thin wrapper around XFTDialog and XFTCtrl modules, mostly containing just renames of Xeffort routines.

A control is a window that used to obtain a specific piece of information from the user, such as the name of a file to open or the desired point size of a text selection. Although controls are windows, their behavior is so well predefined that it is seldom necessary to treat them as such; thus, it is not necessary to define X_WINDOW variables for them. Module XFTCtrl is used for handling of controls.

Menus and Toolbars

Menus and toolbars are special kinds of controls (actually, for historic reasons a menu is not a control nor a window in Win32 terminology, but it acts much like one) which let the user access frequently used commands of your application. They are handled by XFTMenu and XFTToolbar modules, which have mutually similar interfaces.

Drawing and Printing

Once you get hold of a device context (DC) - a drawing canvas - drawing in Xeffort is pretty easy and intuitive. It is handled by XFTGDI module, where you can find many routines for graphic primitives. However, Win32 mechanism of preparation of drawing in windows is not exactly intuitive; see a thorough discussion under WM_PAINT entry.

XFTGDI routines are also applicable to printer DCs; however, you should use routines from XFTPrint module to prepare the printing and ultimatively receive printer (paper) device context to draw onto.

Registry

The registry is a system-defined database that applications and system components use to store and retrieve configuration data. If your application needs to persist small amounts of data (especially, user's preference), the registry is the right place to do it. Interfaces of XFTReg routines resemble Fortran file operations in a certain amount.


XeffortWizard

Xeffort Wizard

Xeffort Wizard is an auxiliary tool which heps you prototyping Xeffort Message handlers and XFLOGM/DFLOGM control callbacks quickly and reliably. Xeffort Wizard generates code for installing the handler/callback and the body of the handler/callback routine:

  • In Xeffort Window edit box, user should type the name of the X_WINDOW (or DIALOG) variable representing the Xeffort Window to handle. XW_FRAME stands for frame window in a Full Xeffort application.

  • In Message to handle list, a message for which the handler is registered should be selected. Windows messages are listed without WM_ prefix. There are also additional four entries:

    - <Command> entry creates a handler for a WM_COMMAND (WM_NOTIFY) message, typically coming from a menu item. This handler is installed using XSetCommand routine.

    - <Other> entry creates a default handler, i.e. a handler for WM_ messages not directly supported by Xeffort. This handler is installed using XSetHandler routine.

    - <XFLOGM> entry creates a handler for XFLOGM or DFLOGM control callbacks. This callback is installed using DlgSetSub routine.

    - <XFTCTRL> entry creates a handler for controls created by XFTCtrl. This handler is installed using XCtlSetSub routine.

  • In Separator dropdown list, you can select the separator which will be automatically prepended to the routine body. Separators =, - and * are selectable; item From File lets you select an ASCII file (max. 1 kB) whose contents are automatically inserted (e.g. your custom function header comment). The file can be browsed using the button with explorer-like icon next to Separator list.

  • In Keywords list you can select whether you prefer Fortran keywords uppercase or lowercase.

  • In Indent body spin edit you can select the horizontal indentation of routine body.

  • If Description comments checkbox is checked, additional comments about purpose of the routine and its arguments are inserted.

  • If Use Xeffort checkbox is checked, line "USE Xeffort" is inserted in routine heading. This is normally not required if the code is within a MODULE that uses Xeffort.

  • If IMPLICIT NONE checkbox is checked, line "IMPLICIT NONE" is inserted in routine heading. This is normally not required if the code is within a MODULE that specifies IMPLICIT NONE.

  • ID edit box is available only for <Command>, <XFLOGM> and <XFTCTRL> types of handlers. These handlers require an ID of the control, which should be typed here.

  • In Set Handler read-only edit-box, the line used to invoke required registering Xeffort Routine (XSetHandler, XSetCommand, DlgSetSub, XCtlSetSub) is generated automatically. This line can be copied to clipboard using the "Copy" button next to it.

  • In Handler Routine read-only edit-box, an empty body for handler routine, with a correct prototype, is generated. This routine can be copied using "Copy" button next to it and pasted into your code.

The recommended convention for naming of the handler routines is:

  • For message handlers: xWnd_OnMessageName
    where xWnd is the name of X_WINDOW variable, and MessageName is the name of the message code (without WM_ prefix)

  • For command and control handlers: xWnd_OnControl

    where xWnd is the name of X_WINDOW variable, and Control is the name of the control identifier (without ID*_ prefix)


XFTApp Overview

XFTAPP Overview

XFTAPP module contains basic functions for dealing with application's overall setup in framework of Xeffort full library. Routines from XFTAPP should be called only when your application is native Xeffort application, i.e. initialized by XInit routine.

Reference


XFTApp Reference

XFTApp Reference

Overview

Basic Application Framework

XInit

XCreateDialogApp

XCreateSDIApp

XCreateMDIApp

XEpilog

XProcessMessages

XOneInstance

Miscellaneous

XLoadAccelerators

XGetInstance

XBeep

XMessageBeep

XPlaySound

XPickColor

XPickFont

XPickCtlFont

XTimerStart

XTimerStop


XInit

XInit

Overview Reference

XInit is programmer-defined function which is called by Xeffort Library on Xeffort application startup. In XInit function, necessary initialization should be performed, such as loading settings from the registry, loading data from files, and creating main (and other) application window(s), which can be done by means of XCreateWindow routine or one of XCreate*App routines listed below.

LOGICAL
FUNCTION XInit(szCmdLine, nCmdShow)
!DEC$ATTRIBUTES ALIAS: "_XINIT@12":: XInit
CHARACTER(*), INTENT(IN):: szCmdLine
INTEGER, INTENT(IN)::      nCmdShow

Arguments

szCmdLine
 String specifying the command line for the application, excluding the program name.

nCmdShow
Specifies how the main application window is to be shown. This parameter can be one of the SW_ values listed in description of XShowWindow routine.

Return Value

The function should return .TRUE. if the startup was performed successfully and the execution should continue. If the function returns .FALSE., the application is terminated. (Returning .FALSE. can be also useful for applications which aren't meant to create any windows or process messages).

Remarks

If XInit is placed in a module, it must be properly aliased as _XINIT@12 to avoid linking errors.

See Also

XCreateSDIApp, XCreateMDIApp, XCreateDialogApp, XEpilog


XCreateSDIApp

XCreateSDIApp

XCreateSDIApp function creates a basic framework for a SDI (Single Document Interface) application, i.e. it creates main application window with WS_OVERLAPPEDWINDOW style and associates XW_FRAME pointer with it.

LOGICAL FUNCTION XCreateSDIApp(xMenu, sCaption, idIcon,
nCmdShow, iStyle, iExStyle)

TYPE(X_MENU), OPTIONAL, INTENT(INOUT)::  xMenu
CHARACTER(*), OPTIONAL, INTENT(IN)::     sCaption
INTEGER, OPTIONAL, INTENT(IN)::          idIcon
INTEGER, OPTIONAL, INTENT(IN)::          nCmdShow
INTEGER, OPTIONAL, INTENT(IN)::          iStyle
INTEGER, OPTIONAL, INTENT(IN)::          iExStyle

Arguments

[xMenu]
X_MENU structure previously loaded with XLoadMenu, representing the main window menu. If absent, the window is created without the menu.

[sCaption]
 Window caption. If absent, the window has no caption.

[idIcon]
Identifier of the window icon resource, located in the applications .exe file, which will be displayed in the left corner of the caption bar, taskbar, and Alt+Tab popup. The icon should contain both 16x16 and 32x32 versions; if one is absent, the other is emulated. If this argument is absent, the window is created with Windows' default icon (white window with blue caption).

[nCmdShow]
One of SW_ constants described in XShowWindow entry. Specifies how the window is to be initially shown. If absent, the window is created with WS_VISIBLE style.

[iStyle]
 A combination of window styles for the frame window. Should contain at least a WS_OVERLAPPED or WS_POPUP flag. If absent, the default is WS_OVERLAPPEDWINDOW+WS_CLIPCHILDREN.

[iExStyle]
 A combination of extended window styles for the frame window. If absent, the default is WS_EX_APPWINDOW.

Return Value

The function returns .TRUE. if successful, otherwise .FALSE.

Remarks

This function may be called only from programmer-defined XInit function. In all other contexts, it will fail and return .FALSE.

See Also

XInit, XCreateMDIApp, XCreateDialogApp


XCreateMDIApp

XCreateMDIApp

XCreateMDIApp function creates a basic framework for a MDI (Multiple Document Interface) application, i.e. it creates main application window with WS_OVERLAPPEDWINDOW style and associates XW_FRAME pointer with it. Then, it creates MDI Client window, and associates XW_MDI pointer with it.

LOGICAL FUNCTION XCreateMDIApp(xMenu, iWindowIndex, sCaption, &
                               idIcon, nCmdShow)

TYPE(X_MENU), INTENT(INOUT)::            xMenu
INTEGER, INTENT(IN)::                    iWindowIndex
CHARACTER(*), OPTIONAL, INTENT(IN)::     sCaption
INTEGER, OPTIONAL, INTENT(IN)::          idIcon
INTEGER, OPTIONAL, INTENT(IN)::          nCmdShow

Arguments

xMenu
 X_MENU structure previously loaded with XLoadMenu, representing the main window menu.

iWindowIndex
Index of Window menu in the menu xMenu. Window menu is used by the system to display the list of opened MDI child windows, as well as Tile and Cascade menu items.

[sCaption]
 Window caption. If absent, the window has no caption.

[idIcon]
Identifier of the window icon resource, located in the application's .exe file, which will be displayed in the left corner of the caption bar, taskbar, and Alt+Tab popup. The icon should contain both 16x16 and 32x32 versions; if one is absent, the other is emulated. If this argument is absent, the window is created with Windows' default icon (white window with blue caption).

[nCmdShow]
One of SW_ constants described in XShowWindow entry. Specifies how the window is to be initially shown. If absent, the window is created with WS_VISIBLE style.

Return Value

The function returns .TRUE. if successful, otherwise .FALSE.

Remarks

This function may be called only from programmer-defined XInit function. In all other contexts, it will fail and return .FALSE.

See Also

XInit, XCreateSDIApp, XCreateDialogApp


XCreateDialogApp

XCreateDialogApp

XCreateDialogApp function creates a basic framework for a dialog-based application, i.e. it loads main application dialog and associates XW_FRAME pointer with it. The function internally calls XLoadDialog, but the XInit function should call XModelessDialog itself to display the dialog and start the application.

LOGICAL FUNCTION XCreateDialogApp(idDialog, xMenu, idIcon)

INTEGER, INTENT(IN)::                 idDialog
TYPE(X_MENU), OPTIONAL, INTENT(IN):: xMenu
INTEGER, OPTIONAL, INTENT(IN)::      idIcon

Arguments

idDialog
Identifier of main dialog's resource template stored in application's .exe file.

[xMenu]
 X_MENU structure previously loaded with XLoadMenu, representing the main menu of the dialog. If absent, the dialog is created without the menu.

[idIcon]
Identifier of the icon resource, located in the application's .exe file, which will be displayed in the left corner of the dialog's caption bar, taskbar, and Alt+Tab popup. The icon should contain both 16x16 and 32x32 versions; if one is absent, the other is emulated. If this argument is absent, the window is created with Windows' default icon (white window with blue caption).

Return Value

The function returns .TRUE. if successful, otherwise .FALSE.

Remarks

This function may be called only from programmer-defined XInit function. In all other contexts, it will fail and return .FALSE.

See Also

XInit, XCreateSDIApp, XCreateMDIApp, XFTDialog Overview


XEpilog

XEpilog

XEpilog is optional programmer-defined function which is called by Xeffort Library when the application is about to exit. When the XEpilog function is called, no windows exist anymore. XEpilog can be used to perform custom cleanup, such as closing open files and handles, writing into registry and similar.

SUBROUTINE XEpilog()
!DEC$ATTRIBUTES ALIAS: "_XEPILOG@0":: XEpilog

Remarks

If XEpilog is placed in a module, it must be properly aliased as _XEPILOG@0 in order to be called. If absent, no linking error will occur as Xeffort supplies a dummy XEpilog routine.

See Also

XCreateSDIApp, XCreateMDIApp, XCreateDialogApp


XProcessMessages

XProcessMessages

The XProcessMessages function runs a message loop. It enables the messages to be processed, and message handlers called. Optionally, it can wait for one or more synchronization objects (process, thread, event, mutex or other handles).

As described in Window Messages Overview, any message processing code should be brief, as other messages can not be processed while the current handler is being executed. When this condition can not be satisfied, use this routine to temporarily yield control to other message handlers before continuing.

Depending on the value of bModal argument, XProcessMessages can be modal or modeless. In modeless form, the function returns immediately after the input messages are processed. A modeless message loop is used when the application needs to perform a long-lasting calculation, in order to have user input correctly processed and windows repainted while the calculation is performed. In modal form, the function does not return until condition in iExitMsg or hSyncEvents is satisfied. A modal message loop is used when application needs to stop executing the current routine until a specified event occurs (e.g. use a normal window as if it is a modal dialog).

INTEGER FUNCTION
XProcessMessages(bModal, iExitMsg, hSyncEvents, bWaitAll)

LOGICAL, OPTIONAL, INTENT(IN):: bModal
INTEGER, OPTIONAL, INTENT(IN):: iExitMsg(:)
INTEGER, OPTIONAL, INTENT(IN):: hSyncEvents(:)
LOGICAL, OPTIONAL, INTENT(IN):: bWaitAll

Arguments

[bModal]
If .TRUE., specifies that the function will not return until any of messages in iExitMsg array is posted, or a WM_QUIT message is posted (indicating that the application should quit), or one of hSyncEvents is signalled.

If .FALSE., specifies that the function will return immediately after all the messages accumulated in the message queue are processed (or one of messages in iExitMsg array is encountered).

[iExitMsg]
An optional array of message codes which will cause the routine to exit. Specified message codes are not processed, i.e. their handlers, if any, will not be called. WM_QUIT message causes the routine to exit regardless.

[hSyncEvents]
An array of synchronization objects (handles of change notification, console input, events, jobs, mutexes, processes, semaphores, threads, and/or waitable timers). Presence of this argument makes sense only if bModal is .TRUE.. If present, the function will exit if any (or all) of objects becomes signalled. Use this argument when you need e.g. execute another process or thread and wait until it is completed, but still need to process your own messages. (A thread or process handle is signalled when the thread or process exits)

[bWaitAll]
If .FALSE. (default), the function will return when any of hSyncEvens is signalled. If .TRUE., the function will return when all of hSyncEvents become signalled. If hSyncEvens is not present, this argument is ignored.

Return Value

If bModal is .FALSE., and the function has processed all the messages from the queue, the return value is zero.

If the function returned because it encountered WM_QUIT or any of iExitMsg messages, the return value is code of the message which caused it to quit.

If the function returned because one of hSyncEvents is signalled, the return value is negative index of the corresponding handle in hSyncEvents.

Remarks

This routine can invoke other message handlers. That can sometimes result in a recursive call to itself, or other undesired effects. For example, if the calling routine is invoked using an "Execute" button, and user presses the button for the second time while OnExecute handler is not completed, that event will be processed when XProcessMessages is called, resulting in a recursion which could crash the application. Also, if some of invoked handlers launches a modal dialog, this routine will not exit until the dialog is dismissed. The application should take care to disable user interface features which can be harmful in order to prevent such effects.

Other routines which contain a modal message loop are XModalDialog and XMessageBox. These routines disable the owner window, though, so the possibility of such effects is minimal.

The "main" application's message loop is contained in Xeffort startup code (EXWinMain routine). When a WM_QUIT message arrives, XProcessMessages will repost it, so that it ultimatively arrives to the main message loop resulting in termination of the application. The application will not be exited, however, until all messages from the queue arriving in the meantime have been processed. By default, closing the XW_FRAME window causes a WM_QUIT to be generated.

Examples

To enable window redrawing while executing a long calculation, use modeless form of XProcessMessages:

bSt = XSetCommand(XW_FRAME, IDC_EXECUTE, XW_FRAME_OnExecute)

...

!=========================================
SUBROUTINE XW_FRAME_OnExecute(xWnd, idCmd, nCode)

TYPE(X_WINDOW):: xWnd
INTEGER, INTENT(IN):: idCmd
INTEGER, INTENT(IN):: nCode

!Disable its own menu item to prevent recursive call:
bSt = XMenuSet(xMenu, idCmd, .FALSE., XC_ENABLE)

DO i = 1,1000000

!Heavy number crunching here

...

iSt = XProcessMessages()
END DO

END SUBROUTINE XW_FRAME_OnExecute

To launch a normal window with modal behaviour, use the modal form. You have to post a special message to indicate that the modal loop should be terminated. Alternatively, you can create an Event object using CreateEvent API, put its handle into hSyncObjects, and call SetEvent when you want to terminate the modal loop.

INTEGER, PARAMETER:: WM_EXIT_OUTWINDOW = WM_APP + 1

!=========================================
SUBROUTINE XW_FRAME_OnLaunchWindow(xWnd, idCmd, nCode)

TYPE(X_WINDOW):: xWnd
INTEGER, INTENT(IN):: idCmd
INTEGER, INTENT(IN):: nCode

TYPE(X_WINDOW):: xOutWnd

bSt = XCreateWindow(xOutWnd, XW_FRAME, WS_POPUP.OR.WS_OVERLAPPEDWINDOW.OR.WS_VISIBLE, &
"My Window", 0, 0, 0, 1000, 800)
!The XW_FRAME should be disabled to achieve full modality:
bSt = XEnableWindow(xWnd, .FALSE.)

!Set a handler to post WM_EXIT_OUTWINDOW message
bSt = XSetHandler(xOutWnd, WM_DESTROY, xOutWnd_OnDestroy)

iSt = XProcessMessages(.TRUE., (/WM_EXIT_OUTWINDOW/))
bSt = XEnableWindow(xWnd, .TRUE.)

END SUBROUTINE XW_FRAME_OnExecute
!=========================================
LOGICAL FUNCTION xOutWnd_OnDestroy(xWnd)

TYPE(X_WINDOW):: xWnd

INTEGER:: iSt

iSt = XPostMessage(xWnd, WM_EXIT_OUTWINDOW, 0, 0)
xOutWnd_OnDestroy = .FALSE.

END FUNCTION xOutWnd_OnDestroy

To launch Notepad modally and process your messages, use CreateProcess API and wait for PI%hProcess in XProcessMessages:

TYPE(T_STARTUPINFO):: SI
TYPE(T_PROCESS_INFORMATION):: PI

SI%cb = SIZEOF(SI)

SI%dwFlags = 0

iSt = CreateProcess(NULL, 'Notepad.exe'C, NULL, NULL, FALSE, 0, NULL, NULL, SI, PI)

iSt = XProcessMessages(.TRUE., hSyncEvents=(/PI%hProcess/))

iSt = CloseHandle(PI%hProcess)
iSt = CloseHandle(PI%hThread)

See Also

XSendMessage, XPostMessage, Window Messages Overview

Wrapped APIs

GetMessage, PeekMessage, MsgWaitForMultipleObjects, TranslateMessage, DispatchMessage, IsDialogMessage, TranslateAccelerator, TrasnlateMDISysAccel


XOneInstance

XOneInstance

XOneInstance limits an application such that only one copy of it can be run at a time. That is, if the application is running and the user attempts to launch the program again, the original instance of the program is brought to the foreground and the would-be second copy exits.

LOGICAL FUNCTION XOneInstance (UNIQUE, DOOMED)
CHARACTER(*), INTENT(IN) :: UNIQUE
LOGICAL, OPTIONAL, INTENT(OUT) :: DOOMED

Arguments

Unique
A required non-blank text string that signifies the program, such as the program name. The string should not contain backslash (\) characters.

[Doomed]
If Doomed is returned .false., this is the only current instance of the program. If Doomed is .true., a PostQuitMessage has been issued so the program will exit as soon as the message loop is processed, in which case further setup is pointless and the most expedient action is to exit XInit returning .true.

Return Value

.TRUE. if successful; .FALSE. denotes failure, in which case Doomed (if present) will also be .false. See Remarks for required position.

Remarks

An XOneInstance call must follow a successful call to either XCreateSDIApp, XCreateDialogApp, or XCreateMDIApp. That is, it belongs in an Application Wizard generated XInit function file.

One reason for employing XOneInstance is to preclude multiple copies of a program attempting to simultaneously manipulate a single file.

Module

XFTApp.f90


XLoadAccelerators

XLoadAccelerators

XLoadAccelerators function loads and applies the accelerator table resource from the application's .exe file. A keyboard accelerator (or, simply, accelerator) is a keystroke or combination of keystrokes that generates a WM_COMMAND message for an application. Accelerators are used as shortcuts (such as Ctrl+O for "Open") for certain commands. (But they should not be mixed with mnemonics, which present underlined letters in menus and controls, allowing Alt+letter access from the keyboard. Mnemonics do not require an accelerator table.)

LOGICAL FUNCTION XLoadAccelerators(idAccelTable, hModule)

INTEGER, INTENT(IN)::             idAccelTable
INTEGER, OPTIONAL, INTENT(IN)::   hModule

Arguments

idAccelTable
Identifier of accelerator-table resource to be loaded, contained in the application's .exe file or another module specified by hModule.

[hModule]
 Handle of the module containing the accelerator-table resource, as returned from XGetInstance, LoadLibrary, or GetModuleHandle APIs. If absent, the accelerator-table is loaded from the .exe file that started the current process.

Return Value

The function returns .TRUE. if successful, otherwise .FALSE.

Wrapped APIs

LoadAccelerators

See Also

XGetInstance


XGetInstance

XGetInstance

XGetInstance function returns a module handle (also known as instance handle) for the specified module if the file has been mapped into the address space of the calling process.

INTEGER FUNCTION XGetInstance(sModuleName)

CHARACTER, OPTIONAL, INTENT(IN):: sModuleName

Arguments

[sModuleName]
 String that contains the name of the module (either a .DLL or .EXE file). If the filename extension is omitted, the default library extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension. The string does not have to specify a path. The name is compared (case independently) to the names of modules currently mapped into the address space of the calling process. If absent, the instance handle of main application's executable is returned.

Return Value

If the function succeeds, the return value is a handle to the specified module. If the function fails, the return value is zero.

Wrapped APIs

GetModuleHandle


XBeep

XBeep

Plays a tone on the internal speaker/oscillator.

SUBROUTINE XBeep (iHz, imsec)

INTEGER, OPTIONAL, INTENT(IN)::  iHz
INTEGER, OPTIONAL, INTENT(IN)::  imsec

Arguments

[iHz]

Frequency of the tone. If omitted, or outside of the allowed range of 37 to 32767 Hz, then 440 cycles/second is assumed.

[imsec]

Duration of the tone in milliseconds. If omitted, 50 msec is assumed.

See Also

XMessageBeep, XPlaySound

Wrapped APIs

Beep

Module

XFTextra.f90


XMessageBeep

XMessageBeep

The MessageBeep function plays a waveform sound of certain type. The sound is defined system-wide in Sounds applet of the Control Panel.

SUBROUTINE XMessageBeep(iType)

INTEGER, INTENT(IN)::  iType

Arguments

uType
Specifies the sound type, as identified by an entry in the [sounds] section of the registry. This parameter can be one of the following values:
Value | Sound
0xFFFFFFFF | Standard beep using the computer speaker
MB_ICONASTERISK | SystemAsterisk
MB_ICONEXCLAMATION | SystemExclamation
MB_ICONHAND | SystemHand
MB_ICONQUESTION | SystemQuestion
MB_OK | SystemDefault

See Also

XBeep, XPlaySound

Wrapped APIs

MessageBeep

Module

XFTextra.f90


XPlaySound

XPlaySound

XPlaySound function plays a given audio .WAV file. This function is a generic name encompassing the following three interfaces:

Form 1: To play a .wav file:

LOGICAL FUNCTION XPlaySound (sFile)

CHARACTER(*), INTENT(IN)::      sFile

Form 2: To play a .wav file that has been compiled as a resource:

LOGICAL FUNCTION XPlaySound (ID, hModule)

INTEGER, INTENT(IN)::           ID
INTEGER, OPTIONAL, INTENT(IN):: hModule

Form 3: To stop playback of any .wav file.

LOGICAL FUNCTION XPlaySound ()

Arguments

sFile

Fully qualified path of the audio wave file. Only files in .wav format are supported.

ID

Integer identifier of the resource.

[hModule]

Handle of the module (.exe or .dll) which contains the resource. If absent, the wave resource is loaded fromthe executable which started the current process. See XGetInstance for more information.

Remarks

Form 1 and Form 2 attempt to queue the .wav file for playback and return immediately (i.e., they never wait for the playback to complete). Note however, that these forms will not interrupt a playback in progress. If the audio hardware is not idle when these forms are called, they immediately return .false. If you wish to circumvent this behavior, insure the hardware is available by first using Form 3 to instantly stop any existing playback.

Return Value

.TRUE. if successful; otherwise .FALSE. because either the the .wav file or resource could not be found, or the playback hardware was busy.

See Also

XBeep, XMessageBeep

Wrapped APIs

PlaySound

Module

XFTextra.f90


XPickColor

XPickColor

XPickColor function displays the Windows color selection dialog.

LOGICAL FUNCTION XPickColor (xWnd, iRGB)

TYPE(X_WINDOW)::         xWnd
INTEGER, INTENT(INOUT):: iRGB

Arguments

xWnd
X_WINDOW structure of the parent window of the color selection dialog.

iRGB

Composite integer varible specifying red, green, blue intensities. Initial contents are presented as a default color selection. Contains the user's selected custom color value upon output.

Return Value

If the user closes the color selection dialog with the OK button, the return value is .TRUE. If the user Cancels the dialog, the return value is .FALSE.

Wrapped APIs

ChooseColor

Module

XFTextra.f90


XPickFont

XPickFont

XPickFont function displays the Windows font selection dialog to allow your user to pick a font. XPickFont returns the font characteristics required as input to XSetFont to set a font to be used for subsequent text output for a given DC. XPickFont can also return the user's text color choice.

  LOGICAL FUNCTION XPickFont
(xWnd, xDC/hDC, sFontName, iHeight, &
iEscapement, iWidth, iWeight, &
bItalic, bUnderline, bStrikeOut, iFontColor)

TYPE(X_WINDOW)::
xWnd
TYPE(X_DC)/INTEGER,
INTENT(IN):: xDC/hDC
CHARACTER*(*), INTENT(OUT)::     sFontName
INTEGER, INTENT(OUT)::           iHeight
INTEGER, OPTIONAL, INTENT(OUT)::  iEscapement
INTEGER,
OPTIONAL, INTENT(OUT)::  iWidth
INTEGER, OPTIONAL, INTENT(OUT)::  iWeight
LOGICAL, OPTIONAL, INTENT(OUT)::  bItalic
LOGICAL, OPTIONAL, INTENT(OUT)::  bUnderline
LOGICAL, OPTIONAL, INTENT(OUT):: bStrikeOut
INTEGER, OPTIONAL, INTENT(OUT)::  iFontColor

Arguments

xWnd
X_WINDOW structure of the parent window of the font selection dialog.

xDC (or zero)

If the device X_DC structure is known, e.g., returned by XCreateDC, use it as this argument. Otherwise enter 0 (zero) in which case the font selection dialog will be limited to screen fonts.

sFontName

Name of the selected typeface, such as "Arial" or "Times New Roman". The length of sFontName should be 32 characters.

iHeight
 Character height of the selected font, in pixels.

[iEscapement]
 Angle of the font, in tenths of degrees, relative to the horizontal. Typically returned as zero.

[iWidth]

Average width of a character, in pixels. Usually returned zero to indicate the default font width.

[iWeight]

Weight of the font, in range of 0 to 1000. Generally it will equal one of the following constants:

Value | Weight
FW_DONTCARE | 0
FW_THIN | 100
FW_EXTRALIGHT | 200
FW_ULTRALIGHT | 200
FW_LIGHT | 300
FW_NORMAL | 400
FW_REGULAR | 400
FW_MEDIUM | 500
FW_SEMIBOLD | 600
FW_DEMIBOLD | 600
FW_BOLD | 700
FW_EXTRABOLD | 800
FW_ULTRABOLD | 800
FW_HEAVY | 900
FW_BLACK | 900

[bItalic]

If returned .TRUE., specifies that italic version of the font is requested.

[bUnderline]

If returned .TRUE., specifies that the font is underlined.

[bStrikeOut]

If returned .TRUE., specifies that the font is strike-out.

[iFontColor]

Composite integer representing red, green, blue intensities of the selected text color.

Return Value

If the user closes the font selection dialog with the OK button, the return value is .TRUE. If the user Cancels the dialog, the return value is .FALSE. and the arguments are unchanged.

Wrapped APIs

ChooseFont

Module

XFTextra.f90


XPickCtlFont

XPickCtlFont

XPickCtlFont function displays the Windows font selection dialog to allow your user to pick a font for controls. XPickCtlFont returns a compact text specification of the selected font in the format required by the CTL_FONT iAction argument to XCtlSet.

XPickCtlFont can also return a user's text color choice, which can be used with the CTL_COLOR action of XCtlSet .

LOGICAL FUNCTION XPickCtlFont (xWnd, sCtlFont, iFontColor)

TYPE(X_WINDOW)::                 xWnd
CHARACTER*(*), INTENT(OUT)::     sCtlFont
INTEGER, OPTIONAL, INTENT(OUT):: iFontColor

Arguments

xWnd
X_WINDOW structure of the parent window of the font selection dialog.

sCtlFont

Returned font specification string in the same format as for SETFONT QuickWin function, i.e. "t'Arial'h8eui" means "8 point Arial bold italic underlined". Only t, i, e, u, h, w descriptors are used. The maximum length of sCtlFont is 44 characters, so dimension it accordingly

[iFontColor]

Composite integer representing red, green, blue intensities of the selected text color.

Return Value

If the user closes the font selection dialog with the OK button, the return value is .TRUE. If the user Cancels the dialog, the return value is .FALSE. and the arguments are unchanged.

Wrapped APIs

ChooseFont

Module

XFTextra.f90


XTimerStart

XTimerStart

XTimerStart function creates and starts a timer that will generate WM_TIMER messages at a regular interval.

LOGICAL FUNCTION XTimerStart (xWnd, idTimer, interval)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            idTimer
INTEGER, INTENT(IN)::            interval

Arguments

xWnd
X_WINDOW structure representing the timer's parent window. Even though timers are not visible, each timer is associated with a window.

idTimer
Unique numeric identifier that you assign to the timer. It must be an integer greater than zero.

interval

The timer's time-out value in integer milliseconds. The timer will generate a WM_TIMER message every interval milliseconds until it stopped by XTimerStop.

Remarks

Use the Xeffort Wizard to prototype and invoke a handler for WM_TIMER events. The xWnd and idTimer values above are passed as arguments to the handler routine. Thus it is possible to have multiple active timers, each with a unique idTimer and different time-out value.

Each time the specified interval (or time-out value) for a given timer elapses, the system posts a message to call the window's WM_TIMER event handler. Because the accuracy of a timer depends on the system clock rate and how often the application retrieves messages from the message queue, and the fact that the WM_TIMER message is considered low-priority, the time-out value is only approximate. (To determine actual timing of WM_TIMER events, consider VF's SYSTEM_CLOCK routine.)

To use system resources efficiently, you should destroy timers that are no longer necessary by using XTimerStop before destroying the parent X_WINDOW.

Return Value

If successful, the function returns .TRUE.

See Also

XTimerStop

Wrapped APIs

SetTimer

Module

XFTextra.f90


XTimerStop

XTimerStop

XTimerStop function destroys a timer created by XTimerStart.

LOGICAL FUNCTION XTimerStop (xWnd, idTimer)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            idTimer

Arguments

xWnd
X_WINDOW structure representing the timer's parent window.

idTimer
Unique numeric identifier assigned to the timer.

Remarks

The xWnd and idTimer values above should equal those passed to the XTimerStart function that created the timer.

Return Value

If successful, the function returns .TRUE.

See Also

XTimerStart

Wrapped APIs

KillTimer

Module

XFTextra.f90


XFTCaret Overview

XFTCaret Overview

Reference

It is recommended that all text input in your application be done using Edit Controls. Edit Controls can be used in dialogs and/or as a part of, or as the entire, client area of an X_Window. The user of your application benefits from the standard, thus well known, mouse and keyboard text editing capability of the Edit Control. You benefit because this editing capability, as well as caret management and keyboard focus transfer, are embedded in the Edit Control and require no additional thought or effort on your part. If you use Edit Controls for all text input, you will have no need of anything in this section.

Conversely, if you decide to handle keyboard input directly, you'll need to run the Xeffort Wizard to establish handlers for the KEYDOWN (and/or CHAR), SETFOCUS, and KILLFOCUS events as a minimum. Every window and/or child window that is to receive keyboard input must be connected to such handlers.

Let us review some Microsoft terminology.

  • "Active Window". The "active window" is the frame window of the currently active application. The active window always has a distinctive title bar. Note the user can switch applications at any time and thus cause the active window to change. If the active window is a MDI application, it can "pass on" its activity by simulating making one of its MDI child windows appear active. Similarly, any active application can launch a dialog that will appear to be the active window. Note that child windows can never be the active window (except MDI children fake it).

  • "Focus Window". This is the window to which keystrokes are directed, i.e., "focus" means keyboard focus. Any child of the active window (or the active window itself) can receive focus, i.e., can have keystrokes directed to it.

  • "Cursor". The non-blinking bitmap that tracks mouse movement.

  • "Caret". The blinking bitmap that indicates the text insertion point. The caret is moved only by the XCaretMove routine. (The caret is commonly called the cursor.)

Note the user's computer has only one keyboard and one caret that must be shared among all applications. In order for this sharing to work, you must obey this simple yet rigid rule.

"Whenever a window receives focus, it creates a caret. Whenever a window looses focus, it destroys the caret."

To the Xeffort programmer, this translates to: The WM_SETFOCUS event handler routine calls XCaretShow to create and display a caret. The WM_KILLFOCUS event handler calls XCaretHide to destroy that caret. This will insure the required one-to-one correspondence between caret creations and deletions, and that a caret is not created before the previous caret has been deleted.


XFTCaret Reference

XFTCaret Reference

Overview

Caret Management

XCaretShow

XCaretMove

XCaretHide

Keyboard Focus Transfer

XSetFocus


XCaretShow

XCaretShow

Creates and displays a caret in the given window.

LOGICAL FUNCTION
XCaretShow(xWnd, xBmp)

TYPE(X_WINDOW), INTENT(IN):: xWnd
TYPE(X_BITMAP), OPTIONAL, INTENT(IN) :: xBmp

Arguments

xWnd
 X_WINDOW structure describing the window that has focus and is to contain the caret.

[xBmp]

X_BITMAP structure describing the caret. You have two choices for a caret -- furnish a real bitmap of arbitrary shape and color, or use a rectangular block.

Load a real bitmap using XCreateBitmap. The bitmap size should be appropriate for the text character size being displayed. Because of the raster operations Windows uses to cause the bitmap to blink, it may be necessary to invert the colors in the bitmap source.

Or, to use a rectangular block of width iCaretW and height iCaretH, construct a X_BITMAP variable with a zero handle and with the desired sizes, e.g.,

TYPE (X_BITMAP) xBmp

   xBmp % hBmp = 0
   xBmp % iX = iCaretW
   xBmp % iY = iCaretH

where the dimensions are integer physical units (pixels).

If xBmp is omitted, a rectangular caret of default size is created.

Return Value

If successful, the return value is .TRUE.

Remarks

As mentioned in the Overview, XCaretShow must be called during WM_SETFOCUS event processing. In addition, XCaretShow may be called whenever it is desired to change the caret, provided a call to XCaretHide proceeds the call to XCaretShow. That is, the existing caret must be destroyed before a new caret is created.

See Also

XCaretMove, XCaretHide

Wrapped APIs

CreateCaret, ShowCaret

Module

XFTCaret.f90


XCaretMove

XCaretMove

Positions the caret in the given window.

LOGICAL FUNCTION
XCaretMove(xWnd, iX, iY)

TYPE(X_WINDOW), INTENT(IN):: xWnd
INTEGER, INTENT(IN)       :: iX, iY

Arguments

xWnd
 X_WINDOW structure describing the window that has focus and the caret.

iX, iY

Given horizontal and vertical coordinates, respectively, of the upper-left corner of the caret bitmap in physical coordinates (pixels). These coordinates are with respect to an origin at the top-left corner of the client area.

Return Value

If successful, the return value is .TRUE.

See Also

XCaretShow

Wrapped APIs

SetCaretPos

Module

XFTCaret.f90


XCaretHide

XCaretHide

Removes the caret from the given window.

LOGICAL FUNCTION XCaretHide(xWnd)

TYPE(X_WINDOW), INTENT(IN):: xWnd

Arguments

xWnd
 X_WINDOW structure describing the window whose caret is to be hidden and destroyed.

Return Value

If successful, the return value is .TRUE.

Remarks

XCaretHide should be used during WM_KILLFOCUS event processing if XCaretShow was used during WM_SETFOCUS processing for the window.

See Also

XCaretShow

Wrapped APIs

HideCaret, DestroyCaret

Module

XFTCaret.f90


XSetFocus

XSetFocus

Transfers keyboard focus to the specified X_WINDOW.

LOGICAL FUNCTION XSetFocus(xWnd)

TYPE(X_WINDOW), INTENT(IN):: xWnd

Arguments

xWnd
 X_WINDOW structure describing the window that is to gain keyboard focus.

Return Value

If successful, the return value is .TRUE.

Remarks

This routine starts a chain of events that include: WM_KILLFOCUS to the window that currently has focus, the specified window or its parent is made active, then WM_SETFOCUS to the specified window.

Wrapped APIs

SetFocus

Module

XFTCaret.f90


XFTCTRL Overview

XFTCtrl Overview

Reference

XFTCtrl module is used for handling of controls, such as edit-boxes, check-boxes, or buttons. It can be used to manage controls in Xeffort windows themselves, or in dialog boxes, handled by XFTDialog module.

A control is a window that used to obtain a specific piece of information from the user, such as the name of a file to open or the desired point size of a text selection. Although controls are windows, their behavior is so well predefined that it is seldom necessary to treat them as such; thus, it is not necessary to define X_WINDOW variables for them. The controls are identified by their numeric identifier (ID) and the X_WINDOW variable describing their parent window.

Control Types

The following types of controls are handled by XFTCtrl:

  • Radio buttons

  • Pushbuttons

  • Check boxes

  • Combo boxes (with edit-box portion)

  • Dropdown lists (combo box without edit-box portion)

  • Edit boxes

  • Group boxes

  • List boxes

  • Progress bars

  • Scroll bars

  • Sliders

  • Static controls (text or image)

  • Status bars

  • Tab controls

  • ListView controls

Controls which are not natively handled by XFTCtrl (e.g. Treeviews) can be handled using native Windows APIs and Xeffort helper functions such as XCreateWindow, XCtlSendMessage or XSetCommand.

Control Interface

XFTCtrl has interface similar to DFLOGM shipped by Compaq/Intel with Visual Fortran compiler. Additional features of XFTCtrl can be used with old codes written using DFLOGM using XFLOGM/DFLOGM compatibility layer.

Controls are always child windows, i.e. they are contained withing another window. That window is referred to as parent window. They are referred to by the X_WINDOW variable describing their parent and an identifier - an integer value which should be unique among all controls of the same parent. For example, XCtlSet(xFoo, IDC_EDIT1, "Hello World") sets the text of edit-control with identifier IDC_EDIT1 whose parent is window xFoo.

Controls' Lifetime

Controls can be created in two principal ways. Since the controls are most commonly used within dialogs, creation of a dialog using XLoadDialog also creates its designed controls. An application can create controls in run-time using XCtlCreate routine.

Regardless of how they started their life, controls will be automatically destroyed when their parent window is destroyed (XDestroyDialog for dialogs or XDestroyWindow for other windows). Also, an application can destroy them on demand using XCtlDestroy(All).

Control Properties and Their Values

Controls are finite-state automates, meaning that they have a state, described by a set of properties. For example, a check-box can be checked or unchecked (this property can be changed by user), visible or hidden, enabled or disabled. Values of fhese properties can be set using XCtlSet or retrieved using XCtlGet routines. Some properties are common for all controls, like visibility (CTS_VISIBLE) and enabled state (CTS_ENABLE). Other properties are control-specific. See Control Properties entry for full list of available properties and their meanings.

Control Callbacks

In many cases, it is sufficient that an application sets up a control's properties (many of them can be defined in design time using Visual Studio resource editor if the control is child of a dialog), and reads their values after user has changed them (e.g. a dialog is closed). However, changing a value of a property in one control often requires some chain of events. As a simple example, if there are two check-boxes, titled "Show file names", and "With full path" (both referring to same file names), the second option has no sense if the first is not checked. An application should always present only viable choices to the user; thus, if "Show file names" gets unchecked by user, the application should disable "With full path". That can be done by installing a callback routine using XCtlSetSub, and writing its body which enables the second check box based on the state of the first.


XFTCTRL: Control Styles

XFTCTRL: Control Styles

The following control styles are available for Xeffort controls created by XCtlCreate.

Apart from styles listed below ("common" ones), various controls can have their specific styles. (For example, an edit control can have ES_NUMBER style, specifying it can display only digits, but not other characters). These styles can be set using iAddStyle argument of XCtlCreate.

Style | Applies to | Meaning
CTS_HORZ | XCTL_SCROLLBAR XCTL_SLIDER XCTL_UPDOWN | The control has horizontal appearance.
CTS_VERT | XCTL_SCROLLBAR XCTL_SLIDER XCTL_UPDOWN | The control has vertical appearance.
CTS_RIGHTTEXT | XCTL_EDIT XCTL_STATIC XCTL_RADIO XCTL_AUTORADIO XCTL_BUTTON XCTL_CHECKBOX | The text is aligned right.
CTS_CENTERTEXT | XCTL_EDIT XCTL_STATIC XCTL_RADIO XCTL_AUTORADIO XCTL_BUTTON XCTL_CHECKBOX | The text is aligned in control's horizontal center.
CTS_SORT | XCTL_LIST XCTL_DROPDOWN XCTL_COMBO | Items in the control are sorted.
CTS_LEFTTEXT | XCTL_EDIT XCTL_STATIC XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX | The text is aligned left. For radios and checkboxes, this style means that the text is on the left side of the checkmark.
CTS_ICON | XCTL_STATIC XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX | The control displays an icon rather than text.
CTS_BITMAP | XCTL_STATIC XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX | The control displays a bitmap rather than text.
CTS_WINDOWEDGE | All | The control has an edge like a window.
CTS_CLIENTEDGE | All | The control has sunken edge like an edit box (2 pixels deep by default).
CTS_MULTILINE | XCTL_EDIT XCTL_BUTTON XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX XCTL_BUTTON XCTL_TAB | The text wraps to the next line if it exceeds control's width. For tab controls, the new tab is created in a new line if total width of thumbs exceeds the width of the tab control.
CTS_READONLY | XCTL_EDIT | The text is read-only.
CTS_PUSHLIKE | XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX | The control looks exactly like a push button, but has identical behavior as the normal radio or check-box.
CTS_FLAT | CTS_FLAT | The control is flat, rather than having the default 3D-look.
CTS_GROUP | All | The control is the first in a group. The group consists of this first control and all controls defined after it, up to the next control with the WS_GROUP style. The user can subsequently change the keyboard focus from one control in the group to the next control in the group by using the direction keys.
CTS_DISABLED | All | The control is initially disabled.
CTS_OWNERDRAW | XCTL_STATIC XCTL_BUTTON | Drawing on the control is performed in run-time using a callback routine, rather than using default drawing.


XFTCTRL: Control Properties

XFTCTRL: Control Properties

XCtlSet and XCtlGet routines set or retrieve properties of the control. Value of a property can be an integer, string, logical, or an array.

LOGICAL FUNCTION XCtlSet(xWnd, ID, Value, iAction)

LOGICAL FUNCTION XCtlGet(xWnd, ID, Value, iAction)

General meaning of iAction indices describing control properties are presented in the following table. More detailed explanations are given in the table below and remarks thereafter:

Constant | Meaning
CTL_DEFAULT | The default value. See table below.
CTL_STATE | State of the control, i.e. its important property. For example, for edit controls it refers to control's text, and for check boxes their checked state
CTL_BITMAP | Handle of a bitmap associated with the control. The control must have an appropriate style to display the bitmap.
CTL_BKCOLOR | Background color of the control
CTL_COLOR | Color of control's text
CTL_ENABLE | Enabled/disabled control's status
CTL_FONT | Font of the control
CTL_FORMAT | Rendering format of the listview control
CTL_ICON | Handle of icon associated with the control. The control must have an appropriate style to display the icon.
CTL_NUMITEMS | Number of items in control's (such as list or tab control)
CTL_PAGE | Scrollbars & updown controls: amount of increase of control's value on a single mouse click
CTL_RANGEMAX | Maximal allowed value for the control
CTL_RANGEMIN | Minimal allowed value for the control
CTL_RECTS | Width of individual fields of multi-item status bar, or width of columns of a listview control.
CTL_SELECTION | Selected item in the list. Usually identical to CTL_STATE
CTL_SIZEOF | Size of single user-defined type in a virtual listview control.
CTL_TABSTOPS | Tab stop positions for list boxes with LBS_USETABSTOPS style
CTL_TITLE | Control's caption
CTL_VISIBLE | Control's visibility
Index | For controls containing multiple items, such as list boxes, a positive integer refers to Index-th item in the collection.
CTL_APPEND (=0) | For controls containing multiple items, such as list boxes, CTL_APPEND for XCtrlSet mean "append an item to the end of the list"

The following table describes applicable properties for every type of control handled by XFTCTRL:

Type of control | Integer | String | Logical | Array
XCTL_DIALOG | CTL_ICON CTL_COLOR | CTL_TITLE CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_AUTORADIO | CTL_BITMAP3 CTL_ICON3 CTL_COLOR CTL_BKCOLOR | CTL_TITLE CTL_FONT6 | CTL_STATE CTL_VISIBLE CTL_ENABLE |
XCTL_BUTTON | CTL_BITMAP3 CTL_ICON3 | CTL_TITLE CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_CHECKBOX | CTL_BITMAP3 CTL_ICON3 CTL_COLOR CTL_BKCOLOR | CTL_TITLE CTL_FONT6 | CTL_STATE CTL_VISIBLE CTL_ENABLE |
XCTL_COMBO | CTL_STATE CTL_SELECTION CTL_NUMITEMS CTL_COLOR CTL_BKCOLOR Index | CTL_STATE CTL_SELECTION CTL_SELECTION1 CTL_FONT CTL_APPEND1 Index | CTL_VISIBLE CTL_ENABLE |
XCTL_DROPDOWN | CTL_STATE CTL_SELECTION CTL_NUMITEMS CTL_COLOR CTL_BKCOLOR Index | CTL_SELECTION CTL_SELECTION1 CTL_FONT6 CTL_APPEND Index | CTL_VISIBLE CTL_ENABLE |
XCTL_EDIT | CTL_STATE9 CTL_RANGEMAX CTL_COLOR CTL_BKCOLOR CTL_SELECTION | CTL_STATE CTL_FONT6 CTL_APPEND Index | CTL_VISIBLE CTL_ENABLE |
XCTL_GROUP | CTL_COLOR CTL_BKCOLOR | CTL_TITLE CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_LIST | CTL_STATE CTL_SELECTION CTL_NUMITEMS CTL_COLOR CTL_BKCOLOR Index | CTL_SELECTION CTL_SELECTION7 CTL_FONT CTL_APPEND1 Index | CTL_VISIBLE CTL_ENABLE | CTL_SELECTION CTL_TABSTOPS
XCTL_LISTVIEW (see detailed reference) | CTL_STATE CTL_SELECTION CTL_NUMITEMS CTL_COLOR CTL_BKCOLOR CTL_SIZEOF Index | CTL_FORMAT CTL_APPEND CTL_FONT6 Index | CTL_VISIBLE CTL_ENABLE Index | CTL_SELECTION CTL_RECTS
XCTL_RADIO | CTL_BITMAP3 CTL_ICON3 CTL_COLOR CTL_BKCOLOR | CTL_TITLE CTL_FONT6 | CTL_STATE CTL_VISIBLE CTL_ENABLE |
XCTL_PROGRESS | CTL_STATE CTL_PAGE CTL_COLOR CTL_BKCOLOR | CTL_FONT | CTL_VISIBLE CTL_ENABLE |
XCTL_SCROLLBAR | CTL_STATE CTL_PAGE CTL_RANGEMAX CTL_RANGEMIN CTL_COLOR CTL_BKCOLOR | CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_SLIDER | CTL_STATE CTL_PAGE CTL_RANGEMAX CTL_COLOR CTL_BKCOLOR | CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_STATIC | CTL_BITMAP3 CTL_ICON3 CTL_COLOR CTL_BKCOLOR | CTL_TITLE CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |
XCTL_STATUS (see examples) | CTL_COLOR CTL_BKCOLOR Index 3 | CTL_FONT6 Index | CTL_VISIBLE CTL_ENABLE | CTL_RECTS
XCTL_TAB | CTL_STATE CTL_SELECTION CTL_NUMITEMS CTL_COLOR CTL_BKCOLOR Index8 | CTL_FONT6 Index | CTL_VISIBLE CTL_ENABLE |
XCTL_UPDOWN | CTL_STATE CTL_RANGEMAX CTL_RANGEMIN CTL_BKCOLOR | CTL_FONT6 | CTL_VISIBLE CTL_ENABLE |

Remarks

  1. If iAction argument is omitted, it defaults to the value indicated bold. The default value is indicated red if it's applicable only for XCtlSet, and green if applicable only for XCtlGet. For example:
    b = XCtlSet(xWnd, IDC_LIST1, "Item")
    appends a sting named "Item" at the end of the list (iAction = CTL_APPEND), while
    b = XCtlGet(xWnd, IDC_LIST1, String)
    returns the selected string from the list (iAction = CTL_STATE/CTL_SELECTION).

  2. Where there are two default actions (indicated bold), they have the identical meaning.

  3. CTL_ICON and CTL_BITMAP are applicable only for controls which have appropriate style set, e.g. BS_ICON/BS_BITMAP for buttons or SS_ICON/SS_BITMAP for static controls. Status bars can also display an icon (but not a bitmap); specify the index of status bar's field to indicate the part in which the icon should be displayed.

  4. CTL_COLOR and CTL_BKCOLOR don't affect push button's appearance at all. For check boxes and radio buttons, they affect only the appearance of text.

  5. A control is physically visible if both its parent window and itself have WS_VISIBLE style. CTL_VISIBLE sets/gets only the status of the control itself, i.e. it may be set or returned TRUE even if the parent window is hidden.

  6. CTL_FONT property is available only for XCtlSet. Font descriptor string has to have the same format as for SETFONT QuickWin function, i.e. "t'Arial'h8eui" means "8 point Arial bold italic underlined". Only t, i, e, u, h, w descriptors are supported.

  7. List boxes specifically can have or not LBS_MULTIPLESEL (CTL_) style, which allows several items to be selected simultaneously. To retrieve selected items, you can either:
    - use     XCtlGet(xWnd, IDC_LIST1, iSel, CTL_SELECTION) where iSel is an integer pointer array which will contain indices of selected items, or
    - use     DO WHILE(XCtlGet(xWnd, IDC_LIST1, iSel, n)); n=n+1; END DO. iSel will contain position in the list of n-th selected items.

  8. XCtlSet(xWnd, IDC_TAB1, IDD_DIALOG1, n) will assign modeless child dialog with identifier IDD_DIALOG1 to n-th page of Tab control.

  9. CTL_STATE for edit controls with integer value will set the text of the edit control to textual representation of the integer. For XCtlGet, it will attempt to retrieve to interpret the text as an integer until it encouters a non-numeric value.


XFTCTRL: Control Events

XFTCTRL: Control Events

The following events are specified for controls handled by XFTCTRL. The values listed in the table above should be specified as the last argument of XCtlSetSub argument, to specify the event for which the callback is registered. If omitted, the default value is indicated bold for appropriate controls. That same value is passed by Xeffort library as the last argument (iEvent) of application-defined callback.

Event | Applies to | Meaning
CTL_CHANGE | XCTL_EDIT XCTL_SCROLLBAR XCTL_UPDOWN XCTL_SLIDER | State of the control is changed. For edit and combo boxes, this callback is called when user changes text in edit portion, but before it is formatted and displayed on th screen. For other controls, it is called when control's slider position is changed.
CTL_CLICKED | XCTL_BUTTON XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX | The control is clicked with the mouse (or pressed using Space on keyboard)
CTL_COLUMNCLICK | XCTL_LISTVIEW | Column of the header control was clicked
CTL_DBLCLICK | XCTL_LIST XCTL_DROPDOWN XCTL_COMBO XCTL_LISTVIEW | An item in the list is double-clicked.
CTL_DRAWITEM | XCTL_STATIC XCTL_BUTTON XCTL_RADIO XCTL_AUTORADIO XCTL_CHECKBOX XCTL_LISTVIEW | The control with "Owner drawn" style has to be redrawn.
CTL_DESTROY | XCTL_DIALOG | The dialog is about to be destroyed.
CTL_GAINFOCUS | XCTL_EDIT XCTL_LIST XCTL_COMBO XCTL_DROPDOWN | The control has gained the focus.
CTL_HELP | XCTL_DIALOG | User has pressed button F1, or clicked on a control when the dialog is in "context help" mode. The callback routine receives ID of clicked control as the third parameter (iEvent). iEvent can be casted to Win32 HELPINFO structure using X_HELPINFO helper function.
CTL_INIT | XCTL_DIALOG | The dialog is being initialized. This callback is called from XModalDialog and XModelessDialog.
CTL_LOSEFOCUS | XCTL_EDIT XCTL_LIST XCTL_COMBO XCTL_DROPDOWN | The control has lost the focus.
CTL_SELCHANGE | XCTL_LIST XCTL_DROPDOWN XCTL_COMBO XCTL_TAB XCTL_LISTVIEW | Selected item in the list is changed.
CTL_SELCHANGING | XCTL_TAB | User has clicked on a different page of a tab control, but the control was not yet updated (page changed).
CTL_SIZECHANGE | XCTL_DIALOG | The dialog is being resized.
CTL_UPDATE | XCTL_EDIT XCTL_COMBO | This callback is called when the edit portion of the control is about to be updated.


XFTCTRL: ListView Controls Overview

XFTCTRL: ListView Controls Overview

Reference

ListView controls are complex controls used for displaying of various kinds of list-like reports. Unlike an ordinary list control, list view supports images, columns of adjustable width, and much more. Xeffort supports only ListViews in report mode, which is the most frequently used.

A ListView control has the following components:

The main output consists of items, which consist of one or more subitems. Every item occupies one row of the control. Every subitem is related with one column. Header of the ListView controls contains the columns; header columns have their title and can have adjustable width. I In general, items can be re-sorted.

Xeffort ListView API Concepts, Format and Items

Every item of the ListView control presents an amount of data, in textual (or image) form and spread accross the columns. The correspondence between a ListView item and the data it represents are similar to a record of a formatted, direct-access file and variable(s) read/written into the record. With Xeffort, you must define a TYPE (referred to as usertype in the sequel) which can have any name you want, and specify the format string which will be used to render the contens of the usertype onto the ListView items.

For example, the usertype used to construct a ListView record from the picture above looks like:

TYPE MyType
   SEQUENCE
   INTEGER(4)    h
   CHARACTER(32) s
   REAL(8)       d(2)
   REAL(4)       f(2)
   INTEGER(4)    i
   INTEGER(2)    j
   INTEGER(1)    k
   INTEGER(1)    unused
END TYPE MyType

While the format string used to render it looks like:

sFormat = "(+a32, g10.3, d10.4, f10.0, e10.4, x4, j0, k3)"

Have in mind that Xeffort does not know (and cannot know) how your usertype looks like. The only thing it knows is the format string. The format string is similar (but by no means identical) to standard Fortran format string, but it has limited functionality and uses special descriptors to denote kind of variables. In the example, MyType%h is rendered as an image (+ format descriptor), MyType%s as text of 32 characters, etc. For example, MyType%i is skipped (not rendered) due to x4 descriptor. For more details about ListView format, see ListView reference.

ListView controls can be classified into basic two types:

  • Simple ListView controls hold the contents of all items themselves in textual form (as strings). The application can safely "forget" about the data placed within the control, as it could retrieve them back from the control itself. However, potential loss of precision can occur (because rendering occurs in textual form, as with ASCII files). Also, simple ListView controls with large number of items are slow to sort and redraw.

  • Virtual ListView controls do not hold all the data within. Instead, they request only the minimal amount of data (namely, the visible items), and Xeffort library performs rendering-on-demand. Such controls are much faster for scrolling, sorting, and redrawing. However, they require that the application defines an array of usertypes, which must persist at least as long as the ListView control is visible. Virtual ListView controls have LVS_OWNERDATA window style ("Owner data" checkbox in resource editor).

In any case, Xeffort takes care about item rendering and item sorting, depending on given format string and set of (array of) usertypes. The two types have the same behavior (except that simple ones have slower performance, expecially with large number of items) - there is only a slight difference in programming interface. The type of ListView control can not be changed after its creation.

Simple ListView controls

Simple ListView controls do not have LVS_OWNERDATA style. They hold all the data about its items in textual form. The application need not ensure data persistence; for example, it can load the data from a text file, construct a scalar usertype and add one usertype at a time. To set up items in a simple ListView control, the application should perform the following steps:

TYPE(MyType)::            tItem
CHARACTER(*), PARAMETER:: sFormat = "(+a32,g10.3,d10.4,f10.0,e10.4,x4,j0,k3)"

...
!Set the rendering format
bSt = XCtlSet(XW_FRAME, IDC_LIST1, sFormat, CTL_FORMAT)
!Add the items one at a time:
DO i = 1,nItems
  tItem = MyType(MOD(i,3)+1, "Test "//STRING(i,5), (/ATAN(REAL(i)),REAL(i)/), &
          (/SQRT(REAL(i)), COS(REAL(i))/), i, 10000-i, i/2, 0)
  bSt = XCtlSet(xDlg, IDC_LIST1, XItem(tItem), i)
END DO

XItem function does not do anything special - it only serves to denote that its argument is to be treated as a ListView item and that the compiler should not check what it is. (In C terms, it casts to a void*).

Virtual ListView controls

Virtual ListView controls are faster to process. However, they require that the array of useritems is maintained by the application. The ListView control does not hold the information about the data it contains (but it does hold the information about selection and columns though). Instead, the application is supposed to provide the format string, create an array of useritems, and tell the Xeffort about the first item, number of items, and size of an individual item - Xeffort takes care about proper sorting and rendering of items:

TYPE(MyType), ALLOCATABLE, SAVE:: tItem(:)
CHARACTER(*), PARAMETER::         sFormat = "(+a32,g10.3,d10.4,f10.0,e10.4,x4,j0,k3)"

...
!Set the rendering format
bSt = XCtlSet(XW_FRAME, IDC_LIST1, sFormat, CTL_FORMAT)
!Allocate and fill the item one at a time:
ALLOCATE(tItem(nItems))
!Add the items one at a time:
DO i = 1,nItems
  tItem(i) = MyType(MOD(i,3)+1, "Test "//STRING(i,5), (/ATAN(REAL(i)),REAL(i)/), &
          (/SQRT(REAL(i)), COS(REAL(i))/), i, 10000-i, i/2, 0)
END DO
!Set up the size of an individual item (so that Xeffort can access individual)
!members of the array:
bSt = XCtlSet(xDlg, IDC_LIST1, SIZEOF(tItem(1)), CTL_SIZEOF)
bSt = XCtlSet(xDlg, IDC_LIST1, nItems, CTL_NUMITEMS)
!Set up the pointer to the array of items:
bSt = XCtlSet(xDlg, IDC_LIST1, XItem(tItem(1)), 0)

If the rendering or sorting of the items is still not good enough for you (for example, because setting up an array of usertypes is not practical), there is also the possibility to set up a "do-it-yourself" (DIY) virtual ListView. With DIY virtual ListView, you set up a CTL_DRAWITEM callback and fill the text of every individual subitem yourself. Note, however, that you have to implement your own sorting if you need one, because in this case only you can know how the data are to be sorted.

ListView header and sorting

Xeffort sets up the ListView's header according to the provided format string. Namely, there are as many header columns as there are non-skipped items in the format string. Column titles have to be set up separately using XCtlSetChar. See ListView Control Reference.

By default, Xeffort sets up the "down arrow" and "up arrow" images indicating the sorting order of the column. All the columns are sortable according to their datatype (string, integer or real). To disable sorting altogether, use "No sort header" style (LVS_NOSORTHEADER); to remove the header, use "No column header" style (LVS_NOCOLUMNHEADER). If you want to provide custom sorting, or sorting only for certain columns, you have to write a CTL_COLUMNCLICK callback.

Images

ListView control displays images in its items according to the value of a dedicated member of your usertype and supplied image list. Currently, the image list must be created manually, using ImageList APIs (use COMCTL32) (adding ImageList wrappers is in plans for Xeffort). The image list is a list of icons (or bitmaps), whose members can be accessed by their index. The icons can be standard small (16x16) or of a custom size.

To add an image list of small icons into the list view control, design your icons in the resource editor and assign them an ID. (Hint: to insert a custom-size icon in resource editor, click on "New device image", then "Custom" and enter the size and color depth). All the icons should be of the same size. Then, create and load an image list; the following example creates an image list of three 16x12 icons, and assigns them to the ListView control using CTL_ICON index:

INTEGER::            hIL, hIcon
INTEGER, PARAMETER:: idIcon(3) = (/IDI_BLUE, IDI_YELLOW, IDI_RED/)

hIL = ImageList_Create(16, 12, ILC_MASK, 3, 0)
DO i=1,3
   hIcon = LoadImage(XGetInstance(), idIcon(i), IMAGE_ICON, 16, 12, LR_DEFAULTCOLOR)
   iSt = ImageList_ReplaceIcon(hIL, -1, hIcon)
END DO
bSt = XCtlSet(xDlg, IDC_LIST1, hIL, CTL_ICON)

One (or more) INTEGER(4) members of your usertype must be dedicated to hold the icon index in the image list. In the format string, the column which should contain the image must be prepended with "+". For example, to set images in second column of the listview, use the following format string and usertype:

TYPE MyType
   SEQUENCE
   CHARACTER(32) s
   INTEGER(4)    iImage
   REAL          g
   ...

CHARACTER(*), PARAMETER:: sFormat = "(a32,+f10.3...

This denotes that column g (with real number rendered in f10.3 format) is to be prepended with the image ("+" format) whose index is to be found in INTEGER(4) member preceding it. Allowed values of iImage are from 1 to number of items in the image list.

Note that, when the image list is supplied to the ListView control, an image will always appear in the first column. If you do not want an image, supply an empty icon in the image list and use appropriate index.


XFTCTRL: ListView Control Reference

XFTCTRL: ListView Control Reference

Overview

ListView control supports the following semantics using XCtlSet/DlgSet and XCtlSetSub/DlgSetSub routines:

LOGICAL FUNCTION XCtlSet(xWnd, ID, Value, iAction)

LOGICAL FUNCTION XCtlGet(xWnd, ID, Value, iAction)

Item Value (XCtlSetItem/DlgSetItem)

ListView control contains a collection of items, in form of strings spread across the columns. Xeffort renders the items on the basis of (an array of) arbitrary application-defined data and the format string which must match contents of the data. The data for each item must be packed in a derived TYPE, referred to as usertype in this document.

iAction | Simple |  | Virtual |  | Meaning
 | Set | Get | Set | Get
0 (zero) | • | • | • | • | For simple ListView controls: appends the item to the end of item list. For virtual ListView controls: sets up the array of items to render. CTL_FORMAT, CTL_NUMITEMS and CTL_SIZEOF must be correctly set before setting up the items.
n=1..n Items | • | • |  | • | Sets up the value of n-th item. If n is greater than the current number of items, the item is appended to the end of the list.

The Value argument must be of type X_ITEM. However, X_ITEM is opaque to the user - instead, application must use XItem function to convert the actual usertype into X_ITEM. XItem can take any type as an argument and convert it into a X_ITEM.

Virtual ListView controls render an array of usertypes. The array must be persistent at least as long as the ListView control is alive, i.e. either be static or allocated before the call to XCtlSetItem(...0) and deallocated after the control is destroyed. That also means that changing the value of any member of the array causes the contents of the control to reflect the new state. To force the redraw immediately, call XLVUpdate.

Tip: instead of a TYPE, the application can use string variables which contain fixed-width "subfields", and then use appropriate a format descriptors. For example, the following setup will correctly render two 32-character strings divided into 3 fields of 16, 8 and 8 character onto 3 columns on a ListView:

CHARACTER(32), PARAMETER:: sItem1 = "Item 1          Foo     Bar     "
CHARACTER(32), PARAMETER:: sItem2 = "Item 2          Baz     Boo     "
CHARACTER(*), PARAMETER::  sFormat = "(a16, a8, a8)"
...
bSt = XCtlSet(xDlg, IDC_LIST1, sFormat, CTL_FORMAT)
bSt = XCtlSet(xDlg, IDC_LIST1, XItem(sItem1), 1)
bSt = XCtlSet(xDlg, IDC_LIST1, XItem(sItem2), 2)

Array Value (XCtlSetArray/DlgSetArray)

iAction

Simple

Virtual

Meaning

Set

 Get

Set

Get
CTL_RECTS • • • • Sets the width of columns of the header control. The values can denote pixels, or be one of the following special values:

XLV_AUTOITEM (=-1) - the column width is adjusted to fit the width of the longest text of appropriate subitem

XLV_AUTOHDR (=-2) - same as XLV_AUTOITEM except the column may be widened to accommodate the header column title.

XLV_LEAVE (=-3) - the column width is retained unchanged .

CTL_SELECTION

•

 •

•

 • Sets or retrieves an array of indices of all selected items in the ListView.

CTL_COLUMNORDER

•

 •

•

 • Sets or retrieves an array of indices of the current column order in the ListView.

The following piece of code illustrates retrieving the index of all the selected items from the ListView control into an array:

INTEGER, POINTER :: iSel(:)

!Get all (row/item) selections at once.  (These will be in the order
! that the user has sorted the display, i.e., topmost selection first.)
bSt = XCtlGet (xDlg, IDC_LIST1, iSel, CTL_SELECTION)
!Get count of selections
nSelected = SIZE (iSel)
DO j = 1, nSelected
    !Do something with iSel(j)-th item
END DO

!Before we can use iSel in another call to XCtlGet, it must be deallocated.
!Moreover it should be deallocated before RETURN/END to prevent a memory leak.
DEALLOCATE (iSel)

CTL_COLUMNORDER deals with an integer array that contains some permutation of 1,2,3,...nColumns. The base column order is the order of the variables in a usertype record; but XCtlSet can change the order in which the variables are displayed. For example, for a three-variable usertype, the array (/3,1,2/) means display the 3rd variable in the 1st column, the 1st variable in the middle column, and the 2nd variable in the rightmost column. Regardless of how you arrange columns, the program user is free to re-arrange them by dragging the column header text. If the user's column arrangement has meaning, you can retrieve it via XCtlGet into an unallocated array with the Pointer attribute (and that you subsequently deallocate) as in the selection code example above.

String Value (XCtlSetChar/DlgSetChar)

iAction | Simple |  | Virtual |  | Meaning
 | Set | Get | Set | Get
CTL_FORMAT | • | • | • | • | Sets the ListView rendering format and clears up its contents. See below.
CTL_FONT | • | • | • | • | Sets up the font used by the ListView control.
n=1..nColumns | • | • | • | • | Sets/returns the title of n-th column of the ListView's header

Integer Value (XCtlSetInt/DlgSetInt)

iAction

Simple

Virtual

Meaning

Set

 Get

Set

Get

CTL_NUMITEMS

•

•

 • Sets the number of items of the ListView control. Not available for setting items in the simple control.
CTL_STATE

•

•

 Marks the Value-th item in the control as being selected. This method is not available for retrieving selection.
CTL_SELECTION • • • • Set marks the Value-th item in the control as being selected. Get begins a chain to retrieve the selected items from the ListView control. Note that this behavior is substantially different from ordinary list controls. See remarks below.
CTL_ICON • • • • Sets/returns the handle of the image list associated with the ListView control. See Overview.
CTL_SIZEOF • • Sets/Returns the size, in bytes, of an item (usertype record) in the virtual list-view control.
CTL_COLOR • • • • Sets the color, in #BBGGRR format, of the text of the control items
CTL_BKCOLOR • • • • Sets the background color, in #BBGGRR format, of the ListView control.
CTL_RECTS • • Sets the width of all columns of the header control. The value can denote pixels, or be one of the following special values:

XLV_AUTOITEM (=-1) - the column width is adjusted to fit the width of the longest text of appropriate subitem

XLV_AUTOHDR (=-2) - the column width is adjusted to fit the width of the longest text or the header column title, whichever is greater.

To retrieve the indices of all selected items from the ListView control, you can use the array approach described previously, or use XCtlGetInt with a special 5th argument in order to retrieve selected items one by one. This 5th argument must be an integer variable that you initialize to zero and do not otherwise change. (It is then used to maintain an internal pointer to selections). Note that, if successful, XCtlGetInt will return .TRUE. and place the index of a selected ListView row in its 3rd argument, "Value". When no more selections remain to be returned, XCtlGetInt returns .False. with a zero "Value". The following piece of code illustrates retrieving all the selected items from the ListView control:

iIndex = 0   ! Initialize retrieval chain index
DO WHILE (XCtlGet(xDlg, IDC_LIST1, jSel, CTL_SELECTION, iIndex) )
    !Do something with jSel-th item
END IF
! For the special case where you have marked the ListView control as
! "Single Selection" in the Resource Editor (so the user must select
! either one row or none) you can simplify the above slightly
IF ( XCtlGet(xDlg, IDC_LIST1, jSel, CTL_SELECTION) ) THEN
    !Do something with jSel-th item
END IF

Logical Value (XCtlSetLog/DlgSetLog)

iAction | Simple |  | Virtual |  | Meaning
 | Set | Get | Set | Get
CTL_ENABLE | • | • | • | • | Enables or disables the ListView control
CTL_VISIBLE | • | • | • | • | Shows or hides the ListView control
n=1..nItems | • | • | • | • | Sets/returns the selection of n-th item of the control

Therefore another alternative to retrieve the index of all the selected items from the ListView control would be:

LOGICAL :: wasSelected, bSt

!Loop over all rows/items
bSt = XCtlGet (xDlg, IDC_LIST1, nRows, CTL_NUMITEMS)
DO j = 1, nRows
   bSt = XCtlGet (xDlg, IDC_LIST1, wasSelected, j )
   IF (wasSelected) THEN
      !Do something with j-th item
   END IF
END DO

Callbacks (XCtlSetSub/DlgSetSub)

Four types of callbacks are available:

iAction | Simple | Virtual | Meaning
 | Set | Set
CTL_SELCHANGE | • | • | Called whenever the selection in the listview changes.
CTL_DBLCLICK | • | • | Called whenever the item is double-clicked or activated using Enter key.
CTL_COLUMNCLICK | • | • | Called whenever the column header button is clicked. The 3rd argument is the index of the clicked column. See remarks below.
CTL_DRAWITEM |  | • | Called whenever the application should supply a virtual ListView (sub)item. See remarks below.

CTL_COLUMNCLICK callback can be used in order to provide custom sorting by the application. Its 3rd argument is the index of clicked column. When this callback is absent, Xeffort provides default sorting based on the values of usertype members. The callback can pass the received information to the default Xeffort callback, XLV_OnColumnClick, which does the sorting.

CTL_DRAWITEM callback can be used for "do-it-yourself" virtual ListView items. When this callback is registered, it overrides default Xeffort display of the ListView items, and the format string is effectively invalid. The 3rd argument of the callback is a T_LVITEM Windows API structure (USE DFWIN), which contains the index of the item and subitem whose text/image the application should fill. This callback is called when the parent window receives LVN_GETDISPINFO message; please see SDK documentation about that message and T_LVITEM structure. The application which registers CTL_DRAWITEM callback should also register CTL_COLUMNCLICK callback in order to provide sorting, if any.

Format String

The format string of the ListView control denotes how the usertypes are to be rendered into individual items of the ListView control. The format consists of combination of descriptors, which denote both the size, in bytes, of the corresponding usertype member, and width, in characters, of the output string appearing on the control. The format must obey the following rules:

  • It must start and end with parentheses, like normal Fortran format statement.
  • The format string consist of descriptors, explained in the table below. Every descriptor is in form qW[.D], where q is a 1-character descriptor, W denotes either the output field width or input size in bytes, and optional D number of decimal points or minimal field witdh. Descriptors must be separated with commas. Blanks in the format strings are ignored.
  • Every comma in the format denotes a new column; an exception is x descriptor, which skips n bytes in the usertype.
  • Case of the descriptor does not matter, i.e. both lowercase and uppercase characters are accepted.
  • Repeating descriptors (e.g. 7I5) as well as parentheses are not currently allowed.

Allowed descriptors ([+]qW[.D]):

q | W | D | Meaning
a | bytes | not allowed | The corresponding variable is a CHARACTER(LEN=W). W must exactly match the string length; Xeffort TRIMs the string on output.
i | chars | minimal width, optional | The corresponding variable is an INTEGER(4). The output on the control is a string of W characters, with optional D minimal width (like in standard Fortran Format)
j | chars | minimal width, optional | The corresponding variable is an INTEGER(2). The output on the control is a string of W characters, with optional D minimal width (like in standard Fortran Format)
k | chars | minimal width, optional | The corresponding variable is an INTEGER(1). The output on the control is a string of W characters, with optional D minimal width (like in standard Fortran Format)
n | chars | minimal width, optional | The corresponding variable is an INTEGER(8). The output on the control is a string of W characters, with optional D minimal width (like in standard Fortran Format)
f | chars | dec. places, mandatory | The corresponding variable is a REAL(4). The output on the control is a string of W characters, in fixed notation, with D decimal places (like in standard Fortran Format).
e | chars | dec. places, mandatory | The corresponding variable is a REAL(4). The output on the control is a string of W characters, in exponential notation, with D decimal places (like in standard Fortran Format).
d | chars | dec. places, mandatory | The corresponding variable is a REAL(8). The output on the control is a string of W characters, in fixed notation, with D decimal places (like in standard Fortran Format).
g | chars | dec. places, mandatory | The corresponding variable is a REAL(8). The output on the control is a string of W characters, in exponential notation, with D decimal places (like in standard Fortran Format).
t | 1-5 | optional | The corresponding variable is of derived-type T_SYSTEMTIME (see "Date and Time Columns" below.)
x | bytes | not allowed | The corresponding variable(s) is skipped from rendering. W must contain the total number of bytes to skip, i.e. the total size of skipped variables.
+ | N/A | not allowed | The corresponding variable is an INTEGER(4) denoting the index of the image in control's image list set up by CTL_ICON. The + can appear within another descriptor, meaning that the image should be prepended to that column (rather than start a new one). Tip: to specify that a column contains only an image, use "+a0" descriptor.

The order of the format string entries will always match the order of usertype members. Unless a application-specified CTL_COLUMNORDER is set, it will also match the order of columns in the display.

NB: Pay attention to potential issues of variable alignment within the usertype. SEQUENCE keyword within the usertype ensures that there are no unused bytes between the members, but can cause performance hits and other misalignment problems. If you don't use SEQUENCE and know the rules of variable alignment, use x descriptors where appropriate to denote unused bytes, if any. The following example demonstrates correct format specification for a non-sequence type containing unused bytes:

TYPE MyType
   INTEGER(4) i1
   INTEGER(2) i2
   INTEGER(4) i3
END TYPE MyType

CHARACTER(*), PARAMETER:: sFormat = "(i6, j5, x2, i6)"

"x2" specifies that there are 2 unused bytes after i2 member. If SEQUENCE were specified for MyType, then "x2" should not appear, but i3 would be misaligned (as well as subsequent items of an array of MyTypes).

Date and Time Columns

In addition to the intrinsic Fortran variables, the usertype used to construct a ListView record can also contain variables of the derived type T_SYSTEMTIME whose structure is defined as:

TYPE T_SYSTEMTIME
   SEQUENCE
   INTEGER(2) wYear                 ! 4-digit year
   INTEGER(2) wMonth                ! (1-12)
   INTEGER(2) wDayOfWeek            ! (0-6), superfluous, set 0
   INTEGER(2) wDay                  ! (1-31)
   INTEGER(2) wHour                 ! (0-23)
   INTEGER(2) wMinute               ! (0-59)
   INTEGER(2) wSecond               ! (0-59)
   INTEGER(2) wMilliseconds         ! (0-999), not output
END TYPE

For ListView display, the date/time information is converted to text. The format of that text is specified by the User's Windows Regional Settings which will contain a both a short-date and a long-date format as well as a time format. Which of these formats is used is controlled by the format string above, specifically,

T1 short-date only

T2 long-date only

T3 time only

T4 short-date and time

T5 long-date and time

Normally the time is shown in hours and minutes; to include seconds, enter a non-zero D in the qW[.D] format. For instance, T3 yields hours and minutes, while T3.1 will show hours, minutes, and seconds (assuming the user's chosen Windows locale time format accommodates seconds).

Sorting of dates/times will be in chronological order if the control is a virtual ListView. However, in a simple ListView the text representation of the date/time is sorted alphanumerically, so, e.g., April would come before January, etc.


XFTCTRL Reference

XFTCTRL Reference

Overview

Control Creation and Destruction

XCtlCreate

XCtlDestroy

XCtlDestroyAll

Control Size and Position

XBeginCtlMove

XEndCtlMove

XCtlGetPos

XCtlMove

Control Properties and Events

XCtlGet

XCtlSet

XCtlSetSub

XCtlSendMessage

XSetDialogFocus

ListView Special Routines

XItem

XLV_OnColumnClick

XLVUpdate

ListView Controls Reference


XCtlCreate

XCtlCreate

XCtlCreate creates a control with suggested identifier ID in window xWnd.

INTEGER FUNCTION XCtlCreate(xWnd, ID, iType, iStyle, iX, iY, iWidth, iHeight, iExStyle, iAddStyle)

TYPE(X_WINDOW)::                xWnd
INTEGER, INTENT(IN)::           ID
INTEGER, INTENT(IN)::           iType
INTEGER, INTENT(IN)::           iStyle
INTEGER, OPTIONAL, INTENT(IN):: iX
INTEGER, OPTIONAL, INTENT(IN):: iY
INTEGER, OPTIONAL, INTENT(IN):: iWidth
INTEGER, OPTIONAL, INTENT(IN):: iHeight
INTEGER, OPTIONAL, INTENT(IN):: iExStyle
INTEGER, OPTIONAL, INTENT(IN):: iAddStyle

Arguments

xWnd
 X_WINDOW structure representing control's parent window.

ID
Suggested numeric identifier of the control. If set to 0, the function will pick up an ID and assign it to the control. See remarks below.

iType
Type of the control. Can be one of the following constants:

Constant | Type of the control
XCTL_AUTORADIO | Radio button with automatic toggling
XCTL_BUTTON | Pushbutton
XCTL_CHECKBOX | Check box
XCTL_COMBO | Combo box (with edit-box portion)
XCTL_DROPDOWN | Dropdown list (combo box without edit-box portion)
XCTL_EDIT | Edit box
XCTL_GROUP | Group box
XCTL_LIST | List box
XCTL_RADIO | Radio button without automatic toggling
XCTL_PROGRESS | Progress bar
XCTL_SCROLLBAR | Scroll bar
XCTL_SLIDER | Slider (trackbar)
XCTL_SPIN | Synonym for XCTL_UPDOWN
XCTL_STATIC | Static control (text or image)
XCTL_STATUS | Status bar
XCTL_TAB | Tab control
XCTL_TRACKBAR | Synonym for XCTL_SLIDER
XCTL_UPDOWN | Up-down control (spin)

iStyle
An OR combination of control styles.

[iX, iY]
Coordinates of control's top left corner, relative to xWnd's client rectangle. If absent, (0, 0) is used.

[iWidth, iHeight]
Width and height of the control, in pixels. If absent, value of CW_USEDEFAULT is used, indicating that the system should pick window dimensions.

[iExStyle]
A combination of extended window styles for the control. If absent, extended style is set to 0.

[iAddStyle]
Any additional style specific to the created control. This will be combined with the common styles specified by the iStyle argument above. If absent, no additional styles apply.

Return Value

If successful, the return value is non-zero and it presents assigned identifier of the control. Normally, this value is equal to ID argument. However, if another control exist with the same ID, the function will pick up another ID and assign it to the control.

Remarks

If the suggested ID is duplicated with another control in the same window, the function finds the next free ID and assigns it to the control. Developers should take care either to provide unique IDs or to use return value from XCtlCreate to keep track of control creation/destruction.

All controls are automatically destroyed when the parent window is destroyed.

See Also

XCtlDestroy

Wrapped APIs

CreateWindowEx

Module

XFTCTRL.f90


XCtlDestroy

XCtlDestroy

XCtlDestroy destroys a control with specified ID from a window.

LOGICAL FUNCTION XCtlDestroy(xWnd, ID)

TYPE(X_WINDOW)::                xWnd
INTEGER, INTENT(IN)::           ID

Arguments

xWnd
 X_WINDOW structure representing control's parent window.

ID
Identifier of the control.

Return Value

If successful, the return value is .TRUE.

See Also

XCtlDestroyAll, XCtlCreate

Remarks

All controls are automatically destroyed when their parent window is destroyed.

Wrapped APIs

DestroyWindow, RemoveProp

Module

XFTCTRL.f90


XCtlDestroyAll

XCtlDestroyAll

XCtlDestroyAll destroys all controls from a specified window.

SUBROUTINE XCtlDestroyAll(xWnd)

TYPE(X_WINDOW)::                xWnd

Arguments

xWnd
 X_WINDOW structure representing the controls' parent window.

ID
Identifier of the control.

See Also

XCtlDestroy, XCtlCreate

Remarks

All controls are automatically destroyed when their parent window is destroyed.

Wrapped APIs

DestroyWindow, RemoveProp

Module

XFTCTRL.f90


XCtlGet

XCtlGet

XCtlGet retrieves a property of the control. XCtlGet is generic name for four routines: XCtlGetInt, XCtlGetChar, XCtlGetLog, and XCtlGetArray.

LOGICAL FUNCTION XCtlGet(xWnd, ID, Value, iAction)

TYPE(X_WINDOW)::                xWnd
INTEGER, INTENT(IN)::           ID
INTEGER/CHARACTER(*)/LOGICAL/INTEGER(:), POINTER, INTENT(OUT):: Value
INTEGER, OPTIONAL, INTENT(IN):: iAction

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID
Unique numeric identifier of the control, as set in dialog editor or during control creation by XCtlCreate.

Value
A scalar integer, string, or logical, or an integer pointer array representing the value of control's property. When Value is an array, it must have POINTER attribute and be NULLIFYed before the call. See remarks below.

[iAction]
An integer constant describing the property of control to be retrieved. See Control properties page for description of available properties and their meaning. If absent, CTL_DEFAULT is assumed, which carries different meaning depending on control's type.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XCtlSet, XCtlCreate

Remarks

When Value is an array, it must have POINTER attribute and be NULLIFYed before the call. The function allocates the array and the calling routine must free it after use, otherwise a memory leak will occur. This feature will probably be changed to ALLOCATABLE array in future Xeffort versions.

Wrapped APIs

SendMessage, WM_CTLCOLOR*

Module

XFTCTRL.f90


XCtlGetPos

XCtlGetPos

XCtlGetPos function returns a control's current position and size.

LOGICAL FUNCTION XCtlGetPos(xWnd, ID, iX, iY, iWidth, iHeight)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            ID
INTEGER, OPTIONAL, INTENT(OUT)::  iX,iY
INTEGER, OPTIONAL, INTENT(OUT)::  iWidth, iHeight

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID
Unique numeric identifier of the control, as set in dialog editor or during control creation by XCtlCreate.

[iX, iY]

Position of top-left corner of the control, in pixels expressed as offset from origin of parent's client area.

[iWidth, iHeight]

Control window width and height, in pixels.

Return Value

If successful, the function returns .TRUE.

See Also

XCtlMove

Wrapped APIs

GetWindowPlacement

Module

XFTCTRL.f90


XCtlMove

XCtlMove

XCtlMove function sets a control position, size, and visibility.

LOGICAL FUNCTION XCtlMove(xWnd, ID, iX, iY, iWidth, iHeight, idAfter)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            ID
INTEGER, OPTIONAL, INTENT(IN)::  iX,iY
INTEGER, OPTIONAL, INTENT(IN)::  iWidth, iHeight
INTEGER, OPTIONAL, INTENT(IN)::  idAfter

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID
Unique numeric identifier of the control, as set in dialog editor or during control creation by XCtlCreate.

[iX, iY]

Position of top-left corner of the control, in pixels expressed as offset from origin of parent's client area. If absent, the control is not moved.

[iWidth, iHeight]

Window width and height, in pixels. If used, both must be present. If absent, the control is not resized

[idAfter]

If present, the function moves the control ID immediately above the control idAfter in Z-(vertical) order. If idAfter has value HWND_TOP, the control is moved to the top of Z-order.

Remarks

If several controls should be moved/sized simultaneously, use XBeginCtlMove and XEndCtlMove before and after this function. In that case, the controls' position are updated after call to XEndCtlMove.

Return Value

If successful, the function returns .TRUE.

See Also

XBeginCtlMove, XEndCtlMove, XCtlGetPos

Wrapped APIs

SetWindowPos, DeferWindowPos

Module

XFTCTRL.f90


XCtlSet

XCtlSet

XCtlSet sets a property of the control. XCtlSet is generic name for four routines: XCtlSetInt, XCtlSetChar, XCtlSetLog, and XCtlSetArray

LOGICAL FUNCTION XCtlSet(xWnd, ID, Value, iAction)

TYPE(X_WINDOW)::                xWnd
INTEGER, INTENT(IN)::           ID
INTEGER/CHARACTER(*)/LOGICAL/INTEGER(:), INTENT(IN):: Value
INTEGER, OPTIONAL, INTENT(IN):: iAction

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID
Unique numeric identifier of the control, as set in dialog editor or during control creation by XCtlCreate.

Value
An integer, string, or logical scalar, or an integer array representing the value of control's property. Meaning of the value depends on iAction argument.

[iAction]
An integer constant describing the property of control to be set. See Control properties page for description of available properties and their meaning. If absent, CTL_DEFAULT is assumed, which carries different meaning depending on control's type.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XCtlGet, XCtlCreate

Wrapped APIs

SendMessage, WM_CTLCOLOR*

Module

XFTCTRL.f90


XCtlSetSub

XCtlSetSub

XCtlSetSub installs a handler routine for specified control. The handler routine is called whenever specified event occurs on the control.

 LOGICAL FUNCTION XCtlSetSub(XWnd, ID, lpfnCallback, iEvent)
TYPE(X_WINDOW), INTENT(INOUT)::   xWnd
INTEGER, INTENT(IN)::
ID
INTERFACE
SUBROUTINE lpfnCallback(xWnd, ID, iEvent)
USE XFTTYPES
TYPE(X_WINDOW):: xWnd
INTEGER::        ID
INTEGER::        iEvent
END SUBROUTINE
END INTERFACE
INTEGER, OPTIONAL, INTENT(IN)::    iEvent

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID
Identifier of the control, as set in dialog editor or during control creation by XCtlCreate.

lpfnCallback
Subroutine of prototype described above, which is called whenever event specified by iEvent argument. ID argument represents ID of the control. iEvent argument specifies the type of event that occurred. The same callback routine may be used for different controls and/or different events, provided that it properly distinguishes

[iEvent]
An integer constant describing the event for whom the handler is installed. If absent, default event is assumed. See Control Events page for description of available controls.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

Remarks

XFTWND:XSetCommand function can also be used for handling events from controls. That function is more powerful, as it provides a broader spectrum of events. If a handler is installed via both XSetCommand and XCtlSetSub, the later takes precedence; the former is never called. Such situations should be avoided.

See Also

XSetCommand

Module

XFTCTRL.f90


XCtlSendMessage

XCtlSendMessage

XCtlSendMessage function sends a message to a control which is a child of specified window.

INTEGER FUNCTION XCtlSendMessage(xWnd, ID, Msg, wParam, lParam)

TYPE(X_WINDOW)::            xWnd
INTEGER, INTENT(IN)::       ID, Msg, wParam, lParam

Arguments

xWnd
 X_WINDOW structure representing the control's parent window.

ID

ID of the control.

Msg

Message code.

wParam

First message parameter. The meaning depends on message code.

lParam

The second message parameter. The meaning depends on message code.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

See Also

Window Events, XSendMessage

Wrapped APIs

SendMessage

Module

XFTCTRL.f90


XSetDialogFocus

XSetDialogFocus

XSetDialogFocus function sets focus to a given dialog control, as if the user had clicked in, or tabbed to, the specified control. This function is useful to set an initial focus in the pages of a tabbed dialog.

LOGICAL FUNCTION XSetDialogFocus (xWnd, ID)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            ID

Arguments

xWnd
X_WINDOW structure representing the control's parent dialog window.

ID
Unique numeric identifier of the control, as set in dialog editor or during control creation by XCtlCreate .

Return Value

If successful, the function returns .TRUE.

Module

XFTextra.f90


XBeginCtlMove

XBeginCtlMove

XBeginCtlMove prepares for moving/sizing of several controls in window xWnd simultaneously. Without this function, movement of several controls is slower and flickering.

LOGICAL FUNCTION XBeginCtlMove(xWnd)

TYPE(X_WINDOW):: xWnd

Arguments

xWnd
 X_WINDOW structure representing the controls' parent window.

Return Value

If successful, the functions returns .TRUE.

Remarks

Every XBeginCtlMove call must be terminated by a matching XEndCtlMove call. XBeginCtlMove fails if called twice (but does not produce harmful effects).

See Also

XCtlMove, XEndCtlMove

Wrapped APIs

BeginDeferWindowPos

Module

XFTCTRL.f90


XEndCtlMove

XEndCtlMove

XEndCtlMove function ends the moving/sizing of several windows simultaneously that was initiated by XBeginCtlMove, and updates positions of all affected windows.

LOGICAL FUNCTION XEndCtlMove()

Return Value

If successful, the function returns .TRUE.

Remarks

Every XBeginCtlMove call must be terminated by a matching XEndCtlMove call. XEndCtlMove fails if a XBeginCtlMove was not called.

See Also

XBeginCtlMove, XCtlMove

Wrapped APIs

EndDeferWindowPos

Module

XFTCTRL.f90


XItem

XItem

XItem function has the sole purpose to convert any user-defined type into opaque type X_ITEM. This conversion is necessary in order to set or retrieve a ListView item using XCtlSet or XCtlGet.

FUNCTION XItem(Item)

TYPE(X_ITEM)::                  XItem
!DEC$ATTRIBUTES NO_ARG_CHECK::  Item

Arguments

Item
Any user-defined type or built-in type.

Return Value

The function returns a type X_ITEM (which, by the way, contains only the address of the argument, but user should not care about it). This type is used to disambiguate calls to XCtlSet or XCtlGet.

See Also

XCtlSet, XCtlGet, ListView Controls Overview, ListView Controls Reference

Module

XFTListView.f90


XLV_OnColumnClick

XLV_OnColumnClick

XLV_OnColumnClick is the default CTL_COLUMNCLICK callback for ListView controls. It toggles the up/down arrow image on the ListView header control and sorts the items of ListView control in ascending or descending order, according to the parsing format.

SUBROUTINE XLV_OnColumnClick(xWnd, id, iSubItem)

TYPE(X_WINDOW), INTENT(IN):: xWnd
INTEGER, INTENT(IN)::        ID
INTEGER, INTENT(IN)::        iSubItem

Arguments

xWnd
 X_WINDOW structure representing control's parent window.

idListView
Numeric identifier of the ListView control to be updated.

iSubItem
Column of the control which should be sorted.

See Also

ListView Controls Overview , ListView Controls Reference

Module

XFTListView.f90


XLVUpdate

XLVUpdate

XLVUpdate updates the display of virtual ListView control. This function should be called when the value of one or more useritems is changed and the ListView control should reflect the new state.

LOGICAL FUNCTION
XLVUpdate(xWnd, idListView, iSel)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
INTEGER, INTENT(IN)::
idListView
INTEGER, OPTIONAL, INTENT(IN)::  iSel(:)

Arguments

xWnd
 X_WINDOW structure representing control's parent window.

idListView
Numeric identifier of the ListView control to be updated.

iSel
Optional array of item indices to be updated. If absent, all items are updated.

Return Value

If successful, the function returns .TRUE. Otherwise, it returns .FALSE.

See Also

ListView Controls Overview , ListView Controls Reference

Wrapped APIs

CreateWindowEx

Module

XFTListView.f90


XFTDialog Overview

XFTDialog Overview

XFTDialog module is used for handling of dialogs. It contains only routines for loading, displaying and destroying the dialog. Handling of controls within the dialog is done by routines from XFTCtrl.

XFTDialog has interface similar to DFLOGM shipped by Compaq/Intel with Visual Fortran compiler. Additional features of XFTDialog/XFTCtrl can be used with old codes written using DFLOGM using XFLOGM/DFLOGM compatibility layer.

Dialogs are windows whose main purpose is to contain controls. Dialogs are windows, and it is difficult to make a precise distinction when a window can be referred to as a dialog and when not. Layout of dialogs and their controls is usually predefined in resource editor. Thus, about the only difference between X_WINDOWs and dialogs is how they start their life: the former are created using XCreateWindow and the latter using XLoadDialog routine. All XFTWnd routines are applicable to dialogs as well. Module XFTDialog contains routines for dialog-specific operations.

Reference


XFTDialog Reference

XFTDialog Reference

Overview

Dialog Creation and Destruction

XLoadDialog

XModalDialog

XModelessDialog

XEndDialog

XDestroyDialog

Message Box

XMessageBox

XUserAsk

XUserInfo

XUserWarn

XUserStop


XLoadDialog

XLoadDialog

XLoadDialog loads - but does not display - a dialog template from resource section of specified module.

LOGICAL
FUNCTION  XLoadDialog(ID, xDlg, xOwner, hModule)

INTEGER, INTENT(IN)::               ID
TYPE(X_WINDOW), INTENT(OUT)::                    xDlg
TYPE(X_WINDOW),  OPTIONAL, INTENT(IN)::     xOwner
INTEGER, OPTIONAL, INTENT(IN)::     hModule

Arguments

ID
Integer identifier of the dialog template, as set up in resource editor.

xDlg
Type X_WINDOW representing newly created dialog. This variable must not represent another valid Xeffort window before the call, as it may cause undesired behavior and various run-time crashes. See XFTWND Design Considerations.

[xOwner]
A X_WINDOW structure representing the owner window of given dialog. The dialog will always be on top of its owner window. If the dialog has DS_CENTER style, it will be centered relative to owner window's client area. If xOwner is absent, the following rules apply:
- If the main window of the application, referred to as XW_FRAME, exists, it will be used as the owner;
- Otherwise, the dialog will have no owner window (desktop window will be its formal owner).
XGetWindow function can be used to convert a window handle to a valid X_WINDOW.

[hModule]
Identifies the handle of a Dll module (returned by XGetInstance or LoadLibrary API) if the specified resource ID is to be searched within resources of a dll. If absent, the dialog is attempted to be loaded from the .exe file which started the current process.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XModalDialog, XModelessDialog, XDestroyDialog

Wrapped APIs

CreateDialogParam

Module

XFTDialog.f90


XModalDialog

XModalDialog

XModalDialog function displays the dialog previously loaded by XLoadDialog as modal. Modal dialogs disable their owner window and contain a modal loop. As result, this function is not exited until user closes the dialog using a button or XEndDialog is called.

INTEGER
FUNCTION XModalDialog(xDlg, hParent, bAppModal)

TYPE(X_WINDOW)::                xDlg
INTEGER, OPTIONAL, INTENT(IN):: hParent
LOGICAL, OPTIONAL, INTENT(IN):: bAppModal

Arguments

xDlg
Type X_WINDOW representing the dialog previously loaded by XLoadDialog.

hParent
Handle of the window which will serve as parent for the dialog. This argument is included for compatibility with XFLOGM applicatons and should not be used by applications which use XFTDialog directly - instead, xOwner argument to XLoadDialog is preferred.

bAppModal
Specifies whether the dialog should be modal respective only to its owner (parent) (.FALSE.) or to all other windows in the application (.TRUE.). When bAppModal is .TRUE., all other windows in the application will be disabled during execution. This affects the status of sibling modeless dialogs and other WS_POPUP windows, which are by default not disabled by XModalDialog. If absent, bAppModal defaults to .FALSE.

Return Value

The function returns the ID of the control that caused the dialog to exit, or code programatically set by XEndDialog. By default, buttons with IDs IDOK (=1) and IDCANCEL (=2), if present, cause the dialog to exit, unless overriden by appropriate XCtlSetSub.

Remarks

Xeffort modal dialogs do not use native DialogBox(Param) API. Instead, modal behavior is emulated. On API level, XLoadDialog loads the dialog and runs it as modeless. XModalDialog displays the dialog, disables its owner window, and enters a modal message loop. Dialog initialization and termination callbacks, if any, are called at the beginning and end of XModalDialog. As result, displaying the dialog prematurely using XShowWindow or XCtlSet(CTL_VISIBLE) can lead to undesired effects.

See Also

XLoadDialog, XModelessDialog, XEndDialog

Wrapped APIs

ShowWindow, EnableWindow, GetMessage, IsDialogMessage, TranslateMessage, DispatchMessage

Module

XFTDialog.f90


XModelessDialog

XModelessDialog

XModelessDialog function displays the dialog previously loaded by XLoadDialog as modeless. Modeless dialogs do not disable their owner window. They can have either WS_CHILD or WS_POPUP window style. This function is asynchronous, i.e. the dialog is displayed as requested and it is exited immediately - compare XModalDialog.

LOGICAL FUNCTION XModelessDialog(xDlg, nCmdShow)

TYPE(X_WINDOW)::                 xDlg
INTEGER, OPTIONAL, INTENT(IN)::  nCmdShow

Arguments

xDlg
Type X_WINDOW representing the dialog previously loaded by XLoadDialog.

[nCmdShow]
One of SW_ constants describing visibility of the dialog. If absent, the dialog is displayed (SW_SHOW).

Return Value

If successful, the function returns .TRUE.

Remarks

Dialog-initialization callback (XCtlSetSub(CTL_DEFAULT)), if defined, is called by this function before the dialog is displayed.

See Also

XLoadDialog, XModalDialog

Wrapped APIs

ShowWindow

Module

XFTDialog.f90


XEndDialog

XEndDialog

XEndDialog closes the modal dialog initiated with XModalDialog, i.e. it causes XModalDialog function to exit. This function has no effects for modeless dialogs. This function is useful only when called from callbacks installed with XCtlSetSub or XSetCommand, where the callback wants to exit the dialog programmatically.

SUBROUTINE
XEndDialog(xDlg, ID)

TYPE(X_WINDOW)::       xDlg
INTEGER, INTENT(IN)::  ID

Arguments

xDlg
Type X_WINDOW representing the modal dialog to be closed.

ID
Return value of the XModalDialog function.

Remarks

The function does not close the dialog immediately, i.e. any subsequent statement after the call to XEndDialog will still be executed. The dialog will be closed when the callback routine which called it returns.

See Also

XModalDialog, XDestroyDialog

Module

XFTDialog.f90


XDestroyDialog

XDestroyDialog

XDestroyDialog destroys the given dialog, all controls within it, including any additional resources, and frees the xDlg variable associated with it. Any dialog initiated with XLoadDialog must be eventually destroyed using XDestroyDialog.

SUBROUTINE XDestroyDialog(xDlg)

TYPE(X_WINDOW), INTENT(OUT):: xDlg

Arguments

xDlg
Type X_WINDOW representing the dialog.

See Also

XLoadDialog

Wrapped APIs

DestroyWindow

Module

XFTDialog.f90


XMessageBox

XMessageBox

XMessageBox function operates a message box.

INTEGER FUNCTION XMessageBox(sText, sCaption, iFlags, xWnd, idIcon, &
sRegKey, sRegValue, hModule, sUserButton)

CHARACTER(*), INTENT(IN):: sText
CHARACTER(*), OPTIONAL, INTENT(IN):: sCaption
INTEGER, OPTIONAL, INTENT(IN):: iFlags
TYPE(X_WINDOW), OPTIONAL, INTENT(IN):: xWnd
INTEGER, OPTIONAL, INTENT(IN):: idIcon
CHARACTER(*), OPTIONAL, INTENT(IN):: sRegValue
CHARACTER(*), OPTIONAL, INTENT(IN):: sRegKey
INTEGER, OPTIONAL, INTENT(IN):: hModule
CHARACTER(*), OPTIONAL, INTENT(IN):: sUserButton(:)

Arguments

sText
Text to display.

[sCaption]
Caption of the message box. If absent, the default is "Error".

[iFlags]
Set of flags which determine number and types of buttons, message-box icon and modality:

Button type flags (mutually exclusive). If sUserButton array is present, this flag is ignored.

Flag | Meaning
MB_ABORTRETRYIGNORE | Abort, Retry, and Ignore buttons.
MB_OK | OK button. This is the default.
MB_OKCANCEL | OK and Cancel buttons.
MB_RETRYCANCEL | Retry and Cancel buttons.
MB_YESNO | Yes and No buttons.
MB_YESNOCANCEL | Yes, No, and Cancel buttonsl.

By default, the first button is the default one. In addition, one of the following flags can be specified to alter that behavior:

Flag | Meaning
MB_DEFBUTTON2 | The second button is the default button.
MB_DEFBUTTON3 | The third button is the default button.
MB_DEFBUTTON4 | The fourth button is the default button.

Icons:

Flag | Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING | An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK | An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONQUESTION | A question-mark icon appears in the message box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND | A stop-sign icon appears in the message box.

If a user-defined icon is specified in idIcon argument, it overrides this flag.

Modality:

Flag | Meaning
MB_APPLMODAL | The message box is modal to the parent window, i.e. it disables it. However, other visible popup windows (such as modeless dialogs) in the current thread are not disabled. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.
MB_SYSTEMMODAL | Same as MB_APPLMODAL except that the message box has the WS_EX_TOPMOST style. Use system-modal message boxes to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). This flag has no effect on the user's ability to interact with windows other than those associated with hWnd.
MB_TASKMODAL | All the top-level windows belonging to the current thread are disabled. Use this flag when the calling application or needs to prevent input to other windows in the calling thread without suspending other threads.

In addition, you can specify the following flags:

MB_DEFAULT_DESKTOP_ONLY | The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on. Not supported in the current Xeffort release.
MB_HELP | Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event. Not supported in the current Xeffort release.
MB_RIGHT | The text is right-justified.
MB_RTLREADING | Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems. Not supported in the current Xeffort release.
MB_TOPMOST | The message box will appear on top of all system windows. rather than just on top of the parent window.

[xWnd]
A X_WINDOW structure representing the owner window of the message box. The message box will always be on top of its owner, centered relative to its window. If xOwner is absent, the following rules apply:
- If the main window of the application, referred to as XW_FRAME, exists, it will be used as the owner;
- Otherwise, the dialog will have no owner window (desktop window will be its formal owner).
XGetWindow function can be convert a window handle to a valid X_WINDOW.

[i dIcon]
Identifier of an icon in the current executable to be displayed instead of one of default (MB_) icons. If hModule is also present, the icon is loaded from the module (.exe or .dll) identified by hModule handle. See XGetInstance.

[sRegKey, sRegValue]
If present, an additional check-box titled "Show this message in the future" appears, with check-mark on. If this box remains checked by the user, the message box behaves as usual; otherwise, the message box will store the user's answer in the registry value sRegValue in sRegKey key and all subsequent calls to XMessageBox with these parameters (even in later sessions) will return user's stored answer without displaying the message box. The application can reset this behavior only by altering the registry value in question.

sRegKey must identify an existing key in HKEY_CURRENT_USER branch; othewise, the function will fail. sRegValue must identify a value within that key (not necessarily an existing one). If the checkbox remains checked, the function either does not alter the value. If the checkbox is unchecked, the function stores the returned button ID. See XFTReg Overview.

[hModule]
Identifies the module (.exe or .dll) from which the icon identified by idIcon should be loaded. If absent, the current executable is searched for idIcon resource. If idIcon is not present, this argument is ignored. See XGetInstance.

[sUserButton]
Optional array of (up to 4) button titles. If present, if overrides button definitions in iFlags argument. Use a preceding ampersand (&) within the string to indicate the mnemonic (underlined) letter. For example, (/"&Alpha", "&Beta"/) specifies that there will be two buttons, titled Alpha and Beta. If present, the return value is index of the selected button. MB_DEFBUTTON* flags still apply.

Return Value

The function returns the ID of the button that caused the message box to exit. If sUserButton is absent, can be one of the following values:

Value | Meaning
IDABORT | Abort button.
IDCANCEL | Cancel button.
IDIGNORE | Ignore buttond.
IDNO | No button.
IDOK | OK button.
IDRETRY | Retry button.
IDYES | Yes button.

If sUserButton is present, the return value is 1-based index of the selected button.

If the function fails, the return value is zero.

Remarks

Unlike standard MessageBox API, the XMessageBox function centers the message box relative to the parent window (by default, XW_FRAME), not to the screen.

The function will display localized button captions where available. However, the text "Show this message in the future" will not appear localized.

Note that currently, if sUserButton is present, the routine will not enlarge the button widths to fit the string. Thus, keep the strings short (up to about 20 characters).

Wrapped APIs

DialogBoxIndirectParam

Module

XFTDialog.f90


XUserInfo

XUserInfo, XUserWarn, XUserStop

Each of these routines displays a Message Box with an OK button to inform the user of some condition. They differ only in the icon used and the alert sound played.

XUserInfo displays an Informational Message Box.
XUserWarn displays a Warning Message Box.
XUserStop displays an Error Message Box.

SUBROUTINE XUserInfo (sCaption, sMessage, xOwner)
SUBROUTINE XUserWarn (sCaption, sMessage, xOwner)
SUBROUTINE XUserStop (sCaption, sMessage, xOwner)

CHARACTER(*), INTENT(IN)::  sCaption
CHARACTER(*), INTENT(IN)::  sMessage
TYPE(X_WINDOW), OPTIONAL::  xOwner

Arguments

sCaption

Text that is to appear in the title bar of the message box.

sMessage

Text that is to appear in the body of the message box.

[xOwner]

An optional X_WINDOW structure representing the owner window of the message box. The message box will always be on top of its owner, centered relative to its window. If xOwner is absent, the following rules apply:
- If the main window of the application, referred to as XW_FRAME, exists, it will be used as the owner;
- Otherwise, the dialog will have no owner window (desktop window will be its formal owner).

Regardless of the owner, these subroutines give the message box a TOPMOST style, so it will appear above the other windows in your application. Therefore the owner window specification only effects the initial position of the message box.

Remarks

The actual alert sound heard depends on the user's "Windows Sounds" definitions in the Control Panel.
XUserInfo plays the "Asterisk" sound.
XUserWarn plays the "Exclamation" sound.
XUserStop plays the "Critical Stop" sound.

The Message Box is modal; your application does not regain control until the user hits the OK button. These routines are wrappers for XMessageBeep andXMessageBox.

See Also

XUserAsk, XMessageBeep, XMessageBox

Module

XFTextra.f90


XUserAsk

XUserAsk

XUserAsk querys the user by using a multiple-button Message Box.

INTEGER
FUNCTION XUserAsk (sCaption, sMessage, iBtn, iDef, xOwner)

CHARACTER(*), INTENT(IN)  ::  sCaption
CHARACTER(*), INTENT(IN)  ::  sMessage
INTEGER, OPTIONAL, INTENT(IN) :: iBtn
INTEGER, OPTIONAL, INTENT(IN) :: iDef
TYPE(X_WINDOW), OPTIONAL      ::
xOwner

Arguments

sCaption

Text that is to appear in the title bar of the message box.

sMessage

Text of the question that is to appear in the body of the message box.

[iBtn]
One of the following to specify the response buttons that will be available to the user.

MB_YESNO | The message box contains two push buttons: Yes and No.
MB_OKCANCEL | The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL | The message box contains two push buttons: Retry and Cancel.
MB_YESNOCANCEL | The message box contains three push buttons: Yes, No, and Cancel.
MB_ABORTRETRYIGNORE | The message box contains three push buttons: Abort, Retry, and Ignore.
If iBtn is omitted, or is not one of the above values, a value of MB_YESNO is assumed. The buttons appear in the named order, e.g., for MB_YESNO the "Yes" button is first and the "No" button second.

[iDef]
Either a 1 or 2 (or 3) to signify that the 1st or 2nd (or 3rd) button is to be the default button. If not present, the first button is the default button.

[xOwner]

An optional X_WINDOW structure representing the owner window of the message box. The message box will always be on top of its owner, centered relative to its window. If xOwner is absent, the following rules apply:
- If the main window of the application, referred to as XW_FRAME, exists, it will be used as the owner;
- Otherwise, the dialog will have no owner window (desktop window will be its formal owner).

Regardless of the owner, this function gives the message box a TOPMOST style, so it will appear above the other windows in your application. Therefore the owner window specification only affects the initial position of the message box.

Return Value

The return value is either 1, 2, (or 3) depending on whether the user hits the 1st, 2nd, (or 3rd) answer button, respectively.

Remarks

Alerts by playing the sound associated with Windows "Question". The Message Box is modal; your application does not regain control until the user responds to the question. This function is a wrapper for XMessageBeep and XMessageBox .

See Also

XUserInfo,XMessageBeep, XMessageBox

Module

XFTextra.f90


XFTFile Overview

XFTFile Overview

Overview

XFTFile library is set of routines which wrap Windows File Operations. Wrappers for "Open" "Save" and "Browse for Folder" dialogs are provided, as well as several routines for common tasks which are not part of standard Fortran I/O library.

Reference


XFTFile Reference

XFTFile Reference

Overview

Common File Dialogs

XBrowse

XGetOpenFile

XGetSaveFile

File Operations

XCreateShortcut

XEnumFiles
XEnvironmentString

XSystemPath


XBrowse

XBrowse

XBrowse function displays the common "Browse for Folder" dialog box, which allows the user to select a directory.

LOGICAL FUNCTION XBrowse(xWnd, sDir, iFlags, iRootDir, sTitle, iX, iY)

!DEC$IF DEFINED(XLITE)
INTEGER, INTENT(IN)::                xWnd
!DEC$ELSE
TYPE (X_WINDOW), INTENT(IN)::        xWnd
!DEC$ENDIF
CHARACTER(*), INTENT(INOUT)::        sDir
INTEGER, OPTIONAL, INTENT(IN)::      iFlags
INTEGER, OPTIONAL, INTENT(IN)::      iRootDir
CHARACTER(*), OPTIONAL, INTENT(IN):: sTitle
INTEGER, OPTIONAL, INTENT(IN)::      iX, iY

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window which will serve as parent for the dialog. For QuickWin projects, the handle can be obtained using GETHWNDQQ. . This handle can be NULL, indicating that desktop will serve as parent.

Full Xeffort Version: X_WINDOW structure describing the parent window. The window has to be a valid Xeffort window created by XCreateWindow or bound to Xeffort using XBindWindow or XSubclassWindow.

sDir
Full path to the selected directory (without trailing backslash). On input, this directory is used as the initial directory selected in the tree. On output, it contains the selected directory. If empty on input, root of the namespace ("My computer"). is initially selected.

[iFlags]
An .OR. combination of the follwing flags, which control additional properties of the dialog.

XBIF_BROWSEFORCOMPUTER | Only returns computers. If the user selects anything other than a computer, the OK button is grayed.
XBIF_BROWSEFORPRINTER | Only returns printers. If the user selects anything other than a printer, the OK button is grayed.
XBIF_DONTGOBELOWDOMAIN | Does not include network folders below the domain level in the tree view control.
XBIF_RETURNFSANCESTORS | Only returns file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.
XBIF_RETURNONLYFSDIRS | Only returns file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.
XBIF_STATUSTEXT | Includes a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box. Not supported by Xeffort.

If not present, zero is used, denoting general browsing for directories.

[iRootDir]
Specifies root folder of the displayed namespace. Can be one of the following constants, specifying alternate root for tree-view:

XCSIDL_BITBUCKET | Recycle bin - file system directory containing file objects in the user’s recycle bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.
XCSIDL_COMMON_DESKTOP | File system directory that contains files and folders that appear on the desktop for all users.
XCSIDL_COMMON_PROGRAMS | File system directory that contains the directories for the common program groups that appear on the Start menu for all users.
XCSIDL_COMMON_STARTMENU | File system directory that contains the programs and folders that appear on the Start menu for all users.
XCSIDL_COMMON_STARTUP | File system directory that contains the programs that appear in the Startup folder for all users. The system starts these programs whenever any user logs on to Windows NT or starts up Windows 95.
XCSIDL_CONTROLS | Control Panel - virtual folder containing icons for the control panel applications.
XCSIDL_DESKTOP | Windows desktop - virtual folder at the root of the name space.
XCSIDL_DESKTOPDIRECTORY | File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).
XCSIDL_DRIVES | My Computer - virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
XCSIDL_FONTS | Virtual folder containing fonts.
XCSIDL_NETHOOD | File system directory containing objects that appear in the network neighborhood.
XCSIDL_NETWORK | Network Neighborhood - virtual folder representing the top level of the network hierarchy.
XCSIDL_PERSONAL | File system directory that serves as a common respository for documents. (i.e. "My Documents")
XCSIDL_PRINTERS | Printers folder (virtual folder containing installed printers).
XCSIDL_PROGRAMS | File system directory that contains the user’s program groups (which are also file system directories).
XCSIDL_RECENT | File system directory that contains the user’s most recently used documents.
XCSIDL_SENDTO | File system directory that contains Send To menu items.
XCSIDL_STARTMENU | File system directory containing Start menu items.
XCSIDL_STARTUP | File system directory that corresponds to the user’s Startup program group.
XCSIDL_TEMPLATES | File system directory that serves as a common repository for document templates.

If not present, default namespace root ("My Computer") is used

[sTitle]
Title of the dialog. If not present, default is "Browse".

[iX,iY]
Position of the dialog's upper left corner, in pixels, relative to screen. If omitted, XBrowse centers the dialog relative to the parent window.

Return Value

If successful, return value is .TRUE. If an error occurs or if user cancels the selection, return value is .FALSE.

See Also

XGetSaveFile, XGetOpenFile.

Wrapped APIs

SHBrowseForFolder, SHGetSpecialFolderLocation

Module

XFTFILE.f90


XCreateShortcut

XCreateShortcut

XCreateShortcut creates a shortcut (.lnk) file pointing to given target.

INTEGER FUNCTION XCreateShortcut(sTarget, sShortcut, sDescription, &
                 sArguments, sIconPath, iIconIndex, sWorkingDir)

CHARACTER(*), INTENT(IN)::           sTarget
CHARACTER(*), INTENT(IN)::           sShortcut
CHARACTER(*), OPTIONAL, INTENT(IN):: sDescription
CHARACTER(*), OPTIONAL, INTENT(IN):: sArguments
CHARACTER(*), OPTIONAL, INTENT(IN):: sIconPath
INTEGER, OPTIONAL, INTENT(IN)::      iIconIndex
CHARACTER(*), OPTIONAL, INTENT(IN):: sWorkingDir

Arguments

sTarget
Full path to the target file or directory. Full path can be ommited for programs that are in system search PATH (e.g. Explorer, Notepad).

sShortcut
Full path of the shortcut to file be created. The shortcut should have .lnk extension.

[sDescription]
An arbitrary string containing description of the file. The description appears in "Comments" field of the shortcut properties and in the tooltip over the shortcut in Explorer. If not present, empty description is given.

[sArguments]
Additional command-line arguments of the program.

[sIconPath]
Path to an .exe, .dll or .ico file containing the icon for the shortcut. If not present, default system rules are applied for the icon (for .exe files, the first icon from the .exe files; for document files, default filetype icon; for other unrecognized files, the default icon).

[iIconIndex]
If sIconPath is present, this argument specifies the zero-based icon index from the .exe or .dll file.

[sWorkingDir]
If present, this argument specifies the initial working directory for the application being started from the shortcut.

Return Value

If successful, return value is zero. If an error occurs, the return value is COM error code (HRESULT) from the shell function which failed. You can use "Error lookup" utility from CVF program group to obtain textual description of the error.

Wrapped APIs

IShellLink::SetPath,
IShellLink::SetDescription, IShellLink::SetArguments,
IShellLink::SetIconLocation, IPersistFile::Save

Module

XFTFILE.f90


XEnumFiles

XEnumFiles

XEnumFiles enumerates all files in given directory (and its subdirectories) which satisfy given file filter and passes them to user-written callback procedure.

RECURSIVE INTEGER FUNCTION
 XEnumFiles(sDir, sFilter, fnCallback, bRecursive, lParam)

CHARACTER(*),INTENT(IN)::       sDir
CHARACTER(*),INTENT(IN)::       sFilter
INTERFACE
LOGICAL FUNCTION  fnCallback(sFile, lParam)
CHARACTER(*),INTENT(IN)::   sFile
!DEC$ATTRIBUTES NO_ARG_CHECK:: lParam
INTEGER::
lParam
END FUNCTION fnCallback
END INTERFACE
LOGICAL, OPTIONAL, INTENT(IN)::  bRecursive
!DEC$ATTRIBUTES NO_ARG_CHECK:: lParam
INTEGER, OPTIONAL, INTENT(IN)::  lParam

Arguments

sDir
Path of the directory to be searched, without trailing backslash. If empty, the current directory is searched.

sFilter
String that specifies a valid filename to be searched for, which can contain wildcard characters (* and ?).

fnCallback
Callback function of specified prototype. This function is called whenever XEnumFiles finds a file which satisfies given filter. The callback function should return .FALSE. if it wants the enumeration to be continued, or .TRUE. if it wants to stop the enumeration.

[bRecursive]
If present and .TRUE., subdirectories of sDir are searched as well. Otherwise, only sDir is searched for files satisfying given filter.

[lParam]
An arbitrary value defined by the calling application, which XEnumFiles just passes as second argument to fnCallback. If not present, 0 is passed. This parameter is useful if additional communication is needed between the routine which calls XEnumFiles and fnCallback; if lParam is used, there's no need for global variables.

Return Value

The function returns the total number of files enumerated.

Wrapped APIs

FindFirstFile, FindNextFile, FindClose

Module

XFTFILE.f90


XEnvironmentString

XEnvironmentString

XEnvironmentString retrieves the text string associated with an environment variable, or the pathname of the encompassing program.

LOGICAL FUNCTION XEnvironmentString (sVariable, sString)

CHARACTER(*), INTENT(IN)  ::    sVariable
CHARACTER(*), INTENT(OUT) ::    sString

Arguments

sVariable
 This argument takes one of three forms:

  1. Blank form. If sVariable is a blank string, sString is is returned as the fully-qualified path of the executable file of the current process, i.e., the full pathname of your program.

  2. Standard form. Here sVariable contains the name of an environment variable and sString is returned as its associated text. sVariable names are not case-sensitive.

  3. Substitution form. If sVariable contains, along with other text, one or more environment variable names enclosed in percent (%) signs, sString will contain the given sVariable text with the %name% items replaced by the associated environment string text. For example, "%TMP%\MyFile.txt" will yield the full pathname of the MyFile.txt file in the user's TEMP directory.

The following table lists some of the standard environment variables for Windows XP

sVariable | Description
TEMP or TMP | Returns the default temporary directory available to users who are currently logged on. Some applications may require TEMP while others require TMP.
ALLUSERSPROFILE | Returns the location of the All Users Profile.
APPDATA | Returns the location where applications store data by default.
COMPUTERNAME | Returns the name of the computer.
COMSPEC | Returns the exact path to the command shell executable.
HOMEDRIVE | Returns which local workstation drive letter is connected to the user's home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
HOMEPATH | Returns the full path of the user's home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
HOMESHARE | Returns the network path to the user's shared home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
LOGONSEVER | Returns the name of the domain controller that validated the current logon session.
NUMBER_OF_PROCESSORS | Specifies the number of processors installed on the computer.
OS | Returns the operating system name. Windows 2000 displays the operating system as Windows_NT.
PATH | Specifies the search path for executable files.
PATHEXT | Returns a list of the file extensions that the operating system considers to be executable.
PROCESSOR_ARCHITECTURE | Returns the chip architecture of the processor. Values: x86, IA64.
PROCESSOR_IDENTIFIER | Returns a description of the processor.
PROCESSOR_LEVEL | Returns the model number of the processor installed on the computer.
PROCESSOR_REVISION | Returns the revision number of the processor.
SYSTEMDRIVE | Returns the drive containing the Windows XP root directory (that is, the system root).
SYSTEMROOT | Returns the location of the Windows XP root directory.
USERDOMAIN | Returns the name of the domain that contains the user's account.
USERNAME | Returns the name of the user who is currently logged on.
USERPROFILE | Returns the location of the profile for the current user.
WINDIR | Returns the location of the operating system directory.

sString
 The returned text string. If it contains one of the standard directory specifications, the trailing backslash will be omitted.

Return Value

.TRUE. if successful. If .FALSE. and sString is returned blank then sVariable was not found; conversely, if .FALSE. but sString is not blank then sString is not large enough to hold the result.

Remarks

Windows maintains environment variable tables on both a per-user and on a system-wide basis. Thus both the user and system administrator may add/edit environment variables. Unfortunately, a system restart is generally required after such editing. In case of duplicate names, the user table value takes precedence over the system table.

See Also

 XSystemPath

Wrapped APIs

GetModuleFileName, GetEnvironmentVariable, ExpandEnvironmentStrings

Module

XFTfile.f90


XGetOpenFile

XGetOpenFile

XGetOpenFile function displays the common "Open" dialog box, which allows the user to select file(s) to be opened by the application. The function return selected directory and file name(s).

LOGICAL FUNCTION
XGetOpenFile(xWnd, sDir, nFiles, sFiles, iFlags, sExts, sTypes, &
sTitle, iX, iY)

!DEC$IF DEFINED(XLITE)
INTEGER, INTENT(IN)::                  xWnd
!DEC$ELSE
TYPE(X_WINDOW), INTENT(IN)::           xWnd
!DEC$ENDIF
CHARACTER(*), INTENT(INOUT)::        sDir
INTEGER, INTENT(OUT)::
nFiles
CHARACTER(*), INTENT(INOUT)::
sFiles(:)
INTEGER, OPTIONAL, INTENT(INOUT)::   iFlags
CHARACTER(*), OPTIONAL, INTENT(IN)::   sExts(:)
CHARACTER(*), OPTIONAL, INTENT(IN)::   sTypes(:)
CHARACTER(*), OPTIONAL, INTENT(IN)::   sTitle
INTEGER, OPTIONAL, INTENT(IN)::      iX, iY

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window which will serve as parent for the dialog. For QuickWin projects, the handle can be obtained using GETHWNDQQ. This handle can be NULL, indicating that desktop will serve as parent.

Full Xeffort Version: X_WINDOW structure describing the parent window. The window has to be a valid Xeffort window created by XCreateWindow or bound to Xeffort using XBindWindow or XSubclassWindow.

sDir
Directory where the file(s) are located (without trailing backslash). On input, this directory is used as the initial directory in which the dialog is displayed. On output, it contains directory where the user opened the file(s). If empty on input, current directory is displayed.

nFiles
Number of files selected by the user.

sFiles
(An array of) strings containing selected file name(s). File names do not contain directory path in it. If a scalar string or 1-sized array is provided, XGetOpenFile will allow selection of only one file; otherwise, multiple files are allowed for selection. On input, this string will be used as default file name (displayed in "File name" edit box).
To get a fully qualified file name(s) for opening, use construct
TRIM(sDir) // "\" // sFile

[iFlags]
An .OR. combination of OFN_ flags, which control additional properties of the dialog. Please refer to OPENFILENAME in Win32 SDK documentation for details. If not present, the following set of flags is used to specify that the new (Win95) style user-interface is used and that the file and path must exist.:

OFN_EXPLORER.OR.OFN_FILEMUSTEXIST.OR.OFN_PATHMUSTEXIST.OR.OFN_ENABLEHOOK

If you specify an iFlags argument, it must be a variable and the following flags are automatically included (since they are always required):

OFN_EXPLORER.OR.OFN_ENABLEHOOK

To see if the user checked the "Open as read-only" box. specify an iFlags and after XGetOpenFile returns, test iFlags with:

(IAND (iFlags, OFN_READONLY) .NE. 0)    ! .true. if read-only checked

[sExts]
An array of strings specifying allowed extensions of files. Each string must be in form "*.ext ". To specify multiple possible extensions for a single item, separate entries with a semicolon, e.g. "*.for;*.f90;*.f". If absent, the default is "*.*" .

[sTypes]
An array of strings specifying allowed file types, in human-readable form, i.e. "Text files (*.txt)". The array should be of the same SIZE as sExts; if not, lesser size of the two is used and the excess is ignored. If absent, the default is "All files (*.*)".

[sTitle]
Dialog title. The default is "Open".

[iX,iY]
Position of the dialog's upper left corner, in pixels, relative to screen. If omitted, XGetOpenFile centers the dialog relative to the parent window.

Return Value

If successful, return value is .TRUE. If an error occurs or if user cancels the selection, return value is .FALSE.

Remarks

XGetOpenFile is actually a generic name for two functions, which differ only in the dimension of sFiles argument (scalar vs. array). The former actually calls the latter and is provided for user's convenience, since most frequently only one file name is required.

See Also

XGetSaveFile, XBrowse.

Wrapped APIs

GetOpenFileName

Module

XFTFILE.f90


XGetSaveFile

XGetSaveFile

XGetSaveFile function displays the common "Save" dialog box, which allows the user to select file(s) to be saved by the application. The function returns selected the directory and file name(s).

LOGICAL FUNCTION XGetSaveFile(xWnd, sDir, sFile, iFlags, sExts, sTypes, &
sTitle, iX, iY)

!DEC$IF DEFINED(XLITE)
INTEGER, INTENT(IN)::                xWnd
!DEC$ELSE
TYPE(X_WINDOW), INTENT(IN)::         xWnd
!DEC$ENDIF
CHARACTER(*), INTENT(INOUT)::        sDir
CHARACTER(*), INTENT(INOUT)::        sFile
 INTEGER, OPTIONAL, INTENT(IN)::      iFlags
CHARACTER(*), OPTIONAL, INTENT(IN):: sExts(:)
CHARACTER(*), OPTIONAL, INTENT(IN):: sTypes(:)
CHARACTER(*), OPTIONAL, INTENT(IN):: sTitle
INTEGER, OPTIONAL, INTENT(IN)::      iX, iY

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window which will serve as parent for the dialog. For QuickWin projects, the handle can be obtained using GETHWNDQQ. This handle can be NULL, indicating that desktop will serve as parent.

Full Xeffort Version: X_WINDOW structure describing the parent window. The window has to be a valid Xeffort window created by XCreateWindow or bound to Xeffort using XBindWindow or XSubclassWindow.

sDir
Directory where the file is to be saved (without trailing backslash). On input, this directory is used as the initial directory in which the dialog is displayed. On output, it contains directory where the user selected the file to be saved. If empty on input, current directory is displayed.

sFile
Strings containing selected file name. I does not contain directory path. On input, this string will be used as default file name (displayed in "File name" edit box).
To get a fully qualified file name for writing, use construct
TRIM(sDir) // "\" // sFile

[iFlags]
An .OR. combination of OFN_ flags, which control additional properties of the dialog. Please refer to OPENFILENAME in Win32 SDK documentation for details. If not present, the following set of flags is used:

OFN_EXPLORER.OR.OFN_PATHMUSTEXIST.OR.OFN_OVERWRITEPROMPT.OR.OFN_ENABLEHOOK

I.e. the new (Win95) style user-interface is specified, path must exist, and a prompt message box will pop-up if the user selects an existing file. OFN_ENABLEHOOK is used internally.

[sExts]
An array of strings specifying allowed extensions of files. Each string must be in form "*.ext". To specify a group of extensions simultaneously, separate entries with a semicolon, e.g. *.for;*.f90;*.f". If absent, the default is "*.*" . If user does not type in file extension and sExts is present, first string from sExts will be appended.

[sTypes]
An array of strings specifying allowed file types, in human-readable form, i.e. "Text files (*.txt)". The array should be of the same SIZE as sExts; if not, lesser size of the two is used and the exceed is ignored. If absent, the default is "All files (*.*)".

[sTitle]
Dialog title. The default is "Save".

[iX,iY]
Position of the dialog's upper left corner, in pixels, relative to screen. If omitted, XGetSaveFile centers the dialog relative to the parent window.

Return value

If successful, return value is .TRUE. If an error occurs or if user cancels the selection, return value is .FALSE.

See also

XGetOpenFile, XBrowse.

Wrapped APIs

GetSaveFileName

Module

XFTFILE.f90


XSystemPath

XSystemPath

XSystemPath returns the directory path of a special Windows folder.

LOGICAL FUNCTION XSystemPath (xWnd, iXCSIDL, sDir)

!DEC$IF DEFINED(XLITE)
INTEGER, INTENT(IN) :: xWnd
!DEC$ELSE
TYPE( X_WINDOW), INTENT(IN)::          xWnd
!DEC$ENDIF
INTEGER, INTENT(IN)::                  iXCSIDL
CHARACTER(*), INTENT(OUT)::            sDir

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window which will serve as parent for a possible dialog or message box. For QuickWin projects, the handle can be obtained using GETHWNDQQ.
Full Xeffort Version: X_WINDOW structure describing the parent window for a possible dialog or message box. The window has to be a valid Xeffort window created by XCreateWindow or bound to Xeffort using XBindWindow or XSubclassWindow.

iXCSIDL
One of the XCSIDL_ named constants from the table below. The XCSIDL values provide a unique system-independent way to identify special folders used frequently by applications, but which may not have the same name or location on any given system. For example, the system folder may be "C:\Windows" on one system and "C:\Winnt" on another.

XCSIDL_APPDATA | The file system directory that serves as a common repository for application-specific data. A typical path is C:\Documents and Settings\username\Application Data.
XCSIDL_COMMON_APPDATA | The file system directory that contains application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the XCSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer.
XCSIDL_LOCAL_APPDATA | The file system directory that serves as a data repository for local (nonroaming) applications. A typical path is C:\Documents and Settings\username\Local Settings\Application Data.
XCSIDL_ADMINTOOLS | The file system directory that is used to store administrative tools for an individual user. The Microsoft Management Console (MMC) will save customized consoles to this directory, and it will roam with the user.
XCSIDL_ALTSTARTUP | The file system directory that corresponds to the user's nonlocalized Startup program group. This value is recognized in Windows Vista for backward compatibility, but the folder itself no longer exists.
XCSIDL_COMMON_ADMINTOOLS | The file system directory that contains administrative tools for all users of the computer.
XCSIDL_COMMON_ALTSTARTUP | The file system directory that corresponds to the nonlocalized Startup program group for all users. Valid only for Microsoft Windows NT systems. This value is recognized in Windows Vista for backward compatibility, but the folder itself no longer exists.
XCSIDL_COMMON_DESKTOPDIRECTORY | The file system directory that contains files and folders that appear on the desktop for all users. A typical path is C:\Documents and Settings\All Users\Desktop. Valid only for Windows NT systems.
XCSIDL_COMMON_DOCUMENTS | The file system directory that contains documents that are common to all users. A typical paths is C:\Documents and Settings\All Users\Documents. Valid for Windows NT systems and Microsoft Windows 95 and Windows 98 systems with Shfolder.dll installed.
XCSIDL_COMMON_FAVORITES | The file system directory that serves as a common repository for favorite items common to all users. Valid only for Windows NT systems.
XCSIDL_COMMON_MUSIC | The file system directory that serves as a repository for music files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Music.
XCSIDL_COMMON_PICTURES | The file system directory that serves as a repository for image files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Pictures.
XCSIDL_COMMON_PROGRAMS | The file system directory that contains the directories for the common program groups that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs. Valid only for Windows NT systems.
XCSIDL_COMMON_STARTMENU | The file system directory that contains the programs and folders that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu. Valid only for Windows NT systems.
XCSIDL_COMMON_STARTUP | The file system directory that contains the programs that appear in the Startup folder for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup. Valid only for Windows NT systems.
XCSIDL_COMMON_TEMPLATES | The file system directory that contains the templates that are available to all users. A typical path is C:\Documents and Settings\All Users\Templates. Valid only for Windows NT systems.
XCSIDL_COMMON_VIDEO | The file system directory that serves as a repository for video files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Videos.
XCSIDL_CDBURN_AREA | The file system directory that acts as a staging area for files waiting to be written to a CD. A typical path is C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\CD Burning.
XCSIDL_COOKIES | The file system directory that serves as a common repository for Internet cookies. A typical path is C:\Documents and Settings\username\Cookies.
XCSIDL_DESKTOPDIRECTORY | The file system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself). A typical path is C:\Documents and Settings\username\Desktop.
XCSIDL_FAVORITES | The file system directory that serves as a common repository for the user's favorite items. A typical path is C:\Documents and Settings\username\Favorites.
XCSIDL_FONTS | A virtual folder that contains fonts. A typical path is C:\Windows\Fonts.
XCSIDL_HISTORY | The file system directory that serves as a common repository for Internet history items.
XCSIDL_INTERNET_CACHE | The file system directory that serves as a common repository for temporary Internet files. A typical path is C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
XCSIDL_MYMUSIC | The file system directory that serves as a common repository for music files. A typical path is C:\Documents and Settings\User\My Documents\My Music.
XCSIDL_MYPICTURES | The file system directory that serves as a common repository for image files. A typical path is C:\Documents and Settings\username\My Documents\My Pictures.
XCSIDL_MYVIDEO | The file system directory that serves as a common repository for video files. A typical path is C:\Documents and Settings\username\My Documents\My Videos.
XCSIDL_NETHOOD | A file system directory that contains the link objects that may exist in the My Network Places virtual folder. A typical path is C:\Documents and Settings\username\NetHood.
XCSIDL_PERSONAL | The file system directory used to physically store a user's common repository of documents. A typical path is C:\Documents and Settings\username\My Documents.
XCSIDL_PRINTHOOD | The file system directory that contains the link objects that can exist in the Printers virtual folder. A typical path is C:\Documents and Settings\username\PrintHood.
XCSIDL_PROGRAM_FILES | The Program Files folder. A typical path is C:\Program Files.
XCSIDL_PROGRAM_FILES_COMMON | A folder for components that are shared across applications. A typical path is C:\Program Files\Common. Valid only for Windows NT, Windows 2000, and Windows XP systems. Not valid for Windows Millennium Edition (Windows Me).
XCSIDL_PROGRAMS | The file system directory that contains the user's program groups (which are themselves file system directories). A typical path is C:\Documents and Settings\username\Start Menu\Programs.
XCSIDL_RECENT | The file system directory that contains shortcuts to the user's most recently used documents. A typical path is C:\Documents and Settings\username\My Recent Documents.
XCSIDL_RESOURCES | The file system directory that contains resource data. A typical path is C:\Windows\Resources.
XCSIDL_SENDTO | The file system directory that contains Send To menu items. A typical path is C:\Documents and Settings\username\SendTo.
XCSIDL_STARTMENU | The file system directory that contains Start menu items. A typical path is C:\Documents and Settings\username\Start Menu.
XCSIDL_STARTUP | The file system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT or starts Windows 95. A typical path is C:\Documents and Settings\username\Start Menu\Programs\Startup.
XCSIDL_SYSTEM | The Windows System folder. A typical path is C:\Windows\System32.
XCSIDL_TEMPLATES | The file system directory that serves as a common repository for document templates. A typical path is C:\Documents and Settings\username\Templates.
XCSIDL_WINDOWS | The Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables. A typical path is C:\Windows.

sDir
Returned directory path, without a trailing backslash, if the function succeeds. Otherwise empty.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

Not all of the above special folders are defined on every system. Check the return value status before attempting to use sDir .

See Also

 XEnvironmentString

Module

XFTfile.f90


XFTGDI Overview

XFTGDI Overview

XFTGDI library is set of routines which wrap a part of Windows GDI (Graphic Device Interface) functionality. Windows GDI manages graphic output to any of output devices capable of producing graphic output, such as screen, printers and plotters, files (metafiles and bitmap files) as well as memory buffers.

Device contexts (DCs)

Relationship with Win32 GDI API and QuickWin

Coordinate Systems

Reference


XFTGDI: Device contexts (DCs)

XFTGDI: Device contexts (DCs)

Windows GDI takes care about physical properties of output devices, exposing only device contexts to the calling applications. Device context (DC) can be imagined as a canvas, which can be represented as a matrix of pixels (or, better, physical units). In general, a DC has an origin (which is, by default, in upper left corner of the physical canvas - window client area or paper) but it's axes are, in theory, infinite. Of course, the DC's extents are in practice limited by available physical surface. Thus, the DCs can be divided into screen, printer, metafile and memory DCs, although they all can be drawn onto - the only difference is their physical representation, which is abstracted by GDI layer anyway.

In Win32, every DC (and every object) is referred to by its handle, which is a 32-bit integer uniquely identifying the object in system namespace. The DC handle is passed as an argument to most GDI functions. XFTGDI utilizes a derived type, X_DC, which contains DC handle as a member (X_DC%hDC), along with other information. Members of X_DC structure should be treated as private and should not be directly modified by the application.

XFTGDI currently does not provide means for creation and binding to existing DC handles. (Except XMemoryDC) The following Win32 functions and structures are useful for creating and retrieving DC handles:

Window DCs: BeginPaint, GetDC, WM_DRAWITEM+DRAWITEMSTRUCT

Printer DCs: See XFTPrint routines

Metafile DCs: See XCreateMetaFile


XFTGDI: Relationship with Win32 GDI API and QuickWin

XFTGDI: Relationship with Win32 GDI API and QuickWin

1) Win32 GDI functions always require an hDC first argument; it describes "where" to do the drawing. DC (Device Context) is most easily described as a canvas which belongs to a window. Every window has at least one DC associated with it (client area DC); if the window has frame, it also has "non-client DC". DC, though, is wider concept than window - there are, for example, printer DCs and memory DCs, which are not associated with any window. Every DC on the system has one integer - handle or hDC - which uniquely identifies it. XFTGDI functions define a type, X_DC, which, along with hDC, contains information about viewport and window settings (like in QuickWin), and about currently selected drawing objects (see below).

2) Win32 and QuickWin drawing is similar so that they have functions which define current state of the DC (though DC is not "visible" under QuickWin - it is always the memory DC associated with the active window), like SetFont, SetTextColor, SetBkColor etc. Also, Win32 defines "drawing objects": pens, brushes, fonts, bitmaps, etc. The only important difference are pens and brushes: under Win32, "Pen" is something used to draw the line, while "Brush" is used to fill the surface. Under QuickWin, you have only SetColor, which simultaneously changes both pen and brush. Moreover, pens can be thick or thin, and dotted in several ways (see XSetPen); also, brushes can be hatched (see XSetBrush). XFTGDI adopts Win32 concept, defining the X_PEN and X_BRUSH types, which define the active pen and brush used to do the drawing. With XFTGDI, you can define the current pen using XSetPen and brush using

3) Coordinate systems. QuickWin has three coordinate systems: Physical, Viewport and Window. Win32 also has those three; "client coordinate system", the second is referred to as "device coordinate system (units)" and the third as "logical coordinate system (units)". However, under Win32 there are not _W functions; each time when you want to change the coordinate space you have to use SetMapMode. XFTGDI adopts QuickWin concept, where each drawing function has its _W pair. Window coordinates are expressed in REALs, not in DOUBLE PRECISIONs as in QuickWin. There are XSetViewport and XSetWindow functions, along with set of XView2Window and similar functions, which convert coordinates from one to another.

4) Under Win32, brushes, pens, fonts etc. are objects which are created on system level; they occupy memory; they are never destroyed unless explicitly deleted by programmer. So, drawing under Win32 can be real pain, especially if you frequently change color. For example:

hBrush = CreateSolidBrush(#FF)            !Create a red brush

hPen = CreateSolidPen(PS_SOLID,0,#FF)     !Create a red pen

hOldBrush = SelectObject(hDC, hBrush)     !Set current brush

hOldPen = SelectObject(hDC,hPen)          !Set current pen

iSt = Rectangle(hDC,10,10,50,50)          !Draw rectangle

iSt = SelectObject(hDC,hOldPen)           !Restore DC previous state

iSt = SelectObject(hDC,hOldBrush)         !Restore DC previous state

iSt = DeleteObject(hBrush)

iSt = DeleteObject(hPen)

...all of it in order to draw a simple red rectangle. Failure to DeleteObject under Win32 causes a system memory leak (objects are created but never destroyed) which after enough time leads to system crash. XFTGDI encapsulates this behavior, taking care that objects are created and destroyed properly.

5) In XFTGDI, there is no need for XYCoord type in MoveTo. Types X_POINT and X_WPOINT correspond to QuickWin's XYCoord and WXYCoord. Array of X_POINTs is only passed to XPolygon(_W). Also, X_POINTs can be used as arguments to coordinate-system conversion functions.

6) Not all QuickWin functions are implemented, but only most frequently used. For example, ARC and PIE, are not currently implemented. Some do not make sense, e.g. INITIALIZEFONTS. There are no palettes; all color representation is in RGB space (format is hex #BBGGRR).


XFTGDI: Coordinate Systems

XFTGDI: Coordinate Systems

XFTGDI recognizes three coordinate systems:

  • Physical coordinate system is always expressed in pixels. Its origin is located in upper left corner of output device (window client area, printable area of paper or metafile origin). Axes are oriented left-to-right and top-to-bottom. The first pixel in the coordinate system has coordinates (0,0). Actual dimensions of physical coordinate system can be retrieved using GetClientRect (for windows), GetDeviceCaps(PHYSICALWIDTH/HEIGHT) (for printers).

  • Viewport coordinate system is also expressed in pixels. However, its origin can be located at an arbitrary point inside or outside physical area. Axes are oriented left-to-right and top-to-bottom. Viewport axes have extents. These extents are used to establish mapping between viewport and logical coordinate system. XFTGDI function without _W suffix operate on viewport coordinate system. XSetViewport function sets the viewport coordinate system.

  • Logical (window) coordinate system is expressed in arbitrary units, which are REALs in XFTGDI. Its origin can also be located at an arbitrary point. Logical coordinate system is established (i.e. mapped to viewport system) using XSetWindow subroutine. Logical coordinate system is essential for creation of scalable images. For example, if an image is to always fill the same percent of area of a window or paper, the viewport should be stretched to fill entire area and the window mapped with always the same arguments. When functions with _W suffix are used, the resulting image will always have the same relative size on the DC.

The following image illustrates the relationship between physical, viewport, and logical coordinate systems:

The following functions are used to convert between coordinate systems:

XClient2View

XClient2Wnd

XClient2View

XClient2Wnd

XWnd2Client

XWnd2View


XFTGDI Reference

XFTGDI Reference

Overview

Color Management and DC Settings

XDeleteDC

XMemoryDC

XRGB

XScrollWindow

XSetBkColor

XSetBkMode

XSetBrush

XSetBrushHandle

XSetClipping

XSetPen

XSetPenHandle

XSetROPMode

XSetTextColor

XUpdateWindow

XCreateMetaFile

XCloseMetaFile

Coordinate Systems

XClient2View

XClient2Wnd

XGetViewport

XGetGDIWindow

XSetScaling

XSetViewport

XSetWindow

XView2Client

XView2Wnd

XWnd2Client

XWnd2View

Graphic Primitives

XEllipse

XFillRect

XFillViewport

XFloodFill

XLine

XLineTo

XLineToRelative

XMoveTo

XMoveRelative

XPolygon

XPolyline

XRectangle

XNowAt

Bitmaps and Bit-operations

XBitCopy

XCreateBitmap

XGetBitmap

XGetPixel

XPlaceBitmap

XSetPixel

XSaveBitmap

Text and Font Operations

XGetTextExtent

XSetFont

XTextOut

XWrite

XFTGDI Types

X_BITMAP

X_BRUSH

X_DC

X_PEN

X_POINT


PXCreateBitmap_File

PXCreateBitmap_File

PXCreateBitmap_File function loads a bitmap object from a .bmp file. This function is accessible only under its generic name XCreateBitmap.

LOGICAL FUNCTION
 PXCreateBitmap_File(xBmp, sFile, iFlags, iX, iY)

TYPE(X_BITMAP), INTENT(OUT)::   xBmp
CHARACTER(*), INTENT(IN)::      sFile
INTEGER, OPTIONAL, INTENT(IN)::      iFlags
INTEGER, OPTIONAL, INTENT(IN)::      iX, iY

Arguments

xBmp

X_BITMAP structure containing information about the Bitmap.

sFile

Fully qualified path of the bitmap file. Only files in .bmp format are supported.

[iFlags]
Optional .OR. combination of the following flags.

LR_CREATEDIBSECTION | Causes the function to return a DIB section bitmap rather than a compatible bitmap. This flag is useful for loading a bitmap without mapping it to the colors of the display device.
LR_DEFAULTSIZE | Uses the width or height specified by the system metric values for cursors or icons, if the iX or iY arguments are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.
LR_LOADMAP3DCOLORS | Searches the color table for the image and replaces the following shades of gray with the corresponding 3D color: Color Replaced with Dk Gray (#808080) COLOR_3DSHADOW Gray, (#C0C0C0) COLOR_3DFACE Lt Gray, (#DFDFDF) COLOR_3DLIGHT

LR_LOADTRANSPARENT

Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables.

If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.

LR_MONOCHROME

Loads the image in black and white.

LR_SHARED

Shares the image handle if the image is loaded multiple times. If LR_SHARED is not set, a second call for the same resource will load the image again and return a different handle.

Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file.

None of these flags is applied by default.

[iX], [iY]

Specify desired bitmap dimensions, in pixels. If absent, normal bitmap dimensions as stored in the file are applied.

Return Value

.TRUE. if successful, otherwise .FALSE.

Wrapped APIs

LoadImage, GetObject

See Also

PXCreateBitmap_Rsrc, PXCreateBitmap_DC

Module

XFTGDI.f90


PXCreateBitmap_Rsrc

PXCreateBitmap_Rsrc

PXCreateBitmap_Rsrc function loads a bitmap object as a resource from given executable module.

LOGICAL FUNCTION
 PXCreateBitmap_Rsrc(xBmp, ID, iFlags, iX, iY, hModule)

TYPE(X_BITMAP),INTENT(OUT)::    xBmp
INTEGER, INTENT(IN)::
ID
INTEGER, OPTIONAL, INTENT(IN)::      iFlags
INTEGER, OPTIONAL, INTENT(IN)::      iX, iY
INTEGER, OPTIONAL, INTENT(IN)::      hModule

Arguments

xBmp

X_BITMAP structure containing information about the Bitmap.

ID

Integer identifier of the resource.

[iFlags]
Optional .OR. combination of the following flags.

LR_CREATEDIBSECTION | Causes the function to return a DIB section bitmap rather than a compatible bitmap. This flag is useful for loading a bitmap without mapping it to the colors of the display device.
LR_DEFAULTSIZE | Uses the width or height specified by the system metric values for cursors or icons, if the iX or iY arguments are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.
LR_LOADMAP3DCOLORS | Searches the color table for the image and replaces the following shades of gray with the corresponding 3D color: Color Replaced with Dk Gray (#808080) COLOR_3DSHADOW Gray, (#C0C0C0) COLOR_3DFACE Lt Gray, (#DFDFDF) COLOR_3DLIGHT

LR_LOADTRANSPARENT

Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables.

If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.

LR_MONOCHROME

Loads the image in black and white.

LR_SHARED

Shares the image handle if the image is loaded multiple times. If LR_SHARED is not set, a second call for the same resource will load the image again and return a different handle.

Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file.

None of these flags is applied by default.

[iX, iY]

Specify desired bitmap dimensions, in pixels. If absent, normal bitmap dimensions as stored in the resource are applied.

[hModule]

Handle of the module which contains the resource. By default, the bitmap resource is loaded from the executable which started the current process. You can use XGetInstance or LoadLibrary API to get the handle to the dll containing the bitmap.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

PXCreateBitmap_File, XGetBitmap

Remarks

You should destroy the bitmap after you no longer need it using XDeleteBitmap.

Wrapped APIs

LoadImage

Module

XFTGDI.f90


X_BITMAP

X_BITMAP

X_BITMAP derived type represents a bitmap loaded into memory.

TYPE X_BITMAP
   INTEGER(4):: hBmp = 0
   INTEGER(4):: iX = 0
   INTEGER(4):: iY = 0
END TYPE X_BITMAP

Members

hBmp

Windows handle of the bitmap.

iX1, iY1
Bitmap dimensions, in pixels.

Remarks

Don't explicitly change the members of a variable of X_BITMAP type. Use bitmap functions instead.

See Also

XCreateBitmap, XDeleteBitmap, XGetBitmap

Module

XFTGDI.f90


X_BRUSH

X_BRUSH

X_BITMAP derived type represents a brush. Brush is a GDI object used for filling surfaces.

TYPE X_BRUSH
    INTEGER:: iStyle = 0
    INTEGER:: iColor = 0
    INTEGER:: iHatch = 0
END TYPE X_BRUSH

Members

iStyle

Brush style. Can be one of the following constants:

BS_DIBPATTERN | A pattern brush defined by a device-independent bitmap (DIB) specification. Currently not supported by XFTGDI.
BS_DIBPATTERNPT | A pattern brush defined by a device-independent bitmap (DIB) specification. Currently not supported by XFTGDI.
BS_HATCHED | Hatched brush.
BS_HOLLOW BS_NULL | Hollow brush (not affecting the existing background).
BS_PATTERN | Pattern brush defined by a memory bitmap. Currently not supported by XFTGDI.
BS_SOLID | Solid brush. (default)

iColor

Brush color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function. If brush style is BS_NULL (BS_HOLLOW), color is ignored.

iHatch

If iStyle argument is BS_HATCHED, it defines hatch type using one of the following constants. Otherwise, it is ignored:

HS_BDIAGONAL | A 45-degree upward, left-to-right hatch
HS_CROSS | Horizontal and vertical cross-hatch
HS_DIAGCROSS | 45-degree crosshatch
HS_FDIAGONAL | A 45-degree downward, left-to-right hatch
HS_HORIZONTAL | Horizontal hatch
HS_VERTICAL | Vertical hatch

See Also

XSetBrush

Module

XFTGDI.f90


X_DC

X_DC

X_DC derived type represents a device context. Device context is canvas used for performing graphic operations on.

TYPE X_DC
    INTEGER:: hDC = 0
    ...
END TYPE X_DC

Members

hDC

Windows handle of the DC.

Remarks

Don't use other members. They are reserved for XFTGDI internal use.

See Also

Device contexts overview , XSetViewport, XSetWindow, XMemoryDC

Module

XFTGDI.f90


X_PEN

X_PEN

X_PEN derived type represents a pen. Pen is a GDI object used for drawing lines.

TYPE X_PEN
    INTEGER:: iStyle = 0
    INTEGER:: iWidth = 0
    INTEGER:: iColor = 0
END TYPE X_PEN

Members

iStyle

Pen style. Can be one of the following constants:

PS_SOLID | Pen is solid. (default)
PS_DASH | Pen is dashed.
PS_DOT | Pen is dotted.
PS_DASHDOT | Pen has alternating dashes and dots.
PS_DASHDOTDOT | Pen has dashes and double dots.
PS_NULL | Pen is invisible.

iWidth

Pen width, in pixels. Value of zero indicates 1 pixel. Default value is 1.

iColor

Pen color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

Remarks

Windows 95/98/ME: A pen thicker than 1 pixel can only have PS_SOLID style. If a thicker pen is required, other PS_ styles will be ignored and the pen will be created as solid.

See Also

XSetPen

Module

XFTGDI.f90


X_POINT

X_POINT, X_WPOINT

X_POINT and X_WPOINT derived types represent a single physical point in viewport and logical coordinate system respectively.

TYPE, PUBLIC:: X_POINT
   INTEGER iX
   INTEGER iY
END TYPE X_POINT

TYPE, PUBLIC:: X_WPOINT
   REAL fX
   REAL fY
END TYPE X_POINT

See Also

XView2Client, XView2Wnd, XWnd2Client, XWnd2View, XPolygon, XPolyline

Module

XFTGDI.f90


XBitCopy

XBitCopy, XBitCopy_W

XBitCopy function copies a rectangular region from one DC to another.

LOGICAL FUNCTION XBitCopy_W(xDCsrc, iXsrc1, iYsrc1, iXsrc2, iYsrc2, xDCdest, iXdest1, iYdest1, iXdest2, iYdest2)

TYPE(X_DC), INTENT(IN)::             xDCsrc
INTEGER/REAL, INTENT(IN)::           iXsrc1/fXsrc1
INTEGER/REAL, INTENT(IN)::           iYsrc1/fYsrc1
INTEGER/REAL, INTENT(IN)::           iXsrc2/fXsrc2
INTEGER/REAL, INTENT(IN)::           iYsrc2/fYsrc2
TYPE(X_DC), INTENT(IN)::             xDCdest
INTEGER/REAL, INTENT(IN)::           iXdest1/fXdest1
INTEGER/REAL, INTENT(IN)::           iYdest1/fYdest1
INTEGER/REAL, OPTIONAL, INTENT(IN):: iXdest2/fXdest2
INTEGER/REAL, OPTIONAL, INTENT(IN):: iYdest2/fYdest2
INTEGER, OPTIONAL, INTENT(IN):: iFlags

Arguments

xDCsrc

X_DC structure containing information about the source DC.

iXsrc1, iYsrc1 / fXsrc1, fYsrc1
Viewport (XBitCopy) or logical (XBitCopy_W) coordinates of the point on the source DC which determines the top-left corner of the rectangle to be copied.

iXsrc2, iYsrc2 / fXsrc2, fYsrc2
Viewport (XBitCopy) or logical (XBitCopy_W) coordinates of the point on the source DC which determines the bottom-right corner of the rectangle to be copied.

xDCdest

X_DC structure containing information about the destination DC.

iXdest1, iYdest1 / fXdest1, fYdest1
Viewport (XBitCopy) or logical (XBitCopy_W) coordinates of the point on the target DC which determines the top-left corner where the rectangle is to be copied.

[iXdest2, iYdest2] / [fXdest2, fYdest2]
Viewport (XBitCopy) or logical (XBitCopy_W) coordinates of the point on the target DC which determines the bottom-right corner where the rectangle is to be copied. If necessary, the rectangle will be stretched. If absent, the source is copied to destination rectangle in 1:1 ratio.

[iFlags]
Specifies a raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data for the destination rectangle to achieve the final color.

The following list shows some common raster operation codes:
Value | Description
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT | Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND | Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle (default).
SRCERASE | Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT | Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT | Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette)

Return Value

If successful, the return value is .TRUE. Otherwise, the return value is .FALSE.

Remarks

The same effect can be achieved using XGetBitmap and XPlaceBitmap, but XBitCopy is more efficient since it utilizes only one copy-operation.

The most useful application of XBitCopy is in buffered operations, such as animation.

See Also

XMemoryDC

Wrapped APIs

BitBlt, StretchBlt

Module

XFTGDI.f90


XClient2View

XClient2View

XClient2View routine converts coordinates of a single physical point from physical coordinate system to viewport coordinates. The origin of physical coordinate system is top-left corner of window's client area, printable area of paper, or metafile origin. Physical (client) coordinates are expressed in pixels, just as viewport coordinates, so XClient2View just adds appropriate offset set by XSetViewport.

SUBROUTINE XClient2View(xDC, jX, jY, iX, iY)

TYPE(X_DC),INTENT(IN):: xDC
INTEGER,INTENT(IN)::    jX,jY
INTEGER,INTENT(OUT)::   iX,iY

Arguments

xDC

X_DC structure containing information about the DC.

jX/jY

X/Y coordinate in client coordinate system.

iX/iY
Converted X/Y coordinate in viewport coordinate system

See Also

XSetViewport, XClient2Wnd, XView2Client

Module

XFTGDI.f90


XClient2Wnd

XClient2Wnd

XClient2Wnd routine converts coordinates of a single physical point from physical coordinate system to logical (window) coordinates.

SUBROUTINE XClient2Wnd(xDC, jX, jY, fX, fY)

TYPE(X_DC), INTENT(IN):: xDC
INTEGER, INTENT(IN)::    jX, jY
REAL, INTENT(OUT)::      fX, fY

Arguments

xDC

X_DC structure containing information about the DC.

jX/jY

X/Y coordinate in client coordinate system.

fX/fY
Converted X/Y coordinate in logical (window) coordinate system

See Also

XSetWindow, XWnd2Client

Module

XFTGDI.f90


XCreateBitmap

XCreateBitmap

XCreateBitmap is generic name for the following two functions:

PXCreateBitmap_Rsrc | Loads a bitmap from bitmap resource.
PXCreateBitmap_File | Loads a bitmap from a .bmp file

These functions are accessible only under generic name XCreateBitmap.

See Also

XPlaceBitmap, XDeleteBitmap, XGetBitmap

Module

XFTGDI.f90


XDeleteBitmap

XDeleteBitmap

XDeleteBitmap deletes the bitmap previously created with XCreateBitmap and resets structure members

LOGICAL FUNCTION XDeleteBitmap(xBmp)

TYPE(X_BITMAP), INTENT(INOUT):: xBmp

Arguments

xBmp

X_BITMAP structure containing information about the bitmap. If successful, structure members will be reset to zero

Return Value

If successful, return value is .TRUE. Otherwise, the return value is .FALSE.; cause of failure can be that the bitmap was already deleted or that it is selected into a DC using SelectObject API.

See Also

XCreateBitmap

Wrapped APIs

DeleteObject

Module

XFTGDI.f90


XCreateMetaFile

XCreateMetaFile

XCreateMetaFile creates a DC for an enhanced metafile on the disk. A metafile is like a bitmap file in that both can store GDI drawings. However, a bitmap file stores a raster image of the drawing, while a metafile stores the commands necessary to reconstruct the drawing on a device. Therefore, when an enhanced metafile is imported into a word processor, the drawing can be readily resized with no loss of quality.

LOGICAL FUNCTION XCreateMetaFile (xDCref, sFile, xDCmf, iWidth, iHeight)

TYPE(X_DC), INTENT(IN)::       xDCref
CHARACTER(*), INTENT(IN)::     sFile
TYPE(X_DC), INTENT(OUT)::      xDCmf
INTEGER, INTENT(OUT)::         iWidth
INTEGER, INTENT(OUT)::         iHeight

Arguments

xDCref
 X_DC structure containing information about the reference DC. This can be any valid xDC. The current resolution of the reference DC determines the resolution of the metafile.

sFile
Name of the .emf file to be created. The file is created with name "as-is", i.e. .emf extension is not automatically appended. The name may include path information.

xDCmf
 Returned X_DC structure containing an initialized DC for the metafile. The drawing surface of this DC will be empty.

iWidth
Effective width of the metafile drawing surface based on the resolution of the reference DC.

iHeight
Effective height of the metafile drawing surface based on the resolution of the reference DC.

Return Value

If successful, the return value is .TRUE. Otherwise, the return value is .FALSE.

Remarks

Drawing to a metafile is exactly like drawing to a window. Use any of the XFTGDI routines with the xDCmf returned by this function as the xDC argument. When done drawing invoke XCloseMetaFile .

Because the resolution of the metafile is that of the reference DC, for the best quality (minimal "jaggies") use a high-resolution reference, such as a printer DC returned by XCreateDC .

See Also

XCloseMetaFile, XCreateDC

Wrapped APIs

CreateEnhMetaFile

Module

XFTextra.f90


XCloseMetaFile

XCloseMetaFile

XCloseMetaFile closes a metafile created by XCreateMetaFile .

LOGICAL FUNCTION XCloseMetaFile (xDCmf)

TYPE(X_DC), INTENT(INOUT)::      xDCmf

Arguments

xDCmf
 X_DC structure containing information about the metafile DC created by XCreateMetaFile.

Return Value

If successful, the return value is .TRUE. Otherwise, the return value is .FALSE.

See Also

XCreateMetaFile

Wrapped APIs

CloseEnhMetaFile

Module

XFTextra.f90


XDeleteDC

XDeleteDC

XDeleteDC deletes the DC previously created with XCreateDC or XMemoryDC and resets structure members if successful

LOGICAL FUNCTION XDeleteDC(xDC)

TYPE(X_DC), INTENT(INOUT):: xDC

Arguments

xDC

X_DC structure containing information about the DC. If successful, xDC%hDC will be reset to zero. Do not delete DCs created with means other than XMemoryDC or XCreateDC.

Return Value

If successful, return value is .TRUE. Otherwise, the return value is .FALSE..

See Also

XMemoryDC, XCreateDC

Wrapped APIs

DeleteDC, DeleteObject

Module

XFTGDI.f90


XEllipse

XEllipse, XEllipse_W

XEllipse and XEllipse_W draws a ellipse with bounding rectangle defined by given pairs of coordinates. Ellipse outline is drawn using current pen (XSetPen) and the Ellipse is filled using current brush (XSetBrush).

LOGICAL FUNCTION XEllipse_W(xDC, iX1, iY1, iX2, iY2, xPen, xBrush)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER/REAL, INTENT(IN)::          iX1/fX1
INTEGER/REAL, INTENT(IN)::          iY1/fY1
 INTEGER/REAL, INTENT(IN)::          iX1/fX2
INTEGER/REAL, INTENT(IN)::          iY1/fY2
TYPE(X_PEN), OPTIONAL, INTENT(IN):: xPen
TYPE(X_BRUSH),OPTIONAL,INTENT(IN):: xBrush

Arguments

xDC

X_DC structure containing information about the DC.

iX1/fX1
 X coordinate of upper left corner of the bounding rectangle, in pixels (XEllipse) or logical units (XEllipse_W).

iY1/fY1
 X coordinate of upper left corner of the bounding rectangle, in pixels (XEllipse) or logical units (XEllipse_W).

iX2/fX2,
X coordinate of bottom right corner of the bounding rectangle, in pixels (XEllipse) or logical units (XEllipse_W).

iY2/fY2
Y coordinate of bottom right corner of the bounding rectangle, in pixels (XEllipse) or logical units (XEllipse_W).

[xPen]
X_PEN structure specifying attributes of the pen used to draw the outline of the Ellipse. If not present, the line is drawn using the pen set by last call to XSetPen.

[xBrush]
X_BRUSH structure specifying attributes of the brush used to fill the ellipse. If not present, the line is drawn using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

XFTGDI will inverse top-left and right-bottom corners if inconsistent so the caller need not take care about it.

To draw only an outlined ellipse, use a hollow brush (X_BRUSH(BS_NULL, 0, 0))

Wrapped APIs

Ellipse

Module

XFTGDI.f90


XFillRect

XFillRect, XFillRect_W

XFillRect and XFillRect_W fill a rectangle with corners defined by given pairs of coordinates using given or current brush (XSetBrush), but no outline. This function is faster than similar XRectangle.

LOGICAL FUNCTION XFillRect_W(xDC, iX1, iY1, iX2, iY2, xBrush)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER/REAL, INTENT(IN)::          iX1/fX1
INTEGER/REAL, INTENT(IN)::          iY1/fY1
 INTEGER/REAL, INTENT(IN)::          iX1/fX2
INTEGER/REAL, INTENT(IN)::          iY1/fY2
 TYPE(X_BRUSH),OPTIONAL,INTENT(IN):: xBrush

Arguments

xDC

X_DC structure containing information about the DC.

iX1/fX1
 X coordinate of upper left corner of the rectangle, in pixels (XFillRect) or logical units (XFillRect_W).

iY1/fY1
 X coordinate of upper left corner of the rectangle, in pixels (XFillRect) or logical units (XFillRect_W).

iX2/fX2
X coordinate of bottom right corner of the rectangle, in pixels (XFillRect) or logical units (XFillRect_W).

iY2/fY2
Y coordinate of bottom right corner of the rectangle, in pixels (XFillRect) or logical units (XFillRect_W).

[xBrush]
X_BRUSH structure specifying attributes of the brush used to fill the FillRect. If not present, the rectangle is filled using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

XFTGDI will inverse top-left and right-bottom corners if inconsistent so the caller need not take care about it.

See Also

XRectangle, XFillViewport

Wrapped APIs

FillRect

Module

XFTGDI.f90


XFillViewport

XFillViewport

XFillViewport fills the area of current viewport using the given brush or current brush (XSetBrush).

LOGICAL FUNCTION XFillViewport(xDC, xBrush)

TYPE(X_DC), INTENT(INOUT)::         xDC
TYPE(X_BRUSH),OPTIONAL,INTENT(IN):: xBrush

Arguments

xDC

X_DC structure containing information about the DC.

[xBrush]
X_BRUSH structure specifying attributes of the brush used to fill the rectangle. If not present, the rectangle is filled using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XRectangle, XFillRect

Wrapped APIs

FillRect

Module

XFTGDI.f90


XFloodFill

XFloodFill, XFloodFill_W

XFloodFill and XFloodFill_W fill the given surface (solid-color surface or surface bounded by a solid-color line) with current or specified brush starting from given point.

LOGICAL FUNCTION XFloodFill_W(xDC, iX, iY, iColor, bSurface, xBrush)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER/REAL, INTENT(IN)::      iX/fX
INTEGER/REAL, INTENT(IN)::      iY/fY
 INTEGER, INTENT(IN)::           iColor
LOGICAL, OPTIONAL, INTENT(IN):: bSurface
TYPE(X_BRUSH), OPTIONAL, INTENT(IN):: xBrush

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX
 X coordinate of the point to start filling from, in pixels (XFloodFill) or logical units (XFloodFill_W).

iY/fY
Y coordinate of the point to start filling from, in pixels (XFloodFill) or logical units (XFloodFill_W).

iColor
Color on the original DC surface to be replaced/filled. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

[bSurface]
If .FALSE. (default), the area bounded by pixels of iColor will be filled; otherwise, if .TRUE. the area covered by iColor will be replaced with given brush.

[xBrush]
X_BRUSH structure specifying attributes of the brush used to fill the area. If not present, the rectangle is filled using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

FloodFill operation is not very efficient - use XPolygon instead where applicable.

See Also

XPolygon, XGetPixel

Wrapped APIs

ExtFloodFill

Module

XFTGDI.f90


XGetBitmap

XGetBitmap, XGetBitmap_W

XGetBitmap function creates a bitmap object from a rectangular area on a DC by copying its contents.

LOGICAL FUNCTION XGetBitmap_W(xDC, xBmp, iX1, iY1, iX2, iY2, iWidth, iHeight, iFlags)

TYPE(X_DC), INTENT(IN)::         xDC
TYPE(X_BITMAP), INTENT(OUT)::    xBmp
INTEGER/REAL, INTENT(IN)::       iX1,iY1 / fX1,fY1
INTEGER/REAL, INTENT(IN)::       iX2,iY2 / fX2,fY2
INTEGER, OPTIONAL, INTENT(IN)::  iWidth, iHeight
INTEGER, OPTIONAL, INTENT(IN)::  iFlags

Arguments

xDC

X_DC structure containing information about the source DC.

xBmp

X_BITMAP structure containing information about the Bitmap.

iX1, iY1 / fX1, fY1
Viewport (XGetBitmap) or logical (XGetBitmap_W) coordinates of the point on the DC which determines the top-left corner of the bitmap.

iX2, iY2 / fX2, fY2
Viewport (XGetBitmap) or logical (XGetBitmap_W) coordinates of the point on the DC which determines the bottom-right corner of the bitmap.

[iWidth, iHeight]
Desired dimension of the bitmap, in pixels. If necessary, the bitmap is stretched. If not present, the bitmap is the same size as the source rectangle.

[iFlags]
Specifies a raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the bitmap to achieve the final color.

The following list shows some common raster operation codes:
Value | Description
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT | Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND | Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle (default).
SRCERASE | Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT | Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT | Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette)

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

You should destroy the bitmap after you no longer need it using XDeleteBitmap.

See Also

PXCreateBitmap_File, PXCreateBitmap_DC, XBitCopy, XPlaceBitmap

Wrapped APIs

CreateCompatibleBitmap, BitBlt, StretchBlt

Module

XFTGDI.f90


XGetGDIWindow

XGetGDIWindow

XGetGDIWindow routine retrieves the coordinates of the current logical window for given DC. The logical coordinate system is an arbitrary cartesian system, expressed in arbitrary units (real numbers). All XFTGDI routines with _W suffix operate on logical coordinate system.

XGetGDIWindow specifies mapping of logical coordinate system to viewport previously defined by XSetViewport. Each argument of XGetGDIWindow defines the coordinate of corresponding viewport pixel in logical coordinate system.

SUBROUTINE
XGetGDIWindow(xDC, fX1, fY1, fX2, fY2)

TYPE(X_DC),INTENT(INOUT)::  xDC
REAL,INTENT(OUT)::
fX1, fY1, fX2, fY2

Arguments

xDC

X_DC structure containing information about the DC.

fX1
 Coordinate of viewport's left edge in logical coordinate system.

fY1
 Coordinate of viewport's top edge in logical coordinate system.

fX2
Coordinate of viewport's right edge in logical coordinate system.

fY2
Coordinate of viewport's bottom edge in logical coordinate system.

Remarks

Logical (window) coordinate system can be freely orientated with the only restriction that the viewport has to have non-zero area.

This function is called XGetGDIWindow to avoid conflict with XGetWindow from module XFTWND.

See Also

XGetViewport, XSetWindow

Module

XFTGDI.f90


XGetPixel

XGetPixel, XGetPixel_W

XGetPixel and XGetPixel_W retrieves the color of the specified pixel.

INTEGER FUNCTION XGetPixel_W(xDC, iX, iY)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER/REAL, INTENT(IN)::      iX/fX
INTEGER/REAL, INTENT(IN)::      iY/fY

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX
 X coordinate of the pixel, in pixels (XGetPixel) or logical units (XGetPixel_W).

iY/fY
Y coordinate of the pixel, in pixels (XGetPixel) or logical units (XGetPixel_W).

Return Value

If successful, color of the pixel in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively. If the function fails, return value is -1.

See Also

XSetPixel

Wrapped APIs

GetPixel

Module

XFTGDI.f90


XGetTextExtent

XGetTextExtent, XGetTextExtent_W

XGetTextExtent and XGetTextExtent_W routines return the dimensions of given text drawn using currently selected font, in physical (XGetTextExtent) or logical (XGetTextExtent_W) coordinates

SUBROUTINE XGetTextExtent_W(xDC, sText, iX, iY, bEntire)

TYPE(X_DC),INTENT(IN)::     xDC
CHARACTER(*), INTENT(IN)::  sText
INTEGER/REAL, INTENT(OUT):: iX/fX
INTEGER/REAL, INTENT(OUT):: iY/fY
LOGICAL, OPTIONAL, INTENT(IN):: bEntire

Arguments

xDC

X_DC structure containing information about the DC.

sText

Text whose dimensions are to be returned

iX/fX
Width of the text, in pixels or logical coordinates.

iY/fY
Total height of the text, in pixels or logical coordinates.

[bEntire]

If present and .TRUE., the room required for any trailing spaces in sText is included in the calculations. Normally, trailing spaces are ignored and calculations are based on a trimmed sText.

See Also

XTextOut, XSetFont

Module

XFTGDI.f90


XGetViewport

XGetViewport

XGetViewport routine retrieves the coordinates of the current viewport previously set by XSetViewport.

Viewport is rectangle on DC surface, defined in pixels (device units), which defines the region where subsequent drawing operations will occur. All drawing operations (such as XRectangle, XTextOut etc.) operate on coordinates which are relative to viewport origin.

SUBROUTINE
XGetViewport(xDC, iX1, iY1, iX2, iY2)

TYPE(X_DC), INTENT(INOUT)::          xDC
INTEGER, INTENT(OUT)::       iX1,iY1,iX2,iY2

Arguments

xDC

X_DC structure containing information about the DC.

iX1
 X coordinate of upper left corner of the viewport, in pixels, relative to physical top-left corner of the DC (window's client area, paper printable surface etc.)

iY1
 Y coordinate of upper left corner of the viewport, in pixels

iX2
X coordinate of bottom right corner of the rectangle, in pixels

iY2
Y coordinate of bottom right corner of the rectangle, in pixels

See Also

XSetViewport, XGetGDIWindow

Module

XFTGDI.f90


XLine

XLine, XLine_W

XLine and XLine_W draws the line between given pairs of coordinates. XLine(W) changes the current position to the target point.

LOGICAL FUNCTION XLine_W(xDC, iX1, iY1, iX2, iY2, xPen)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER/REAL, INTENT(IN)::          iX1/fX1
INTEGER/REAL, INTENT(IN)::          iY1/fY1
 INTEGER/REAL, INTENT(IN)::          iX1/fX2
INTEGER/REAL, INTENT(IN)::          iY1/fY2
TYPE(X_PEN), OPTIONAL, INTENT(IN):: xPen

Arguments

xDC

X_DC structure containing information about the DC.

iX1/fX1,
Starting X coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

iY1/fY1
Starting Y coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

iX2/fX2,
Ending X coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

iY2/fY2
Ending Y coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

[xPen]
X_PEN structure specifying attributes of the pen used to draw the line. If not present, the line is drawn using the pen set by last call to XSetPen.

Return Value

.TRUE. if successful, otherwise .FALSE.

Wrapped APIs

MoveToEx, LineTo

Module

XFTGDI.f90


XLineTo

XLineTo, XLineTo_W

XLineTo and XLineTo_W draws the line from the current point to a target coordinate. Current point is defined by a previous call one of the XLine... or XMove... routines. The line, unless overriden by xPen argument, is drawn using pen set by XSetPen.

LOGICAL FUNCTION XLineTo_W(xDC, iX, iY, xPen)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER/REAL, INTENT(IN)::          iX/fX
INTEGER/REAL, INTENT(IN)::          iY/fY
TYPE(X_PEN), OPTIONAL, INTENT(IN):: xPen

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX,
Target X coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

iY/fY
Target Y coordinate, in pixels (XLineTo) or logical units (XLineTo_W) of the line.

[xPen]
X_PEN structure specifying attributes of the pen used to draw the line. If not present, the line is drawn using the pen set by last call to XSetPen.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XLine, XLineToRelative, XMoveTo, XMoveRelative, XSetPen

Wrapped APIs

LineTo

Module

XFTGDI.f90


XLineToRelative

XLineToRelative

XLineToRelative draws a line from the current position to an endpoint specified by delta coordinates from the current position. The endpoint becomes the new current position and affects subsequent calls to XLineTo... and XMove... routines.

LOGICAL FUNCTION XLineToRelative (xDC, idX, idY, xPen)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER, INTENT(IN)::               idX
INTEGER, INTENT(IN)::               idY
TYPE(X_PEN), OPTIONAL, INTENT(IN):: xPen

Arguments

xDC

X_DC structure containing information about the DC.

idX
X component of the line in pixels.

idY
Y component of the line in pixels.

[xPen]
X_PEN structure specifying attributes of the pen used to draw the line. If not present, the line is drawn using the pen set by last call to XSetPen.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XLine, XLineTo, XMoveTo, XMoveRelative, XNowAt, XSetPen

Module

XFTGDI.f90


XMemoryDC

XMemoryDC

XMemoryDC function creates a memory DC, which can be used for copying and buffering operations. Memory DCs have dimensions, thus XMemoryDC also calls XSetViewport and XSetWindow to set both viewport and logical coordinate system to (0, 0, iX, iY).

FUNCTION
 XMemoryDC(iX, iY, xDCSource)  RESULT (xDC)

TYPE(X_DC)::                        xDC

INTEGER, INTENT(IN)::
iX, iY
TYPE(X_DC), OPTIONAL, INTENT(IN)::  xDCSource

Arguments

iX,iY
Width and height of the DC, in pixels. If successful, viewport and window on this DC will be adjusted to (0,0,iX,iY) dimensions.

[xDCSource]
A X_DC structure representing the DC which is used as a template (color depth) for creation of a new DC. If absent, screen DC is used.

Return Value

Returns a X_DC structure containing information about newly created DC. If not successful, X_DC%hDC will be set to 0.

Remarks

You should destroy the memory DC after you no longer need it using XDeleteDC.

See Also

XBitCopy

Wrapped APIs

CreateCompatibleDC, CreateCompatibleBitmap

Module

XFTGDI.f90


XMoveTo

XMoveTo, XMoveTo_W

XMoveTo and XMoveTo_W sets the current position to the specified point. The current position affects subsequent calls to XLineTo/XLineTo_W/XLineToRelative.

SUBROUTINE XMoveTo_W(xDC, iX, iY)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER/REAL, INTENT(IN)::      iX/fX
INTEGER/REAL, INTENT(IN)::      iY/fY

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX
X coordinate of the desired current position, in pixels (XMoveTo) or logical units (XMoveTo_W).

iY/fY
Y coordinate of the desired current position, in pixels (XMoveTo) or logical units (XMoveTo_W).

See Also

XLineTo, XLineToRelative, XMoveRelative

Wrapped APIs

MoveToEx

Module

XFTGDI.f90


XMoveRelative

XMoveRelative

XMoveRelative changes the position by delta coordinates from the current position. The resulting position affects subsequent calls to the XLineTo... and XMove... routines.

SUBROUTINE
XMoveRelative (xDC, idX, idY)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::     idX
INTEGER, INTENT(IN)::     idY

Arguments

xDC

X_DC structure containing information about the DC.

idX
Desired X coordinate change in pixels.

idY
Desired Y coordinate change in pixels.

See Also

XMoveTo, XLineTo, XLineToRelative, XNowAt

Module

XFTGDI.f90


XNowAt

XNowAt

XNowAt returns the viewport coordinates of the current position (resulting from the most recent call to any of the XLine... or XMove... routines).

SUBROUTINE
XNowAt (xDC, iX, iY)

TYPE(X_DC), INTENT(IN)::    xDC
INTEGER, INTENT(OUT)::     iX
INTEGER, INTENT(OUT)::     iY

Arguments

xDC

X_DC structure containing information about the DC.

iX
X viewport coordinate of the current position in pixels.

iY
Y viewport coordinate of the current position in pixels.

See Also

XLine, XLineTo, XLineToRelative, XMoveTo, XMoveRelative

Wrapped APIs

GetCurrentPositionEx

Module

XFTGDI.f90


XPlaceBitmap

XPlaceBitmap, XPlaceBitmap_W

XPlaceBitmap function places (copies) a bitmap at a given location on a DC.

LOGICAL FUNCTION XPlaceBitmap_W(xDC, xBmp, iX, iY, iX2, iY2, iFlags)

TYPE(X_DC), INTENT(IN)::             xDC
TYPE(X_BITMAP),INTENT(IN)::          xBmp
INTEGER/REAL, INTENT(IN)::           iX/fX
INTEGER/REAL, INTENT(IN)::           iY/fY
INTEGER/REAL, OPTIONAL, INTENT(IN):: iX2/fX2
INTEGER/REAL, OPTIONAL, INTENT(IN):: iY2/fY2
INTEGER, OPTIONAL, INTENT(IN):: iFlags

Arguments

xDC

X_DC structure containing information of DC.

xBmp

X_BITMAP structure containing information about the bitmap to be placed. The bitmap must be a valid bitmap obtained using a call to XCreateBitmap.

iX, iY / fX, fY
Viewport (XPlaceBitmap) or logical (XPlaceBitmap_W) coordinates of the point where the top-left corner of the bitmap is to be placed.

[iX2, iY2] / [fX2, fY2]
Viewport (XPlaceBitmap) or logical (XPlaceBitmap_W) coordinates of the point where the bottom-right corner of the bitmap is to be placed. The bitmap is stretched if necessary. If absent, the bitmap is copied in its natural size.

[iFlags]
Specifies a raster-operation code. These codes define how the color data of the bitmap is to be combined with the color data for the destination rectangle to achieve the final color.

The following list shows some common raster operation codes:
Value | Description
BLACKNESS | Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT | Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND | Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle (default).
SRCERASE | Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT | Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT | Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette)

Return Value

If successful, the return value is .TRUE. Otherwise, the return value is .FALSE.

See Also

XBitCopy

Wrapped APIs

CreateCompatibleDC, SelectObject, BitBlt, StretchBlt

Module

XFTGDI.f90


XPolygon

XPolygon, XPolygon_W

XPolygon and XPolygon_W draw a filled polygon with vertices defined by an array of coordinates. Polygon outline is drawn using current pen (XSetPen) and it's filled using current brush (XSetBrush). If necessary, first and last point are automatically connected.

LOGICAL FUNCTION XPolygon_W(xDC, xXY, nPoints, xPen, xBrush)

 TYPE(X_DC), INTENT(INOUT)::           xDC
TYPE(X_POINT/X_WPOINT), INTENT(IN)::  xXY(*)/xwXY(*)
INTEGER, INTENT(IN)::                 nPoints
TYPE(X_PEN), OPTIONAL, INTENT(IN)::   xPen
TYPE(X_BRUSH),OPTIONAL,INTENT(IN)::   xBrush

Arguments

xDC

X_DC structure containing information about the DC.

xXY/xwXY
An array of X_POINT (XPolygon) or X_WPOINT (XPolygon_W) structures defining coordinates of vertices in pixels/logical units.

nPoints
Number of points to be drawn

[xPen]
X_PEN structure specifying attributes of the pen used to draw the outline of the polygon. If not present, the line is drawn using the pen set by last call to XSetPen.

[xBrush]
 X_BRUSH structure specifying attributes of the brush used to fill the ellipse. If not present, the line is drawn using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XPolyline

Wrapped APIs

Polygon

Module

XFTGDI.f90


XPolyline

XPolyline, XPolyline_W

XPolyline and XPolyline_W draw a polygonal line with vertices defined by an array of coordinates. Polyline is drawn using current pen (XSetPen) and it's not filled. Polyline does not enclose the figure.

LOGICAL FUNCTION XPolyline_W(xDC, xXY, nPoints, xPen)

TYPE(X_DC), INTENT(INOUT)::           xDC
TYPE(X_POINT/X_WPOINT), INTENT(IN)::  xXY(*)/xwXY(*)
INTEGER, INTENT(IN)::                 nPoints
TYPE(X_PEN), OPTIONAL, INTENT(IN)::   xPen

Arguments

xDC

X_DC structure containing information about the DC.

xXY/xwXY
An array of X_POINT (XPolyline) or X_WPOINT (XPolyline_W) structures defining coordinates of vertices in pixels/logical units.

nPoints
Number of points to be drawn

[xPen]
 X_PEN structure specifying attributes of the pen used to draw the polyline. If not present, the line is drawn using the pen set by last call to XSetPen.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XPolygon

Wrapped APIs

Polyline

Module

XFTGDI.f90


XRectangle

XRectangle, XRectangle_W

XRectangle and XRectangle_W draw a rectangle with corners defined by given pairs of coordinates. Rectangle outline is drawn using given or current pen (XSetPen) and filled using given or current brush (XSetBrush).

LOGICAL FUNCTION XRectangle_W(xDC, iX1, iY1, iX2, iY2, xPen, xBrush)

TYPE(X_DC), INTENT(INOUT)::         xDC
INTEGER/REAL, INTENT(IN)::          iX1/fX1
INTEGER/REAL, INTENT(IN)::          iY1/fY1
 INTEGER/REAL, INTENT(IN)::          iX1/fX2
INTEGER/REAL, INTENT(IN)::          iY1/fY2
TYPE(X_PEN), OPTIONAL, INTENT(IN):: xPen
TYPE(X_BRUSH),OPTIONAL,INTENT(IN):: xBrush

Arguments

xDC

X_DC structure containing information about the DC.

iX1/fX1
 X coordinate of upper left corner of the rectangle, in pixels (XRectangle) or logical units (XRectangle_W).

iY1/fY1
 X coordinate of upper left corner of the rectangle, in pixels (XRectangle) or logical units (XRectangle_W).

iX2/fX2
X coordinate of bottom right corner of the rectangle, in pixels (XRectangle) or logical units (XRectangle_W).

iY2/fY2
Y coordinate of bottom right corner of the rectangle, in pixels (XRectangle) or logical units (XRectangle_W).

[xPen]
X_PEN structure specifying attributes of the pen used to draw the outline of the rectangle. If not present, the line is drawn using the pen set by last call to XSetPen.

[xBrush]
X_BRUSH structure specifying attributes of the brush used to fill the rectangle. If not present, the rectangle is filled using the brush set by last call to XSetBrush.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

XFTGDI will inverse top-left and right-bottom corners if inconsistent so the caller need not take care about it.

To draw only an outlined rectangle, use a hollow brush (X_BRUSH(BS_NULL, 0, 0))

See Also

XFillRect, XFillViewport

Wrapped APIs

Rectangle

Module

XFTGDI.f90


XRGB

XRGB

XRGB is a helper function used for merging intensities of red, green and blue components of the color into one composite integer representing

INTEGER FUNCTION XRGB(iR, iG, iB)

INTEGER, INTENT(IN)::           iR, iG, iB

Arguments

iR

Intensity of red component. Should be in 0-255 range. Values which exceed this range will be brought to 0 or 255.

iG

Intensity of green component. Should be in 0-255 range. Values which exceed this range will be brought to 0 or 255.

iB

Intensity of blue component. Should be in 0-255 range. Values which exceed this range will be brought to 0 or 255.

Remarks

It's more efficient to use hex format #BBGGRR than XRGB function.

You can also use the following constants for colors from the "standard" palette:

XCOLOR_BLACK | #000000
XCOLOR_BLUE | #800000
XCOLOR_GREEN | #008000
XCOLOR_CYAN | #808000
XCOLOR_RED | #000080
XCOLOR_MAGENTA | #800080
XCOLOR_BROWN | #008080
XCOLOR_LTGRAY | #C0C0C0
XCOLOR_GRAY | #808080
XCOLOR_LTBLUE | #FF0000
XCOLOR_LTGREEN | #00FF00
XCOLOR_LTCYAN | #FFFF00
XCOLOR_LTRED | #0000FF
XCOLOR_LTMAGENTA | #FF00FF
XCOLOR_YELLOW | #00FFFF
XCOLOR_WHITE | #FFFFFF

See Also

XSetPen, XSetBrush

Module

XFTGDI.f90


XScrollWindow

XScrollWindow

XScrollWindow function updates the contents of window's client area. The function shifts the current image by the given amount then generates a WM_PAINT message to display any newly exposed area.

SUBROUTINE XScrollWindow(xWnd, iHorz, iVert)

!DEC$IF DEFINED (XLITE)
INTEGER, INTENT(IN):: xWnd
!DEC$ELSE
TYPE(X_WINDOW), INTENT(IN):: xWnd
!DEC$ENDIF

INTEGER, OPTIONAL, INTENT(IN):: iHorz
INTEGER, OPTIONAL, INTENT(IN):: iVert

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window. For QuickWin projects, the handle can be obtained using GETHWNDQQ.

Full Xeffort Version: X_WINDOW structure describing the window.

[iHorz]
The amount to scroll horizontally, in physical coordinates (pixels). Sign convention is such that a negative iHorz exposes new info on the right and hides the info that was on the left edge of the client area. If not present, a value of zero is assumed.

[iVert]
The amount to scroll vertically, in physical coordinates (pixels). Sign convention is such that a negative iVert exposes new info on the bottom of the window's client area and hides the info that was at the top. If not present, a value of zero is assumed.

Remarks

XScrollWindow is faster than XUpdateWindow(xWnd) since only the newly exposed area, rather than total client area, needs to be generated. As the iHorz or iVert arguments approach or exceed client area dimensions, XScrollWindow matches XUpdateWindow in both performance and functionality. The arguments to XScrollWindow are almost always derived from changes in scroll bar position. See XScrollbarGet.

See Also

XScrollbarGet, XUpdateWindow

Wrapped APIs

ScrollWindow, UpdateWindow


XSaveBitmap

XSaveBitmap

XSaveBitmap saves given bitmap to a .bmp file on the disk.

LOGICAL
FUNCTION XSaveBitmap(xBmp, sFileName, iDepth)

TYPE(X_BITMAP), INTENT(IN)::         xBmp
CHARACTER(*), INTENT(IN)::
sFileName
INTEGER, OPTIONAL, INTENT(IN)::      iDepth

Arguments

xBmp

X_BITMAP structure containing information about the bitmap to be saved. The bitmap must be a valid bitmap obtained using a call to XCreateBitmap or XGetBitmap.

sFileName
Name of the .bmp file to be created. The file is created with name "as-is", i.e. .bmp extension is not automatically appended.

[iDepth]
Desired bitmap color depth, in bits. Can be one of {1, 4, 8, 16, 24, 32}; if out of range, will be automatically set to next higher allowed value. If absent, the bitmap is saved with color depth as kept by Windows internally (usually, the screen color depth).

Return Value

If successful, the return value is .TRUE. Otherwise, the return value is .FALSE.

See Also

XBitCopy, XGetBitmap, XCreateBitmap

Wrapped APIs

GetObject, GetDIBits

Module

XFTGDI.f90


XSetBkColor

XSetBkColor

XSetBkColor sets the current background color. The background color affects the background of non-continuous pens and hatched brushes as well as text, provided that they're drawn in OPAQUE mode set by XSetBkMode.

INTEGER
FUNCTION XSetBkColor(xDC, iBkColor)

TYPE(X_DC), INTENT(IN)::              xDC
INTEGER, INTENT(IN)::    iBKColor

Arguments

xDC

X_DC structure containing information about the DC.

iBkColor
Background color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

Return Value

Return value is the previous background color.

See Also

XSetBkMode

Wrapped APIs

SetBkColor

Module

XFTGDI.f90


XSetBkMode

XSetBkMode

XSetBkMode sets the current background mode, i.e. how the empty regions in dotted pens and hatched brushes are mixed with the background.

INTEGER FUNCTION XSetBkMode(xDC, iBkMode)

TYPE(X_DC), INTENT(IN):: xDC
INTEGER, INTENT(IN)::    iBkMode

Arguments

xDC

X_DC structure containing information about the DC.

iBkMode

Can be one of the following flags:

OPAQUE | Background is filled with the current background color set by XSetBkColor before the hatched brush, or pen is drawn.
TRANSPARENT | Background remains untouched. (default)

Return Value

Return value is the previous background mode.

See Also

XSetBkColor

Wrapped APIs

SetBkMode

Module

XFTGDI.f90


XSetBrush

XSetBrush

XSetBrush is a generic name for two functions: XSetBrush_1 and XSetBrush_2. XSetBrush sets the current brush in the device context. Brush is used for filling surfaces with subsequent drawing operations.

SUBROUTINE XSetBrush_1(xDC,iColor,iStyle,iHatch)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
iColor
INTEGER, OPTIONAL, INTENT(IN)::    iStyle
INTEGER, OPTIONAL, INTENT(IN)::    iHatch

SUBROUTINE
XSetBrush_2(xDC,xBrush)

TYPE(X_DC), INTENT(INOUT)::           xDC
TYPE(X_BRUSH), INTENT(IN)::      xBrush

Arguments

xDC

X_DC structure containing information of DC.

iColor

Brush color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function. If brush style is BS_NULL (BS_HOLLOW), color is ignored.

[iStyle]

Brush style. Can be one of the following constants:

BS_DIBPATTERN | A pattern brush defined by a device-independent bitmap (DIB) specification. Currently not supported by XFTGDI.
BS_DIBPATTERNPT | A pattern brush defined by a device-independent bitmap (DIB) specification. Currently not supported by XFTGDI.
BS_HATCHED | Hatched brush.
BS_HOLLOW BS_NULL | Hollow brush (not affecting the existing background).
BS_PATTERN | Pattern brush defined by a memory bitmap. Currently not supported by XFTGDI.
BS_SOLID | Solid brush. (default)

[iHatch]

If iStyle argument is BS_HATCHED, it defines hatch type using one of the following constants. Otherwise, it is ignored:

HS_BDIAGONAL | A 45-degree upward, left-to-right hatch
HS_CROSS | Horizontal and vertical cross-hatch
HS_DIAGCROSS | 45-degree crosshatch
HS_FDIAGONAL | A 45-degree downward, left-to-right hatch
HS_HORIZONTAL | Horizontal hatch
HS_VERTICAL | Vertical hatch

XSetBrush_2 requires X_BRUSH structure as input, containing the same information as iColor, iStyle and iHatch structures.

See Also

X_BRUSH

Wrapped APIs

CreateBrushIndirect, SelectObject

Module

XFTGDI.f90


XSetBrushHandle

XSetBrushHandle

XSetBrushHandle sets a programmer-created brush, described by its Win32 handle (HBRUSH) in the device context xDC. Brush is used for filling closed areas with subsequent drawing operations. This function is useful when an "advanced" brush is required, such as bitmapped brush. See e.g. CreateBrushIndirect Win32 function.

SUBROUTINE
XSetBrushHandle(xDC, hBrush)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
hBrush

Arguments

xDC

X_DC structure containing information of DC.

hBrush

Win32 handle of the brush. See CreateBrushIndirect Win32 API.

Remarks

XSetBrushHandle does not validate the brush handle. It is programmer's responsibility to ensure that hBrush is a valid Win32 handle, and to destroy it after no longer needed using DeleteObject API. hBrush is never selected by XFTGDI into the given xDC%hDC (outside of XFTGDI functions), so deletion should be safe. Note, however, that after the hBrush is deleted, another valid brush must be immediately substituted for given xDC by a call to XSetBrush or XSetBrushHandle. Otherwise, subsequent calls to XFTGDI functions such as XPolygon or XRectangle will yield undefined results.

See Also

XSetBrush

Module

XFTGDI.f90


XSetClipping

XSetClipping, XSetClipping_W

XSetClipping and XSetClipping_W set the clipping rectangle with corners defined by given pairs of coordinates. Any subsequent drawing is clipped to the rectangle. If the coordinates are omitted, the clipping rectangle is removed and no clipping will occur subsequently.

SUBROUTINE XSetClipping_W(xDC, iX1, iY1, iX2, iY2)

TYPE(X_DC), INTENT(INOUT)::             xDC
INTEGER/REAL, OPTIONAL, INTENT(IN)::    iX1/fX1
INTEGER/REAL, OPTIONAL, INTENT(IN)::    iY1/fY1
 INTEGER/REAL, OPTIONAL, INTENT(IN)::    iX1/fX2
INTEGER/REAL, OPTIONAL, INTENT(IN)::    iY1/fY2

Arguments

xDC

X_DC structure containing information about the DC.

iX1/fX1, iY1/fY1
 X and Y coordinate of upper left corner of the rectangle, in pixels (XSetClipping) or logical units (XSetClipping_W).

iX2/fX2, iY2/fY2
X and Y coordinate of bottom right corner of the rectangle, in pixels (XSetClipping) or logical units (XSetClipping_W).

See Also

XSetViewport

Wrapped APIs

SelectClipRgn

Module

XFTGDI.f90


XSetFont

XSetFont, XSetFont_W

XSetFont function creates a font with given characteristics and sets it as the font used for subsequent text output for given DC.

LOGICAL FUNCTION
XSetFont_W(xDC,
sFontName, iHeight, iEscapement, iWidth, iWeight, &
bItalic, bUnderline, bStrikeOut)

TYPE(X_DC), INTENT(INOUT)::     xDC
CHARACTER*(*), INTENT(IN)::     sFontName
INTEGER/REAL,
INTENT(IN)::      iHeight/fHeight
INTEGER, OPTIONAL, INTENT(IN)::  iEscapement
INTEGER/REAL,
OPTIONAL, INTENT(IN)::  iWidth/fWidth
INTEGER, OPTIONAL, INTENT(IN)::  iWeight
LOGICAL, OPTIONAL, INTENT(IN)::  bItalic
LOGICAL, OPTIONAL, INTENT(IN)::  bUnderline
LOGICAL, OPTIONAL, INTENT(IN)::  bStrikeOut

Arguments

xDC

X_DC structure containing information of DC.

sFontName

Name of the typeface, such as "Arial" or "Times New Roman". If the requested typeface is not installed on the system, Windows font mapper will try to substitute a font with most similar characteristics.

iHeight/fHeight
Height of the font, in pixels (XSetFont) or logical units (XSetFont_W). Font height comprises of the entire character cell height.

[iEscapement]
Angle of the font, in tenths of degrees, relative to the horizontal line. If absent, a horizontal font is created.

[iWidth/fWidth]

Average width of a character, in pixels (XSetFont) or logical units (XSetFont_W). If not present, default font width is used.

[iWeight]

Weight of the font, in range of 0 to 1000. If omitted, default font weight is used (0). The following constants are also defined for convenience:

Value | Weight
FW_DONTCARE | 0
FW_THIN | 100
FW_EXTRALIGHT | 200
FW_ULTRALIGHT | 200
FW_LIGHT | 300
FW_NORMAL | 400
FW_REGULAR | 400
FW_MEDIUM | 500
FW_SEMIBOLD | 600
FW_DEMIBOLD | 600
FW_BOLD | 700
FW_EXTRABOLD | 800
FW_ULTRABOLD | 800
FW_HEAVY | 900
FW_BLACK | 900

[bItalic]

If present and .TRUE., specifies that italic version of the font is requested.

[bUnderline]

If present and .TRUE., specifies that the font is underlined.

[bStrikeOut]

If present and .TRUE., specifies that the font is strike-out.

Wrapped APIs

CreateFontIndirect

Module

XFTGDI.f90


XSetPen

XSetPen

XSetPen is a generic name for two subroutines: XSetPen_1 and XSetPen_2. XSetPen sets the current pen in the device context. Pen is used for drawing lines with subsequent drawing operations.

SUBROUTINE
XSetPen_1(xDC,iColor,iStyle,iWidth)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
iColor
INTEGER, OPTIONAL, INTENT(IN)::    iStyle
INTEGER, OPTIONAL, INTENT(IN)::    iWidth

SUBROUTINE
 XSetPen_2(xDC,xPen)

TYPE(X_DC), INTENT(INOUT)::      xDC
TYPE(X_PEN), INTENT(IN)::
xPen

Arguments

xDC

X_DC structure containing information of DC.

iColor

Pen color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

[iStyle]

Pen style. Can be one of the following constants:

PS_SOLID | Pen is solid. (default)
PS_DASH | Pen is dashed.
PS_DOT | Pen is dotted.
PS_DASHDOT | Pen has alternating dashes and dots.
PS_DASHDOTDOT | Pen has dashes and double dots.
PS_NULL | Pen is invisible.

[iWidth]

Pen width, in pixels. Value of zero indicates 1 pixel. Default value is 1.

XSetPen_2 requires X_PEN structure as input.

Remarks

Windows 95/98/ME: A pen thicker than 1 pixel can only have PS_SOLID style. If a thicker pen is required, other PS_ styles will be ignored and the pen will be created as solid.

Wrapped APIs

CreatePen, SelectObject

Module

XFTGDI.f90


XSetPenHandle

XSetPenHandle

XSetPenHandle sets a pen created by programmer described by its Win32 handle (HBRUSH) in the device context xDC. Pen is used for drawing lines with subsequent drawing operations. This function is useful when an "advanced" pen is required, such as bitmapped or user-style pen. See e.g. ExtCreatePen Win32 function.

SUBROUTINE
XSetPenHandle(xDC, hPen)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
hPen

Arguments

xDC

X_DC structure containing information of DC.

hPen

Win32 handle of the pen. See CreatePenIndirect, ExtCreatePen Win32 APIs.

Remarks

XSetPenHandle does not validate the pen handle. It is programmer's responsibility to ensure that hPen is a valid Win32 handle, and to destroy it after no longer needed using DeleteObject API. hPen is never selected by XFTGDI into the given xDC%hDC (outside of XFTGDI functions), so deletion should be safe. Note, however, that after the hPen is deleted, another valid pen must be immediately substituted for given xDC by a call to XSetPen or XSetPenHandle. Otherwise, subsequent calls to XFTGDI functions such as XLine or XRectangle will yield undefined results.

See Also

XSetPen

Module

XFTGDI.f90


XSetPixel

XSetPixel, XSetPixel_W

XSetPixel and XSetPixel_W set the color of the specified pixel.

LOGICAL FUNCTION XSetPixel_W(xDC, iX, iY, iColor)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER/REAL, INTENT(IN)::      iX/fX
INTEGER/REAL, INTENT(IN)::      iY/fY
INTEGER, INTENT(IN)::           iColor

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX
 X coordinate of the pixel, in pixels (XSetPixel) or logical units (XSetPixel_W).

iY/fY
Y coordinate of the pixel, in pixels (XSetPixel) or logical units (XSetPixel_W).

iColor
Color of the pixel. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XGetPixel

Wrapped APIs

SetPixelV

Module

XFTGDI.f90


XSetROPMode

XSetROPMode

XSetROPMode sets the current foreground raster-operation mode, i.e. how the pens and brushes are mixed with the existing objects on the background. Normally, new object just overdraw the existing background (iROPMode = R2_COPYPEN). Using this function

INTEGER FUNCTION XSetROPMode(xDC, iROPMode)

TYPE(X_DC), INTENT(IN):: xDC
INTEGER, INTENT(IN)::    iROPMode

Arguments

xDC

X_DC structure containing information about the DC.

iROPMode

Can be one of the following flags:

R2_BLACK | Pixel is always 0.
R2_COPYPEN | Pixel is the pen color. (default)
R2_MASKNOTPEN | Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN | Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT | Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN | Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN | Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT | Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP | Pixel remains unchanged.
R2_NOT | Pixel is the inverse of the screen color.
R2_NOTCOPYPEN | Pixel is the inverse of the pen color.
R2_NOTMASKPEN | Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN | Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN | Pixel is the inverse of the R2_XORPEN color.
R2_WHITE | Pixel is always 1.
R2_XORPEN | Pixel is a combination of the colors in the pen and in the screen, but not in both.

Return Value

Return value is the previous raster-operation mode.

Remarks

Apart from normal R2_COPYPEN, the most valuable flags are R2_XORPEN and R2_NOTXORPEN. Since XOR and .NOT.XOR operations yield the same result when applied twice, these modes can be used for fast adding and removing of overlaying objects, which can be useful for animation effects.

Wrapped APIs

SetROP2

Module

XFTGDI.f90


XSetScaling

XSetScaling

XSetScaling routine defines the logical coordinate system for given DC, like XSetWindow routine. The logical coordinate system is an arbitrary cartesian system, expressed in arbitrary units (real numbers). All XFTGDI routines with _W suffix operate on logical coordinate system.

XSetScaling specifies mapping of the logical coordinate system origin to the viewport previously defined by XSetViewport, as well as the scaling factor, i.e. how many pixels is contained in each logical (window) unit.

SUBROUTINE
XSetScaling(xDC, fX1, fY1, fScalingX, fScalingY)

TYPE(X_DC), INTENT(INOUT)::  xDC
REAL, INTENT(IN)::
fX1, fY1
REAL, INTENT(IN)::           fScalingX
REAL, OPTIONAL, INTENT(IN):: fScalingY

Arguments

xDC

X_DC structure containing information about the DC.

fX1
 Coordinate of viewport's left edge in logical coordinate system.

fY1
 Coordinate of viewport's top edge in logical coordinate system.

fScalingX
Scaling factor by X-axis, which determines how many pixels is contained in each logical (window) unit. Must be a non-zero value. The following special values can be also used (in this case, fScalingY argument is ignored):

MM_PIXELS | One logical unit is equal to one pixel.
MM_METRIC | One logical unit is equal to one millimeter .
MM_ENGLISH | One logical unit is equal to one inch.
MM_POINTS | One logical unit is equal to one point (=1/72 in).

[fScalingY]
Scaling factor by Y-axis. If absent, the Y-axis scaling factor is taken equal to X-axis scaling factor.

Remarks

Logical (window) coordinate system can be freely orientated with the only restriction that the viewport has to have non-zero area.

See Also

XSetViewport, XSetWindow, XGetGDIWindow

Module

XFTGDI.f90


XSetTextColor

XSetTextColor

XSetTextColor sets the current color of the text in DC. The text can be drawn using XTextOut.

SUBROUTINE XSetTextColor(xDC,iColor)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
iColor

Arguments

xDC

X_DC structure containing information of DC.

iColor

Text color color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function.

See Also

XSetBkColor

Wrapped APIs

SetTextColor

Module

XFTGDI.f90


XSetViewport

XSetViewport

XSetViewport routine sets the viewport at specified pair of coordinates, and optionally sets the clipping rectangle.

Viewport is rectangle on DC surface, defined in pixels (device units), which defines the region where subsequent drawing operations will occur. All drawing operations (such as XRectangle, XTextOut etc.) operate on coordinates which are relative to viewport origin.

SUBROUTINE
XSetViewport(xDC, iX1, iY1, iX2, iY2, bClip)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER, INTENT(IN)::
iX1,iY1,iX2,iY2
LOGICAL, OPTIONAL, INTENT(IN):: bClip

Arguments

xDC

X_DC structure containing information about the DC.

iX1, iY1
X and coordinate of upper left corner of the viewport, in pixels, relative to physical top-left corner of the DC (window's client area, paper printable surface etc.).

iX2, iY2
X and Y coordinate of bottom right corner of the rectangle, in pixels

[bClip]
If present and .TRUE., any subsequent drawing on the viewport will be clipped to the viewport rectangle. Otherwise (default), no clipping will occur, i.e. the application can freely draw outside of the rectangle.

Remarks

If top/left and bottom/right coordinates are reversed, Xeffort reverses them internally. Thus, a viewport always has downward/left-to-right orientation.

See Also

XGetViewport, XSetWindow, XSetClipping

Module

XFTGDI.f90


XSetWindow

XSetWindow

XSetWindow routine defines the logical coordinate system for given DC. The logical coordinate system is an arbitrary cartesian system, expressed in arbitrary units (real numbers). All XFTGDI routines with _W suffix operate on logical coordinate system.

XSetWindow specifies mapping of logical coordinate system to viewport previously defined by XSetViewport. Each argument to XSetWindow defines the coordinate of corresponding viewport pixel in logical coordinate system.

SUBROUTINE
XSetWindow(xDC, fX1, fY1, fX2, fY2)

TYPE(X_DC), INTENT(INOUT)::  xDC
REAL, INTENT(IN)::
fX1, fY1, fX2, fY2

Arguments

xDC

X_DC structure containing information about the DC.

fX1
Coordinate of viewport's left edge in logical coordinate system.

fY1
 Coordinate of viewport's top edge in logical coordinate system.

fX2
Coordinate of viewport's right edge in logical coordinate system.

fY2
Coordinate of viewport's bottom edge in logical coordinate system.

Remarks

Logical (window) coordinate system can be freely orientated with the only restriction that the viewport has to have non-zero area.

See Also

XSetViewport, XGetGDIWindow, XSetScaling

Module

XFTGDI.f90


XTextOut

XTextOut, XTextOut_W

XTextOut and XTextOut_W draw text on specified position. The text is drawn using the currently selected font using XSetFont.

LOGICAL
FUNCTION XTextOut_W(xDC,
fX, fY, sText, iColor, bOpaque, iStyle, bEntire)

TYPE(X_DC), INTENT(INOUT)::     xDC
INTEGER/REAL,
INTENT(IN)::
iX/fX
INTEGER/REAL,
INTENT(IN)::
iY/fY
CHARACTER(*), INTENT(IN)::      sText
INTEGER, OPTIONAL, INTENT(IN):: iColor
LOGICAL, OPTIONAL, INTENT(IN):: bOpaque
INTEGER, OPTIONAL, INTENT(IN):: iStyle
LOGICAL, OPTIONAL, INTENT(IN):: bEntire

Arguments

xDC

X_DC structure containing information about the DC.

iX/fX
Starting X coordinate of the text, in pixels (XTextOut) or logical units (XSetFont_W). By default, the text is drawn to the right of that position. iStyle argument, if present can change that setting.

iY/fY
Starting Y coordinate of the text, in pixels (XTextOut) or logical units (XSetFont_W). By default, this argument defines top position of text bounding rectangle; iStyle argument, if present, can change that setting.

sText
Text to be drawn. The text is TRIMmed on output unless bEntire argument is set to .TRUE..

[iColor]
Text color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function. If not present, color set by XSetTextColor is used.

[bOpaque]

If present and .TRUE., the text background is opaque (it overwrites the image) and it is drawn in color set by XSetBkColor. Default is transparent text.

[iStyle]

An .OR. combination of formatting flags. Formatting flags affect relative position of text to the reference point. Available constants are:

TA_BASELINE | The reference point will be on the base line of the text.
TA_BOTTOM | The reference point will be on the bottom edge of the bounding rectangle.
TA_TOP | The reference point will be on the top edge of the bounding rectangle.
TA_CENTER | The reference point will be aligned horizontally with the center of the bounding rectangle.
TA_LEFT | The reference point will be on the left edge of the bounding rectangle.
TA_RIGHT | The reference point will be on the right edge of the bounding rectangle.
TA_RTLREADING | Windows 95 only: The text is laid out in right to left reading order, as opposed to the default left to right order. This applies only when the font selected into the device context is either Hebrew or Arabic.

TA_BASELINE, TA_BOTTOM and TA_TOP are mutually exclusive; TA_CENTER, TA_LEFT and TA_RIGHT are mutually exclusive. The default is TA_LEFT.OR.TA_TOP.

[bEntire]

If present and .TRUE., any trailing spaces in sText are also output. Normally, trailing spaces are ignored.

See Also

XSetFont , XWrite

Return Value

.TRUE. if successful, otherwise .FALSE.

Wrapped APIs

TextOut, SetTextAlign, SetTextColor

Module

XFTGDI.f90


XUpdateWindow

XUpdateWindow

XUpdateWindow function updates the contents of window's client area. The function invalidates given rectangle (in physical coordinates) and updates the window, generating a WM_PAINT message.

SUBROUTINE XUpdateWindow(xWnd, iX1, iY1, iX2, iY2)

!DEC$IF DEFINED (XLITE)
INTEGER, INTENT(IN):: xWnd
!DEC$ELSE
TYPE(X_WINDOW), INTENT(IN):: xWnd
!DEC$ENDIF
INTEGER, OPTIONAL, INTENT(IN):: iX1, iY1, iX2, iY2

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window. For QuickWin projects, the handle can be obtained using GETHWNDQQ.

Full Xeffort Version: X_WINDOW structure describing the window.

[iX1, iY1, iX2, iY2]
Bounding coordinates of the rectangle to be updated, in physical coordinates. If not present, entire client area is updated. All four arguments together have to be present in order to be processed.

See Also

XScrollWindow

Wrapped APIs

InvalidateRect, UpdateWindow

Module

XFTGDI.f90


XView2Client

XView2Client

XView2Client routine converts coordinates of a single physical point from viewport coordinate system to physical (client) coordinates. The origin of physical

SUBROUTINE
XView2Client(xDC, iX, iY, jX, jY)

TYPE(X_DC),INTENT(IN):: xDC
INTEGER,INTENT(IN)::    iX,iY
INTEGER,INTENT(OUT)::   jX,jY

Arguments

xDC

X_DC structure containing information about the DC.

jX/jY

X/Y coordinate in viewport coordinate system.

iX/iY
Converted X/Y coordinate in physical (client) coordinate system

See Also

Coordinate Systems Overview, XSetViewport, XClient2Wnd, XClient2View

Module

XFTGDI.f90


XView2Wnd

XView2Wnd

XView2Wnd routine converts coordinates of a single physical point from viewport coordinate system to logical (window) coordinates.

XView2Wnd is generic name for two routines, first converting coordinates in scalar form, second in form of array of structures.

SUBROUTINE
XView2Wnd_1(xDC, jX, jY, fX, fY)

TYPE(X_DC), INTENT(IN)::              xDC
INTEGER, INTENT(IN)::    jX,jY
REAL, INTENT(OUT)::      fX,fY

SUBROUTINE
XView2Wnd_2(xDC, xXY, xwXY)

TYPE(X_DC), INTENT(IN)::      xDC
TYPE(X_POINT), INTENT(IN)::   xXY(:)
TYPE(X_WPOINT), INTENT(OUT)::         xwXY(:)

Arguments

xDC

X_DC structure containing information about the DC.

jX/jY

X/Y coordinate in viewport coordinate system.

fX/fY
Converted X/Y coordinate in logical coordinate system

xXY
An array of X_POINT structures containing viewport coordinates to be converted.

xwXY
An array of X_WPOINT structures containing converted logical coordinates

See Also

Coordinate Systems Overview, XSetWindow, XWnd2View

Module

XFTGDI.f90


XWnd2Client

XWnd2Client

XWnd2Client routine converts coordinates of a single physical point from logical (window) coordinates system to physical (client) coordinates.

SUBROUTINE
XWnd2Client(xDC, fX, fY, jX, jY)

TYPE(X_DC), INTENT(IN)::              xDC
REAL, INTENT(IN)::       fX,fY
INTEGER, INTENT(OUT)::   jX,jY

Arguments

xDC

X_DC structure containing information about the DC.

fX/fY
X/Y coordinate in logical coordinate system

jX/jY
Converted X/Y coordinate in physical (window) coordinate system.

See Also

XSetWindow, XClient2Wnd

Module

XFTGDI.f90


XWnd2View

XWnd2View

XWnd2View routine converts coordinates of a single physical point from logical (window) coordinates system to viewport coordinates.

XWnd2View is generic name for two routines, first converting coordinates in scalar form, second in form of array of structures.

SUBROUTINE
XWnd2View_1(xDC, fX, fY, jX, jY)

TYPE(X_DC), INTENT(IN)::              xDC
REAL, INTENT(IN)::       fX,fY
INTEGER, INTENT(OUT)::   jX,jY

SUBROUTINE
XWnd2View_2(xDC, xwXY, xXY)

TYPE(X_DC), INTENT(IN)::     xDC
TYPE(X_WPOINT), INTENT(IN)::         xwXY(:)
TYPE(X_POINT), INTENT(OUT)::         xXY(:)

Arguments

xDC

X_DC structure containing information about the DC.

fX/fY
X/Y coordinate in logical coordinate system

jX/jY
Converted X/Y coordinate in viewport coordinate system.

xwXY
An array of X_WPOINT structures containing logical coordinates to be converted

xXY
An array of X_POINT structures containing converted viewport coordinates.

See Also

Coordinate Systems Overview, XSetWindow, XView2Wnd

Module

XFTGDI.f90


XWrite

XWrite

XWrite routine draws one or more lines of text starting from the position set by last call to XMoveTo or XWrite, and moves the current position below the just written text. The text can be additionally formatted using set of flags in optional iStyle argument.

LOGICAL
FUNCTION XWrite(xDC, sText, iColor, bOpaque, iStyle)

TYPE(X_DC), INTENT(INOUT)::     xDC
CHARACTER(*), INTENT(IN)::      sText
INTEGER, OPTIONAL, INTENT(IN):: iColor
LOGICAL, OPTIONAL, INTENT(IN):: bOpaque
INTEGER, OPTIONAL, INTENT(IN):: iStyle

Arguments

xDC

X_DC structure containing information about the DC.

sText
Text to be drawn. The text can contain multiple lines (use char(13)//char(10) as a line separator). The text is not trimmed on output.

[iColor]
Text color. Color can be set in hex format #BBGGRR, where BB, GG, RR are intensities of blue, green, or red component respectively or using XRGB function. If not present, color set by XSetTextColor is used.

[bOpaque]

If present and .TRUE., the text background is opaque (it overwrites the image) and it is drawn in color set by XSetBkColor. Default is transparent text.

[iStyle]

An .OR. combination of formatting flags. Formatting flags affect relative position of text to the reference rectangle. The reference rectangle has the current position as the top left corner, and the right viewport border as the right side. Available constants are:

Value | Description
DT_CENTER | Centers text horizontally in the reference rectangle.
DT_EDITCONTROL | Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS or DT_PATH_ELLIPSIS | Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified rectangle. The given string is not modified unless the DT_MODIFYSTRING flag is specified. You can specify DT_END_ELLIPSIS to replace characters at the end of the string, or DT_PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash.
DT_EXPANDTABS | Expands tab characters. The default number of characters per tab is eight.
DT_EXTERNALLEADING | Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.
DT_INTERNAL | Uses the system font to calculate text metrics.
DT_LEFT | Aligns text to the left.
DT_MODIFYSTRING | Modifies the given string to match the displayed text. This flag has no effect unless the DT_END_ELLIPSIS or DT_PATH_ELLIPSIS flag is specified.
DT_NOCLIP | Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.
DT_NOPREFIX | Turns off processing of prefix characters. Normally, DrawText interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off.
DT_RIGHT | Aligns text to the right.
DT_RTLREADING | Layout in right to left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic font. The default reading order for all text is left to right.
DT_SINGLELINE | Displays text on a single line only. Carriage returns and linefeeds do not break the line.
DT_TABSTOP | Sets tab stops. Bits 15–8 (high-order byte of the low-order word) of the uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight.
DT_TOP | Top-justifies text (single line only).
DT_VCENTER | Centers text vertically (single line only).
DT_WORDBREAK | Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.
DT_WORD_ELLIPSIS | Truncates text that does not fit in the rectangle and adds ellipses.

DT_CENTER, DT_LEFT and DT_RIGHT are mutually exclusive. The default is DT_LEFT .OR. DT_TOP .OR. DT_WORDBREAK .OR. DT_NOPREFIX. That means that, if the text length exceeds the right viewport margin, the text will wrap into the next row.

See Also

XSetFont, XTextOut

Return Value

If successful, the function returns .TRUE. If the text is about to overflow the bottom margin of the viewport, the function returns .FALSE. That allows that e.g. during printing of a text, an application can insert a page break using XEndPage/XStartPage and continue printing on the next page.

Wrapped APIs

DrawText, SetTextAlign, SetTextColor

Module

XFTGDI.f90


XFTMDI Overview

XFTMDI Overview

Reference

XFTMDI module is used for handling child windows in MDI (Multiple Document Interface) environment. Each document in an MDI application is displayed in a separate child window within the client area of the application's main window.

An MDI application has three kinds of windows: a frame window (XW_FRAME), an MDI client window (XW_MDI), as well as a number of child windows. An MDI application does not display output in the client area of the frame window. Instead, it displays the MDI client window. An MDI client window is a special type of child window belonging to the preregistered window class MDICLIENT; it serves as the background for child windows. It also provides support for creating and manipulating child windows. For example, an MDI application can create, activate, or maximize child windows by sending messages to the MDI client window.

When the user opens or creates a document, the XW_MDI window creates a child window for the document. Each child window typically has a sizing border, a title bar, a window menu, a Minimize button, and a Maximize button. Because a child window is clipped, it is confined to the client window and cannot appear outside it.

The frame window of an MDI application should include a menu bar with a Window menu. The Window menu should include items that arrange the child windows within the client window or that close all child windows. The Window menu of a typical MDI application might include the items in the following table.

Menu item | Purpose
Tile | Arranges child windows in a tile format so that each appears in its entirety in the client window.
Cascade | Arranges child windows in a cascade format. The child windows overlap one another, but the title bar of each is visible.
Arrange Icons | Arranges the icons of minimized child windows along the bottom of the client window.
Close All | Closes all child windows.

Whenever a child window is created, the system automatically appends a new menu item to the Window menu. The text of the menu item is the same as the text on the menu bar of the new child window. By clicking the menu item, the user can activate the corresponding child window. When a child window is destroyed, the system automatically removes the corresponding menu item from the Window menu.


XFTMDI Reference

XFTMDI Reference

Overview

XMDICreate

XMDIDestroy

XMDIGetActive

XMDIGetCount

XMDISetActive


XMDICreate

XMDICreate

XMDICreate function creates a new MDI child window.

LOGICAL FUNCTION
 XMDICreate(xWnd, sWindowName, iStyle, &
iX, iY, iWidth, iHeight, sClassName)

TYPE(X_WINDOW), INTENT(OUT)::      xWnd
CHARACTER(*), INTENT(IN)::
sWindowName
INTEGER, OPTIONAL, INTENT(IN)::    iStyle
INTEGER, OPTIONAL, INTENT(IN)::    iX, iY
INTEGER, OPTIONAL, INTENT(IN)::    iWidth, iHeight
CHARACTER(*), OPTIONAL, INTENT(IN)::    sClassName

Arguments

xWnd
 X_WINDOW structure representing newly created MDI child window.

sWindowName
Title of the child window.

[iStyle]
An OR combination of window styles. If absent, WS_HSCROLL + WS_VSCROLL + WS_VISIBLE is used.

[iX, iY]
Position of the upper-left corner of the window, in pixels. If absent, (0,0) is used. The position is relative to frame window's client area origin.

[iWidth, iHeight]
Width and height of the window, in pixels. If absent, value of CW_USEDEFAULT is used, indicating that the system should pick window dimensions.

[sClassName]
Name of a registered window class. Window class defines basic properties of a (set of) window and is identified by its name. Xeffort doesn't contain wrappers for RegisterClass API; all native Xeffort windows are of class named Xeffort_CLASSNAME="XWndClass". An application seldom needs to use windows of classes other than system ones. Examples of system classes are buttons and edit boxes (which are handled by XFTCTRL module anyway). MDI child windows handled by Xeffort should, however, have sClass argument set to "MDIChild".

Return Value

If successful, the return value is .TRUE., otherwise .FALSE.

Remarks

Lifetime of the X_WINDOW variable supplied as the actual argument should be at least as long as lifetime of the window itself, i.e. until window is destroyed using XDestroyWindow. See XFTWND Design Considerations page for a thorough discussion.

See Also

XMDIDestroy, XCreateWindow

Wrapped APIs

WM_MDICREATE

Module

XFTMDI.f90


XMDIDestroy

XMDIDestroy

XMDIDestroy function destroys a MDI child window previously created by XMDICreate.

LOGICAL FUNCTION XMDIDestroy(xWnd)

TYPE(X_WINDOW)::               xWnd

Arguments

xWnd
 X_WINDOW structure representing the MDI child window to be destroyed.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XMDICreate

Wrapped APIs

WM_MDIDESTROY

Module

XFTMDI.f90


XMDIGetActive

XMDIGetActive

XMDIGetActive function returns a pointer to currently active MDI child window previously created by XMDICreate.

FUNCTION XMDIGetActive()
RESULT(xWnd)

TYPE(X_WINDOW), POINTER::     xWnd

Return Value

If successful, the functions returns a pointer to currently active MDI child window. If there is not any MDI child window, the returned pointer is NULLIFYed.

See Also

XMDICreate, XMDISetActive

Wrapped APIs

WM_MDIGETACTIVE

Module

XFTMDI.f90


XMDIGetCount

XMDIGetCount

XMDIGetCount function returns the current number of MDI Child windows previously created with XMDICreate.

INTEGER FUNCTION XMDIGetCount()

Return Value

If successful, the functions returns the current number of MDI Child windows.

See Also

XMDICreate

Wrapped APIs

FindWindowEx

Module

XFTMDI.f90


XMDISetActive

XMDISetActive

XMDISetActive function activates a MDI child window.

LOGICAL FUNCTION XMDISetActive(xChild)

TYPE(X_WINDOW)::  xChild

Arguments

xChild
 X_WINDOW structure representing MDI child window to be activated.

Return Value

If successful, the return value is .TRUE., otherwise .FALSE.

See Also

XMDICreate, XMDIGetActive, WM_MDIACTIVATE, WM_CHILDACTIVATE

Wrapped APIs

WM_MDIACTIVATE

Module

XFTMDI.f90


XFTMenu Overview

XFTMenu Overview

Reference

XFTMenu module is used for handling of menus. A menu is a list of items that specify options or groups of options (a submenu) for an application. Clicking a menu item opens a submenu or causes the application to carry out a command.

A menu is arranged in a hierarchy. At the top level of the hierarchy is the menu bar; which contains a list of drop-down menus, which in turn can contain submenus. A menu bar is sometimes called a top-level menu.

A menu item can either carry out a command or open a submenu. Items that carry out a command are called command items. Command items cannot have submenus. An item on the menu bar almost always opens a menu. Menu bars rarely contain command items. When a drop-down menu is displayed, it is attached to the menu bar.

The menu names on a menu bar represent the main categories of commands that an application provides. Selecting a menu name from the menu bar typically opens a menu whose menu items correspond to the commands in a category. For example, a menu bar might contain a File menu name that, when clicked by the user, activates a menu with menu items such as New, Open, and Save.

Only an overlapped or pop-up window can contain a menu bar; a child window cannot contain one. If the window has a title bar, the system positions the menu bar just below it. A menu bar is always visible. A submenu is not visible, however, until the user selects a menu item that activates it.

Menus which do not have menu bar are referred to as popup menus or, to avoid confusion, context menus. Context menus are typically displayed when user right-clicks on an item in an applications, presses Shift+F10 or Context menu button on the keyboards that have it. The application is informed that it could display a context menu in form of WM_CONTEXTMENU message.

Menus and menu items can be created at run-time, or designed in resource editor and saved as a resource in a .exe or .dll file; combination of these methods is possible as well. Every menu item has a unique numeric identifier. Also, menu items can be referred by their index in their owner menu. Since there can be several levels of submenu hierarchy, an item can be referred by an array of indices. For example, (/1,3,2/) refers to 2nd item in submenu opened as 3rd item of 1st item on the menu bar. XFTMenu module provides access to menu items both by their ID or by their index array.


XFTMenu Menu Item Types

XFTMenu: Menu Item Types

The following flags define type of a menu item. The type of menu item can be set using XMenuSet or XInsertMenuItem routines, and retrieved using XMenuGet routine.

Value | Meaning
MFT_BITMAP | Displays the menu item using a bitmap. This type is not directly supported by Xeffort.
MFT_MENUBARBREAK | Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, a vertical line separates the new column from the old.
MFT_MENUBREAK | Places the menu item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu). For a drop-down menu, submenu, or shortcut menu, the columns are not separated by a vertical line.
MFT_OWNERDRAW | Assigns responsibility for drawing the menu item to the window that owns the menu. The window receives a WM_MEASUREITEM message before the menu is displayed for the first time, and a WM_DRAWITEM message whenever the appearance of the menu item must be updated.
MFT_RADIOCHECK | Displays selected menu items using a radio-button mark instead of a check mark.
MFT_RIGHTJUSTIFY | Right-justifies the menu item and any subsequent items. This value is valid only if the menu item is in a menu bar.
MFT_RIGHTORDER | Specifies that menus cascade right-to-left (the default is left-to-right). This is used to support right-to-left languages, such as Arabic and Hebrew.
MFT_SEPARATOR | Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line.
MFT_STRING | Displays the menu item using a text string. The dwTypeData member is the pointer to a null-terminated string, and the cch member is the length of the string.

The MFT_BITMAP, MFT_SEPARATOR, and MFT_STRING values cannot be combined with one another.

Reference


XFTMenu Reference

XFTMenu Reference

Overview

Menu Creation and Destruction

XContextMenu

XCreateMenu

XLoadMenu

XSetWindowMenu

XGetWindowMenu

Controlling Menu Items

XInsertMenuItem

XDeleteMenuItem

XMenuSet

XMenuSetBmp

XMenuGet

XFTMenu Types

X_MENU

X_MENUITEM


X_MENU

X_MENU

X_MENU structure describes a menu.

TYPE X_MENU
    INTEGER:: hMenu = 0
    ...
END TYPE X_MENU

Members

hWnd

Windows handle of the Menu.

See Also

XLoadMenu, XCreateMenu

Module

XFTMenu.f90


X_MENUITEM

X_MENUITEM

X_MENUITEM structure describes a menu item.

TYPE X_MENUITEM
   INTEGER:: iType = 0
   INTEGER:: iState = 0
   INTEGER:: ID = 0
   CHARACTER(64):: sTitle = ""
END TYPE X_MENUITEM

Members

iType
Meny item type. Can be a combination of flags described in Menu Item Types.

iState
Menu item state. Can be a combination of the following flags:

Value | Meaning
MFS_CHECKED | Checks the menu item.
MFS_DEFAULT | Specifies that the menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
MFS_DISABLED | Disables the menu item and grays it so that it cannot be selected. This is equivalent to MFS_GRAYED.
MFS_ENABLED | Enables the menu item so that it can be selected. This is the default state.
MFS_GRAYED | Disables the menu item and grays it so that it cannot be selected. This is equivalent to MFS_DISABLED.
MFS_HILITE | Highlights the menu item.
MFS_UNCHECKED | Unchecks the menu item.
MFS_UNHILITE | Removes the highlight from the menu item. This is the default state.

ID
Menu item identifier. An arbitrary application-defined integer which should be unique among all the menu item IDs within the same menu.

sTitle
Title of the menu item. Use an ampersand (&) to denote that the character following it presents a mnemonic key (i.e. it is underlined and the menu item can be activated using Alt+key)

See Also

XInsertMenuItem

Module

XFTMenu.f90


XContextMenu

XContextMenu

XContextMenu displays a context (popup) menu previously created using XCreateMenu(.TRUE.) and filled using XInsertMenuItem. This function is typically invoked from a WM_CONTEXTMENU handler.

INTEGER FUNCTION XContextMenu(xMenu, xParent, iX, iY, iFlags)

TYPE (X_MENU), INTENT(IN)::     xMenu
!DEC$IF .NOT.DEFINED(XLITE)
TYPE(X_WINDOW)::                xParent
!DEC$ELSE
INTEGER, INTENT(IN)::           xParent
!DEC$ENDIF
INTEGER, INTENT(IN)::           iX, iY
INTEGER, OPTIONAL, INTENT(IN):: iFlags

Arguments

xMenu
 X_MENU structure representing the menu to be displayed. The menu must have been previously created using XCreateMenu(.TRUE.) and filled using XInsertMenuItem.

xParent
LITE Xeffort Version: (INTEGER) Handle of the window which will serve as parent for the menu. For QuickWin projects, the handle can be obtained using GETHWNDQQ. This handle can be NULL, indicating that desktop will serve as parent.

Full Xeffort Version: X_WINDOW structure describing the parent window.

iX, iY
Position of the menu's top left corner, in screen-relative coordinates

[iAction]
An integer constant describing which property of the menu item be retrieved. The following combinations of iAction and type of Value are allowed:

Value | iAction | Meaning
Integer | <not used> | Returns the type of the menu item.
Character | XMENU_TITLE (default) | String of the menu item. Ampersand (&) denotes that the character following it presents a mnemonic key (i.e. it is underlined and the menu item can be activated using Alt+key)
Logical | XMENU_STATE (default) | Returns .TRUE. if the menu item is checked (has a check-mark next to its text)
Logical | XMENU_ENABLE | Returns .TRUE. if the menu item is enabled, and .FALSE. otherwise.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XMenuSet

Wrapped APIs

GetMenuItemInfo, GetSubMenu

Module

XFTMenu.f90


XCreateMenu

XCreateMenu

XCreateMenu creates an empty menu bar or popup (context) menu

FUNCTION XCreateMenu(bContext) RESULT(xMenu)

TYPE(X_MENU)::                  xMenu
LOGICAL, INTENT(IN)::           bContext

Arguments

bContext
If present and .TRUE. the new menu will be a popup (context) menu that can be displayed using XContextMenu. Else, the new menu is a menu bar which can be associated with a window using XSetWindowMenu.

Return Value

Return value is a X_MENU structure which can be used in subsequent operations on the menu. Since the menu is empty, its items should be first created using XInsertMenuItem. If the function fails, the return X_MENU structure is invalid, i.e. its hMenu member is zero.

Remarks

Context menus created using this function should be destroyed after no longer needed using XDestroyMenu. If the menu is latter assigned to a window using XSetWindowMenu, destruction is not required.

See Also

XContextMenu, XSetWindowMenu, XInsertMenuItem, XDestroyMenu

Wrapped APIs

CreateMenu, CreatePopupMenu

Module

XFTMenu.f90


XDestroyMenu

XDestroyMenu

XDestroyMenu destroys a menu.

SUBROUTINE XDestroyMenu(xMenu)

TYPE(X_MENU), INTENT(INOUT)::  xMenu

Arguments

xMenu
 X_MENU structure representing the menu to be deleted. hMenu member of the structure is set to zero. The xMenu variable may be latter reused for creation of a new menu, but cannot be used in other menu-related functions.

See Also

XCreateMenu, XLoadMenu

Wrapped APIs

DestroyMenu

Module

XFTMenu.f90


XDeleteMenuItem

XDeleteMenuItem

XDeleteMenuItem deletes an existing menu item.

LOGICAL FUNCTION XDeleteMenuItem(xMenu, ID/iPosArray)

TYPE(X_MENU)::                  xMenu
INTEGER, INTENT(IN)::           ID/iPosArray(:)

Arguments

xMenu
 X_MENU structure representing the menu.

ID/iPosArray
ID is unique numeric identifier of an existing menu item to delete. iPosArray is an array of indices describing an menu item, whose first member is index in top-level menu, second is index in its n-th submenu etc; iPosArray must always be an array, even if it refers to top-level menu - in that case, an array of size 1 is required, e.g. (/1/) refers to first top-level menu item (typically File).

Return Value

If successful (the menu item is deleted), the functions returns .TRUE.; otherwise, it returns .FALSE.

Remarks

After successful deletion, remaining menu items are shifted by 1 position. Thus, to delete several consecutive items in a loop, use the same value of iPosArray.

See Also

XInsertMenuItem

Wrapped APIs

DeleteMenu, DrawMenuBar

Module

XFTMenu.f90


XGetWindowMenu

XGetWindowMenu

XGetWindowMenu retrieves menu bar, if any assigned to given window.

FUNCTION     XGetWindowMenu(xWnd) RESULT(xMenu)

!DEC$IF .NOT.DEFINED(XLITE)
TYPE(X_WINDOW)::        xWnd
!DEC$ELSE
INTEGER, INTENT(IN)::   xWnd
!DEC$ENDIF
TYPE(X_MENU)::
xMenu

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window whose menu is to be retrieved. For QuickWin projects, the handle can be obtained using GETHWNDQQ.

Full Xeffort Version: X_WINDOW structure describing the window.

Return Value

X_MENU structure representing the menu assigned to given window. If the window is invalid, or if it does not have a menu assigned, the returned structure is invalid (hMenu member has value 0)

See Also

XSetWindowMenu

Wrapped APIs

GetMenu

Module

XFTMenu.f90


XInsertMenuItem

XInsertMenuItem

XInsertMenuItem adds a menu item to an existing menu.

LOGICAL FUNCTION XInsertMenuItem(xMenu, xMI, ID/iPosArray)

TYPE(X_MENU)::                  xMenu
TYPE(X_MENUITEM), INTENT(IN)::  xMI
INTEGER, INTENT(IN)::           ID/iPosArray(:)

Arguments

xMenu
 X_MENU structure representing the menu.

xMI
 X_MENUITEM structure containing the properties of newly created item.

ID/iPosArray
ID is unique numeric identifier of an existing menu item. Newly created menu item will be created immediately above/before that item. To append a item to the end of an existing menu, form with iPosArray must be used.

iPosArray is an array of indices describing an menu item, whose first member is index in top-level menu, second is index in its n-th submenu etc; iPosArray must always be an array, even if it refers to top-level menu - in that case, an array of size 1 is required, e.g. (/1/) refers to first top-level menu item (typically File). In context of this function, all items of iPosArray member must exist except the last one. If the last member of iPosArray is either XMENU_APPEND or greater than number of existing items in corresponding submenu, the behavior is as follows:

- If the corresponding submenu exists, the new item is appended to the end of the list

- If the corresponding submenu does not exist, a new submenu is created; the item described by xMI structure is created as the first item in that submenu; its parent item is converted to a MF_POPUP item (as consequence, any command handler that might have been associated with it via XSetCommand becomes disassociated).

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

Example

The following example appends a menu item "Popup" with ID 10000 to existing QuickWin File menu. Then, it adds a submenu to that menu item (which will appear as 4th in File menu), containing five items with strings "Item 1"..."Item 5" and IDs 10001...10005. It associates command handler OnMenuItem with every new item.

xMenu%hMenu = GetMenu(GETHWNDQQ(QWIN$FRAMEWINDOW))
xMI = X_MENUITEM(MF_STRING, MF_ENABLED, 10000, "Popup")
bSt = XInsertMenuItem(xMenu, xMI, (/1,XMENU_APPEND/) )
DO i = 1,5
WRITE(sItem,"(A,I1,A)") "Item", i, CHAR(0)
xMI = X_MENUITEM(MF_STRING, MF_ENABLED, 10000+i, sItem)
bSt = XInsertMenuItem(xMenu,xMI,(/1,4,XMENU_APPEND/) )
CALL XSetCommand(xFrame, 10000+i, OnMenuItem)
END DO

See Also

XMenuSet, X_MENUITEM

Wrapped APIs

InsertMenuItem, GetSubMenu

Module

XFTMenu.f90


XLoadMenu

XLoadMenu

XLoadMenu loads a menu bar as a resource from the current or given application image.

FUNCTION XLoadMenu(ID, hModule, bContext) RESULT(xMenu)

TYPE(X_MENU)::                  xMenu
INTEGER, INTENT(IN)::           ID
INTEGER, OPTIONAL, INTENT(IN):: hModule
LOGICAL, OPTIONAL, INTENT(IN):: bContext

Arguments

ID
Identifier of menu resource stored in the file identified with hModule argument

[hModule]
Identifies the handle of a Dll module (returned by XGetInstance or LoadLibrary API) if the specified resource ID is to be searched within resources of a dll. If absent, the dialog is attempted to be loaded from the .exe file which started the current process.

[bContext]
If present and .TRUE., it specifies that the returned menu is a popup (context) menu, which can be used in subsequent XContextMenu.

Return Value

Return value is a X_MENU structure which can be used in subsequent operations on the menu.

Remarks

If the menu is latter assigned to a window using XSetWindowMenu, destruction is not required; otherwise, XDestroyMenu should be called to release resources associated with the menu.

See Also

XCreateMenu, XSetWindowMenu, XInsertMenuItem, XDestroyMenu

Wrapped APIs

LoadMenu

Module

XFTMenu.f90


XMenuGet

XMenuGet

XMenuGet retrieves a property of a menu item. XMenuGet is generic name for three routines: XMenuGetType, XMenuGetChar and XMenuGetLog. Additionally, every routine comes in two forms, where second argument can be either a scalar integer (representing menu item ID), or an integer array (representing menu item position in a chain of submenus).

LOGICAL FUNCTION XMenuGet(xMenu, ID/iPosArray, Value, iAction)

TYPE(X_MENU)::                  xMenu
INTEGER, INTENT(IN)::           ID/iPosArray(:)
INTEGER/CHARACTER(*)/LOGICAL, INTENT(OUT)::  Value
INTEGER, OPTIONAL, INTENT(IN):: iAction

Arguments

xMenu
 X_MENU structure representing the menu.

ID/iPosArray
ID is unique numeric identifier of the menu item, as set in dialog editor or during menu creation by XInsertMenuItem. iPosArray is an array of indices whose first member is index in top-level menu, second is index in its n-th submenu etc; iPosArray must always be an array, even if it refers to top-level menu - in that case, an array of size 1 is required, e.g. (/1/) refers to first top-level menu item (typically File).

Value
An integer, string, or logical scalar representing the value of menu item's property to be retrieved. See table below for description of available properties and their meanings.

[iAction]
An integer constant describing which property of the menu item be retrieved. The following combinations of iAction and type of Value are allowed:

Value | iAction | Meaning
Integer | <not used> | Returns the type of the menu item.
Character | XMENU_TITLE (default) | String of the menu item. Ampersand (&) denotes that the character following it presents a mnemonic key (i.e. it is underlined and the menu item can be activated using Alt+key)
Logical | XMENU_STATE (default) | Returns .TRUE. if the menu item is checked (has a check-mark next to its text)
Logical | XMENU_ENABLE | Returns .TRUE. if the menu item is enabled, and .FALSE. otherwise.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XMenuSet

Wrapped APIs

GetMenuItemInfo, GetSubMenu

Module

XFTMenu.f90


XMenuSet

XMenuSet

XMenuSet sets a property of a menu item. XMenuSet is generic name for three routines: XMenuSetType, XMenuSetChar, XMenuSetLog. Additionally, every routine comes in two forms, where second argument can be either a scalar integer (representing menu item ID), or an integer array (representing menu item position in a chain of submenus).

LOGICAL FUNCTION XMenuSet(xMenu, ID/iPosArray, Value, iAction)

TYPE(X_MENU)::                  xMenu
INTEGER, INTENT(IN)::          ID/iPosArray(:)
INTEGER/CHARACTER(*)/LOGICAL, INTENT(IN)::  Value
INTEGER, OPTIONAL, INTENT(IN):: iAction

Arguments

xMenu
 X_MENU structure representing the menu.

ID/iPosArray
ID is unique numeric identifier of the menu item, as set in dialog editor or during menu creation by XInsertMenuItem. iPosArray is an array of indices whose first member is index in top-level menu, second is index in its n-th submenu etc; iPosArray must always be an array, even if it refers to top-level menu - in that case, an array of size 1 is required, e.g. (/1/) refers to first top-level menu item (typically File).

Value
An integer, string, or logical scalar representing the value of menu item's property to be set. See table below for description of available properties and their meanings.

[iAction]
An integer constant describing which property of the menu item be retrieved. If absent, the value indicated with (default) in table below is assumed. The following combinations of iAction and type of Value are allowed:

Value | iAction | Meaning
Integer | XMENU_TYPE (default) | Set the type of the menu item. See menu item types for allowed combinations of types.
Character | XMENU_TITLE (default) | String of the menu item. Ampersand (&) denotes that the character following it presents a mnemonic key (i.e. it is underlined and the menu item can be activated using Alt+key)
Logical | XMENU_STATE (default) | If .TRUE. the menu item is being checked (having a check-mark symbol next to its text); if .FALSE., the menu item is being unchecked.
Logical | XMENU_ENABLE | If .TRUE. if the menu item is enabled, and if .FALSE. it is disabled.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XMenuGet

Wrapped APIs

GetMenuItemInfo, GetSubMenu

Module

XFTMenu.f90


XMenuSetBmp

XMenuSetBmp

XMenuSetBmp sets the bitmaps associated with a menu item. A menu item can have two bitmaps associated: one when it's checked, and one when it's not.

LOGICAL FUNCTION XMenuSetBmp(xMenu, ID/iPosArray, xBmpChecked, xBmpUnchecked)

TYPE(X_MENU)::                          xMenu
INTEGER, INTENT(IN)::                   ID/iPosArray(:)
TYPE(X_BITMAP), OPTIONAL, INTENT(IN)::  xBmpChecked
TYPE(X_BITMAP), OPTIONAL, INTENT(IN)::  xBmpUnChecked

Arguments

xMenu
 X_MENU structure representing the menu.

ID/iPosArray
ID is unique numeric identifier of the menu item, as set in dialog editor or during menu creation by XInsertMenuItem. iPosArray is an array of indices whose first member is index in top-level menu, second is index in its n-th submenu etc; iPosArray must always be an array, even if it refers to top-level menu - in that case, an array of size 1 is required, e.g. (/1/) refers to first top-level menu item (typically File).

[xBmpChecked]
A X_BITMAP structure representing the bitmap displayed when the menu item is checked. If absent, the previously associated bitmap, if any, is unchanged.

[xBmpUnChecked]
A X_BITMAP structure representing the bitmap displayed when the menu item is not checked. If absent, the previously associated bitmap, if any, is unchanged.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

Remarks

When the menu is destroyed, these bitmaps are not destroyed; it is up to the application to destroy them.

Default size for bitmaps at normal fonts under standard color scheme is 12x12. The system uses the Boolean AND operator to combine bitmaps with the menu background, so that the white part becomes transparent and the black part becomes the menu-item color. Best results with color bitmaps are obtained if white color is abandoned.

See Also

XMenuSet, XCreateBitmap, XDeleteBitmap

Wrapped APIs

SetMenuItemBitmaps, GetSubMenu

Module

XFTMenu.f90


XSetWindowMenu

XSetWindowMenu

XSetWindowMenu assigns a menu bar of type X_MENU to given window.

LOGICAL FUNCTION XSetWindowMenu(xWnd, xMenu)

!DEC$IF .NOT.DEFINED(XLITE)
TYPE(X_WINDOW)::        xWnd
!DEC$ELSE
INTEGER, INTENT(IN)::   xWnd
!DEC$ENDIF
TYPE(X_MENU)::          xMenu

Arguments

xWnd
LITE Xeffort Version: (INTEGER) Handle of the window whose menu is to be assigned. For QuickWin projects, the handle can be obtained using GETHWNDQQ.

Full Xeffort Version: X_WINDOW structure describing the window.

xMenu
 X_MENU structure representing the menu to be assigned to given window.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

See Also

XLoadMenu, XGetWindowMenu

Wrapped APIs

SetMenu

Module

XFTMenu.f90


XFTPrint Overview

XFTPrint Overview

XFTPrint module is used for managing printers and their settings. When an application wants to produce output on a printer or other printing device, it ultimately needs to obtain a printer device context and use XFTGDI routines to draw the output on it.

Printers

A computer can have zero or more printers (more precisely, printer drivers) installed. One of these printers is the default printer, meaning that it is the preferred one by the user. Every installed printer has its default settings (such as preferred paper size, print quality etc.), as set up in "Printers" folder of the Control Panel. These settings can be overriden by the user, or programmatically by the application. Type X_PRINTERSETTINGS models these settings, and they can also be changed programmatically using XPrinterSet/XPrinterGet routines.

Obtaining a printer DC

The most common interface for managing printer settings and obtaining printer's device context is the "Print" common dialog, which can be invoked using XPrintDlg routine. The Print dialog allows the user to modify the default printer settings and set up number of copies, requested pages to be printed etc. When user selects "OK" on the print dialog, it returns a valid X_DC structure where the application can draw its output.

Alternatively, an application can create a printer X_DC by other means. It can use one or more of the following steps:

  • Obtain the list of installed printer names using XEnumPrinters

  • Retrieve the default printer settings for given printer name in form of X_PRINTERSETTINGS structure using XGetPrinterSettings routine, or allowing the user to change the printer settings using XPrinterSettingsDlg dialog.

  • Modify one or more of printer settings using XPrinterSet/XPrinterGet routines.

  • Create a printer DC from X_PRINTERSETTINGS using XCreateDC routine.

An application should take care to release the memory for each X_PRINTERSETTINGS routine it initializes using XFreePrinterSettings.

A user-friendly GUI application which presents a common "Print" dialog to the user should take care about posible modification of printer settings by the user. For example, if user selects a non-default printer and sets up landscape paper orientation and high-resolution printing, (s)he would expect that these settings remain preserved when (s)he invokes the print dialog for another time. To obtain such behavior, an application should save a X_PRINTERSETTINGS structure (at least for one printer) and reuse it between invocations of XPrintDialog; XFreePrinterSettings for the saved settings should be called on the termination of the application. See sample below for an illustration.

Drawing on the printer DC

Once the printer DC (X_DC structure) is obtained, the application should proceed:

  • Create a new document in selected printer's queue using XStartDoc

  • For each page it is about to print, call XStartPage routine.

  • Draw its graphic output for appropriate page using XFTGDI routines.

  • End the page(s) using XEndPage routine for each page.

  • End the printing by calling XEndDoc routine, which places the document in the printer's queue and ultimatively prints it.

Special care should be taken that printers vary by their printing capabilities, especially available resolution(s), paper size, and color. Thus, the application should set up a scalable (logical) coordinate system using XSetWindow and draw on the printer DC using XFTGDI routines with _W suffix. XSetScaling routine can also be used to set up the logical coordinate system in terms of millimeters, inches, points, or other convenient measuring units.

Sample

The following code is taken from XTabEditor Xeffort sample. It uses a global X_PRINTERSETTINGS structure and reuses it between invocations of XPrintDlg. When user clicks "OK" on the print dialog, it creates a printer document of the same name as the text file being printed. Then, it sets up the scaling using XSetScaling in form of points, which are convenient for text output. After calling XStartDoc/XStartPage, it outputs the text using XWrite routine, and starts a new page each time the current page is filled in:

module XTabEditor
...
type(X_PRINTERSETTINGS), save:: xPS
!============================================================

subroutine XW_FRAME_OnFilePrint(xWnd, idCmd, nCode)

type(X_WINDOW)::      xWnd

integer, intent(IN):: idCmd, nCode

type(X_DC)::          xDC

integer::             iSt, iVal, i, nLines

character(128)::      sLine

if (XPrintDlg(xWnd=XW_FRAME, xDC=xDC, xPS=xPS)) then

    iSt = XStartDoc(xDC, UD%sFileName)

    iSt = XStartPage(xDC)
    !Count of lines to be printed

    nLines = GetLineCount()

    call XSetScaling(xDC, 0., 0., MM_POINTS)

    !Set up 9-point Courier New font

    call XSetFont_W(xDC, "Courier New", 9.)

    do i = 1, nLines
        !Obtain new line of text

        call GetLine(sLine, i)
        !Print the lines one by one; if the page overflows
        !start a new one

        if (.NOT.XWrite(xDC, sLine)) then

            iSt = XEndPage(xDC)
            iSt = XStartPage(xDC)

call XMoveTo(xDC, 0,0)

            iSt = XWrite(xDC, trim(sLine))

        end if

    end do

    iSt = XEndDoc(xDC)

end if

end subroutine XW_FRAME_OnFilePrint
!=========================================================

logical function XW_FRAME_OnClose(xWnd)
...

call XFreePrinterSettings(xPS)

Reference


XFTPrint Reference

XFTPrint Reference

Overview

Management of printers

XEnumPrinters

Printer settings

X_PRINTERSETTINGS

XGetPrinterSettings

XFreePrinterSettings

XPrintDlg

XPrinterGet

XPrinterSet

XPrinterSettingsDlg

Printing process

XCreateDC

XEndDoc

XEndPage

XStartDoc

XStartPage


X_PRINTERSETTINGS

X_PRINTERSETTINGS

X_PRINTERSETTINGS type models the various settings of a particular printer, such as resolution, paper orientation, color etc. X_PRINTERSETTINGS is an opaque type, i.e. you should not modify its contents directly, but use other XFTPrint functions such as XPrinterGet and XPrinterSet to modify it.

TYPE X_PRINTERSETTINGS
    INTEGER:: hmemDevMode = 0
END TYPE X_PRINTERSETTINGS

Members

hmemDevMode
Handle to a GMEM_MOVEABLE memory area containing a DEVMODE structure, describing common properties of all printer models, immediately followed by an array of printer driver-specific data. See DEVMODE entry in Win32 SDK help for details. If the memory is not initialized, hmemDevMode must have value zero.

Remarks

hmemDevMode is a handle to allocated memory, i.e. it is in effect a pointer. An application should take care to release the memory using XFreePrinterSettings. Functions XPrintDlg, XPrinterSettingsDlg and XGetPrinterSettings can allocate the memory.

See Also

XPrinterGet, XPrinterSet, XFreePrinterSettings, XGetPrinterSettings, XPrintDlg, XCreateDC, XPrinterSettingsDlg

Wrapped APIs

DEVMODE

Module

XFTPrint.f90


XCreateDC

XCreateDC

XCreateDC creates a printer device context on the basis of settings of a printer.

FUNCTION XCreateDC(xPS) RESULT(xDC)

TYPE(X_PRINTERSETTINGS), OPTIONAL, INTENT(IN):: xPS
TYPE(X_DC):: xDC

Arguments

[xPS]
Type X_PRINTERSETTINGS representing settings of a particular printer. If absent, the function returns the DC based on default settings of the default system printer.

Return Value

Type X_DC representing printer's device context. If the function fails, the returned DC is invalid, i.e. its hDC member has value zero.

Remarks

When done with the DC, remove it with XDeleteDC .

See Also

X_PRINTERSETTINGS, XStartDoc, XEndPage, XDeleteDC

Wrapped APIs

CreateDC

Module

XFTPrint.f90


XEndDoc

XEndDoc

XEndDoc function ends a print job previously started using XStartDoc.

LOGICAL FUNCTION XEndDoc(xDC)

TYPE(X_DC), INTENT(IN)::     xDC

Arguments

xDC
Type X_DC representing printer's device context. The DC must be previously created using XPrintDlg or XCreateDC routines, and prepared for printing using XStartDoc.

Return Value

If the function succeeds, the return value is .TRUE.

See Also

XStartDoc

Wrapped APIs

EndDoc

Module

XFTPrint.f90


XEndPage

XEndPage

XEndPage function informs the printer driver that the application has completed drawing on a page, previously started using XStartPage. This function is typically used to direct the device driver to advance to a new page.

LOGICAL FUNCTION XEndPage(xDC)

TYPE(X_DC), INTENT(IN)::     xDC

Arguments

xDC
Type X_DC representing printer's device context. The DC must be previously created using XPrintDlg or XCreateDC routines, and prepared for printing using XStartDoc and XStartPage.

Return Value

If the function succeeds, the return value is .TRUE.

See Also

XStartPage

Wrapped APIs

EndPage

Module

XFTPrint.f90


XEnumPrinters

XEnumPrinters

XEnumPrinters function returns the list of installed printers on the system.

LOGICAL FUNCTION XEnumPrinters(psPrinterName)

CHARACTER(*), POINTER::         psPrinterName(:)

Arguments

psPrinterName
Character pointer array which contains names of installed printers on the system on output. Must be NULLIFYed on input, otherwise the function fails. String length should be at least 32 characters. The size of returned array is equal to the number of printers installed; however, printer names whose length exceeds LEN(psPrinterName) will not be returned, i.e. the returned string will be blank.

Return value

If the function succeeds, the return value is .TRUE.

Wrapped APIs

EnumPrinters

Module

XFTPrint.f90


XFreePrinterSettings

XFreePrinterSettings

XFreePrinterSettings releases the memory referenced in type X_PRINTERSETTINGS previously allocated by a call to XPrintDlg, XPrinterSettingsDlg or XGetPrinterSettings.

SUBROUTINE XFreePrinterSettings(xPS)

TYPE(X_PRINTERSETTINGS), INTENT(INOUT):: xPS

Arguments

xPS
Type X_PRINTERSETTINGS representing settings of a printer.

See Also

X_PRINTERSETTINGS, XPrintDlg, XPrinterSettingsDlg, XGetPrinterSettings.

Wrapped APIs

GlobalFree

Module

XFTPrint.f90


XGetPrinterSettings

XGetPrinterSettings

XGetPrinterSettings routine retrieves the default settings of the printer identified by its name.

LOGICAL FUNCTION XGetPrinterSettings(sPrinterName, xPS)

CHARACTER(*), INTENT(IN)::                 sPrinterName
TYPE(X_PRINTERSETTINGS), INTENT(INOUT)::   xPS

Arguments

sPrinterName
Name of the printing device whose settings are queried. If blank, the routine returns the settings of the default printer.

xPS
Type X_PRINTERSETTINGS representing the settings of the selected printer. This argument is in effect INTENT(OUT); however, if the type is already initialized, the function will free the associated memory and allocate a new one. The memory must be eventually released using XFreePrinterSettings routine.

See Also

X_PRINTERSETTINGS, XPrinterSettingsDlg, XFreePrinterSettings, XPrinterSet/XPrinterGet, XCreateDC

Return Value

If the function succeeds, the return value is .TRUE.

Wrapped APIs

DocumentProperties

Module

XFTPrint.f90


XPrintDlg

XPrintDlg

XPrintDlg function displays a Print dialog box. The Print dialog box enables the user to specify the properties of a particular print job.

LOGICAL
FUNCTION  XPrintDlg(iFlags, xWnd, xDC, xPS, &
nFromPage, nToPage, nMinPage, nMaxPage, nCopies) RESULT(bOK)

INTEGER, OPTIONAL, INTENT(INOUT)::     iFlags
TYPE(X_WINDOW), OPTIONAL, INTENT(IN)::          xWnd
TYPE(X_DC), OPTIONAL, INTENT(OUT)::    xDC
TYPE(X_PRINTERSETTINGS), OPTIONAL, INTENT(INOUT):: xPS
INTEGER, OPTIONAL, INTENT(INOUT)::     nFromPage
INTEGER, OPTIONAL, INTENT(INOUT)::     nToPage
INTEGER, OPTIONAL, INTENT(IN)::
nMinPage
INTEGER, OPTIONAL, INTENT(IN)::
nMaxPage
INTEGER, OPTIONAL, INTENT(INOUT)::     nCopies

Arguments

[iFlags]
A set of bit flags used to initialize controls on the Print dialog box and to retrieve some of settings. It can be a combination of the following flags (the flags printed bold are both input and output; the other ones are used just on input, i.e. only for initialization of the controls):

PD_ALLPAGES | The default flag that indicates that the All radio button is initially selected. This flag has value zero, i.e. it is used as a placeholder to indicate that the PD_PAGENUMS and PD_SELECTION flags are not specified.
PD_COLLATE | If this flag is set, the Collate check box is checked. If this flag is set when the function returns, the application must simulate collation of multiple copies.
PD_DISABLEPRINTTOFILE | Disables the Print to File check box.
PD_HIDEPRINTTOFILE | Hides the Print to File check box.
PD_NONETWORKBUTTON | Hides and disables the Network button.
PD_NOPAGENUMS | Disables the Pages radio button and the associated edit controls.
PD_NOSELECTION | Disables the Selection radio button.
PD_NOWARNING | Prevents the warning message from being displayed when there is no default printer.
PD_PAGENUMS | If this flag is set, the Pages radio button is selected. If this flag is set when the function returns, the nFromPage and nToPage arguments indicate the starting and ending pages specified by the user.
PD_PRINTSETUP | Causes the system to display the Print Setup dialog box rather than the Print dialog box.
PD_PRINTTOFILE | If this flag is set, the Print to File check box is selected.
PD_SELECTION | If this flag is set, the Selection radio button is selected. If neither PD_PAGENUMS nor PD_SELECTION is set, the All radio button is selected.
PD_SHOWHELP | Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.

If absent, the default combination is PD_ALLPAGES .OR. PD_NOSELECTION .OR. PD_NOPAGENUMS.

[xWnd]
Type X_WINDOW representing the window which will serve as the owner of the dialog box. If absent, the application's frame window (XW_FRAME) is used.

[xDC]
Type X_DC representing the obtained printer's device context. The returned variable can be later used in functions XStartDoc and XStartPage to initialize the printing, and in XFTGDI routines for the purpose of creating graphical output.

[xPS]
Type X_PRINTERSETTINGS representing the initial settings of the selected printer. Settings of the printer can be modified by the user in the Print dialog, or programmatically using XPrinterGet/XPrinterSet. The memory must be eventually released using XFreePrinterSettings routine. An application should store this value and reuse it in later invocations of XPrintDlg; see considerations in overview. If absent, no memory is allocated, and all printer settings are initialized to their default values as set up in Printer Properties dialog in system Printers folder (but the user can modify them for the particular print job using "Properties..." button on the dialog).

[nFromPage], [nToPage]
Starting and ending page to be printed. On input, these values are used to initialize values in From and To edit boxes. On output, these values indicate user's selection, but only if PD_PAGENUMS flag is present in iFlags argument. If absent, both values default to 1.

[nMinPage], [nMaxPage]
Minimal and maximal allowed values of nFromPage and nToPage arguments respectively. If absent, both values default to 1.

[nCopies]
On input, contains the initial number of copies of the document. On output, contains the selected number of copies by the user. The default value is 1. For most printer drivers, an application need not take special attention to the number of copies, because appropriate number of copies will be generated automatically.

See Also

XPrinterSet, XPrinterGet, XFTGDI: Device contexts (DCs), XFreePrinterSettings

Wrapped APIs

PrintDlg

Module

XFTPrint.f90


XPrinterSet

XPrinterGet/XPrinterSet

XPrinterGet retrieves, and XPrinterSet sets a property of a particular printer for a particular print job.

LOGICAL FUNCTION XPrinterGet/XPrinterSet(xPS, iValue, iIndex)

TYPE(X_PRINTERSETTINGS), INTENT(IN):: xPS
INTEGER, INTENT(OUT/IN)::             iValue
INTEGER, INTENT(IN)::                 iIndex

Arguments

xPS
Type X_PRINTERSETTINGS representing settings of a particular printer.

iValue
Integer value representing a printer property described by the value of iIndex argument.

iIndex
Integer value describing a printer property. Can be one of the following values (values indicated bold can be both set and retrieved; other ones can be only retrieved):

Index Meaning

DM_SIZE

Returns the size of DEVMODE structure, in bytes

DM_DRIVEREXTRA

Returns the size (in bytes) of printer-specific data that follow the DEVMODE structure immediately in memory

DM_ORIENTATION

Selects the orientation of the paper. This member can be either DMORIENT_PORTRAIT (1) or DMORIENT_LANDSCAPE (2).

DM_PAPERSIZE

The size of the paper to print on. This member can be set to zero if the length and width of the paper are set using DM_PAPERLENGTH and DM_PAPERWIDTH indices. Otherwise, it can be set to one of the DMPAPER_ predefined values. For full list, see DEVMODE entry in Win32 SDK help:

DMPAPER_LETTER | Letter, 8 1/2- by 11-inches
DMPAPER_LEGAL | Legal, 8 1/2- by 14-inches
DMPAPER_A4 | A4 Sheet, 210- by 297-millimeters

DM_PAPERLENGTH

Paper length (height). If specified, it overrides the paper dimensions set by DM_PAPERSIZE.

DM_PAPERWIDTH

Paper width. If specified, it overrides the paper dimensions set by DM_PAPERSIZE.

DM_SCALE

 Specifies the factor by which the printed output is to be scaled. The apparent page size is scaled from the physical page size by a factor of dmScale/100. For example, an A4-sized page with a dmScale value of 50 would contain as much data as an A3 page, because the output text and graphics would be half their original height and width.

DM_COPIES

Selects the number of copies printed if the device supports multiple-page copies

DM_DEFAULTSOURCE

 Specifies the paper source. To retrieve a list of the available paper sources for a printer, use the DeviceCapabilities API function with the DC_BINS flag.

This member can be one of the following values, or it can be a device-specific value greater than DMBIN_USER.

DMBIN_ONLYONE
DMBIN_LOWER
DMBIN_MIDDLE
DMBIN_MANUAL
DMBIN_ENVELOPE
DMBIN_ENVMANUAL
DMBIN_AUTO
DMBIN_TRACTOR
DMBIN_SMALLFMT
DMBIN_LARGEFMT
DMBIN_LARGECAPACITY
DMBIN_CASSETTE
DMBIN_FORMSOURCE

DM_PRINTQUALITY

 Specifies the printer resolution. There are four predefined device-independent values:

DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT

If a positive value is given, it specifies the number of dots per inch (DPI) and is therefore device dependent.

DM_COLOR

 Switches between color and monochrome on color printers. Following are the possible values:

DMCOLOR_COLOR
DMCOLOR_MONOCHROME

DM_DUPLEX

 Selects duplex or double-sided printing for printers capable of duplex printing. Following are the possible values:

DMDUP_SIMPLEX
DMDUP_HORIZONTAL
DMDUP_VERTICAL

DM_YRESOLUTION

Specifies the y-resolution, in dots per inch, of the printer. If the printer initializes this member, the DM_PrintQuality value specifies the x-resolution, in dots per inch, of the printer.

DM_TTOPTION

 Specifies how TrueType® fonts should be printed. This member can be one of the following values:
Value | Meaning
DMTT_BITMAP | Prints TrueType fonts as graphics. This is the default action for dot-matrix printers.
DMTT_DOWNLOAD | Downloads TrueType fonts as soft fonts. This is the default action for Hewlett-Packard printers that use Printer Control Language (PCL).
DMTT_SUBDEV | Substitute device fonts for TrueType fonts. This is the default action for PostScript® printers.

DM_COLLATE

 Specifies whether collation should be used when printing multiple copies. This member can be be one of the following values:
Value | Meaning
DMCOLLATE_TRUE | Collate when printing multiple copies.
DMCOLLATE_FALSE | Do not collate when printing multiple copies.

Using DMCOLLATE_TRUE provides faster, more efficient output for collation, since the data is sent to the device driver just once, no matter how many copies are required. The printer is told to simply print the page again.

DM_ICMMETHOD

 Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is enabled or disabled. For ICM applications, the system examines this member to determine how to handle ICM support. This member can be one of the following predefined values, or a driver-defined value greater than the value of DMICMMETHOD_USER:
Value | Meaning
DMICMMETHOD_NONE | Specifies that ICM is disabled.
DMICMMETHOD_SYSTEM | Specifies that ICM is handled by Windows.
DMICMMETHOD_DRIVER | Specifies that ICM is handled by the device driver.
DMICMMETHOD_DEVICE | Specifies that ICM is handled by the destination device.

The printer driver must provide a user interface for setting this value. Most printer drivers support only the DMICMMETHOD_SYSTEM or DMICMMETHOD_NONE value. Drivers for PostScript printers support all values.

DM_ICMINTENT

 Specifies which of the three possible color matching methods, or intents, should be used by default. This member is primarily for non-ICM applications. ICM applications can establish intents by using the ICM functions. This value can be one of the following predefined values, or a driver defined value greater than the value of DMICM_USER:
Value | Meaning
DMICM_SATURATE | Color matching should optimize for color saturation. This value is the most appropriate choice for business graphs when dithering is not desired.
DMICM_CONTRAST | Color matching should optimize for color contrast. This value is the most appropriate choice for scanned or photographic images when dithering is desired.
DMICM_COLORMETRIC | Color matching should optimize to match the exact color requested. This value is most appropriate for use with business logos or other images when an exact color match is desired.

DM_MEDIATYPE

 Specifies the type of media being printed on. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMMEDIA_USER:
Value | Meaning
DMMEDIA_STANDARD | Plain paper.
DMMEDIA_GLOSSY | Glossy paper.
DMMEDIA_TRANSPARENCY | Transparent film.

DM_DITHERTYPE

 Specifies how dithering is to be done. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMDITHER_USER:
Value | Meaning
DMDITHER_NONE | No dithering.
DMDITHER_COARSE | Dithering with a coarse brush.
DMDITHER_FINE | Dithering with a fine brush.
DMDITHER_LINEART | Line art dithering, a special dithering method that produces well defined borders between black, white, and gray scalings. It is not suitable for images that include continuous graduations in intensisty and hue such as scanned photographs.
DMDITHER_GRAYSCALE | Device does grayscaling

Return Value

If the function succeeds, the return value is .TRUE.

Remarks

Adjustments made using XPrinterSet are not applied immediately to the printer; the routine merely modifies contents of memory referenced by xPS argument. The changes will be reflected when a printer device context is created on the basis of xPS using XCreateDC or XPrintDlg routines.

See Also

XGetPrinterSettings, XCreateDC, XPrintDlg, X_PRINTERSETTINGS

Wrapped APIs

DEVMODE

Module

XFTPrint.f90


XPrinterSettingsDlg

XPrinterSettingsDlg

XPrinterSettingsDlg displays the printer-specific "Settings" or "Properties" dialog, where user can adjust printer settings such as print quality, paper orientation, paper size etc. The changes made can be only for the current job session or system-wide.

INTEGER FUNCTION
 XPrinterSettingsDlg(sPrinterName, xWnd, xPS, bGlobal)

CHARACTER(*), INTENT(IN)::
sPrinterName
TYPE(X_PRINTERSETTINGS), INTENT(INOUT)::           xPS
TYPE(X_WINDOW), OPTIONAL, INTENT(IN)::   xWnd
LOGICAL, OPTIONAL, INTENT(IN)::
bGlobal

Arguments

sPrinterName
Name of the printer to be configured. This name can be obtained using XEnumPrinters function.

xPS
Type X_PRINTERSETTINGS representing the settings of the selected printer. If initialized on input (non-zero hmemDevMode), then it must match the printer identified by sPrinterName (i.e. came out as a result of a previous call to XPrintDlg, XGetPrinterSettings or XPrinterSettingsDlg). The memory must be eventually released using routine.

[xWnd]
Type X_WINDOW representing the window which will serve as the owner of the dialog box. If absent, the application's frame window (XW_FRAME) is used.

[bGlobal]
If present and .TRUE., the changes made are system-wide, i.e. they modify the default printing preferences of the printer.

Return Value

If the function succeeds, the return value is IDOK (1) or IDCANCEL(2), depending on which button was used to close the dialog. If the function fails, the return value is negative.

See Also

X_PRINTERSETTINGS, XPrintDlg, XGetPrinterSettings, XFreePrinterSettings

Wrapped APIs

DocumentProperties, AdvancedDocumentProperties

Module

XFTPrint.f90


XStartDoc

XStartDoc

The XStartDoc function starts a print job. The print job must be started first in order to produce any output on the printer using XFTGDI routines. The started print job must be terminated using XEndDoc.

LOGICAL FUNCTION XStartDoc(xDC, sDocName, sFileName)

TYPE(X_DC), INTENT(IN)::             xDC
CHARACTER(*), INTENT(IN)::           sDocName
CHARACTER(*), OPTIONAL, INTENT(IN):: sFileName

Arguments

xDC
Type X_DC representing printer's device context. The DC must be previously created using XPrintDlg or XCreateDC routines.

sDocName
An application-defined string describing the document name. That name will appear in printer's queue list (accessible from the printer's icon in the system tray until the printing is complete).

[sFileName]
If present, the print job will be redirected to the file with given name sFileName. This argument must be a valid file name.

Return Value

If the function succeeds, the return value is .TRUE.

See Also

XPrintDlg, XCreateDC, XEndDoc, XStartPage

Wrapped APIs

StartDoc

Module

XFTPrint.f90


XStartPage

XStartPage

XStartPage prepares the printer driver to accept data. Only after this function is called, output on the printer can be produced using XFTGDI routines. The printer page must be terminated using XEndPage routine. One print job initiated using XStartDoc can contain several calls to XStartPage/XEndPage.

LOGICAL FUNCTION XStartPage(xDC)

TYPE(X_DC), INTENT(IN)::     xDC

Arguments

xDC
Type X_DC representing printer's device context. The DC must be previously created using XPrintDlg or XCreateDC routines, and prepared for printing using XStartDoc.

Return Value

If the function succeeds, the return value is .TRUE.

See Also

XEndPage, XStartDoc

Wrapped APIs

StartPage

Module

XFTPrint.f90


XFTReg Overview

XFTReg Overview

The registry is a system-defined database that applications and system components use to store and retrieve configuration data. The registry stores data in a hierarchically structured tree. Each node in the tree is called a key. Each key can contain both subkeys and data entries called values. Sometimes, the presence of a key is all the data that an application requires; other times, an application opens a key and uses the values associated with the key. A key can have any number of values, and the values can be in any form.

Each key has a name consisting of one or more printable ANSI characters. Key names cannot include a space, a backslash (\), or a wildcard character (* or ?). Key names beginning with a period (.) are reserved. The name of each subkey is unique with respect to the key that is immediately above it in the hierarchy.

XFTReg module is used for reading and writing from/to registry. It contains simple wrappers for basic registry operations, such as creation, deletion, reading and writing of keys and values.

Reference


XFTReg Reference

XFTReg Reference

Overview

Creation and Destruction

XRegClose

XRegDeleteKey

XRegDeleteValue

XRegOpen

Reading and Writing

XRegRead

XRegWrite


XRegOpen

XRegOpen

XRegOpen opens (and/or creates) a registry key.

INTEGER FUNCTION
 XRegOpen(hkRoot, sKey, iAccess, iStatus, ioStat)

INTEGER, INTENT(IN)::
hkRoot
CHARACTER(*), INTENT(IN)::       sKey
INTEGER, OPTIONAL, INTENT(IN)::  iAccess
INTEGER, OPTIONAL, INTENT(IN)::  iStatus
INTEGER, OPTIONAL, INTENT(OUT)::       ioStat

Arguments

hkRoot
Handle of parent key for the specified key. Can be a handle previously opened by XRegOpen, or one of the following predefined system root keys:

Value | Purpose
HKEY_CLASSES_ROOT | Stores file associations, registered COM components and other similar data on interaction between aplications and the system.
HKEY_CURRENT_CONFIG |
HKEY_CURRENT_USER | Stores the settings affecting only the current user.
HKEY_LOCAL_MACHINE | Stores computer- or application-specific settings without reference to the current users
HKEY_USERS | Stores settings for all users of the computer. HKEY_CURRENT_USER is alias (synonym) for currently logged on user.
HKEY_PERFORMANCE_DATA (WinNT-XP) HKEY_DYN_DATA (Win9x-ME) |

sKey
Path or name of the key to open relative to specified hkRoot. Keys nested in several levels of hierarchy can be opened at once; in that case, parent subkeys must be separated by backslashes (\). For example, "Software\MyCompany\MyApp\1.0"

[iAccess]
Requested access mask to the specified key, specifying permitted subsequent action for the key. This argument can be a combination of following values:

Value | Meaning
KEY_ALL_ACCESS (default) | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK | Permission to create a symbolic link.
KEY_CREATE_SUB_KEY | Permission to create subkeys.
KEY_ENUMERATE_SUB_KEYS | Permission to enumerate subkeys.
KEY_EXECUTE | Permission for read access.
KEY_NOTIFY | Permission for change notification.
KEY_QUERY_VALUE | Permission to query subkey data.
KEY_READ | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE | Permission to set subkey data.
KEY_WRITE | Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.

[iStatus]
Specifies the status of the key when it is opened. Can be one of the following values:

Value | Meaning
XREG_UNKNOWN (default) | If the key exists, it is opened; if not, it is created
XREG_OLD | If the key exists, it is opened; if not, an error value is returned
XREG_NEW | If the key does not exist, it is created; if it exists, an error value is returned

[ioStat]
Integer variable which will receive a Win32 error code describing the nature of the error if the function fails. If the function succeeds, this argument will be set to zero if present.

Return Value

If successful, the functions returns a handle to newly opened registry key, which can be used in subsequent operations such as reading, writing, or deleting. Otherwise, return value is zero.

Remarks

Recommended convention for storing per-application user-specific settings is HKEY_CURRENT_USER\ Software\ CompanyName\ AppName\ Version. Normally, this key has full access permissions for the current user.

Recommended convention for storing application-global settings is HKEY_LOCAL_MACHINE\ Software\ CompanyName\ AppName\ Version. Note that access to HKEY_LOCAL_MACHINE is frequently restricted to non-administrators; specify minimal access rights in iAccess argument (such as KEY_READ, KEY_WRITE) to access these keys and test the return value.

Every open key must be closed using XRegClose.

See Also

XRegClose, XRegRead, XRegWrite, XRegDeleteKey, XRegDeleteValue

Wrapped APIs

RegOpenKeyEx, RegCreateKeyEx

Module

XFTReg.f90


XRegRead

XRegRead

XRegRead reads data from specified value in a registry key previously opened by XRegOpen. XRegRead is generic name for the following five specific procedures;

INTEGER FUNCTION PXRegReadChar(hKey, sValue, sData)
INTEGER FUNCTION PXRegReadInt(hKey,  sValue, iData)
 INTEGER FUNCTION PXRegReadLog(hKey,  sValue, bData)
 INTEGER FUNCTION PXRegReadReal(hKey, sValue, fData)
INTEGER FUNCTION PXRegReadType(hKey, sValue, lpData, iSize)

INTEGER, INTENT(IN)::      hKey
CHARACTER(*), INTENT(IN):: sValue
CHARACTER(*)/INTEGER/LOGICAL/REAL/INTEGER(INT_PTR_KIND()), INTENT(OUT)::
                           Data
INTEGER, INTENT(IN)::      iSize

Arguments

hKey
Handle of the key previously opened by XRegOpen, containing the value whose data are queried.

sValue
Name of the value to query.

*Data
Data associated with given sValue to be retrieved. Can be a string, integer, logical, or real scalar. For other datatypes, such as derived TYPEs or arrays, the variable must be passed using LOC() function and iSize argument must be provided. Datatype must match the one stored in the registry, i.e. the one used in the past by means of XRegWrite.

iSize
Required only when a derived TYPE or an array is retrieved. Must contain the size in bytes of the buffer pointed to by lpData argument, for example:

INTEGER::
myArray(17), hKey, iStatus
hKey = XRegOpen(HKEY_CURRENT_USER,
"Software\MyCompany\MyApp\1.0")
iStatus = XRegRead(hKey, "My Array", LOC(myArray), SIZEOF(myArray))

Return Value

If successful, the functions returns zero. Otherwise, return value is a Win32 error code.

See Also

XRegOpen, XRegWrite

Wrapped APIs

RegQueryValueEx

Module

XFTReg.f90


XRegWrite

XRegWrite

XRegWrite writes data into specified value in a registry key previously opened by XRegOpen. XRegWrite is generic name for the following five specific procedures;

 INTEGER FUNCTION
PXRegWriteChar(hKey, sValue, sData)
INTEGER FUNCTION PXRegWriteInt(hKey,  sValue, iData)
INTEGER FUNCTION PXRegWriteLog(hKey,  sValue, bData)
INTEGER FUNCTION PXRegWriteReal(hKey, sValue, fData)
INTEGER FUNCTION PXRegWriteType(hKey, sValue, lpData, iSize)

INTEGER, INTENT(IN)::                       hKey
CHARACTER(*), INTENT(IN)::             sValue
CHARACTER(*)/INTEGER/LOGICAL/REAL/INTEGER(INT_PTR_KIND()), INTENT(OUT)::
Data
INTEGER, INTENT(IN)::                       iSize

Arguments

hKey
Handle of the key previously opened by XRegOpen, containing the value whose data are written.

sValue
Name of the value whose data is set.

*Data
Data associated with given sValue to be written. Can be a string, integer, logical, or real scalar. For other datatypes, such as derived TYPEs or arrays, the variable must be passed using LOC() function and iSize argument must be provided.

iSize
Used only when a derived TYPE or an array is written. Must contain the size, in bytes, of the data pointed to by lpData argument to be written, for example, the following code writes first 10 elements of an integer array:

INTEGER::
myArray(17), hKey, iStatus
hKey = XRegOpen(HKEY_CURRENT_USER,
"Software\MyCompany\MyApp\1.0")
iStatus = XRegWrite(hKey, "My Array", LOC(myArray),
SIZEOF(myArray(1:10)))

Return Value

If successful, the functions returns zero. Otherwise, return value is a Win32 error code.

See Also

XRegOpen, XRegRead

Wrapped APIs

RegSetValueEx

Module

XFTReg.f90


XRegDeleteKey

XRegDeleteKey

XRegDeleteKey deletes a registry key and all its descendants. The function will remove the key and all of the key's values from the registry. The parent key must be previously open by XRegOpen.

INTEGER FUNCTION XRegDeleteKey(hKey, sSubKey)

INTEGER, INTENT(IN)::      hKey
CHARACTER(*), INTENT(IN):: sSubKey

Arguments

hKey
Handle of key containing the key to delete.

sSubKey
Name of the subkey to delete relative to specified hKey.

Return Value

If successful, the return value is zero; otherwise, it is a Win32 error code.

Remarks

The parent key must be opened with KEY_WRITE access.

See Also

XRegOpen, XRegDeleteValue

Wrapped APIs

SHDeleteKey

Module

XFTReg.f90


XRegDeleteValue

XRegDeleteValue

XRegDeleteValue deletes a value from a key previously open by XRegOpen.

INTEGER FUNCTION XRegDeleteKey(hKey, sValue)

INTEGER, INTENT(IN)::      hKey
CHARACTER(*), INTENT(IN):: sValue

Arguments

hKey
Handle of key containing the key to delete.

sValue
Name of the value to delete.

Return Value

If successful, the return value is zero; otherwise, it is a Win32 error code.

Remarks

The parent key must be opened with KEY_WRITE access.

See Also

XRegOpen, XRegDeleteKey

Wrapped APIs

RegDeleteValue

Module

XFTReg.f90


XRegClose

XRegClose

XRegClose closes a registry key previously opened by XRegOpen.

SUBROUTINE XRegClose(hKey)

INTEGER, INTENT(INOUT)::            hKey

Arguments

hKey
Handle of the key to be closed. On exit, this value is set to zero.

See Also

XRegOpen

Wrapped APIs

RegCloseKey

Module

XFTReg.f90


XFTReg Reference

XFTStrings Reference

XFTString module is used for common operations with strings, such as conversions of numbers, case, and string type:

XC2F
XF2C
XLoadString
XMultiByte
XQuote
XShorten
XSqueeze
XString
XNunber
XToLower
XToUpper
XUnicode
XUnQuote


XC2F

XC2F

Reference

XC2F converts a C-style string (CHAR(0)-terminated) into a Fortran string of appropriate length. If the input string is not CHAR(0) terminated, the function does nothing.

FUNCTION XC2F(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::       sString

CHARACTER(LEN=...)::             s

Arguments

sString
String to be converted.

Return Value

The string without trailing CHAR(0) shortened to appropriate length. If the input string does not contain CHAR(0), the output is equal to input string.

Module

XFTStrings.f90


XC2F

XF2C

Reference

XF2C converts a Fortran string to a C-style string. The given string is trimmed of trailing blanks then CHAR(0)-terminated.

FUNCTION XF2C(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::       sString

CHARACTER(LEN=...)::             s

Arguments

sString
String to be converted.

Return Value

The string with a CHAR(0) appended after the last non-blank character.

Module

XFTStrings.f90


XLoadString

XLoadString

Reference

XLoadString loads a string from a string-table resource.

FUNCTION XLoadString(ID, hModule) RESULT(s)

INTEGER, INTENT(IN)::            ID
INTEGER, OPTIONAL, INTENT(IN)::  hModule

CHARACTER(LEN=...)::             s

Arguments

ID
Identifier of the string in string-table resource of given executable

[hModule]
Module handle of an executable or dll containing the string. This handle can be obtained by XGetInstance or LoadLibrary API.

Return Value

The string with given identifier in the string-table resource. If the string does not exist, the return value is an empty string.

Wrapped APIs

LoadString

Module

XFTStrings.f90


XMultiByte

XMultiByte

Reference

XMultiByte function converts a wide (UNICODE), 2-byte string, represented by an array of INTEGER(2), into a multi-byte (ASCII) string. This function is useful for accessing Windows API functions which return wide strings.

FUNCTION
XMultiByte(wString, iCodePage, bConvertAll) RESULT(s)

INTEGER(2), INTENT(IN)::        wString(:)
INTEGER, OPTIONAL, INTENT(IN)::
iCodePage
LOGICAL, OPTIONAL, INTENT(IN):: bConvertAll

CHARACTER(LEN=...)::
s

Arguments

wString
Wide string to be converted, in form of an INTEGER(2) array.

[iCodePage]
Specifies the code page to be used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following values:

Value | Meaning
CP_ACP | ANSI code page
CP_MACCP | Macintosh code page
CP_OEMCP | OEM code page
CP_SYMBOL | Symbol code page (42)
CP_THREAD_ACP | The current thread's ANSI code page
CP_UTF7 | Translate using UTF-7
CP_UTF8 | Translate using UTF-8

If absent, CP_ACP is used.

[bConvertAll]
By default, the function will convert only the wide characters up to terminating zero and return string of that length. If bConvertAll is .TRUE., entire wide string will be converted.

Return Value

Converted string, without terminating CHAR(0) unless bConvertAll is .TRUE.. For characters which do not have representation in given code page, a system-dependent character (usually ?) is substituted.

See Also

XUnicode

Wrapped APIs

WideCharToMultiByte

Module

XFTStrings.f90


XQuote

XQuote

Reference

XQuote encloses a string in quotes.

FUNCTION XQuote(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::      sString

CHARACTER(LEN=LEN_TRIM(sString)+2):: s

Arguments

sString
String to be enclosed in quotes.

Return Value

Returned string is equal to TRIMmed (but not adjusted left if necessary) input string enclosed in quotes.

See Also

XUnQuote

Module

XFTStrings.f90


XShorten

XShorten

Reference

XShorten shortens a string to the given length, by breaking it into words and adding an ellipsis (...) in the middle, beginning or end.

FUNCTION
XShorten(sString, iLen, iSide, sDelim) RESULT(s)

CHARACTER(*), INTENT(IN)::           sString
INTEGER, INTENT(IN)::
iLen
INTEGER, OPTIONAL, INTENT(IN)::      iSide
CHARACTER(*), OPTIONAL, INTENT(IN):: sDelim

CHARACTER(LEN=iLen)::
s

Arguments

sString
String to be shortened.

iLen
Desired length of the string. If the LEN_TRIM(sString) is shorter than iLen, the function does nothing.

[iSide]
An integer defining from which side the shortening occurs. If zero (default), the string is shortened from the middle, and the ellipsis occurs in the middle of the returned value. If negative, the string is shortened from right (the ellipsis occurs in the beginning), and if positive, the string is shortened from left. Constants XS_MIDDLE, XS_RIGHT and XS_LEFT can be used for legibility.

[sDelim]
Set of word-delimiters, i.e. the characters on which word breaking can occur. The default set is " /\;:," (space included).

Return Value

Input string shortened on appropriate end with ellipsis replacing the excluded part.

Remarks

This routine is suitable for shortening file names which occur on various parts of user interface, such as MRU lists.

Module

XFTStrings.f90


XSqueeze

XSqueeze

Reference

XSqueeze removes any leading or embedded spaces and/or ASCII control characters from a given string. Any space characters in the result string will be trailing spaces.

FUNCTION XSqueeze(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::      sString

CHARACTER(LEN=LEN_TRIM(sString)):: s

Arguments

sString
String to be processed.

Return Value

Returned string is equal to the given string with any control characters transformed to space characters and with all space characters moved to the end of the string.

Module

XFTextra.f90


XString

XString

Reference

XString converts an INTEGER(4) or REAL(4) into its character representation. XString is generic name for the following two procedures:

FUNCTION PXIString(iVal, iBase) RESULT(s)

INTEGER, INTENT(IN)::           iVal
INTEGER, OPTIONAL, INTENT(IN):: iBase

CHARACTER(LEN=...)::             s

FUNCTION PXFString(fVal, iPrec) RESULT(s)

REAL, INTENT(IN)::              fVal
INTEGER, OPTIONAL, INTENT(IN):: iPrec

CHARACTER(LEN=...)::             s

Arguments

iVal/fVal
Numeric (INTEGER(4) or REAL(4)) value to be converted.

[iBase]
For integer value, specifies the base of result. Valid values are 10 (default), 2 (binary), 8 (octal) and 16 (hex).

[iPrec]
For real value, specifies the exact number of decimal places for the result. The default behavior is described in remarks below.

Return Value

String of minimal length containing the converted numerical values. If an error occurs, the return value is an empty string.

Remarks

For real values, the default number of significant digits is 10. That means that the corresponding format is a "F10.x" (or "F11.x" for negative numbers), where number of decimal places depends on the magnitude. However, if fVal is a whole number, no decimal digits are displayed, and length of result depends only on the number's magnitude. Explicit specification of iPrec overrides this behavior.

Example

WRITE(*,*) XQuote(XString(74))
"74"
WRITE(*,*) XQuote(XString(-1234151))   "-1234151"
WRITE(*,*) XQuote(XString(42,16))      "2A"
WRITE(*,*) XQuote(XString(42,8))       "52"
WRITE(*,*) XQuote(XString(42,2))       "101010"

WRITE(*,*) XQuote(XString(0.0000001))  "0.000000100"
WRITE(*,*) XQuote(XString(-0.0000001)) "-0.000000100"
WRITE(*,*) XQuote(XString(42.))        "42."
WRITE(*,*) XQuote(XString(42.,6))      "42.000000"
WRITE(*,*) XQuote(XString(0.,2))       "0.00"

Module

XFTStrings.f90


XNumber

XNumber

Reference

XNumber attempts to decode a given string as an INTEGER(4), REAL(4), or REAL(8) value. It serves as a complement to XString.

LOGICAL FUNCTION XNumber (sString, Value)

CHARACTER(*), INTENT(IN)::              sString
INTEGER/REAL(4)/REAL(8), INTENT(OUT) :: Value

Arguments

sString
Given text string to be converted. It may start with a leading sign, must contain one or more digits, may contain a decimal point, may also contain an optionally signed exponent preceded by one of the letters 'E', 'e', 'D', or 'd'. All spaces within sString are ignored. If sString is blank, the function returns .true. with a zero Value .

Value
An INTEGER(4), REAL(4), or REAL(8) variable to contain the result. Will be set zero if the conversion fails.

Return Value

.TRUE. if the conversion succeeds; .FALSE. if the given text does not make sense as a number.

Remarks

sString is first interpreted as a REAL(8) value using the standard Fortran conventions. If the decoding succeeds, that result is then mapped to a REAL(4) or INTEGER value as required.

Module

XFTextra.f90


XToLower and XToUpper

XToLower/XToUpper

Reference

XToLower converts a string to lowercase, and XToUpper converts a string to uppercase. Non-alphabet characters are left untouched.

FUNCTION XToLower/XToUpper(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::           sString

CHARACTER(LEN=LEN(sString))::        s

Arguments

sString
String to be converted to lowercase or uppercase.

Return Value

Input string converted to lowercase or uppercase.

Remarks

The function also affects characters on positions (192-222) (uppercase) and (224-254) (lowercase) in the current thread codepage. This conversion is (mostly) valid (i.e. the affected characters are uppercase and lowercase letters) for Western, Central European, Cyrillic, Turkish, Greek and Baltic code pages.

Module

XFTStrings.f90


XUnicode

XUnicode

Reference

XUnicode function converts a multi-byte (ASCII) string to a wide (UNICODE), 2-byte string, represented by an array of INTEGER(2). This function is useful for accessing Windows API functions which expect wide strings.

FUNCTION
XUnicode(sString, iCodePage) RESULT(ws)

CHARACTER(*), INTENT(IN)::      sString
INTEGER, OPTIONAL, INTENT(IN):: iCodePage

INTEGER(2)::
ws(LEN(sString)+1)

Arguments

sString
String to be converted.

iCodePage
Specifies the code page to be used to perform the conversion. This parameter can be given the value of any code page that is installed or available in the system. You can also specify one of the following values:

Value | Meaning
CP_ACP | ANSI code page
CP_MACCP | Macintosh code page
CP_OEMCP | OEM code page
CP_SYMBOL | Symbol code page (42)
CP_THREAD_ACP | The current thread's ANSI code page
CP_UTF7 | Translate using UTF-7
CP_UTF8 | Translate using UTF-8

Return Value

Integer(2), zero-terminated array representing the converted string. If an error occurs, the array size is zero.

See Also

XMultiByte

Wrapped APIs

MultiByteToWideChar

Module

XFTStrings.f90


XUnQuote

XUnQuote

Reference

XUnQuote removes the quotes around given string. If the input string does not contain two quotes, it does nothing. The function also trims all characters before the leading and after the ending quote.

FUNCTION XUnQuote(sString) RESULT(s)

CHARACTER(*), INTENT(IN)::      sString

CHARACTER(LEN=...):: s

Arguments

sString
String to be unquoted.

Return Value

Part of the input string between the leading and after the ending quote.

See Also

XQuote

Module

XFTStrings.f90


XFTToolbar Overview

XFTToolbar Overview

Reference

XFTToolbar module is used for handling of toolbars. A toolbar is a control which contains buttons used for execution of most frequently used actions. The toolbar is always associated with a parent window. In a general sense, toolbar can contain controls other than buttons, such as drop-down lists or edit boxes; this feature is not currently supported by Xeffort, but it is planned for a future release.

A toolbar consists of several buttons, each having a small bitmap. Clicking a toolbar button generates a WM_COMMAND message, which can be handled in the toolbar's parent window using an appropriate handler routine. The toolbar button can behave like an ordinary pushbutton or like a check-box, depending on its style. Also, it can have a set of states, like enabled/disabled or checked/unchecked.

In Xeffort, an empty toolbar is first created using XCreateToolbar routine. It fills in a variabe of type X_TOOLBAR. After that, the bitmap(s) have to be associated with the toolbar control using XToolbarSet routine with CTL_BITMAP argument. Next, the toolbar buttons should be added using XToolbarAddButtons routine. After the toolbar is created, state and appearance of its buttons can be manipulated using XToolbarSet, XToolbarAddButtons, XToolbarRemoveButtons and XToolbarSetPos routines. Finally, the toolbar should be destroyed using XDestroyToolbar.

Toolbar position and styles

Native Windows toolbars allow the toolbar control only to be docked alongside the top edge of its parent window. Xeffort toolbars, however, can be docked over any edge of the parent window's client area, or can "float" on any position within it. This is achieved by introducing an intermediary window, toolbar host, which hosts the toolbar control on one side but acts as a child window on the other side. The Xeffort programmer normally need not take care of the host window, as all its services are available through XFTToolbar routines.

Xeffort defines several custom window styles which manage the apparance of the toolbar. Position and style of a Xeffort toolbar can be adjusted using XToolbarSet(CTL_STYLE), XToolbarSetPos and XCreateToolbar routines. In addition, the toolbar with CCS_DOCKABLE style can be dragged around or docked by the user within parent window's client area, using a "dragging grip".

Note, however, that a toolbar does not automagically dock itself along appropriate edge when the parent window is resized. For example, a toolbar docked along right edge of the parent window will disappear when the parent is made smaller. Thus, if the parent window is resizable, the application should handle WM_SIZE message and call XToolbarSetPos to inform the toolbar that it should reposition itself.

Also, note that the Xeffort toolbars are child windows (although they always appear as topmost of all the parent's child controls) and that they occupy a portion of parent's client area (much like status bars). That means that the application should be aware about existence of the toolbar and take care not to draw over it. Usually, the best architecture is to define a "view" child window embedded within main frame window, used to display the graphic output; the application should take care about proper tiling of the toolbar, view window and/or the status bar by handling WM_SIZE message and adjust the positions accordingly using XSetWindowPos, XToolbarSetPos and/or XCtlMove. In order to fit well within such setup, a Xeffort toolbar sends a WM_SIZE message to the parent window whenever it is (un)docked, allowing the parent to do resizing appropriately.

To embed a toolbar as a floating control within other window (like e.g. in standard File Open dialog), specify CCS_FLOATING style and adjust its position using XToolbarSetPos.

Toolbar images

A toolbar control holds a list of button images. See Toolbar Images page for detailed explanation on usage of images with a toolbar control.

Tooltips

If the toolbar has TBSTYLE_TOOLTIPS style, it sends a WM_NOTIFY/TTN_GETDISPINFO message to the parent window whenever it needs to display a tooltip. By default, the toolbar host window will try to map an entry in application's string table to the button identifier. That means that the simplest way to provide tooltips is to create string table entries for each button with the same ID as the button ID.

Still, the Xeffort toolbar relays that event to the parent window, which can supply its own tooltip handling, by registering a command handler and handling TTN_GETDISPINFO code:

SUBROUTINE XW_FRAME_OnButtonA(xWnd, idCmd, nCode)

USE XFTNotify

TYPE(X_WINDOW):: xWnd
INTEGER, INTENT(IN):: idCmd, nCode

TYPE(T_NMTTDISPINFO), POINTER:: NMTD

INCLUDE "Resource.fd"

IF (nCode.EQ.TTN_GETDISPINFO) THEN
NMTD => X_NMTTDISPINFO(nCode)
NMTD%hinst = 0
NMTD%lpszText = LOC("New button tooltip text"C)

ELSE IF (nCode.EQ.0) THEN
!Normal handling of button click

...
END IF

END SUBROUTINE XW_FRAME_OnButtonA

Note that command handlers for toolbar buttons should always test for nCode in order to provide normal button click handling; the toolbars send at least TTN_GETDISPINFO and TBN_HOTITEMCHANGE notification, which are not usually handled.


XFTToolbar Reference

XFTToolbar Reference

Overview

Toolbar Creation and Destruction

XCreateToolbar

XDestroyToolbar

Toolbar Placement

XToolbarGetPos

XToolbarSetPos

Controlling Toolbar Buttons

Toolbar Images

XToolbarAddButtons

XToolbarRemoveButtons

XToolbarRemoveAllButtons

XToolbarSet

XToolbarGet

Styles and States

Toolbar control styles

Toolbar button styles and states

XFTToolbar Types

X_TBBUTTON

X_TOOLBAR


XFTToolbar: Toolbar button styles and states

XFTToolbar: Toolbar button styles and states

Reference

Toolbar button styles

The following flags define styles of a toolbar button. The style of button can be set using XToolbarSet or XToolbarAddButtons routines, and retrieved using XToolbarGet routine.

Style | Description
TBSTYLE_BUTTON | Creates a toolbar button that looks like a standard Windows push button.
TBSTYLE_CHECK | Creates a button that toggles between the pressed and not pressed states each time the user clicks it. The button has a different background color when it is in the pressed state.
TBSTYLE_CHECKGROUP | Creates a check button that stays pressed until another button in the group is pressed.
TBSTYLE_GROUP | Creates a button that stays pressed until another button in the group is pressed.
TBSTYLE_AUTOSIZE | Calculates a button's width based on the text of the button, not on the size of the image.
TBSTYLE_DROPDOWN | Creates a drop-down list button.
TBSTYLE_SEP | Creates a separator, which provides a small gap between button groups. A button that has this style does not receive user input

Toolbar button states

The following flags define states of a toolbar button. The state is initially set using XToolbarAddButtons, and can be changed in runtime using XToolbarSet/XToolbarGet.

State |  | Description
TBSTATE_CHECKED | The button has the TBSTYLE_CHECKED style and is being pressed.
TBSTATE_ENABLED | The button accepts user input. A button without this state does not accept user input and is grayed.
TBSTATE_HIDDEN | The button is not visible and cannot receive user input.
TBSTATE_HIGHLIGHTED | The button is highlighted.
TBSTATE_INDETERMINATE | The button is grayed.
TBSTATE_PRESSED | The button is being pressed.
TBSTATE_WRAP | The button has a line break following it. The button must also have the TBSTATE_ENABLED state


Toolbar Images

XFTToolbar: Toolbar Images

Reference

A toolbar control holds a list of button images. All button images must be of the same dimension, as specifed in call to XCreateToolbar (the default dimension is 16x15 pixels). Button images can be set using bitmap(s) consisting of button bitmaps merged horizontally, or using an image list, or a combination of the two. The images should be set before the buttons that use them are added to the toolbar. The toolbar internally "merges" added bitmaps and assigns an index to each button bitmap. When a button is added to the toolbar using XToolbarAddButtons, each X_TBBUTTON structure should contain an index referring to the individual image in the merged list.

An application can also use "standard" Windows bitmaps for common buttons such as Cut, Copy, Paste, etc. by specifying e.g. IDB_STD_SMALL_COLOR as the bitmap.

A bitmap can be assigned to the toolbar in the following three ways:

  1. Specify a bitmap handle as Value in call to XToolbarSet with iAction CTL_BITMAP. The bitmap image is appended to the current image list. The bitmap can be loaded using e.g. XCreateBitmap:

    bSt = XCreateBitmap(xBmp, IDR_TOOLBAR1, LR_LOADMAP3DCOLORS)
    bSt = XToolbarSet(xTb, IDR_TOOLBAR1, xBmp%hBmp, CTL_BITMAP)

  2. To load predefined system images, specify one of the following constants as Value in call to XToolbarSet with iAction CTL_BITMAP. The bitmap image is appended to the current image list:

    IDB_HIST_LARGE_COLOR

    Explorer bitmaps in large size.
    IDB_HIST_SMALL_COLOR | Explorer bitmaps in small size.
    IDB_STD_LARGE_COLOR | Standard bitmaps in large size.
    IDB_STD_SMALL_COLOR | Standard bitmaps in small size.
    IDB_VIEW_LARGE_COLOR | View bitmaps in large size.
    IDB_VIEW_SMALL_COLOR | View bitmaps in small size.
    Index values for IDB_HIST_LARGE_COLOR and IDB_HIST_SMALL_COLOR:
    HIST_ADDTOFAVORITES | Add to favorites.
    HIST_BACK | Move back.
    HIST_FAVORITES | Open favorites folder.
    HIST_FORWARD | Move forward.
    HIST_VIEWTREE | View tree.
    Index values for IDB_STD_LARGE_COLOR and IDB_STD_SMALL_COLOR:
    STD_COPY | Copy operation.
    STD_CUT | Cut operation.
    STD_DELETE | Delete operation.
    STD_FILENEW | New file operation.
    STD_FILEOPEN | Open file operation.
    STD_FILESAVE | Save file operation.
    STD_FIND | Find operation.
    STD_HELP | Help operation.
    STD_PASTE | Paste operation.
    STD_PRINT | Print operation.
    STD_PRINTPRE | Print preview operation.
    STD_PROPERTIES | Properties operation.
    STD_REDOW | Redo operation.
    STD_REPLACE | Replace operation.
    STD_UNDO | Undo operation.
    Index values for IDB_VIEW_LARGE_COLOR and IDB_VIEW_SMALL_COLOR:
    VIEW_DETAILS | Details view.
    VIEW_LARGEICONS | Large icons view.
    VIEW_LIST | List view.
    VIEW_NETCONNECT | Connect to network drive.
    VIEW_NETDISCONNECT | Disconnect from network drive.
    VIEW_NEWFOLDER | New folder.
    VIEW_PARENTFOLDER | Go to parent folder.
    VIEW_SMALLICONS | Small icon view.
    VIEW_SORTDATE | Sort by date.
    VIEW_SORTNAME | Sort by name.
    VIEW_SORTSIZE | Sort by size.
    VIEW_SORTTYPE | Sort by type.

  3. Create an image list and specify its handle as Value. Note that this overwrites any existing image list. The following example loads three 16x16 icons into an image list and assigns it to the toolbar:

INTEGER::            i, hIl, hIcon
INTEGER, PARAMETER:: idIcon(3) = (/IDI_BLUE, IDI_YELLOW, IDI_RED/)

hIL = ImageList_Create(16, 16, ILC_MASK, 3, 0)
DO i=1,3
   hIcon = LoadImage(XGetInstance(), idIcon(i), IMAGE_ICON, &
                     16, 16, LR_DEFAULTCOLOR)
   bSt = ImageList_ReplaceIcon(hIL, -1, hIcon)
END DO
bSt = XToolbarSet(xTb, IDR_TOOLBAR1, hIL, CTL_BITMAP)

On retrieval, only a handle to an image list can be returned, i.e. the toolbar converts bitmaps supplied using methods 1 and 2 to an image list:

bSt = XToolbarGet(xTb, IDR_TOOLBAR1, hIl, CTL_BITMAP)
n = ImageList_GetImageCount(hIl)
n = ImageList_GetImageInfo(hIl, 4, IIF)


XFTToolbar: Toolbar control styles

XFTToolbar: Toolbar control styles

The following flags define styles of a toolbar control. In addition, a toolbar can have a combination of window styles.

Style | Value (hex) | Description
TBSTYLE_CUSTOMERASE | Z'2000' | Creates a toolbar that generates NM_CUSTOMDRAW notification messages when it processes WM_ERASEBKGND messages.
TBSTYLE_FLAT | Z'0800' | Creates a flat toolbar, in which both the toolbar and the buttons are transparent.
TBSTYLE_TOOLTIPS | Z'0100' | Creates a tooltip control that an application can use to display descriptive text for the buttons in the toolbar.
TBSTYLE_TRANSPARENT | Z'8000' | Creates a transparent toolbar, in which the toolbar is transparent but the buttons are not.
TBSTYLE_WRAPABLE | Z'0200' | Creates a toolbar that can have multiple rows of buttons. Toolbar buttons can wrap to the next line when the toolbar becomes too narrow to include all buttons on the same line. Wrapping occurs on separation and non-group boundaries. XCreateToolbar adds this style by default in order to enable vertical appearance of the toolbar.
CCS_ADJUSTABLE | Z'0020' | Enables a toolbar's built-in customization features, which allow the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the Customize Toolbar dialog box, which allows the user to add, delete, and rearrange toolbar buttons.
CCS_BOTTOM | Z'0003' | Causes the control to position itself at the bottom of the parent window's client area and sets the width of the control to be the same as the parent window's width. Status windows have this style by default.
CCS_BOTTOMRIGHT | Z'0002' | Specifies that the control is docked along bottom edge (provided CCS_VERT is absent) or right edge (if CCS_VERT is present) of the parent window's client area
CCS_DOCKABLE | Z'0400' | Specifies that user can drag the control and dock it along one of parent window edges, or leave it floating. Control with this style displays a "dragging grip" on its left or top side.
CCS_FLOATING | Z'0008' | Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent. This style overrides other positioning styles such as CCS_TOP, CCS_BOTTOM, CCS_RIGHT, CCS_VERT.
CCS_LEFT | Z'0081' | Causes the control to display vertically on the left side of the parent window.
CCS_NODIVIDER | Z'0040' | Prevents a 2-pixel highlight from being drawn at the top of the control.
CCS_NOPARENTALIGN | Z'0008' | Same as CCS_FLOATING.
CCS_NORESIZE | Z'0004' | Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing.
CCS_TOP | Z'0001' | Causes the control to position itself at the top of the parent window's client area and matches the width of the control to the same width of the parent window. Toolbars have this style by default.
CCS_RIGHT | Z'0083' | Causes the control to display vertically on the right side of the parent window.
CCS_VERT | Z'0080' | Causes the control to display vertically.

Styles indicated bold are Xeffort-specific. Namely, CCS_BOTTOMRIGHT and CCS_FLOATING have similar semantics with Windows common control styles CCS_NOMOVEY and CCS_NOPARENTALIGN of the same value. CCS_DOCKABLE style (hex 0400) overrides default toolbar style TBSTYLE_ALTDRAG (which does not have much practical value).

For example, to embed a toolbar as a floating control within other window (like e.g. in standard File Open dialog), specify CCS_FLOATING style and adjust its position using XToolbarSetPos.

See also

To olbar button styles , XCreateToolbar, XToolbarSet, XToolbarSetPos


X_TBBUTTON

X_TBBUTTON

X_TBBUTTON structure describes a toolbar button. It is used with XToolbarAddButtons routine to add buttons to the toolbar.

TYPE X_TBBUTTON
INTEGER ID
INTEGER iState
INTEGER iStyle
INTEGER iBitmap
INTEGER pszText
END TYPE X_TBBUTTON

Members

ID
Control identifier of the button. An arbitrary application-defined integer which should be unique among all the toolbar button IDs.

iState
Initial button state. Can be a combination of flags described in Toolbar button states.

iStyle
Button style. Can be a combination of flags described in Toolbar button styles.

iBitmap
Index of the image in the current toolbar's image list associated with the button. See Toolbar images.

pszText
Reserved for future use; set to zero.

See Also

XToolbarAddButtons

Module

XFTToolbar.f90


X_TOOLBAR

X_TOOLBAR

X_TOOLBAR structure describes a toolbar.

TYPE X_TOOLBAR
    INTEGER:: hWnd = 0
    INTEGER:: hToolbar = 0
    ...
END TYPE X_TOOLBAR

Members

hWnd

Windows handle of the toolbar's host window.

hToolbar

Windows handle of the toolbar control itself.

See Also

XCreateToolbar

Module

XFTToolbar.f90


XCreateToolbar

XCreateToolbar

XCreateToolbar creates an empty toolbar.

LOGICAL FUNCTION
XCreateToolbar(xWnd, xToolbar, ID, iStyle, &
iXButton, iYButton, iXBmp, iYBmp)

TYPE(X_WINDOW), INTENT(IN)::
xWnd
TYPE(X_TOOLBAR), INTENT(OUT)::     xToolbar
INTEGER, INTENT(IN)::
ID
INTEGER, OPTIONAL, INTENT(IN)::    iStyle
INTEGER, OPTIONAL, INTENT(IN)::    iXButton
INTEGER, OPTIONAL, INTENT(IN)::    iYButton
INTEGER, OPTIONAL, INTENT(IN)::    iXBmp
INTEGER, OPTIONAL, INTENT(IN)::    iYBmp

Arguments

xWnd
A X_WINDOW structure representing toolbar's parent window.

xToolbar
A X_TOOLBAR structure representing the newly created toolbar.

ID
Control identifier ot the toolbar.

[iStyle]
An .OR. combination of window styles and toolbar styles for the toolbar. If absent, the default style is TBSTYLE_FLAT.OR.TBSTYLE_TOOLTIPS.OR.WS_BORDER.

[iXButton, iYButton]
Size of individual buttons on the toolbar, in pixels. If absent, the default value is 16x16 pixels.

[iXBmp, iYBmp]
Size of images of indivitual buttons, in pixels. If absent, the default value is 16x15 pixels. The actual bitmaps should be added later using XToolbarSet(CTL_IMAGE)

Return Value

If the function succeeds, the return value is .TRUE., otherwise .FALSE.

See Also

XToolbarAddButtons, XDestroyToolbar, XToolbarSet

Wrapped APIs

CreateToolbarEx, CreateWindowEx

Module

XFTToolbar.f90


XDestroyToolbar

XDestroyToolbar

DestroyToolbar destroys a toolbar.

SUBROUTINE XDestroyToolbar(xToolbar)

TYPE(X_TOOLBAR), INTENT(INOUT)::  xToolbar

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar to be deleted. All members of the structure are set to zero. The xToolbar variable may be latter reused for creation of a new Toolbar, but cannot be used in other Toolbar-related functions until it's recreated.

See Also

XCreateToolbar

Wrapped APIs

DestroyWindow

Module

XFTToolbar.f90


XToolbarAddButtons

XToolbarAddButtons

XTooolbarAddButtons adds buttons to an existing toolbar.

INTEGER FUNCTION
XToolbarAddButtons(xToolbar, xButtons, nIndex)

TYPE(X_TOOLBAR), INTENT(IN)::     xToolbar
TYPE(X_TBBUTTON), INTENT(IN)::    xButtons(:)
INTEGER, OPTIONAL, INTENT(IN)::   nIndex

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar.

xButtons
Array of X_TBBUTTON structures containing properties of newly created buttons.

[nIndex]
Index of an existing button after which the new buttons are to be inserted. If absent, the routine appends the buttons to the end of existing button list.

Return Value

The functions returns current count of buttons on the toolbar.

Example

The following example inserts five buttons to the toolbar. First two buttons are normal buttons, the third is separator, and the last two are check-buttons. Four bitmaps from the toolbar's image list are associated with the buttons. Then, appropriate command handlers are associated with the buttons using XSetCommand routine.

xButtons(1) =  X_TBBUTTON(ID_ROLL,
TBSTATE_ENABLED, TBSTYLE_BUTTON, 1, 0)
xButtons(2) = X_TBBUTTON(ID_NEWROLL, TBSTATE_ENABLED, TBSTYLE_BUTTON, 2, 0)
xButtons(3) = X_TBBUTTON(0, 0, TBSTYLE_SEP, 0, 0)
xButtons(4) = X_TBBUTTON(ID_ANNOUNCE, TBSTATE_ENABLED, TBSTYLE_CHECK, 3, 0)
xButtons(5) =
  X_TBBUTTON(ID_UNDO, TBSTATE_ENABLED, TBSTYLE_CHECK, 4, 0)

iSt = XToolbarAddButtons(xTb, xButtons(1:5), 0)

bSt =
  XSetCommand(XW_FRAME, ID_ROLL, OnRoll)
bSt =
  XSetCommand(XW_FRAME, ID_NEWROLL, OnNewRoll)
bSt =
  XSetCommand(XW_FRAME, ID_ANNOUNCE, OnAnnounce)
bSt =
  XSetCommand(XW_FRAME, ID_UNDO, OnUndo)

See Also

XToolbarSet, X_MENUITEM

Wrapped APIs

TB_ADDBUTTONS, TB_INSERTBUTTON

Module

XFTToolbar.f90


XToolbarGet/XToolbarSet

XToolbarSet/XToolbarGet

XToolbarSet sets, and XToolbarGet retrieves a property of a toolbar button or the toolbar itself.

INTERFACE XToolbarSet
   MODULE PROCEDURE XToolbarSetInt
   MODULE PROCEDURE XToolbarSetChar
   MODULE PROCEDURE XToolbarSetLog
END INTERFACE

LOGICAL FUNCTION XToolbarSet(xToolbar, ID, Value, iAction)

TYPE(X_TOOLBAR), INTENT(INOUT)::        xToolbar
INTEGER, INTENT(IN)::                   ID
INTEGER/CHARACTER/LOGICAL, INTENT(IN):: Value
INTEGER, INTENT(IN)::                   iAction

INTERFACE XToolbarGet
   MODULE PROCEDURE XToolbarGetInt
   MODULE PROCEDURE XToolbarGetChar
   MODULE PROCEDURE XToolbarGetLog
END INTERFACE

LOGICAL FUNCTION XToolbarGet(xToolbar, ID, Value, iAction)

TYPE(X_TOOLBAR), INTENT(INOUT)::        xToolbar
INTEGER, INTENT(IN)::                   ID
INTEGER/CHARACTER/LOGICAL, INTENT(OUT)::Value
INTEGER, INTENT(IN)::                   iAction

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar.

ID
Numeric identifier of the toolbar button, as set in during its creation by XToolbarAddButtons, or numeric identifier of the toolbar control, as set using XCreateToolbar.

Value
An integer, string, or logical scalar representing the value of button's or toolbar's property.

iAction
An integer constant describing which property to retrieve or set. The following combinations of iAction and Value are supported;

Integer Value (XToolbarSetInt/XToolbarGetInt)

iAction | Button |  | Toolbar |  | Meaning
 | Set | Get | Set | Get
CTL_STYLE |  | • | • | • | Sets or retrieves style of the toolbar control or the button. Button style can not be changed after creation, so XToolbarSet is not supported for that combination.
CTL_BITMAP | • | • | • | • | For a button, sets or retrieves the index of the image in the current toolbar's image list. For a toolbar, sets or retrieves complete image list or a bitmap. See Toolbar images for more details.
CTL_ID |  | • |  |  | Returns the identifier of the button whose index is specified by ID argument.
CTL_INDEX |  | • |  |  | Returns the index of the button whose identifier is specified by ID argument.
CTL_NUMITEMS |  |  |  | • | Returns the current number of buttons.

String Value (XToolbarSetChar/XToolbarGetChar)

No values are currently supported.

Logical Value (XToolbarSetLog/XToolbarGetLog)

iAction | Button |  | Toolbar |  | Meaning
 | Set | Get | Set | Get
CTL_ENABLE | • | • | • | • | Enables or disables a button. For toolbar ID, enables or disables all the buttons in the toolbar
CTL_VISIBLE | • | • | • | • | Shows or hides the button or the toolbar itself.
CTL_STATE | • | • |  |  | Checks or unchecks a toolbar button. The button must have TBSTYLE_CHECK or TBSTYLE_CHECKGROUP style.

Return Value

If successful, the functions returns .TRUE.; otherwise, it returns .FALSE.

Wrapped APIs

GetMenuItemInfo, GetSubMenu

Module

XFTToolbar.f90


XToolbarGetPos

XToolbarGetPos

XToolbarGetPos function returns toolbar's current position and size.

LOGICAL FUNCTION XToolbarGetPos(xToolbar, iX, iY, iWidth, iHeight)

TYPE(X_TOOLBAR)::                 xToolbar
INTEGER, OPTIONAL, INTENT(OUT)::  iX,iY
INTEGER, OPTIONAL, INTENT(OUT)::  iWidth, iHeight

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar.

[iX, iY]

Position of top-left corner of the toolbar, in pixels expressed as offset from origin of parent's client area.

[iWidth, iHeight]

Control window width and height, in pixels.

Return Value

If successful, the function returns .TRUE.

See Also

XT oolbarSetPos

Wrapped APIs

GetWindowRect

Module

XFTToolbar.f90


XToolbarRemoveButtons

XToolbarRemoveButtons

XToolbarRemoveButtons removes buttons from the toolbar. The buttons can be represented as an array of IDs or array of indices.

INTEGER FUNCTION
XToolbarRemoveButtons(xToolbar, nIndex, bByID)

TYPE(X_TOOLBAR), INTENT(IN)::     xToolbar
INTEGER, INTENT(IN)::
nIndex(:)
LOGICAL, OPTIONAL, INTENT(IN)::   bByID

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar.

nIndex
Array of IDs or indices of buttons to be removed from the toolbar. bByID argument specifies the interpretation. If bByID is .FALSE., nIndex specifies button indices; in that case, the array must be sorted in increasing order.

[bByID]
Specifies whether nIndex contains an array of indices (.FALSE.) or IDs (.TRUE.). If absent, the default is .TRUE.

Return Value

The functions returns current count of buttons on the toolbar.

See Also

XToolbarAddButtons

Wrapped APIs

TB_DELETEBUTTON

Module

XFTToolbar.f90


XToolbarRemoveAllButtons

XToolbarRemoveAllButtons

XToolbarRemoveAllButtons removes all buttons from the toolbar.

SUBROUTINE XToolbarRemoveAllButtons (xToolbar)

TYPE(X_TOOLBAR), INTENT(IN):: xToolbar

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar to be emptied.

See Also

XToolbarRemoveButtons

Wrapped APIs

TB_DELETEBUTTON

Module

XFTToolbar.f90


XToolbarSetPos

XToolbarSetPos

XToolbarSetPos sets the toolbar's position and size. If optional coordinates is specified, it sets the position accordingly and sets up CCS_FLOATING style for the toolbar. Otherwise, it realigns the toolbar to appropriate edge of parent window's client area according to existing CCS_BOTTOM, CCS_VERT, CCS_RIGHT or CCS_LEFT styles.

LOGICAL FUNCTION XToolbarSetPos(xToolbar, iX, iY)

TYPE(X_WINDOW)::                 xWnd
INTEGER, OPTIONAL, INTENT(IN)::  iX,iY

Arguments

xToolbar
 X_TOOLBAR structure representing the toolbar.

[iX, iY]

Position of top-left corner of the toolbar, in pixels expressed as offset from origin of parent's client area. Both iX and iY have to be present simultaneously.

Example

A toolbar does not automagically dock itself along appropriate edge when the parent window is resized. For example, a toolbar docked along right edge of the parent window will disappear when the parent is made smaller. Thus, if the parent window is resizable, the application should handle WM_SIZE message and call XToolbarSetPos to inform the toolbar that it should reposition itself:

Remarks

XToolbarSetPos will send a WM_SIZE message to the parent if the toolbar has changed its docking state, e.g. if it is undocked from its top position to floating state. By handling WM_SIZE message, the parent can adjust position of its other child windows accordingly.

LOGICAL FUNCTION XW_FRAME_OnSize(xWnd, iWidth, iHeight, nFlag)

TYPE(X_WINDOW):: xWnd
INTEGER, INTENT(IN):: iWidth, iHeight
INTEGER, INTENT(IN):: nFlag

INTEGER:: iSt, tbWidth, tbHeight, iStyle, iX, iY, cX, cY

!Realign the toolbar

iSt = XToolbarSetPos(xTb)

!Query toolbar dimensions and style:

iSt = XToolbarGetPos(xTb, iWidth=tbWidth, iHeight=tbHeight)
iSt = XToolbarGet(xTb, IDR_TOOLBAR1, iStyle, CTL_STYLE)
!Adjust position and size of other child window so that it fills the

!rest of client area
iX = 0

iY = 0

cX = iWidth

cY = iHeight

IF (IAND(iStyle,CCS_VERT).NE.0) THEN
cX = cX - tbWidth

IF (IAND(iStyle,CCS_BOTTOMRIGHT).EQ.0) iX = tbWidth

ELSE
cY = cY - tbHeight

IF (IAND(iStyle,CCS_BOTTOMRIGHT).EQ.0) iY = tbHeight

END IF

iSt = XSetWindowPos(xChild, iX, iY, cX, cY)
XW_FRAME_OnSize = .FALSE.

END FUNCTION XW_FRAME_OnSize

Return Value

If successful, the function returns .TRUE.

See Also

XToolbarGetPos

Wrapped APIs

SetWindowPos

Module

XFTToolbar.f90


XFTWND Overview

XFTWND Overview

Reference

XFTWND library is set of routines which wrap a part of Windows window-manipulation functions.

XFTWND module is the heart of Xeffort library; it is important to understand the concepts behind windows, controls, and messages (events). The former are described in more detail in Window Events page. This overview assumes the programmer is familiar with basic concepts of window and application. Rather, it focuses on how windows are used under Xeffort framework.

A window is a rectangular area of the screen where the application displays output and receives input from the user. In Windows API, every window is uniquely identified by its handle, which is a 32-bit integer. Under Xeffort, every window is represented by a variable of type X_WINDOW. A X_WINDOW type, apart from window handle, contains additional info which should be used only by Xeffort framework. See Design Considerations for information on how to ensure that each window is uniquely represented by a X_WINDOW structure.

Every Windows application has at least one window, referred to as frame or main window. The frame window is the first created window by the application. Later, all non-trivial applications create more windows, of permanent (i.e. lasting as long as the frame window) or temporary nature. (There are also windowless applications, but let's forget about them at the moment - Xeffort is a GUI library). In Xeffort library, that main window can be always referred by variable named XW_FRAME. Main window can have one or more child windows. Also, there are popup windows, which belong to the application as well, but have a bit weaker relationship than the child windows. Dialogs are special kind of popup windows. Dialogs (or other windows) contain controls, such an edit boxes or buttons, which are also child windows of its own.

When writing "pure" Xeffort application, windows are created by XCreateWindow function. Dialogs and controls, which are the most frequently used form of user interface, and thus have a lot of "precoded" behavior, have somewhat special treatment: modules XFTDialog and XFTCtrl are all devoted to handling dialogs and controls. It is not necessary to create them using XCreateWindow.

However, if you already have an existing Win32 or QuickWin application, Xeffort can tie to the existing code, in order to simplify programming (Win32) or extend behavior/override limitations (QuickWin). See Window Bindings page for more information.

Behavior of windows

Behavior of windows is affected by both their systemic properties, which automatically dictate certain most frequently used aspects, and by programmer-defined part, which defines appearance and properties of specific windows or specific groups of windows used in concrete application.

Systemic aspects of windows' behavior include:

  • Window styles, which mostly define visual appearance of window's borders and relationship with higher- and lower- level windows.

  • Window class, which defines the common behavior of all windows based on the same class, i.e. how they respond to user's actions. For example, windows of class "Edit" (edit controls) accept user's typing, text selections, text scrolling, support copy/paste operations, etc. The behavior can be strictly specialized (like mentioned edit controls), more general (e.g. dialog boxes) or purely general (like Xeffort windows, having default class named "XWndClass"). In Xeffort, dealing with window classes is mostly hidden from the programmer, because using the general-purpose XWndClass (and, equally frequently, default system dialog class) provides enough capabilities for most applications.

In Xeffort, every window in the application (except controls, which are handled specially) should be represented by a variable of type X_WINDOW. Contents of type X_WINDOW are opaque, i.e. the programmer should not care about them. The programmer should create a required number of X_WINDOWs either on startup (XInit routine) or "on the fly", using XCreateWindow, XLoadDialog, or one of XCreate*App routines. One of windows in the application has the special property of being "main" (or frame), and have the name XW_FRAME (this variable is declared within Xeffort code).

Programmer-defined aspects of window behavior are defined by writing message handlers, which define how individual windows respond to events (messages).

Window Hierarchy

Windows maintains a tree-like hierarchy of windows. The root of the hierarchy is desktop window. The desktop contains main windows of running applications. These windows are referred as to top-level windows. Each top-level window can have none or more owned windows, which in turn can have their owned windows. When a window is destroyed, all its owned windows are automatically destroyed, so there's no need to destroy every window separately.

The three key styles which dictate behavior of windows regarding to hierarchy are:

  • WS_OVERLAPPED windows are always top-level windows. Their owner is always the desktop. Usually, an application has only one overlapped window - the main window (XW_FRAME in Xeffort terminology) (although some applications, such as Internet Explorer, create more overlapped windows within the same process). These windows usually have a frame (WS_THICKFRAME) and caption (WS_CAPTION). They can have menus.

  • WS_POPUP windows always remain on top of their owner. They can be moved anywhere on screen and activated separately of their owner. Popup windows can (but need not) have a caption. Dialogs usually have this style. They can have menus.

  • WS_CHILD windows can appear only on the client area of their owner. Their parent window clips their contents when (a part of) child window is outside their client area. Child windows (except for special-cased MDI child windows) cannot be activated separately of their parent; they should not have caption bar. Controls (edit boxes, buttons etc.) are a special kind of child windows which "talk to" their parent using WM_COMMAND message. Child windows cannot have menus

WS_OVERLAPPED windows and ownerless WS_POPUP windows behave much the same. Thus, both of them can serve as main application windows. Usually, when the main window is overlapped, the application is referred to as SDI or MDI, and when it is a WS_POPUP, it is referred to as dialog-based.

Dialogs and Controls

A control is a window that used to obtain a specific piece of information from the user, such as the name of a file to open or the desired point size of a text selection. Although controls are windows, their behavior is so well predefined that it is seldom necessary to treat them as such; thus, it is not necessary to define X_WINDOW variables for them. The controls are identified by their numeric identifier (ID) and the X_WINDOW variable describing their parent window. Module XFTCtrl is used for handling of controls.

Dialogs are windows whose main purpose is to contain controls. Dialogs are windows, and it is difficult to make a precise distinction when a window can be referred to as a dialog and when not. Layout of dialogs and their controls is usually predefined in resource editor. Thus, about the only difference between X_WINDOWs and dialogs is how they start their life: the former are created using XCreateWindow and the latter using XLoadDialog routine. All XFTWnd routines are applicable to dialogs as well. Module XFTDialog contains routines for dialog-specific operations.

Window Events and Messages

Every event that occurs in the system is sent by Windows to an application's windows in form of a message. Every event/message that arrives to a window must be handled in some way. Usually, the system or Xeffort library handle events in a logical manner, so there's nothing the programmer should do about them. However, it is programmer's duty to define a (small) subset of events that are important for the application and write handler routines for such events.

Most of the code in a full Xeffort application consists of message handlers. Under Xeffort, message handler is a programmer-defined routine (function or subroutine) of predefined prototype. The message handler is registered for your window using XSetHandler routine.

Window Messages Overview page describes message handling mechanisms, and the Message Handlers Reference lists all possible events that an applicaton can be interested in.

Reference


XFTWND: Window Bindings

XFTWND: Window Bindings

As described in Window Events, it is possible to register routines which handle events in Xeffort Windows. However, it is possible only if the window is bound with Xeffort framework. Xeffort framework installs Xeffort window procedure (see FXWindowProc in XFTWND.f90) which checks whether the programmer has registered the handler for given event and calls it if so; otherwise, it passes the message further to default processing.

Xeffort can be used in any kind of application (Win32, Standard Graphics, QuickWin, console) and can easily bind windows already created using previous code in that application. A window can be bound to Xeffort framework (becoming a Xeffort window) using XCreateWindow or XBindWindow routines. Thus, X_WINDOWs can be divided into three types: "native", "bound" and "unbound". Native and bound windows can have registered event handlers via XSetHandler, and can act as parents of controls created using XCtlCreate. Handlers cannot be registered for unbound windows, neither they can have Xeffort-handled controls.

XIsWindow routine can be used to query the binding status of the window.

Native Xeffort Windows

Native Xeffort windows are created using XCreateWindow or XLoadDialog functions. They start their life with Xeffort window procedure (FXWindowProc) as the central place from where messages are decoded and dispatched to handlers registered by the programmer.

There's a slight further classification of native Xeffort windows. If sClassName argument of XCreateWindow is ommitted, Xeffort creates a window of class "XFTWindow", whose "native" procedure is FXWindowProc. Otherwise, if sClassName is present, it creates a Xeffort window which behaves the same as window of given class; however, that behavior can be modified using XSetHandler.

Bound Xeffort Windows

Bound Xeffort Windows begin their life in some other way; in the beginning these windows are created using CreateWindow API somewhere (as any window ultimately has to be). Bound Xeffort windows can be created in a Win32 application, QuickWin application or by any other library. However, Xeffort can bind windows created by other libraries by installing its FXWindowProc in window procedure chain using subclassing technique. XBindWindow routine converts windows handle to a X_WINDOW structure, which can normally be passed latter to all Xeffort routines, including XSetHandler.

Note that controls (although controls are windows) created by Xeffort are normally not Xeffort Windows. The reason for that is that Xeffort binding involves a small memory and performance overhead, and modifying behavior of controls is seldom necessary. However, a control window can be bound using XBindWindow if it's necessary to modify (subclass) the control.

Unbound Xeffort Windows

Unbound Xeffort Windows also begin their life in some other way, but they're not handled by Xeffort framework. Unbound Xeffort Windows are obtained using XGetWindow routine. Basically, XGetWindow just performs a "cast" from hWnd to X_WINDOW structure, whose other members are empty. XGetWindow and unbound windows in general are useful where a Xeffort routine expects a X_WINDOW structure but the resulting window is not bound. This is usually case for windows which act as parents, other windows which receive focus etc. Unbound windows cannot have registered handlers, nor they can have Xeffort-handled controls.


XFTWND: Design Considerations

XFTWND: Design Considerations

As said in the overview, it is required that every instance of a Xeffort window is represented by a unique instance of a X_WINDOW structure. In the X_WINDOW structure, Xeffort keeps, among other things, window handle and a lookup table for message and command handlers. Thus, since a X_WINDOW structure is passed to handler routines, it must be ensured that every change made in a handler routine is reflected properly to the window. Xeffort does that by associating address of X_WINDOW structure to the window itself, using SetProp API. As a consequence, address of the X_WINDOW structure passed to the handler must be the same as the address of X_WINDOW structure that was passed to XCreateWindow or XMDICreate ¹).

A window shouldn't be represented by two X_WINDOW structures (since changes applied to a copy will not reflect to the original one). Also, one X_WINDOW structure must not be used to create two live windows (since the one first created will lose its binding). It is the programmer's responsibility to ensure 1:1 mapping between the window and its X_WINDOW, and that lifetime of X_WINDOW variable is equal or longer than the one of its window. If this condition is not satisfied, it may result in unpredictable behavior. Xeffort library will raise one of the following exceptions:

XEXCEPT_INVALID_XWND (= #E00000E2) | if it enters FXWindowProc but the window is not associated.
XEXCEPT_INVALID_HANDLE (= #E00000E1) | if it detects mismatch between X_WINDOW and the window itself.
EXCEPTION_ACCESS_VIOLATION (=#C0000005) | if the original X_WINDOW is destroyed before the window itself

In many cases, it is not complicated to ensure the requirement above. If the application creates a limited number of windows, it can maintain a set of individual scalar X_WINDOWs, or an array (static or allocatable) or a linked list of X_WINDOW structures and use it appropriately. However, in cases where number of windows which will be created is not known in advance, it is recommended to use the scheme described in the sequel.

Maintaining a list of X_WINDOWs

When there's an unknown (and potentially infinite) number of Xeffort windows to be maintained, the application can make the X_WINDOW structure (possibly as part of another, larger derived type) a POINTER and ALLOCATE is whenever the window is to be created. Since memory allocated for the pointer's target should be released (otherwise memory leak would occur), the pointer must be DEALLOCATEd on window destruction. However, in order to do that, the contents of the pointer must be recaptured. The ideal place for keeping the pointer is the arbitrary data which can be associated with the window using XSetWindowData, XGetWindowData.

Consider the following code snippet from MDI application generated by the Xeffort Application Wizard:

TYPE T_USERDATA
TYPE(X_WINDOW):: xWnd
...
END TYPE T_USERDATA
...
!=====================================================================
SUBROUTINE CreateChild()

TYPE(T_USERDATA), POINTER:: UD
...
ALLOCATE(UD)
IF (XMDICreate(UD%xWnd, sWindowTitle)) THEN
 !Associate a POINTER-based structure with the window
bSt = XSetWindowData(UD%xWnd, UD)
bSt = XSetHandler(UD%xWnd, WM_NCDESTROY, xChild_OnNcDestroy)
...
END IF

END SUBROUTINE CreateChild

The ideal place to release the allocated memory is the WM_NCDESTROY handler, since it is the very last message sent to the window. This ensures that the X_WINDOW, once released, will never be tried to be accessed by Xeffort framework (resulting in an Access Violation):

!=======================================================================
LOGICAL FUNCTION xChild_OnNcDestroy(xWnd)

TYPE(X_WINDOW):: xWnd

TYPE(T_USERDATA), POINTER:: UD
INTEGER:: iSt

!Recapture the pointer to the structure used to create original window
iSt = XGetWindowData(xWnd, UD)
!Remove the association with the window
iSt = XFreeWindowData(xWnd)

!Clean up the xWnd structure.
CALL XFreeWindow(xWnd)
!Free the memory. This xWnd will never be accessed again.
DEALLOCATE(UD)

xChild_OnNcDestroy = .FALSE.

END FUNCTION xChild_OnNcDestroy

¹) There are only two additional routines which can be used to create a X_WINDOW structure where there (potentially) wasn't any: XGetWindow and XBindWindow, but they return a pointer to the X_WINDOW structure.


XFTWND: Window Styles

Window Styles and Extended Styles

Window Styles

Style | Meaning
WS_BORDER | Creates a window that has a thin-line border.
WS_CAPTION | Creates a window that has a title bar (includes the WS_BORDER style).
WS_CHILD | Creates a child window. This style cannot be used with the WS_POPUP style.
WS_CHILDWINDOW | Same as the WS_CHILD style.
WS_CLIPCHILDREN | Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used when creating the parent window.
WS_CLIPSIBLINGS | Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, the WS_CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. If WS_CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.
WS_DISABLED | Creates a window that is initially disabled. A disabled window cannot receive input from the user.
WS_DLGFRAME | Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.
WS_GROUP | Specifies the first control of a group of controls. The group consists of this first control and all controls defined after it, up to the next control with the WS_GROUP style. The first control in each group usually has the WS_TABSTOP style so that the user can move from group to group. The user can subsequently change the keyboard focus from one control in the group to the next control in the group by using the direction keys.
WS_HSCROLL | Creates a window that has a horizontal scroll bar.
WS_ICONIC | Creates a window that is initially minimized. Same as the WS_MINIMIZE style.
WS_MAXIMIZE | Creates a window that is initially maximized.
WS_MAXIMIZEBOX | Creates a window that has a Maximize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_MINIMIZE | Creates a window that is initially minimized. Same as the WS_ICONIC style.
WS_MINIMIZEBOX | Creates a window that has a Minimize button. Cannot be combined with the WS_EX_CONTEXTHELP style. The WS_SYSMENU style must also be specified.
WS_OVERLAPPED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_TILED style.
WS_OVERLAPPEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_TILEDWINDOW style.
WS_POPUP | Creates a pop-up window. This style cannot be used with the WS_CHILD style.
WS_POPUPWINDOW | Creates a pop-up window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles must be combined to make the window menu visible.
WS_SIZEBOX | Creates a window that has a sizing border. Same as the WS_THICKFRAME style.
WS_SYSMENU | Creates a window that has a window-menu on its title bar. The WS_CAPTION style must also be specified.
WS_TABSTOP | Specifies a control that can receive the keyboard focus when the user presses the TAB key. Pressing the TAB key changes the keyboard focus to the next control with the WS_TABSTOP style.
WS_THICKFRAME | Creates a window that has a sizing border. Same as the WS_SIZEBOX style.
WS_TILED | Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_OVERLAPPED style.
WS_TILEDWINDOW | Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_OVERLAPPEDWINDOW style.
WS_VISIBLE | Creates a window that is initially visible.
WS_VSCROLL | Creates a window that has a vertical scroll bar.

Extended Styles

Style | Meaning
WS_EX_ACCEPTFILES | Specifies that a window created with this style accepts drag-drop files.
WS_EX_APPWINDOW | Forces a top-level window onto the taskbar when the window is minimized.
WS_EX_CLIENTEDGE | Specifies that a window has a border with a sunken edge.
WS_EX_CONTEXTHELP | Includes a question mark in the title bar of the window. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a WM_HELP message. The child window should pass the message to the parent window procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the child window. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
WS_EX_CONTROLPARENT | Allows the user to navigate among the child windows of the window by using the TAB key.
WS_EX_DLGMODALFRAME | Creates a window that has a double border; the window can, optionally, be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.
WS_EX_LEFT | Window has generic “left-aligned” properties. This is the default.
WS_EX_LEFTSCROLLBAR | If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the vertical scroll bar (if present) is to the left of the client area. For other languages, the style is ignored and not treated as an error.
WS_EX_LTRREADING | The window text is displayed using Left to Right reading-order properties. This is the default.
WS_EX_MDICHILD | Creates an MDI child window.
WS_EX_NOPARENTNOTIFY | Specifies that a child window created with this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.
WS_EX_OVERLAPPEDWINDOW | Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_PALETTEWINDOW | Combines the WS_EX_WINDOWEDGE, WS_EX_TOOLWINDOW, and WS_EX_TOPMOST styles.
WS_EX_RIGHT | Window has generic “right-aligned” properties. This depends on the window class. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored and not treated as an error.
WS_EX_RIGHTSCROLLBAR | Vertical scroll bar (if present) is to the right of the client area. This is the default.
WS_EX_RTLREADING | If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the window text is displayed using Right to Left reading-order properties. For other languages, the style is ignored and not treated as an error.
WS_EX_STATICEDGE | Creates a window with a three-dimensional border style intended to be used for items that do not accept user input.
WS_EX_TOOLWINDOW | Creates a tool window; that is, a window intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font. A tool window does not appear in the taskbar or in the dialog that appears when the user presses ALT+TAB. If a tool window has a system menu, its icon is not displayed on the title bar. However, you can display the system menu by right-clicking or by typing ALT+SPACE.
WS_EX_TOPMOST | Specifies that a window created with this style should be placed above all non-topmost windows and should stay above them, even when the window is deactivated. To add or remove this style, use the XSetWindowPos function.
WS_EX_TRANSPARENT | Specifies that a window created with this style is to be transparent. That is, any windows that are beneath the window are not obscured by the window. A window created with this style receives WM_PAINT messages only after all sibling windows beneath it have been updated.
WS_EX_WINDOWEDGE | Specifies that a window has a border with a raised edge.
XS_EX_DBLBUFFERED | This is a special style used only by Xeffort library. Xeffort Windows with this style use double-buffering when receiving a WM_PAINT message. See considerations under WM_PAINT entry.


XFTWND Reference

XFTWND Reference

Overview

Window Management

XBindWindow

XCreateWindow

XDestroyWindow

XGetWindow

XIsWindow

XUnbindWindow

Messages and Handlers

Message Handlers Reference

XPostMessage

XSendMessage

XSetCommand

XSetHandler

Window Position

XClient2Screen

XEndMoveWindows

XEnableWindow

XGetCanvas

XGetClientRect

XGetWindowPos

XGetWindowRect

XMoveWindow

XScreen2Client

XSetCanvas

XSetWindowPos

XShowWindow

XSizeWindow

Window Properties

XGetWindowStyle

XSetCursor

XSetWindowIcon

XSetWindowTitle

XSetWindowStyle

XStdCursor

User-Defined Properties

XFreeWindowData

XGetWindowData

XFTWND Types

X_WINDOW


X_WINDOW

X_WINDOW

X_WINDOW structure describes a window.

TYPE X_WINDOW
    INTEGER:: hWnd = 0
    ...
END TYPE X_WINDOW

Members

hWnd

Windows handle of the window.

See Also

XCreateWindow, XBindWindow, XGetWindow, Window Bindings, Design Considerations

Module

XFTWnd.f90


XBeginMoveWindows

XBeginMoveWindows

XBeginMoveWindows function prepares for moving/sizing of several windows simultaneously. If there's need to resize several windows at once, usage of XBeginMoveWindows/XSetWindowPos/XEndMoveWindows does it at once without flicker.

LOGICAL FUNCTION XBeginMoveWindows(nWindows)

INTEGER, OPTIONAL, INTENT(IN)::  nWindows

Arguments

[nWindows]

Number of windows to be moved. If known in advance, it increases efficiency of moving operation.

Return Value

If successful, the function returns .TRUE.

Remarks

Every XBeginMoveWindows call must be terminated by a matching XEndMoveWindows call. XBeginMoveWindows fails if called twice (but does not produce harmful effects).

See Also

XSetWindowPos, XEndMoveWindows

Wrapped APIs

BeginDeferWindowPos

Module

XFTWND.f90


XBindWindow

XBindWindow

XBindWindow function binds a window created by means other than XCreateWindow to Xeffort framework and returns a X_WINDOW structure representing the window. Returned structure can be used latter for any Xeffort routine.

LOGICAL FUNCTION XBindWindow(hWnd, xWnd)

INTEGER, INTENT(IN)::         hWnd
TYPE(X_WINDOW), POINTER::     xWnd

Arguments

hWnd
Windows handle of the window. For QuickWin, that handle can be retrieved using GETHWNDQQ. Win32 APIs EnumChildWindows, EnumThreadWindows, FindWindow, GetWindow can also be used to retrieve window handles of interest.

xWnd
 X_WINDOW structure representing the Xeffort window. On input, must be a NULLIFYed pointer. If the window has already been bound or is a native Xeffort window, it will point to the structure previously used to bind or create the window. If the window was not bound, a new structure will be allocated. It can be freed by DEALLOCATEing the pointer after the window has been destroyed or by calling XUnbindWindow.

Return Value

If successful, the return value is .TRUE. ,otherwise, .FALSE. The function may fail if the window belongs to another process or if hWnd is an invalid handle (of a non-existing window). The function will also fail (without memory leaks) if xWnd is not NULL() on input.

Remarks

The calling application is responsible for DEALLOCATEing the pointer after the window is destroyed. It must not deallocate it before that, otherwise Xeffort library will raise XEXCEPT_INVALID_XWND exception as soon as the window is accessed. Please see Design Considerations page.

See Also

XGetWindow, XCreateWindow, XIsWindow, XSetHandler, XUnbindWindow

Wrapped APIs

SetWindowLong

Module

XFTWND.f90


XFreeWindow

XFreeWindow

XFreeWindow routine cleans up the contents of the X_WINDOW structure, i.e. it frees up all resources that Xeffort library allocated in the structure and breaks the binding between the window and X_WINDOW structure, but does not destroy the window. This function should be used only for a dead or dying window (see WM_NCDESTROY), as it breaks all the Xeffort bindings with the window object. See remarks below and design considerations.

SUBROUTINE XFreeWindow(xWnd)

TYPE(X_WINDOW), INTENT(INOUT)::           xWnd

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

Remarks

This function should be used only in situations where the X_WINDOW structure is embedded within another structure which is being deallocated. Such a situation occurs e.g. in wizard-generated MDI application, where pointer to user-defined structure should be deallocated on child window's WM_NCDESTROY, but the X_WINDOW itself is not freed. XDestroyWindow and XUnbindWindow internally call XFreeWindow, and it's also called by default Xeffort WM_NCDESTROY handler.

See Also

XDestroyWindow, XUnbindWindow, WM_NCDESTROY

Module

XFTWND.f90


XClient2Screen

XClient2Screen

XClient2Screen function converts coordinates of a single physical point from client-based coordinates of given window to screen-based coordinates

XClient2Screen is generic name for two routines, first converting coordinates in scalar form, second in form of X_POINT structures. They are accessible only under generic name XClient2Screen.

LOGICAL
FUNCTION  PXClient2Screen_1(xWnd, iXWnd, iYWnd, iXScreen, iYScreen)

TYPE(X_WINDOW), INTENT(IN)::      xWnd
INTEGER, INTENT(IN)::
iXWnd
INTEGER, INTENT(IN)::
iYWnd
INTEGER, OPTIONAL, INTENT(OUT)::  iXScreen
INTEGER, OPTIONAL, INTENT(OUT)::  iYSCreen

LOGICAL FUNCTION
 PXClient2Screen_2(xWnd, xPTWnd, xPTScreen)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
TYPE(X_POINT), INTENT(IN)::      xPTWnd
TYPE(X_POINT), INTENT(OUT)::     xPTScreen

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose coordinates are to be converted.

iXWnd/ iYWnd, xPTWnd

A point in client coordinate system of given xWnd.

iXScreen/ iYScreen, xPTScreen

Converted coordinate in screen-coordinate system.

See Also

XScreen2Client, XClient2View (XFTGDI)

Module

XFTWND.f90


XCreateWindow

XCreateWindow

XCreateWindow function creates a window. It specifies the window class, window title, window style, and (optionally) the initial position and size of the window. The function also specifies the window’s parent or owner, if any, and the window’s menu.

LOGICAL
FUNCTION XCreateWindow(xWnd, xParent, iStyle, sWindowName, iExStyle,                       iX, iY, iWidth, iHeight,
xMenu, sClassName, ID)

TYPE(X_WINDOW), INTENT(OUT)::             xWnd
TYPE(X_WINDOW), INTENT(IN)::              xParent
INTEGER, INTENT(IN)::
iStyle
CHARACTER(*), OPTIONAL, INTENT(IN)::      sWindowName
INTEGER, OPTIONAL, INTENT(IN)::           iExStyle
INTEGER, OPTIONAL, INTENT(IN)::           iX, iY
INTEGER, OPTIONAL, INTENT(IN)::           iWidth, iHeight
TYPE(X_MENU), OPTIONAL, INTENT(INOUT)::   xMenu
CHARACTER*(*), OPTIONAL, INTENT(IN)::     sClassName
INTEGER, OPTIONAL, INTENT(IN)::           ID

Arguments

xWnd
 X_WINDOW structure representing newly created window.

xParent
 X_WINDOW structure representing parent of the window. For top-level (main application) window, use XGetWindow() with empty argument-list, which represents the desktop window. See also XCreateApp.

iStyle
An OR combination of window styles. Window styles can be common or class-specific.

[sWindowName]
Title of the window. If not present, empty string is used.

[iExStyle]
An OR combination of window extended styles. Extended styles define additional properties of the window. If absent, 0 is used.

[iX, iY]
Position of the upper-left corner of the window, in pixels. If absent, (0,0) is used. The position is relative to upper-left corner of the screen for overlapped and popup windows, and relative to parent window's client area origin for child windows.

[iWidth, iHeight]
Width and height of the window, in pixels. If absent, value of CW_USEDEFAULT is used, indicating that the system should pick window dimensions.

[xMenu]
Type X_MENU describing the menu associated with the window. The menu can be associated later using XFTMENU routines. If absent, the window is created without initial menu. This argument is used only if iStyle does not contain WS_CHILD, as child windows can not have menu; otherwise, it is ignored.

[sClassName]
Name of a registered window class. Window class defines basic properties of a (set of) window and is identified by its name. Xeffort doesn't contain wrappers for RegisterClass API; all native Xeffort windows are of class named Xeffort_CLASSNAME="XWndClass". An application seldom needs to use windows of classes other than system ones. Examples of system classes are buttons and edit boxes (which are handled by XFTCTRL module anyway). MDI child windows handled by Xeffort should, however, have sClass argument set to "MDIChild".

[ID]
Control identifier of the window. This argument is used only if iStyle contains WS_CHILD, as only child windows can have identifiers; otherwise, it is ignored. This argument is useful, for example, when creating a control not directly supported by XFTCTRL; this identifier is used to distinguish the control in its Command handler.

Return Value

If successful, the return value is .TRUE.. Otherwise, return value is .FALSE.

Remarks

Lifetime of the X_WINDOW variable should be at least as long as lifetime of the window itself, i.e. until window is destroyed using XDestroyWindow.

See Also

XBindWindow, XGetWindow, XDestroyWindow, XSetHandler

Wrapped APIs

CreateWindowEx

Module

XFTWND.f90


XDestroyWindow

XDestroyWindow

XDestroyWindow function destroys the window, frees any resources associated with it, and clears up the XWnd structure. All child windows contained in the given window are destroyed as well.

LOGICAL FUNCTION XDestroyWindow(xWnd)

TYPE(X_WINDOW)::         xWnd

Arguments

xWnd
 X_WINDOW structure representing the Xeffort window to be destroyed.

Return Value

If the function succeeds, the return value is .TRUE. Otherwise, the return value is .FALSE.

See Also

XBindWindow, XGetWindow, XCreateWindow, XIsWindow, XUnbindWindow

Module

XFTWND.f90


XEnableWindow

XEnableWindow

XEnableWindow function enables or disables a window. A disabled window does not receive any mouse or keyboard input and cannot be activated.

LOGICAL FUNCTION
XEnableWindow(xWnd, bEnable)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
LOGICAL, INTENT(IN)::
bEnable

Arguments

xWnd

X_WINDOW structure describing the window.

bEnable

New enabled state of the window. (.TRUE. to enable or .FALSE. to disable the window)

Return Value

The previous enabled state of the window.

Remarks

If the enabled state of a window is changing, a WM_ENABLE message is sent before the XEnableWindow function returns. If a window is already disabled, all its child windows are implicitly disabled, although they are not sent a WM_ENABLE message.

A window must be enabled before it can be activated. For example, if an application is displaying a modeless dialog box and has disabled its main window, the application must enable the main window before destroying the dialog box. Otherwise, another window will receive the keyboard focus and be activated. If a child window is disabled, it is ignored when the system tries to determine which window should receive mouse messages.

By default, a window is enabled when it is created. To create a window that is initially disabled, an application can specify the WS_DISABLED style in the XCreateWindow function. To query enabled/disabled state of the window, use XIsWindow(xWnd, WS_DISABLED).

See Also

XIsWindow, WM_ENABLE

Wrapped APIs

EnableWindow

Module

XFTWND.f90


XEndMoveWindows

XEndMoveWindows

XEndMoveWindows function ends the moving/sizing of several windows simultaneously that was initiated by XBeginMoveWindows, and updates positions of all affected windows.

LOGICAL FUNCTION XEndMoveWindows()

Return Value

If successful, the function returns .TRUE.

Remarks

Every XBeginMoveWindows call must be terminated by a matching XEndMoveWindows call. XEndMoveWindows fails if XBeginMoveWindows was not called.

See Also

XSetWindowPos, XBeginMoveWindows

Wrapped APIs

EndDeferWindowPos

Module

XFTWND.f90


XFreeWindowData

XFreeWindowData

XFreeWindowData removes the association of application-defined data with the window, previously established using XSetWindowData. The application is responsible for removing all entries it added, and it must be done before the window is destroyed. Failure to do so result in small memory leaks. XFreeWindowData only breaks the association; it is application's responsibility to do the deallocation if the original data were ALLOCATEd.

LOGICAL FUNCTION XFreeWindowData(xWnd, sDataID)

TYPE(X_WINDOW), INTENT(IN)::           xWnd
CHARACTER(*), OPTIONAL, INTENT(IN)::   sDataID

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

[sDataID]

A unique (case-insensitive) string which represents the property. If absent, Xeffort library removes the association under "XDATA" entry.

Return Value

If successful, the function returns .TRUE.

See Also

XSetWindowData, XGetWindowData

Wrapped APIs

RemoveProp

Module

XFTWND.f90


XGetCanvas

XGetCanvas

XGetCanvas routine returns the dimensions of the window's current canvas set by XSetCanvas , and optionally the position of window's scrollbars, which represent the offset of canvas origin from window client area origin.

LOGICAL FUNCTION
XGetCanvas(xWnd, iCanvasX, iCanvasY, iPosX, iPosY)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
INTEGER, INTENT(OUT)::
iCanvasX, iCanvasY
INTEGER, OPTIONAL, INTENT(OUT):: iPosX, iPosY

Arguments

xWnd
 X_WINDOW structure representing the Xeffort window whose canvas is retrieved.

iCanvasX, iCanvasY
X and Y dimensions of the canvas, in pixels. Value of zero indicates that the window has no set up canvas for appropriate dimension.

[iPosX], [iPosY]
Current position of horizontal and vertical scrollbar respectively. If the dimensions are such that the scrollbar is not visible, the appropriate value is zero.

Return Value

If the function succeeds, return value is .TRUE.

See Also

XScrollbarGet, XSetCanvas

Module

XFTWND.f90


XGetClientRect

XGetClientRect

XGetClientRect function returns the size of window's client rectangle

LOGICAL FUNCTION XGetClientRect(xWnd, iWidth, iHeight)

TYPE(X_WINDOW), INTENT(IN)::   xWnd
INTEGER, INTENT(OUT)::          iWidth, iHeight

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

iWidth, iHeight

Width and height of the client area, in pixels.

Return Value

If successful, the function returns .TRUE.

Wrapped APIs

GetClientRect

Module

XFTWND.f90


XGetWindow

XGetWindow

XGetWindow function converts a Win32 window handle to a X_WINDOW structure. Returned structure can be used for various Xeffort functions which expect X_WINDOW as input, but in general cannot be used as argument to XSetHandler, XSetCommand or XCtlCreate functions (unless it is the handle of an already bound Window ).

FUNCTION XGetWindow(hWnd) RESULT(xWnd)

TYPE(X_WINDOW), POINTER::        xWnd
INTEGER, OPTIONAL, INTENT(IN)::  hWnd

Arguments

hWnd
Windows handle of the window. If not present, the returned window represents the desktop window. For QuickWin, that handle can be retrieved using GETHWNDQQ. Win32 APIs EnumChildWindows, EnumThreadWindows, FindWindow, GetWindow etc. can also be used to retrieve window handles of interest.

Return Value

Pointer to a X_WINDOW structure representing the Xeffort window. If the window has already been bound or is a native Xeffort window, it will point to the same structure which is previously used to bind or create the window, i.e. the result will be an Xeffort window. If the window is an unbind window, it will point to a (static) structure describing the window. If hWnd is an invalid handle, the returned pointer is NULL().

Remarks

XGetWindow never allocates memory for its result, so it cannot cause any memory leaks.

See Also

XBindWindow, XCreateWindow, XIsWindow, XSetHandler

Module

XFTWND.f90


XGetWindowData

XGetWindowData

XGetWindowData retrieves the application-defined data previously associated with the window using XSetWindowData. An application can associate and retrieve an arbitrary number of data sets using different sDataID strings.

LOGICAL FUNCTION XGetWindowData(xWnd, lpData, sDataID)

TYPE(X_WINDOW), INTENT(IN)::           xWnd
!DEC$ATTRIBUTES NO_ARG_CHECK::         lpData
WHATEVER, POINTER::                    lpData
CHARACTER(*), OPTIONAL, INTENT(IN)::   sDataID

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

lpData

Scalar pointer of any type. On output, points to the variable which was previously associated with the window using XSetWindowData. If the function fails, the pointer is NULL().

[sDataID]

A unique (case-insensitive) string which represents the property. If absent, Xeffort library retrieves the data, if any, stored under default entry ("XDATA").

Return Value

If successful, the function returns .TRUE. Otherwise, the return value is .FALSE. and lpData is NULL().

Remarks

The function returns the pointer to the same variable which was used in call to XSetWindowData. On input, lpData pointer should (but does not have to) be NULL. Since XGetWindowData associates the pointer, the application should ensure that any target previously associated with the lpData pointer, if any, is available for deallocation (otherwise, memory leaks can occur).

The application must free every added entry when it is no longer needed by calling XFreeWindowData.

Current implementation of XGetWindowData is based on CVF6.6 NO_ARG_CHECK attribute and CVF scalar pointer format (=C void*).

See Also

XSetWindowData, XFreeWindowData

Wrapped APIs

GetProp

Module

XFTWND.f90


XGetWindowPos

XGetWindowPos

XGetWindowPos function returns the window position and size. If the window is minimized or maximized, it returns the restored position and size. Compare XGetWindowRect.

LOGICAL FUNCTION XGetWindowPos(xWnd, iX1, iY1, iWidth, iHeight, iShow, bParent)

TYPE(X_WINDOW), INTENT(IN)::            xWnd
INTEGER, INTENT(OUT)::         		iX1, iY1
INTEGER, OPTIONAL, INTENT(OUT)::        iWidth, iHeight
INTEGER, OPTIONAL, INTENT(OUT)::        iShow
LOGICAL, OPTIONAL, INTENT(IN)::  	bParent

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

iX1, iY1

Position of top-left corner of the window, in pixels. By default, in screen coordinates (see bParent argument below).

[iWidth, iHeight]

Window width and height, in pixels.

[iShow]

Specifies the current show state of the window. This member can be one of the following values:
Value | Meaning
SW_HIDE | Hides the window and activates another window.
SW_MINIMIZE | Minimizes the specified window and activates the top-level window in the system's list.
SW_RESTORE | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position (same as SW_SHOWNORMAL).
SW_SHOW | Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED | Activates a window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates a window and displays it as an icon.
SW_SHOWMINNOACTIVE | Displays a window as an icon. The active window remains active.
SW_SHOWNA | Displays a window in its current state. The active window remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position (same as SW_RESTORE).

[bParent]

If present and .TRUE., the returned coordinates for child windows will be expressed in coordinates relative to parent's client area origin. Otherwise, they will be expressed in screen coordinates. For popup and overlapped windows, this argument is ignored and coordinates are always screen-relative.

Return Value

If successful, the function returns .TRUE.

See Also

XGetWindowRect, XMoveWindow, XSizeWindow, XShowWindow, XSetWindowPos

Wrapped APIs

GetWindowPlacement, ScreenToClient

Module

XFTWND.f90


XGetWindowRect

XGetWindowRect

XGetWindowRect function returns the window position, and size. If the window is maximized, it returns its maximized dimensions. If the window is minimized, it returns position of its icon.

LOGICAL FUNCTION XGetWindowRect(xWnd, iX1, iY1, iWidth, iHeight, bParent)

TYPE(X_WINDOW), INTENT(IN)::            xWnd
INTEGER, INTENT(OUT)::         		iX1, iY1
INTEGER, OPTIONAL, INTENT(OUT)::        iWidth, iHeight
LOGICAL, OPTIONAL, INTENT(IN)::  	bParent

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

iX1, iY1

Position of top-left corner of the window, in pixels. By default, in screen coordinates (see bParent argument below).

[iWidth, iHeight]

Window width and height, in pixels.

[bParent]

If present and .TRUE., the returned coordinates for child windows will be expressed in coordinates relative to parent's client area origin. Otherwise, they will be expressed in screen coordinates. For popup and overlapped windows, this argument is ignored and coordinates are always screen-relative.

Return Value

If successful, the function returns .TRUE.

See Also

XGetWindowPos, XMoveWindow, XSizeWindow, XShowWindow, XSetWindowPos

Wrapped APIs

GetWindowRect, ScreenToClient

Module

XFTWND.f90


XSetWindowData

XGetWindowStyle

XGetWindowStyle retrieves the window's style, extended style, or class style.

INTEGER FUNCTION XGetWindowStyle(xWnd, iType)

TYPE(X_WINDOW), INTENT(IN)::           xWnd
INTEGER, INTENT(IN)::                  iStyle

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose style is queried.

[iType]

One of the following constants, which determines which kind of style is requested

XWST_STYLE | Window style (default)
XWST_EXSTYLE | Extended style
XWST_CLASS | Class style

Return Value

If successful, the function returns window styles of appropriate type. If the function fails (because xWnd is invalid), the return value is zero.

See Also

XSetWindowStyle, XIsWindow

Wrapped APIs

GetWindowLong, GetClassLong

Module

XFTWND.f90


XIsWindow

XIsWindow

XIsWindow is used for querying various window properties and relationships between two windows.

LOGICAL FUNCTION XIsWindow(xWnd, nWhat, xWnd2)

TYPE(X_WINDOW), INTENT(IN)::             xWnd
INTEGER, INTENT(IN)::                    nWhat
TYPE(X_WINDOW), OPTIONAL, INTENT(IN)::   xWnd2

Arguments

xWnd
 X_WINDOW structure representing the window.

nWhat
One of the following parameters, describing the queried property:

Value | Meaning
MINIMIZED | Returns .TRUE. if the window is minimized.
MAXIMIZED | Returns .TRUE. if the window is maximized
XEFFORT_WINDOW or XFT_WINDOW | Returns .TRUE. if the window is a bound Xeffort window
WINDOW | Returns .TRUE. if the window is valid (created and not destroyed)
CHILDOF | Returns .TRUE. if the window is descendant of xWnd2. A child window is the direct descendant of a specified parent window if that parent window is in the chain of parent windows.
[default] | If nWhat is none of the above parameters, it is regarded as a combination of window styles. The function returns .TRUE. if all of queried styles are present as a bit-combination in the actual window's style.

xWnd2
 X_WINDOW structure representing the window which is related with xWnd. It is used only if nWhat has value CHILDOF.

Return Value

The return value is .TRUE. or .FALSE. according to the table above.

See Also

XCreateWindow, XBindWindow, XGetWindow

Wrapped APIs

IsWindow, IsChild, IsIconic, IsZoomed, GetWindowLong

Module

XFTWND.f90


XMoveWindow

XMoveWindow

XMoveWindow function sets the window position.

LOGICAL FUNCTION XMoveWindow(xWnd, iX, iY)

TYPE(X_WINDOW), INTENT(IN)::   xWnd
INTEGER, INTENT(IN)::          iX, iY

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

iX, iY

Position of top-left corner of the window, in pixels. For child windows, it is expressed as offset from origin of parent's client area. For popup and overlapped windows, it is expressed in screen coordinates.

Return Value

If successful, the function returns .TRUE.

See Also

XSizeWindow, XShowWindow, XGetWindowPos, XSetWindowPos

Wrapped APIs

SetWindowPos

Module

XFTWND.f90


XPostMessage

XPostMessage

The XPostMessage function places (posts) a message in the message queue associated with the thread that created the specified window and then returns immediately, without waiting for the thread to process the message.

INTEGER FUNCTION XPostMessage(xWnd, Msg, wParam, lParam)

TYPE(X_WINDOW)::            xWnd
INTEGER, INTENT(IN)::       Msg, wParam, lParam

Arguments

xWnd

X_WINDOW structure describing window to which the message is sent.

Msg

Message code.

wParam

First message parameter. The meaning depends on message code.

lParam

The second message parameter. The meaning depends on message code.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

See Also

Window Events, XSendMessage

Wrapped APIs

PostMessage

Module

XFTWND.f90


XScreen2Client

XScreen2Client

XScreen2Client function converts coordinates of a single physical point from screen-based coordinates to client-based coordinates of given window.

XScreen2Client is generic name for two routines, first converting coordinates in scalar form, second in form of X_POINT structures. They are accessible only under generic name XScreen2Client.

LOGICAL
FUNCTION PXScreen2Client_1(xWnd, iXScreen, iYScreen, iXWnd, iYWnd)

TYPE(X_WINDOW), INTENT(IN)::      xWnd
INTEGER, INTENT(IN)::
iXScreen
INTEGER, INTENT(IN)::
iYScreen
INTEGER, OPTIONAL, INTENT(OUT)::  iXWnd
INTEGER, OPTIONAL, INTENT(OUT)::  iYWnd

LOGICAL FUNCTION
 PXScreen2Client_2(xWnd, xPTScreen, xPTWnd)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
TYPE(X_POINT), INTENT(IN)::      xPTScreen
TYPE(X_POINT), INTENT(OUT)::     xPTWnd

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose client-coordinates are to be retrieved.

iXScreen/ iYScreen, xPTScreen

A point in screen coordinate system.

iXWnd/ iYWnd, xPTWnd

Converted coordinate in client-coordinate system of given xWnd.

See Also

XClient2Screen, XClient2View (XFTGDI)

Wrapped APIs

ScreenToClient

Module

XFTWND.f90


XScrollbarGet

XScrollbarGet

XScrollbarGet function retrieves the properties of window's scroll bar. The window must have WS_VSCROLL and/or WS_HSCROLL style in order to have scrollbars visible.

 LOGICAL FUNCTION XScrollbarGet(xWnd, iSB, iPos, iMin, iMax,
iPage)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
INTEGER, INTENT(IN)::
iSB
INTEGER, OPTIONAL, INTENT(OUT):: iPos
INTEGER, OPTIONAL, INTENT(OUT):: iMin
INTEGER, OPTIONAL, INTENT(OUT):: iMax
INTEGER, OPTIONAL, INTENT(OUT):: iPage

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose scrollbar properties are retrieved.

iSB

Determines which scrollbar is referred to. Must be one of the following values:

SB_HORZ | Horizontal scrollbar
SB_VERT | Vertical scrollbar

[iPos]

If present, receives the current position of the scrollbar.

[iMin]

If present, receives the minimal position of the scrollbar.

[iMax]

If present, receives the maximal position of the scrollbar.

[iPage]

If present, receives the size of scrollbar's page. Page is proportional to the size of scrollbar's thumb.

See Also

XScrollbarSet, XGetCanvas, WM_VSCROLL, WM_HSCROLL

Wrapped APIs

GetScrollInfo

Module

XFTWND.f90


XScrollbarSet

XScrollbarSet

XScrollbarSet function sets the properties of window's scroll bar. The window must have WS_VSCROLL and/or WS_HSCROLL style in order to have scrollbars visible.

 LOGICAL FUNCTION
XScrollbarSet(xWnd, iSB, iPos, iMin, iMax,
iPage)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
INTEGER, INTENT(IN)::
iSB
INTEGER, OPTIONAL, INTENT(OUT):: iPos
INTEGER, OPTIONAL, INTENT(OUT):: iMin
INTEGER, OPTIONAL, INTENT(OUT):: iMax
INTEGER, OPTIONAL, INTENT(OUT):: iPage

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose scrollbar properties are set.

iSB

Determines which scrollbar is referred to. Must be one of the following values:

SB_HORZ | Horizontal scrollbar
SB_VERT | Vertical scrollbar

[iPos]

If present, sets the current position of the scrollbar.

[iMin, iMax]
If present, sets the minimal and maximal position of the scrollbar respectively. Both iMin and iMax must be present in order to acheive any effect.

[iPage]

If present, sets the size of scrollbar's page. Page is proportional to the size of scrollbar's thumb.

Remarks

The iPage argument should specify a value from 0 to iMax-iMin+1. The iPos argument should specify a value between iMin and nMax-MAX(nPage–1, 0). If either value is beyond its range, the function sets it to a value that is just within the range.

Properties of window's scrollbars are typically set in the following places:

  • When the window is resized, i.e. from a WM_SIZE handler. Typically, iMin is set to zero, and iMax is set to the extent of virtual image (i.e. total width/height of scrollable image), in pixels. iPage is set to the actual window's client area height/width.

  • When the scrollbar is moved, i.e. from WM_VSCROLL or WM_HSCROLL handlers. See an example under WM_VSCROLL.

See Also

XScrollbarGet, XSetCanvas, WM_VSCROLL, WM_HSCROLL, WM_SIZE

Wrapped APIs

SetScrollInfo

Module

XFTWND.f90


XSendMessage

XSendMessage

XSendMessage function sends a message to specified window. The function calls the window procedure for the specified window and does not return until the window procedure has processed the message.

INTEGER FUNCTION XSendMessage(xWnd, Msg, wParam, lParam)

TYPE(X_WINDOW)::            xWnd
INTEGER, INTENT(IN)::       Msg, wParam, lParam

Arguments

xWnd

X_WINDOW structure describing window to which the message is sent.

Msg

Message code.

wParam

First message parameter. The meaning depends on message code.

lParam

The second message parameter. The meaning depends on message code.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

See Also

Window Events, XPostMessage

Wrapped APIs

SendMessage

Module

XFTWND.f90


XSetCanvas

XSetCanvas

XSetCanvas function sets up a canvas for given window. Canvas presents a fictive rectangular area whose contents are presented in window's client area. When dimensions of the canvas are bigger than dimensions of the window's client area, an appropriate scrollbar is automatically displayed and set up, so that user can scroll in order to see entire canvas. See remarks below for full explanation.

XSetCanvas behaves similarly to QuickWin SetWindowConfig routine. However, it does not allocate any resources so the canvas can be of arbitrary size. A WM_PAINT handler still has to be written appropriately, but presence of the canvas affects the provided viewport of the device context as described below.

LOGICAL FUNCTION XSetCanvas(xWnd, iCanvasX, iCanvasY, iPosX, iPosY)

TYPE(X_WINDOW):: xWnd
INTEGER, INTENT(IN):: iCanvasX, iCanvasY
INTEGER, OPTIONAL, INTENT(IN):: iPosX, iPosY

Arguments

xWnd
 X_WINDOW structure representing the Xeffort window whose canvas is to be set.

iCanvasX, iCanvasY
X and Y dimensions of the canvas, in pixels. If a positive integer, sets up the canvas dimension; if zero or negative, canvas features are disabled for appropriate dimension. If the value is bigger than corresponding dimension of the window's client area, a scrollbar is displayed with appropriate thumb.

[iPosX], [iPosY]
New position of horizontal and vertical scrollbar respectively. If the dimensions are such that the scrollbar is not visible, this value is ignored. If absent, the scrollbar's position is left untouched.

Return Value

If the function succeeds, return value is .TRUE.

Remarks

Presence of canvas affects the behaviour of the following routines and handlers:

  • A scrollbar is automatically set up when needed. Its extent is equal to appropriate canvas dimension in pixels, and its thumb is equal to the current dimension of the client area in pixels.

  • The scrollbar extent and thumb size is automatically handled on window resize (WM_SIZE message)

  • The scrollbar events WM_VSCROLL and WM_HSCROLL are automatically handled, thus manual writing of WM_*SCROLL handler is not required anymore. SB_PAGE* events scroll the window by the current size of client area; SB_LINE* events scroll the window by 1% of the appropriate canvas dimension.

  • Xeffort set up the viewport (XSetViewport) and logical coordinate system (XSetWindow) of the DC passed to WM_PAINT handler to (-iPosX, -iPosY, iCanvasX-iPosX, iCanvasY-iPosY), i.e. the viewport is offset for the current scrollbar position, and its dimensions are equal to canvas dimensions. That provides that the window scrolling appears automatic even if no viewport is explicitly set within WM_PAINT handler.

XSetCanvas calls XScrollbarSet and XUpdateWindow internally.

See Also

XScrollbarSet, XGetCanvas, WM_VSCROLL, WM_HSCROLL, WM_SIZE, WM_PAINT

Module

XFTWND.f90


XSetCommand

XSetCommand

XSetCommand function registers a handler (callback) function for WM_COMMAND and WM_NOTIFY messages. WM_COMMAND message can be sent by a control which is child of the window or by window's or popup menu. A control or menu item must have an identifier, idCmd, unique to parent window. Command handler is called whenever user performs an action on the control or menu with given ID. Programmer can register one command handler per idCmd or one handler for several idCmds (i.e. one handler routine can handle several controls or even several X_WINDOWs).

LOGICAL FUNCTION XSetCommand(xWnd, idCmd, fnHandler)

TYPE(X_WINDOW), INTENT(INOUT)::  xWnd
INTEGER, INTENT(IN)::            idCmd
EXTERNAL                         fnHandler

Arguments

xWnd

X_WINDOW structure describing window for which the callback is registered.

idMsg

Control or menu identifier for which the callback is registered. Must be unique for the window.

fnHandler

Routine which handles the message. It must be of prototype:

INTERFACE
    SUBROUTINE fnHandler(xWnd, idCmd, nCode)
    USE XFTTYPES
    TYPE(X_WINDOW):: 	xWnd
    INTEGER:: 		idCmd, nCode
    END SUBROUTINE fnHandler
END INTERFACE

See Command handler for more details.

Return Value

If the window is a native or bound Xeffort window, the return value is .TRUE. Otherwise, it is .FALSE. XSetCommand does not check for existence of control/menu item with given ID. If it's never created, the callback will never be invoked.

Remarks

XSetCommand is the most general way to install a handler for WM_COMMAND message. XCtlSetSub can be used instead to register handlers for events on controls created by XFTCTRL. If a handler is registered via XCtlSetSub, it overrides the handler registered via XSetCommand.

Prototype of fnHandler must exactly match the interface above, especially regarding number of arguments. If it is not the case, Xeffort library will raise XEXCEPT_STACK_VIOLATION (= Z'E00000E3') exception. Xeffort Wizard application assists you to write a correct prototype for a command handler or other message handlers.

See Also

Window Events, Xeffort Window Bindings, XSetHandler, XCtlSetSub

Module

XFTWND.f90


XSetCursor

XSetCursor

XSetCursor function sets the cursor for window's client area.

INTEGER FUNCTION XSetCursor(xWnd, hCursor)

TYPE(X_WINDOW)::             	 xWnd
INTEGER, OPTIONAL, INTENT(IN)::  hCursor

Arguments

xWnd

X_WINDOW structure describing window whose cursor is to be set.

[hCursor]

Handle of the cursor. The cursor can be loaded by SetCursor API. If absent, the function sets the window's default cursor (which is normal arrow for native Xeffort windows).

Return Value

If successful, the function returns the handle of the previous cursor associated with the window's client area. If the previous cursor was the default, returns -1.

See Also

WM_SETCURSOR, XStdCursor

Module

XFTWND.f90


XSetHandler

XSetHandler

XSetHandler function registers a handler (callback) function which will be called when the window receives a message either from Windows or using XSendMessage.

LOGICAL FUNCTION XSetHandler(xWnd, iMsg, fnHandler)

TYPE(X_WINDOW), INTENT(INOUT)::  xWnd
INTEGER, INTENT(IN)::            iMsg
EXTERNAL                         fnHandler

Arguments

xWnd

X_WINDOW structure describing window for which the callback is registered.

iMsg

Message identifier. See Reference for a detailed list of predefined message identifiers, their meanings and prototypes of handler functions

fnHandler

Function which handles the message. See Reference for a detailed list of predefined message identifiers, their meanings and prototypes of handler functions.

Return Value

If the window is a native or bound Xeffort window, the return value is .TRUE. Otherwise, it is .FALSE.

Remarks

Prototype of fnHandler must exactly match the interface as described in Message and Message Handlers chapter, especially regarding number of arguments. Failure to do so may result in various run-time errors (the most frequent being stack corruption), or, still worse, unexpected behaviors. Xeffort Library checks the value of stack pointer before and after call to programmer-defined handler. If it detects a mismatch, it raises the exception:

XEXCEPT_STACK_VIOLATION (=#E00000E3) Value of stack pointer is not preserved during call to a programmer-defined handler routine. This may happen if the handler has wrong number of arguments of if it uses calling convention other than default one.

Xeffort Wizard application assists you to write a correct prototype for a message handler.

See Also

Window Events, Xeffort Window Bindings, XSetCommand

Module

XFTWND.f90


XSetWindowData

XSetWindowData

XSetWindowData associates any application-defined data with the window. If data were already associated, it changes the existing entry. Application-defined data are very useful technique for sharing window-specific data between routines. See for example the "Maintaining a list of X_WINDOWs" in Design Considerations. An application can associate an arbitrary number of data sets using different sDataID strings.

LOGICAL FUNCTION XSetWindowData(xWnd, lpData, sDataID)

TYPE(X_WINDOW), INTENT(IN)::           xWnd
!DEC$ATTRIBUTES NO_ARG_CHECK::         lpData
WHATEVER::                             lpData
CHARACTER(*), OPTIONAL, INTENT(IN)::   sDataID

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

lpData

Any scalar. Variable which corresponds to lpData should be declared SAVE, ALLOCATABLE or POINTER, so that it can be later retrieved using XGetWindowData.

[sDataID]

A unique (case-insensitive) string which represents the property. If absent, Xeffort library stores the data under "XDATA" entry.

Return Value

If successful, the function returns .TRUE.

Remarks

The application must free every added entry when no longer needed by calling XFreeWindowData.

"XWND" and "XCTL" entries are reserved by Xeffort library itself.

See Also

XGetWindowData, XFreeWindowData

Wrapped APIs

SetProp

Module

XFTWND.f90


XSetWindowIcon

XSetWindowIcon

XSetWindowIcon function sets the window's icon. The function loads the icon as resource and expects to find both small (16x16) and big (32x32) icon. If one size is missing, it attempts to fit it with the other.

LOGICAL FUNCTION XSetWindowIcon(xWnd, IDIcon, hModule)

TYPE(X_WINDOW)::                 xWnd
INTEGER, INTENT(IN)::            IDIcon
INTEGER, OPTIONAL, INTENT(IN)::  hModule

Arguments

xWnd

X_WINDOW structure describing window whose icon is to be set.

IDIcon

Icon identifier.

[hModule]

Handle of the dll module from which the icon is loaded (as returned from XGetInstance, LoadLibrary, or GetModuleHandle APIs). If absent, the icon is loaded from the .exe file that started the current process.

Return Value

The function returns .TRUE. if it finds either small or big icon under the same ID.

Wrapped APIs

WM_SETICON

Module

XFTWND.f90


XSetWindowPos

XSetWindowPos

XSetWindowPos function sets the window position, size, and visibility.

LOGICAL FUNCTION XSetWindowPos(xWnd, iX, iY, iWidth, iHeight, iShow, xWndAfter)

TYPE(X_WINDOW), INTENT(IN)::            xWnd
INTEGER, OPTIONAL, INTENT(IN)::         iX, iY
INTEGER, OPTIONAL, INTENT(IN)::         iWidth, iHeight
INTEGER, OPTIONAL, INTENT(IN)::         iShow
TYPE(X_WINDOW), OPTIONAL, INTENT(IN)::  xWndAfter

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

[iX, iY]

Position of top-left corner of the window, in pixels. For child windows, it is expressed as offset from origin of parent's client area. For popup and overlapped windows, it is expressed in screen coordinates. If used, both iX and iY must be present.

[iWidth, iHeight]

Window width and height, in pixels. If used, both must be present.

[iShow]

One of SW_flags determining how the window should be displayed. If absent, the window's current appearance is not changed. In addition to the flags applicable to XShowWindow, it can be one of:

Value | Meaning
SW_BOTTOM | Places the window at the bottom of the Z order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
SW_NOTOPMOST | Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
SW_TOP | Places the window at the top of the Z order.
SW_TOPMOST | Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.

[xWndAfter]

If present, the function moves xWnd immediately above window xWndAfter in Z-(vertical) order.

Remarks

If several windows should be moved/sized simultaneously, use XBeginMoveWindows and XEndMoveWindows before and after this function. In that case, the windows' position are updated after call to XEndMoveWindows.

Return Value

If successful, the function returns .TRUE.

See Also

XMoveWindow, XSizeWindow, XShowWindow, XGetWindowPos, XBeginMoveWindows, XEndMoveWindows

Wrapped APIs

SetWindowPos, DeferWindowPos

Module

XFTWND.f90


XSetWindowData

XSetWindowStyle

XSetWindowStyle changes the window's style, extended style, or class style.

INTEGER FUNCTION XSetWindowStyle(xWnd, iStyle, iType, iAction)

TYPE(X_WINDOW), INTENT(IN)::           xWnd
INTEGER, INTENT(IN)::                  iStyle
INTEGER, OPTIONAL, INTENT(IN)::        iType
INTEGER, OPTIONAL, INTENT(IN)::        iAction

Arguments

xWnd

X_WINDOW structure representing the Xeffort window whose style is to be modified.

iStyle

An OR combination of window styles, extended styles, or class styles. iType argument determines which kind of style is changed.

[iType]

One of the following constants, which determines which kind of style is set:

XWST_STYLE | Window style (default)
XWST_EXSTYLE | Extended style
XWST_CLASS | Class style

[iAction]

One of the following constants, which determines how the new style(s) are combined with the existing window style:

XWSA_APPEND | The new style(s) are added to the existing style set of the window. If the new style was already present in the existing set, it produces no effect. (default)
XWSA_REPLACE | The new style(s) entirely replace existing window styles
XWSA_REMOVE | The new style(s) are removed from the existing style set of the window. If a new style was not present in the existing set, it produces no effect.

Return Value

If successful, the function returns new window styles of appropriate type. If the function fails (because xWnd is invalid), the return value is zero.

See Also

XGetWindowStyle

Wrapped APIs

SetWindowLong, GetWindowLong, SetClassLong, GetClassLong

Module

XFTWND.f90


XSetWindowTitle

XSetWindowTitle

XSetWindowTitle function sets the window's title (the text that appears in window's title bar). If the specified window is a control, the text of the control is changed.

LOGICAL FUNCTION XSetWindowTitle(xWnd, sTitle)

TYPE(X_WINDOW)::             xWnd
CHARACTER*(*), INTENT(IN)::  sTitle

Arguments

xWnd

X_WINDOW structure describing window whose title is to be set.

sTitle

Window title.

Return Value

If successful. the function returns .TRUE.

Wrapped APIs

SetWindowText

Module

XFTWND.f90


XShowWindow

XShowWindow

XShowWindow function changes the window's visibility, minimized or maximized state.

LOGICAL FUNCTION
XShowWindow(xWnd, iFlags)

TYPE(X_WINDOW), INTENT(IN)::     xWnd
INTEGER, INTENT(IN)::
iFlags

Arguments

Wnd

X_WINDOW structure describing window whose icon is to be set.

iFlags

One of the following values, indicating new visual state of the window:

Value | Meaning
SW_HIDE | Hides the window and activates another window.
SW_MAXIMIZE | Maximizes the specified window.
SW_MINIMIZE | Minimizes the specified window and activates the next top-level window in the Z order.
SW_RESTORE | Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW | Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT | Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE | Displays the window as a minimized window. The active window remains active.
SW_SHOWNA | Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

Return Value

If the window was previously visible, the return value is .TRUE. Otherwise, it is .FALSE.

Remarks

XShowWindow is also affected by multiple-updating of windows using XBeginMoveWindows and XEndMoveWindows

See Also

XBeginMoveWindows, XEndMoveWindows, XSetWindowPos

Wrapped APIs

ShowWindow, DeferWindowPos

Module

XFTWND.f90


XSizeWindow

XSizeWindow

XSizeWindow function sets the window size.

LOGICAL FUNCTION XSizeWindow(xWnd, iWidth, iHeight)

TYPE(X_WINDOW), INTENT(IN)::   xWnd
INTEGER, INTENT(IN)::          iWidth, iHeight

Arguments

xWnd

X_WINDOW structure representing the Xeffort window.

iWidth, iHeight

Window width and height, in pixels.

Return Value

If successful, the function returns .TRUE.

See Also

XMoveWindow, XShowWindow, XGetWindowPos, XSetWindowPos

Wrapped APIs

SetWindowPos

Module

XFTWND.f90


XStdCursor

XStdCursor

XStdCursor function sets the cursor for window's client area to one of the standard cursors.

INTEGER FUNCTION XStdCursor(xWnd, iCursor)

TYPE(X_WINDOW)::             	 xWnd
INTEGER, OPTIONAL, INTENT(IN)::  iCursor

Arguments

xWnd

X_WINDOW structure describing window whose cursor is to be set.

[iCursor]

One of the values from the following table:

iCursor Value | Description
IDC_ARROW | Standard arrow
IDC_WAIT | Hourglass
IDC_APPSTARTING | Standard arrow and small hourglass
IDC_CROSS | Crosshair
IDC_IBEAM | I-beam
IDC_NO | Slashed circle
IDC_UPARROW | Vertical arrow
IDC_SIZEALL | Four-pointed arrow pointing north, south, east, and west
IDC_SIZENESW | Double-pointed arrow pointing northeast and southwest
IDC_SIZENS | Double-pointed arrow pointing north and south
IDC_SIZENWSE | Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE | Double-pointed arrow pointing west and east

If iCursor is omitted, or is not a value in the above table, then an iCursor value of IDC_ARROW is used.

Return Value

The function returns the handle (not the iCursor value) of the previous cursor associated with the window's client area. Therefore, to revert to the cursor in use before the XStdCursor call, pass that handle to XSetCursor.

See Also

XSetCursor, WM_SETCURSOR

Wrapped APIs

LoadCursor, SetCursor


XUnbindWindow

XUnbindWindow

XUnbindWindow function removes Xeffort binding from a window previously bound using XBindWindow function and deallocates the structure.

LOGICAL FUNCTION XUnbindWindow(xWnd)

TYPE(X_WINDOW), POINTER::         xWnd

Arguments

xWnd
 X_WINDOW structure representing the Xeffort window to be unbound from Xeffort framework. Must be a pointer. Neither native Xeffort windows nor unbound windows cannot be unbound. If successful, the function DEALLOCATEs the xWnd.

Return Value

The window must be previously bound using XBindWindow; if so, the return value is .TRUE. Otherwise, the return value is .FALSE.

Remarks

Call to XUnbindWindow will remove all command and message handlers installed since call to XBindWindow. If you added any controls into the window using XCtlCreate, they should be removed before the call using XCtlDestroyAll. Also, any subclassing procedure manually added using SetWindowLong will be removed from subclassing chain.

See Also

XBindWindow, XGetWindow, XCreateWindow, XIsWindow, XSetHandler

Module

XFTWND.f90


XFTWND: Window Messages Overview

XFTWND: Window Mesages Overview

XFTWnd O verview XFTWnd Reference Messages Reference

A typical console Fortran application usually reads data from a file or other source, performs computation and writes data to screen, file or printer. On the way, it may stop to ask user a few questions and, depending on response and/or on structure of input data it continues execution in some branch. That can be expressed by a linear flow chart.

This approach cannot be applied to Windows application, which continuously interacts with the user. A Windows application is better represented as a black box which changes its state whenever user performs some action, like choosing a command from a menu, typing a letter or moving the mouse. Here, state should be understood as a set of programmer-defined variables (and their visible represents on screen) which change their values depending on user's actions. Apart from direct user's actions, the program may change its state whenever something other happens in the system, for example, when system resolution changes, or when screen saver starts. All user actions, along with changes that occur in the system for whatever reason, are referred to as events. Every event under Win32 is directed to a window.

But, there is a vast amount of events that can occur and perhaps an infinite number of states which are allowed for the application. Windows informs every application (which, in turn, pass that information to their windows) running on the system of all events that may be of interest for it. For example, when user moves the mouse, that information is sent to every window that lays beneath the cursor; when user adds a system font from Control Panel applet, that information is passed to every main application window in the system. In event-driven programming, programmer's duty is to handle only the events that are of interest for his application, i.e. to write a piece of code that will change the application's state accordingly. These procedures are called event handlers or callbacks. For example, if user has both Notepad and Word opened on the system, and then adds a font to system pool, both applications are informed about that. Word has the interest for that information, with appropriate event handler written, which enhances list of fonts available to user; on the other side, this information is irrelevant for Notepad, since it can operate with only one font at a time.

Messages

Every event that occurs in the system is sent by Windows to the application in form of a message. Message is a small set of data which describes what has happened. Every message has two basic parameters:

  • Handle of the window it is intended for (hWnd)
  • Message code - description of event that happened (Msg)

Also, every event that may occur in the system is uniquely coded. Windows recognize over 1000 types of "standard" events, i.e. there are 1000 different message codes. For example, the mentioned event of change in set of system fonts has code 29 and symbolic name WM_FONTCHANGE (WM_ stands for "window message").

In addition, every message has two integer parameters, called lParam and wParam, which carry additional information about the event. For example, when user moves mouse pointer over a window, message WM_MOUSEMOVE is sent; lParam carries packed information of X and Y cursor position, and wParam information of state of mouse buttons, control and shift keys.

Since there is limited room (only 32-bit integers lParam and wParam) to store information, Windows packs it in various ways depending on message code (lParam and wParam can be pointers to structures, treated as 2 16-bit integers etc.). Xeffort framework does the decoding of information for you, as described in Messages and Message Handlers chapter.

Every application has a "message queue". When an event (e.g. a keypress) occurs, system places an appropriate message into application's message queue. It is application's duty to take the message out of the queue and do something (or nothing) with it. Xeffort library takes care about that part; programmer's task is just to define what to do with the message. Such messages are referred to as posted. However, the messages can be also sent. That means that the source of the message was not the system, but the message can be sent directly to the window using XSendMessage, or generated on the fly by many routines; for example, XUpdateWindow generates a WM_PAINT message. However, the programmer should not care about the origin of the message - the only concern should be on the message handling itself and whether default processing should take place.

Message Handling

Every event/message that arrives to a window must be handled in some way. Handling events means that the window should do something about it. However, most events (for example, WM_FONTCHANGE) are by default simply ignored; they do not mean anything essential in contexts not defined by programmer. For other events, default behavior of the window usually depends on window style; e.g. if the window has WS_THICKFRAME style (resizable windows), moving of mouse pointer on window's frame would generate WM_NCMOUSEMOVE event, which will cause the cursor to change shape to a "resizer". Third, some messages, like WM_CLOSE, will cause the window, regardless of the style, to close.

The catch-all Win32 function for all events not explicitly handled by application is called DefWindowProc; it does the default processing for all messages not handling previously by someone in the call stack.

When an event occurs, i.e. a message arrives in the message queue, a typical call stack looks like on the picture. Yellow routines are part of the syste code; red ones are Xeffort library code. xWnd_OnHandler is programmer-defined handler. If the handler returns .TRUE., further processing is halted; otherwise, the default action takes place. The left picture depicts the call stack for posted messages and the right one the call stack for sent messages.

Message Handlers

Most of the code in a full Xeffort application consists of message handlers.

Under Xeffort, message handler is a programmer-defined routine (function or subroutine) of predefined prototype. It is your duty to write a routine of that prototype and register it for your window using XSetHandler routine. In average, programmer handles just a dozen of events of interest; default window procedure intelligently takes care about the rest (which, in most cases, is equal to "do nothing"). The exception would be WM_COMMAND message, which comes when user does something with a control (menu, edit box, toolbar) which is a child of given window; controls are created to provide some special means of user input and usually events coming from the controls are handled specially. Thus, WM_COMMAND and WM_NOTIFY messages has somewhat special status - their handlers can be registered using XSetCommand or some special Xeffort routines, like XCtlSetSub. (WM_NOTIFY is kind of "extended" WM_COMMAND; it's probably a Microsoft quirk when they discovered that parameters of WM_COMMAND are not enough to pass all the info).

Message Handlers reference page lists the messages for which Xeffort decodes wParam and lParam parameters. If you need to handle a message not listed there, you have to write a default handler.

Xeffort Wizard application is used to define the handler prototyple quickly and reliably. For given message code (or control ID), it generates a call to XSetHandler and an appropriate body of handler routine. The recommended convention for naming of the handler routines is:

  • For message handlers: xWnd_OnMessageName
    where xWnd is the name of X_WINDOW variable, and MessageName is the name of the message code (without WM_ prefix)

  • For command and control handlers: xWnd_OnControl

    where xWnd is the name of X_WINDOW variable, and Control is the name of the control identifier (without ID*_ prefix)

Message handlers documentation also describes the default behavior for given message. For many messages, the default action is to simply do nothing; for others, there is some further processing of the message. The default action depends on window's class, described in the sequel. The documentation usually refers to default behavior of "XWndClass" windows; that is the general-purpose Xeffort window class. For other window classes, you have to refer to their documentation or just common sense; for example, an edit box responds to WM_CHAR message by adding an appropriate character to its display.

An attention should be paid that message handlers execute quickly. Namely, while the handler is being executed, no other message processing can take place, since the application is normally single-threaded. See XProcessMessages routine.

Window Classes and Subclassing

While DefWindowProc "blindly" handles events in some manner, there's often a need for something more. Some windows do have to behave differently - for example, control windows or MDI child windows. For this reason, windows are organized in classes. All windows of the same class share the procedure for default handling of events (referred to as window procedure). Window class has few more properties shared by the windows belonging to the class, like icon, cursor, and background color. (Please note that the term class here has nothing in common with classes in object-oriented languages like C++). Window procedure handles additional set of events or handles some events differently than DefWindowProc.

Window class is uniquely identified by its name. For example, edit boxes class is named "Edit" while MDI child window class is named "MDIClient". Classes can be predefined, system-wide, like "Edit", "Button" or "MDIClient" or defined by programmer. Currently Xeffort does not wrap RegisterClass API, i.e. it does not allow programmer to define new classes. By default, Xeffort windows created by XCreateWindow are of class "XWndClass". However, it is seldom necessary since Xeffort windows can extend and/or alter the behavior of windows of any existing class using technique called subclassing.

As said above, any event which occurs in a window is sent to its window procedure. Windows "knows" what's the address of the window procedure by "looking" at a piece of memory which defines properties of the window. Subclassing is technique which replaces default window procedure with the one defined by programmer by simply altering that address. New message handler acts as a filter: it may handle some additional events, it may disallow the event to even go to default handling, or it may simply pass the events to the window procedure which was there before. Note that the "chain" of window procedure can be arbitrarily long; the only condition is that every message must be handled somewhere, at least in DefWindowProc.

Xeffort Window Bindings page describes classification of windows regarding event handling.


Message Handlers Reference

Message Handlers Reference

Overview

Window Creation and Activation

WM_ACTIVATE

WM_ACTIVATEAPP

WM_CHILDACTIVATE

WM_CREATE

WM_ENABLE

WM_DESTROY

WM_MDIACTIVATE

WM_MDIDESTROY

WM_MOUSEACTIVATE

WM_NCACTIVATE

WM_NCDESTROY

WM_SETFOCUS

Mouse and Keyboard Events

WM_CHAR

WM_CONTEXTMENU

WM_DEADCHAR

WM_KEYDOWN

WM_KEYUP

WM_KILLFOCUS

WM_LBUTTONDBLCLK

WM_LBUTTONDOWN

WM_LBUTTONUP

WM_MOUSEMOVE

WM_MOUSEWHEEL

WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDOWN

WM_NCLBUTTONUP

WM_NCMOUSEMOVE

WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDOWN

WM_NCRBUTTONUP

WM_RBUTTONDOWN

WM_RBUTTONUP

WM_NCHITTEST

Painting and Drawing

WM_ERASEBKGND

WM_PAINT

Menu and Control Events

WM_CLOSE

WM_ENTERMENULOOP

WM_EXITMENULOOP

WM_HSCROLL

WM_HELP

WM_HOTKEY

WM_INITMENU

WM_INITMENUPOPUP

WM_SETCURSOR

WM_SYSCOMMAND

WM_VSCROLL

Size and Position

WM_CAPTURECHANGED

WM_DISPLAYCHANGE

WM_GETMINMAXINFO

WM_MOVE

WM_SIZE

WM_WINDOWPOSCHANGED

WM_WINDOWPOSCHANGING

Other Events

WM_DROPFILES

WM_ENDSESSION

WM_QUERYENDSESSION

WM_SYSCOLORCHANGE

WM_TIMECHANGE

WM_TIMER


Command handler

Command Handler

The WM_COMMAND or WM_NOTIFY message is sent when the user selects a command item from a menu, when a control sends a message to its parent window providing notification or requesting information, or when an accelerator keystroke is translated.

Handler for WM_COMMAND and WM_NOTIFY messages is installed using XSetCommand routine.

bSt = XSetCommand(xWnd, IdControl, xWnd_OnIdControl)

LOGICAL FUNCTION xWnd_OnIdControl(xWnd, ID, nCode)

TYPE(X_WINDOW)::          xWnd
INTEGER, INTENT(IN)::     ID
INTEGER, INTENT(IN)::     nCode

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

ID

Identifier of the menu item or control where the event occurred.

nCode

A coded integer constant which describes the nature of the event. If the command is generated from a menu, accelerator or toolbar button, this argument has value zero. Otherwise, the set of available codes depends on type of the control. For example, edit controls send EN_CHANGE, EN_KILLFOCUS, buttons send BN_CLICKED, etc.

When the source of the event is a common control (i.e. the command is sent in form of WM_NOTIFY message), this argument can carry additional info. For example, a ListView control sends LVN_ITEMCHANGED nCode when user changes an item. As described in Win32 Help, the additional info is carried in a T_NMLISTVIEW structure. Application can cast nCode argument using the X_NMLISTVIEW macro function, e.g:

TYPE(T_NMLISTVIEW), POINTER:: NML
...
IF (nCode==LVN_ITEMCHANGED) THEN
   NML => X_NMLISTVIEW(nCode)
   IF (IAND(NML%uChanged,LVIF_TEXT) /= 0) THEN
      !User changed the text of the item
      ...

See Also

XSetCommand, List of X_NM macros, XCtlSetSub


Default Message Handler

Default Handler

Default handler is provided for messages which are not decoded by the Xeffort library. Xeffort library decodes wParam and lParam for messages which are commonly handled. When a message other than ones listed in Message Handlers Reference should be handled, the handler function should be of prototype described here; decoding of wParam and lParam must be done by the application.

bSt = XSetHandler(xWnd, WM_WHATEVER, xWnd_OnWhatever)

LOGICAL FUNCTION xWnd_OnWhatever(xWnd, Msg, wParam, lParam)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         Msg, wParam, lParam

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Msg

Message code. WM_WHATEVER is used as a generic name in the prototype above; use specific WM_* name.

wParam

First message parameter. The meaning depends on message code.

lParam

The second message parameter. The meaning depends on message code.

Return Value

The return value specifies the result of the message processing and depends on the message sent.


WM_ACTIVATE

WM_ACTIVATE

The WM_ACTIVATE message is sent when a window is being activated or deactivated. This message is sent first to the window procedure of the top-level window being deactivated; it is then sent to the window procedure of the top-level window being activated.

bSt = XSetHandler(xWnd, WM_ACTIVATE, xWnd_OnActivate)

LOGICAL FUNCTION xWnd_OnActivate(xWnd, nActivate, bMinimized, hwndPrevious)

TYPE(X_WINDOW)::
xWnd
INTEGER, INTENT(IN)::         nActivate
LOGICAL, INTENT(IN)::         bMinimized
TYPE(X_WINDOW)::
xWndPrevious

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nActivate
Specifies the how the window was (de)activated:

WA_ACTIVE | Activated by some method other than a mouse click (for example, by a call to the SetActiveWindow function or by use of the keyboard interface to select the window).
WA_CLICKACTIVE | Activated by a mouse click.
WA_INACTIVE | Deactivated.

bMinimized
.TRUE. if window is minimized, otherwise .FALSE.

xWndPrevious
X_WINDOW structure describing the window being activated or deactivated, depending on the value of the fActive parameter. If the value of fActive is WA_INACTIVE, xWndPrevious is the the window being activated. If the value of fActive is WA_ACTIVE or WA_CLICKACTIVE, xWndPrevious is the handle of the window being deactivated. The window can be invalid.

Default Action / Return Value

If the window is being activated and is not minimized, the keyboard focus is set the to the window.

Function should return .TRUE. if you doesn't want default action to be performed; otherwise, it should return .FALSE.

See Also

WM_MOUSEACTIVATE, WM_NCACTIVATE, WM_SETFOCUS, WM_KILLFOCUS


WM_ACTIVATEAPP

WM_ACTIVATEAPP

The WM_ACTIVATEAPP message is sent when a window belonging to a different application than the active window is about to be activated. The message is sent to the application whose window is being activated and to the main window (XW_FRAME) of the application whose window is being deactivated.

bSt = XSetHandler(xWnd, WM_ACTIVATEAPP, xWnd_OnActivateApp)

LOGICAL FUNCTION xWnd_OnActivateApp(xWnd, bActivate)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN)::         bActivate

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bActivate
If .TRUE., the application is being activated; otherwise, it is being deactivated.

Return Value

The function should return .FALSE.

See Also

WM_ACTIVATE


WM_CAPTURECHANGED

WM_CAPTURECHANGED

The WM_CAPTURECHANGED message is sent to the window that is losing the mouse capture.

bSt = XSetHandler(xWnd, WM_CAPTURECHANGED, xWnd_OnCaptureChanged)

LOGICAL FUNCTION xWnd_OnCaptureChanged(xWnd, xWndGainCapture)

TYPE(X_WINDOW)::              xWnd
TYPE(X_WINDOW), INTENT(IN)::  xWndGainCapture

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xWndGainCapture

X_WINDOW structure containing information about the window which gains the capture.

Return Value

The function should return .FALSE.


WM_CHAR

WM_CHAR

The WM_CHAR message is posted to the window with the keyboard focus when a WM_KEYDOWN message is translated by the TranslateMessage function. WM_CHAR contains the character code of the key that was pressed.

bSt = XSetHandler(xWnd, WM_CHAR, xWnd_OnChar)

LOGICAL FUNCTION xWnd_OnChar(xWnd, nCode, bPressed, bAlt)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nCode
LOGICAL, INTENT(IN)::         bPressed, bAlt

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nCode

Character code of the key. Character code is equal to ASCII code for printable characters and you can use CHAR/ACHAR intrinsics to convert them back and forth to characters. For most special characters, that value will be equal to virtual-key code. For non-ASCII characters (with nCode>127), nCode is equal to character position in system code page.

bPressed

Current state of the key. If .TRUE., the key is pressed, otherwise it is released.

bAlt

Current state of the Alt key. If .TRUE., the key is pressed, otherwise it is released.

Return Value

The function should return .FALSE. if it wants default processing or .TRUE. otherwise. Although this message is ignored by default, it is processed by predefined classes which accept key input (such as edit boxes or combo boxes). For example, the following handler when applied to an edit box limits the input to floating point numbers (it allows numbers, +, - and .):

LOGICAL FUNCTION XEdit_OnChar(xWnd, nCode, bPressed, bAlt)

TYPE(X_WINDOW)::              xWnd
INTEGER,  INTENT(IN)::         nCode
LOGICAL,  INTENT(IN)::         bPressed, bAlt

SELECT CASE(nCode)
CASE(VK_0:VK_9, VK_DECIMAL, VK_ADD, VK_DIVIDE)
XEdit_OnChar = .FALSE.
CASE(VK_RETURN, VK_TAB, VK_BACK, VK_END:VK_DOWN)
XEdit_OnChar =
   .FALSE.
CASE DEFAULT
XEdit_OnChar = .TRUE.
END SELECT

END FUNCTION XEdit_OnChar

See Also

WM_KEYDOWN, WM_KEYUP, Keycodes


WM_CHILDACTIVATE

WM_CHILDACTIVATE

The WM_CHILDACTIVATE message is sent to a multiple document interface (MDI) child window when the user clicks the window’s title bar or when the window is activated, moved, or sized.

bSt = XSetHandler(xWnd, WM_CHILDACTIVATE, xWnd_OnChildActivate)

LOGICAL FUNCTION xWnd_OnChildActivate(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Return Value

The function should return .FALSE.

See Also

WM_MDIACTIVATE, XMDISetActive


WM_CLOSE

WM_CLOSE

The WM_CLOSE message is sent as a signal that a window or an application should terminate. WM_CLOSE is generated when user presses X button on window's title bar or "Close" option from window's system menu.

bSt = XSetHandler(xWnd, WM_CLOSE, xWnd_OnClose)
LOGICAL FUNCTION xWnd_OnClose(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Default Action / Return Value

The default action is to call DestroyWindow function to destroy the window.

The function should return .FALSE. if it wants this behavior or .TRUE. otherwise.

See Also

WM_DESTROY, WM_SYSCOMMAND


WM_CONTEXTMENU

WM_CONTEXTMENU

The WM_CONTEXTMENU message notifies a window that the user clicked the right mouse button in the window, pressed Shift+F10 or Context Menu key on the keyboard.

bSt = XSetHandler(xWnd, WM_CONTEXTMENU, xWnd_OnContextMenu)

LOGICAL FUNCTION xWnd_OnContextMenu(xWnd, iX, iY)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX

X position, in screen-relative coordinates, of the mouse at the time of the click.

iY

Y position, in screen-relative coordinates, of the mouse at the time of the click.

Default Action / Return Value

By default, no action is taken, but some predefined classes (e.g. edit boxes) display a context menu.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

Handling of this message is the preferred way to display context menus, because WM_CONTEXTMENU is sent also when user accesses the context menu using keyboard (Shift+F10 or "menu" key). This is not the case with WM_RBUTTONUP.

See Also

WM_RBUTTONUP, XCreateMenu, XContextMenu


WM_CREATE

WM_CREATE

WM_CREATE message is sent during creation of the window, i.e. during XCreateWindow routine.

bSt = XSetHandler(xWnd, WM_CREATE, xWnd_OnCreate)

LOGICAL FUNCTION xWnd_OnCreate(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Return Value

The function should return .FALSE.

Remarks

This feature is currently defunct, because WM_CREATE is sent during XCreateWindow, but a handler may not be installed using XSetHandler before that.


WM_DEADCHAR

WM_DEADCHAR

The WM_DEADCHAR message is posted to the window with the keyboard focus when a WM_KEYUP message is translated by the TranslateMessage function. WM_DEADCHAR specifies a character code generated by a dead key. A dead key is a key that generates a character, such as the umlaut (double-dot), that is combined with another character to form a composite character. For example, the umlaut-O character (Ö) is generated by typing the dead key for the umlaut character, and then typing the O key.

bSt = XSetHandler(xWnd, WM_DEADCHAR, xWnd_OnDeadChar)

LOGICAL FUNCTION xWnd_OnDeadChar(xWnd, nCode, bPressed, bAlt)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nCode
LOGICAL, INTENT(IN)::         bPressed, bAlt

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nCode

Character code of the key. Character code is equal to ASCII code for printable characters and you can use CHAR/ACHAR intrinsics to convert them back and forth to characters. For most special characters, that value will be equal to virtual-key code. For non-ASCII characters (with nCode>127), nCode is equal to character position in system code page.

bPressed

Current state of the key. If .TRUE., the key is pressed, otherwise it is released.

bAlt

Current state of the Alt key. If .TRUE., the key is pressed, otherwise it is released.

Return Value

The function should return .FALSE. if it wants default processing or .TRUE. otherwise. Although this message is ignored by DefWindowProc, it is processed by predefined classes which accept key input (such as edit boxes or combo boxes).

See Also

WM_CHAR, WM_KEYUP


WM_DESTROY

WM_DESTROY

The WM_DESTROY message is sent when a window is being destroyed. It is sent to the window procedure of the window being destroyed after the window is removed from the screen.

This message is sent first to the window being destroyed and then to the child windows (if any) as they are destroyed. During the processing of the message, it can be assumed that all child windows still exist.

bSt = XSetHandler(xWnd, WM_DESTROY, xWnd_OnDestroy)

LOGICAL FUNCTION xWnd_OnDestroy(xWnd)

TYPE(X_WINDOW)::           xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Return Value

By default Xeffort framework (FXWindowProc) calls PostQuitMessage for frame window (XW_FRAME), which causes the application to terminate. For other windows this message is not handled (but it may be for bound windows).

To prevent that, return .TRUE., otherwise return .FALSE..

See Also

WM_CLOSE, WM_NCDESTROY


WM_DISPLAYCHANGE

WM_DISPLAYCHANGE

The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed.

bSt = XSetHandler(xWnd, WM_DISPLAYCHANGE, xWnd_OnDisplayChange)

LOGICAL FUNCTION xWnd_OnDisplayChange(xWnd, nBitsPerPel, iX, iY)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nBitsPerPel, iX, iY

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nBitsPerPel

Specifies the new image depth of the display in bits per pixel.

iX

Specifies the new horizontal resolution of the screen.

iY

Specifies the new horizontal resolution of the screen.

Return Value

The function should return .FALSE.

See Also

WM_SYSCOLORCHANGE


WM_DROPFILES

WM_DROPFILES

The WM_DROPFILES message is sent when the user drops a file on the window of an application that has registered itself as a recipient of dropped files by means of calling DragAcceptFiles API, or having WS_EX_ACCEPTFILES extended style.

bSt = XSetHandler(xWnd, WM_DROPFILES, xWnd_OnDropFiles)

LOGICAL FUNCTION xWnd_OnDropFiles(xWnd, sFile)

TYPE(X_WINDOW)::              xWnd
CHARACTER(*), INTENT(IN)::    sFile(:)

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

sFile

Array of filenames (including filenames) of dropped files.

Return Value

The function should return .FALSE.


WM_ENABLE

WM_ENABLE

The WM_ENABLE message is sent when an application changes the enabled state of a window. It is sent to the window whose enabled state is changing. This message is sent before the XEnableWindow function returns, but after the enabled state (WS_DISABLED style bit) of the window has changed.

bSt = XSetHandler(xWnd, WM_ENABLE, xWnd_OnEnable)

LOGICAL FUNCTION xWnd_OnEnable(xWnd, bEnable)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN)::         bEnable

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bEnable

.TRUE. if the window has been enabled and .FALSE. if the window has been disabled.

Return Value

The function should return .FALSE.

See Also

XEnableWindow


WM_ENDSESSION

WM_ENDSESSION

The WM_ENDSESSION message is sent to an application after Windows processes the results of the WM_QUERYENDSESSION message. The WM_ENDSESSION message informs the application whether the Windows session is ending.

bSt = XSetHandler(xWnd, WM_ENDSESSION, xWnd_OnEndSession)

LOGICAL FUNCTION  xWnd_OnEndSession(xWnd, bEnd)

TYPE(X_WINDOW)::              xWnd
LOGICAL::
bEnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bEnd

Specifies whether the session is being ended. If the session is being ended, this parameter is .TRUE.; otherwise, it is .FALSE.

Return Value

The function should return .FALSE.

See Also

WM_QUERYENDSESSION


WM_ENTERMENULOOP

WM_ENTERMENULOOP

The WM_ENTERMENULOOP message informs an application’s main window (XW_FRAME) that a menu modal loop has been entered.

bSt = XSetHandler(xWnd, WM_ENTERMENULOOP, xWnd_OnEnterMenuLoop)

LOGICAL FUNCTION xWnd_OnEnterMenuLoop(xWnd, bPopup)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN)::         bPopup

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bPopup

Specifies whether the menu involved is a shortcut (popup) menu. This parameter has a value of TRUE if it is a shortcut menu, FALSE if it isn’t.

Return Value

The function should return .FALSE.

See Also

WM_EXITMENULOOP


WM_ERASEBKGND

WM_ERASEBKGND

A window receives the WM_ERASEBKGND message when the window background must be erased (for example, when a window is resized).

bSt = XSetHandler(xWnd, WM_ERASEBKGND, xWnd_OnEraseBkGnd)

LOGICAL FUNCTION xWnd_OnEraseBkGnd(xWnd, xDC)

TYPE(X_WINDOW)::              xWnd
TYPE(X_DC), INTENT(IN)::      xDC

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xDC

X_DC structure containing information about the background device context. Both viewport and window dimensions are adjusted to client area of the window.

Default Action / Return Value

This message is sent immediately before WM_PAINT message. Native Xeffort windows (of class "XWndClass") do not do any painting by default. Other windows (especially, dialogs) can erase the background using the default window's class background brush (for dialogs, that would be a system color for 3-D foreground).

In general, the function should return .TRUE. if it does not want default processing.

Remarks

An application can draw on its window in two steps: in the first step, WM_ERASEBKGND is sent and the background can be erased using e.g. XFillRect. In the second step, WM_PAINT is sent and there the application can draw more complex output. Both steps are optional, but at least one should be performed. Thus, if WM_PAINT handler fills in an entire client area, WM_ERASEBKGND should not be executed, because its results will be immediately overdrawn.

WM_ERASEBKGND is suitable for "skinned" applications, e.g. if the background should be a constant pattern but the controls (e.g. static text) should appear transparent over the background.

See Also

WM_PAINT


WM_EXITMENULOOP

WM_EXITMENULOOP

The WM_EXITMENULOOP message informs an application’s main window (XW_FRAME) that a menu modal loop has been exited.

bSt = XSetHandler(xWnd,
WM_EXITMENULOOP, xWnd_OnExitMenuLoop)
LOGICAL FUNCTION  xWnd_OnExitMenuLoop(xWnd, bPopup)

TYPE(X_WINDOW)::              xWnd
LOGICAL,  INTENT(IN)::         bPopup

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bPopup

Specifies whether the menu involved is a shortcut (popup) menu. This parameter has a value of TRUE if it is a shortcut menu, FALSE if it isn’t.

Return Value

The function should return .FALSE.

See Also

WM_ENTERMENULOOP


WM_GETMINMAXINFO

WM_GETMINMAXINFO

The WM_GETMINMAXINFO message is sent to a window when the size or position of the window is about to change. An application can use this message to override the window’s default maximized size and position, or its default minimum or maximum tracking size.

bSt = XSetHandler(xWnd, WM_GETMINMAXINFO, xWnd_OnGetMinMaxInfo)

LOGICAL FUNCTION xWnd_OnGetMinMaxInfo(xWnd, xSizeMax, xMaxPos, xMinSize, xMaxSize)

TYPE(X_WINDOW)::                 xWnd
TYPE(X_POINT), INTENT(INOUT)::   xSizeMax
TYPE(X_POINT), INTENT(INOUT)::   xMaxPos
TYPE(X_POINT), INTENT(INOUT)::   xMinSize
TYPE(X_POINT), INTENT(INOUT)::   xMaxSize

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xSizeMax

X_POINT structure specifying the width and the height of maximized window. Function can fill in this structure to override defaults.

xMaxPos

X_POINT structure specifying the X and Y position of upper left corner of maximized window. Function can fill in this structure to override defaults.

xMinSize

X_POINT structure specifying the minimal tracking width and height of the window; user cannot size the window less than that. Function can fill in this structure to override defaults.

xMaxSize

X_POINT structure specifying the maximal tracking width and height of the window; user cannot size the window bigger than that. Function can fill in this structure to override defaults.

Return Value

The function should return .FALSE.

See Also

XSetWindowPos


WM_HELP

WM_HELP

The WM_HELP message indicates that the user pressed the F1 key. If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no window has the keyboard focus, WM_HELP is sent to the currently active window.

bSt = XSetHandler(xWnd, WM_HELP, xWnd_OnHelp)

LOGICAL FUNCTION xWnd_OnHelp(xWnd, bMenu, ID)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN)::         bMenu
INTEGER, INTENT(IN)::         ID

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bMenu

Indicates whether the help is requested for a menu item (.TRUE.) or for a window/control (.FALSE.)

ID

ID of a menu item or a control.

Return Value

The function should return .FALSE.

See Also

WM_KEYDOWN


WM_HOTKEY

WM_HOTKEY

WM_HOTKEY message is sent when when the user presses a hot key registered by the RegisterHotKey function.

bSt = XSetHandler(xWnd, WM_HOTKEY, xWnd_OnHotKey)

LOGICAL FUNCTION xWnd_OnHotKey(xWnd, IDKey)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         IDKey

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

IDKey

Specifies the identifier of the hot key that generated the message. If the message was generated by a system-defined hot key, the idHotKey parameter will be one of the following values:
Value | Meaning
IDHOT_SNAPDESKTOP | The “snap desktop” hot key was pressed.
IDHOT_SNAPWINDOW | The “snap window” hot key was pressed.

Return Value

The function should return .FALSE.


WM_HSCROLL

WM_HSCROLL

WM_HSCROLL message is sent when a scroll event occurs in the window’s standard horizontal scroll bar. This message is also sent to the owner of a horizontal scroll bar control when a scroll event occurs in the control, but that event is better handled by the scrollbar control's event handler registered via XCtlSetSub; if that's the case, this handler is not called.

bSt = XSetHandler(xWnd, WM_HSCOLL, xWnd_OnHScroll)

LOGICAL FUNCTION xWnd_OnHScroll(xWnd, nFlag, nScrollCode, iPos)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nFlag
INTEGER, INTENT(IN)::         nScrollCode
INTEGER, INTENT(IN)::         iPos

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nFlag

If the event occurred in window's standard scrollbar, this value is SB_HORZ; if it is generated by a scrollbar control, it contains handle of scrollbar window.

nScrollCode

Specifies a value that indicates the user’s scrolling request. This parameter can be one of the following values:
Value | Meaning
SB_BOTTOM | Scrolls to the lower right.
SB_ENDSCROLL | Ends scroll.
SB_LINELEFT | Scrolls left by one unit.
SB_LINERIGHT | Scrolls right by one unit.
SB_PAGELEFT | Scrolls left by the width of the window.
SB_PAGERIGHT | Scrolls right by the width of the window.
SB_THUMBPOSITION | Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK | Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP | Scrolls to the upper left.

iPos

Specifies the current position of the scroll box. If the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK, it represents the current position where the thumb is dragged. Otherwise, it represents the position of the scrollbar previously set by a call to XScrollbarSet.

Default Action / Return Value

If the window has set canvas using XSetCanvas, Xeffort handles this message automatically. In that case, SB_PAGE* events scroll the window by the current size of client area; SB_LINE* events scroll the window by 1% of the appropriate canvas dimension; SB_THUMBTRACK and SB_THUMBPOSITION are also handled. If the window has no set up canvas, no action is taken.

The handler should return .TRUE. to suppress that behaviour. Otherwise, return .FALSE.

Remarks

Note that, when user performs an action on a scrollbar (dragging or clicking), its position is not updated automatically unless the canvas is set up. See an example under WM_VSCROLL entry.

See Also

WM_VSCROLL, XSetCanvas, XScrollbarGet, XScrollbarSet


WM_INITMENU

WM_INITMENU

WM_INITMENU message is sent when a menu is about to become active. It occurs when the user clicks an item on the menu bar or presses a menu key. This allows the application to modify the menu before it is displayed.

bSt = XSetHandler(xWnd, WM_INITMENU, xWnd_OnInitMenu)

LOGICAL FUNCTION xWnd_OnInitMenu(xWnd, xMenu)

TYPE(X_WINDOW)::              xWnd
TYPE(X_MENU), INTENT(IN)::    xMenu

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xMenu

X_MENU structure containing the information about the menu.

Return Value

The function should return .FALSE.

Remarks

A WM_INITMENU message is sent only when a menu is first accessed; only one WM_INITMENU message is generated for each access. For example, moving the mouse across several menu items while holding down the button does not generate new messages. WM_INITMENU does not provide information about menu items.

See Also

WM_INITMENUPOPUP, XFTMenu Overview


WM_INITMENUPOPUP

WM_INITMENUPOPUP

WM_INITMENUPOPUP message is sent when a when a drop-down menu or submenu is about to become active. This allows an application to modify the menu before it is displayed, without changing the entire menu.

bSt = XSetHandler(xWnd, WM_INITMENUPOPUP, xWnd_OnInitMenuPopup)

LOGICAL FUNCTION  xWnd_OnInitMenuPopup(xWnd, xMenu, bSystemMenu)

TYPE(X_WINDOW)::              xWnd
TYPE(X_MENU),   INTENT(IN)::    xMenu
LOGICAL, INTENT(IN)::
bSystemMenu

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xMenu

X_MENU structure containing the information about the menu.

bSystemMenu

Specifies whether the drop-down menu is the window menu (also known as the System menu or the Control menu). If the menu is the window menu, this parameter is TRUE; otherwise, it is FALSE.

Remarks

Handling WM_INITMENUPOPUP is the preferred way to modify system menu.

Return Value

The function should return .FALSE.

See Also

WM_INITMENU, XFTMenu Overview


WM_KEYDOWN

WM_KEYDOWN

The WM_KEYDOWN message is posted to the window with the keyboard focus when a nonsystem key (without Alt key) is pressed.

bSt = XSetHandler(xWnd, WM_KEYDOWN, xWnd_OnKeyDown)

LOGICAL FUNCTION xWnd_OnKeyDown(xWnd, nCode, iRepeatCount, iScanCode)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nCode
INTEGER, INTENT(IN)::         iRepeatCount
INTEGER, INTENT(IN)::         iScanCode

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nCode

Character code of the key. Character code is equal to ASCII code for printable characters and you can use CHAR/ACHAR intrinsics to convert them back and forth to characters. For most special characters, that value will be equal to virtual-key code. For non-ASCII characters (with nCode>127), nCode is equal to character position in system code page.

iRepeatCount

Specifies the number of times the keystroke is auto-repeated as a result of longer holding of the key. For the initial strike, this value is zero.

iScanCode

Scan code of the key. Scan code uniquely represents the key in question, unlike nCode. For example, pressing a number "7" on numeric keyboard produces VK_HOME if num lock is off, and VK_NUMPAD7 if num lock is on; however, it has unique scan code of 71.

Return Value

This message is followed by an appropriate WM_CHAR message. Exact character code sent to the WM_CHAR handler depends on the active keyboard layout. Also, WM_HELP (F1), WM_SYSCOMMAND (F10) can be generated depending on nCode.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

See Also

WM_CHAR, WM_KEYUP, Keycodes


WM_KEYUP

WM_KEYUP

WM_KEYUP message is posted to the window with the keyboard focus when a nonsystem key is released. A nonsystem key is a key that is pressed when the alt key is not pressed, or a keyboard key that is pressed when a window has the keyboard focus.

bSt = XSetHandler(xWnd, WM_KEYUP, xWnd_OnKeyUp)

LOGICAL FUNCTION  xWnd_OnKeyUp(xWnd, nCode, iRepeatCount,
iScanCode)

TYPE(X_WINDOW)::              xWnd
INTEGER,  INTENT(IN)::         nCode
INTEGER, INTENT(IN)::         iRepeatCount
INTEGER, INTENT(IN)::         iScanCode

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nCode

Character code of the key. Character code is equal to ASCII code for printable characters and you can use CHAR/ACHAR intrinsics to convert them back and forth to characters. For most special characters, that value will be equal to virtual-key code. For non-ASCII characters (with nCode>127), nCode is equal to character position in system code page.

iRepeatCount

Specifies the number of times the keystroke was auto-repeated as a result of longer holding of the key. For the initial strike, this value is zero.

iScanCode

Scan code of the key. Scan code uniquely represents the key in question, unlike nCode. For example, pressing a number "7" on numeric keyboard produces VK_HOME if num lock is off, and VK_NUMPAD7 if num lock is on; however, it has unique scan code of 71.

Default Action / Return Value

The system function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

See Also

WM_CHAR, WM_KEYDOWN


WM_KILLFOCUS

WM_KILLFOCUS

WM_KILLFOCUS message is sent to the window immediately before it loses the keyboard focus.

bSt = XSetHandler(xWnd, WM_KILLFOCUS, xWnd_OnKillFocus)

LOGICAL FUNCTION xWnd_OnKillFocus(xWnd, xWndFocus)

TYPE(X_WINDOW)::              xWnd
TYPE(X_WINDOW)::              xWndFocus

Arguments

xWnd

X_WINDOW structure containing information about the window which loses the focus.

xWndFocus

X_WINDOW structure containing information about the window which gains the focus. May be NULL.

Return Value

The function should return .FALSE.

See Also

WM_SETFOCUS


WM_LBUTTONDBLCLK

WM_LBUTTONDBLCLK

WM_LBUTTONDBLCLK message is posted when the user double-clicks the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_LBUTTONDBLCLK, xWnd_OnLButtonDblClk)

LOGICAL FUNCTION xWnd_OnLButtonDblClk(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always Has value WM_LBUTTONDBLCLK. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguisehd by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Return Value

Default Xeffort windows do nothing, but windows of other classes can process this message.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

This message is preceded by a WM_LBUTTONDOWN/WM_LBUTTONUP pair for the first click. This message arrives only after the second click. Thus, if an application handles both WM_LBUTTONUP and WM_LBUTTONDBLCLK, it should take care that the two behaviors don't clash. For example, if a message box is displayed on WM_LBUTTONUP, the WM_LBUTTONDBLCLK will never be received, because activation will be transferred to the message box.

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

See Also

WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_MOUSEMOVE


WM_LBUTTONDOWN

WM_LBUTTONDOWN

WM_LBUTTONDOWN message is posted when the user presses the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_LBUTTONDOWN, xWnd_OnLButtonDown)

LOGICAL FUNCTION xWnd_OnLButtonDown(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always has value WM_LBUTTONDOWN. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguisehd by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Default Action / Return Value

Default Xeffort windows do nothing, but windows of other classes can process this message.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

See Also

WM_LBUTTONUP, WM_LBUTTONDBLCK, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_MOUSEMOVE


WM_LBUTTONUP

WM_LBUTTONUP

The WM_LBUTTONUP message is posted when the user releases the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_LBUTTONUP, xWnd_OnLButtonUp)

LOGICAL FUNCTION xWnd_OnLButtonUp(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always has value WM_LBUTTONUP. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguisehd by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Default Action / Return Value

Default Xeffort windows do nothing, but windows of other classes can process this message.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

See Also

WM_LBUTTONDOWN, WM_LBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_MOUSEMOVE


WM_MDIACTIVATE

WM_MDIACTIVATE

An application sends the WM_MDIACTIVATE message to a multiple document interface (XW_MDI) client window to instruct the client window to activate a different MDI child window. As the client window processes this message, it sends WM_MDIACTIVATE to the child window being deactivated and to the child window being activated.

bSt = XSetHandler(xWnd, WM_MDIACTIVATE, xWnd_OnMdiActivate)

LOGICAL FUNCTION xWnd_OnMdiActivate(xWnd, xWndDeact)

TYPE(X_WINDOW)::              xWnd
TYPE(X_WINDOW)::              xWndDeact

Arguments

xWnd

X_WINDOW structure containing information about the MDI child window to be activated.

xWndDeact

X_WINDOW structure containing information about the MDI child window to be deactivated.

Return Value

The function should return .FALSE.

Remarks

An MDI child window is activated independently of the MDI frame window. When the frame window becomes active, the child window last activated by using this message receives the WM_NCACTIVATE message to draw an active window frame and title bar; the child window does not receive another WM_MDIACTIVATE message.

See Also

WM_CHILDACTIVATE, XMDISetActive


WM_MDIACTIVATE

WM_MDIDESTROY

MDI Client window (globally known as XW_MDI) receives WM_MDIDESTROY message when its child window is destroyed using XMDIDestroy or closed by the user. An application can handle this message, for example, in order to keep track of MDI child count.

bSt = XSetHandler(xWnd, WM_MDIDESTROY, xWnd_OnMdiDestroy)

LOGICAL FUNCTION xWnd_OnMdiDestroy(xWnd, xWndDestroy)

TYPE(X_WINDOW)::              xWnd
TYPE(X_WINDOW)::              xWndDestroy

Arguments

xWnd

X_WINDOW structure containing information about the MDI client window (XW_MDI).

xWndDestroy

X_WINDOW structure containing information about the MDI child window which is about to be destroyed.

Default Action / Return Value

By default, the MDI child window xWndDestroy is destroyed.

The function should return .TRUE. to prevent default processing, and .FALSE. otherwise.

See Also

WM_MDIACTIVATE, XMDIDestroy


WM_MOUSEACTIVATE

WM_MOUSEACTIVATE

The WM_MOUSEACTIVATE message is sent when the cursor is in an inactive window and the user presses a mouse button. The parent window receives this message only if the child window passes it to the DefWindowProc function.

bSt = XSetHandler(xWnd, WM_MOUSEACTIVATE, xWnd_OnMouseActivate)

INTEGER
FUNCTION xWnd_OnMouseActivate(xWnd, nHitTest)

TYPE(X_WINDOW)::              xWnd
INTEGER,  INTENT(IN)::         nHitTest

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nHitTest

Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

Return Value

The return value specifies whether the window should be activated and whether the identifier of the mouse message should be discarded. It must be one of the following values:

Value | Meaning
MA_ACTIVATE | Activates the window, and does not discard the mouse message.
MA_ACTIVATEANDEAT | Activates the window, and discards the mouse message.
MA_NOACTIVATE | Does not activate the window, and does not discard the mouse message.
MA_NOACTIVATEANDEAT | Does not activate the window, but discards the mouse message.

See Also

WM_ACTIVATE, WM_NCACTIVATE


WM_MOUSEMOVE

WM_MOUSEMOVE

WM_MOUSEMOVE message is posted to a window when the cursor moves in its client area. If the mouse is not captured, the message is posted to the window that contains the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_MOUSEMOVE, xWnd_OnMouseMove)

LOGICAL FUNCTION xWnd_OnMouseMove(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always Has value WM_MOUSEMOVE. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguisehd by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Default Action / Return Value

A WM_SETCURSOR message is generated. See its documentation for details.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

See Also

WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_LBUTTONDBLCLK


WM_MOUSEWHEEL

WM_MOUSEWHEEL

The WM_MOUSEWHEEL message is sent to the focus window when the mouse wheel is rotated.

bSt = XSetHandler(xWnd, WM_MOUSEWHEEL, xWnd_OnMouseWheel)

LOGICAL FUNCTION xWnd_OnMouseWheel(xWnd, nDelta, iX, iY, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nDelta
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nDelta

Indicates the distance that the wheel is rotated, expressed in multiples or divisions of WHEEL_DELTA, which is 120. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user.

iX, iY

Client coordinates of the point where the mouse event occurred.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Default Action / Return Value

If the window has a vertical scrollbar, Xeffort automatically moves the scrolls thumb up or down. A single unit wheel movement results in scrolling by 2% of scrollbar's extent (nMax-nMin).

The handler should return .TRUE. to suppress that behaviour. Otherwise, return .FALSE..

See Also

XSetCanvas, XScrollbarSet


WM_MOVE

WM_MOVE

The WM_MOVE message is sent after a window has been moved.

bSt = XSetHandler(xWnd, WM_MOVE, xWnd_OnMove)
LOGICAL FUNCTION xWnd_OnMove(xWnd, iX, iY)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Position of window's top-left corner. It is expressed in screen coordinates for overlapped and pop-up windows and in parent-client coordinates for child windows.

Default Action / Return Value

No default action is taken. The function should return .FALSE.

Remarks

The system can't prevent the window from being (or control its movement limits) moved by processing this message. Instead, handle WM_WINDOWPOSCHANGING.

See Also

WM_SIZE, WM_WINDOWPOSCHANGED, WM_WINDOWPOSCHANGING


WM_NCACTIVATE

WM_NCACTIVATE

The WM_NCACTIVATE message is sent to a window when its nonclient area needs to be changed to indicate an active or inactive state.

bSt = XSetHandler(xWnd, WM_NCACTIVATE, xWnd_OnNCActivate)

LOGICAL FUNCTION xWnd_OnNcactivate(xWnd, bActivate)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN)::         bActivate

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bActivate

X_WINDOW structure containing information about the window where the event occurred.

Default Action / Return Value

The window's caption is drawn in system colors to indicate active or inactive state.

The function should return .FALSE. to indicate that the system should proceed with the default processing, or .TRUE. to

See Also

WM_ACTIVATE, WM_ACTIVATEAPP, WM_SETFOCUS


WM_NCDESTROY

WM_NCDESTROY

The WM_NCDESTROY message informs a window that its nonclient area is being destroyed. The DestroyWindow function sends the WM_NCDESTROY message to the window following the WM_DESTROY message. WM_NCDESTROY is the last message sent to the window, and thus should be used to free any allocated memory objects associated with the window.

bSt = XSetHandler(xWnd, WM_NCDESTROY, xWnd_OnNCDestroy)

LOGICAL FUNCTION xWnd_OnNCDestroy(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Return Value

The function should return .FALSE.

See Also

WM_DESTROY


WM_NCHITTEST

WM_NCHITTEST

The WM_NCHITTEST message is sent to a window when the cursor moves, or when a mouse button is pressed or released. If the mouse is not captured, the message is sent to the window beneath the cursor. Otherwise, the message is sent to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_NCHITTEST, xWnd_OnNCHitTest)

INTEGER
FUNCTION  xWnd_OnNCHitTest(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER,  INTENT(IN)::         iX
INTEGER,  INTENT(IN)::         iY
INTEGER,  INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located:

Value | Location of hot spot
HTBORDER | In the border of a window that does not have a sizing border
HTBOTTOM | In the lower horizontal border of a resizable window (the user can click the mouse to resize the window vertically)
HTBOTTOMLEFT | In the lower-left corner of a border of a resizable window (the user can click the mouse to resize the window diagonally)
HTBOTTOMRIGHT | In the lower-right corner of a border of a resizable window (the user can click the mouse to resize the window diagonally)
HTCAPTION | In a title bar
HTCLIENT | In a client area
HTCLOSE | In a close button
HTERROR | On the screen background or on a dividing line between windows (same as HTNOWHERE, except that the DefWindowProc function produces a system beep to indicate an error)
HTGROWBOX | In a size box (same as HTSIZE)
HTHELP | In a Help button
HTHSCROLL | In a horizontal scroll bar
HTLEFT | In the left border of a resizable window (the user can click the mouse to resize the window horizontally)
HTMENU | In a menu
HTMAXBUTTON | In Maximize button
HTMINBUTTON | In Minimize button
HTNOWHERE | On the screen background or on a dividing line between windows
HTREDUCE | In a Minimize button
HTRIGHT | In the right border of a resizable window (the user can click the mouse to resize the window horizontally)
HTSIZE | In a size box (same as HTGROWBOX)
HTSYSMENU | In a System menu or in a Close button in a child window
HTTOP | In the upper horizontal border of a window
HTTOPLEFT | In the upper-left corner of a window border
HTTOPRIGHT | In the upper right corner of a window border
HTTRANSPARENT | In a window currently covered by another window in the same thread (the message will be sent to underlying windows in the same thread until one of them returns a code that is not HTTRANSPARENT)
HTVSCROLL | In the vertical scroll bar
HTZOOM | In a Maximize button

Default Action / Return Value

This message is only interrogating, i.e. the system just queries the window on which part of it is the cursor located. However, the return value significantly affects behavior of the window. For example, always returning HTCAPTION would cause that the window can be moved by mouse wherever it's clicked, but in the same time prevents any client mouse message (like WM_MOUSEMOVE) to be generated, because the system will never conclude that the cursor is over client area.

Normally, the function should return the value of nWhere argument. However, it may return some other HTxxx code instead, changing window's behavior. For example, an application can enable a captionless window to be moved whenever the mouse is anywhere in the client area using the following function:

INTEGER FUNCTION
XWindow_OnNcHitTest(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER,  INTENT(IN)::         iX
INTEGER,  INTENT(IN)::         iY
INTEGER,  INTENT(IN)::         nWhere

IF (nWhere == HTCLIENT) THEN
XWindow_OnNcHitTest = HTCAPTION
ELSE
XWindow_OnNcHitTest = nWhere
END IF

END FUNCTION XWindow_OnNcHitTest


WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDBLCLK message is posted when the user double-clicks the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCLBUTTONDBLCLK, xWnd_OnNCLButtonDblClk)

LOGICAL FUNCTION xWnd_OnNCLButtonDblClk(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Return Value

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_NCMOUSEMOVE, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP


WM_NCLBUTTONDOWN

WM_NCLBUTTONDOWN

The WM_NCLBUTTONDOWN message is posted when the user presses the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCLBUTTONDOWN, xWnd_OnNCLButtonDown)

LOGICAL FUNCTION xWnd_OnNCLButtonDown(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONUP, WM_NCLBUTTONDBLCLK, WM_NCMOUSEMOVE, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP


WM_NCLBUTTONUP

WM_NCLBUTTONUP

WM_NCLBUTTONUP message is posted when the user releases the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCLBUTTONUP, xWnd_OnNCLButtonUp)

LOGICAL FUNCTION xWnd_OnNCLButtonUp(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONDBLCLK, WM_NCMOUSEMOVE, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP


WM_NCMOUSEMOVE

WM_NCMOUSEMOVE

The WM_NCMOUSEMOVE message is posted to a window when the cursor is moved within the nonclient area of the window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCMOUSEMOVE, xWnd_OnNCMouseMove)

LOGICAL FUNCTION xWnd_OnNCMouseMove(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action (e.g. set a sizing cursor when the mouse is located over window's frame).

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONUP, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP


WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDBLCLK message is posted when the user double-clicks the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCRBUTTONDBLCLK, xWnd_OnNCRButtonDblClk)

LOGICAL FUNCTION xWnd_OnNCRButtonDblClk(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_NCMOUSEMOVE, WM_NCLBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP


WM_NCRBUTTONDOWN

WM_NCRBUTTONDOWN

WM_NCRBUTTONDOWN message is posted when the user presses the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCRBUTTONDOWN, xWnd_OnNCRButtonDown)

LOGICAL FUNCTION xWnd_OnNCRButtonDown(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONUP, WM_NCLBUTTONDOWN, WM_NCLBUTTONDBLCLK, WM_NCMOUSEMOVE, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONUP


WM_NCRBUTTONUP

WM_NCRBUTTONUP

WM_NCRBUTTONUP message is posted when the user releases the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted.

bSt = XSetHandler(xWnd, WM_NCRBUTTONUP, xWnd_OnNCRButtonUp)

LOGICAL FUNCTION xWnd_OnNCRButtonUp(xWnd, iX, iY, nWhere)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX
INTEGER, INTENT(IN)::         iY
INTEGER, INTENT(IN)::         nWhere

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Cursor position, in screen coordinates

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

Default Action / Return Value

By default, the given point is tested to find out the location of the cursor and performs the appropriate action. If appropriate, the WM_SYSCOMMAND message is sent to the window.

To prevent this behavior, return .TRUE.; otherwise, return .FALSE.

See Also

WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_NCLBUTTONDBLCLK, WM_NCMOUSEMOVE, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN


WM_PAINT

WM_PAINT

WM_PAINT message is sent when the system or another application makes a request to paint a portion of an application's window. The message can be generated as result of a change of window's visible area (the window goes foreground, user drags another window over it etc.) or by a call to XUpdateWindow routine.

bSt = XSetHandler(xWnd, WM_PAINT, xWnd_OnPaint)

LOGICAL FUNCTION xWnd_OnPaint(xWnd, xDC, iX1, iY1, iX2, iY2)

TYPE(X_WINDOW)::              xWnd
TYPE(X_DC), INTENT(INOUT)::   xDC
INTEGER, INTENT(IN)::         iX1, iY1, iX2, iY2

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xDC

X_DC structure containing information about the window's device context. The function should pass this argument to draw using XFTGDI routines.

If the window's canvas is not set up using XSetCanvas, both viewport and the window of the DC are set to (0., 0., ClientAreaWidth, ClientAreaHeight). Otherwise, the viewport is set up to (-iPosX, -iPosY, iCanvasX-iPosX, iCanvasY-iPosY), and the window to (0., 0., iCanvasX, iCanvasY), i.e. the viewport is offset for the current scrollbar position, and its dimensions are equal to canvas dimensions; the logical coordinate system has unit-scaling to the viewport.

iX1, iY1, iX2, iY2

Bounding coordinates of the update rectangle, in physical coordinates (which are same as default viewport coordinates). The update rectangle is the portion of window which needs to be repainted. The application can utilize these coordinates to optimize drawing by redrawing only in the update rectangle.

Default Action / Return Value

Native Xeffort windows (of class "XWndClass") do not do any painting by default. Thus, their client area appears (temporarily) transparent. An application thus should perform at least a minimal painting (such as using XFillViewport) in order to fill in the contents of the client area. The return value should be .FALSE.

Remarks

Contrary to what one might initially think, the system does not keep contents of active applications' windows buffered anywhere. Instead, whenever any of the application's windows is revealed and has to be redrawn, system informs the application by sending it WM_PAINT message; it is up to the application to decide what should be drawn in its client area.

When no double-buffering is used, but the image is drawn directly in response to WM_PAINT, flickering occurs during window resizing. Thus, any drawing of non-trivial complexity should be performed using double-buffering. If the window has Xeffort-specific XS_EX_DBLBUFFERED extended style, Xeffort library does double-buffering for you. That means that it creates a memory DC using XMemoryDC, calls your WM_PAINT handler to draw on that DC, and then uses XBitCopy to copy memory DC contents onto window's client DC.

When a really efficient drawing is required, an application can utilize double-buffering itself (in that case, it should not use XS_EX_DBLBUFFERED style), as Xeffort internal double-buffering must XBitCopy entire contents of client area to ensure consistent behavior. Double-buffering consists of creating a memory (offscreen) DC, drawing onto it somewhere outside of WM_PAINT, and "copying & pasting" the bitmap into window's DC using XBitCopy function:

!Elsewhere (e.g. in XInit)
xMemDC = XMemoryDC(xDC, 1024, 768)
!===================
INTEGER FUNCTION XWindow_OnPaint(xWnd, xDC, iX1, iY1, iX2, iY2)
USE XFTTYPES
USE MY_XDC, ONLY: xMemDC
TYPE(X_WINDOW)::              xWnd
TYPE(X_DC), INTENT(INOUT)::   xDC
INTEGER, INTENT(IN)::         iX1, iY1, iX2, iY2

LOGICAL::                     bSt

bSt = XBitCopy(xDC, iX1, iY1, iX2, iY2, xMemDC, iX1, iY1)
XWindow_OnPaint = .TRUE.

END FUNCTION XWindow_OnPaint
!===================
SUBROUTINE DrawMyData()
USE MY_XDC, ONLY: xMemDC

!Erase background to white
XFillViewport(XMemDC, xBrush=X_BRUSH(BS_SOLID, XCOLOR_WHITE, 0))
!TODO your drawing here
XUpdateWindow(xWnd) !Force WM_PAINT to be generated for entire window

END SUBROUTINE DrawMyData

In the sample, DrawMyData should be called to refresh window contents whenever appropriate (i.e. the image has changed). The preferred way for associating an offscreen DC to a window is using XSetWindowData/XGetWindowData functions instead of using global xMemDC as in code above.

See Also

WM_ERASEBKGND, XSetCanvas, XFTGDI Overview


WM_QUERYENDSESSION

WM_QUERYENDSESSION

The WM_QUERYENDSESSION message informs the application that the Windows session is ending. An application should respond whether it can terminate gracefully (.TRUE.) or not, in which case the session is not ended.

bSt = XSetHandler(xWnd, WM_QUERYENDSESSION, xWnd_OnQueryEndSession)

LOGICAL FUNCTION xWnd_OnQueryEndSession(xWnd, bLogOff)

TYPE(X_WINDOW)::              xWnd
LOGICAL, INTENT(IN) ::        bLogOff

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

bLogOff

Specifies whether the user is logging off (.TRUE.) or shutting down (.FALSE.).

Return Value

The function should return .TRUE. if it can terminate gracefully or .FALSE. otherwise. If .TRUE. is returned, WM_ENDSESSION message will follow.

See Also

WM_ENDSESSION


WM_RBUTTONDOWN

WM_RBUTTONDOWN

WM_RBUTTONDOWN message is posted when the user presses the left mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_RBUTTONDOWN, xWnd_OnRButtonDown)

LOGICAL FUNCTION xWnd_OnRButtonDown(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always Has value WM_RBUTTONDOWN. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguisehd by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Return Value

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

For purpose of displaying context menus, it is preferred to handle WM_CONTEXTMENU instead.

See Also

WM_LBUTTONDOWN, WM_LBUTTONDBLCK, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_MOUSEMOVE, WM_CONTEXTMENU


WM_RBUTTONUP

WM_RBUTTONUP

The WM_RBUTTONUP message is posted when the user releases the right mouse button while the cursor is in the client area of a window. If the mouse is not captured, the message is posted to the window beneath the cursor. Otherwise, the message is posted to the window that has captured the mouse.

bSt = XSetHandler(xWnd, WM_RBUTTONUP, xWnd_OnRButtonUp)

LOGICAL FUNCTION xWnd_OnRButtonUp(xWnd, iX, iY, Msg, iKeyState)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         Msg
INTEGER, INTENT(IN)::         iKeyState

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Client coordinates of the point where the mouse event occurred.

Msg

Always has value WM_RBUTTONUP. Since all mouse event functions have the same prototype, one function can serve as event handler for several mouse messages at the same time. In this case, the events can be distinguished by Msg parameter.

iKeyState

Indicates whether various virtual keys are down. This parameter can be any combination of the following values:
Value | Description
MK_CONTROL | Set if the ctrl key is down.
MK_LBUTTON | Set if the left mouse button is down.
MK_MBUTTON | Set if the middle mouse button is down.
MK_RBUTTON | Set if the right mouse button is down.
MK_SHIFT | Set if the shift key is down.

Default Action / Return Value

A WM_CONTEXTMENU message is generated. Default Xeffort windows do nothing on WM_CONTEXTMENU, but certain window classes may display a context menu.

The function should return .FALSE. if it wants default processing or .TRUE. otherwise.

Remarks

All mouse event functions have the same prototype, thus the function can serve as event handler for several mouse messages at the same time.

For the purpose of displaying context menus, it is preferred to handle WM_CONTEXTMENU instead.

See Also

WM_LBUTTONDOWN, WM_LBUTTONDBLCLK, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_MOUSEMOVE, WM_CONTEXTMENU


WM_SETCURSOR

WM_SETCURSOR

WM_SETCURSOR message is sent to a window if the mouse causes the cursor to move within a window and mouse input is not captured.

bSt = XSetHandler(xWnd, WM_SETCURSOR, xWnd_OnSetCursor)

LOGICAL FUNCTION xWnd_OnSetCursor(xWnd, nWhere, iMsg)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nWhere
INTEGER, INTENT(IN)::         iMsg

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nWhere

Indicates the area on the window where the cursor is located. See WM_NCHITTEST.

iMsg

Identifier of the mouse message that caused the message to be triggered. Can be one of WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_NCMOUSEMOVE etc.

Default Action / Return Value

Default processing by Xeffort library is to display the cursor set by XSetCursor or XStdCursor in client area of the window; if none is set, DefWindowProc sets the default cursor which depends on window class (usually, normal arrow cursor).

The function should return .FALSE. if it wants the default processing.

See Also

XSetCursor, XStdCursor, WM_NCHITTEST, WM_MOUSEMOVE


WM_SETFOCUS

WM_SETFOCUS

WM_SETFOCUS message is sent to a window after it has gained the keyboard focus.

bSt = XSetHandler(xWnd, WM_SETFOCUS, xWnd_OnSetFocus)

LOGICAL FUNCTION xWnd_OnSetFocus(xWnd, xWndLose)

TYPE(X_WINDOW)::              xWnd
TYPE(X_WINDOW)::              xWndLose

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

xWndLose

X_WINDOW structure containing information about the window which loses the focus. May be NULL.

Return Value

The function should return .FALSE.

See Also

WM_KILLFOCUS, WM_ACTIVATE


WM_SIZE

WM_SIZE

The WM_SIZE message is sent to a window after its size has changed. An application should handle this message for top-level windows which need to resort the placement of its child windows when the size changes. Also, if the window displays scrollbars but has no canvas set using XSetCanvas, the handler routine should adjust the scrollbar thumb.

bSt = XSetHandler(xWnd, WM_SIZE, xWnd_OnSize)

LOGICAL FUNCTION xWnd_OnSize(xWnd, iWidht, iHeight, nFlag)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iWidth, iHeight
INTEGER, INTENT(IN)::         nFlag

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iWidth, iHeight

Width and height of windows client area.

nFlag

Specifies the type of resizing requested.

Value | Meaning
SIZE_MAXHIDE | Message is sent to all pop-up windows when some other window is maximized.
SIZE_MAXIMIZED | The window has been maximized.
SIZE_MAXSHOW | Message is sent to all pop-up windows when some other window has been restored to its former size.
SIZE_MINIMIZED | The window has been minimized.
SIZE_RESTORED | The window has been resized, but neither the SIZE_MINIMIZED nor SIZE_MAXIMIZED value applies

Default Action / Return Value

If the window has set canvas using XSetCanvas, Xeffort sets up the scrollbar so that:

  • If the canvas dimension is smaller than appropriate client area dimension, the scrollbar is hidden

  • Otherwise, the scrollbar is displayed and its thumb size is set equal to appropriate client area dimension. Scrollbar position is not affected.

The handler should return .TRUE. to suppress that behaviour. Otherwise, return .FALSE.

See Also

XSetCanvas, WM_MOVE, WM_GETMINMAXINFO, XScrollbarSet


WM_SYSCOLORCHANGE

WM_SYSCOLORCHANGE

WM_SYSCOLORCHANGE message is sent to all top-level windows (XW_FRAME and all popup windows) when a change is made to a system color setting.

bSt = XSetHandler(xWnd, WM_SYSCOLORCHANGE, xWnd_OnSysColorChange)

LOGICAL FUNCTION xWnd_OnSysColorChange(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window.

Default Action / Return Value

Xeffort broadcasts this message to all child windows of the given window. That enables that the controls are redrawn properly in new system colors.

The function should return .TRUE. to prevent default processing, otherwise false.


WM_SYSCOMMAND

WM_SYSCOMMAND

WM_SYSCOMMAND message is sent when the user chooses a command from the window menu (formerly known as the system or control menu) or when the user chooses the maximize button, minimize button, restore button, or close button.

bSt = XSetHandler(xWnd, WM_SYSCOMMAND, xWnd_OnSysCommand)

LOGICAL FUNCTION xWnd_OnSysCommand(xWnd, nCommand)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nCommand

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nCommand

Specifies the type of system command requested. This parameter can be one of the following values.
Value | Meaning
SC_CLOSE | Closes the window.
SC_CONTEXTHELP | Changes the cursor to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message.
SC_DEFAULT | Selects the default item; the user double-clicked the window menu.
SC_HOTKEY | Activates the window associated with the application-specified hot key. The low-order word of lParam identifies the window to activate.
SC_HSCROLL | Scrolls horizontally.
SC_KEYMENU | Retrieves the window menu as a result of a keystroke.
SC_MAXIMIZE | Maximizes the window.
SC_MINIMIZE | Minimizes the window.
SC_MONITORPOWER | Sets the state of the display. This command supports devices that have power-saving features, such as a battery-powered personal computer.
SC_MOUSEMENU | Retrieves the window menu as a result of a mouse click.
SC_MOVE | Moves the window.
SC_NEXTWINDOW | Moves to the next window.
SC_PREVWINDOW | Moves to the previous window.
SC_RESTORE | Restores the window to its normal position and size.
SC_SCREENSAVE | Executes the screen saver application specified in the [boot] section of the SYSTEM.INI file.
SC_SIZE | Sizes the window.
SC_TASKLIST | Activates the Start menu.
SC_VSCROLL | Scrolls vertically

Default Action / Return Value

Depending on the value of nCommand, the system will perform appropriate action. For example, if nCommand is SC_CLOSE, a WM_CLOSE message will be generated.

The function should return .TRUE. to prevent default processing.

See Also

WM_COMMAND


WM_TIMECHANGE

WM_TIMECHANGE

WM_TIMECHANGE message is sent when system time is changed.

bSt = XSetHandler(xWnd, WM_TIMECHANGE, xWnd_OnTimeChange)

LOGICAL FUNCTION xWnd_OnTimeChange(xWnd)

TYPE(X_WINDOW)::              xWnd

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

Return Value

The function should return .FALSE.


WM_TIMER

WM_TIMER

WM_TIMER message is sent when a timer event is triggered. A timer can be installed using SetTimer API.

bSt = XSetHandler(xWnd, WM_TIMER, xWnd_OnTimer)

LOGICAL FUNCTION xWnd_OnTimer(xWnd, idTimer)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         idTimer

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

idTimer

Identifier of the timer.

Return Value

The function should return .FALSE.


WM_VSCROLL

WM_VSCROLL

WM_VSCROLL message is sent when a scroll event occurs in the window’s standard vertical scroll bar. This message is also sent to the owner of a vertical scroll bar control when a scroll event occurs in the control, but that event is better handled by the scrollbar control's event handler registered via XCtlSetSub; if that's the case, this handler is not called.

bSt = XSetHandler(xWnd, WM_VSCROLL, xWnd_OnVscroll)

LOGICAL FUNCTION xWnd_OnVscroll(xWnd, nFlag, nScrollCode, iPos)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         nFlag
INTEGER, INTENT(IN)::         nScrollCode
INTEGER, INTENT(IN)::         iPos

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

nFlag

If the event occurred in window's standard scrollbar, this value is SB_VERT; if it is generated by a scrollbar control, it contains handle of scrollbar window.

nScrollCode

Specifies a value that indicates the user’s scrolling request. This parameter can be one of the following values:
Value | Meaning
SB_BOTTOM | Scrolls to the lower right.
SB_ENDSCROLL | Ends scroll.
SB_LINEDOWN | Scrolls down by one unit.
SB_LINEUP | Scrolls up by one unit.
SB_PAGEDOWN | Scrolls down by the height of the window.
SB_PAGEUP | Scrolls up by the height of the window.
SB_THUMBPOSITION | Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK | Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP | Scrolls to the upper left.

iPos

Specifies the current position of the scroll box. If the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK, it represents the current position where the thumb is dragged. Otherwise, it represents the position of the scrollbar previously set by a call to XScrollbarSet.

Default Action / Return Value

If the window has set canvas using XSetCanvas, Xeffort handles this message automatically. In that case, SB_PAGE* events scroll the window by the current size of client area; SB_LINE* events scroll the window by 1% of the appropriate canvas dimension; SB_THUMBTRACK and SB_THUMBPOSITION are also handled. If the window has no set up canvas, no action is taken.

The handler should return .TRUE. to suppress that behaviour. Otherwise, return .FALSE.

Example

If the canvas is absent, when user performs an action on a scrollbar (dragging or clicking), its position is not updated automatically. You should use XScrollbarSet function to adjust the position permanently:

LOGICAL FUNCTION XW_FRAME_OnVScroll(xWnd, nFlag, nScrollCode, iPos)

TYPE(X_WINDOW)::      xWnd
INTEGER, INTENT(IN)::         nFlag
INTEGER, INTENT(IN)::         nScrollCode
INTEGER, INTENT(IN)::         iPos
INTEGER::
newPos, iPage
LOGICAL::
bSt

bSt = XScrollbarGet(xWnd, SB_VERT, iPage=iPage)
newPos = iPos
SELECT CASE (nScrollCode)
CASE(SB_LINEUP)
newPos = iPos - 10    !Subtract
10 pixels
CASE(SB_LINEDOWN)
newPos = iPos + 10    !Add 10
pixels
CASE(SB_PAGEUP)
newPos = iPos - iPage !Subtract one page
CASE(SB_PAGEDOWN)
newPos = iPos + iPage !Add one page
CASE(SB_THUMBTRACK, SB_THUMBPOSITION)
newPos = iPos         !Enable
redrawing while the thumb is dragged
END SELECT
bSt = XScrollbarSet(xWnd, SB_VERT, newPos)

END FUNCTION  XW_FRAME_OnVScroll

See Also

WM_HSCROLL, XSetCanvas, XScrollbarGet, XScrollbarSet


WM_WINDOWPOSCHANGED

WM_WINDOWPOSCHANGED

The WM_WINDOWPOSCHANGED message is sent to a window whose size, position, or place in the Z order has changed as a result of a call to the SetWindowPos function or another window-management function.

bSt = XSetHandler(xWnd, WM_WINDOWPOSCHANGED, xWnd_OnWindowPosChanged)

LOGICAL FUNCTION xWnd_OnWindowPosChanged(xWnd, iX, iY, iWidth, iHeight, nFlags)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         iWidth, iHeight
INTEGER, INTENT(IN)::         nFlags

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Position of the top left corner of the window

iWidth, iHeight

Window dimensions, in pixels

nFlags

An OR combination of the following SWP_flags.

Value | Meaning
SWP_DRAWFRAME | Draws a frame (defined in the window's class description) around the window.
SWP_FRAMECHANGED | Sends a WM_NCCALCSIZE message to the window, even if the window's size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window's size is being changed.
SWP_HIDEWINDOW | Hides the window.
SWP_NOACTIVATE | Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS | Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE | Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER | Does not change the owner window's position in the Z order.
SWP_NOREDRAW | Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION | Same as the SWP_NOOWNERZORDER flag.
SWP_NOSIZE | Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER | Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW | Displays the window.

Return Value

The function should return .FALSE.

See Also

XSetWindowPos, WM_WINDOWPOSCHANGING


WM_WINDOWPOSCHANGING

WM_WINDOWPOSCHANGING

WM_WINDOWPOSCHANGING message is sent when a window's size, position or place in the Z order is about to change as a result of a call to the XSetWindowPos function or another window-management function.

bSt = XSetHandler(xWnd, WM_WINDOWPOSCHANGING, xWnd_OnWindowPosChanging)

LOGICAL FUNCTION xWnd_OnWindowPosChanging(xWnd, iX, iY, iWidth, iHeight, nFlags)

TYPE(X_WINDOW)::              xWnd
INTEGER, INTENT(IN)::         iX, iY
INTEGER, INTENT(IN)::         iWidth, iHeight
INTEGER, INTENT(IN)::         nFlags

Arguments

xWnd

X_WINDOW structure containing information about the window where the event occurred.

iX, iY

Position of the top left corner of the window

iWidth, iHeight

Window dimensions, in pixels

nFlags

An OR combination of the following SWP_flags.

Value | Meaning
SWP_DRAWFRAME | Draws a frame (defined in the window's class description) around the window.
SWP_FRAMECHANGED | Sends a WM_NCCALCSIZE message to the window, even if the window's size is not being changed. If this flag is not specified, WM_NCCALCSIZE is sent only when the window's size is being changed.
SWP_HIDEWINDOW | Hides the window.
SWP_NOACTIVATE | Does not activate the window. If this flag is not set, the window is activated and moved to the top of either the topmost or non-topmost group (depending on the setting of the hWndInsertAfter parameter).
SWP_NOCOPYBITS | Discards the entire contents of the client area. If this flag is not specified, the valid contents of the client area are saved and copied back into the client area after the window is sized or repositioned.
SWP_NOMOVE | Retains the current position (ignores the X and Y parameters).
SWP_NOOWNERZORDER | Does not change the owner window's position in the Z order.
SWP_NOREDRAW | Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the window being moved. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.
SWP_NOREPOSITION | Same as the SWP_NOOWNERZORDER flag.
SWP_NOSIZE | Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER | Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW | Displays the window.

Return Value

The function should return .TRUE. to prevent requested changing; otherwise, it should return .FALSE.

See Also

XSetWindowPos, WM_WINDOWPOSCHANGED


X_NM_ macros

List of X_NM_ Macros

When a command handler routine is called, its third parameter is a code describing nature of the event. For many events, an additional information is carried, and it can be retrieved from the command handler using one of macros listed below.

Each nCode argument received in the command handler maps to exactly one larger structure. The handler routine can examine nCode, and if necessary, cast it to appropriate structure. nCode depends on control type and the event that occurred. For example:

LOGICAL FUNCTION xChild_OnListViewEvent(xWnd, ID, nCode)

USE XFTNotify

TYPE(X_WINDOW)::          xWnd
INTEGER, INTENT(IN)::     ID
INTEGER, INTENT(IN)::     nCode

TYPE(T_NMLISTVIEW), POINTER:: NML
...
IF (nCode==LVN_ITEMCHANGED) THEN
   NML => X_NMLISTVIEW(nCode)
   IF (IAND(NML%uChanged,LVIF_TEXT) /= 0) THEN
      !User changed the text of the item
      ...

When an item in ListView control is changed, command handler is called with nCode = LVN_ITEMCHANGED. nCode can then be casted to T_NMLISTVIEW structure, which contains additional information about the event.

Note 1: X_NM_ macros are available only by USE XFTNotify statement, which is not USEd in MODULE Xeffort. These macros depend on definition of appropriate T_NM_ structures in DFWIN. File XFTNotify.f90 may not compile under older CVF versions due to lack of definitions.

Note 2: These macros operate only on original nCode variable received through argument list. Attempt to operate on a copy will produce garbage results:

iCode = nCode
IF (iCode==LVN_ITEMCHANGED) THEN
   NML => X_NMLISTVIEW(iCode)       !Returns a garbage or produces run-time error

The following NM_ macros are available. Each X_Foo macro returns a pointer to a structure of type T_Foo:

Macro | nCode | Applies to
X_PSHNOTIFY | PSN_* | Property sheets
X_OFNOTIFY | CDN_* | OPENFILENAME hook procedure
X_OFNOTIFYW | CDN_* | OPENFILENAME hook procedure
X_OFNOTIFYEX | CDN_INCLUDEITEM | OPENFILENAME hook procedure
X_OFNOTIFYEXW | CDN_INCLUDEITEMW | OPENFILENAME hook procedure
X_NMTOOLTIPSCREATED | NM_TOOLTIPSCREATED |
X_NMMOUSE |  | X_NMMOUSE
X_NMOBJECTNOTIFY | TBN_GETOBJECT TCN_GETOBJECT PSN_GETOBJECT | Toolbars Tab controls Property Sheets
X_NMKEY |  |
X_NMCHAR |  |
X_NMCUSTOMDRAW |  |
X_NMHEADER |  |
X_NMHEADERW |  |
X_NMHDDISPINFOW |  |
X_NMHDDISPINFO |  |
X_NMHDFILTERBTNCLICK |  |
X_NMTBHOTITEM |  |
X_NMTBSAVE |  |
X_NMTBRESTORE |  |
X_NMTBGETINFOTIP |  |
X_NMTBGETINFOTIPW |  |
X_NMTBDISPINFO |  |
X_NMTBDISPINFOW |  |
X_NMTOOLBAR |  |
X_NMTOOLBARW |  |
X_NMREBARCHILDSIZE |  |
X_NMREBAR |  |
X_NMRBAUTOSIZE |  |
X_NMREBARCHEVRON |  |
X_NMTTDISPINFO |  |
X_TOOLTIPTEXT |  |
X_NMTTDISPINFOW |  |
X_NMUPDOWN |  |
X_NMLISTVIEW |  |
T_NM_LISTVIEW |  |
X_NMITEMACTIVATE |  |
X_NMLVCACHEHINT |  |
X_NMLVFINDITEM |  |
X_NMLVFINDITEMW |  |
X_NMLVODSTATECHANGE |  |
X_NMLVDISPINFO |  |
X_NMLVDISPINFOW |  |
X_NMLVKEYDOWN |  |
X_NMLVGETINFOTIP |  |
X_NMLVGETINFOTIPW |  |
X_NMTREEVIEW |  |
X_NMTREEVIEWW |  |
X_NMTVDISPINFO |  |
X_NMTVDISPINFOW |  |
X_NMTVKEYDOWN |  |
X_NMTVGETINFOTIP |  |
X_NMTVGETINFOTIPW |  |
X_NMCOMBOBOXEX |  |
X_NMCOMBOBOXEXW |  |
X_NMCBEDRAGBEGINW |  |
X_NMCBEDRAGBEGIN |  |
X_NMCBEENDEDITW |  |
X_NMCBEENDEDIT |  |
X_NMTCKEYDOWN |  |
X_NMSELCHANGE |  |
X_NMDAYSTATE |  |
X_NMDATETIMECHANGE |  |
X_NMDATETIMESTRING |  |
X_NMDATETIMESTRINGW |  |
X_NMDATETIMEWMKEYDOWN |  |
X_NMDATETIMEWMKEYDOWNW |  |
X_NMDATETIMEFORMAT |  |
X_NMDATETIMEFORMATW |  |
X_NMDATETIMEFORMATQUERY |  |
X_NMDATETIMEFORMATQUERYW |  |
X_NMIPADDRESS |  |
X_NMPGSCROLL |  |
X_NMPGCALCSIZE |  |
X_NMPGSCROLL |  |
X_HELPINFO | WM_HELP | Any control


Keyboard and Character Codes

Keyboard and Character Codes

These results were obtained from a typical US keyboard. They are presented in keyboard layout order, working each row from left to right. The first column in the table denotes the key pressed. The second column gives the name of an associated integer parameter defined in DFWINTY. The value of that parameter is given in the third column. The third column is also the "nCode" argument passed to a WM_KEYDOWN message handler (and/or the "wParam" argument passed to a WM_SYSKEYDOWN message handler if the Alt key is down). The fourth column contains the OEM scan code ("iScanCode" argument). If the message handler returns .FALSE. an attempt is made to generate a WM_CHAR message. If the key corresponds to an ASCII character, the generation succeeds and that character is passed to a WM_CHAR message handler as its "nCode" argument. The character generated depends on the status of the Shift, Ctrl, and Alt modifier keys. The "unmodified" column shows results when no modifier key is used. The "with Shift" and "with Ctrl" columns give results when only the Shift or Ctrl modifier is used, respectively. A blank cell indicates that the key is not associated with a character and that no WM_CHAR message is generated. Generally, if the Alt modifier is used, no WM_CHAR message is generated. The entries in the table are in decimal(hexadecimal) format.

 | Generated Key codes |  |  | WM_CHAR Contents
KEY | virtual-key name | key code | scan code | unmodified | with Shift | with Ctrl
Esc | VK_ESCAPE | 27(x1B) | 1(x001) | 27(x1B) | 27(x1B) | 27(x1B)
F1 | VK_F1 | 112(x70) | 59(x03B) |  |  |
F2 | VK_F2 | 113(x71) | 60(x03C) |  |  |
F3 | VK_F3 | 114(x72) | 61(x03D) |  |  |
F4 | VK_F4 | 115(x73) | 62(x03E) |  |  |
F5 | VK_F5 | 116(x74) | 63(x03F) |  |  |
F6 | VK_F6 | 117(x75) | 64(x040) |  |  |
F7 | VK_F7 | 118(x76) | 65(x041) |  |  |
F8 | VK_F8 | 119(x77) | 66(x042) |  |  |
F9 | VK_F9 | 120(x78) | 67(x043) |  |  |
F10 | VK_F10 | 121(x79) | 68(x044) |  |  |
F11 | VK_F11 | 122(x7A) | 87(x057) |  |  |
F12 | VK_F12 | 123(x7B) | 88(x058) |  |  |
accent | VK_OEM_3 | 192(xC0) | 41(x029) | 96(x60)` | 126(x7E)~ |
1 |  | 49(x31) | 2(x002) | 49(x31)1 | 33(x21)! |
2 |  | 50(x32) | 3(x003) | 50(x32)2 | 64(x40)@ |
3 |  | 51(x33) | 4(x004) | 51(x33)3 | 35(x23)# |
4 |  | 52(x34) | 5(x005) | 52(x34)4 | 36(x24)$ |
5 |  | 53(x35) | 6(x006) | 53(x35)5 | 37(x25)% |
6 |  | 54(x36) | 7(x007) | 54(x36)6 | 94(x5E)^ |
7 |  | 55(x37) | 8(x008) | 55(x37)7 | 38(x26)& |
8 |  | 56(x38) | 9(x009) | 56(x38)8 | 42(x2A)* |
9 |  | 57(x39) | 10(x00A) | 57(x39)9 | 40(x28)( |
0 |  | 48(x30) | 11(x00B) | 48(x30)0 | 41(x29)) |
- | VK_OEM_MINUS | 189(xBD) | 12(x00C) | 45(x2D)- | 95(x5F)_ |
= | VK_OEM_PLUS | 187(xBB) | 13(x00D) | 61(x3D)= | 43(x2B)+ |
\ | VK_OEM_5 | 220(xDC) | 43(x02B) | 92(x5C)\ | 124(x7C)| | 28(x1C)
backspace | VK_BACK | 8(x08) | 14(x00E) | 8(x08) | 8(x08) | 127(x7F)
tab | VK_TAB | 9(x09) | 15(x00F) | 9(x09) | 9(x09) |
Q |  | 81(x51) | 16(x010) | 113(x71)q | 81(x51)Q | 17(x11)
W |  | 87(x57) | 17(x011) | 119(x77)w | 87(x57)W | 23(x17)
E |  | 69(x45) | 18(x012) | 101(x65)e | 69(x45)E | 5(x05)
R |  | 82(x52) | 19(x013) | 114(x72)r | 82(x52)R | 18(x12)
T |  | 84(x54) | 20(x014) | 116(x74)t | 84(x54)T | 20(x14)
Y |  | 89(x59) | 21(x015) | 121(x79)y | 89(x59)Y | 25(x19)
U |  | 85(x55) | 22(x016) | 117(x75)u | 85(x55)U | 21(x15)
I |  | 73(x49) | 23(x017) | 105(x69)i | 73(x49)I | 9(x09)
O |  | 79(x4F) | 24(x018) | 111(x6F)o | 79(x4F)O | 15(x0F)
P |  | 80(x50) | 25(x019) | 112(x70)p | 80(x50)P | 16(x10)
[ | VK_OEM_4 | 219(xDB) | 26(x01A) | 91(x5B)[ | 123(x7B){ | 27(x1B)
] | VK_OEM_6 | 221(xDD) | 27(x01B) | 93(x5D)] | 125(x7D)} | 29(x1D)
CapsLock | VK_CAPITAL | 20(x14) | 58(x03A) |  |  |
A |  | 65(x41) | 30(x01E) | 97(x61)a | 65(x41)A | 1(x01)
S |  | 83(x53) | 31(x01F) | 115(x73)s | 83(x53)S | 19(x13)
D |  | 68(x44) | 32(x020) | 100(x64)d | 68(x44)D | 4(x04)
F |  | 70(x46) | 33(x021) | 102(x66)f | 70(x46)F | 6(x06)
G |  | 71(x47) | 34(x022) | 103(x67)g | 71(x47)G | 7(x07)
H |  | 72(x48) | 35(x023) | 104(x68)h | 72(x48)H | 8(x08)
J |  | 74(x4A) | 36(x024) | 106(x6A)j | 74(x4A)J | 10(x0A)
K |  | 75(x4B) | 37(x025) | 107(x6B)k | 75(x4B)K | 11(x0B)
L |  | 76(x4C) | 38(x026) | 108(x6C)l | 76(x4C)L | 12(x0C)
; | VK_OEM_1 | 186(xBA) | 39(x027) | 59(x3B); | 58(x3A): |
apostrophe | VK_OEM_7 | 222(xDE) | 40(x028) | 39(x27)' | 34(x22)" |
Enter | VK_RETURN | 13(x0D) | 28(x01C) | 13(x0D) | 13(x0D) | 10(x0A)
left shift | VK_SHIFT | 16(x10) | 42(x02A) |  |  |
Z |  | 90(x5A) | 44(x02C) | 122(x7A)z | 90(x5A)Z | 26(x1A)
X |  | 88(x58) | 45(x02D) | 120(x78)x | 88(x58)X | 24(x18)
C |  | 67(x43) | 46(x02E) | 99(x63)c | 67(x43)C | 3(x03)
V |  | 86(x56) | 47(x02F) | 118(x76)v | 86(x56)V | 22(x16)
B |  | 66(x42) | 48(x030) | 98(x62)b | 66(x42)B | 2(x02)
N |  | 78(x4E) | 49(x031) | 110(x6E)n | 78(x4E)N | 14(x0E)
M |  | 77(x4D) | 50(x032) | 109(x6D)m | 77(x4D)M | 13(x0D)
comma | VK_OEM_COMMA | 188(xBC) | 51(x033) | 44(x2C), | 60(x3C)< |
period | VK_OEM_PERIOD | 190(xBE) | 52(x034) | 46(x2E). | 62(x3E)> |
/ | VK_OEM_2 | 191(xBF) | 53(x035) | 47(x2F)/ | 63(x3F)? |
right shift | VK_SHIFT | 16(x10) | 54(x036) |  |  |
left Ctrl | VK_CONTROL | 17(x11) | 29(x01D) |  |  |
left Alt | VK_MENU | 18(x12) | 56(x038) |  |  |
space bar | VK_SPACE | 32(x20) | 57(x039) | 32(x20) | 32(x20) | 32(x20)
right Alt | VK_MENU | 18(x12) | 312(x138) |  |  |
right Ctrl | VK_CONTROL | 17(x11) | 285(x11D) |  |  |
Editing Cluster Keys |  |  |  |  |  |
Insert | VK_INSERT | 45(x2D) | 338(x152) |  |  |
Home | VK_HOME | 36(x24) | 327(x147) |  |  |
Page Up | VK_PRIOR | 33(x21) | 329(x149) |  |  |
Delete | VK_DELETE | 46(x2E) | 339(x153) |  |  |
End | VK_END | 35(x23) | 335(x14F) |  |  |
Page Down | VK_NEXT | 34(x22) | 337(x151) |  |  |
up arrow | VK_UP | 38(x26) | 328(x148) |  |  |
left arrow | VK_LEFT | 37(x25) | 331(x14B) |  |  |
down arrow | VK_DOWN | 40(x28) | 336(x150) |  |  |
right arrow | VK_RIGHT | 39(x27) | 333(x14D) |  |  |
Keypad Border Keys |  |  |  |  |  |
NumLock | VK_NUMLOCK | 144(x90) | 325(x145) |  |  |
keypad / | VK_DIVIDE | 111(x6F) | 309(x135) | 47(x2F)/ | 47(x2F)/ |
keypad * | VK_MULTIPLY | 106(x6A) | 55(x037) | 42(x2A)* | 42(x2A)* |
keypad - | VK_SUBTRACT | 109(x6D) | 74(x04A) | 45(x2D)- | 45(x2D)- |
keypad + | VK_ADD | 107(x6B) | 78(x04E) | 43(x2B)+ | 43(x2B)+ |
kpd. Enter | VK_RETURN | 13(x0D) | 284(x11C) | 13(x0D) | 13(x0D) | 10(x0A)
Keypad Numeric Keys with NumLock Off |  |  |  |  |  |
keypad 0 | VK_INSERT | 45(x2D) | 82(x052) |  |  |
keypad . | VK_DELETE | 46(x2E) | 83(x053) |  |  |
keypad 1 | VK_END | 35(x23) | 79(x04F) |  |  |
keypad 2 | VK_DOWN | 40(x28) | 80(x050) |  |  |
keypad 3 | VK_NEXT | 34(x22) | 81(x051) |  |  |
keypad 4 | VK_LEFT | 37(x25) | 75(x04B) |  |  |
keypad 5 | VK_CLEAR | 12(x0C) | 76(x04C) |  |  |
keypad 6 | VK_RIGHT | 39(x27) | 77(x04D) |  |  |
keypad 7 | VK_HOME | 36(x24) | 71(x047) |  |  |
keypad 8 | VK_UP | 38(x26) | 72(x048) |  |  |
keypad 9 | VK_PRIOR | 33(x21) | 73(x049) |  |  |
Keypad Numeric Keys with NumLock On |  |  |  |  |  |
keypad 0 | VK_NUMPAD0 | 96(x60) | 82(x052) | 48(x30)0 |  |
keypad . | VK_DECIMAL | 110(x6E) | 83(x053) | 46(x2E). | 46(x2E). |
keypad 1 | VK_NUMPAD1 | 97(x61) | 79(x04F) | 49(x31)1 |  |
keypad 2 | VK_NUMPAD2 | 98(x62) | 80(x050) | 50(x32)2 |  |
keypad 3 | VK_NUMPAD3 | 99(x63) | 81(x051) | 51(x33)3 |  |
keypad 4 | VK_NUMPAD4 | 100(x64) | 75(x04B) | 52(x34)4 |  |
keypad 5 | VK_NUMPAD5 | 101(x65) | 76(x04C) | 53(x35)5 |  |
keypad 6 | VK_NUMPAD6 | 102(x66) | 77(x04D) | 54(x36)6 |  |
keypad 7 | VK_NUMPAD7 | 103(x67) | 71(x047) | 55(x37)7 |  |
keypad 8 | VK_NUMPAD8 | 104(x68) | 72(x048) | 56(x38)8 |  |
keypad 9 | VK_NUMPAD9 | 105(x69) | 73(x049) | 57(x39)9 |  |

Notes

When there are two keys that have the same purpose, e.g., the left and right shift keys; the arrow keys in the editing cluster and on the keypad; etc., the key code is the same for both keys. However the scan code for each physical key is distinct.

Key codes for keys not listed here can be found in the DFWINTY source listing and at Microsoft with brief comments.

The scan codes shown are for the key down event. Scan codes associated with key release are different. For complete lists of scan codes and an explanation of keyboard signal transmission, see Adam Chapweske's site http://www.computer-engineering.org/ps2keyboard/.

Xeffort.com. Submitted by Mike Gaitens.


XFTLOGM Overview

XFLOGM Overview

Intel ships module DFLOGM with Visual Fortran product. DFLOGM serves as a wrapper for dialog handling in all types of applications, simplifying the programming. However, with DFLOGM you can't obtain full functionality that you could with a Win32-handled dialog; the most frequent requirements from users were handling of controls' colors and context help.

XFLOGM 1.0 module provided by myself was a tweak of the existing Compaq/Intel DFLOGM module. New XFLOGM 2.0 provides (almost) full compatibility with DFLOGM, as well as retaining all extensions introduced in XFLOGM 1.0 (DLG_COLOR, DLG_VISIBLE etc.).

XFLOGM 2.0 is written from scratch. Actually, it presents just a thin layer around modules XFTCTRL and XFTDialog. Type DIALOG is actually just a synonym for X_WINDOW structure, and that means that dialogs created by XFLOGM 2.0 are at the same time native Xeffort windows. Thus, all the features of Xeffort library are applicable for dialogs created by XFLOGM 2.0.

You are encouraged to use native XFTDialog and XFTCtrl APIs instead of XFLOGM, especially for new applications. XFLOGM 2.0 is provided primarily for compatibility with older XFLOGM/DFLOGM code - note that the file XFLOGM2.f90 contains just renames or thin wrappers of XFTCtrl routines/constants.

XFLOGM 2.0 introduces several new features, and uses a quite different architecture than DFLOGM/XFLOGM 1.0.

Under XFLOGM 2.0, TYPE(DIALOG) is just a synonym for Xeffort TYPE(X_WINDOW). Thus, they can be freely interchanged. Every XFTWND routine can operate on a variable of TYPE(DIALOG). Thus, you can freely use a mixture of XFLOGM and other Xeffort routines.

See also XFTWND Design Considerations page for an overview of properties of DIALOG/X_WINDOW structure.

Features


XFLOGM: Known Incompatibilities

XFLOGM: Known Incompatibilities

The following issues are not compatible in XFLOGM 2.0 and DFLOGM at the current stage (Dec 2003):

  • ActiveX controls are not supported.

  • When used in QuickWin applications, main application window is not by default used as parent in DlgModal. As result, the dialog is effectively modeless, and it may even appear behind parent window. Set the second argument (hParent) of DlgModal to GETHWNDQQ(QWIN$FRAMEWINDOW) to avoid that.

  • DLG_NUMITEMS is not the default value for DlgGet for list-boxes, combo-boxes and dropdown-list. Instead, it's DLG_SELECTION.

  • Due to New Modal behavior, all Win32 APIs work in the same routine from where DlgInit is called (which practically eliminates the need for having DLG_INIT callback). Since the dialog actually starts its life as modeless, that includes ShowWindow(Dlg%hWnd, SW_SHOW), which can lead to undesired effects. Be aware.

  • For the same reason, DLG_DESTROY callback is called when the dialog is about to be destroyed, but in XFLOGM 2.0 it happens on DlgUnInit, not on DlgExit. For that reason, CVF AppWizard-generated code for dialog-based application will not quite work, as PostQuitMessage will never get called.

  • Pushbuttons do not cause the dialog to exit by default anymore, with the exception of IDOK (=1) and IDCANCEL (=2). They do nothing unless a DlgSetSub is set for them.

  • In summary, to make the CVF AppWizard-generated code work, replace
    lret = DlgSetSub(gdlg, IDD_DIALOG, WizardTestSub)
    with
    lret = DlgSetSub(gdlg, IDM_EXIT, WizardTestSub)
    or, better still, get rid of it and write a simple WinMain containing only DlgInit and DlgModal (with appropriate DlgSet/DlgGet)

Any other incompatibility is either unintended, undesired, or simply forgotten. Please report any other to jdujic@uns.ns.ac.yu.

The following extensions are not compatible in XFLOGM 2.0 and XFLOGM 1.0 at the current stage:

  • DlgSetHelp routine is replaced with DLG_HELP callback.


XFLOGM: Control Properties

XFLOGM: Control Properties

DlgSet and DlgGet routines set or retrieve properties of the control. These routines are just renames of XCtlSet and XCtlGet routines. Value of a property can be an integer, string, logical, or an array.

INTEGER FUNCTION DlgSet(xWnd, ID, Value, iAction)

INTEGER FUNCTION DlgGet(xWnd, ID, Value, iAction)

General meaning of iAction indices describing control properties are presented in the following table. More detailed explanations are given in the table below and remarks thereafter:

Constant | Meaning
DLG_DEFAULT | The default value. See table below.
DLG_STATE | State of the control, i.e. its important property. For example, for edit controls it refers to control's text, and for check boxes their checked state
DLG_ADDSTRING | In list and combo boxes, appends the item to the end of the list.
DLG_BITMAP | Handle of a bitmap associated with the control
DLG_BKCOLOR | Background color of the control
DLG_COLOR | Color of control's text
DLG_ENABLE | Enabled/disabled control's status
DLG_FONT | Font of the control
DLG_FORMAT | Rendering format of the listview control
DLG_ICON | Handle of icon associated with the control
DLG_NUMITEMS | Number of items in control's (such as list or tab control)
DLG_PAGE | Scrollbars & updown controls: amount of increase of control's value on a single mouse click
DLG_RANGEMAX | Maximal allowed value for the control
DLG_RANGEMIN | Minimal allowed value for the control
DLG_RECTS | Width of individual fields of multi-item status bar, or width of columns of a listview control.
DLG_SELECTION | Selected item in the list. Usually identical to DLG_STATE
CTL_SIZEOF | Size of single user-defined type in a virtual listview control.
DLG_TABSTOPS | Tab stop positions for list boxes with LBS_USETABSTOPS style
DLG_TITLE | Control's caption
DLG_VISIBLE | Control's visibility
Index | For controls containing multiple items, such as list boxes, a positive integer refers to Index-th item in the collection.
0 (DLG_ADDSTRING) | For controls containing multiple items, such as list boxes, zero for DlgSet means "append an item to the end of the list"

The following table describes applicable properties for every type of:

Type of control | Integer | String | Logical | Array
Dialog itself | DLG_ICON DLG_COLOR | DLG_TITLE DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Radio button (automatic) | DLG_BITMAP DLG_ICON DLG_COLOR DLG_BKCOLOR | DLG_TITLE DLG_FONT | DLG_STATE DLG_VISIBLE DLG_ENABLE |
Push button | DLG_BITMAP DLG_ICON | DLG_TITLE DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Check box | DLG_BITMAP DLG_ICON DLG_COLOR DLG_BKCOLOR | DLG_TITLE DLG_FONT | DLG_STATE DLG_VISIBLE DLG_ENABLE |
Combo box | DLG_STATE DLG_SELECTION DLG_NUMITEMS DLG_COLOR DLG_BKCOLOR Index | DLG_SELECTION DLG_STATE DLG_SELECTION DLG_FONT DLG_ADDSTRING Index | DLG_VISIBLE DLG_ENABLE |
Dropdown list combo | DLG_STATE DLG_SELECTION DLG_NUMITEMS DLG_COLOR DLG_BKCOLOR Index | DLG_SELECTION DLG_SELECTION DLG_FONT DLG_ADDSTRING Index | DLG_VISIBLE DLG_ENABLE |
Edit box | DLG_RANGEMAX DLG_COLOR DLG_BKCOLOR | DLG_STATE DLG_FONT 0 Index | DLG_VISIBLE DLG_ENABLE |
Group box | DLG_COLOR DLG_BKCOLOR | DLG_TITLE DLG_FONT | DLG_VISIBLE DLG_ENABLE |
List box | DLG_STATE DLG_SELECTION DLG_NUMITEMS DLG_COLOR DLG_BKCOLOR Index | DLG_SELECTION DLG_SELECTION DLG_FONT DLG_ADDSTRING Index | DLG_VISIBLE DLG_ENABLE | DLG_SELECTION DLG_TABSTOPS
ListView control (see detailed reference) | DLG_STATE DLG_SELECTION DLG_NUMITEMS DLG_COLOR DLG_BKCOLOR DLG_SIZEOF Index | DLG_FORMAT 0 Index | DLG_VISIBLE DLG_ENABLE Index | DLG_SELECTION DLG_RECTS
Radio button | DLG_BITMAP DLG_ICON DLG_COLOR DLG_BKCOLOR | DLG_TITLE DLG_FONT | DLG_STATE DLG_VISIBLE DLG_ENABLE |
Progress bar | DLG_STATE DLG_PAGE DLG_COLOR DLG_BKCOLOR | DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Scrollbar | DLG_STATE DLG_PAGE DLG_RANGEMAX DLG_RANGEMIN DLG_COLOR DLG_BKCOLOR | DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Slider (Trackbar) | DLG_STATE DLG_PAGE DLG_RANGEMAX DLG_COLOR DLG_BKCOLOR | DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Static control | DLG_BITMAP DLG_ICON DLG_COLOR DLG_BKCOLOR | DLG_TITLE DLG_FONT | DLG_VISIBLE DLG_ENABLE |
Status bar | DLG_COLOR DLG_BKCOLOR | DLG_FONT Index | DLG_VISIBLE DLG_ENABLE | DLG_RECTS
Tab control | DLG_STATE DLG_SELECTION DLG_NUMITEMS DLG_COLOR DLG_BKCOLOR Index | DLG_FONT Index | DLG_VISIBLE DLG_ENABLE |
Updown (Spin) | DLG_STATE DLG_RANGEMAX DLG_RANGEMIN DLG_BKCOLOR | DLG_FONT | DLG_VISIBLE DLG_ENABLE |

Remarks

  1. If iAction argument is ommitted, it defaults to the value indicated bold. The default value is indicated red if it's applicable only for DlgSet, and green if applicable only for DlgGet. For example:
    b = DlgSet(Dlg, IDC_LIST1, "Item")
    appends a sting named "Item" at the end of the list (iAction = 0), while
    b = DlgGet(xWnd, IDC_LIST1, String)
    returns the selected string from the list (iAction = DLG_STATE versus DLG_SELECTION).

  2. Where there are two default actions (indicated bold), they have the identical meaning.

  3. DLG_ICON and DLG_BITMAP are applicable only for controls which have appropriate style set, e.g. BS_ICON/BS_BITMAP for buttons or SS_ICON/SS_BITMAP for static controls. DLG_ICON is applicable to the dialog itself, changing its caption icon.

  4. DLG_COLOR and DLG_BKCOLOR don't affect push button's appearance at all. For check boxes and radio buttons, they affect only appearance of the text.

  5. A control is physically visible if both its parent window and itself have WS_VISIBLE style. DLG_VISIBLE sets/gets only the status of the control itself, i.e. it may be set or returned TRUE even if the parent window is hidden.

  6. DLG_FONT property is available only for DlgSet. Font descriptor string has to have the same format as for SETFONT QuickWin function, i.e. "t'Arial'h8eui" means "8 point Arial bold italic underlined". Only t, i, e, u, h, w descriptors are supported.

  7. List boxes specifically can have or not LBS_MULTIPLESEL style, which allows several items to be selected simultaneously. To retrieve selected items, you can either:
    - use     DlgGet(xWnd, IDC_LIST1, iSel, DLG_SELECTION) where iSel is an integer pointer array which will contain indices of selected items, or
    - use     DO WHILE(DlgGet(xWnd, IDC_LIST1, iSel, n)); n=n+1; END DO. iSel will contain position in the list of n-th selected items.

  8. DlgSet(xWnd, IDC_TAB1, IDD_DIALOG1, n) will assign modeless child dialog with ID IDD_DIALOG1 to n-th page of Tab control.


XFLOGM: Control Callbacks

XFLOGM 2.0: Control Callbacks

The following events/callbacks are specified for controls handled by XFLOGM. Additions by XFLOGM relative to DFLOGM are marked green.

Event | Applies to | Meaning
DLG_CLICKED | BUTTON RADIO AUTORADIO CHECKBOX | The control is clicked with the mouse (or pressed using Space on keyboard)
DLG_CHANGE | EDIT COMBO SCROLLBAR UPDOWN SLIDER | State of the control is changed. For edit and combo boxes, this callback is called when user changes text in edit portion, but before it is formatted and displayed on th screen. For other controls, it is called when control's position is changed.
DLG_UPDATE | EDIT COMBO | This callback is called when the edit portion of the control is about to be updated.
DLG_SELCHANGE | LIST DROPDOWN COMBO TAB | Selected item in the list is changed
DLG_DBLCLICK | LIST DROPDOWN COMBO | An item in the list is double-clicked
DLG_DRAWITEM | STATIC BUTTON RADIO AUTORADIO CHECKBOX | The control with "Owner drawn" style has to be redrawn.
DLG_GAINFOCUS | EDIT | Edit-box control has gained the focus
DLG_LOSEFOCUS | EDIT | Edit-box control has lost the focus
DLG_SELCHANGING | TAB | User has clicked on a different page of a tab control, but the control was not yet updated (page changed).
DLG_HELP | DIALOG | User has pressed button F1, or clicked on a control when the dialog is in "context help" mode. The callback routine receives ID of clicked control as the third parameter (iEvent). iEvent can be casted to Win32 HELPINFO structure using X_HELPINFO helper function.
DLG_DESTROY | DIALOG | The dialog is about to be destroyed.
DLG_SIZECHANGE | DIALOG | The dialog is being resized.


XFTLOGM Features

XFLOGM Reference

Available properties for dialog controls

Available callbacks for dialog controls

Known incompatibilities

Features Introduced in XFLOGM 1.0

DLG_BITMAP and DLG_ICON

DLG_COLOR and DLG_BKCOLOR

DLG_DRAWITEM

DLG_VISIBLE

Dialogs with DS_CENTER Style

DlgSetHelp

New in XFLOGM 2.0

New Modal behavior

DLG_SELECTION

DLG_RANGEMAX

Status Bars Support

ListView Controls Support

DLG_TABSTOPS

DLG_TITLE

DLG_HELP


DLG_BITMAP and DLG_ICON

DLG_BITMAP and DLG_ICON

DLG_BITMAP and DLG_ICON control indices are available for push buttons, push-like check boxes, push-like radio buttons and static controls (with "icon" or "bitmap" style). You have to set "Bitmap" or "Icon" style on control's property sheet in order to assign the bitmap to it. Syntax is:

result = DlgSet/DlgGet(Dlg, idControl, hImage, DLG_BITMAP)

where hImage is integer representing handle of the image. You can obtain hBitmap using one of the following Win32 (DFWIN) functions:

LoadBitmap, LoadImage, CreateBitmapIndirect, CreateBitmap, LoadIcon

Where LoadImage is the most useful, with capability of loading bitmaps and icons both as resource and from file and providing "transparent" effect (LR_LOADMAP3DCOLORS), i.e. light-gray in the original bitmap is replaced with the 3D face color in the actual color scheme. Also, to use 16x16 or other non-default size icons you have to use LoadImage.

Also, XCreateBitmap can be used, using X_BITMAP%hBmp member as hImage.

Additionally, DLG_ICON is available in XFLOGM 2.0 for status bars.

Remarks

For buttons/check boxes/radio buttons, DLG_ICON style is preferred, if applicable (16x16 or 32x32 icons should be used). The reason is that disabled buttons with "Bitmap" style look ugly.


DLG_COLOR and DLG_BKCOLOR

DLG_COLOR and DLG_BKCOLOR

DLG_BKCOLOR and DLG_COLOR control indices are available static text, group boxes, push buttons, check boxes, and radio buttons. Syntax is:

result = DlgSet/DlgGet(Dlg, idControl, nRGBvalue, DLG_COLOR)
result = DlgSet/DlgGet(Dlg, idControl, nRGBvalue, DLG_BKCOLOR)

where nRGBvalue is integer in Win32 COLORREF format. nRGBValue can be obtained using:
- Hex notation #BBGGRR
- MSFLIB RGBToInteger function
- Xeffort XRGB function

To retreat to the default color values, use -1 as nRGBvalue argument.

Remarks

For push buttons, due to Win32 design, these flags affect only "focus rectangle"; for other controls text background and text color are affected. However, DLG_DRAWITEM callback can be used for that purpose.


DLG_DRAWITEM

DLG_DRAWITEM

DLG_DRAWITEM control index can be used in conjunction with DlgSetSub for static controls and buttons with "owner-drawn" style. Owner-drawn controls enable you to draw on their surface at run-time, providing means for displaying bitmaps that change at run-time. The syntax is:

result = DlgSetSub(Dlg, idCtrl, OwnerDrawCallback, DLG_DRAWITEM)

where idCtrl is ID of control with "owner-draw" style, and OwnerDrawCallback is EXTERNAL callback routine of prototype:

SUBROUTINE OwnerDrawCallback(Dlg, idControl, xDC)

where xDC is either integer handle of control's DC or type X_DC from XFTGDI. Note that OwnerDrawCallback is of the same prototype as any other routine registered with DlgSetSub. Third argument is used to pass control's DC (as handle or X_DC) so that the routine can perform drawing. With other "standard" callbacks this argument is used to indicate type of event that happened on the control.

Also, note that "standard" callbacks are invoked when the user performs an action on the control. DLG_DRAWITEM callback is, however, invoked without direct user's action -- whenever the control has to be redrawn. Redrawing occurs whenever a part of the control is revealed, e.g. when another window is moved over the control or when the application comes into foreground. Also, the application itself can force redrawing using Win32 function InvalidateRect. In Test.f90 sample, animation is realised so that a timer is started immediately before DlgModal; the timer function is invoked every 0.1 s and it changes the global radius of the circle and then calls InvalidateRect function, which indirectly triggers the DLG_DRAWITEM callback. For example, if you want the image to change as result of an event in another control in the dialog, simply make a callback routine for that control which calls InvalidateRect. Note that data necessary to perform drawing has to be either exchanged via global variables, or OwnerDrawCallback has to be "intelligent", performing the drawing on the basis of state of other controls in the dialog.

Remarks

Drawing on control's surface has to be done using XFTGDI or Win32 GDI functions. MSFLIB functions such as MoveTo, Rectangle, SetColor are unusable for this purpose. Please refer to "Painting and Drawing" section of Win32 help for detailed description.

Buttons with BS_OWNERDRAW style are actually neither buttons, checkboxes nor radio buttons -- they are a species of its own. XFLOGM treats them equally as pushbuttons, i.e. other properties of a pushbutton apply to them.

VS resource editor does not enable you to specify "owner drawn" style for static controls from the IDE (on the control's property sheet). To workaround this, insert a "picture" control of type e.g. "black frame". After saving resource, open the .rc file in a text editor (from VS IDE, in File/Open dialog, specify "Text" in "Open as" dropdown) and replace "SS_BLACKFRAME" with "SS_OWNERDRAW" for that control. Make sure that control ID is other than IDC_STATIC.


DLG_HELP

DLG_FONT

DLG_FONT control index is available for all controls, in conjunction with string argument. DLG_FONT affects the control's font.

result = DlgSet(Dlg, idControl, sFontDescriptor, DLG_FONT)

sFontDescriptor describes the font, in a similar manner as SETFONT QuickWin function. sFontDescriptor is a combination of following letters:

t'fontname' or t"fontname" | Name of the desired typeface. It can be any installed font.
h y | Character height, where y is the number of points. If ommited, the default height is 10.
w x | Character width, where x is the number of pixels.
e | The font is bold.
u | The font is underlined.
i | The font is italic.

For example, "t'Arial'h8eui" means "8 point Arial bold italic underlined".


DLG_HELP

DLG_HELP

DLG_HELP control index is available for dialogs. This callback is invoked whenever:

  • User presses F1 key when a dialog control is focused

  • Dialog has "context help" button, and a control is clicked while the dialog is in "help" mode

result = DlgSetSub(Dlg, idDialog, HelpCallback, DLG_HELP)

Where HelpCallback has the following prototype:

SUBROUTINE HelpCallback(Dlg, idControl, idContext)

Where idContext is help context ID of the control identified by idControl. idContext is automatically assigned by resource editor, and by default recorded in file "resource.hm". If that file is compiled with help compiler, idContext can be passed to WinHelp API function with appropriate arguments and HELP_CONTEXTPOPUP flag, and the appropriate help popup will be displayed next to the mouse pointer.

Remarks

IMPORTANT: DLG_HELP supersedes DlgSetHelp routine from XFLOGM 1.0. DlgSetHelp is not supported by XFLOGM as a precaution/warning, because prototype of the HelpCallback is changed. If you port from XFLOGM 1.0, make sure to change prototypes of all help callbacks, because otherwise a phenomenon called "fandango on stack" may occur, resulting in various strange run-time errors/misbehaviors.

HelpCallback routine typically invokes an user-provided help page from a .hlp file. Please refer to WinHelp Win32 function for details.

In order to enable context-help feature, you must check both "system menu" and "context help" styles on the dialog's property sheet in resource editor. If so, HelpCallback will be called upon clicking on a control with "question mark" cursor; idControl argument contains ID of the control. HelpCallback should then invoke appropriate popup description using WinHelp function with HELP_CONTEXTPOPUP flag.

On pressing F1 key idControl will contain the ID of the control which has the keyboard focus. However, note that the dialog need not have neither "context help" nor "system menu" style in order to respond to F1 key. If you decide to use a single help page for entire dialog instead of context help popups, simply ignore idControl argument and invoke appropriate page using WinHelp with HELP_CONTEXT flag.


DLG_RANGEMAX

DLG_PAGE

DLG_PAGE control index is available for scrollbars. It adjusts the height (width) of the scrollbar thumb. Size of scrollbar thumb relative to total scrollbar length is proportional to the ratio of this control index and total scrollbar range.

result = DlgSet(Dlg, IDC_SCROLLBAR, 10, DLG_RANGEMIN)
result = DlgSet(Dlg, IDC_SCROLLBAR, 50, DLG_RANGEMAX)
result = DlgSet(Dlg, IDC_SCROLLBAR, 20, DLG_PAGE)

In the sample above, the total scrollbar range is 50-10=40. That means that scrollbar thumb will occupy half of scrollbar length (20/40=50%).


DLG_RANGEMAX

DLG_RANGEMAX

DLG_RANGEMAX control index is available for scrollbars, updown controls, trackbars (sliders) and progress bars. Additionally, in XFLOGM 2.0 it is available for edit controls. There, it denotes the maximal length of the text user can type in the control.

result = DlgSet(Dlg, IDC_EDIT, 8, DLG_RANGEMAX)

In the sample above, only 8 characters can be entered by the user. Note that that does not affect the text that can be entered programatically, i.e.

result = DlgSet(Dlg, IDC_EDIT, "123456789", DLG_STATE)

will print out all nine digits regardless of DLG_RANGEMAX setting.


DLG_SELECTION

DLG_SELECTION

DLG_SELECTION control index is introduced for list-boxes, combo-boxes, dropdown lists, and tab controls. It can be used for retrieval of either text (DlgGetChar) or index (DlgGetInt) of the selected item(s):

result = DlgGet(Dlg, idControl, sValue, DLG_SELECTION)
result = DlgGet(Dlg, idControl, iValue, DLG_SELECTION)

When used for setting, with integer argument, it is identical to DLG_STATE:

result = DlgGet(Dlg, idControl, iValue, DLG_SELECTION)

When used for setting, with character argument, it selects the first item in list-box (single-selection), combo-box or dropdown list, whose starting letters match the given string. The search is case-insensitive:

result = DlgSet(Dlg, idControl, sValue, DLG_SELECTION)

For list-boxes with multiple selection (LBS_MULTIPLESEL), a new feature is introduced: Value argument for DlgSet can be an integer array, containing indices of items selected/to be selected:

result = DlgSet(Dlg, IDC_LIST, (/1,3,5,8/), DLG_SELECTION)

Will select items with 1,3,5, and 8.

With DlgGet, the integer array must be a NULLIFYed pointer. The calling routine must DEALLOCATE the pointer after use, otherwise a memory leak will occur (this feature will possibly be replaced with ALLOCATABLE arrays, breaking compatibility with CVF 6.1 and older):

INTEGER, POINTER:: piSel(:)
...
result = DlgGet(Dlg, IDC_LIST, piSel, DLG_SELECTION)
DO i=1, SIZE(piSel)
!Do something with the selection piSel(i)
END DO
DEALLOCATE(piSel)


DLG_VISIBLE

DLG_VISIBLE

DLG_VISIBLE control index shows or hides the control. Syntax is:

result = DlgSet/DlgGet(Dlg, idControl, bVisible, DLG_VISIBLE)

where bVisible is logical value which determines visibility of the control.

Remarks

A control is physically visible if both its parent window and itself have WS_VISIBLE style. DLG_VISIBLE sets / gets only the status of the control itself, i.e. it may be set or returned TRUE even if the parent window is hidden.


Dialogs with DS_CENTER Style

Dialogs with DS_CENTER Style

A change in behavior of dialogs with "center" (DS_CENTER) style is introduced in XFLOGM. By default, dialogs with this style are displayed in center of the screen. More logical behavior is that they are centered relative to its owner-window. In QuickWin applications, you can obtain handle of dialog's parent window using GetHWNDQQ MSFLIB function.


DLG_TABSTOPS

DLG_TABSTOPS

DLG_TABSTOPS control index is available only for list boxes which have "Use tab stops" (LBS_USETABSTOPS) style. This style is useful for emulation of ListView control in report mode, i.e. its items, if their text is separated by tabs (CHAR(9)) are displayed in multiple columns. This index is available only for DlgSet

result = DlgSet(Dlg, IDC_LIST, (/20,70,140/), DLG_TABSTOPS)

There are three tab stops: at 20, 70, and 140 dialog units (not pixels!) from the left. To show the text in three columns, use e.g:

result = DlgSet(Dlg, IDC_LIST, "1"//Char(9)//"Item 1"//Char(9)//"Value 1",
DLG_ADDSTRING)


DLG_TITLE

Dialog Extensions

DLG_TITLE control index is available for dialogs as well. It sets the dialog's caption, in the same way as DlgSetTitle routine.

result = DlgSet(Dlg, IDD_DIALOG1, "My Dialog", DLG_TITLE)

DLG_VISIBLE and DLG_ENABLE properties are available for dialogs themselves as well.


DlgSetHelp

DlgSetHelp

DlgSetHelp routine from XFLOGM1.0 is superseded by DLG_HELP callback. If you are porting code containing references to DlgSetHelp, please make sure read remarks in DLG_HELP page about incompatibility in this area.


ListView Control Support

XFLOGM 2.0: ListView Controls Support

XFLOGM 2.0 offers a rich support for ListView controls. Please refer to detailed overview and reference in XFTCtrl chapter (pay attention to naming conventions, i.e. CTL_ and XCtl prefixes should be replaced with DLG_ and Dlg respectively if you intend to use XFLOGM layer).


New Modal Behaviour

XFLOGM 2.0: New Modal behavior

Since XFLOGM 2.0 is based on Xeffort library, it has a new mechanism for creation of modal dialogs. It does not use DialogBox(Indirect) API anymore. Actually, XFLOGM2 modal dialogs are emulated. They are created in DlgInit and start they life as modeless at that point. On DlgModal, the dialog is shown, its parent window is disabled, and a modal message loop is entered. When the dialog is exited using an OK or Cancel button, or DlgExit routine, it is just hidden and the modal loop is exited. The dialog is physically destroyed at DlgUnInit.

The described change in behavior allows greater flexibility in the sense that all native APIs, if needed, such as SendMessage or DlgSendCtrlMessage can be called from the same routine where DlgInit is called -- there's no need for complex callback schemas.


Status Bars Support

XFLOGM 2.0: Status Bars Support

The following control indices are available for status bars:

result = DlgSet/DlgGet(Dlg, idStatus, sText, n)

  • Index with character string sets or retrieves text sText of n-th field of the status bar

result = DlgSet/DlgGet(Dlg, idStatus, hIcon, n)

  • Index with a handle of an icon sets or retrieves handle of an icon of n-th field of the status bar. 16x16 icons are recommended.

result = DlgSet/DlgGet(Dlg, idStatus, (/20, 80, 180, -1/), DLG_RECTS)

  • DLG_RECTS sets/retrieves the number and positions of status bar fields. In the sample above, there are four fields, first 20 pixels wide, second is (80-20) pixels wide, third (180-80) pixels wide, and the last extends to status bar's width.

Remarks

Status bars do not exist as an item in VS resource editor, but they can be added using "Custom Control" and specifying msctls_statusbar32 as class name.


XYPlot Overview

XYPlot Overview

Reference

XYPlot is a full-featured X-Y plotting package for engineering and scientific applications. It is capable of producing either a quick plain plot, or a presentation-quality plot with most appearance items being readily adjustable.

Here are the steps for constructing a very simple plot program.

  1. Open Visual Studio and use the Xeffort Application Wizard to create a new project. We’ll use DEMOPLOT as a placeholder for your project name.
  2. In the Step 1 App Wizard dialog, select SDI Application. In Step 2 select “View window” (we’ll be plotting in this view window), then complete the dialog.
  3. Open DEMOPLOT.f90 for editing. Go to the function XW_FRAME_OnSize. After the line bSt = XSetWindowPos(… insert the line
    CALL XUpdateWindow (xView)
    to redraw the plot display whenever the window is resized. Save your change.
  4. Open View.f90 for editing. Remove the 3 lines that contain “TODO”. The XFillViewport line is optional here, so we'll remove it too. Finally we generate some data for plotting (a sine and cosine curve) and plot it using XYQuickPlot . The lines we added are shown in bold. (You can select the code shown below, press Ctrl-C to copy it to the clipboard, then paste it into View.f90)

MODULE View

USE Xeffort
USE DFWIN

IMPLICIT NONE

TYPE(X_WINDOW)::      xView
!========================================================================
CONTAINS
!========================================================================
LOGICAL FUNCTION xView_OnPaint(xWnd, xDC, iX1, iY1, iX2, iY2)
      TYPE(X_WINDOW)::              xWnd
      TYPE(X_DC), INTENT(INOUT)::   xDC
      INTEGER, INTENT(IN)::         iX1, iY1, iX2, iY2

      LOGICAL::                     bSt
!           make some data for plotting
      INTEGER, PARAMETER :: NPTS = 360
      REAL :: X(NPTS), Y(NPTS,2)
      INTEGER :: J

      DO J = 1, NPTS
         X(J) = J                ! angle in degrees
         Y(J,1) = SIND (X(J))    ! sine of angle in col. 1
         Y(J,2) = COSD (X(J))    ! cosine of angle in col. 2
      END DO

      bSt = XYQuickPlot (xWnd, xDC, X, Y, 'Angle - deg.', 'Amplitude', 'Basic Trig Functions')

      xView_OnPaint = .TRUE.

END FUNCTION xView_OnPaint

END MODULE View

Run the program and notice how the plot changes as the window is resized. At some size we get:

Later in this introduction we'll modify this plot by using the XYPlot module in its native mode.

Anatomy of a Plot

Here we discuss our nomenclature. The six title line areas in the plot below are self-describing. Note a plot can have 4 axes, called X, Y, V, and W. Granted a W axis, a second independent axis with a scale different from X, may be somewhere between weird and ridiculous; nonetheless the capability exists. Here the Y axis is logarithmetic. To show non-default behavior, on the V axis we have commanded that the tick marks be inside the plot frame and that the labels be horizontal (labels are normally parallel to their axes). The plot features a legend which shows a sample of the plotting line along with a programmer-supplied curve name. Curves may be distinguished by color, pen style, and/or plotting symbols. Curves may also have deviation bars to indicate a range or other measure of uncertainty.

The plot below shows some additional features. There is the use of a non-white background. We also asked that the X axis be drawn at the Y=0 position rather than at the usual bottom of the plot frame, and that the Y axis be drawn at X=0. This plot demonstrates automatic clipping; note how the spiral is clipped as it leaves and re-enters the plot frame. Gridlines, faint lines that emanate from tick marks and span the plot frame, can also be seen. A coarse grid is shown; a fine grid, with a gridline extending from every tick mark, could have been requested. We called for tick marks on both sides of the axes. Unlike the sine plot above, this plot has borders. If used, borders appear opposite axes. A border can be plain, or have tick marks copied from its opposing axis. However, unlike an axis, a border cannot have labels or a title. One feature of this plot that is not readily apparent is the use of IsoScaling to maintain an equal number of pixels/unit on the X and Y axes, so circles will remain circular regardless of how the plot is stretched.

By now you will have noticed that tick marks come in two sizes, which we call major and minor. Unless you override tick mark placement, 9 minor ticks are used between a consecutive pair of major ticks to decimate the interval. However, if the major tick marks are close together, so there is insufficient room for distinct minor ticks, the minor tick marks are omitted. The maximum number of tick marks that can appear on an axis is controlled by the MaxTicks argument to XYPlotTicks . Also note that only major tick marks can have labels, but not every major tick is labeled. This module strives to make labels sparse and compact. Examine the W axis and its opposite X axis in the plot above as examples. That said, it is relatively easy to override tick mark appearance, placement, and labels.

Axes have end points, i.e., limits. There are two ways to establish axis end points. The end points can be specified (as was done for the spiral plot) in which case clipping can occur. Or you can merely give XYPlot the data arrays to be plotted and it will determine limits that both encompass the data and end in “nice” numbers (as was done for the sine plot). Because the log of zero or a negative number is not real, if a non-positive lower limit is specified or deduced for a log axis, the log axis will be switched to a linear axis. Numerically, linear axes have been restricted to +/-1018 . Log axes are limited to 10+/-38 .

HPD

Plots automatically stretch to use all of the available drawing surface (window) space. (Less any margins you might impose via XYPlotMargins). Normally one wants the various elements that comprise a plot, e.g., fonts, tick marks, plotting symbols, etc. to grow as the plot grows. All element sizes are entered as HPD (Height Percent [or Pixel] Dimension). An HPD is a real number, which if positive, is interpreted as a percent of window height. A negative HPD is rounded to the nearest integer number of pixels. Thus an HPD is a relative dimension if positive, but an absolute dimension if zero or negative. Internally, HPD’s are converted to an integer pixel count. For instance, an HPD of 4.8 means 4.8% of total height (then rounded to the nearest pixel), while a –4.8 would be 5 pixels.

Named Constants

The XYPlot module uses integer controls. Named constants may be used in place of these integers to make your code more self-documenting. XYPlot uses the convention for named constants that a name which contains an underscore can be used in an .OR. combination. However, you will find that the most popular combinations have already been OR’d with the result defining another named constant. Conversely, names that do not contain an underscore denote mutually exclusive choices.

Using XYPlot

To use the XYPlot module in its native mode, follow these steps.

  1. Decide how many curves are to be in the plot. Dimension an array of the XYCURVE derived type with this number of curves. It is assumed you have a corresponding pair of real X and Y data arrays for each curve that defines the points on that curve. Give each of these data arrays the TARGET attribute. Then for each element of the XYCURVE array, i.e., for each curve:
    1. Set the XYCURVE XDATA and YDATA pointers to point to the appropriate X and Y data arrays for that curve.
    2. If you wish the curve to appear in a legend, enter a short text description in the XYCURVE NAME field.
    3. Unless you want to draw the curve with a solid black line, fill the XYCURVE Pen field with an X_PEN description.
    4. If you want the curve to have a plotting symbol, enter your symbol choice in the XYCURVE PltSymb field.
  2. You’ll need the DC of the device to receive the plot. Ordinarily this will be given as an xDC argument to the paint routine.
  3. Get the size of the device to receive the plot. If the device is a window, use:
    XGetClientRect (xWnd, iWidth, iHeight)
  4. Invoke XYPlotInit giving it the xDC and the iWidth, iHeight dimensions. You can also set gridline, border, and background color options.
  5. If you wish change any defaults, call XYPlotFont, XYPlotMargins, XYPlotGaps, XYPlotLegend, XYPlotTicks, XYPlotLabels, XYPlotOverride as required. You are urged to skip this step unless you have determined that the default values are unsatisfactory.
  6. Invoke XYPlot giving it the XYCURVE array created in Step 1. You also specify titles here. Any title that is omitted or blank is not allocated space on the plot. Other options include axis type (linear, log) and axis limits.

Example

We return to the sine plot and make some changes:

  • Make the Y axis limits +/-1.2 so the curves don’t touch the X axis.
  • Make the X axis go from 0 to 360 degrees.
  • Put on a border with tick marks.
  • Add a fine grid.
  • Put a legend in the lower-left corner to identify the curves.
  • Add the tangent curve to the plot. Since the Y axis limits are not suitable for the tangent values, plot the tangent on the V axis using limits of +/-6.
  • Change the title fonts to an italic Times New Roman. Underline the top title line.
  • Use Times New Roman for the labels too.
  • Change the X axis minor tick spacing from the current 10 degrees to 15 degrees. Put major tick marks at 0, 90, 180, 270, and 360 degrees and label them appropriately.

We remove the call to XYQuickPlot from View.f90 above, and add the lines shown in bold.

MODULE View

USE Xeffort
USE DFWIN

IMPLICIT NONE

TYPE(X_WINDOW)::      xView
!========================================================================
CONTAINS
!========================================================================
LOGICAL FUNCTION xView_OnPaint(xWnd, xDC, iX1, iY1, iX2, iY2)
      TYPE(X_WINDOW)::              xWnd
      TYPE(X_DC), INTENT(INOUT)::   xDC
      INTEGER, INTENT(IN)::         iX1, iY1, iX2, iY2

      LOGICAL::                     bSt
      INTEGER::    iWidth, iHeight
!           make some data for plotting
      INTEGER, PARAMETER :: NPTS = 360
      REAL :: X(NPTS), Y(NPTS,2)
      INTEGER :: J

      DO J = 1, NPTS
         X(J) = J                ! angle in degrees
         Y(J,1) = SIND (X(J))    ! sine of angle in col. 1
         Y(J,2) = COSD (X(J))    ! cosine of angle in col. 2
      END DO

      bSt = XGetClientRect (xWnd, iWidth, iHeight)
      CALL MyPlot (xDC, iWidth, iHeight, X, Y)

      xView_OnPaint = .TRUE.

END FUNCTION xView_OnPaint
! =================================================
      SUBROUTINE MyPlot (xDC, iWidth, iHeight, X, Y)
      TYPE(X_DC), INTENT(INOUT)::   xDC
      INTEGER, INTENT(IN)      ::   iWidth, iHeight
      REAL, TARGET, INTENT(IN) ::   X(:), Y(:,:)
!
      TYPE (XYCURVE) :: CURVE(3)    ! create 3 curves
      REAL, TARGET :: TAN(SIZE (Y, DIM=1))  ! room for tangent data
      LOGICAL :: OK
      CHARACTER(1) :: DEG = CHAR (176)      ! the degree symbol
      CHARACTER(*), PARAMETER :: FACE = 'Times New Roman'
!           define CURVEs
      CURVE(1) % XDATA => X
      CURVE(1) % YDATA => Y(:,1)
      CURVE(1) % NAME = 'Sine'
      CURVE(1) % PEN = X_PEN (PS_SOLID, 0, XCOLOR_BLUE)
!
      CURVE(2) % XDATA => X
      CURVE(2) % YDATA => Y(:,2)
      CURVE(2) % NAME = 'Cosine'
      CURVE(2) % PEN = X_PEN (PS_DASH, 0, XCOLOR_GREEN)
!
      TAN = Y(:,1) / Y(:,2)      ! form tangent data
      CURVE(3) % XDATA => X
      CURVE(3) % YDATA => TAN
      CURVE(3) % NAME = 'Tangent'
      CURVE(3) % PEN = X_PEN (PS_SOLID, 0, XCOLOR_RED)
      CURVE(3) % PltSymb = 2     ! diamond
      CURVE(3) % YISV = .TRUE.   ! mark tan as V axis data
!
      OK = XYPlotInit (xDC, iWidth, iHeight, Grid_full.OR.Grid_On,&
     &                     BorderTicks, bUseV = .TRUE. )
      CALL XYPlotLabels (X_Axis, 0, (/ '0'//DEG, '90'//DEG,  &
     &           '180'//DEG, '270'//DEG, '360'//DEG /) )
      CALL XYPlotOverride (X_Axis, 15.0, 1, 5)
      CALL XYPlotFont (TX_TopLine, FACE, 4.8, bItalic = .TRUE.,  &
     &                  bUnderline = .TRUE.)
      CALL XYPlotFont (TX_Axes,    FACE, 4.5, bItalic = .TRUE.)
      CALL XYPlotFont (TX_Labels,  FACE, 4.0)
      OK = XYPlot (xDC, CURVE, 'Angle', 'Sine, Cosine', &
     &     'Basic Trig Functions', ' ', LegendLwrLeft,  &
     &     LinearAxis, LinearAxis, 0.0, 360.0,  -1.2, 1.2, &
     &     'Tangent', LinearAxis, -6.0, 6.0)
!
    END SUBROUTINE MyPlot
!===================================================
END MODULE View

Which yields

We’ll assume that’s good enough.  Obviously plots are subject to endless refinement.  For instance, the next change might be to remove the vertical lines that result as the tangent flips thru +/- infinity.  We would do this by adding two curves to the plot where CURVE(5) = CURVE(4) = CURVE(3) except

      CURVE(3) % XDATA =>
X(1:89)
CURVE(4) % XDATA =>
X(91:269)
CURVE(5) % XDATA =>
X(271:360)
CURVE(3) % YDATA => TAN(1:89)
CURVE(4) % YDATA => TAN(91:269)
CURVE(5) % YDATA => TAN(271:360)

Reporting

Perhaps this is the most important step.  We’ll demonstrate two methods of transferring a plot to a file so it can be distributed; the first method is more suitable for publishing on the web, the second for a report on paper.

For the web, we simply copy the plot window to a bitmap file using XGetBitmap / XSaveBitmap .  The resulting image will have the same resolution as the screen.

For printing, a high-resolution image is desired.  To get it, rather than plotting to a screen DC, we plot directly to a DC modeled after a printer (which has much higher resolution, hence fewer “jaggies”), and using XCreateMetaFile, save the result as an enhanced metafile for a word processor.

The code to accomplish this follows.  Once again, new lines are bolded.

MODULE View

USE Xeffort
USE DFWIN

IMPLICIT NONE

TYPE(X_WINDOW)::      xView
!========================================================================
CONTAINS
!========================================================================
LOGICAL FUNCTION xView_OnPaint(xWnd, xDC, iX1, iY1, iX2, iY2)
      TYPE(X_WINDOW)::              xWnd
      TYPE(X_DC), INTENT(INOUT)::   xDC
      INTEGER, INTENT(IN)::         iX1, iY1, iX2, iY2

      TYPE (X_BITMAP) :: xBmp
      TYPE (X_DC) :: xDCmf, xDCpr       ! metafile and printer DC's
      LOGICAL::                     bSt
      INTEGER::    iWidth, iHeight
!           make some data for plotting
      INTEGER, PARAMETER :: NPTS = 360
      REAL :: X(NPTS), Y(NPTS,2)
      INTEGER :: J

      DO J = 1, NPTS
         X(J) = J                ! angle in degrees
         Y(J,1) = SIND (X(J))    ! sine of angle in col. 1
         Y(J,2) = COSD (X(J))    ! cosine of angle in col. 2
      END DO

      bSt = XGetClientRect (xWnd, iWidth, iHeight)
      CALL MyPlot (xDC, iWidth, iHeight, X, Y)
!             save to bitmap file 'MyPlot.bmp'
      CALL XSetViewport (xDC, 0, 0, iWidth, iHeight)
      bSt = XGetBitmap (xDC, xBmp, 0, 0, iWidth, iHeight)
      bSt = XSaveBitmap (xBmp, 'MyPlot.bmp', 24)
      bSt = XDeleteBitmap (xBmp)

!             get metafile DC and its drawing surface size
      xDCpr = XCreateDC ()  ! get DC of default printer
      bSt = XCreateMetaFile (xDCpr, 'MyPlot.emf', xDCmf, iWidth, iHeight)
!             plot to metafile 'MyPlot.emf'
      CALL MyPlot (xDCmf, iWidth, iHeight, X, Y)  ! note 1st arg.
      bSt = XCloseMetaFile (xDCmf)
      bSt = XDeleteDC (xDCpr)

      xView_OnPaint = .TRUE.

END FUNCTION xView_OnPaint
! =================================================
      SUBROUTINE MyPlot (xDC, iWidth, iHeight, X, Y)
      TYPE(X_DC), INTENT(INOUT)::   xDC
      INTEGER, INTENT(IN)      ::   iWidth, iHeight
      REAL, TARGET, INTENT(IN) ::   X(:), Y(:,:)
!
      TYPE (XYCURVE) :: CURVE(3)    ! create 3 curves
      REAL, TARGET :: TAN(SIZE (Y, DIM=1))  ! room for tangent data
      LOGICAL :: OK
      CHARACTER(1) :: DEG = CHAR (176)      ! the degree symbol
      CHARACTER(*), PARAMETER :: FACE = 'Times New Roman'
!           define CURVEs
      CURVE(1) % XDATA => X
      CURVE(1) % YDATA => Y(:,1)
      CURVE(1) % NAME = 'Sine'
      CURVE(1) % PEN = X_PEN (PS_SOLID, 0, XCOLOR_BLUE)
!
      CURVE(2) % XDATA => X
      CURVE(2) % YDATA => Y(:,2)
      CURVE(2) % NAME = 'Cosine'
      CURVE(2) % PEN = X_PEN (PS_DASH, 0, XCOLOR_GREEN)
!
      TAN = Y(:,1) / Y(:,2)      ! form tangent data
      CURVE(3) % XDATA => X
      CURVE(3) % YDATA => TAN
      CURVE(3) % NAME = 'Tangent'
      CURVE(3) % PEN = X_PEN (PS_SOLID, 0, XCOLOR_RED)
      CURVE(3) % PltSymb = 2     ! diamond
      CURVE(3) % YISV = .TRUE.   ! mark tan as V axis data
!
      OK = XYPlotInit (xDC, iWidth, iHeight, Grid_full.OR.Grid_On,&
     &                     BorderTicks, bUseV = .TRUE. )
      CALL XYPlotLabels (X_Axis, 0, (/ '0'//DEG, '90'//DEG,  &
     &           '180'//DEG, '270'//DEG, '360'//DEG /) )
      CALL XYPlotOverride (X_Axis, 15.0, 1, 5)
      CALL XYPlotFont (TX_TopLine, FACE, 4.8, bItalic = .TRUE.,  &
     &                  bUnderline = .TRUE.)
      CALL XYPlotFont (TX_Axes,    FACE, 4.5, bItalic = .TRUE.)
      CALL XYPlotFont (TX_Labels,  FACE, 4.0)
      OK = XYPlot (xDC, CURVE, 'Angle', 'Sine, Cosine', &
     &     'Basic Trig Functions', ' ', LegendLwrLeft,  &
     &     LinearAxis, LinearAxis, 0.0, 360.0,  -1.2, 1.2, &
     &     'Tangent', LinearAxis, -6.0, 6.0)
!
    END SUBROUTINE MyPlot
!===================================================
END MODULE View

“Sticky” Appearance Settings

The subroutines XYPlotFont, XYPlotGaps, XYPlotLegend , XYPlotTicks and XYPlotPhase redefine current defaults.  Therefore, the appearance items they control are “sticky” and apply to all subsequent plots.  They may even be used before the first call to XYPlotInit or XYQuickPlot.  For instance, if the top title font is changed to Times New Roman for the first plot, that same font will also be used for the top title in all remaining plots unless/until the font is re-commanded.

Conversely, subroutines XYPlotMargins, XYPlotLabels, and XYPlotOverride have no carry-over.  If used, calls to these routines must be placed between the calls to XYPlotInit and XYPlot, and they affect only to the current plot.

Plotting Complex Arrays in Magnitude-Phase Form

Consider plotting a complex array.  One could copy the real and the imaginary parts into two temporary real arrays and, using XYPlot, plot the two curves as a real-imaginary representation of the complex data.

An alternative is to pass the complex array to XYPlotComplex and have it plot the data in magnitude and phase-angle form.  Magnitude is plotted in the main plot frame while the corresponding phase angle appears in a special "phase banner" placed directly above the main plot frame.  A sample plot that uses a phase banner is show below.  (Remember that phase angles of +180° and -180° are identical).

The table below outlines the similarities and principal differences between XYPlot and XYPlotComplex.

XYPlot | XYPlotComplex
Must be preceded by XYPlotInit | Same. Must follow XYPlotInit
Requires an array of XYCURVE derived type, in which the Y (or V) axis data are in real arrays. X axis arrays are also real. | Requires an array of XYCURVECOMPLEX derived type, in which the Y (or V) axis data are in complex arrays. X axis arrays are real. An additional array of XYCURVE type may also be given.
Can have a W axis. | W axis is ignored.
Can use IsoScaling. | IsoScaling not supported.

All of the plot customization routines, namely XYPlotFont, XYPlotLegend, XYPlotGaps, XYPlotTicks, XYPlotLabels, XYPlotOverride, and XYPlotMargins, work equally well with both XYPlot and XYPlotComplex.  In addition, there is XYPlotPhase to adjust the height, gaps, and title of a phase banner.


Layout

Standard X-Y Plot Layout

Altho the text which appears on a plot is not surrounded by visible boxes, invisible boxes are used in the layout process. These boxes are sized by XGetTextExtent which returns the minimum size box which will encompass the text using the current font. However, visual aesthetics depend on the space between items. To provide adjustablity a number of "gaps" are defined in the figure below (along with their two-character names). The gaps are highly exagurated in this figure. Title gaps are typically 20-25% of font height. The label gaps, (distance between a label text box and the outer end of major tick mark), are typically zero.

The layout logic is to start at the margins and work toward the center. After the surrounding text and gaps have been accomodated, the remaining space is used for the plot frame.

Legend Layout

A "legend" is an optional feature that can be used to distinguish multiple curves in a plot. It shows a sample of the pen and plotting symbol used for a curve along with the programmer-supplied name for that curve. If the given name of a curve is blank, that curve is omitted from the legend. If used, the legend will appear in one of the inside corners of the plot frame. A magnified view of the gaps used in the layout of a legend is shown below. Note the gaps labeled DV and DH are top or bottom and left or right margins from the plot frame corner. DT is the vertical gap between text lines. DS is length of the pen samples.


XYPlot Reference

XYPlot Reference

Overview

Quick Plot

XYQuickPlot

Plot Creation

XYCURVE

XYPlotInit

XYPlot

Overview

Layout

Plot Customization

XYPlotFont

XYPlotGaps

XYPlotLabels

XYPlotLegend

XYPlotMargins

XYPlotOverride

XYPlotTicks

Magnitude-Phase Plots

XYCURVECOMPLEX

XYPlotComplex

XYPlotPhase


XYQuickPlot

XYQuickPlot

XYQuickPlot produces a simple X-Y plot using default appearance settings.

LOGICAL FUNCTION XYQuickPlot (xWnd, xDC, XARRAY, YARRAY, &
                                XTITLE, YTITLE, TITLE1, TITLE2)
TYPE (X_WINDOW), INTENT(IN)        :: xWnd
TYPE (X_DC), INTENT(INOUT)         :: xDC
REAL(4), TARGET, INTENT(IN)        :: XARRAY(:)
REAL(4), TARGET, INTENT(IN)        :: YARRAY(:) or YARRAY(:,:)
CHARACTER(*), OPTIONAL, INTENT(IN) :: XTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: YTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE1
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE2

Arguments

xWnd

X_WINDOW structure representing the Xeffort plot window.

xDC
 X_DC structure containing information about the DC that is to receive the plot.

XARRAY
An array of the X coordinates (independent values) of the data points to be plotted. There should be at least two data points.

YARRAY
An array of corresponding Y coordinates (dependent values) of the data points to be plotted. The number of rows in YARRAY should equal the number of rows in XARRAY. YARRAY may contain one or more columns. The contents of each column of YARRAY are plotted against XARRAY to form a separate curve on the plot.

[XTitle]
The X-axis title line text.

[YTitle]
The Y-axis title line text.

[Title1]
Text for the top title line.

[Title2]
Text for the second title line.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

The plot produced by XYQuickPlot is rather plain. Both X and Y will be linear axes, sized to encompass the given data. Only a single set of independent values is supported. A legend is not present to distinguish multiple curves. No gridlines, borders, or deviation bars are shown. The resulting plot can be saved only via XGetBitmap / XSaveBitmap. To overcome these limitations, instead call XYPlotInit and XYPlot to use the XYPlot package in its native mode.

Module

XYPlotMod.f90


XYCURVE

XYCURVE

XYCURVE structure describes a curve.

TYPE  XYCURVE
 SEQUENCE
    REAL(4), POINTER :: XDATA(:) => NULL()
    REAL(4), POINTER :: YDATA(:) => NULL()
    CHARACTER(16)    :: NAME = ' '
    TYPE (X_PEN)     :: PEN = X_PEN (0, 0, 0)
    INTEGER          :: PLTSYMB = 0
    REAL(4)          :: HPDSYMB = 2.0
    REAL(4), POINTER :: SIGUP(:) => NULL()
    REAL(4), POINTER :: SIGDN(:) => NULL()
    LOGICAL          :: YISV = .FALSE.
    LOGICAL          :: XISW = .FALSE.
END TYPE XYCURVE

Members

XData
Pointer to a vector (i.e., a one-dimensional array of real numbers, can be a row or column) of independent values. Remember an array that is pointed to must have the Target attribute.

YData
Pointer to a vector of dependent values. Each pair of corresponding elements of the XData, YData arrays forms an X-Y data point. These X-Y data points are joined to form a curve.

Name
Short text string describing the curve. To appear in a legend, a curve must have a non-blank Name.

Pen
 X_PEN structure specifying attributes of the pen used to draw the curve. The default is to use a thin solid line, color black.

PltSymb
An integer between zero and ten from the table below to specify which plotting symbol to use for the curve. Plotting symbols are drawn at the X-Y points. If there are only a few points on the curve, or if Pen specifies an invisible line (iStyle=PS_NULL), then the selected plotting symbol is drawn at every point. Otherwise plotting symbols appear at a few points spaced along the curve.

PltSymb | Symbol | Symbol Description
0 |  | none (no symbol)
1 |  | Square
2 |  | Diamond
3 |  | Plus
4 |  | X
5 |  | Arrowhead Up
6 |  | Arrowhead Right
7 |  | Arrowhead Down
8 |  | Arrowhead Left
9 |  | Hourglass
10 |  | Bowtie

HPDsymb
Size of the plotting symbol as a percent of total plot height. (Internally, plotting symbol sizes will be rounded to the nearest multiple of five pixels).

SigUp, SigDn
These are ignored unless both point to real vectors. The size of these vectors should equal the number of X-Y points. If given, they are used to draw a deviation bar at each point. Deviation bars are drawn as I-beams where the top and bottom flanges are located at (YData + SigUp) and (YData + SigDn). Therefore, if the beam is to straddle the curve, the signs of SigUp and SigDn must differ. The width of the flanges is the size of a plotting symbol, i.e., controlled by HPDsymb. If both SigUp and SigDn are zero at a point, no deviation bar is drawn at that point.

YisV

If .true. then YData points to a dependent vector that is to plotted using the V-axis scale. Normally .false. so YData indeed points to Y-axis data.

XisW

If .true. then XData points to an independent vector that is to plotted using the W-axis scale. Normally .false. so XData indeed points to X-axis data.

Module

XYPlotMod.f90


XYCURVECOMPLEX

XYCURVECOMPLEX

XYCURVECOMPLEX structure points to a complex array that is to be plotted in magnitude-phase form by XYPlotComplex .

TYPE  XYCURVECOMPLEX
SEQUENCE
REAL(4), POINTER    :: XDATA(:) => NULL()
COMPLEX(4), POINTER :: YDATA(:) => NULL()
CHARACTER(16)
  :: NAME = ' '
TYPE (X_PEN)        :: PEN = X_PEN (0, 0, 0)
INTEGER
   :: PLTSYMB = 0
REAL(4)
  :: HPDSYMB = 2.0
LOGICAL
  :: YISV = .FALSE.
END TYPE XYCURVECOMPLEX

Members

XData
Pointer to a real vector (i.e., a one-dimensional array of real numbers, can be a row or column) of independent values. Remember an array that is pointed to must have the Target attribute.

YData
Pointer to a vector of complex dependent values. Each pair of corresponding elements of the XData, YData arrays forms two X-Y data points. one on the magnitude axis and the other on the phase axis. These X-Y data points are joined to form the two curves.

Name
Short text string describing the curve. To appear in a legend, a curve must have a non-blank Name.

Pen
 X_PEN structure specifying attributes of the pen used to draw the curve. The default is to use a thin solid line, color black. Note that dashed and/or dotted line patterns will not be rendered correctly in phase curves. Therefore, it is recommended that you specify a solid pen.

PltSymb
An integer between zero and ten from the table below to specify which plotting symbol to use for the curve. Plotting symbols are drawn at the X-Y points. If there are only a few points on the curve, or if Pen specifies an invisible line (iStyle=PS_NULL), then the selected plotting symbol is drawn at every point. Otherwise plotting symbols appear at a few points spaced along the curve.

PltSymb | Symbol | Symbol Description
0 |  | none (no symbol)
1 |  | Square
2 |  | Diamond
3 |  | Plus
4 |  | X
5 |  | Arrowhead Up
6 |  | Arrowhead Right
7 |  | Arrowhead Down
8 |  | Arrowhead Left
9 |  | Hourglass
10 |  | Bowtie

HPDsymb
Size of the plotting symbol as a percent of total plot height. (Internally, plotting symbol sizes will be rounded to the nearest multiple of five pixels).

YisV

If .true. then the magnitude curve is plotted using the V-axis scale. Normally .false. so magnitudes are plotted on the Y-axis. Phase curves are plotted on the Phase axis, regardless.

Module

XYPlotMod.f90


XYPlotInit

XYPlotInit

Each plot must start by invoking XYPlotInit to set the overall plot size and perhaps some options.

LOGICAL FUNCTION XYPlotInit (xDC, iWidth, iHeight,     &
                             iGrid, iBorder, iBKColor, &
                             bIsoScale, bUseV, bUseW)
TYPE(X_DC), INTENT(INOUT)     :: xDC
INTEGER, INTENT(IN)           :: iWidth
INTEGER, INTENT(IN)           :: iHeight
INTEGER, OPTIONAL, INTENT(IN) :: iGrid
INTEGER, OPTIONAL, INTENT(IN) :: iBorder
INTEGER, OPTIONAL, INTENT(IN) :: iBKColor
LOGICAL, OPTIONAL, INTENT(IN) :: bIsoScale
LOGICAL, OPTIONAL, INTENT(IN) :: bUseV
LOGICAL, OPTIONAL, INTENT(IN) :: bUseW

Arguments

xDC
 X_DC structure containing information about the DC that is to receive the plot.

iWidth
Width of the plot in device units (pixels).

iHeight
Height of the plot in device units (pixels). Plot text, etc., is scaled as a percentage of this value.

[iGrid]
Controls grid lines. Grid lines emanate from tick marks on the X and/or Y axes. The presence of a V or W axis precludes grid lines by default, since the grid lines would generally not align with the ticks on the opposite axis. Enter one (or an OR'd combination) of the named constants or values from the table below. Grid_Off and Grid_Full are the most common choices. If absent, Grid_Off is assumed.

Named Constant | Value | Notes
Grid_Off | 0 | No grid lines except along the X= 0 and/or Y= 0 lines if they appear within the plot frame
Grid_Horizontal | 1 | From Y axis major ticks
Grid_Vertical | 2 | From X axis major ticks
Grid_Both | 3 | Draw coarse grid
Grid_AtMajor | 0 | Does nothing
Grid_AtMinor | 4 | Include minor ticks too
Grid_Full | 7 | Draw fine grid
Grid_OnZero | 8 | Forces grid lines along the X=0 and/or Y=0 lines even in the presence of V or W axes
Grid_On | 16 | Forces grid lines even in the presence of V or W axes

[iBorder]
A border is a line on the plot frame boundary opposite an axis. A border can have tick marks copied from it's opposing axis. Unlike axes, borders never have labels or title lines. Enter one of the named constants or values from the table below. If absent, BorderOff is assumed.

Named Constant | Value | Notes
BorderOff | 0 | No border
BorderPlain | 1 | Border without tick marks
BorderTicks | 2 | Border with tick marks

[iBKColor]
A composite integer containing the red, green, blue intensities of the background color. See XRGB . If absent, XCOLOR_WHITE is assumed.

[bIsoScale]
If present and .true., the X or Y axis will be shortened as necessary such that both axes have the same number of pixels/unit. Therefore, as the plot is resized, slopes and angles remain true and unchanged, circles do not become ovals, etc. Note this option makes sense only if both axes represent the same physical units, e.g., both inches, both MPa, both unitless, etc., and if the ranges are similar so that the axis with the smaller range does not become vanishingly small. This option is incompatible with the presence of a V or W axis; if either bUseV or bUseW is present and .true., bIsoScale is treated as .false. If absent, bIsoScale is assumed .false.

[bUseV]
If present and .true., the plot is to have a V axis. If absent, bUseV is considered .false. and the plot will not have a V axis and any V axis data will be ignored.

[bUseW]
If present and .true., the plot is to have a W axis. If absent, bUseW is considered .false. and the plot will not have a W axis and any W axis data will be ignored.

Return Value

.TRUE. if successful, otherwise .FALSE.

See Also

XYPlot

Module

XYPlotMod.f90


XYPlot

XYPlot

XYPlot produces a plot. It must be preceded by a call to the XYPlotInit function.

LOGICAL FUNCTION XYPlot (xDC, CURVE, XTITLE, YTITLE, &
                         TITLE1, TITLE2, LEGEND,     &
                         XAxisType, YAxisType,       &
                         XLO, XHI, YLO, YHI,         &
                         VTITLE, VAxisType, VLO, VHI,&
                         WTITLE, WAxisType, WLO, WHI )
TYPE (X_DC), INTENT(INOUT)         :: xDC
TYPE (XYCURVE), INTENT(IN)         :: CURVE(:)
CHARACTER(*), OPTIONAL, INTENT(IN) :: XTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: YTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE1
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE2
INTEGER, OPTIONAL, INTENT(IN)      :: LEGEND
INTEGER, OPTIONAL, INTENT(IN)      :: XAxisType
INTEGER, OPTIONAL, INTENT(IN)      :: YAxisType
REAL(4), OPTIONAL, INTENT(IN)      :: XLO
REAL(4), OPTIONAL, INTENT(IN)      :: XHI
REAL(4), OPTIONAL, INTENT(IN)      :: YLO
REAL(4), OPTIONAL, INTENT(IN)      :: YHI

CHARACTER(*), OPTIONAL, INTENT(IN) :: VTITLE
INTEGER, OPTIONAL, INTENT(IN)      :: VAxisType
REAL(4), OPTIONAL, INTENT(IN)      :: VLO
REAL(4), OPTIONAL, INTENT(IN)      :: VHI
CHARACTER(*), OPTIONAL, INTENT(IN) :: WTITLE
INTEGER, OPTIONAL, INTENT(IN)      :: WAxisType
REAL(4), OPTIONAL, INTENT(IN)      :: WLO
REAL(4), OPTIONAL, INTENT(IN)      :: WHI

Arguments

xDC
 X_DC structure containing information about the DC that is to receive the plot.

CURVE
An array of XYCURVE derived types. The number of elements in this array equals the number of curves on the plot. Thus CURVE must be dimensioned at least one.

[XTitle]
The X-axis title line text.

[YTitle]
The Y-axis title line text.

[Title1]
Text for the top title line.

[Title2]
Text for the second title line.

[Legend]
Controls placement of the legend. The legend shows a sample of the pen and plotting symbol along with the curve's name for for the various curves on a plot. Enter one of the named constants or values from the table below. If absent, LegendNone is assumed.

Named Constant | Value | Notes
LegendNone | 0 | No legend will appear.
LegendUprLeft | 1 | Put legend in the upper-left corner.
LegendUprRight | 2 | Put legend in the upper-right corner.
LegendLwrRight | 3 | Put legend in the lower-right corner.
LegendLwrLeft | 4 | Put legend in the lower-left corner.

[XAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Standard linear axis at the bottom.
LogAxis | 1 | Logarithmic axis. Requires all X data be .gt. 0
AxisOnZero | 2 | Linear axis drawn on the Y= 0 line if zero is within the Y-axis limits and if V or W axes not used, else axis drawn at the bottom of the plot frame.

[YAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Standard linear axis on the left.
LogAxis | 1 | Logarithmic axis. Requires all Y data be .gt. 0
AxisOnZero | 2 | Linear axis drawn on the X= 0 line rather than at the left side of the plot frame provided zero is in the X range and no V or W axes.

[Xlo, Xhi]
If both of these are present and have different values, i.e., Xlo .NE. Xhi, those values are used as the X-axis limits. Otherwise, the program will pick "nice" limits that encompass the X axis data.

[Ylo, Yhi]
If both of these are present and have different values, those values are used as the Y-axis limits. Otherwise, the program will pick "nice" limits that encompass all Y axis data.

Note: The values given for VTitle, VAxisType, Vlo, Vhi will be ignored unless the bUseV argument to XYPlotInit is present and .true.

[VTitle]
The V-axis title line text.

[VAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Linear axis on the right side.
LogAxis | 1 | Logarithmic axis. Requires all V data to be .gt. 0

[Vlo, Vhi]
If both of these are present and have different values, those values are used as the V-axis limits. Otherwise, the program will pick "nice" limits that encompass all V axis data.

Note: The values given for WTitle, WAxisType, Wlo, Whi will be ignored unless the bUseW argument to XYPlotInit is present and .true.

[WTitle]
The W-axis title line text.

[WAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Linear axis on top edge of the frame.
LogAxis | 1 | Logarithmic axis. Requires all W data to be .gt. 0

[Wlo, Whi]
If both of these are present and have different values, those values are used as the W-axis limits. Otherwise, the program will pick "nice" limits that encompass all W axis data.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

Titles are truncated at 80 characters. Any element of the CURVE array that has a disassociated XDATA or YDATA pointer is silently ignored and does not produce a curve. At least one element of CURVE must produce a plot for this function to return .true.

See Also

XYPlotInit

Module

XYPlotMod.f90


XYPlotComplex

XYPlotComplex

XYPlotComplex produces a magnitude-phase plot. It must be preceded by a call to the XYPlotInit function.

LOGICAL FUNCTION XYPlotComplex (xDC, XCURVE,
&
XTITLE, YTITLE,         &
TITLE1, TITLE2, LEGEND, &
XAxisType, YAxisType,   &
XLO, XHI, YLO, YHI,     &
CURVE,                  &
VTITLE, VAxisType, VLO, VHI)
TYPE (X_DC), INTENT(INOUT)         ::
xDC
TYPE
(XYCURVECOMPLEX), INTENT(IN)  ::
XCURVE(:)
CHARACTER(*), OPTIONAL, INTENT(IN) :: XTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: YTITLE
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE1
CHARACTER(*), OPTIONAL, INTENT(IN) :: TITLE2
INTEGER, OPTIONAL, INTENT(IN)      :: LEGEND
INTEGER, OPTIONAL, INTENT(IN)      :: XAxisType
INTEGER, OPTIONAL, INTENT(IN)      :: YAxisType
REAL(4), OPTIONAL, INTENT(IN)      :: XLO
REAL(4), OPTIONAL, INTENT(IN)      :: XHI
REAL(4), OPTIONAL, INTENT(IN)      :: YLO
REAL(4), OPTIONAL, INTENT(IN)      :: YHI
TYPE (XYCURVE), INTENT(IN)         ::
CURVE(:)

CHARACTER(*), OPTIONAL, INTENT(IN) :: VTITLE
INTEGER, OPTIONAL, INTENT(IN)      :: VAxisType
REAL(4), OPTIONAL, INTENT(IN)      :: VLO
REAL(4), OPTIONAL, INTENT(IN)      :: VHI

Arguments

xDC
 X_DC structure containing information about the DC that is to receive the plot.

XCURVE
An array of XYCURVECOMPLEX derived types. Each element in this array can produce a magnitude-phase curve set. XCURVE must be dimensioned at least one.

[XTitle]
The X-axis title line text.

[YTitle]
The Y-axis title line text.

[Title1]
Text for the top title line.

[Title2]
Text for the second title line.

[Legend]
Controls placement of the legend. The legend shows a sample of the pen and plotting symbol along with the curve's name for for the various curves on a plot. Enter one of the named constants or values from the table below. If absent, LegendNone is assumed.

Named Constant | Value | Notes
LegendNone | 0 | No legend will appear.
LegendUprLeft | 1 | Put legend in the upper-left corner.
LegendUprRight | 2 | Put legend in the upper-right corner.
LegendLwrRight | 3 | Put legend in the lower-right corner.
LegendLwrLeft | 4 | Put legend in the lower-left corner.

[XAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Standard linear axis at the bottom.
LogAxis | 1 | Logarithmic axis. Requires all X data be .gt. 0
AxisOnZero | 2 | Linear axis drawn on the Y= 0 line provided zero is within the Y-axis limits and if a V axis is not used, else a linear axis is drawn at the bottom of the plot frame.

[YAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Standard linear axis on the left.
LogAxis | 1 | Logarithmic axis. Requires all Y data be .gt. 0
AxisOnZero | 2 | Linear axis drawn on the X= 0 line rather than at the left side of the plot frame provided zero is in the X range and no V axis is used.

[Xlo, Xhi]
If both of these are present and have different values, i.e., Xlo .NE. Xhi, those values are used as the X-axis limits. Otherwise, the program will pick "nice" limits that encompass the X axis data.

[Ylo, Yhi]
If both of these are present and have different values, those values are used as the Y-axis limits. Otherwise, the program will pick "nice" limits that encompass all Y axis data.

[CURVE]
An optional array of XYCURVE derived types. The elements in this array produce additional real curves on the plot. Any elements that reference the W axis will be skipped. Nothing is drawn in the phase banner for these CURVE elements.

Note: The values given for VTitle, VAxisType, Vlo, Vhi will be ignored unless the bUseV argument to XYPlotInit is present and .true.

[VTitle]
The V-axis title line text.

[VAxisType]
Enter one of the named constants or values from the table below. If absent, LinearAxis is assumed.

Named Constant | Value | Notes
LinearAxis | 0 | Linear axis on the right side.
LogAxis | 1 | Logarithmic axis. Requires all V data to be .gt. 0

[Vlo, Vhi]
If both of these are present and have different values, those values are used as the V-axis limits. Otherwise, the program will pick "nice" limits that encompass all V axis data.

Return Value

.TRUE. if successful, otherwise .FALSE.

Remarks

Titles are truncated at 80 characters. Any element of the XCURVE or CURVE array that has a disassociated XDATA or YDATA pointer is silently ignored and does not produce a curve. At least one element of XCURVE must produce a magnitude-phase plot for this function to return .true.

See Also

XYPlotInit, XYPlot, XYPlotPhase

Module

XYPlotMod.f90


XYPlotFont

XYPlotFont

XYPlotFont is used to customize the typefaces, sizes, and colors of the text items used on a plot. All text items that share the same font specification can be set in a single call.

SUBROUTINE XYPlotFont (iAt, sFontName, HPD,  iColor,      &
                        WHPD, iWeight, bItalic, bUnderline)
INTEGER, INTENT(IN)::             iAt         !TX_ combo
CHARACTER(*), INTENT(IN)::        sFontName   !typeface
REAL(4), INTENT(IN)::            HPD         !char Height
INTEGER, OPTIONAL, INTENT(IN)::  iColor      !Font color
REAL(4), OPTIONAL, INTENT(IN)::  WHPD        !Font width
INTEGER, OPTIONAL, INTENT(IN)::  iWeight     !Font weight
LOGICAL, OPTIONAL, INTENT(IN)::  bItalic     !Italic font
LOGICAL, OPTIONAL, INTENT(IN)::   bUnderline  !Underlined

Arguments

iAt
Enter one (or an OR'd combination) of the named constants or values from the table below to specify the text items to which this font specification applies.

Named Constant | Value | Notes
TX_TopLine | 1 | Top title line
TX_2ndLine | 2 | Second title line
TX_Xaxis | 4 | X axis title
TX_Yaxis | 8 | Y axis title
TX_Vaxis | 16 | V axis title
TX_Waxis | 32 | W axis title
TX_Legend | 64 | Curve distinction legend
TX_Xlabels | 128 | Tick labels on X axis
TX_Ylabels | 256 | Tick labels on Y axis
TX_Vlabels | 512 | Tick labels on V axis
TX_Wlabels | 1024 | Tick labels on W axis
TX_PhaseLabels | 2048 | Labels on Phase axis
TX_PhaseAxis | 4096 | Phase axis title
TX_Axes | 60 | X,Y,V,W axis titles
TX_Labels | 1920 | X,Y,V,W tick labels

sFontName

Name of the typeface, such as "Arial" or "Times New Roman". If the requested typeface is not installed on the system, Windows font mapper will try to substitute a font with the most similar characteristics.

HPD
Height of the font, as a percent of total plot height if positive, or in pixels if negative. Fonts usually are in the 2.5% to 6% range, with a large size used for titles, a small size for the legend, and an intermediate size for labels.

[iColor]
A composite integer containing the red, green, blue intensities of the text color. See XRGB . If absent, XCOLOR_BLACK is assumed.

[WHPD]

Average width of a character, as a percent of total plot height if positive, or in pixels if negative. If not present, default font width is used.

[iWeight]

Weight of the font, in range of 0 to 1000. If omitted, default font weight is used (0). The following constants are also defined for convenience:

Value | Weight
FW_DONTCARE | 0
FW_THIN | 100
FW_EXTRALIGHT | 200
FW_ULTRALIGHT | 200
FW_LIGHT | 300
FW_NORMAL | 400
FW_REGULAR | 400
FW_MEDIUM | 500
FW_SEMIBOLD | 600
FW_DEMIBOLD | 600
FW_BOLD | 700
FW_EXTRABOLD | 800
FW_ULTRABOLD | 800
FW_HEAVY | 900
FW_BLACK | 900

[bItalic]

If present and .TRUE., specifies that the italic version of the font is requested.

[bUnderline]

If present and .TRUE., specifies that the font is underlined.

Remarks

If this routine is not used, the default typeface is "Arial" and the sizes are 5.0 (%) for all titles, 4.0 (%) for labels, and 3.0 (%) for legend text. Phase axis title and lablels use 2.2 (%).

Module

XYPlotMod.f90


XYPlotGaps

XYPlotGaps

XYPlotGaps specifies the "line-spacing" gaps for text items. See Layout for a pictorial representation of these gaps. Each gap is expressed as an HPD, i.e., a positive value is interpreted as a percent of drawing surface height, while a negative value is a pixel count.

SUBROUTINE XYPlotGaps  (TT, T2, TX, TY, LX, LY, TV, LV, TW, LW)

REAL(4), OPTIONAL, INTENT(IN) :: TT
REAL(4), OPTIONAL, INTENT(IN) :: T2
REAL(4), OPTIONAL, INTENT(IN) :: TX
REAL(4), OPTIONAL, INTENT(IN) :: TY
REAL(4), OPTIONAL, INTENT(IN) :: LX
REAL(4), OPTIONAL, INTENT(IN) :: LY
REAL(4), OPTIONAL, INTENT(IN) :: TV
REAL(4), OPTIONAL, INTENT(IN) :: LV
REAL(4), OPTIONAL, INTENT(IN) :: TW
REAL(4), OPTIONAL, INTENT(IN) :: LW

Arguments

[TT]
Gap under the top title line.

[T2]
Gap under the second title line.

[TX]
Gap between X-axis title and X-axis labels.

[TY]
Gap between Y-axis title and Y-axis labels.

[LX]
Gap between X-axis labels and major tick marks.

[LY]
Gap between Y-axis labels and major tick marks.

[TV]
Gap between V-axis title and V-axis labels.

[LV]
Gap between V-axis labels and major tick marks.

[TW]
Gap between W-axis title and W-axis labels.

[LW]
Gap between W-axis labels and major tick marks.

Remarks

If this routine is not called, the title [T_] gaps are 1.0 (%), and the label gaps [L_] are zero.

See Also

XYPlotLegend

Module

XYPlotMod.f90


XYPlotLabels

XYPlotLabels

XYPlotLabels can be used to change the orientation of axis labels. It can also be used to override label text. This feature is our sole concession to business plots. For instance, you may have an axis whose major tick marks would ordinarily be labeled 1,2,3,... You could change those labels to Jan,Feb,Mar,... .

SUBROUTINE XYPlotLabels (AxisInd, iOrient, sCustom)

INTEGER, INTENT(IN)                :: AxisInd
INTEGER, OPTIONAL, INTENT(IN)      :: iOrient
CHARACTER(*), OPTIONAL, INTENT(IN) :: sCustom(:)

Arguments

AxisInd
Enter one (or rarely an OR'd combination) of the named constants or values from the table below to specify the axis whose labeling is being customized.

Named Constant | Value
X_Axis | 1
Y_Axis | 2
V_Axis | 4
W_Axis | 8

[iOrient]
Enter one of the values from the table below to specify label orientation. Note the default convention is to use horizontal lettering on horizontal axes (X and W) and vertical lettering on vertical (Y and V) axes.

Value | Meaning
0 | Use default
1 | Horizontal lettering
2 | Vertical lettering (rotate 90°)
3 | Omit labels

[sCustom]
An array of text strings, one element for each major tick mark on the axis. Use a blank element for any major tick mark that is to go unlabeled. Only the first 16 characters of a custom label are output. Minor tick marks are never labeled.

This often means that you must first plot the data permitting numeric labels in order to find the number of, and the meaning of, the major ticks before you can assign the custom labels. Alternatively, you may force a predetermined number of major tick marks on an axis by using XYPlotOverride.

Remarks

If this routine is used, it must follow XYPlotInit and precede either XYPlot or XYPlotComplex.

Module

XYPlotMod.f90


XYPlotLegend

XYPlotLegend

XYPlotLegend specifies the spacing gaps in and around the legend. See Legend Layout for a pictorial representation of these gaps. Each gap is expressed as an HPD, i.e., a positive value is interpreted as a percent of drawing surface height, while a negative value is a pixel count.

SUBROUTINE XYPlotLegend (DS, DT, DH, DV, DA)

REAL(4), OPTIONAL, INTENT(IN) :: DS
REAL(4), OPTIONAL, INTENT(IN) :: DT
REAL(4), OPTIONAL, INTENT(IN) :: DH
REAL(4), OPTIONAL, INTENT(IN) :: DV
REAL(4), OPTIONAL, INTENT(IN) :: DA

Arguments

[DS]
Length of the pen sample line. (10.0)

[DT]
Gap between curve name text lines. (0.9)

[DH]
Vertical margin between plot frame and legend. (2.5)

[DV]
Horizontal margin between plot frame and legend. (2.5)

[DA]
Gap between end of line sample and start of curve name. (1.0)

Remarks

The numbers in parentheses above are the initial default percent of height values.

See Also

XYPlotGaps

Module

XYPlotMod.f90


XYPlotMargins

XYPlotMargins

XYPlotMargins can be used to impose additional blank space between the edges of the drawing surface or window and the outer boundaries of the plot, thus reducing the size of the plot. Margin dimensions are given as HPD's, i.e., a positive value is interpreted as a percent of drawing surface height, while a negative value is a pixel count.

SUBROUTINE XYPlotMargins (xDC, LEFT, TOP,
RIGHT, BOTTOM)

TYPE(X_DC),
INTENT(INOUT)     :: xDC
REAL(4),
OPTIONAL, INTENT(IN) :: LEFT
REAL(4), OPTIONAL,
INTENT(IN) :: TOP
REAL(4), OPTIONAL,
INTENT(IN) :: RIGHT
REAL(4), OPTIONAL,
INTENT(IN) :: BOTTOM

Arguments

xDC
 X_DC structure containing information about the DC that is to receive the plot.

[LEFT]
Additional left margin HPD.

[TOP]
Additional top margin HPD.

[RIGHT]
Additional right margin HPD.

[BOTTOM]
Additional bottom margin HPD.

Remarks

If this routine is used, it must follow XYPlotInit and precede either XYPlot or XYPlotComplex.

Module

XYPlotMod.f90


XYPlotOverride

XYPlotOverride

XYPlotOverride overrides the normal placement of tick marks along an axis. Calculations here are based on the range of the axis. The range is the positive difference between the axis end points, e.g., Xhi - Xlo.

SUBROUTINE XYPlotOverride (AxisInd, Delta, Nth, Minors)

INTEGER, INTENT(IN)   :: AxisInd
REAL(4), INTENT(IN)   :: Delta
INTEGER, INTENT(IN)   :: Nth
INTEGER, INTENT(IN)   :: Minors

Arguments

AxisInd
Enter one (or rarely an OR'd combination) of the named constants or values from the table below to specify the axis whose tick placement is being customized.

Named Constant | Value
X_Axis | 1
Y_Axis | 2
V_Axis | 4
W_Axis | 8

Delta
The spacing between minor tick marks. Note Delta must have the same units as the range, and must be between zero and the range. The total number of tick marks will equal (1 + INT (range / Delta)).

Nth

This is the sequence number of the first minor tick mark that is to be promoted to a major tick. Enter 1 if the axis is to start with a major tick mark.

Minors

Enter the number of minor tick marks that are to appear between each consecutive pair of major tick marks. Enter zero if all tick marks are to become major tick marks.

Remarks

Because the tick marks specified here have equal spacing, an attempt to override tick marks on a logarithmetic axis will be ignored.

Only major tick marks may have labels. Those labels should be entered via XYPlotLabels. The maximum number of major tick mark labels is 60.

If this routine is used, it must follow XYPlotInit and precede either XYPlot or XYPlotComplex.

Module

XYPlotMod.f90


XYPlotPhase

XYPlotPhase

XYPlotPhase is used to set the size, gaps, and title of the phase banner produced by XYPlotComplex .

SUBROUTINE XYPlotPhase (BannerSize, BannerGap, &
                       PhaseTitleGap, PhaseTitle)
REAL(4), OPTIONAL, INTENT(IN) :: BannerSize
REAL(4), OPTIONAL, INTENT(IN) :: BannerGap
REAL(4), OPTIONAL, INTENT(IN) :: PhaseTitleGap
CHARACTER(*), OPTIONAL, INTENT(IN) :: PhaseTitle

Arguments

[BannerSize]
 This is an HPD specifying the height of the phase banner, i.e., the distance between the +180° and -180° lines. The default value is 12.0 (%). If zero is given, the phase banner will be omitted, and only the magnitudes of the complex quantities are plotted.

[BannerGap]
 This HPD specifies an additional vertical gap between the -180° line and the tick mark zone on the top border of the main plot frame. The default value is zero.

[PhaseTitleGap]
This HPD specifies an additional horizontal gap between the phase axis title and the phase axis labels. The default value is zero. The phase axis title is rotated vertical while the phase axis labels appear horizontal.

[PhaseTitle]
Text of the phase axis title. Default value is "Phase". If the title is too long to fit within the room provided by BannerSize , the title is not displayed.

Module

XYPlotMod.f90


XYPlotTicks

XYPlotTicks

XYPlotTicks is used to set the size, placement, color, and maximum number of, tick marks on an axis. All axes that share the same tick mark specification can be set in a single call.

SUBROUTINE XYPlotTicks (AxisInd, HPDMajor, HPDMinor, &
                         MajorPLC, MinorPLC, &
                         MaxTicks, iColor)
INTEGER, INTENT(IN)           :: AxisInd
REAL(4), OPTIONAL, INTENT(IN) :: HPDMajor
REAL(4), OPTIONAL, INTENT(IN) :: HPDMinor
INTEGER, OPTIONAL, INTENT(IN) :: MajorPLC
INTEGER, OPTIONAL, INTENT(IN) :: MinorPLC
INTEGER, OPTIONAL, INTENT(IN) :: MaxTicks
INTEGER, OPTIONAL, INTENT(IN) :: iColor

Arguments

AxisInd
Enter one (or an OR'd combination) of the named constants or values from the table below to specify the axes to which this tick specification applies.

Named Constant | Value | Notes
X_Axis | 1 | X axis
Y_Axis | 2 | Y axis
V_Axis | 4 | V axis
W_Axis | 8 | W axis
XY_Axes | 3 | X and Y axes
All_Axes | 15 | X, Y, V, and W axes

[HPDMajor]
Height of a major tick mark, as a percent of total plot height if positive, or in pixels if negative. Default is 3.0 (%).

[HPDMinor]
Height of a minor tick mark, as a percent of total plot height if positive, or in pixels if negative. Default is 1.5 (%).

[MajorPLC]
Enter one of the named constants or values from the table below to specify where major tick marks are to be placed.

Named Constant | Value | Notes
TicksOutside | 0 | Outside the plot frame (default)
TicksInside | 1 | Inside the plot frame
TicksBothSides | 2 | Both inside and outside
TicksNone | 3 | Do not draw tick marks

[MinorPLC]
Enter one of the named constants or values from the table above to specify where minor tick marks are to be placed.

[MaxTicks]
Maximum number of tick marks (major plus minor) allowed on an axis. Whenever the total numer of tick marks would exceed this value, only the major tick marks are drawn. Default value is 75.

[iColor]
A composite integer containing the red, green, blue intensities of the tick marks. See XRGB . If absent, XCOLOR_BLACK is assumed.

Module

XYPlotMod.f90


Status Bar Support

Status Bar Support

The following control options are available for status bars:

result = XCtlSet/XCtlGet(xWnd, idStatus, sText, n)

  • Value as a character string sets or retrieves text sText of n-th field of the status bar

result = XCtlSet/XCtlGet(xWnd, idStatus, hIcon, n)

  • Value as a handle of an icon sets or retrieves handle of an icon of n-th field of the status bar. 16x16 icons are recommended.

result = XCtlSet/XCtlGet(xWnd, idStatus, (/20, 80, 180, -1/), CTL_RECTS)

  • CTL_RECTS sets/retrieves the number and positions of status bar fields. In the sample above, there are four fields, first 20 pixels wide, second is (80-20) pixels wide, third (180-80) pixels wide, and the last extends to status bar's width.

Remarks

Status bars do not exist as an item in VS resource editor, but they can be added using "Custom Control" and specifying msctls_statusbar32 as class name. Alternately, status bars may be created by XCtlCreate .