Version www.capesoft.com Updated Tuesday 15 July 2008

Contents

Introduction

Copyright

Support

Installation

Distribution

How to read this manual

Example Program

Enabling WinEvent Functions
WinAlert Functions
Comm's Functions  
Taskbar Functions  
Window Behaviour Functions
Windows System Functions
RAM & Disk Functions
Time & Date Functions
File Functions
Process & Thread Functions
DLL Functions
SMS Functions
Debugging & Error Reporting Functions
Auto-Shutdown Functions
Other Functions
Reference Section
Frequently Asked Questions (FAQ's)
Version History

Introduction

Welcome to WinEvent. This small library package allows you to leverage the power of the Windows API. In addition to the WinAlert functions (which allow you access to the native Windows messages) there are also now Comm's (RS232) functions, Taskbar functions and Windows Behaviour & System functions.

All the functionality provided in WinEvent is built into Windows itself in one way or another. The main advantage of WinEvent is two fold.

Main Advantages
		It provides the functions in a simple easy-to-use manner, avoiding the complexities of the Windows API.
		The functions are (mostly) cross-compatible between 16 and 32 bit implementations of your program. The Taskbar functions and some advanced Comm's functions are only available in 32 bit programs, but all the other functions are the same in 16 and 32 bit programs.

WinEvent functionality is divided into 5 areas:

Functionality
		Windows message capturing functions (WinAlert) WinAlert allows your CW programs more access to the native Window messages. This is in itself nothing new. Using the sub-classing technique access to the Windows messages has been available since almost the first days of CW. WinAlert provides a simple wrapper to subclassing, which removes the complexities and makes the code both simple to follow, easy to implement, and consistent with the rest of the Clarion language. In essence one new major function, and a couple of support functions allow the flexibility and ease of use that we've come to expect from Clarion. In addition it comes with a template that makes adding this wrapper to your applications even easier. You can use the template to alert messages on individual windows. In addition a utility template makes it possible to enable Auto Shut Down across your entire application.
		RS 232 Port functions Very often developers need simple access to a Comm's port. This simple functionality is built into the Windows API, but is quite complex and difficult to code. In addition to this the APIs for 16 bit and 32 bit Windows are very different. The Comm's section of the WinEvent package provides some simple easy-to-use functions that allow you to read and write to Comm's ports. In addition almost all the functions are the same in 16 and 32 bit ( the library takes care of the API differences ) so it's easier to move from one platform to another. The library also corrects a bug in the Windows functions that affect Comm's at speeds of greater than 19200. Some advanced functions to test specific hardware handshaking lines for their current status are only supported in 32 bit as no 16 bit equivalent exists.
		Taskbar functions Users of Windows 95, and Windows NT 4.0, will be familiar with the Taskbar that usually sits at the bottom of the screen. The taskbar functions allow you to add / change and delete an icon from the "Tray" ( the area at the right hand side of the taskbar ) as well as detect when the mouse has been clicked on an icon in the tray. This is very useful for apps which are running in the background on a full time basis. In addition, you can make use of a function that prevents your program from appearing on the main area of the Taskbar itself.
		Window behaviour functions A small group of functions that allow you to change the behaviour of a window. This includes the ability to make a window permanently "on top", and also the ability to bring the window to the front.
		System functions These functions return system information to your application. The Windows, and Dos (if applicable) version numbers are available to your application. Also you are able to get the current free disk space in 16 and 32 bit. This is useful for detecting low disk space conditions before they occur. A function for playing a wav file is also included.

Copyright

WinEvent is copyrighted © 2008 by CapeSoft Software (Pty) Ltd. CapeSoft Software (Pty) Ltd assumes no responsibility for applications created which incorporate WinEvent. WinEvent is used entirely at your own risk. You may not distribute any of the WinEvent files.

Each developer needs his own license to use WinEvent. (Need to buy more licenses?)

Support

We welcome your comments, suggestions, and criticisms. Please do not hesitate to contact us if you have a problem, or a suggestion.

You can contact CapeSoft in one of the following ways:

CapeSoft Support
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Purchase WinEvent at $149.00 from:

Buy Online
	Web	www.clarionshop.com

Installation

To install WinEvent, run the supplied installation file and follow the prompts.

Distribution

You are free to distribute the WinEvent DLLs with any of your Applications without extra charge.

The DLLs your program require will depend on your version of Clarion. Note that programs compiled in Local Mode do not use DLLs and therefore there is nothing extra for you to distribute.

How To Read this Manual

This manual is split into two sections. This first section contains a general overview of the WinEvent features. Each of the WinEvent function areas is dealt with and the templates provided are discussed here.

The second section is the Technical Reference. In this section the individual functions are described, along with their syntax. This is particularly useful as most of these functions are designed to be used in simple embed points etc.

Example Program

Included in the WinEvent package is a simple example program that demonstrates all of WinEvent's features. This example is in the \Clarion\3rdParty\Examples\Winevent\Windemo directory and is called WinDemo.

There is also an example of a barcode collector program. This is stored in \Clarion\3rdParty\Examples\Winevent\Barcode
 

Enabling WinEvent Functions

To use the WinEvent functions in your application you must first enable them. This is done by selecting the Global Properties option from the Application dropdown menu, selecting the Extensions button then the Insert button, scrolling down the extension options and then selecting EnableWinEvent - Enable the WinEvent functions in your app.

On the Settings tab of the WinEvent global extension template:

The Auto-Shutdown on tick box to apply the automatic shutdown function to your application. This will then be globally applied to the application. By default, this feature is on, but you can disable it here if you'd like to. You can also disable it at a local level as well.

The Make windows visible on Desktop will ensure that when your windows open, they are visible on the desktop area. You can disable this locally if there are specific windows that don't require this feature (otherwise by default it will be on for all windows in your application).

WinAlert Functions

The Concept

First some terminology. An Event is the Clarion word for a message that is provided to you via the ACCEPT loop. A Message is the Windows equivalent. Part of the job of the Accept command is to filter out many of these Messages, and pass on only those Events that are usually required.

The idea is to use a new function, called WinAlert in the same way you would use the Alert function for keystrokes. This allows you to get at the messages before the Accept command does, taking further action where it is required. In addition to simply spotting the message, you can also specify its action at the same time. Some messages require an immediate reply (usually True or False) to the procedure that sent the message. However most messages would be required simply so that you can gain more control over the things that are happening. In this case a user event, is posted to the Accept loop, after storing the value of the Message.

To further complicate the issue Messages can also have additional data tagged on with them. This data is stored in 2 variables, often going by the somewhat cryptic names of wParam and lParam. The w and l represent the data type (w for Word - ie a Short (16bit programs) or Long (32 bit programs) and l for Long). On receiving the User event, WinMessageEvent you can use 2 new support functions, WinParam1() and WinParam2() to get the values of these parameters when the message arrived, as well as the Winevent() function to see which windows message triggered the event.

The Classic Example

One of the most frequently asked questions on the Internet's cw-talk mailing list, is "How do I get my application to terminate automatically when the user shuts down Windows ?" Using WinEvent the answer is both simple and elegant. you simply add the WinEvent global extension template and leave the defaults checked and away you go.

Using the Local WinEvent: Alert Windows Messages Template

You can override some of the global defaults set in the Global WinEvent Extension template in the WinEvent: Alert Windows Messages local extension template that is populated onto each window:

• If Auto Shutdown has been globally set for your application, this option will enable you to disable the Auto Shutdown for when a selected window is the focus window (i.e. a window that requires you to save information before closing).

• Make this window visible on Desktop allows you to either use the Default option (i.e. the setting in the Global Extension template) - or force it to override the global default option using the Yes or No option.

• You can also use the Append compile date to title bar - which by default is turned off as it would only be necessary on one of your windows in your application (if you require this functionality).

Using WinAlert in Applications

The WinEvent extension template, which is included, assist's you in using the WinAlert functions. It organizes in one place the three items that are required, namely Alerting the message, handling any action that may be required, and unAlerting the message before closing the window. The template leads you through the options that you have, and provides you with the required embed point for processing the WinMessageEvent. You may alert as many Windows messages as you like.

You can view a list of the Windows Messages to equate in the eventequ.clw file (which is found in your Clarion6\3rdparty\libsrc directory).

Action (group 1):

WinAccept is a event handler that will accept the windows event before it arrives at your window. Action (group 1) determines what reply WinAccept must do (for the Windows Kernel) when this event is received. If Return 1 or Return 0 is selected, then those values are returned to the Windows kernel, otherwise the event is passed on to Clarion for Clarion to return a value to the Windows kernel.

Action (group 2):

These options are telling WinAccept what to do with the event - in terms of forwarding it on to your Clarion procedure. There are 3 possible options you can select:

• None will do nothing further with the event received.

• Post WinMessageEvent will post the user event on to the Event handler (which means you can run code when that event is passed to the event handler).

case Event() - WinMessageEvent
of 0 ! WinMessageEvent
  !Put your code in here to process when this event is received. 

• Post Equivalent Event will assess the received windows message and post a suitable Clarion equivalent to the window as follows:

Windows Message	Clarion Event posted
WE::WM_CLOSE	Event:CloseWindow
WE::WM_MOUSEMOVE	Event:MouseMove
WE::WM_NCMOUSEMOVE
WE::WM_TIMER	Event:Timer
WE::WM_LBUTTONDOWN	Event:MouseDown
WE::WM_RBUTTONDOWN
WE::WM_NCRBUTTONDOWN
WE::WM_NCLBUTTONDOWN
WE::WM_NCMBUTTONDOWN
WE::WM_MBUTTONDOWN
WE::WM_LBUTTONUP	Event:MouseUp
WE::WM_RBUTTONUP
WE::WM_NCRBUTTONUP
WE::WM_NCLBUTTONUP
WE::WM_NCMBUTTONUP
WE::WM_MBUTTONUP

Please Note: If using the WE::WM_MouseWheel on a window with a listbox, then only the mouse wheel events occurring when the mouse wheel button is depressed will be passed to the WinAccept. Windows will only pass on the mouse wheel events when a list box is not present.

For those that care

Basically when you ask Windows to shut itself down it polls each running application by sending it the WM_QueryEndSession message. If all the applications respond by returning True, then they are each, in turn, instructed to close. In the above line of code you are telling the WinEvent library, that when the window receives this message, then it must return True. The utility template automatically adds an instance of the WinEvent extension template to each of your procedures.

Using WinAlert in a Hand Coded Project

This details how to add WinAlert functionality to a hand-coded project. For a detailed description of each of the functions, see the Reference section of this document.

Adding WinAlert to a function
		Use the WinAlert function to alert the message. This should be called before the Accept command, but after the window is opened.
		Use the WinAlert function, with no parameters, before Closing the window.
		Use the WinEvent's WinControl, WinParam1 and WinParam2 functions to examine the message.

Enabling WinAlert in the root module
		Include the (supplied in \clarion\libsrc ) map file, EventMap.Clw, in your Global Map.
		Include the (supplied in \clarion\libsrc ) equates file, EventEqu.Clw in your main module's data section.
		Clarion 5: Add the Event532.Lib file to your project for Stand-Alone compile mode or EvLib532.Lib for Local compiles. All these library files are in your \clarion5\3rdparty\lib directory. Clarion 5.5: Add the we55x.Lib file to your project for Stand-Alone compile mode or we55xL.Lib for Local compiles. All these library files are in your \clarion 55\3rdparty\lib directory. Clarion 6: Add the we60x.Lib file to your project for Stand-Alone compile mode or we60xL.Lib for Local compiles. All these library files are in your \clarion 60\3rdparty\lib directory.

Note:  A WinEvent Demo has been included with WinEvent (\Clarion X\3rdParty\examples\WinEvent\Demo\windemo.app) and can be used to view how these features can be used.

Comm's Functions

The Comm's section of the WinEvent package provides some simple easy-to-use functions that allow you to read and write to Comm's ports (RS232).

Using Comm's functions in an Application

Using Comms functions in a hand-coded project
		Include the (supplied in \clarion\libsrc ) map file, EventMap.Clw, in your Global Map.
		Include the (supplied in \clarion\libsrc ) equates file, EventEqu.Clw in your main module's data section.
		Clarion 5: Add the Event532.Lib file to your project for Stand-Alone compile mode or EvLib532.Lib for Local compiles. All these library files are in your \clarion5\3rdparty\lib directory. Clarion 5.5: Add the we55x.Lib file to your project for Stand-Alone compile mode or we55xL.Lib for Local compiles. All these library files are in your \clarion55\3rdparty\lib directory. Clarion 6: Add the we60x.Lib file to your project for Stand-Alone compile mode or we60xL.Lib for Local compiles. All these library files are in your \clarion6\3rdparty\lib directory.

Functions supplied

Newport
ReadPort
WritePort
ResetPort
ClosePort
KillAllPorts
SetHandShake
CtsHigh
DsrHigh
RingHigh
CdHigh
SetRts
SetDtr

For a detailed description of each of the functions, see the reference section. You will need to handcode the functions into your application where you need them. 

Taskbar Functions

There are a number of Taskbar functions which allow your application to interact with the Windows Taskbar. These functions allow you to add icons to the Taskbar's tray, add balloon text, menu option and also allow you to prevent your application (icon) from appearing on the taskbar.

Template Supplied

An Extension template has been provided to add an icon to the tray. This icon will automatically be put in the tray when the window is opened, and automatically removed when the window is closed. You can also use the functions in hand code to add, change and remove icons at will.

If you place an Icon in the tray, then you will also probably want to capture mouse events when the user interacts with this icon. We've included some generic default behaviour, but you may like to add some more options. In WinEvent this is done automatically for you. The template also takes care of all the details - there are embed points so you can add your code for the event, and there are buttons on the AddIcon template to easily get to those embed points.

Tip: Use the Mouse Right Up embed point for opening a Pop-up menu.

• The name of the icon to add is the filename of the icon to add to the systemtray. You can use a ~ to use icons included in the project. 

• The Icon tip is the text for the default tooltip that will appear. You can change this at runtime using the WinTaskBarChangeIcon function

• Note: For use with services, you must use the icon handle to change the icon at runtime. 

• Use the Code to Run when Events are received button to get to the embed points to code in your handcode to run when handling received events. If you used the old embed points (where there was one button for each embed point on the template) - then check the Show Old Event Buttons checkbox and you will be able to edit your previous code through the Old Embeds tab. 

• The Add Show|Hide|Close Menu to right-click Popup option allows the template to build this functionality into the taskbar icon easily. These are pretty standard functions that you will probably require when using the taskbar functionality.

• Checking the Hide Window on Startup option will ensure that your application opens in minimized mode when starting.

• Checking the Not on Toolbar when Minimized will make sure that your window is removed from the taskbar when minimizing (so that it will only appear in the systemtray).

• Checking the Only Close from popup menu will mean that when clicking the X button (the red x on the right side of the titlebar), the application is minimized instead of closing (as well as all other CloseWindow controls). This means that the user must exit through the correct option instead of merely clicking the X. If you would like to allow your user another method of exiting the application (like through a window option) then you can code the following:

WE::CloseAllNow = 1
post(event:closewindow)

• Checking the Left click Icon shows window option will restore the window if the user clicks on the icon in the system tray.

• You can use the Add items to the popup button to add other items to the popup menu. You will need to handcode these calls in as follows:
  WE::MouseRightPopup.AddItem('Process','Process the Records')
  
  You can use menus in the popup as well:
  
  WE::MouseRightPopup.AddItem('Menu','Menu','-',1)
  WE::MouseRightPopup.AddItem('Do it','Do it','Menu',2)

• You can use the Handle new popup items button to add other items to the popup menu. You will need to handcode these calls in as follows (the code needs to appear between the 'Run popup for Show|Hide|Close' and the 'Perform Show|Hide|Close' embed points):
  of 'Process the Records'
    ProcessTheRecords()

Note : The message is ultimately processed by the Accept command. If your program spends a long time processing between calls to the Accept loop then you may notice a delay between clicking on the Icon, and the execution of your embedded code. For better responses make sure your program frequently returns to the Accept command.

Note: If you have hand-coded handling these events then you should be aware that the method has changed and your old code will no longer work. In the past the event came through as WinMessageEvent. This has been changed - the mouse events are now separated and come through as WinMessageEvent+500+x where x is 512 (mouse move) or 513(mouse left down) or 514(mouse left up) or 515(double left click) or 516(mouse right down) or 517(mouse right up).

Functions supplied

WinTaskbarAddIcon
WinTaskbarChangeIcon
WinTaskbarRemoveIcon
WinNotOnTaskbar
ds_WinTaskbarBalloon 

For a detailed description of each of the functions, see the reference section.

Window Behavior Functions

Functions Supplied

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop
ds_ShowWindow
ds_HideWindow
 

For a detailed description of each of the functions, see the reference section. 

Windows System Functions

Functions Supplied

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI

For a detailed description of each of the functions, see the reference section.

 

RAM & Disk Functions

Functions Supplied

GetFreeDiskSpace
GetDiskSpace
ds_GetDiskMegs
ds_Memory  
 

For a detailed description of each of the functions, see the reference section.

 

Time & Date Functions

Functions Supplied

ds_FastClock
ds_FormatFastTime
ds_Timer
ds_Sleep
ds_WeekDay
ds_ReadCPUTimeStamp
 

For a detailed description of each of the functions, see the reference section.
 

File Functions

Functions Supplied

ds_DeleteFile
ds_GetFileDirEntry
ds_SetFileAttributes
ds_CreateDirectory
ds_RemoveDirectory
ds_SetFileDateTime
ds_MoveFile
ds_GetFolderPath
ds_GetTempPath
ds_String2File
ds_File2String
ds_GetHModule
ds_GetHIcon
ds_CreateShortcutEx
ds_GetFileVersionInfo

 

For a detailed description of each of the functions, see the reference section.
 

Process & Thread Functions

Functions Supplied

ds_GetCurrentProcess
ds_GetCurrentThread
ds_GetProcessTime
ds_GetThreadTime
ds_SetRealTimePriority

 

For a detailed description of each of the functions, see the reference section.
 

DLL Functions

Functions Supplied

        ds_LoadDLLProc
        ds_UnloadDLLProc
        ds_GetDLLVersion

For a detailed description of each of the functions, see the reference section.
 

SMS Functions

Getting Started

Functions Supplied

        ds_GSMSendSMS
        ds_GSMEnterPin
        ds_GSMEchoOFF
        ds_GSMSetSMSTextmode
        ds_GetGSMReply
        ds_EmptyPort
        ds_GSMReadSMSInit
        ds_GSMReadSMS
        ds_GSMDeleteSMS
        ds_GSMSetSMSReporting
        ds_GSMSelectSR
        ds_GSMReadSMSReportInit
        ds_GSMReadSMSReport
        ds_GSMDeleteSMSReport
        ds_GSMReadEvents
        ds_GSMSetEvents
        ds_GSMReset
       
       
        For a detailed description of each of the functions, see the reference section.

Getting Started

First, some Important info:

Note: Using a GSM modem is really the only way to send and receive SMSes using WinEvent. Phones themselves vary widely in the ability to handle GSM and every manufacturer's GSM protocol (Commands, etc) are so widely varied, that they will be impossible to support (although you may be lucky - but to avoid the frustration, get a modem).

Note: Only the standard Charset is supported at this stage. We will include the ability to change charsets as soon as possible.

Note: Modems tested with WinEvent: Siemens TC35i, SonyEricson GT47 and Wavecom Wismo (serial only). Please let us know if you have tested with other models of Modems, and we'll add those to this list.

First call NewPort and wait for it to finish before sending an sms - it will look something like the following:

LOC:SMSPortID = NewPort('COM' &clip(left(pComport)) &':' &clip(left(pBaud)) &', ' &clip(left(pParity)) &', ' &clip(left(pPData)) &', ' &clip(left(pStop)))

You need to wait a couple of seconds between sending SMS's. You can use a window timer event for this. Have a look at the ds_GSMSendSMS function for details.

Make sure there is space on the SIM card (although you shouldn't need the space unless you are reading SMS's, but it's a good idea anyway). Take a look at the ds_GSMReadSMS and ds_GSMDeleteSMS functions.

Debugging & Error Reporting Functions

Functions Supplied

        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack
       

For a detailed description of each of the functions, see the reference section.
 

Auto Shut-down Functions

Auto-shutdown gives your application the ability to automatically shutdown when windows performs a restart or shutdown or user logoff while your application is running. This is on by default when you add the WinEvent global extension template to your application.

Note: If you have a Multi-DLL application and require the Auto-shutdown throughout your application, then you need to add the global extension to each application in the Multi-DLL suite. You can override this locally at the template level by checking the 'Disable Auto Shutdown' checkbox - if there are specific windows where you would like to disable the auto-shutdown.

Functions Supplied

        ds_SetOKToEndSessionHandler
        ds_SetEndSessionHandler
        ds_SetNoEndSession         

For a detailed description of each of the functions, see the reference section.  

Some Technical Details

When you select Auto-Shutdown on your Global WinEvent Extension two callback functions MyOKToEndSessionHandler &  MyEndSessionHandler are added to your app.  These appear in your Global Embeds list as :
Winevent MyOKToEndSessionHandler
Winevent MyEndSessionHandler

Use MyOKToEndSessionHandler to tell windows whether it is OK to shut down now.  Set the return value variable OKToEndSession to FALSE if you do not what to allow shutdown now.

If you have given the go ahead to shutdown and no other program has refused then MyEndSessionHandler will be called before windows ends this application.  This is for you to save any settings etc.  Please note that windows ends all your app threads without allowing then to execute the closing window code you may have written.  This is your only chance to execute code. 

If either your MyEndSessionHandler or MyOKToEndSessionHandler code takes longer than 3 seconds to execute then windows (XP 2K etc) pops up a "Ending Application" window which gives you about 15 seconds.

Other Functions

Functions Supplied

        ds_FormatHex
        ds_SetClipboard
        ds_ShutDown
        ds_WineventVersion
        ds_Ulong64ToReal
             

For a detailed description of each of the functions, see the reference section.
 

Reference Guide

WinAlert functions

WinAlert
Winevent
WinControl
WinParam1
WinParam2
WinChangeUserEvent
WinSysEvent
WinSysParam1
WinSysParam2
WinWtsEvent
WinWtsID

 

Comms Functions

NewPort
ResetPort
ClosePort
KillAllPorts
WritePort
ReadPort
SetHandShake
CtsHigh
DsrHigh
RingHigh
CdHigh
SetRts  
SetDtr  

 

Taskbar Functions

WinTaskBarAddIcon
WinTaskBarRemoveIcon
WinTaskBarChangeIcon
WinNotOnTaskBar
ds_WinTaskbarBalloon

Window Behaviour Functions

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop

ds_ShowWindow

ds_HideWindow
 

Windows System Functions

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
GetFreeDiskSpace
GetDiskSpace  
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI

Time & Date Functions

          ds_FastClock
          ds_FormatFastTime
          ds_Timer
          ds_Sleep
          ds_WeekDay

File Functions

        ds_DeleteFile
        ds_GetFileDirEntry
        ds_SetFileAttributes
        ds_CreateDirectory
        ds_RemoveDirectory
        ds_SetFileDateTime
        ds_MoveFile
        ds_GetFolderPath
        ds_GetTempPath
        ds_String2File
        ds_File2String
        ds_GetHModule
        ds_GetHIcon
        ds_CreateShortcut
        ds_GetFileVersionInfo

 

DLL Functions

        ds_LoadDLLProc
        ds_UnloadDLLProc

SMS Functions

        ds_GSMSendSMS
        ds_GSMEnterPin
        ds_GSMEchoOFF
        ds_GSMSetSMSTextmode
        ds_GetGSMReply
        ds_EmptyPort
        ds_GSMReadSMSInit
        ds_GSMReadSMS
        ds_GSMDeleteSMS
        ds_GSMSetSMSReporting
        ds_GSMSelectSR
        ds_GSMReadSMSReportInit
        ds_GSMReadSMSReport
        ds_GSMDeleteSMSReport
        ds_GSMReadEvents
        ds_GSMSetEvents
        ds_GSMReset
       
       
 

Debugging & Error Reporting Functions

        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack
       

WinAlert(<FromMessage>, <ToMessage>, <Action> )

Parameters

Purpose

Complication

Returns

Example

See Also

Winevent(), WinControl(), WinParam1(), WinParam2()

Parameters

Purpose

Complication

Returns

Example

See Also

WinChangeUserEvent (WinMessageEvent)

Parameters

Purpose

Returns

Example

WinSysEvent(byte pClearAfterRead=0), WinSysParam1(), WinSysParam2()

Parameters

Purpose

Returns

Example

WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinWtsEvent : For handling the wm_WTSSESSION_CHANGE windows message.
 

WinWtsEvent(byte pClearAfterRead=0), WinWtsID()

Parameters

Purpose

Returns

Value	Meaning
WTS_CONSOLE_CONNECT 0x1	A session was connected to the console session.
WTS_CONSOLE_DISCONNECT 0x2	A session was disconnected from the console session.
WTS_REMOTE_CONNECT 0x3	A session was connected to the remote session.
WTS_REMOTE_DISCONNECT 0x4	A session was disconnected from the remote session.
WTS_SESSION_LOGON 0x5	A user has logged on to the session.
WTS_SESSION_LOGOFF 0x6	A user has logged off the session.
WTS_SESSION_LOCK 0x7	A session has been locked.
WTS_SESSION_UNLOCK 0x8	A session has been unlocked.
WTS_SESSION_REMOTE_CONTROL 0x9	A session has changed its remote controlled status. To determine the status, call GetSystemMetrics and check the SM_REMOTECONTROL metric.

Example

WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinSysEvent : For handling the wm_SYSCOMMAND windows message.
 

NewPort (string pmode, <long pInb>, <long pOutb>,byte pUseEvents=0)

Purpose

Parameters

mode ( string ) : This is a mode string such as would be accepted by the Dos MODE
command.

in buffer size (long) ( optional parameter - default 512 bytes )
out buffer size (long) ( optional parameter - default 512 bytes )
These are the sizes Windows must use for the In and Out buffers.

pUseEvents (byte) (optional parameter - default = 0)
When set (TRUE) the current window will receive com events.

  Comms transmit buffer empty event = WinEventMessage + 5601

  Comms characters received = WinEventMessage + 5602

  Comms handshaking lines changed = WinEventMessage + 5602

Returns : Long
<0 if an error has occurred. Otherwise a port number used by readport and writeport.

Examples

ResetPort (mode string)

Purpose

Parameters

Returns : long

Example

ClosePort (PortId long)

Purpose

Parameters

Returns : long

Example

KillAllPorts ( )

Purpose

Returns

Example

WritePort (PortId long, String string, Length long)

Purpose

Parameters

Returns : long

Example

Note: Do not use:

if WritePort(pid,buf,10) >= 0
  !Successful write
end

instead of:

bytessent = WritePort(pid,buf,10)
if bytessent
  !Successful write
end

ReadPort (PortId long, String string, Length long)

Purpose

Parameters

Returns : long

Example

Tip: To monitor the port in the background (i.e. without hogging processing time) - you can put the ReadPort in a timer event (Timer set to at least 100 - unless for mission critical timing applications). If the ReadPort returns a 0 then just skip the code for handling the buffer code. In 32bit, windows has an almost unlimited COMPort buffer, so you don't have to worry about comms going missing (if it's not monitored in a tight loop).

SetHandShake (PortId long, HandShake long)

Purpose

Parameters

Returns : long

Example

CtsHigh (Pid Long)

Purpose

Parameters

Returns

Example

DsrHigh (Pid Long)

Purpose

Parameters

Returns

Example

RingHigh (Pid Long)

Purpose

Parameters

Returns

Example

CdHigh (Pid Long)

Purpose

Parameters

Returns

Example

SetRts (Pid Long, Value Long)

Purpose

Parameters

Returns

Example

SetDtr (Pid Long, Value Long)

Purpose

Parameters

Returns

Example

WinTaskbarAddIcon(IconName String,< Tips String>,byte pSetVersion5=0,<string pIconModule>),long

Purpose

Parameters

• IconName (string) - This is the name of the icon to display. The icon is an ICO file stored on the disk (or prefix with a '~' to use an icon in the project).
• Tips (string) - This parameter is optional. If you put a string in here, then this will be the tip displayed when the mouse rests on the icon in the tray.
• pSetVersion5 (byte) -
• pIconModule (string) - this is the name of the module containing the icon (if the icon is in the project). Blank will default to the EXE. This is only required if: 1) this is not an EXE and 2) the IconName is prefixed with a '~' and 3) the icon is not in the EXEs project (but in this or another loaded DLL).

Returns : long

Example

WinTaskbarRemoveIcon(<Id longt>)

Purpose

Parameters

Returns

Example

WinTaskbarChangeIcon(<Id long>, IconName string,<Tips string>,<string pIconModule>)

Purpose

Parameters

• Id (long) - The Icon identifier as returned by the Add function.  If omitted then the first icon added by this window will be changed.
• IconName (string) - The name of the icon to use.
• Tips ( string ) - The new tool tip for the icon.  If omitted then the tip will be cleared.
• pIconModule (string) - this is the name of the module containing the icon (if the icon is in the project). Blank will default to the EXE. This is only required if: 1) this is not an EXE and 2) the IconName is prefixed with a '~' and 3) the icon is not in the EXEs project (but in this or another loaded DLL).
  

Returns

Example

Additional notes:

There are 3 events available for event tracking:

1. Balloon open
2. Balloon close
3. Balloon close on timeout.

To track these events, you can place code in the relative embed point to run when one of these events occurs:

ds_WinTaskbarBalloon(<ulong pID>,string pText,<string pTitle>,uLong pFlags=1,ulong pTimeout=1500)

Purpose

Parameters

pText (string) : The balloon text.  If no balloon text is supplied then any open balloon is closed. Embedding '<13,10>' in the text produces multiline text.

pTitle (string) : Optional.  The balloon title. Icons only appear if the title is supplied.

pFlags (uLong) : Optional.  Default = 1 (An information icon).

WE::NIIF_ERROR EQUATE(003h) An error icon.
WE::NIIF_INFO EQUATE(001h) An information icon. (Default)
WE::NIIF_NONE EQUATE(000h) No icon.
WE::NIIF_WARNING EQUATE(002h) A warning icon.
WE::NIIF_NOSOUND EQUATE(010h) XP/Vista only. Do not play the associated sound.

pTimeout (ulong) : Optional.  Default=1500 (15 seconds). Balloon minimum display time in 100ths of a second. (clarion time)

Returns

Example

WinNotOnTaskbar()

Purpose

To hide the window
    window{prop:iconize} = TRUE
    window{prop:hide} = TRUE

To unhide the window
    window{prop:hide} = FALSE
    window{prop:iconize} = FALSE

Note that the order of the hide / iconize commands is important

Parameters

Returns

Example

WinOnTop()

Purpose

Parameters

Returns

Example 1

Example 2

WinNotOnTop()

Purpose

Parameters

Returns

Example 1

WinBringToFront()

Purpose

Parameters

Returns

Example

ds_ShowWindow(byte pGrabFocus=1)

Purpose

Parameters

pGrabFocus (byte) : Optional.  Defaults to TRUE.  When set you window takes focus and so keyboard input goes to your window.

Returns

Example

ds_HideWindow

Purpose

Parameters

None.

Returns

Example

ds_WinTransparent(long Transparency)

NB: Only available for non-MDI windows.

Purpose

Parameters

Returns

Example

ds_VisibleOnDesktop(<*long pWinX>,<*long pWinY>,<*long pWinWidth>,<*long pWinHeight>,long pMode=1)

Purpose

Parameters

pWinY (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pWinWidth (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pWinHeight (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pMode (long) : Optional.  Default=1  When set this flags that the window must not be obscured by the taskbar.

Returns

Example

ds_GetWinVersion()

Purpose

Parameters

Returns

Win XXX ...............

Note: At least up to Clarion6.3 9056, the Clarion IDE is run in XP compatibility mode on Windows Vista. This means that when running an application from within the IDE, the ds_GetWinVersion will return Win XP, and not Win Vista. The same application run from a normal shortcut will return the correct windows version (i.e. Win Vista).

Example

WindowsVersion()

Purpose

Parameters

Returns

Example

WindowsRelease()

Purpose

Parameters

Returns

Example

DosVersion()

Purpose

Parameters

Returns

Example

DosRelease()

Purpose

Parameters

Returns

Example

GetFreeDiskSpace (<drive long>)

Purpose

Parameters

Returns

Example

GetDiskSpace (<drive long>)

Purpose

Parameters

Returns

Example

ds_GetDiskMegs (<string pDrive>,<string pSelector>)

Purpose

Parameters

pSelector (string) : Optional.  Defaults to 'USER FREE'  This modifies the ret