Windows API Functions - VB Migration

1 1189 AppendixWindows APIF unctionsThe visual Basic language provides a rich set of Functions , commands, and objects,but in many cases they don t meet all the needs of a professional programmer. Justto name a few shortcomings, visual Basic doesn t allow you to retrieve system infor-mation such as the name of the current user and most visual Basic controls ex-pose only a fraction of the features that they potentially programmers have learned to overcome most of these limitations by di-rectly calling one or more Windows API Functions . In this book, I ve resorted to APIfunctions on many occasions, and it s time to give these Functions the attention theydeserve. In contrast to my practice in most other chapters in this book, however,I won t even try to exhaustively describe all you can do with this programming tech-nique, for one simple reason: The Windows operating system exposes several thou-sand Functions , and the number grows almost , I ll give you some ready-to-use routines that perform specific tasks andthat remedy a few of the deficiencies of visual Basic.

2 You won t see much theory inthese pages because there are many other good sources of information available, suchas the Microsoft Developer Network (MSDN), a product that should always have aplace on the desktop of any serious developer, regardless of his or her WORLD OF MESSAGESThe Microsoft Windows operating system is heavily based on messages. For example,when the user closes a window, the operating system sends the window a WM_CLOSE message. When the user types a key, the window that has the focus receives aWM_CHAR message, and so on. (In this context, the term window refers to both top-level Windows and child controls.) Messages can also be sent to a window or a con-trol to affect its appearance or behavior or to retrieve the information it contains. Forexample, you can send the WM_SETTEXT message to most Windows and controlsto assign a string to their contents, and you can send the WM_GETTEXT message toread their current contents.

3 By means of these messages, you can set or read thecaption of a top-level window or set or read the Text property of a TextBox control,just to name a few common uses for this speaking, messages belong to one of two families: They re control mes-sages or notification messages. Control messages are sent by an application to a win-dow or a control to set or retrieve its contents, or to modify its behavior or messages are sent by the operating system to Windows or controls as theresult of the actions users perform on Basic greatly simplifies the programming of Windows applications becauseit automatically translates most of these messages into properties, methods, and of using WM_SETTEXT and WM_GETTEXT messages, visual Basic program-mers can reason in terms of Caption and Text properties. Nor do they have to worryabout trapping WM_CLOSE messages sent to a form because the visual Basic runtimeautomatically translates them into Form_Unload events.

4 More generally, control mes-sages map to properties and methods, whereas notification messages map to all messages are processed in this way, though. For example, the TextBoxcontrol has built-in undo capabilities, but they aren t exposed as properties or methodsby visual Basic, and therefore they can t be accessed by pure visual Basic code.(In this appendix, pure visual Basic means code that doesn t rely on external API func-tions.) Here s another example: When the user moves a form, Windows sends theform a WM_MOVE message, but the visual Basic runtime traps that message with-out raising an event. If your application needs to know when one of its windowsmoves, you re out of using API Functions , you can work around these limitations. In this section,I ll show you how you can send a control message to a window or a control to af-fect its appearance or behavior, while in the Callback and Subclassing section, I llillustrate a more complex programming technique, called window subclassing, whichlets you intercept the notification messages that visual Basic doesn t translate to API Functions1191 Before you can use an API function, you must tell visual Basic the name of theDLL that contains it and the type of each argument.

5 You do this with a Declare state-ment, which must appear in the declaration section of a module. Declare statementsmust be declared as Private in all types of modules except BAS modules (which alsoaccept Public Declare statements that are visible from the entire application). Foradditional information about the Declare statement, see the language main API function that you can use to send a message to a form or a controlis SendMessage, whose Declare statement is this:Private Declare Function SendMessage Lib user32 Alias SendMessageA _ (ByVal hWnd As Long, ByVal wMsg As Long, _ ByVal wParam As Long, lParam As Any) As LongThe hWnd argument is the handle of the window to which you re sending themessage (it corresponds to the window s hWnd property), wMsg is the messagenumber (usually expressed as a symbolic constant), and the meaning of the wParamand lParam values depend on the particular message you re sending.

6 Notice thatlParam is declared with the As Any clause so that you can pass virtually anything tothis argument, including any simple data type or a UDT. To reduce the risk of acci-dentally sending invalid data, I ve prepared a version of the SendMessage function,which accepts a Long number by value, and another version that expects a Stringpassed by value. These are the so called type-safe Declare statements:Private Declare Function SendMessageByVal Lib user32 _ Alias SendMessageA (ByVal hWnd As Long, ByVal wMsg As Long, _ ByVal wParam As Long, Byval lParam As Long) As LongPrivate Declare Function SendMessageString Lib user32 _ Alias SendMessageA ByVal hWnd As Long, ByVal wMsg As Long, _ ByVal wParam As Long, ByVal lParam As String) As LongApart from such type-safe variants, the Declare Functions used in this chapter,as well as the values of message symbolic constants, can be obtained by running theAPI Viewer utility that comes with visual Basic.

7 (See Figure A-1 on the following page.)CAUTIONWhen working with API Functions , you re in direct touch with theoperating system and aren t using the safety net that visual Basic offers. If youmake an error in the declaration or execution of an API function, you re likely toget a General Protection Fault (GPF) or another fatal error that will immediatelyshut down the visual Basic environment. For this reason, you should carefullydouble-check the Declare statements and the arguments you pass to an APIfunction, and you should always save your code before running the API Viewer utility has been improved in visual Basic 6 with thecapability to set the scope of Const and Type directives and Declare TextBox ControlsThe SendMessage API function is very useful with multiline TextBox controls becauseonly a small fraction of their features is exposed through standard properties andmethods.

8 For example, you can determine the number of lines in a multiline TextBoxcontrol by sending it an EM_GETLINECOUNT message:LineCount = SendMessageByVal( , EM_GETLINECOUNT, 0, 0)or you can use the EM_GETFIRSTVISIBLELINE message to determine which line isthe first visible line. (Line numbers are zero-based.)FirstVisibleLine = SendMessageByVal( , EM_GETFIRSTVISIBLELINE, 0, 0)NOTEAll the examples shown in this appendix are available on the compan-ion CD. To make the code more easily reusable, I ve encapsulated all the ex-amples in Function and Sub routines and stored them in BAS modules. Eachmodule contains the declaration of the API Functions used, as well as the Constdirectives that define all the necessary symbolic constants. On the CD, you ll alsofind demonstration programs that show all the routines in action. (See Figure A-2.)The EM_LINESCROLL message enables you to programmatically scroll the con-tents of a TextBox control in four directions.

9 You must pass the number of columnsto scroll horizontally in wParam (positive values scroll right, negative values scrollleft) and the number of lines to scroll vertically in lParam (positive values scroll down,negative values scroll up). Scroll one line down and (approximately) 4 characters to the , EM_LINESCROLL, 4, 1 AppendixWindows API Functions1193 Figure program that demonstrates how to use the routines in the that the number of columns used for horizontal scrolling might notcorrespond to the actual number of characters scrolled if the TextBox control uses anonfixed font. Moreover, horizontal scrolling doesn t work if the ScrollBars propertyis set to 2-Vertical. You can scroll the control s contents to ensure that the caret is visibleusing the EM_SCROLLCARET:SendMessageByVal , EM_SCROLLCARET, 0, 0 One of the most annoying limitations of the standard TextBox control is thatthere s no way to find out how longer lines of text are split into multiple lines.

10 Us-ing the EM_FMTLINES message, you can ask the control to include the so-called softline breaks in the string returned by its Text property. A soft line break is the pointwhere the control splits a line because it s too long for the control s width. A soft linebreak is represented by the sequence CR-CR-LF. Hard line breaks, points at whichthe user has pressed the Enter key, are represented by the CR-LF sequence. Whensending the EM_FMTLINES message, you must pass True in wParam to activate softline breaks and False to disable them. I ve prepared a routine that uses this featureto fill a String array with all the lines of text, as they appear in the control: Return an array with all the lines in the control. If the second optional argument is True, trailing CR-LFs are GetAllLines(tb As TextBox, Optional KeepHardLineBreaks _ As Boolean) As String() Dim result() As String, i As Long Activate soft line breaks.