13.2. GUI Support
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.2. GUI Support

### 13.2.1. ProgDlg

Creates and manages a modal progress bar. This is intended to be used with coroutines, where a main UI thread controls the progress bar dialog while a background coroutine (worker thread) yields to the main thread between steps. The main thread checks the status of the Cancel button and if it’s not set, returns control to the coroutine.

Figure 13.1. A progress bar in action

The legacy (GTK+) user interface displayed this as a separate dialog, hence the “Dlg” suffix. The Qt user interface shows a progress bar inside the main status bar.

#### 13.2.1.1. ProgDlg.new([title], [task])

Creates and displays a new `ProgDlg` progress bar with a Cancel button and optional title. It is highly recommended that you wrap code that uses a `ProgDlg` instance because it does not automatically close itself upon encountering an error. Requires a GUI.

#### 13.2.1.2. Example

        if not gui_enabled() then return end

        local p = ProgDlg.new("Constructing", "tacos")

        -- We have to wrap the ProgDlg code in a pcall in case some unexpected
        -- error occurs.
        local ok, errmsg = pcall(function()
                local co = coroutine.create(
                        function()
                                local limit = 100000
                                for i=1,limit do
                                        print("co", i)
                                        coroutine.yield(i/limit, "step "..i.." of "..limit)
                                end
                        end
                )

                -- Whenever coroutine yields, check the status of the cancel button to determine
                -- when to break. Wait up to 20 sec for coroutine to finish.
                local start_time = os.time()
                while coroutine.status(co) ~= 'dead' do
                        local elapsed = os.time() - start_time

                        -- Quit if cancel button pressed or 20 seconds elapsed
                        if p:stopped() or elapsed > 20 then
                                break
                        end

                        local res, val, val2 = coroutine.resume(co)
                        if not res or res == false then
                                if val then
                                        debug(val)
                                end
                                print('coroutine error')
                                break
                        end

                        -- show progress in progress dialog
                        p:update(val, val2)
                end
        end)

        p:close()

        if not ok and errmsg then
                report_failure(errmsg)
        end

##### Arguments

title (optional)
  Title of the progress bar. Defaults to "Progress".

task (optional)
  Optional task name, which will be appended to the title. Defaults to the empty string ("").

##### Returns

The newly created `ProgDlg` object.

#### 13.2.1.3. progdlg:update(progress, [task])

Sets the progress dialog’s progress bar position based on percentage done.

##### Arguments

progress
  Progress value, e.g. 0.75. Value must be between 0.0 and 1.0 inclusive.

task (optional)
  Task name. Currently ignored. Defaults to empty string ("").

##### Errors

- GUI not available
- Cannot be called for something not a ProgDlg
- Progress value out of range (must be between 0.0 and 1.0)

#### 13.2.1.4. progdlg:stopped()

Checks whether the user has pressed the Cancel button.

##### Returns

Boolean `true` if the user has asked to stop the operation, `false` otherwise.

#### 13.2.1.5. progdlg:close()

Hides the progress bar.

##### Returns

A short label identifying the dialog.

##### Errors

- GUI not available

### 13.2.2. TextWindow

Creates and manages a text window. The text can be read-only or editable, and buttons can be added below the text.

Figure 13.2. A text window in action

#### 13.2.2.1. TextWindow.new([title])

Creates a new `TextWindow` text window and displays it. Requires a GUI.

#### 13.2.2.2. Example

        if not gui_enabled() then return end

        -- create new text window and initialize its text
        local win = TextWindow.new("Log")
        win:set("Hello world!")

        -- add buttons to clear text window and to enable editing
        win:add_button("Clear", function() win:clear() end)
        win:add_button("Enable edit", function() win:set_editable(true) end)

        -- add button to change text to uppercase
        win:add_button("Uppercase", function()
                local text = win:get_text()
                if text ~= "" then
                        win:set(string.upper(text))
                end
        end)

        -- print "closing" to stdout when the user closes the text window
        win:set_atclose(function() print("closing") end)

##### Arguments

title (optional)
  Title of the new window. Optional. Defaults to "Untitled Window".

##### Returns

The newly created `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.3. textwindow:set_atclose(action)

Set the function that will be called when the text window closes.

##### Arguments

action
  A Lua function to be executed when the user closes the text window.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.4. textwindow:set(text)

Sets the text to be displayed.

##### Arguments

text
  The text to be displayed.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.5. textwindow:append(text)

Appends text to the current window contents.

##### Arguments

text
  The text to be appended.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.6. textwindow:prepend(text)

Prepends text to the current window contents.

##### Arguments

text
  The text to be prepended.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.7. textwindow:clear()

Erases all of the text in the window.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.8. textwindow:get_text()

Get the text of the window.

##### Returns

The `TextWindow`'s text.

##### Errors

- GUI not available

#### 13.2.2.9. textwindow:close()

Close the window.

##### Errors

- GUI not available

#### 13.2.2.10. textwindow:set_editable([editable])

Make this text window editable.

##### Arguments

editable (optional)
  `true` to make the text editable, `false` otherwise. Defaults to `true`.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

#### 13.2.2.11. textwindow:add_button(label, function)

Adds a button with an action handler to the text window.

##### Arguments

label
  The button label.

function
  The Lua function to be called when the button is pressed.

##### Returns

The `TextWindow` object.

##### Errors

- GUI not available

### 13.2.3. Global Functions

#### 13.2.3.1. gui_enabled()

Checks if we’re running inside a GUI (i.e. Wireshark) or not.

##### Returns

Boolean `true` if a GUI is available, `false` if it isn’t.

#### 13.2.3.2. register_menu(name, action, [group])

Register a menu item in one of the main menus. Requires a GUI.

##### Arguments

name
  The name of the menu item. Use slashes to separate submenus. (e.g. Lua Scripts → My Fancy Statistics). (string)

action
  The function to be called when the menu item is invoked. The function must take no arguments and return nothing.

group (optional)

  Where to place the item in the menu hierarchy. If omitted, defaults to MENU_STAT_GENERIC. Valid packet (Wireshark) items are:

  - MENU_PACKET_ANALYZE_UNSORTED: Analyze
  - MENU_PACKET_STAT_UNSORTED: Statistics
  - MENU_STAT_GENERIC: Statistics, first section
  - MENU_STAT_RESPONSE_TIME: Statistics → Service Response Time
  - MENU_STAT_RSERPOOL: Statistics → Reliable Server Pooling (RSerPool)
  - MENU_TELEPHONY_UNSORTED: Telephony
  - MENU_TELEPHONY_ANSI: Telephony → ANSI
  - MENU_TELEPHONY_GSM: Telephony → GSM
  - MENU_TELEPHONY_3GPP_UU: Telephony → 3GPP Uu
  - MENU_TELEPHONY_MTP3: Telephony → MTP3
  - MENU_TELEPHONY_SCTP: Telephony → SCTP
  - MENU_TOOLS_UNSORTED: Tools

Valid log (Stratoshark) items are:

- MENU_LOG_ANALYZE_UNSORTED: Analyze
- MENU_LOG_STAT_UNSORTED: Statistics

The following are deprecated and shouldn’t be used in new code:

- MENU_ANALYZE_CONVERSATION_FILTER, Analyze → Conversation Filter registration is not yet supported in Lua
- MENU_STAT_CONVERSATION_LIST, Statistics → Conversations registration is not yet supported in Lua
- MENU_STAT_ENDPOINT_LIST, Statistics → Endpoints registration is not yet supported in Lua
- MENU_ANALYZE_UNSORTED, superseded by MENU_PACKET_ANALYZE_UNSORTED
- MENU_ANALYZE_CONVERSATION, superseded by MENU_ANALYZE_CONVERSATION_FILTER
- MENU_STAT_CONVERSATION, superseded by MENU_STAT_CONVERSATION_LIST
- MENU_STAT_ENDPOINT, superseded by MENU_STAT_ENDPOINT_LIST
- MENU_STAT_RESPONSE, superseded by MENU_STAT_RESPONSE_TIME
- MENU_STAT_UNSORTED, superseded by MENU_PACKET_STAT_UNSORTED
- MENU_STAT_TELEPHONY, superseded by MENU_TELEPHONY_UNSORTED
- MENU_STAT_TELEPHONY_ANSI, superseded by MENU_TELEPHONY_ANSI
- MENU_STAT_TELEPHONY_GSM, superseded by MENU_TELEPHONY_GSM
- MENU_STAT_TELEPHONY_3GPP_UU, superseded by MENU_TELEPHONY_3GPP_UU
- MENU_STAT_TELEPHONY_MTP3, superseded by MENU_TELEPHONY_MTP3
- MENU_STAT_TELEPHONY_SCTP, superseded by MENU_TELEPHONY_SCTP

#### 13.2.3.3. register_packet_menu(name, action, [required_fields])

Register a menu item in the packet list.

##### Arguments

name
  The name of the menu item. Use slashes to separate submenus. (e.g. level1/level2/name). (string)

action
  The function to be called when the menu item is invoked. The function must take a variable number of arguments and return nothing. The arguments will be FieldInfo objects, one for each field present in the selected packet.

required_fields (optional)
  A comma-separated list of packet fields (e.g., http.host,dns.qry.name) which all must be present for the menu to be displayed. If omitted, the packet menu will be displayed for all packets.

#### 13.2.3.4. new_dialog(title, action, …​)

Displays a dialog, prompting for input. The dialog includes an OK button and Cancel button. Requires a GUI.

Figure 13.3. An input dialog in action

#### 13.2.3.5. Example

        if not gui_enabled() then return end

        -- Prompt for IP and port and then print them to stdout
        local label_ip = "IP address"
        local label_port = "Port"
        local function print_ip(ip, port)
                print(label_ip, ip)
                print(label_port, port)
        end
        new_dialog("Enter IP address", print_ip, label_ip, label_port)

        -- Prompt for 4 numbers and then print their product to stdout
        new_dialog(
                "Enter 4 numbers",
                function (a, b, c, d) print(a * b * c * d) end,
                "a", "b", "c", "d"
                )

##### Arguments

title
  The title of the dialog.

action
  Action to be performed when the user presses OK.

…​
  Strings to be used as labels of the dialog’s fields. Each string creates a new labeled field. The first field is required. Instead of a string it is possible to provide tables with fields 'name' and 'value' of type string. Then the created dialog’s field will be labeled with the content of name and prefilled with the content of value.

##### Errors

- GUI not available
- At least one field required

#### 13.2.3.6. retap_packets()

Rescans all packets and runs each tap listener without reconstructing the display.

#### 13.2.3.7. copy_to_clipboard(text)

Copy a string into the clipboard. Requires a GUI.

##### Arguments

text
  The string to be copied into the clipboard.

#### 13.2.3.8. open_capture_file(filename, filter)

Open and display a capture file. Requires a GUI.

##### Arguments

filename
  The name of the file to be opened.

filter
  The display filter to be applied once the file is opened.

#### 13.2.3.9. get_filter()

Get the display filter from the filter toolbar. This may not be the currently active display filter.

##### Returns

The display filter string in the filter toolbar.

##### Errors

- GUI not available

#### 13.2.3.10. set_filter(text)

Set (Prepare) the display filter in the filter toolbar.

##### Arguments

text
  The filter’s text.

##### Errors

- GUI not available

#### 13.2.3.11. apply_filter()

Apply the display filter in the filter toolbar. Requires a GUI.

| Warning
Avoid calling this from within a dissector function or else an infinite loop can occur if it causes the dissector to be called again. This function is best used in a button callback (from a dialog or text window) or menu callback.

##### Errors

- GUI not available

#### 13.2.3.12. get_color_filter_slot(row)

Gets the current packet coloring rule (by index) for the current session. Wireshark reserves 10 slots for these coloring rules. Requires a GUI.

##### Arguments

row
  The index (1-10) of the desired color filter value in the temporary coloring rules list.

Table 13.1. Default background colors

Index | RGB (hex) | Color
--- | --- | ---
1 | ffc0c0 | pink 1
2 | ffc0ff | pink 2
3 | e0c0e0 | purple 1
4 | c0c0ff | purple 2
5 | c0e0e0 | green 1
6 | c0ffff | green 2
7 | c0ffc0 | green 3
8 | ffffc0 | yellow 1
9 | e0e0c0 | yellow 2
10 | e0e0e0 | gray

#### 13.2.3.13. set_color_filter_slot(row, text)

Sets a packet coloring rule (by index) for the current session. Wireshark reserves 10 slots for these coloring rules. Requires a GUI.

##### Arguments

row
  The index (1-10) of the desired color in the temporary coloring rules list. The default foreground is black and the default backgrounds are listed below.

Table 13.2. Default background colors

Index | RGB (hex) | Color
--- | --- | ---
1 | ffc0c0 | pink 1
2 | ffc0ff | pink 2
3 | e0c0e0 | purple 1
4 | c0c0ff | purple 2
5 | c0e0e0 | green 1
6 | c0ffff | green 2
7 | c0ffc0 | green 3
8 | ffffc0 | yellow 1
9 | e0e0c0 | yellow 2
10 | e0e0e0 | gray

The color list can be set from the command line using two unofficial preferences: `gui.colorized_frame.bg` and `gui.colorized_frame.fg`, which require 10 hex RGB codes (6 hex digits each), e.g.

    wireshark -o gui.colorized_frame.bg:${RGB0},${RGB1},${RGB2},${RGB3},${RGB4},${RGB5},${RGB6},${RGB7},${RGB8},${RGB9}

For example, this command yields the same results as the table above (and with all foregrounds set to black):

    wireshark -o gui.colorized_frame.bg:ffc0c0,ffc0ff,e0c0e0,c0c0ff,c0e0e0,c0ffff,c0ffc0,ffffc0,e0e0c0,e0e0e0 -o gui.colorized_frame.fg:000000,000000,000000,000000,000000,000000,000000,000000,000000,000000

text
  The display filter for selecting packets to be colorized .

#### 13.2.3.14. reload()

Reload the current capture file. Deprecated. Use reload_packets() instead.

#### 13.2.3.15. reload_packets()

Reload the current capture file. Requires a GUI.

| Warning
Avoid calling this from within a dissector function or else an infinite loop can occur if it causes the dissector to be called again. This function is best used in a button callback (from a dialog or text window) or menu callback.

#### 13.2.3.16. redissect_packets()

Redissect all packets in the current capture file. Requires a GUI.

| Warning
Avoid calling this from within a dissector function or else an infinite loop can occur if it causes the dissector to be called again. This function is best used in a button callback (from a dialog or text window) or menu callback.

#### 13.2.3.17. reload_lua_plugins()

Reload all Lua plugins.

#### 13.2.3.18. browser_open_url(url)

Opens an URL in a web browser. Requires a GUI.

| Warning
Do not pass an untrusted URL to this function. It will be passed to the system’s URL handler, which might execute malicious code, switch on your Bluetooth-connected foghorn, or any of a number of unexpected or harmful things.

##### Arguments

url
  The url.

#### 13.2.3.19. browser_open_data_file(filename)

Open a file located in the data directory (specified in the Wireshark preferences) in the web browser. If the file does not exist, the function silently ignores the request. Requires a GUI.

| Warning
Do not pass an untrusted URL to this function. It will be passed to the system’s URL handler, which might execute malicious code, switch on your Bluetooth-connected foghorn, or any of a number of unexpected or harmful things.

##### Arguments

filename
  The file name.

Prev | Up | Next
Chapter 13. Wireshark’s Lua API Reference Manual | Home | 13.3. Functions For New Protocols And Dissectors