home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / pcmag / vol12n13.zip / FIND.ZIP / FIND.DOC < prev    next >
Text File  |  1993-06-15  |  19KB  |  369 lines
  1. FIND.DLL (VERSION 1.0)                  Copyright (c) 1993 Douglas Boling
  2. -------------------------------------------------------------------------
  3.                      First Published in PC Magazine July 1993 (Utilities)
  4. -------------------------------------------------------------------------
  5.  
  6. FIND.DLL:  A Text-Search Utility for Windows 3.1
  7.            BY DOUGLAS BOLING
  8.  
  9.            FIND is a Windows 3.1 utility that lets you scan through a
  10. single file, a set of files, or an entire partition and find all
  11. occurrences of a given string. FIND can search in the background, so
  12. you can continue to work on other tasks and instead of being a
  13. standalone program, it seamlessly integrates itself into the Windows
  14. File Manager. In this way, the services provided by FIND supplement the
  15. already-powerful File Manager.  Once installed, FIND becomes simply an
  16. additional item on the File Manager menu.
  17.  
  18. USING FIND
  19.  
  20.     To install FIND, copy the FIND.DLL file into a directory on your
  21. hard disk. You should then edit the File Manager's WINFILE.INI file,
  22. adding the following line to its [AddOns] section:
  23.  
  24. Text Search Extension=d:\path\FIND.DLL
  25.  
  26. For example, because I put FIND in my \WINDOWS\UT directory on
  27. my D: drive, I entered
  28.  
  29.                       Text Search Extension=D:\WINDOWS\UT\FIND.DLL
  30.  
  31.     Note that if your WINFILE.INI doesn't already have an [AddOns]
  32. section, you must add it, on a line by itself. If the whole idea of
  33. editing .INI files is new to you, see the sidebar (below)
  34. `How to Install FIND.DLL''
  35.  
  36.     Once FIND is installed, start the File Manager.  You will see that
  37. an extra menu item--Find--has been added on the main menu line.  For a
  38. quick test, select a file in the File Manager window, click on the
  39. FindText menu item, type in the text to be found, and either press
  40. Enter or click the Find button.  FIND will then display a list of all
  41. occurrences of that text string in the file you selected.
  42.  
  43.     Since FIND is an extension of the File Manager, you can use the File
  44. Manager to select the files you want examined.  To select a file or
  45. directory, simply click on it.  If you hold down the Ctrl key while
  46. making a selection the new file or directory will be added to the
  47. currently selected list.  Holding down the Shift key selects all files
  48. between the current selection and the new selection.  Note, however,
  49. that multiple selections can be made only from the file list side of
  50. the directory window.
  51.  
  52.     Using the mouse or Alt-N to select the Find menu item on the File
  53. Manager's main menu reveals the three-item FIND menu.  Its first item,
  54. Text, brings up FIND's Text Search dialog box. The text to be found is
  55. entered in the edit box in the top-left corner.  To its right is a
  56. combo box that contains a list of the files you selected to search in
  57. the File Manager window.  If you change your mind you can enter a new
  58. file specification directly in the combo box.  This will remove any
  59. previous selections.
  60.  
  61.     The first check box at the bottom of the dialog box lets you tell
  62. FIND to ignore the case of the text during the search.  An X in the
  63. second check box tells FIND to search through files contained in any
  64. subdirectories below the current directory.  If you set the directory
  65. selection to the root directory and then check the Search Subdirectories
  66. box, FIND will look for matching text in every file on the disk.
  67.  
  68.     Pressing the Attributes button displays a dialog box that lets you
  69. restrict the type of files to be searched.  By default, FIND looks at
  70. all files that match the filename specification.  By using the
  71. Attributes dialog, however, you can limit the search to files that
  72. have the desired file attributes.  There's usually no point in having
  73. FIND waste its time going through the hidden files or system files.
  74.  
  75.     Hitting Enter or clicking the Find button starts the search.  FIND
  76. will display the name of the file it is currently examining in the title
  77. bar of the dialog box.  This allows you to monitor the progress of the
  78. search.  When FIND finds the matching text, that line from the file is
  79. displayed in the list box, together with the filename and the line
  80. number within the file.  If the file is not a pure ASCII text file,
  81. FIND displays the offset into the file rather than the line number of
  82. the matched text.
  83.  
  84.     When you start a search, the Find button changes to read ``Stop.''
  85. Pressing the Stop button immediately aborts the search.  When a search
  86. is stopped or has been completed, the button changes back to Find.
  87. Since FIND performs its search in the background, you can continue to
  88. work with programs other than the File Manager while the search is
  89. taking place.  The only limitation here is that you cannot switch to
  90. a full-screen DOS box that has the Exclusive tasking option set.
  91. If you do, FIND (along with all your other Windows programs) will be
  92. suspended until you switch back to the desktop.  The only remaining
  93. button on the dialog box is the Cancel button.
  94.  
  95.     The other two items on the main FIND menu are Files and About Find.
  96. Selecting the Files menu displays the same dialog you could access from
  97. the File Manager's FileSearch menu.  I simply reduplicated it here to
  98. let you use it as part of FIND's search operations.  The final menu
  99. selection, About Find, contains the usual author and copyright
  100. information.
  101.  
  102. FILE MANAGER EXTENSIONS
  103.  
  104.     The Windows 3.1 File Manager is much improved over its Windows 3.0
  105. predecessor.  Along with performance enhancements,  Microsoft provided
  106. a documented method for adding new functions to the File Manager.
  107. The interface is described in the documentation that accompanies the
  108. Microsoft Windows Software Development Kit (SDK), Borland's C++ 3.1
  109. compiler, and other Windows 3.1 development environments.  Fortunately,
  110. the interface is relatively straightforward--for a Microsoft-defined
  111. interface.  Before discussing how FIND works in detail, it's good to
  112. begin with File Manager extensions in general.
  113.  
  114.     A File Manager extension must be implemented as a dynamic link
  115. library (DLL) that contains an external entry point with the name
  116. FMExtensionProc.  When the File Manager is launched, it looks in the
  117. [AddOns] section of its WINFILE.INI file for the names of any extension
  118. DLLs.  The File Manager reads the names listed there and loads each DLL
  119. into memory.  If a listed DLL cannot be found, the File Manager does
  120. not display an error; it just proceeds to the next extension in the
  121. list.  This allows an extension to be removed simply by deleting the
  122. DLL, although it is good practice to delete the [AddOns] entry as well.
  123.  
  124.     Communication between the File Manager and an extension DLL is
  125. performed through messages.  When the File Manager wants to send a
  126. message to an extension, it does not send the message to the
  127. extension's window; instead, it calls FMExtensionProc.  When the
  128. extension wants to send a message to the File Manager, it uses the
  129. standard Windows SendMessage() function to send a message back to the
  130. File Manager window.  The File Manager will respond correctly only to
  131. messages sent from the FMExtensionProc function.  Unfortunately, this
  132. means that programs other than extensions cannot use these messages
  133. to query the File Manager for information.
  134.  
  135.     The File Manager calls FMExtensionProc with three parameters:  the
  136. handle of the File Manager window, a number indicating the message type,
  137. and an lParam parameter that contains message-specific information.
  138. Figure 1 (below) lists the messages used to communicate between the File
  139. Manager and the extension.  The File Manager also calls the
  140. FMExtensionProc when the user selects any of the extension's menu items.
  141.  
  142.     When the File Manager loads an extension DLL, it sends an
  143. FMEVENT_ LOAD message to the extension.  The lParam parameter contains
  144. a pointer to an FMS_LOAD structure.  Figure 2 (below) contains the
  145. C-style definition for FMS_LOAD and for the other structures used in
  146. the File Manager extension interface.  When the extension is called,
  147. the only field that is filled in by the File Manager is the wMenuDelta
  148. field, which I'll discuss shortly.
  149.  
  150.     Before returning from the FMEVENT_LOAD call, the extension must fill
  151. in the dwSize, szMenuName and hMenu fields in the FMS_LOAD structure.
  152. The first field, dwSize, is a (rather optimistically large) double-word
  153. parameter that contains the size of the structure.  The szMenuName
  154. parameter is the menu name that the File Manager will use to label the
  155. extension's menu on the File Manager's main menu.  In keeping with
  156. Windows standards, this string may contain an ampersand (&) character
  157. preceding the character to be underlined in the menu item.
  158.  
  159.     The hMenu field is filled with the handle of the extension submenu
  160. to be displayed when the user selects the extension's main menu item.
  161. Normally, the extension uses a LoadMenu call to load this menu from its
  162. resource information.  The items in an extension's menu must have IDs in
  163. the range of 1 to 99.  When the user selects one of the extension's menu
  164. items, the File Manager calls FMExtensionProc with a message number set
  165. to the ID value of the menu item.  Thus, a File Manager extension
  166. processes its menu selections in FMExtensionProc, not--as in a typical
  167. Windows program--in a WM_COMMAND message.
  168.  
  169.     The documentation for the FM_EVENTLOAD message mistakenly indicates
  170. that the extension should not return a value for this message.  The
  171. extension must return the hMenu value or the extension will not be
  172. loaded.  Fortunately, this documentation error is not duplicated in
  173. the example shown in the File Manager extension overview.
  174. FMEVENT_INITMENU message is sent to the extension when the user selects
  175. the extension's main menu item on the File Manager menu.  The message
  176. is sent before the extension menu is displayed, and it allows the
  177. extension to perform any menu initialization processing needed.  Such
  178. menu initializations might include disabling or checking menu items.
  179. If the extension's menu contains submenus, these must also be initialized
  180. at this time, as no other notifications are sent when the submenus are
  181. displayed.  The lParam parameter contains the extension's menu handle
  182. in the high word and the wMenuDelta parameter in the low word.
  183.  
  184.     The wMenuDelta parameter is a number that the extension must use
  185. when manipulating its own menu items.  When the File Manager loads
  186. an extension, it selects a wMenuDelta value that is higher than all its
  187. other menu IDs.  It then adds this wMenuDelta value to the extension's
  188. menu IDs so that they will be unique.  When the user selects one of
  189. these items, the File Manager sends its original menu ID from 1 through
  190. 99 to the extension, but if an extension needs to modify a menu directly,
  191. it must use the wMenuDelta value to compute the real menu ID.  Thus, for
  192. example, FIND has three menu items, Text, Files, and About, which have
  193. ID numbers 1, 2, and 3.  To disable the Files menu item, the extension
  194. would use
  195.  
  196. EnableMenuItem (hMenu, 2 + wMenuDelta, MF_BYCOMMAND | MF_GRAYED);
  197.  
  198.  
  199. The hMenu parameter in this example is the handle to the extension menu.
  200.  
  201.     The FMEVENT_SELCHANGE message is sent to the extension when the user
  202. changes the selections in the File Manager window.  This message allows
  203. the extension to update its display with the new selections.  The
  204. lParam parameter is not used in this message.
  205.  
  206.     The FMEVENT_USER_REFRESH message is sent when the user selects the
  207. File Manager's WindowRefresh menu item.  This message indicates that
  208. the extension should update its menus and windows to reflect the
  209. current situation.  As with the FMEVENT_SELCHANGE message, the lParam
  210. parameter is not used.
  211.  
  212.     Finally, the FMEVENT_UNLOAD message is sent to the extension when
  213. the File Manager unloads the extension DLL.  This message allows the
  214. extension to perform any cleanup needed before being removed from
  215. memory.  Again, the lParam parameter is not used.  While the extension
  216. can use this message for cleanup, the DLL's WEP (Windows exit procedure)
  217. routine will also be called by Windows' KERNEL module just before the
  218. DLL is unloaded from memory.
  219.  
  220.     During any of the FMEVENT messages, the extension can send a number
  221. of messages to the File Manager to query its current state.  The
  222. FM_GETDRIVEINFO message is used to return information about the
  223. currently selected disk drive.  This message is sent with SendMessage's
  224. lParam parameter pointing to an FMS_GETDRIVEINFO structure; the wParam
  225. parameter is not used.  FMS_GETDRIVEINFO contains such information as
  226. the drive's total space, free space, current path, volume name and
  227. share name.
  228.  
  229.     The FM_GETFILESELCOUNT message can be used to query the number of
  230. items selected in the File Manager's directory and search windows.
  231. The File Manager returns the number of selected files and directories
  232. in the return value of SendMessage.  Neither the wParam nor the lParam
  233. parameters of SendMessage are used for this message.
  234.  
  235.     Once an extension knows how many files have been selected, it can
  236. send an  FM_GETFILESEL message to retrieve each of their names.  For
  237. this message, wParam contains the index of the file in which the
  238. extension is interested, and lParam points to an FMS_GETFILESEL
  239. structure.  When the message returns, the structure is filled with
  240. information about the file, including its name, size, attributes, and
  241. the date and time the file was created.
  242.  
  243.     FM_GETSELCOUNTFN and FM_GETFILESELFN are similar to the
  244. FM_GETSELCOUNT and FM_GETFILESEL messages except that they also return
  245. information on selected files whose filenames are longer than the
  246. standard 8.3 DOS format.  Although DOS does not itself recognize these
  247. long filenames, this support is provided for File Manager extensions
  248. that may operate on network files with nonstandard filenames.
  249.  
  250.     Depending on the type of window that currently has the focus in
  251. the File Manager, the FM_GETFOCUS message returns one of four values.
  252. The four window types are the directory portion of the directory window,
  253. the tree portion of the directory window, the drive selection bar, and
  254. the search results window.
  255.  
  256.     The last two File Manager messages, FM_REFRESH_WINDOWS and
  257. FM_RELOAD_EXTENSIONS, give the extension a little bit of control over
  258. what is presented in the File Manager windows.  The FM_REFRESH_WINDOWS
  259. message can be sent to instruct the File Manager when you want to update
  260. its windows.  This comes in handy if an extension creates, deletes, or
  261. moves files and wants the File Manager to display the state of the disk
  262. accurately.  If the wParam parameter is zero, the File Manager updates
  263. the active window; otherwise all File Manager windows are updated.
  264.  
  265.     The FM_RELOAD_EXTENSIONS message instructs the File Manager to unload
  266. and then reload all of its extensions.  The File Manager rereads its
  267. WINFILE.INI file to see what extensions need to be reloaded.  This
  268. message is convenient when an extension wants to unload itself.  It can
  269. remove its entry from WINFILE.INI and then send the FM_RELOAD_EXTENSIONS
  270. message to force the File Manager to reload all the other extensions.
  271. ---------------------------------------------------------------------------
  272. DOUGLAS BOLING IS A CONTRIBUTING EDITOR TO PC MAGAZINE. HE CAN BE REACHED
  273. ON PC MAGNET (72241,217) IN THE UTILITIES/TIPS FORUM (GO ZNT:TIPS), THE
  274. TECHNICAL SUPPORT AREA FOR PC MAGAZINE UTILITIES.
  275. ---------------------------------------------------------------------------
  276.                         How to Install FIND.DLL
  277.  
  278. In order to install the FIND utility, simply follow these step-by-step
  279. instructions:
  280.  
  281.     1. Copy the file FIND.DLL into your Windows (or another convenient)
  282.        directory.
  283.     2. Start Notepad by double-clicking on the Notepad icon in the
  284.        Accessories group.
  285.     3. Open the File Manager's .INI file by selecting the FileOpen menu
  286.        selection in Notepad and entering WINFILE.INI.
  287.     4. Find the [AddOns] section in the file. If there is no [AddOns]
  288.        section, go to the end of the file and enter [AddOns] on a line
  289.        of its own.
  290.     5. Just under that line, add the line
  291.  
  292.  
  293.                              Text Search Extension=FIND.DLL
  294.  
  295.  
  296.         If you didn't place FIND.DLL in your Windows directory, include
  297.         the path to the DLL in the filename.
  298.     6. Save the file by selecting the FileSave menu item.
  299.     7. Close Notepad by selecting the FileExit menu item.
  300. ===========================================================================
  301.                   File Manager Messages
  302.  
  303. Messages from the File Manager to the extension
  304.  
  305.  
  306. Messages 1 to 99Sent when the user selects one of the extension's menu items.
  307. FMEVENT_LOADSent when the File Manager loads the extension.
  308.  
  309. FMEVENT_INITMENUSent when the user selects the extension's main menu selection.
  310.  
  311. FMEVENT_SELCHANGESent when the user changes the selection in the File Manager's directory or search window.
  312.  
  313. FMEVENT_USER_REFRESHSent when the user clicks on the File Manager's Refresh Windows button.
  314.  
  315. FMEVENT_UNLOADSent when the File Manager unloads the extension.
  316.  
  317.  
  318.  
  319.  
  320. Message from the extension to the File Manager
  321.  
  322.  
  323. FM_GETDRIVEINFOReturns information about the currently selected disk drive.
  324.  
  325. FM_GETSELCOUNTReturns the number of selections in the File Manager window.
  326.  
  327. FM_GETFILESELReturns directory entry information for a selected file.
  328.  
  329. FM_GETSELCOUNTFNSame as FM_GETSELCOUNT except that the count includes any selections with long filenames.
  330.  
  331. FM_GETFILESELFNSame as FM_GETFILESEL except that the filename returned may be longer than the standard 8.3 file-naming convention allows.
  332.  
  333. FM_GETFOCUSReturns the type of the File Manager window with the active focus.
  334.  
  335. FM_REFRESH_WINDOWSTells the File Manager to refresh its windows.
  336.  
  337. FM_RELOAD_EXTENSIONSTells the File Manager to unload then reload all its extensions.
  338.  
  339. Figure 1:  These messages are used to communicate between the File Manager and a File Manager extension.
  340. ==============================================================================
  341.           Structures Used in the File Manager Extension Interface
  342.  
  343. typedef struct FMS_LOAD
  344.     DWORD dwSize;
  345.     char  szMenuName[MENU_TEXT_LEN];
  346.     HMENU hMenu;
  347.     UINT  wMenuDelta;
  348.  FMS_LOAD;
  349.  
  350. typedef struct FMS_GETDRIVEINFO 
  351.     DWORD dwTotalSpace;
  352.     DWORD dwFreeSpace;
  353.     char  szPath[260];
  354.     char  szVolume[14];
  355.     char  szShare[128];
  356.  FMS_GETDRIVEINFO, FAR *LPFMS_GETDRIVEINFO;
  357.  
  358. typedef struct FMS_GETFILESEL
  359.     UINT  wTime;
  360.     UINT  wDate;
  361.     DWORD dwSize;
  362.     BYTE  bAttr;
  363.     char  szName[260];
  364.  FMS_GETFILESEL;
  365.  
  366. Figure 2:  The C-style definitions for FMS_LOAD, FMS_GETDRIVEINFO, and
  367. FMS_GETFILESEL, which are used in the File Manager extension interface.
  368. =======================================================================
  369.