wguispy.gml

开放源码的编译器open watcom 1.6.0版的源代码

:set symbol="msg_info" value="Viewing Message Information"
:set symbol="win_info" value="Viewing Information About a Window"
:set symbol="mark_menu" value="List"
:set symbol="appname" value="&spy"
:set symbol="msg_list" value="message list"
.*
.chap &spy
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix '&spy'
Most Windows programs are message based. Messages are sent to windows
that programs create and the programs are expected to react to the
messages appropriately.
.np
When a program does not react as expected, you must spend time
debugging the program to find and correct the errors. &spy is a tool
designed to help you debug Windows programs by letting you view the
messages sent to windows in Win16 and Win32 applications. By watching how
a program reacts to the messages it receives, you can isolate the
parts of your code that are causing problems and then make the
required corrections.
.np
With &spy:
.begbull
.bull
you can determine if your window is receiving the messages you expect
it to receive.
.bull
you can verify that your window is receiving messages in the order you
expect.
.bull
novice Windows programmers can become familiar with Windows messages,
by viewing the messages and their parameters.
.endbull
.np
As you run your Windows programs, &spy displays messages in the &spy
window. You control the window using the menu items or the &spy
toolbar.
.*
.section Using &spy
.*
.np
This section discusses the following topics:
.begbull $compact
.bull
Starting &spy
.bull
Quitting &spy
.bull
The &spy Menu Bar
.bull
The &spy Toolbar
.endbull
.*
.beglevel
.*
.section Starting &spy
.*
.np
.ix '&spy' 'start'
.ix 'start' '&spy'
To start &spy, double click on the &spy icon.
This opens the &spy window.
When you start the application, the &spy window is always empty.
This window displays the menu bar, message list and a toolbar.
.figure *depth='3.32' *scale=79 *file='SPY1' The &spy window contains the menu bar, message list and toolbar.
.*
.section Quitting &spy
.*
.np
.ix '&spy' 'leave'
.ix 'leave' '&spy'
To exit &spy, choose Exit from the File menu of the &spy window.
.*
.section The &spy Menu Bar
.*
.np
.ix '&spy' 'Menu Bar'
.ix 'Menu Bar' '&spy'
The menu bar consists of the following five menus:
.begpoint
.point File
Save to a file, start and pause logging, and configure the session
.point List
Manipulate the message list by clearing, marking, and autoscrolling it
.point Spy
Start, stop, and pause the &spy session, select the windows you want
to monitor, and gain access to information in windows.
.point Messages
Select the messages you want to monitor or stop on.
.point Help
Gain access to on-line help information
.endpoint
.figure *depth='0.77' *scale=79 *file='SPY1A' The &spy menu bar.
.*
.section The &spy Toolbar
.*
.np
.ix '&spy' 'toolbar'
The &spy toolbar provides quick access to commonly used menu items.
The following explains the function each tool bar button performs
as well as the equivalent menu item.
.begnote
.note SELECT WINDOW
Select a single window and start spying on it or add a window to the
list of windows being spied on. This is equivalent to the Select
Window and Add Window items in the Spy menu.
.note STOP
Stop monitoring the selected window(s) and cancel the window
selections. This is equivalent to the Stop Spying item in the Spy
menu.
.note PEEK AT WINDOW
Obtain information about a selected window. This is equivalent to the
Peek at Window item in the Spy menu.
.note MARK
Record your own comments in the &spy window. This is equivalent to the
Mark item in the List menu.
.note CLEAR MESSAGE LIST
Erase all messages from the &spy window. This is equivalent to the
Clear Message List item in the List menu.
.note SHOW SELECTED WINDOWS
Obtain information about the windows open on your desktop. This is
equivalent to the Show Selected Windows item in the Spy menu.
.note MESSAGES TO WATCH
Select the messages you want to monitor and log. This is equivalent to
the Messages to Watch item in the Messages menu.
.note MESSAGES TO STOP ON
Specify the messages you want &spy to stop on when it encounters them.
This is equivalent to the Messages to Stop on item in the Messages menu.
.endnote
.figure *depth='0.77' *scale=79 *file='SPY1A' The &spy toolbar.
.np
Only one of the following three toolbar buttons appears at a time.
.begnote
.note NOT SPYING
This button appears when &spy is not monitoring any windows.  Pressing
this button has no effect.  It is simply an indicator to you that
spying is not in progress.
.note STOP SPYING TEMPORARILY
This button appears when &spy is in the process of monitoring one or
more windows. Choosing this button temporarily suspends monitoring
operations. This is equivalent to the Stop Spying Temporarily item in
the Spy menu.
.note CONTINUE SPYING
This button appears when you instruct &spy to temporarily suspend
monitoring operations. Choosing this button resumes monitoring
operations. This is equivalent to the Continue Spying item in the Spy
menu.
.endnote
.*
.endlevel
.*
.section The &spy Window
.*
.np
.ix '&spy' 'Message List'
.ix 'Message List' 'in &spy'
The &spy window contains the menu bar and the toolbar discussed above.
However, most of the &spy window is occupied by the message list.  This
is where &spy logs the messages it monitors.
.figure *depth='3.32' *scale=79 *file='SPY2' Once you start spying, the message list displays the messages selected for monitoring.
.np
For the messages it monitors &spy displays the following information in
the message list:
.begpoint $break
.point Message Name
Name of the message sent.
.point hWnd
The handle of the window that received the message.
.point MsgID
The numeric identifier of the message.
.point wParam
Data specific to the message. This is the value that will be passed
as the wparam parameter of the window's callback function.  To find
the meaning of this parameter see the section &msg_info for information
on how to get help on a message or refer to your Windows 3.x or Win32
programmer's documentation.
.point lParam
Data specific to the message. This is the value that will be passed
as the lparam parameter of the window's callback function. To find
the meaning of this parameter see the section &msg_info for information
on how to get help on a message or refer to your Windows 3.x or Win32
programmer's documentation.
.endpoint
.np
Several spy functions affect the appearance or behavior of the &spy
window.
.begbull $compact
.bull
Setting the Fonts
.bull
Saving
.bull
Clearing the Message List
.bull
Marking the Message List
.bull
Automatic Scrolling
.bull
Always On Top
.endbull
.*
.beglevel
.*
.section Spy: Setting the Fonts
.*
.np
.ix '&spy' 'set fonts'
.ix 'Fonts' 'set in &spy'
The Set Font item in the File menu allows you to set the font, style,
and size for the text in the &spy window. Choosing this item opens
the Font dialog box. Select the desired font details and click on OK
to close the dialog and apply the fonts.
.*
.section Spy: Saving the Contents of the Message List
.*
.np
.ix '&spy' 'saving in'
.ix 'save' 'in &spy'
The Save and Save as items under the File menu in &spy allow you to
save the contents of the message list to a text file. Saving
information to a file enables you to print the output later or
annotate the text file on-line.
.np
Choose Save from the File menu in the &spy window to save the message
list information into the current working directory. A message box
appears indicating the path to which &spy saved the file.
.np
.ix '&spy' 'Save As option'
.ix 'Save As' 'in &spy'
Choose Save As from the File menu to specify the file to which you
want to save the currently displayed information. This opens a Save As
dialog box where you select the desired file. Click on OK when
completed. A message box appears indicating the path to which &spy
saved the file.
.*
.section Spy: Clearing the Message List
.*
.np
.ix '&spy' 'clear message list'
.ix 'Message List' 'clear in &spy'
Choose Clear from the File menu to delete all information from the
message list.
.*
.section Spy: Marking the Message List
.*
.ix '&spy' 'mark message list'
.ix 'Message List' 'mark in &spy'
.*
:INCLUDE file='wguimark.gml'
.*
.section Spy: Automatic Scrolling
.*
.np
.ix '&spy' 'automatic scrolling'
.ix 'Auto Scroll Message List'
As &spy writes new information to the message list, the information
is added to the bottom of the list. Choosing Auto Scroll Message List
from the List menu tells &spy to automatically scroll the information
in the message list so that the most recent information written to the
message list always appears on the screen. The Auto Scroll Message List
menu item is checked when this feature is active.
.np
When this feature is deactivated, new messages written to the
message list are added to the bottom of the list and you must use
the scroll bar to scroll down and view the information.
.*
.section Spy: Always On Top
.*
.np
.ix 'Always On Top'
.ix '&spy' 'always on top'
The &spy window behaves like all other windows&mdash.it moves into the
background when other windows are selected. To ensure the &spy window
is visible at all times, select the Always On Top item from the File
menu. The Always On Top menu item is checked when this feature is
enabled. To turn this feature off, select the item again from the File
menu.
.*
.endlevel
.*
.section Selecting Messages to Monitor
.*
.np
.ix 'messages' 'watching'
.ix 'messages' 'stopping on'
.ix '&spy' 'selecting messages to monitor'
Each window receives an overwhelming volume of messages. Generally,
you will only be interested in a small subset of these. &spy lets
you limit the messages on which it will report so that you do not have
to sort through all the extraneous data yourself.
.np
&spy maintains two lists of messages: the messages to watch list and
the messages to stop on list.  When spy monitors a message in the
messages to watch list it adds information about that message to
the Message List in the &spy window. When spy monitors a message
in the messages to stop on list it displays a message box reporting
that the message has been encountered and pauses spying operations
until you restart them by selecting Continue Spying from the spy menu.
Any message that does not appear on either list is ignored by &spy.
.np
To modify the messages to watch list choose Messages To Watch from the
Messages menu. To modify the messages to stop on list choose Messages
To Stop On from the Messages menu. In either case, the process of
modifying the list is the same. The rest of this section explains the
dialogs you use to do this.
.*
.beglevel
.*
.section *refid=selinms Selecting Individual Messages
.*
.np
.ix 'messages' 'watching'
.ix 'messages' 'stopping on'
The most precise way to modify the messages to watch or messages to
stop on lists is simply to select a set of individual messages to
appear on the list. To select a set of individual messages to
monitor follow these procedures.
.begstep
.step Choose Messages To Watch or Messages To Stop On
from the Messages Menu.
.result
This opens a Message Class dialog box.  The caption of
the dialog box reflects the menu item selected.
.figure *depth='3.23' *scale=80 *file='SPY5' In the Message Class dialog, select change button.
.step Click on the Change button
next to the alphabetic range into
which your first message selection falls.
.result
This opens a dialog that contains a check box for each message
that falls into that alphabetic range.
.figure *depth='2.55' *scale=52 *file='SPY6' In the Message Range dialog, you select the individual messages you want &spy to watch or stop on.
.step Add or remove messages from the list of messages.
.result
A message appears on the selected list if it is checked.
The following buttons are provided for your convenience:
.begnote
.note Clear All
Uncheck all messages on this dialog.
.note Set All
Check all messages on this dialog.
.endnote
.step Choose an action button.
.result
The following buttons allow you to proceed from this dialog:
.begnote
.note Next
Close the current dialog and open the one for the alphabetic
range of messages immediately following this one. Changes made
on the current dialog will not be saved until you press the
OK button on some future message range dialog.
.note Prev
Close the current dialog and open the one for the alphabetic
range of messages immediately preceding this one. Changes
made on the current dialog will not be saved until you press
the OK button on some future message range dialog.
.note OK
Close the current dialog and save all changes made in it and
in previous dialog that were exited using the Next or Prev
button.