User Manual for PopHelp Version 1.0 15/7/1995 Contents 0. About PopHelp 1. Operating Environment 2. Examples 3. Define Help 4. Trigger Help 5. Save and Load HIF Files 6. Other Operations(Install, Setup, Modify, Clear) 7. Future Development 8. Known Problems 0. About PopHelp PopHelp is a program to add arbitrary help information into any application under MS Windows, without touching that application's code. PopHelp works independently of the target application, requires no knowledge of programming skills to use, and can easily operate in the background, thus creating an operating environment where every application can have a customized on-line help system. The help information defined can be text, multimedia playback(via MCI drivers), arbitrary program execution, menu popup[1], or WinHelp files[1]. PopHelp can add help to any window, or to any rectangle area within a window. PopHelp allows various triggering mechanism to be defined, including mouse button or key pressing, timers, application status[2], etc. The popup help window's text font, color, window size, position, and styles[2], can all be customized. Registration is A$40, US$30, and will be genuinely appreciated: Guang Yang, PO Box 591, Blacktown, NSW, Australia 2148 Fax/Phone: 61(Country Code) 02(Area Code) 622 2605 Phone: 61(Country Code) 02(Area Code) 622 0061 Mobile: 61(Country Code) 019 903 193 Internet: guang@mailhost.world.net Any suggestions warmly welcome. 1. Operating Environment Any MS-Windows 3.1, 3.11, WFW 3.11, Windows 95 environment. You need these files that come with PopHelp: pophelp.exe filters.dll pophelp.wri (this file in MS Write format):optional pophelp.txt (this file in plain ASCII format):optional hotkeyhk.dll (Copyright 1995 Robert Marshlan) vhkd.386 (Copyright 1995 Robert Marshlan) msvideo.dll (from Microsoft, freely distributable) Optional Help Information Files: msvc1_5.hif for MS Visual C++ 1.5 IDE apptool.hif for MS Visual C++ 1.5 Application Studio pbrush.hif for PaintBrush vb3_0.hif for MS Visual Basic 3.0 Professional Edition The vhkd.386 can be installed into the [386Enh] section of MS Windows' system.ini file as device=[path]\vhkd.386, but PopHelp can run without this VxD, in which case any hot key definition for PopHelp will not work if the input focus is in a DOS box or other non-system VM. PopHelp can be run without parameters, or be followed by a group of PopHelp-Generated *.HIF(Help Information File) file names. If *.HIF file list is supplied, each one must contain its full path(non-existing path/file will be ignored), and the content of them will be interpreted by PopHelp at start-up. Note if any of the command-line *.HIF file indicates HIDE or ICONIZE(see Setup Menu section below), the PopHelp 's main window will be hidden or iconized initially. When PopHelp is run without parameter, if the MS Windows' WIN.INI file has a section like this: [PopHelp] initHIFFiles=[path1]\file1.hif [path2]\file2.hif ... [pathn]\filen.hif, then PopHelp will load all the HIF files assigned to initHIFFiles entry, just like they were put onto the command line. 2. Examples 2.1 Define a Popup Help for Paintbrush's Drawing Width Window 1.When both PaintBrush and PopHelp programs are running, click the Select Target Window tool bar button(the button with an arrow) of the PopHelp program, now various windows moved over by the cursor will have their frames color-inverted and the window's information(handle, module, title, etc) displayed in PopHelp's client area. 2. Move the cursor over the PaintBrush's Drawing Width window(under the drawing tool window) and click the mouse to select it as the target window, a dialog titled "Define Features for Window(0xXXXX)" pops up over PopHelp's main window. 3. In the box titled "Help Content" on the "Define Features for Window(0xXXXX)" dialog, type Drawing Width (or whatever help text), then click the Edit button, a dialog titled "Help Features" appears, click "Window ID Details" button on this dialog, another dialog titled "Window Identification Details" appears. 4. On the "Window Identification Details" dialog, check the check-box "Identified by Window Class", then click OK 5. Click OK on dialog Help Features, then click OK on dialog "Define Features for Window(0xXXXX)". Now move cursor over the drawing width window inside the PaintBrush, a help window containing "Drawing Width "(or whatever help text you typed in Step 3 above) pops up: a Popup Help is defined. 2.2 Define Rectangle Popup Helps for Paintbrush's Drawing Tools Window 1. Same as "1" in 2.1 above 2. Move the cursor over the PaintBrush's Tool Window(at the left end of the client window) and click the mouse to select it as the target window, dialog "Define Features for Window(0xXXXX)" pops up. Click the "Edit" button on this dialog. 3. In the newly appeared dialog "Help Features", check the "To New Rectangle" check-box, then click button Window ID Details. 4. On the newly appeared "Window Identification Details" dialog, check the check-box "Identified by Window Class", then click OK. 5. In the "Help Features" dialog, click button "Rect Details", check all four check-boxes in the newly appeared dialog "Rectangle Details", then click OK of "Rectangle Details" dialog. 6. Back in the "Define Features for Window(0xXXXX)" dialog, type "Scissors Tool: define a free-form cut-out", then move cursor into the "Help Features" dialog, click OK there. 7. Now the PopHelp's client window displays prompt: Click to Select the 1st Point for the New Target Rectangle, click the top-left corner of the left scissor's rectangle, another prompt appears in the PopHelp's client window: Click to Select the 2nd Point for the Target Rectangle. Clicking the bottom-right corner of the left scissors' rectangle in the PainBrush, new prompt appears inside PopHelp: Rectangle (*,*) (*,*) Selected OK. Now whenever you move cursor over the left scissors' rectangle in the Paintbrush program, help dialog "Scissors Tool: define a free-form cut-out" shows up, even if you have resized the PaintBrush's main window(therefore resized the drawing tool window), this pop-up help still appears as the mouse cursor moves into its resized rectangle. 3. Define Help Choosing "Select Window" menu item under File menu, or click the Arrow toolbar button, PopHelp will enter selecting target window mode(Arrow toolbar button disabled, Cross toolbar button enabled), any window under the cursor will have its rectangle outline color- inverted, the PopHelp 's client area will show that window's information like handle, title, module, class, etc. Clicking left mouse button over a target window, selecting target window mode will be cancelled(Arrow button enabled, Cross button disabled), and the Define Features for Window(see below) dialog appears. Choosing "Stop Select" menu item under File menu, or click the Cross toolbar button will also cancel the selecting target window mode. 3.1 Define Features for Window Dialog This dialog allows user to define new or modify existing members of the selected target window database. The Combo box titled "Select Already Defined Windows" lists all existing target windows, and the "Help Content" edit box lists the help information defined for the current target window(the one showing in the Combo box's Edit area). Edit button: brings up Help Heatures dialog Copy button: copy the current target window 's help features to the end of the database Delete button: Delete the current target window from database OK button: Confirm the new or modified target window feature Cancel button: Cancel adding new target window, but cannot cancel already modified help features 3.2 Help Heatures Dialog This dialog defines or changes target window's help features. Window ID Details button: This brings up Window Identification Details dialog. When user moves mouse cursor over any window, PopHelp searches its selected target window database. The conditions defined in the Window Identification Details dialog are used to test if the window under the cursor meet these conditions. If the window does meet all the defined Identification Conditions, its help window will pop up. Please note the Window Class is most likely been used(check box checked) to identify a target window, except in some cases where a target window's class name is not fixed. Background Color, Text Color, Text Font buttons: Brings up dialogs to define the help information text's color and font. Apply to Window, To New Rectangle, To Old Rectangle boxes: Only one of these check boxes will be checked at a time, indicating the help information defined will apply to a window, a new rectangle inside the target window, or an already defined old rectangle. Rectangle Details button: When Apply to New Rectangle or To Old Rectangle is checked, this button brings up the Rectangle Details dialog, which defines if the target rectangle's start position will be scaled along X or Y axis, or the target rectangle's Width or Height will be scaled, when the target rectangle's parent window changes size. Currently the scaling ratio is always according to the ratio recorded at the time the definition is taking place. An example is in the pbrush.hif file, the drawing tool window(of class "pbTool") has defined 18 rectangles, all of them have the four check boxes in Rectangle Details dialog checked, this is why when pbrush.hif is loaded, no matter how you scale the PaintBrush's main window(therefore changing the drawing tool window's size), as the cursor moves over any of the 18 rectangles in its drawing tool window, they will always correctly popup the context sensitive help information. Trigger Details button: This brings up Trigger Details dialog, that defines how the help info. for a target window or for all the target rectangles inside a target window will be triggered, i.e., when the cursor is over the target window or target rectangle, all the trigger conditions (if defined) must be satisfied before the help information window pops up. Multiple trigger conditions can be defined at the same time. Note if a "Key Down" trigger is defined, to make the help info. window pop up by pressing the trigger key(s), the mouse cursor must be moving over the target window/rectangle, and the input focus must be already at the target window. Size/Pos. Details button: This activates the Size/Pos. Details dialog to define the help information window's size and postion, when it is shown. All size and position values are in screen co-ordinates. If the Size Fixed box is checked, the help info window's size will be the Width and Height values defined on that line. If the Size Prop. box is checked, the help info. window's width will be proportional to the target window's width at the ratio defined inside the width edit, the help info. window's heigth will be proportional to the target window's height at the ratio defined inside the height edit. If neither Size Fixed nor Size Prop. is checked, the help info window's size defaults to approximately 104 X 57 pixels. The rest of the controls define help info window's starting position: If the position needs to be variable relative to the target window's position (default to at the target window's X Centre, Y Bottom), the boxes inside the Pos. Variable group can be used, else the Pos. Fixed box can be checked to make the starting position relative to the actual screen's origin (0, 0) position. Content Details button: This pops up the Help Content Details dialog, which defines the content inside the help information window to be text, or MCI file playback(*.avi for video, *.wav for sound, *.bmp for bitmap), or executing another program. When Execute Program is selected, the SW_: Combo box can be used to set visibility flag of the program at start up. The options are the same as in the ShowWindow() SKD call's parameter nCmdShow. Style Details button: This brings up Help Style dialog, which currently allows only Manual Dismiss to be defined. By default, the help infomation window will disappear when the mouse cursor is moved out of the target window or target rectangle. When Manual Dismiss style is on, the help info window will not dismiss itself as the mouse is moving out of the target window: it will disappear only by pressing the Escape or Enter key (when focus is in help info window). Note pressing these keys will not dismiss the help info window if the Manual Dismiss style is off. Delete Old Rect button: When (Apply help info) To Old Rectangle box is checked, pressing this button will delete the current old rectangle as being displayed in the Combo box to the right of the To Old Rectangle check box. OK button and Keep Old Rect box: Normally, when (Apply help info) To New Rectangle or To Old Rectangle box is checked, pressing OK of the Help Features dialog needs to be followed by selecting or re-selecting the target rectangle: clicking the mouse inside the target window twice to indicate the two diagonal points bounding the rectangle. Each clicking is prompted by some messages in the PopHelp main window's client area, and is followed by a simple beep indicating the clicking has successfully recorded that point. When To Old Rectangle box and Keep Old Rect box are both checked, clicking OK will make PopHelp to use the old rectangle's current co-ordinates, therefore no redefiniton for that old rectangle is needed. 4. Trigger Help When the target window database is not empty, moving mouse cursor over any defined target window/target rectangle will cause PopHelp to examine the database members against the window under the cursor. If all triggering conditions are met for any one window/rectangle in the database, the help information window will pop up. Moving mouse out of the target window/rectangle will dismiss the help info window, except when the Manual Dismiss has been set for that target window. 5. Save and Load HIF Files The currently defined target window database can be saved into disk file by selecting Save or Save As... menu item. If the database is empty, the save will generate an HIF file indicating empty database. Loading HIF file causes PopHelp to fill the database with the data from one or more HIF files: Load: Clear current database and load a new HIF file having the name as show on the PopHelp's main window title bar Load From:Clear current database, load one or more HIF file (can do multiple file selection) Load on Top From: Without clearing current database, load one more HIF file on top of the current database content. if the newly loaded file contains target window having same module name and class name as any existing target window, the window from the new file will not be added into database. 6. Other Operations under File Menu(Install, Setup, Modify, Clear) The Install menu selection will pop up the Install PopHelp into Windows dialog: On entry, the HIF Files listbox contains all the files assigned to the initHIFFiles entry of the [PopHelp] section in win.ini file. Add File/Delete File button allows you to add/delete HIF files into/from the listbox. Install button will put the HIF file names in the listbox into the initHIFFiles entry. If the HIF file listbox has no file, the initHIFFiles entry will equal NULL. Setup Menu Item: The Saved HIF Features allows user to define if PopHelp will be ReadOnly, Iconized or Hidden at the next loading of the HIF file. On the otherhand, the Hot Key To Show/Hide PopHelp Window will take effect immediately once you change the hot key and hit OK button. ReadOnly HIF file will not permit changes on that HIF file's content. All the Yes Features and Hot Keys defined in this dialog will overwrite the previously defined same feature/hot key. For example, if hif1.hif defines hot key Ctrl+F2 and hif2.hif defines ReadOnly, Hide and hot key Alt+H, then loading both hif1.hif and hif2.hif will make the PopHelp's database ReadOnly, main window initially hidden, and hot key Alt+H can toggle the main window to show or hide. Modify Menu Item allows user modify any existing target window or rectangle's help features. Once selected, the Define Features for Window dialog will appear. See section 3.1 for details. Clear Menu Item will clear current database. 7. Future Development 7.1 Allow the help content to be invoking WinHelp SKD call with all parameters specified by the user 7.2 Allow the help content to be a user-definable pop-up menu 7.3 Provide function call entries for other applications to dynamically manipulate PopHelp's behaviour at run-time 7.4 Improve the memory management mechanism to allow unlimited text for each target window/rectangle. 7.5 Provide a PopHelp definition language to define arbitrary triggering methods and arbitrary target window identification methods. 7.6 Draw a Windows Tree inside PopHelp's main window to show all live windows in the system, so that target windows can be easily picked up from the tree. 7.7 Port PopHelp to Win32 environment as true 32-bit application. 7.8 Add WinHelp on-line help system for PopHelp. 8. Known Problems 8.1 Target Window Identification is not perfect, and probably can never be, due to lacking a unique and sustainable mechanism under MS Windows to identify an arbitrary window. 8.2 If Two Ajacent Rectangles Overlap, Their Help Info Window Will Show up Alternatively, therefore it is recommended the users make sure no target rectangles in the same target window overlap so that the constant poping up of more than one help info window won't happen. -------------------------------------------------------------------------------------------------------------------- [1]. Not available in version 1.0 [2]. Choices are limited in version 1.0