home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 24 / CD_ASCQ_24_0995.iso / win / prg / phelp1_0 / pophelp.txt < prev    next >
Text File  |  1995-07-29  |  19KB  |  365 lines
  1.                                      
  2.  
  3.         User Manual for PopHelp Version 1.0
  4.                     15/7/1995
  5.  
  6.                                 Contents
  7. 0.  About PopHelp
  8. 1.  Operating Environment
  9. 2.  Examples
  10. 3.  Define Help
  11. 4.  Trigger Help
  12. 5.  Save and Load HIF Files
  13. 6.  Other Operations(Install, Setup, Modify, Clear)
  14. 7.  Future Development
  15. 8.  Known Problems
  16.  
  17. 0.  About PopHelp
  18.  
  19.     PopHelp is a program to add arbitrary help information into any application under 
  20.     MS Windows, without touching that application's code.
  21.  
  22.     PopHelp works independently of the target application, requires no knowledge of 
  23.     programming skills to use, and can easily operate in the background, thus creating an 
  24.     operating environment where every application can have a customized on-line help system.
  25.  
  26.     The help information defined can be text, multimedia playback(via MCI drivers), arbitrary 
  27.     program execution, menu popup[1], or WinHelp files[1].
  28.  
  29.     PopHelp can add help to any window, or to any rectangle area within a window.
  30.  
  31.     PopHelp allows various triggering mechanism to be defined, including mouse button or key 
  32.     pressing, timers, application status[2], etc.
  33.  
  34.     The popup help window's text font, color, window size, position, and styles[2], 
  35.     can all be customized.
  36.  
  37.     Registration is A$40, US$30, and will be genuinely appreciated:
  38.  
  39.     Guang Yang, PO Box  591, Blacktown, NSW, Australia 2148
  40.     Fax/Phone:  61(Country Code) 02(Area Code) 622 2605
  41.     Phone:    61(Country Code) 02(Area Code) 622 0061
  42.     Mobile: 61(Country Code) 019 903 193
  43.     Internet: guang@mailhost.world.net
  44.  
  45.     Any suggestions warmly welcome.
  46.  
  47. 1.  Operating Environment
  48.     Any MS-Windows 3.1, 3.11, WFW 3.11, Windows 95 environment. 
  49.     You need these files that come with PopHelp:
  50.         pophelp.exe
  51.         filters.dll
  52.         pophelp.wri (this file in MS Write format):optional
  53.         pophelp.txt (this file in plain ASCII format):optional
  54.         hotkeyhk.dll  (Copyright 1995 Robert Marshlan)
  55.         vhkd.386  (Copyright 1995 Robert Marshlan)
  56.         msvideo.dll (from Microsoft, freely distributable)
  57.  
  58.         Optional Help Information  Files:
  59.         msvc1_5.hif for MS Visual C++ 1.5 IDE
  60.         apptool.hif for MS Visual C++ 1.5 Application Studio 
  61.         pbrush.hif  for PaintBrush
  62.         vb3_0.hif for MS Visual Basic 3.0 Professional Edition
  63.  
  64.     The vhkd.386 can be installed into the [386Enh] section of MS 
  65.     Windows' system.ini file as device=[path]\vhkd.386, but PopHelp can     
  66.     run without this VxD, in which case any hot key definition for PopHelp 
  67.     will not work if the input focus is in a DOS box or other non-system VM.
  68.     
  69.     PopHelp can be run without parameters, or be followed by a group
  70.     of PopHelp-Generated *.HIF(Help Information File) file names. If *.HIF
  71.     file list is supplied, each one must contain its full path(non-existing 
  72.     path/file will be ignored), and the content of them will be interpreted
  73.     by PopHelp at start-up. Note if any of the command-line *.HIF file
  74.     indicates HIDE or ICONIZE(see Setup Menu section below), the 
  75.     PopHelp 's main window will be hidden or iconized initially.
  76.  
  77.     When PopHelp is run without parameter, if the MS Windows' WIN.INI
  78.     file has a section like this:
  79.         [PopHelp]
  80.         initHIFFiles=[path1]\file1.hif  [path2]\file2.hif ...  [pathn]\filen.hif,
  81.     then PopHelp will load all the HIF files assigned to initHIFFiles entry,
  82.     just like they were put onto the command line.  
  83. 2.  Examples
  84.     2.1 Define a Popup Help for Paintbrush's Drawing Width Window
  85.         1.When both PaintBrush and PopHelp programs are running,  click
  86.              the Select Target Window tool bar button(the button with an arrow)
  87.              of the PopHelp program, now various windows moved over by the
  88.              cursor will have their frames color-inverted and the window's
  89.              information(handle, module, title, etc) displayed in PopHelp's client area.
  90.         2. Move the cursor over the PaintBrush's Drawing Width window(under the
  91.                 drawing tool window) and click the mouse to select it as the target window,
  92.                 a dialog titled "Define Features for Window(0xXXXX)" pops up over
  93.                 PopHelp's main window.
  94.         3. In the box titled "Help Content" on the "Define Features for 
  95.                 Window(0xXXXX)" dialog, type Drawing Width (or whatever help text),
  96.                 then click the Edit button,  a dialog titled "Help Features" appears, click
  97.                 "Window ID Details" button on this dialog, another dialog titled
  98.                 "Window Identification Details" appears.
  99.         4. On the "Window Identification Details" dialog, check the check-box               "Identified by Window Class", then click OK
  100.         5. Click OK on dialog Help Features, then click  OK on dialog
  101.                 "Define Features for Window(0xXXXX)".
  102.                 Now move cursor over the drawing width window inside the PaintBrush, 
  103.                 a help window containing "Drawing Width "(or whatever help text you 
  104.                 typed in Step 3 above) pops up: a Popup Help is defined.
  105.  
  106.     2.2 Define Rectangle Popup Helps for Paintbrush's Drawing Tools Window
  107.         1. Same as "1" in 2.1 above
  108.         2. Move the cursor over the PaintBrush's Tool Window(at the left end of the
  109.                 client window) and click the mouse to select it as the target window,
  110.                 dialog "Define Features for Window(0xXXXX)" pops up.                    Click the "Edit" button on this dialog.
  111.         3. In the newly appeared dialog "Help Features", check the 
  112.                 "To New Rectangle" check-box, then click button Window ID Details.
  113.         4. On the newly appeared "Window Identification Details" dialog, check the  
  114.                 check-box "Identified by Window Class", then click OK.
  115.         5. In the "Help Features" dialog, click button "Rect Details", check all
  116.                 four check-boxes in the newly appeared dialog "Rectangle Details", then
  117.                 click OK of "Rectangle Details" dialog.
  118.         6. Back in the "Define Features for Window(0xXXXX)" dialog, type 
  119.                 "Scissors Tool: define a free-form cut-out", then move cursor into the
  120.                 "Help Features" dialog, click OK there.
  121.         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
  122.                 scissor's rectangle, another prompt appears in the PopHelp's client window:
  123.                 Click to Select the 2nd Point for the Target Rectangle. Clicking the
  124.                 bottom-right corner of the left scissors' rectangle in the PainBrush, new prompt
  125.                 appears inside PopHelp: Rectangle (*,*) (*,*) Selected OK.
  126.                 Now whenever you move cursor over the left scissors' rectangle in the Paintbrush
  127.                 program, help dialog "Scissors Tool: define a free-form cut-out" shows up,
  128.                 even if you have resized the PaintBrush's main window(therefore resized the
  129.                 drawing tool window), this pop-up help still appears as the mouse cursor moves
  130.                 into its resized rectangle.
  131.                 
  132. 3.  Define Help
  133.     Choosing "Select Window" menu item under File menu, or click the
  134.     Arrow toolbar button, PopHelp will enter selecting target window  
  135.     mode(Arrow toolbar button disabled, Cross toolbar button enabled),    
  136.     any window under the cursor will have its rectangle outline color-  
  137.     inverted, the PopHelp 's client area will show that window's information  
  138.     like handle, title, module, class, etc. Clicking left mouse button over a     
  139.     target window, selecting target window  mode will be cancelled(Arrow
  140.     button enabled, Cross button disabled), and the Define Features for
  141.     Window(see below) dialog appears.
  142.     
  143.     Choosing "Stop Select" menu item under File menu, or click the
  144.     Cross toolbar button will also cancel the selecting target window  mode.
  145.     
  146.     3.1 Define Features for Window Dialog
  147.     This dialog allows user to define new or modify existing members of the 
  148.     selected target window database. The Combo box titled "Select 
  149.     Already Defined Windows" lists all existing target windows, and the
  150.     "Help Content" edit box lists the help information defined for the current 
  151.     target window(the one showing in the Combo box's Edit area).
  152.  
  153.     Edit button:    brings up Help Heatures dialog
  154.     Copy button:    copy the current target window 's help features to 
  155.                 the end of the database
  156.     Delete button:  Delete the current target window from database
  157.     OK button:    Confirm the new or modified target window feature
  158.     Cancel button:  Cancel adding new target window, but cannot cancel
  159.                 already modified help features
  160.  
  161.     3.2 Help Heatures Dialog
  162.     This dialog defines or changes target window's help features.
  163.  
  164.     Window ID Details button:
  165.     This brings up Window Identification Details dialog.
  166.     When user moves mouse cursor over any window, PopHelp searches 
  167.     its selected target window database. The conditions defined in the  
  168.     Window Identification Details dialog are used to test if the window 
  169.     under the cursor meet these conditions. If the window does meet all the
  170.     defined Identification Conditions, its help window will pop up.
  171.     Please note the Window Class is most likely been used(check box checked) 
  172.     to identify a target window, except in some cases where a target window's 
  173.     class name is not fixed.
  174.  
  175.     Background Color, Text Color, Text Font buttons:
  176.     Brings up dialogs to define the help information text's color and font.
  177.  
  178.     Apply to Window, To New Rectangle, To Old Rectangle boxes:
  179.     Only one of these check boxes will be checked at a time, indicating the 
  180.     help information defined will apply to a window, a new rectangle inside the 
  181.     target window, or an already defined old rectangle.
  182.  
  183.     Rectangle Details button:
  184.     When Apply to New Rectangle or  To Old Rectangle  is checked,
  185.     this button brings up the Rectangle Details dialog, which defines if
  186.     the target rectangle's start position will be scaled along X or Y axis, 
  187.     or the target rectangle's Width or Height will be scaled, when the target 
  188.     rectangle's parent window changes size. Currently the scaling ratio
  189.     is always according to the ratio recorded at the time the definition is taking
  190.     place. An example is in the pbrush.hif file, the drawing tool window(of 
  191.     class "pbTool") has defined 18 rectangles, all of them have the four check
  192.     boxes in Rectangle Details dialog checked, this is why when pbrush.hif is
  193.     loaded, no matter how you scale the PaintBrush's main window(therefore
  194.     changing the drawing tool window's size), as the cursor moves over any of
  195.     the 18 rectangles in its drawing tool window, they will always correctly 
  196.     popup the context sensitive help information.
  197.  
  198.     Trigger Details button:
  199.     This brings up Trigger Details dialog, that defines how the help info.
  200.     for a target window or for all the target rectangles inside a target window 
  201.     will be triggered, i.e., when the cursor is over the target window or target 
  202.     rectangle, all the trigger conditions (if defined) must be satisfied before 
  203.     the help information window pops up. 
  204.  
  205.     Multiple trigger conditions can be defined at the same time.
  206.  
  207.     Note if a "Key Down" trigger is defined, to make the help info. window
  208.     pop up by pressing the trigger key(s), the mouse cursor must be moving
  209.     over the target window/rectangle, and the input focus must be already at 
  210.     the target window.
  211.  
  212.     Size/Pos. Details button:
  213.     This activates the Size/Pos. Details dialog to define the help information
  214.     window's size and postion, when it is shown. All size and position values are 
  215.     in screen co-ordinates.
  216.     
  217.     If the Size Fixed box is checked, the help info window's size will be the 
  218.     Width and Height values defined on that line.
  219.  
  220.     If the Size Prop. box is checked, the help info. window's width will be
  221.     proportional to the target window's width at the ratio defined inside 
  222.     the width edit, the help info. window's heigth will be proportional to the 
  223.     target window's height at the ratio defined inside the height edit.
  224.  
  225.     If neither Size Fixed nor Size Prop. is checked, the help info window's 
  226.     size defaults to approximately 104 X 57 pixels.
  227.  
  228.     The rest of the controls  define help info window's starting position:
  229.     If the position needs to be variable relative to the target window's position
  230.     (default to at the target window's X Centre, Y Bottom), the boxes inside the
  231.     Pos. Variable group can be used, else the Pos. Fixed box can be 
  232.     checked to make the starting position relative to the actual screen's origin
  233.     (0, 0) position.
  234.  
  235.     Content Details button:
  236.     This pops up the Help Content Details dialog, which defines the content
  237.     inside the help information window to be text, or MCI file playback(*.avi for
  238.     video, *.wav for sound, *.bmp for bitmap), or executing another program.
  239.     
  240.     When Execute Program is selected, the SW_: Combo box can be used
  241.     to set visibility flag of the program at start up. The options are the same as 
  242.     in the ShowWindow() SKD call's parameter nCmdShow.
  243.  
  244.     Style Details button:
  245.     This brings up Help Style dialog, which currently allows only 
  246.     Manual Dismiss to be defined. By default, the help infomation window
  247.     will disappear when the mouse cursor is moved out of the target window
  248.     or target rectangle. When Manual Dismiss style is on, the help info
  249.     window will not dismiss itself as the mouse is moving out of the target
  250.     window: it will disappear only by pressing the Escape or Enter key
  251.     (when focus is in help info window). Note pressing these keys will not
  252.     dismiss the help info window if the Manual Dismiss style is off.
  253.  
  254.     Delete Old Rect button:
  255.     When (Apply help info) To Old Rectangle box is checked, pressing
  256.     this button will delete the current old rectangle as being displayed in
  257.     the Combo box to the right of the To Old Rectangle check box.
  258.  
  259.     OK button and Keep Old Rect box:
  260.     Normally, when (Apply help info) To New Rectangle or To Old Rectangle 
  261.     box is  checked, pressing OK of the Help Features dialog needs to be 
  262.     followed by selecting or re-selecting  the target rectangle: clicking the 
  263.     mouse inside the target window twice to indicate the two diagonal points
  264.     bounding the rectangle. Each clicking is prompted by some messages in the
  265.     PopHelp main window's client area, and is followed by a simple beep
  266.     indicating the clicking has successfully recorded that point.
  267.     When To Old Rectangle box and Keep Old Rect box are both checked, 
  268.     clicking OK will make PopHelp to use the old rectangle's current 
  269.     co-ordinates, therefore no redefiniton for that old rectangle is needed.
  270.  
  271. 4.  Trigger Help
  272.     When the target window database is not empty, moving mouse cursor 
  273.     over any defined target window/target rectangle will cause PopHelp
  274.     to examine the database members against the window under the cursor.
  275.     If all triggering conditions are met for any one window/rectangle in the 
  276.     database, the help information window will pop up.
  277.     Moving mouse out of the target window/rectangle will dismiss the help info
  278.     window, except when the Manual Dismiss has been set for that target window.
  279.  
  280. 5.  Save and Load HIF Files
  281.     The currently defined target window database can be saved into disk file 
  282.     by selecting Save or Save As... menu item. If the database is empty, the
  283.     save will generate an HIF file indicating empty database.
  284.  
  285.     Loading HIF file causes PopHelp to fill the database with the data from
  286.     one or more HIF files:
  287.     Load: Clear current database and load a new HIF file having the name 
  288.         as show on the PopHelp's main window title bar
  289.     Load From:Clear current database, load one or more HIF file
  290.                      (can do multiple file selection)
  291.     Load on Top From: Without clearing current database,  load one more 
  292.                 HIF file on top of the current database content. 
  293.                  if the newly loaded file contains target window having 
  294.                  same module name and class name as any existing 
  295.                  target window, the window from the new file will not
  296.                  be added into database.
  297.  
  298. 6.  Other Operations under File Menu(Install, Setup, Modify, Clear)
  299.  
  300.     The Install menu selection will pop up the
  301.     Install PopHelp into Windows dialog:
  302.         On entry, the HIF Files listbox contains all the files assigned to the
  303.         initHIFFiles entry of the [PopHelp] section in win.ini file.
  304.  
  305.         Add File/Delete File button allows you to add/delete HIF files
  306.         into/from the listbox.
  307.         Install button will put the HIF file names in the listbox into the
  308.         initHIFFiles entry. If the HIF file listbox has no file, the initHIFFiles 
  309.         entry will equal NULL.
  310.  
  311.     Setup Menu Item:
  312.         The Saved HIF Features allows user to define if PopHelp 
  313.         will be ReadOnly, Iconized or Hidden at the next loading of the
  314.         HIF file.  On the otherhand, the Hot Key To Show/Hide PopHelp 
  315.         Window will take effect immediately once you change the hot key
  316.         and hit OK button.
  317.  
  318.         ReadOnly HIF file will not permit changes on that HIF file's content.
  319.  
  320.         All the Yes Features and Hot Keys defined in this dialog will overwrite 
  321.         the previously defined same feature/hot key. For example, if hif1.hif 
  322.         defines hot key Ctrl+F2 and hif2.hif defines ReadOnly, Hide and hot 
  323.         key Alt+H, then loading both hif1.hif and hif2.hif will make the 
  324.         PopHelp's database ReadOnly, main window initially hidden, 
  325.         and hot key Alt+H can toggle the main window to show or hide.
  326.             
  327.     Modify Menu Item allows user modify any existing 
  328.     target window or rectangle's help features. Once selected, the
  329.     Define Features for Window dialog will appear.  See section 3.1
  330.     for details.
  331.  
  332.     Clear Menu Item will clear current database.  
  333.  
  334.  
  335. 7.  Future Development
  336.     7.1 Allow the help content to be invoking WinHelp SKD call with all parameters
  337.                  specified by the user
  338.     7.2 Allow the help content to be a user-definable pop-up menu
  339.     7.3 Provide function call entries for other applications to dynamically
  340.                 manipulate PopHelp's behaviour at run-time
  341.     7.4 Improve the memory management mechanism to allow unlimited text
  342.                  for each target window/rectangle.
  343.     7.5 Provide a PopHelp definition language to define arbitrary triggering 
  344.                  methods and arbitrary target window identification methods.
  345.     7.6 Draw a Windows Tree inside PopHelp's main window to show all live
  346.                  windows in the system, so that target windows can be easily picked up
  347.                  from the tree.
  348.     7.7 Port PopHelp to Win32 environment as true 32-bit application. 
  349.     7.8 Add WinHelp on-line help system for PopHelp.      
  350.  
  351. 8.  Known Problems
  352.     8.1 Target Window Identification is not perfect, and probably can never be,
  353.     due to lacking a unique and sustainable mechanism under MS Windows to 
  354.     identify an arbitrary window.
  355.     8.2 If Two Ajacent Rectangles Overlap, Their Help Info Window Will
  356.     Show up Alternatively, therefore it is recommended the users make
  357.     sure no target rectangles in the same target window overlap so that
  358.     the constant poping up of more than one help info window won't happen.
  359.  
  360.  
  361. --------------------------------------------------------------------------------------------------------------------
  362. [1].  Not available in version 1.0
  363.  
  364. [2].  Choices are limited in version 1.0
  365.