Functions

Navigation:  The User Interface > The main display >

Functions

Previous pageReturn to chapter overviewNext page

The Functions tab view displays function and line coverage information for each hookable function.

 

interactiveRead on, or click a part of the image below to jump straight to the help for that area.

 

tab-functions-view

 

 

Functions

 

The function coverage view focuses on coverage at the function level. If you need to see an overview of coverage for a whole file, see the Coverage view.

 

When viewing the source code, only the lines in the selected function are highlighted.

 

As with many of the tab views, the display is split into two resizable panes.

 

the left side lists a summary of the function coverage data
 

the right side shows source code for any function selected on the left

 

We'll cover the data view and its popup menu first, and then the source code view.

 

 

The data view
 

tab-functions-header

 

Each line in the view displays the following:

 

the file, class, method or function, depending on the Type of the view
 

the percentage of hookable lines that have been visited in the function

 

the number of hooked lines in the function
 

This is not the same as the number of hookable lines since some lines or functions can be excluded from hooking.
 

the number of different lines that have been visited in the function

 

the total visit count for the function

 

This may be equal to the number of different lines visited unless you're counting each visit separately as seen in one of the hierarchical view examples below.

 

The count also includes lines which should have been hooked but failed, for example because the instrumentation level was set low.

 

the DLL in which the file was found

 

 

The Function coverage can show a hierarchical or list view of data according to the Type setting.

 

 

Hierarchical views
 

A hierarchical view is shown when the Type is set to one of the following:

 

class / method

 

file / function (the default)
 

directory structure / file / function
 

Examples:

 

Data organised by file / function:

 

tab-functions-file-function

 

 

Data organised by directory / file / function:

 

tab-functions-directory

 

note For class and directory hierarchical views, the statistics shown against each directory or class is an aggregated sum of all the contained functions

 

 

List views
 

A hierarchical view is shown when the Type is set to one of the following:

 

method or function ordered by name
 

class or method ordered by number of lines in file
 

Example:

 

Data organised by function name:

 

tab-functions-function

 

 

note Function names are sorted alphabetically. Destructors (starting with ~) will likely be shown first or last depending on the sorting order.

 

note Only the first column in the view can be used for sorting the data.

 

 

Line colours

 

Each line of data in any of the views is colour coded to indicate one of the following:

 

the function has not had any lines visited at all
 

tab-functions-unvisited

 

some but not all lines in the function have been visited
 

tab-functions-partial-visited

 

every hookable line in the function has been visited, i.e. 100% file coverage

 

tab-functions-all-visited

 

no lines in the function could be hooked
 

tab-branch-coverage-unhooked

 

note Unhookable lines are likely when the instrumentation level is set low, for example 'incomplete but faster'.

 

 

Unhooked lines

 

Depending on what file or DLLs hook filters are set up, not all the hookable lines in a header file may attempt to be hooked.

 

Only those that are actually used (e.g. via macros or inlines) in the program may actually be hooked.

 

note By default, lines that could not be hooked don't stop the coverage from reaching 100%, but you can change this.

 

In this example below, the instrumentation level was set low ('incomplete but faster') to force significant numbers of unhooked lines.

 

tab-functions-unhookable-lines

 

 

Scrollbar visualisations

 

To the right of each pane, beside the vertical scrollbars, you'll see a coloured area which represents the coverage.

 

As with the scrollbar visualisation in the Coverage tab, the bar in the left hand pane shows an overall view of the coverage distribution across every function listed.

 

However, because function coverage is broken down to the function level, selecting a function in the left hand pane will only highlight lines in the source code view for that function.

 

 

Function coverage options

 

The function coverage controls are shown below.

 

tab-branch-coverage-display-options

 

 

Window orientation

 

The horizontal or vertical orientation of the statistics and source code panes can be toggled with the orientation button.

 

coverageOrientationVert        coverageOrientationHoriz

 

 

Updating the display

 

Refresh instructionStep updates the display - as does the refresh button on the Tools menu and toolbar

 

 

View type

 

Changing the Type alters the view to one of the hierarchical or list views described earlier.

 

By Class instructionStep shows a hierarchical C++ class / method view

 

By Function Name instructionStep shows a list of all functions sorted by name

 

By Directory instructionStep shows a hierarchical view of directory / file / function

 

By File instructionStep shows a hierarchical file / function view

 

By Number of Lines instructionStep shows a list of classes or methods ordered by number of lines in file

 

note Each view shows the same overall data, just in different arrangements

 

 

Sort order

 

Descending instructionStep reverses the direction of the data, sorted by the names in first column

 

 

Expanding and collapsing the data

 

Expand All / Collapse All instructionStep switches any hierarchical view between collapsed and expanded view

 

Collapsed instructionStep sets the preferred state of the view when the data is refreshed

 

This includes when you change some of the other display settings.

 

 

Display settings

 

Highlight unvisited lines instructionStep highlight rows for any functions that have not been visited (on by default)

 

If switched off, unvisited lines appear white - or whatever colour you've set as the unselected colour.

 

Show unhooked functions instructionStep display information about functions that could not be hooked (off by default)

 

This means unhookable lines, for example lines that were too short, rather than lines or functions that are deliberately set not to be hooked.

 

 

File list menu optionsright_mouse_button

 

The popup menu is identical to that for the Branch Coverage view.

 

The following popup menu is available over the data area to add filters, edit code, or expand and collapse the view.

 

tab-branch-coverage-menu

 

 

right_mouse_buttonMenu options: Instrumentation Filter

 

The instrumentation filter lets you add filters at different levels of granularity:

 

tab-branch-coverage-menu-inst-filter

 

Exclude Filename instructionStep adds a new filter to the Source Files Filter settings, excluding it from the results of subsequent sessions
 

Exclude Directory instructionStep excludes all files in the same directory as the selected file
 

From the sub menu, choose the directory level at which you want to exclude files, right up to the drive specifier if you need to.

 

tab-coverage-menu-inst-filter-dir

 

Exclude DLL instructionStep excludes all files belonging to the same executable or DLL as the selected file
 

This adds a filter to the Hooked DLLs settings.

 

 

The other options all add a filter to the Class and function filter settings

 

Filter By Class instructionStep excludes all functions in the selected class
 

Example filter: CTeststakDoc::

 

Filter By Class And Method instructionStep excludes only the selected class functions
 

Example filter: CTeststakDoc::OnNewDocument

 

Filter By Method instructionStep excludes all functions in the selected class
 

Example filter: OnNewDocument

 

 

note Filters become effective at the start of the next session. Adding a filter during a session will show the relevant rows in grey so that you can see which items would be filtered, but the coverage results will continue to be included for the rest of the current session.

 

 

right_mouse_buttonMenu option: editing source code

 

Edit Source Code... instructionStep opens the default or preferred editor to edit the source code

 

 

right_mouse_buttonMenu options: collapse / expand trace

 

Expand or Collapse Entry instructionStep shows and hides the selected section in the view, the same as using the expand-symbol or collapse-symbolbuttons

 

Collapse All instructionStep completely collapses all sections

 

Expand All instructionStep expands all the sections

 

 

The functions source code view

 

Clicking on a function in the left hand panel, shows that file and function in the source code view on the right.

 

The source code uses syntax highlighting by default, with the background colour of the line indicating if the function lines have been visited, are unvisited or could not be hooked.

 

Icons are displayed next to hooked and unhooked function lines indicating visit and hook status and visit counts are shown in-line with the code.

 

Hovering over a line for a short period of time shows a tooltip with the number of visits to the line.

 

Contiguous groups of lines can be collapsed and hidden from view.

 

 

Source code function information

 

On the right hand panel, above the source code, you'll find some information about lines in the selected function in the source file

 

 

tab-functions-file-info

 

The details shown include the following:

 

'quick view' details for visited and unvisited lines in the function, pink for unvisited, light green for partial visited, and dark green for 100% visited
 

tab-functions-file-info-dial           tab-functions-dial-covered

 

 

the source code filename and the executable or DLL to which it belongs
 

tab-functions-file-info-file-exec

 

the same statistics as seen in the left hand panel
 

tab-functions-file-info-stats

 

 

Browsing visited and unvisited lines

 

next-unvisted instructionStep show the previous and next unvisited line in the function
 

b_f7 and b_shift + b_f7 also navigate forwards and backwards when the source code has focus.
 

next-visited instructionStep show previous and next visited line in the function
 

The arrows are grey when disabled.

 

b_f8 and b_shift + b_f8 also navigate forwards and backwards through the visited lines.

 

 

Line instructionStep step by individual lines of code
 

Group instructionStep step by groups of contiguous visited or unvisited lines

 

 

Keyboard access: Find and Goto

 

When the data view or the source code view has focus, some keyboard access is available to search for text, or to navigate to numbered lines.

 

 

Find text in data view

 

In the data view, b_ctrl + b_f displays a dialog that will allow you to search by full or partial match for text in the first column - the contents of which depends on the Type setting.

 

find-in-brach-coverage-data

 

 

Find text in source view

 

In the source code view b_ctrl + b_f lets you search by full or partial match anywhere in the file.

 

goto-line-functions-dialog

 

 

Goto line

 

In the source code view, b_ctrl + b_g displays a goto-line dialog.

 

goto-line-dialog

 

.