Using the Visual Debugger in NetBeans IDE
This document describes how to use the Visual Debugger to help you locate and debug the code for visual elements in your GUI application. You can use the visual debugger in Java and JavaFX GUI applications.
In this document you will use the Visual Debugger to explore the Anagram Game sample project. This document will demonstrate how to take a GUI snapshot of the application and then work with the snapshot to locate source code, add listeners to events and view the event log of GUI components.
Taking a GUI Snapshot
In this tutorial you will use the Anagram Game sample application, a Java desktop application with a simple GUI that is available as a sample in the New Project wizard. After you create the project you will start a debugging session and take a GUI snapshot of the application.
Choose File > New Project from the main menu (Ctrl-Shift-N; ⌘-Shift-N on Mac) to open the New Project wizard.
Select Anagram Game in the Samples > Java category. Click Next.
Specify a location for the project. Click Finish.
When you click Finish, the IDE creates the project and opens the project in the Projects window.
Click the Debug button in the toolbar (Ctrl-F5; ⌘-F5 on Mac) to start the debugging session.
Alternatively, right-click the project node in the Projects window and choose Debug.
When you start the session, the IDE will launch the Anagram Game application and open the Debugging window.
For more on running the debugger, see About Running and Debugging Java Application Projects in Developing Applications with NetBeans IDE.
Choose Debug > Take GUI Snapshot from the main menu.
When you choose Take GUI Snapshot, the IDE will take a snapshot of the GUI and will open the snapshot in the main window.
In this guide to the visual debugger you will not use the Debugging window.
Working with the Visual Debugger
The GUI snapshot is a visual debugging tool that can help you locate the source code for GUI components. The source code for GUI components can sometimes be difficult to locate and the snapshot provides a way for you to locate the code based on the GUI instead of searching through the code. You can select components in the snapshot and invoke tasks from the popup menu to view the source code for the component, show the listeners and set breakpoints on components.
Locating the Source Code for Components
This exercise will demonstrate how to use the GUI snapshot to navigate to the lines in the source code where a component is declared and defined. When you select a component in the GUI snapshot, you can use the popup menu to invoke various commands.
The commands can also be invoked from the Navigator window by right-clicking the component and choosing the command in the popup menu.
In the GUI snapshot, select the Guess button.
When you select a component in the snapshot, the IDE displays details about the selected component in the Properties window. If the Properties window is not visible you can choose Window > Properties from the main menu to open the window.
The IDE also displays the location of the component in the form hierarchy in the Navigator window.
Right-click the Guess button in the snapshot and choose Go to Component Declaration from the popup menu.
When you choose Go to Component Declaration the IDE opens the source file in the editor and moves the cursor to the line in the code where
guessButton is declared.
Right-click the Guess button in the snapshot again and choose Go to Component Source.
When you choose Go to Component Source the IDE opens the source file in the editor and moves the cursor to the line in the source code for the JButton component.
You can use the Go to Hierarchy Addition command in the GUI snapshot to locate the line in the source code where a component is added to its container. The Go to Hierarchy Addition command is disabled by default. You can enable the command in the Options window.
Open the Options window.
Click the Java Debugger tab in the Java category in the Options window.
Note. In NetBeans IDE 7.1 the Java Debugger tab is located in the Miscellaneous category in the Options window.
Select Visual Debugging in the list of categories and select Track locations of component hierarchy changes. Click OK.
Stop your debugging session (if one is running).
Note. After you enable the command in the Options window you will need to restart your debugging session and take a new GUI snapshot before you can use the Go to Hierarchy Addition command.
Start a new debugging session and take a GUI snapshot.
Right-click a component in the GUI snapshot and choose Go to Hierarchy Addition.
The IDE will open the source code in the editor at the line where the component is added.
Exploring Component Events
This exercise will demonstrate how you can use the GUI snapshot and the Events window to explore component events, enabling you to locate component listeners and the events that are triggered by the components.
Right-click the Guess button in the snapshot and choose Show Listeners from the popup menu.
When you choose Show Listeners, the IDE opens the Events window. You can see that the Custom Listeners node is expanded.
Right-click com.toy.anagrams.ui.Anagrams$3 below the Custom Listeners node and choose Go to Component Source in the popup menu.
The source code opens in the editor at the line where the listener is defined.
Select the empty text field in the snapshot.
Alternatively, you can select the
guessedWord text field in the Navigator window.
When you select the text field, the items in the Events window will change automatically to display the listeners for the selected component.
In the Events window, double-click the Event Log node to open the Select Listener window.
Alternatively, you can right-click the Event Log node and choose Set Logging Events from the popup menu.
java.awt.event.KeyListenerlistener from the dialog. Click OK. image::images/debug-select-listener.png[title="Line of source code where component is added to container"]
This listener is now listening for keyboard events in the text field.
In the Anagram Game application, type some characters in the text field.
When you type a character in the text field, the event is recorded in the events log. If you expand the Event Log node you can see that each keystroke is now logged. New events appear each time that you type in the Anagram Game application text field. If you expand an individual event, for example
keyPressed , you can see the properties of that event in the log.
If you expand the "Called From…" node for an event you can see the stack trace for the event.
This tutorial was a basic introduction to the visual debugger in the IDE. The visual debugger enables you to easily locate the source code and log events for GUI components. This can be extremely helpful when you are debugging GUI applications.