3.2.1. ui – User Interface module

This module exposes a number of tools and class definitions for interacting with IDA’s user interface. This includes things such as getting the current state of user input, information about windows that are in use as well as utilities for simplifying the customization of the interface.

There are a few namespaces that are provided in order to get the current state. The ui.current namespace allows for one to get the current address, function, segment, window, as well as a number of other things.

A number of namespaces defined within this module also allows a user to interact with the different windows that are currently in use. This can allow for one to automatically show or hide a window that they wish to expose to the user.

3.2.1.1. Namespace list

These are the namespaces available within this module. Namespaces group similar functions that can be used typically for the same concept. Please see Classes as namespaces for more information on namespaces. For more information on multicase functions or aliases, please see Multicased functions or Aliases.

3.2.1.1.1. ui.application

This namespace is for getting information about the application user-interface.

ui.application()

Return the current instance of the application.

application.beep()

Beep using the application interface.

Aliases: ui.beep

application.window()

Return the current window for the application.

application.windows()

Return all of the top-level windows for the application.

3.2.1.1.2. ui.appwindow

Base namespace used for interacting with the windows provided by IDA.

appwindow.close()

Close or hide the window belonging to the namespace.

appwindow.open(*args)

Open or show the window belonging to the namespace.

Parameters:*args – any options or arguments to pass to the windows open function

3.2.1.1.3. ui.ask

This namespace contains utilities for asking the user for some particular type of information. These will typically require a user-interface of some sort and will block while waiting for the user to respond.

If the default parameter is specified to any of the functions within this namespace, then its value will be used by default in the inbox that is displayed to the user.

ui.ask(**default)

Request the user choose from the options “yes”, “no”, or “cancel”.

Parameters:**default – if yes, no, or cancel is set to true, then use that value as the default

ui.ask(message, **default)

Request the user choose from the options “yes”, “no”, or “cancel” using the specified message as the prompt.

Parameters:

• message – the message to display when asking the user for input
• **default – if yes, no, or cancel is set to true, then use that value as the default

ask.address(**default)

Request the user provide an address.

Parameters:**default – the default address for the user to change. if one was not specified, then use the current address.

ask.address(message, **default)

Request the user provide an address using the specified message as the prompt.

If the valid parameter is specified, then verify that the address is within the bounds of the database. If the bounds parameter is specified, then verify that the address chosen by the user is within the provided bounds.

Parameters:

• message – the message to display when asking the user for input
• **default – the default address for the user to change. if one was not specified, then use the current address.

ask.integer(**default)

Request the user provide an integer.

Parameters:**default – the default integer for the user to change. if one was not specified, then use the previous integer that the user input.

ask.integer(message, **default)

Request the user provide an integer using the specified message as the prompt.

Parameters:

• message – the message to display when asking the user for input
• **default – the default integer for the user to change. if one was not specified, then use the previous integer that the user input.

ask.note(**default)

Request the user provide a multi-lined string.

Parameters:**default – the default string for the user to change

ask.note(message, **default)

Request the user provide a multi-lined string using the specified message as the prompt.

If the length parameter is provided as an integer, then constrain the length of the user’s input to the integer that was specified.

Parameters:

• message – the message to display when asking the user for input
• **default – the default string for the user to change

ask.segment(**default)

Request the user provide a segment.

Parameters:**default – the default segment for the user to change. if one was not specified, then use the address of the current segment.

ask.segment(message, **default)

Request the user provide a segment using the specified message as the prompt.

Parameters:

• message – the message to display when asking the user for input
• **default – the default segment for the user to change. if one was not specified, then use the address of the current segment.

ask.string(**default)

Request the user provide a string.

Parameters:**default – the default string for the user to change

ask.string(message, **default)

Request the user provide a string using the specified message as the prompt.

Parameters:

• message – the message to display when asking the user for input
• **default – the default string for the user to change

ask.yn(**default)

Request the user choose from the options “yes”, “no”, or “cancel”.

Parameters:**default –

ask.yn(message, **default)

Request the user choose from the options “yes”, “no”, or “cancel” using the specified message as the prompt.

If any of the options are specified as a boolean, then it is assumed that this option will be the default. If the user chooses “cancel”, then this value will be returned instead of the value None.

Parameters:

• message – the message to display when asking the user for input
• **default – if yes, no, or cancel is set to true, then use that value as the default

3.2.1.1.4. ui.breakpoints

This namespace is for interacting with the Breakpoints window.

Bases: ui.appwindow

3.2.1.1.5. ui.calls

This namespace is for interacting with the (Function) Calls window.

Bases: ui.appwindow

3.2.1.1.6. ui.clipboard

This namespace is for interacting with the current clipboard state.

ui.clipboard()

Return the current clipboard.

3.2.1.1.7. ui.current

This namespace contains tools for fetching information about the current selection state. This can be used to get the state of thigns that are currently selected such as the address, function, segment, clipboard, widget, or even the current window in use.

current.address()

Return the current address.

current.color()

Return the color of the current item.

current.function()

Return the current function.

current.operand()

Return the currently selected operand number.

Aliases: ui.current.opnum

current.segment()

Return the current segment.

current.selection()

Return the current address range of whatever is selected

Aliases: ui.current.selected

current.status()

Return the IDA status.

current.symbol()

Return the current highlighted symbol name or register.

current.viewer()

Return the current viewer that is being used.

current.widget()

Return the current widget that is being used.

current.window()

Return the current window that is being used.

3.2.1.1.8. ui.disassembly

This namespace is for interacting with the Disassembly window.

Bases: ui.appwindow

disassembly.refresh()

Refresh the main IDA disassembly view.

3.2.1.1.9. ui.dump

This namespace is for interacting with the (Hex) Dump window.

Bases: ui.appwindow

3.2.1.1.10. ui.enumerations

This namespace is for interacting with the Enumerations window.

Bases: ui.appwindow

3.2.1.1.11. ui.exports

This namespace is for interacting with the Exports window.

Bases: ui.appwindow

3.2.1.1.12. ui.frame

This namespace is for interacting with the (Function) Frame window.

Bases: ui.appwindow

3.2.1.1.13. ui.functions

This namespace is for interacting with the Functions window.

Bases: ui.appwindow

3.2.1.1.14. ui.imports

This namespace is for interacting with the Imports window.

Bases: ui.appwindow

3.2.1.1.15. ui.keyboard

Base namespace for interacting with the keyboard input.

keyboard.input()

Return the current keyboard input context.

keyboard.list()

Display the current list of keyboard combinations that are mapped along with the callable each one is attached to.

keyboard.map(key, callable)

Map the specified key combination to a python callable in IDA.

If the provided key is being re-mapped due to the mapping already existing, then return the previous callable that it was assigned to.

Aliases: ui.keyboard.add

Parameters:

• key – the key to map
• callable – a python callable to execute when the specified key is pressed

keyboard.modifiers()

Return the current keyboard modifiers that are being used.

keyboard.unmap(key)

Unmap the specified key from IDA and return the callable that it was assigned to.

Aliases: ui.keyboard.rm

Parameters:key – the key mapping to unmap

3.2.1.1.16. ui.libraries

This namespace is for interacting with the (Type) Libraries window.

Bases: ui.appwindow

3.2.1.1.17. ui.menu

This namespace is for registering items in IDA’s menu system.

menu.add(path, name, callable, hotkey='', flags=0, args=())

Register a callable as a menu item at the specified path with the provided name.

Parameters:

• path – the menu path to add the item to
• name – the name of the item to add
• callable – the callable to execute when the item is clicked
• hotkey – the key mapping to map the menu item to
• flags – any extra flags to pass to idaapi.add_menu_item
• args – any parameters to pass to the callable

menu.reset()

Remove all currently registered menu items.

menu.rm(path, name)

Remove the menu item at the specified path with the provided name.

Parameters:

• path – the menu path containing the item to remove
• name – the name of the item to remove

3.2.1.1.18. ui.message

This namespace is for displaying a modal dialog box with the different icons that are available from IDA’s user interface. The functions within will block IDA from being interacted with while their dialog is displayed.

ui.message(message, **icon)

Display a modal information dialog box using the provided message.

Parameters:

• message – the message to display in the dialog box
• **icon – a boolean specifying the icon to include in the dialog which can be either information or warning

message.error(message)

Display a modal error dialog box using the provided message.

Parameters:message – the message to display in the dialog box

message.information(message)

Display a modal information dialog box using the provided message.

Aliases: ui.message.info

Parameters:message – the message to display in the dialog box

message.warning(message)

Display a modal warning dialog box using the provided message.

Aliases: ui.message.warn

Parameters:message – the message to display in the dialog box

3.2.1.1.19. ui.modules

This namespace is for interacting with the Modules window.

Bases: ui.appwindow

3.2.1.1.20. ui.mouse

Base namespace for interacting with the mouse input.

mouse.buttons()

Return the current mouse buttons that are being clicked.

mouse.position()

Return the current (x, y) position of the cursor.

3.2.1.1.21. ui.names

This namespace is for interacting with the Names window.

Bases: ui.appwindow

names.at(index)

Return the address and the symbol name of the specified index.

Parameters:index – the index in the list to return

names.contains(ea)

Return whether the address ea is referenced in the names list.

Parameters:ea – the address of the symbol to check

names.ea(index)

Return the address at the specified index.

Parameters:index – the index in the list to return

names.iterate()

Iterate through all of the address and symbols in the names list.

names.name(index)

Return the name at the specified index.

Parameters:index – the index in the list to return

names.refresh()

Refresh the names list.

names.search(ea)

Return the index of the address ea in the names list.

Parameters:ea – the address of the symbol to return the index for

names.size()

Return the number of elements in the names list.

3.2.1.1.22. ui.navigation

This namespace is for updating the state of the colored navigation band.

navigation.analyze(ea)

Parameters:ea – the address to set the auto-analysis analyze address to on the navigation bar

navigation.auto(ea, **type)

Set the auto-analysis address and type on the navigation bar to ea.

If type is specified, then update using the specified auto-analysis type.

Parameters:

• ea – the address to set the auto-analysis address to on the navigation bar
• **type – if type is specified as an idaapi.AU_*, then use this as the navigation type

navigation.code(ea)

Parameters:ea – the address to set the auto-analysis code address to on the navigation bar

navigation.final(ea)

Parameters:ea – the address to set the auto-analysis final address to on the navigation bar

navigation.procedure(ea)

Parameters:ea – the address to set the auto-analysis procedure address to on the navigation bar

navigation.set(ea)

Set the auto-analysis address on the navigation bar to ea.

Parameters:ea – the address to set the navigation bar pointer to

navigation.signature(ea)

Parameters:ea – the address to set the auto-analysis signature address to on the navigation bar

navigation.stackpointer(ea)

Parameters:ea – the address to set the auto-analysis stackpointer address to on the navigation bar

navigation.tail(ea)

Parameters:ea – the address to set the auto-analysis tail address to on the navigation bar

navigation.type(ea)

Parameters:ea – the address to set the auto-analysis type address to on the navigation bar

navigation.unknown(ea)

Parameters:ea – the address to set the auto-analysis unknown address to on the navigation bar

navigation.weak(ea)

Parameters:ea – the address to set the auto-analysis weak address to on the navigation bar

3.2.1.1.23. ui.notepad

This namespace is for interacting with the Notepad window.

Bases: ui.appwindow

notepad.append(string)

Append the provided string to the current text that is stored within the notepad window.

Parameters:string – the text to append to the contents of the notepad window

notepad.close()

Close or hide the notepad window.

notepad.count()

Return the number of lines that are currently stored within the notepad window.

notepad.cursor()

Return the QtGui.QTextCursor used by the notepad window.

notepad.cursor(cursor)

Set the QtGui.QTextCursor for the notepad window to cursor.

Parameters:cursor – the QtGui.QTextCursor to assign to the notepad window

notepad.get()

Return the string that is currently stored within the notepad window.

notepad.open(*args)

Open or show the notepad window and return its UI widget that can be used to modify it.

Parameters:*args –

notepad.set(string)

Set the text that is currently stored within the notepad window to string.

Parameters:string – the string to assign to the contents of the notepad window

notepad.set(items)

Set each line that is currently stored within the notepad window to items.

Parameters:items – the list to assign to each row of the notepad window

notepad.size()

Return the number of characters that are currently stored within the notepad window.

3.2.1.1.24. ui.problems

This namespace is for interacting with the Problems window.

Bases: ui.appwindow

3.2.1.1.25. ui.references

This namespace is for interacting with the Cross-References window.

Bases: ui.appwindow

3.2.1.1.26. ui.segmentregisters

This namespace is for interacting with the Segments window.

Bases: ui.appwindow

3.2.1.1.27. ui.segments

This namespace is for interacting with the Segments window.

Bases: ui.appwindow

3.2.1.1.28. ui.selectors

This namespace is for interacting with the Selectors window.

Bases: ui.appwindow

3.2.1.1.29. ui.signatures

This namespace is for interacting with the Signatures window.

Bases: ui.appwindow

3.2.1.1.30. ui.stack

This namespace is for interacting with the (Call) Stack window.

Bases: ui.appwindow

3.2.1.1.31. ui.state

This namespace is for fetching or interacting with the current state of IDA’s interface. These are things such as waiting for IDA’s analysis queue, or determining whether the function is being viewed in graph view or not.

state.graphview()

Returns true if the current function is being viewed in graph view mode.

state.wait()

Wait until IDA’s autoanalysis queues are empty.

Aliases: ui.wait

3.2.1.1.32. ui.strings

This namespace is for interacting with the Strings window.

Bases: ui.appwindow

strings.at(index)

Return the idaapi.string_info_t for the specified index in the strings list.

Parameters:index – the index of the string item to return

strings.get(index)

Return the address and its bytes representing the string at the specified index.

Parameters:index – the index of the string to return

strings.iterate()

Iterate through all of the addresses and items in the strings list.

strings.refresh()

Refresh the strings list.

strings.size()

Return the number of items available in the strings list.

3.2.1.1.33. ui.structures

This namespace is for interacting with the Structures window.

Bases: ui.appwindow

3.2.1.1.34. ui.threads

This namespace is for interacting with the Threads window.

Bases: ui.appwindow

3.2.1.1.35. ui.timer

This namespace is for registering a python callable to a timer in IDA.

timer.register(id, interval, callable)

Register the specified callable with the requested id to be called at every interval.

Parameters:

• id – a unique id used to refer to the callable being registered in the timer
• interval – what interval to execute the callable at
• callable – a python callable to execute when the timer ticks

timer.reset()

Remove all the registered timers.

timer.unregister(id)

Unregister the specified id.

Parameters:id – the unique id of the callable to unregister

3.2.1.1.36. ui.tracing

This namespace is for interacting with the Tracing window.

Bases: ui.appwindow

3.2.1.1.37. ui.types

This namespace is for interacting with the Types window.

Bases: ui.appwindow

3.2.1.1.38. ui.widget

This namespace is for interacting with any of the widgets associated with the native user-interface.

ui.widget()

Return the widget that is currently being used.

ui.widget(xy)

Return the widget at the specified (x, y) coordinate within the xy tuple.

Parameters:xy – a tuple composed of the X and Y coordinates of a widget

ui.widget(title)

Return the widget that is using the specified title.

Parameters:title – a string containing the widget title

widget.at(xy)

Return the widget at the specified (x, y) coordinate within the xy tuple.

Parameters:xy – a tuple composed of the X and Y coordinates of a widget

widget.by(title)

Return the widget associated with the given window title.

Parameters:title – the title of the desired widget to return

widget.close(widget, flags)

Close the widget using the specified idaapi.WCLS_ flags.

Parameters:

• widget – the widget to close
• flags – the specified flags to use when closing the widget

widget.focus(widget)

Activate the specified widget and put it in focus.

Parameters:widget – the widget to put into focus

widget.form(widget)

Return the IDA form for the UI widget that is provided.

Parameters:widget – the user-interface widget to convert to an IDA plugin form

widget.isinstance(object)

Return whether the given object is of the correct type for the UI.

Parameters:object – the object to check the instance of

widget.of(form)

Return the UI widget for the IDA form that is provided.

Parameters:form – the IDA plugin form to convert to a user-interface widget

widget.open(widget, flags, **target)

Open the widget using the specified idaapi.WOPN_ flags.

Parameters:

• widget – the widget to open
• flags – the specified flags to use when opening the widget
• **target –

widget.show(widget)

Display the specified widget without putting it in focus.

Parameters:widget – the widget to show

widget.title(widget)

Return the window title for the given widget.

Parameters:widget – the widget to return the title from

widget.type(widget)

Return the idaapi.twidget_type_t for the given widget.

Parameters:widget – the widget to return the type of

3.2.1.1.39. ui.window

This namespace is for interacting with a specific window.

ui.window()

Return the currently active window.

window.at(cls, xy)

Return the widget at the specified (x, y) coordinate within the xy tuple.

Parameters:

• cls –
• xy – a tuple composed of the X and Y coordinates of a window

3.2.1.1.40. ui.windows

This namespace is for interacting with any or all of the windows for the application.

ui.windows()

Return all of the top-level windows.

windows.refresh()

Refresh all of lists and choosers within the application.

Aliases: ui.refresh

3.2.1.2. Class list

Classes provide the definition necessary to instantiate an object. In most cases, a class is returned when calling one of the prior listed functions and thus have no need to be manually instantiated. Classes may also have aliases defined for them. Please refer to the documentation for the class to see what is available. For more information on aliases, please see Aliases.

3.2.1.2.1. ConsoleProgress

class ui.ConsoleProgress

Helper class used to simplify the showing of a progress bar in IDA’s console.

close(self)

Close the current progress bar.

open(self, width=0.8, height=0.1)

Open a progress bar with the specified width and height relative to the dimensions of IDA’s window.

Parameters:

• width – the percentage of IDA’s dimensions to set the width to
• height – the percentange of IDA’s dimensions to set the height to

update(self, **options)

Update the current state of the progress bar.

Parameters:**options –

The options to update the progress bar with. Some of these options are:

• minimum - the minimum value on the progress bar
• maximum - the maximum value on the progress bar
• text - the current text to display
• title - the title of the progress bar
• tooltip - what to emit when the user hovers over the progress bar

3.2.1.2.2. InputBox

class ui.InputBox

Bases: idaapi.PluginForm

A class designed to be inherited from that can be used to interact with the user.

OnClose(self, form)

A method to overload to be notified when the plugin form is destroyed.

Parameters:form – an idaapi.PluginForm that is created

OnCreate(self, form)

A method to overload to be notified when the plugin form is created.

Parameters:form – an idaapi.PluginForm that is created

Show(self, caption, options=0)

Show the form with the specified caption and options.

Parameters:

• caption – the title of the form to show
• options – any flags to show the form with

3.2.1.2.3. Progress

class ui.Progress

The default progress bar in with which to show progress. This class will automatically determine which progress bar (Console or UI) to instantiate based on what is presently available.

__new__(cls, *args, **kwargs)

Figure out which progress bar to use and instantiate it with the provided parameters args and kwargs.

Parameters:

• *args – any variable arguments to pass to the determined progress bar
• **kwargs – any keyword arguments to pass to the determined progress bar

3.2.1.2.4. UIProgress

class ui.UIProgress

Helper class used to simplify the showing of a progress bar in IDA’s UI.

canceled

Parameters:

• getter –
• setter –
• set –

close(self)

Close the current progress bar.

open(self, width=0.8, height=0.1)

Open a progress bar with the specified width and height relative to the dimensions of IDA’s window.

Parameters:

• width – the percentage of IDA’s dimensions to set the width to
• height – the percentange of IDA’s dimensions to set the height to

update(self, **options)

Update the current state of the progress bar.

Parameters:**options –

The options to update the progress bar with. Some of these options are:

• minimum - the minimum value on the progress bar
• maximum - the maximum value on the progress bar
• text - the current text to display
• title - the title of the progress bar
• tooltip - what to emit when the user hovers over the progress bar