OS/2 Shareware BBS: 10 Tools/10-Tools.zip/hookkbsm.zip/HOOKKBSM.DOC

Text File | 1993-07-28 | 19KB | 371 lines

Document File for HOOKKBSM PROGRAM

From : Morton F. Kaplon  CIS : 73457,437
       1047 Johnston Drive
       Bethlehem PA 18017
       [phone]

Revised and Updated : Thu  07-22-1993

Subject : Hooking the Keyboard in OS/2 2.0, Assigning HotKeys,
          MACROS:Recording and Playing Back KeyStrokes and Mouse Actions

INTRODUCTION and OVERVIEW

  HOOKKBSM is an OS/2 equivalent of a DOS TRS program. Operationally it
  consists of two cooperating entities. One is the DLL(dynamic link library)
  named HOOKDLSM.DLL and the other the executable HOOKKBSM.EXE. When HOOKKBSM
  is loaded, it in turns loads HOOKDLSM into memory where it remains until it
  is removed from memory by an explicit call (made by HOOKKBSM when it is
  closed). Since HOOKDLSM is a dynamic link library, it can in principle
  interact with programs other than the one which loaded it. In this
  application, the DLL contains two functions. One named INITIALIZE which is a
  specific link between it and HOOKKBSM, and the other named InputHook which
  is called by the system whenver the WinGetMsg or the WinPeekMsg functions
  are about to return a message. Thus the DLL has access to all messages in
  the system message queue.

  When HOOKKBSM is loaded, it displays a small window named "Hook" in the
  lower right Corner of the Desktop. In addition to providing evidence of the
  Active existence of HOOKKBSM, the window is used to display messages when
  operating in MacroRecord or MacroPlayBack mode and when the file containing
  user assignment data has been changed and re-read into memory.

  In its role as a hot-key actuator it tests ALL WM_CHAR messages in the
  message queue, the equivalent in DOS of hooking the Keyboard Interrupt. When
  a key stroke meeting a HotKey definition is detected (one of the sequence
  Shift-Alt/Ctrl-X), HOOKDLSM notifies HOOKKBSM by POSTing a message to it
  with the mp1 parameter holding a flag indicating whether the Alt or Ctrl key
  was struck along with the Shift Key and the parameter mp2 holding the Scan
  Code of the Key X that was struck. HOOKKBSM takes action if the key X is
  defined in its Data structures.

  Its role as a Macro Recorder is initiated by the user action of
  pressing the Shift-Ctrl-LeftArrow combination. HOOKKBSM is notified of
  this by the action above, and in turn Calls HOOKDLSM setting a flag to
  ON that enables the recording of all messages from the system message
  queue but WM_TIMER (its behavior seems unaffected if WM_TIMER is not
  excluded). The messages are saved in a DataBuffer. Macro recording is
  turned OFF by pressing the combination Shift-Ctrl-RightArrow, which
  results in HOOKKBSM Calling the DLL and setting the flag to OFF. The
  set of messages in the Data Buffer is played back by pressing the
  Shift-Ctrl-Ins key. If the combination Shft-Ctl-PgDn is struck before
  a new macro recording is started, the content of the buffer is saved,
  in ASCII text form to a file named HOOKKBSM.MAC. The file is a set of
  records, one for each message, in the format indicated below. This is
  sort of like a "spy" program and allows one to see what goes on behind
  the scenes, so to speak.

WinHandle MessageID msgParam1 msgParam2  msgTime  X_ScreenP Y_ScreenP TaskListName

  The set of Hot-Keys for which the User may define actions is that for which
  X = 0,1,..,9,A,B,...,Y,Z (independent of case), a total of 72. Values of X =
  1..9 on the White Keys on the KeyPad are reserved for a variety of program
  defined uses as well as the key on the regular keyboard, having the symbol
  "?" in the UpperCase position.

  The reason for requiring the triplet combination of Shift-Alt-X or
  Shift-Ctrl-X is that besides the large number of pre-assigned keys in OS/2,
  many programs use keystroke combinations for accessing specific features and
  if the Hot Key is to be useful, it should not conflict. I can only remember
  one program that I have seen over the years which used a Shift-Alt-X or
  Shift-Ctrl-X combination and so it seems to be a fairly safe one, and one
  that should not lead to conflicts. In filtering KeyStrokes the program
  rejects all but the combinations Shift-Alt-X and Shift-Ctrl-X so that the
  usual run of keystroke assignments of Alt-X or Ctrl-X and all Function key
  combinations will be unaffected. Keystrokes are recognized on the down
  stroke. I would note that the Shift-Alt or Shift-Ctrl combination is
  particularly easy to access on those keyboards where the Shift Key sits
  vertically between the Ctrl and Alt keys.

  For the User defined HotKeys, HOOKKBSM reads the User created file
  HOOKKBSM.DAT which defines the actions associated with each Hot-Key. The
  action taken is that of executing an assigned command which may be a COM,
  EXE, CMD, or BAT file or loading an instance of the command processor for
  either OS/2 or DOS. Thus you may activate a program or load an instance of
  the command processor at the flick of a HotKey without having to access an
  ICON. Included in the files is a sample HOOKKBSM.DAT(one that I use) which
  defines the format to be followed and which the user should modify to
  reflect his/her requirements.

  IF you edit the file HOOKKBSM.DAT when HOOKKBSM is active, you need only
  use the key combination Shift-Alt-UpArrow(White) to activate the changes.
  The "Hook" window in the lower right screen flashes "USER Updated" when this
  is done. This update fixes an assumption about editors made previously.
  Namely that files were not terminated with a Ctrl-Z. That was causing
  errors when many editors (those coming with OS/2) were used that place
  a Ctrl-Z at the EOF.

  In addition there are several features also assigned to Hot Keys which are
  of a diagnostic or informational nature and may be of some educational use
  in understanding some aspects of OS/2. Finally there are some housekeeping
  aspects (removing the "TSR", and closing down the system) and one OS/2 PopUp
  Command window included in the pre-assigned category.

  <--------------------- Pre-Assigned KEY ASSIGNMENTS ----------------------->
  Shft-Alt-Del(wkp)      : unloads program (like unloading a TSR in DOS)
  Shft-Alt-End(wkp)      : performs an orderly shut down of the system
                           (same as from the DeskTop ShutDown Option)
  Shft-Alt-UpArrow(wkp)  : Update DataStructures if HOOKKBSM.DAT changed
  Shft-Alt-Ins(wkp)      : pops up a small OS/2 window in center of screen
  Shft-Ctl-LftArrow(wkp) : Start Macro Recording
  Shft-Ctl-RgtArrow(wkp) : Stop Macro Recording
  Shft-Ctl-PgDn(wkp)     ; Write Last Macro as ASCII text to file HOOKKBSM.MAC
  Shft-Ctl-Ins(wkp)      : Playback Macro Using Current Window SetUp
  Shft-Ctl-?(tkb)        : Display Listing of User Defined HotKeys
  Shft-Alt-?(tkb)        : Display Listing of Pre-assigned Hot Keys

  Shft-Alt-5(wkp)        : For window under Mouse,Displays Handle,WindowClass
                         : Window Type(10h/20h bit),Parent and Owner
  Shft-Ctl-5(wkp)        : WindowEnumerator from Window Under Mouse

  wkp = White Key Pad   tkb = typewriter key board
  All hot-keys callable from anywhere, except Full Screen OS/2 or DOS sessions.


  INSTALLATION

  1: Copy the file HOOKKBSM.EXE to a directory that is defined in your path
     command.

  2: Copy the file HOOKDLSM.DLL to the directory C:\OS2\DLL

  3: a. Copy the file HOOKKBSM.DAT to the directory C:\OS2
     b. Edit the file HOOKKBSM.DAT to fit your requirements.

        Instructions for format are included in the comments in this file.
        This one as defined, uses the 4OS2 command processor. To use the
        OS/2 command processor instead replace

         C:\4OS2\4OS2.EXE  WITH  C:\OS2\CMD.EXE

  4: a. Copy the file HOT-KEYS.PRG to C:\OS2
     b. Copy the file HOT-KEYS.USR to C:\OS2
     c. Edit the file HOT-KEYS.USR to reflect your assignments as made
        in HOOKKBSM.DAT

  5: There are a variety of flags that affect the behavior of hookkbsm
     that can be passed on the command line when it is started.
     These can be passed in either upper or lower case and are:

     /scommandprocessorfilespec  commandprocessorfilespec is the
       filespecification of the command processor to use when using
       the Shift-Alt-Ins(whiteKeys) option to open an OS/2 window.
       The default is the command processor defined by the COMSPEC
       variable in config.sys. This is determined by the program
       when loaded.

     /i This makes the window invisible. When any commands are to be
        displayed in the window, it is made visible for those displays
        and then restored to invisible

     /j The default behavior is for hookkbsm to be not Jumpable, that is
        using Alt-Esc or Alt-Tab does not activate the hookkbsm window.
        This switch makes it responsive to Alt-Esc or Alt-Tab

     /l The default. This positions the hookkbsm window in the lower left
        corner with its defined size.

     /r This positions the hookkbsm window in the lower right corner
        with its  defined size.

       If you want to use the OS/2 command processor

       START HOOKKBSM     starts with the defaults

         OR   If you use the 4OS2 command processor and it is stored in
         c:\4os2\4os2.exe

       START HOOKKBSM /sC:\4OS2\4OS2.EXE

         OR   If you use yet a different command processor use its file
              specification as the parameter on the command line instead
              of C:\4OS2\4OS2.EXE.

       Example:
       START HOOKKBSM /r /i   starts the window as invisible and in the
                              lower right hand corner

  6:  OPTIONALLY you may place the starting command in a STARTUP.CMD file to
       have the HOOK loaded automatically.

OVERVIEW

  FILES REQUIRED TO CREATE HOOKKBSM.EXE AND HOOKDLSM.DLL

  DOSWIN32.MAC  Macros and Equates used by Programs

  HOOKKBSM.ASM  Source for Executable, Assembled and Linked by MLC-W386.CMD

  HOOKDLSM.DEF  Define file needed by IMPLIB and linker for HOOKDLSM.ASM

  HOOKDLSM.ASM  Source for HOOKDLSM.DLL, Assembled and linked by DLL-W386.CMD

  DLL-W386.CMD  IMPLIB and HOOKDLSM.DEF create C:\TOOLKT20\OS2LIB\HOOKDLSM.LIB
                MASM then assembles HOOKDLSM.ASM, LINK386 produces HOOKDLSM.DLL
                and HOOKDLSM.DLL is copied to C:\OS2\DLL directory.

  MLC-W386.CMD  MASM assembles HOOKKBSM.ASM and LINK386 produces HOOKKBSM.EXE

  To ASSEMBLE and LINK use the directory holding the above files as the
  default and the two commands below (in order given) to create the necessary
  DLL and EXE files.

  DLL-W386  HOOKDLSM
  MLC-W386  HOOKKBSM

  FILES REQUIRED TO EXECUTE HOOKKBSM.EXE

  HOT-KEYS.PRG  This is a text file called by the HotKey combination
                Shft-Alt-?..It displays a listing of the HARD CODED
                Key Assignments in a format contained in a Standard
                OS/2 window. It should not be edited and should be
                used as is. MUST BE LOCATED IN C:\OS2.

  HOT_KEYS.USR  This is a text file called by the HotKey combination
                Shft-Ctl-?. It must be created by the USER to reflect
                his/her key assignments as contained in HOOKKBSM.DAT.
                The file presented is a Template that contains space
                for all the User assignable HotKeys and which will
                be contained in a standard OS/2 text window.
                MUST BE LOCATED IN C:\OS2.

  HOOKKBSM.DAT  Text File assigning programs to key strokes-read by HOOKKBSM.
                The USER creates this file according to the structure outlined
                in the sample. MUST BE LOCATED IN C:\OS2. Edit the sample to
                fit your needs.

  HOOKDLSM.DLL  Dynamic Load File Created Above - must be in C:\OS2\DLL

  HOOKKBSM.EXE  Exec file created above

  DO NOT RENAME HOOKDLSM.* or HOOKKBSM.DAT as those names are coded into
                HOOKKBSM.ASM .

  The program is written in 32 bit Assembler. The assembler used is MASM 6.00B
  including its built in MACROS for control structures and segment
  definitions.

  The 32 bit linker (LINK386) and the 32 bit library, along with the necessary
  INC files require the user to have the OS/2 TOOLKIT as well as MASM 6.00B to
  assemble the program.

  PROGRAM METHOD

  The system message queue is hooked using the HK_INPUT parameter. The
  function which samples the message queue is in HOOKDLSM.DLL. In the section
  "Input Hook", p. 30-2 in the Programming Guide, Vol. II, it states : "The
  system calls an input_hook function whenever the WinGetMsg or WinPeekMsg
  functions is about to return a message."

  There are two procedures in HOOKDLSM.DLL. One is named Initialize and is
  used to pass parameters between HOOKKBSM and HOOKDLSM. The other named
  InputHook tests for WM_CHAR and when detected it further tests to see if the
  key combination Shift-Alt-X or Shift-Ctrl-X was struck, with X (as defined
  above) on the down stroke. If that criteria is met its POSTS to HOOKKBSM,
  via the API function WinPostMsg, the message WM_USER+300h. The mp1 parameter
  of that message holds a flag indicating whether Alt or Ctl was down and the
  mp2 parameter has the scan code for the key X that was struck.

  IF at any time the user starts to record a Macro by hitting the
  HotKeyCombination Shft-Ctrl-LeftArrow, then the program HOOKKBSM calls
  the program HOOKDLSM and sets a flag in HOOKDLSM so that the procedure
  InputHook also saves ALL messages in the system queue (but WM_TIMER)
  to a memory Buffer. Omitting the WM_TIMER messages (its inclusion
  seems to make no difference) saves buffer space. Hitting the
  combination Shft-Ctrl-RightArrow results in HOOKKBSM resetting the
  flag in HOOKDLSM that so the recording of all messages is turned OFF.
  If the combination Shft-Ctl-PgDn is struck before a new macro
  recording is started, the content of the buffer is saved, in ASCII
  text form to a file named HOOKKBSM.MAC. The file is a set of records,
  one for each message, in the format indicated below.

WinHandle MessageID msgParam1 msgParam2  msgTime  X_ScreenP Y_ScreenP TaskListName

  The main program, HOOKKBSM.EXE, a PM program, sets up the hook, receives the
  message indicated above and takes the appropriate action depending on the
  Key Stroke. The program is established as visible and is listed in the
  Window List. The small window displayed is located in the lower right hand
  corner of the Desktop. The program should be launched from an OS/2 window
  with the START command, i.e. "START HOOKKBSM" or "START HOOKKBSM
  C:\4OS2\4OS2.EXE" where the latter option uses the command processor
  4os2.exe as the one to be loaded with the Shift-Alt-Ins key strokes. (Any
  other valid ODS/2 2.0 command processor may loaded here in place of the
  default c:\os2\cmd.exe). That command can be placed in a STARTUP.CMD file
  for automatic loading.

  HOOKKBSM determines if the Key actually struck was assigned in the file
  HOOKKBSM.DAT and if so reads its parameters into the appropriate data
  structure required to execute the program.

  The key stroke combination Shift-Alt-End(white) closes down the system in
  the same manner as choosing the ShutDown option from the DeskTop menu does.
  Again you are relieved of hunting for space to access the desktop.

  The program automatically sets DPMI_DOS_API=ENABLED for programs whose
  session type (DOS full or windowed) is defined as 4 or 7 in HOOKKBSM.dat.
  This enables the Dos Protected Mode Interface for the DOS session. If the
  Session type value of 0 is used, DPMI is not enabled as above. It is
  interesting to note that setting that parameter is done by passing the
  DosStartSession data structure an address holding the text string above,
  even though the manual states that the field for a DOS session is reserved
  and must be ZERO. Unfortunately, there are quite a few errors in the OS/2
  Technical Library, but fortunately a lot of people (principally on
  CompuServe) to inform you about them.

  The program also contains a NASCENT  Macro Record and Playback facility
  which is rather limited in its capabilities. AT the present time the
  PlayBack is limited to just the most recent Macro recorded. When Macros are
  recorded, what is saved are the parameters of the message queue as contained
  in the structure QMSG
     QMSG    STRUC
     qmsg_hwnd       DD      ?
     qmsg_msg        DD      ?
     qmsg_mp1        DD      ?
     qmsg_mp2        DD      ?
     qmsg_time       DD      ?
     qmsg_ptl        DB      SIZE POINTL DUP (?)
     qmsg_reserved   DD      ?
     QMSG    ENDS

     POINTL  STRUC
     ptl_x   DD      ?
     ptl_y   DD      ?
     POINTL  ENDS

  The first six components of QMSG make up each Macro RECORD. The first
  element qmsg_hwnd is the handle of the window that was created during the
  actual macro recording. IF a series of windows were opened during that
  recording and then closed, when the macro is played back, the actual handle
  assigned when windows are opened is not necessarily the same as that
  contained in the message and thus the value in the macro record is of no use
  in the playback. IF the window display is different during playback than
  when recorded, mouse actions will be played back differently. Thus, in
  playing back any macro one must be certain that the window set up initially
  is the same as when recorded.

  The playback currently does not handle any other mouse actions than its
  movement and the left mouse button actions.

  It also does not playback the Alt-Esc or Alt-Tab sequences, and only
  plays back those involving CTrl-Esc if the undocumented message 82h is
  trapped for playback. It also does incomplete PlayBacks in those cases
  where two windows on screen are highlighted at the same time, such as
  a Table of Contents window included when On Line documentation as
  brought up by, for example by the command VIEW REXX from the OS/2
  prompt. In these cases, and this is one of the problems puzzling me,
  the keystrokes selecting commands from the Table of Contents appear to
  be played back before the window is completely painted on the screen.
  This appears more dramatically if you use Mouse movements.

  The problem does not occur, when the screen selected, has a single
  highlighted component, such as HELP.

  The macros that record removing items, such as F3 from Table of Contents
  Screens and ALt-F4 to close Containers show problems. Macros recognize
  F3 in closing Table of Contents and also Esc, but do not play back
  the Alt-F4 or Alt-Close(via the mouse) choices.