TokenNavigation

Detailed Description

Classes
struct	TokenActivationAction
	The result of resolving a token into the behavior that activating it should perform. More...
class	TokenNavigationHandler
	Shared implementation of "activate the selected token", used by every view that renders tokens so that double-clicking a token and pressing the "Activate Selection" key behave identically everywhere. More...

Enumerations
enum	TokenActivationType {   NoTokenActivation , NavigateToAddressActivation , NavigateToTypeActivation , NavigateToGotoLabelActivation ,   NavigateToMatchingBraceActivation , DefineNameActivation , EditCommentActivation }
	The kind of behavior that activating a token (by double-clicking it, or by pressing the "Activate Selection" key) should perform. More...

Functions
std::optional< BinaryNinja::DerivedString >	getDerivedStringForToken (FunctionRef func, const BinaryNinja::InstructionTextToken &token)
	Look up the derived string that a token refers to, if any.
uint64_t	getAddressForStringToken (FunctionRef func, const BinaryNinja::InstructionTextToken &token)
	Get the address that a string token refers to.
bool	navigateToExternalLinkForAddress (BinaryViewRef data, uint64_t linkSourceAddr)
	If the given address is an external symbol that is backed by another file in the project, open that file at the corresponding location.
std::optional< uint64_t >	getNavigationTargetForLineTokens (const std::vector< BinaryNinja::InstructionTextToken > &tokens)
	Find the single token on a line that can be navigated to, for use when no individual token is selected.

---

Class Documentation

TokenActivationAction

struct TokenActivationAction

The result of resolving a token into the behavior that activating it should perform.

Public Member Functions
bool	isValid () const
bool	isNavigation () const
	True for the actions that move the view somewhere, as opposed to those that edit the database.
bool	isNavigationToAddress () const
	True for actions that navigate to an address.
Public Attributes
TokenActivationType	type = NoTokenActivation
uint64_t	address = 0
	Target address for NavigateToAddressActivation, or the label identifier for NavigateToGotoLabelActivation.
std::string	typeName
	Name of the type to show for NavigateToTypeActivation.
uint64_t	typeOffset = 0
	Offset of the member to show for NavigateToTypeActivation.

Member Function Documentation

isValid()

bool TokenActivationAction::isValid ( ) const

inline

isNavigation()

bool TokenActivationAction::isNavigation

(

)

const

True for the actions that move the view somewhere, as opposed to those that edit the database.

Used to decide whether an entry point that only navigates should act.

isNavigationToAddress()

bool TokenActivationAction::isNavigationToAddress

(

)

const

True for actions that navigate to an address.

Member Data Documentation

type

TokenActivationType TokenActivationAction::type = NoTokenActivation

address

uint64_t TokenActivationAction::address = 0

Target address for NavigateToAddressActivation, or the label identifier for NavigateToGotoLabelActivation.

typeName

std::string TokenActivationAction::typeName

Name of the type to show for NavigateToTypeActivation.

typeOffset

uint64_t TokenActivationAction::typeOffset = 0

Offset of the member to show for NavigateToTypeActivation.

TokenNavigationHandler

class TokenNavigationHandler

Shared implementation of "activate the selected token", used by every view that renders tokens so that double-clicking a token and pressing the "Activate Selection" key behave identically everywhere.

Views inherit from this alongside their widget and View base classes, provide the context that token resolution needs, and implement the handful of operations that are view specific.

Public Member Functions
virtual	~TokenNavigationHandler ()=default
TokenActivationAction	getActionForToken (const HighlightTokenState &highlight)
	Resolve a token into the action that activating it should perform.
TokenActivationAction	getActionForSelection (const HighlightTokenState &highlight)
	Resolve the current selection into an action, falling back to the contents of the current line when no single token is selected.
bool	activateSelectedToken (const HighlightTokenState &highlight, bool navigationOnly=false)
	Perform the action for the current selection.
bool	canActivateSelectedToken (const HighlightTokenState &highlight, bool navigationOnly=false)
	Determine whether activateSelectedToken would do anything, for use as the validity check of an action.
std::optional< uint64_t >	getNavigationAddressForSelectedToken (const HighlightTokenState &highlight)
	Get the target address for the current selection if it is an action that navigates to an address.
bool	canNavigateToAddressForSelectedToken (const HighlightTokenState &highlight)
	Determine whether getNavigationAddressForSelectedToken would return an address to navigate to, for use as the validity check of an action.
Protected Member Functions
virtual BinaryViewRef	getBinaryViewForTokenActivation ()=0
	The binary view that the tokens were rendered from.
virtual QWidget *	getWidgetForTokenActivation ()=0
	The widget for this view.
virtual View *	getViewForTokenActivation ()=0
	The view to navigate.
virtual UIContext *	getUIContextForTokenActivation ()
	The context that owns the view.
virtual ViewFrame *	getViewFrameForTokenActivation ()
	The view frame that owns the view.
virtual FunctionRef	getFunctionForTokenActivation ()
	The function that the tokens were rendered from, if any.
virtual std::optional< std::vector< BinaryNinja::InstructionTextToken > >	getTokensForLineWithSelection ()
	The tokens of the line containing the selection, used when no single token is selected.
virtual TokenActivationAction	getActionForLineWithSelection ()
	An action to fall back on when neither the selected token nor the tokens on the line resolve to anything, such as navigating to the function that a header line describes.
virtual void	navigateToTokenTarget (uint64_t addr)=0
	Navigate to an address within this view, or to wherever the user's preferences say that the address should be shown.
virtual bool	navigateToTokenGotoLabel (uint64_t label)
	Navigate to the line defining a goto label.
virtual bool	navigateToTokenMatchingBrace ()
	Navigate to the brace matching the selected one.
virtual void	defineNameForSelectedToken ()
	Rename the selected variable.
virtual void	editCommentForSelectedToken ()
	Edit the selected comment.

Constructor & Destructor Documentation

~TokenNavigationHandler()

virtual TokenNavigationHandler::~TokenNavigationHandler ( )

virtualdefault

Member Function Documentation

getActionForToken()

TokenActivationAction TokenNavigationHandler::getActionForToken

(

const HighlightTokenState &

highlight

)

Resolve a token into the action that activating it should perform.

Returns an invalid action if the token is not one that can be activated.

getActionForSelection()

TokenActivationAction TokenNavigationHandler::getActionForSelection

(

const HighlightTokenState &

highlight

)

Resolve the current selection into an action, falling back to the contents of the current line when no single token is selected.

activateSelectedToken()

bool TokenNavigationHandler::activateSelectedToken	(	const HighlightTokenState &	highlight,
		bool	navigationOnly = false )

Perform the action for the current selection.

If navigationOnly is set, actions that edit the database (renaming a variable, editing a comment) are not performed. Returns true if an action was performed.

canActivateSelectedToken()

bool TokenNavigationHandler::canActivateSelectedToken	(	const HighlightTokenState &	highlight,
		bool	navigationOnly = false )

Determine whether activateSelectedToken would do anything, for use as the validity check of an action.

getNavigationAddressForSelectedToken()

std::optional< uint64_t > TokenNavigationHandler::getNavigationAddressForSelectedToken

(

const HighlightTokenState &

highlight

)

Get the target address for the current selection if it is an action that navigates to an address.

canNavigateToAddressForSelectedToken()

bool TokenNavigationHandler::canNavigateToAddressForSelectedToken

(

const HighlightTokenState &

highlight

)

Determine whether getNavigationAddressForSelectedToken would return an address to navigate to, for use as the validity check of an action.

getBinaryViewForTokenActivation()

virtual BinaryViewRef TokenNavigationHandler::getBinaryViewForTokenActivation ( )

protectedpure virtual

The binary view that the tokens were rendered from.

Implemented in FlowGraphWidget.

getWidgetForTokenActivation()

virtual QWidget * TokenNavigationHandler::getWidgetForTokenActivation ( )

protectedpure virtual

The widget for this view.

Implemented in FlowGraphWidget.

getViewForTokenActivation()

virtual View * TokenNavigationHandler::getViewForTokenActivation ( )

protectedpure virtual

The view to navigate.

Implemented in FlowGraphWidget.

getUIContextForTokenActivation()

virtual UIContext * TokenNavigationHandler::getUIContextForTokenActivation ( )

protectedvirtual

The context that owns the view.

getViewFrameForTokenActivation()

virtual ViewFrame * TokenNavigationHandler::getViewFrameForTokenActivation ( )

protectedvirtual

The view frame that owns the view.

getFunctionForTokenActivation()

virtual FunctionRef TokenNavigationHandler::getFunctionForTokenActivation ( )

inlineprotectedvirtual

The function that the tokens were rendered from, if any.

Required to resolve tokens that refer to an IL expression, such as derived strings.

Reimplemented in FlowGraphWidget.

getTokensForLineWithSelection()

virtual std::optional< std::vector< BinaryNinja::InstructionTextToken > > TokenNavigationHandler::getTokensForLineWithSelection ( )

inlineprotectedvirtual

The tokens of the line containing the selection, used when no single token is selected.

Reimplemented in FlowGraphWidget.

getActionForLineWithSelection()

virtual TokenActivationAction TokenNavigationHandler::getActionForLineWithSelection ( )

inlineprotectedvirtual

An action to fall back on when neither the selected token nor the tokens on the line resolve to anything, such as navigating to the function that a header line describes.

navigateToTokenTarget()

virtual void TokenNavigationHandler::navigateToTokenTarget ( uint64_t addr )

protectedpure virtual

Navigate to an address within this view, or to wherever the user's preferences say that the address should be shown.

Implemented in FlowGraphWidget.

navigateToTokenGotoLabel()

virtual bool TokenNavigationHandler::navigateToTokenGotoLabel ( uint64_t label )

inlineprotectedvirtual

Navigate to the line defining a goto label.

Views without goto labels need not implement this.

Reimplemented in FlowGraphWidget.

navigateToTokenMatchingBrace()

virtual bool TokenNavigationHandler::navigateToTokenMatchingBrace ( )

inlineprotectedvirtual

Navigate to the brace matching the selected one.

Views without braces need not implement this.

defineNameForSelectedToken()

virtual void TokenNavigationHandler::defineNameForSelectedToken ( )

inlineprotectedvirtual

Rename the selected variable.

Reimplemented in FlowGraphWidget.

editCommentForSelectedToken()

virtual void TokenNavigationHandler::editCommentForSelectedToken ( )

inlineprotectedvirtual

Edit the selected comment.

Reimplemented in FlowGraphWidget.

Enumeration Type Documentation

TokenActivationType

enum TokenActivationType

The kind of behavior that activating a token (by double-clicking it, or by pressing the "Activate Selection" key) should perform.

Enumerator
NoTokenActivation	Nothing can be done with the selected token.
NavigateToAddressActivation	Navigate to an address in the binary.
NavigateToTypeActivation	Show a named type, optionally scrolling to a member at a given offset.
NavigateToGotoLabelActivation	Navigate to the line that defines a goto label.
NavigateToMatchingBraceActivation	Navigate to the brace matching the selected one.
DefineNameActivation	Rename the selected variable.
EditCommentActivation	Edit the selected comment.

Function Documentation

getDerivedStringForToken()

std::optional< BinaryNinja::DerivedString > getDerivedStringForToken	(	FunctionRef	func,
		const BinaryNinja::InstructionTextToken &	token )

Look up the derived string that a token refers to, if any.

Only tokens rendered with DerivedStringReferenceTokenContext refer to a derived string.

getAddressForStringToken()

uint64_t getAddressForStringToken	(	FunctionRef	func,
		const BinaryNinja::InstructionTextToken &	token )

Get the address that a string token refers to.

For a derived string with a known location, this is the location backing the string (which is not where the token itself is rendered).

navigateToExternalLinkForAddress()

bool navigateToExternalLinkForAddress	(	BinaryViewRef	data,
		uint64_t	linkSourceAddr )

If the given address is an external symbol that is backed by another file in the project, open that file at the corresponding location.

getNavigationTargetForLineTokens()

std::optional< uint64_t > getNavigationTargetForLineTokens

(

const std::vector< BinaryNinja::InstructionTextToken > &

tokens

)

Find the single token on a line that can be navigated to, for use when no individual token is selected.

Tokens are searched for in order of preference, and a category containing more than one candidate is treated as ambiguous rather than picking one arbitrarily.