Documentation for the main executable file (DDRescue_GUI.py)

This is the main script that you use to start DDRescue-GUI.

class ddrescue_gui.DDRescue_GUI.BackendThread(parent)

Handles getting input from ddrescue during a recovery, and forwards it back to the GUI thread as required.

process_line(line)

Process a given line to get ddrescue’s current status and recovery information and send it to the GUI Thread

run()

Main body of the thread, started with self.start().

class ddrescue_gui.DDRescue_GUI.CustomTextCtrl(parent, wx_id, value, style)

A custom wx.TextCtrl that provides features that are broken on Linux and Cygwin.

Features:

A version of XYToPosition() that fixes a bug on Linux and Cygwin. carriage_return(): Handles carriage returns correctly. up_one_line(): Moves insertion point up one line.

XYToPosition(column, row)

A custom version of wx.TextCtrl.XYToPosition() that fixes a bug on Linux and Cygwin.

Args:

column (int). The column we want to get the integer

position for.

row (int). The row we want to get the integer

position for.

Returns:

int. The position.

Note

This is required on Linux/Cygwin because the built-in one has a quirk: when you’re at the end of the text, it always returns -1.

add_line(data, crs, uols, char_number)

Adds a new line to the custom output box. Also handles calling carriage_return() and up_one_line() when required. Receives the data chunks and other information from the update method.

Args:

data (string). The chunk of text to add to the

output box.

crs (list). A list of character numbers where

the character is a carriage return.

uols (list). As above, for up-one-line

sequences.

char_number (int). The character number we are at in

the line (the character after the last character in our chunk of text).

carriage_return()

Handles carriage returns in output. This is done by going back to the last newline in the box - any new text will now overwrite what is there.

up_one_line()

Handles (control sequence to go up one line) in the output. This is done by moving the insertion point so we are up one line, but in the same column (if possible).

update(line)

Append the given line to the contents of the output box. Counts carriage returns and up-one-lines so that an auxiliary method (add_line) can handle them.

Args:

line (string). The line to add.

class ddrescue_gui.DDRescue_GUI.DiskInfoWindow(parent)

DDRescue-GUI’s disk information window.

bind_events()

Bind all events for DiskInfoWindow

create_widgets()

Create all widgets for DiskInfoWindow

get_diskinfo(event=None)

Call the thread to get Disk info, disable the refresh button, and start the throbber

on_exit(event=None)

Exit DiskInfoWindow

on_size(event=None)

Auto resize the list_ctrl columns

receive_diskinfo(info)

Get Disk data, call self.update_list_ctrl(), and then call MainWindow().update_file_choices() to refresh the file choices with the new info.

Args:

info (dict). The new disk information.

setup_sizers()

Set up the sizers for DiskInfoWindow

update_list_ctrl(event=None)

Update the list control

class ddrescue_gui.DDRescue_GUI.ElapsedTimeThread(parent)

Keeps track of elapsed time during a recovery. A separate thread is used for this because wx.Timer wasn’t working on macOS, and the BackendThread blocks if ddrescue pauses.

run()

Main body of the thread, started with self.start().

class ddrescue_gui.DDRescue_GUI.FinishedWindow(parent, disk_capacity, recovered_data)

This is displayed after a recovery is finished/aborted. Used to provide the user w/ options to restart the GUI, mount the output file, or close the GUI.

bind_events()

Bind all events for FinishedWindow.

create_buttons()

Create all buttons for FinishedWindow.

create_text()

Create all text for FinishedWindow.

on_browse(event=None)

Open the file viewer and browse the mounted volume.

on_exit(event=None)

Close FinishedWindow and trigger closure of MainWindow.

on_mount(event=None)

Triggered when mount button is pressed, used to initiate mounting the output file/device.

restart(event=None)

Close FinishedWindow and call MainWindow().restart() to re-display and reset MainWindow.

setup_sizers()

Set up all sizers for FinishedWindow.

class ddrescue_gui.DDRescue_GUI.GetDiskInformation(parent)

Used to get disk information without blocking the GUI thread. Calls parent.receive_diskinfo when info has ben retrieved.

get_info()

Get disk information as a privileged user.

Returns:

dict.

If successful: The disk information. If unsuccessful: An empty dictionary.

run()

Use GetDevInfo module to get disk information.

class ddrescue_gui.DDRescue_GUI.MainWindow

DDRescue-GUI’s main window.

bind_events()

Bind all events for MainWindow

check_for_updates(event=None, starting_up=False)

Check for updates using the plist-formatted update file on my website. If on startup, only display info to the user if there was an update. Otherwise (aka requested by user), always display the information.

Args:

starting_up[=True] (boolean). If the GUI is starting up, specify

True, otherwise leave unspecified.

create_buttons()

Create all buttons for MainWindow

create_choice_boxes()

Create all choiceboxes for MainWindow

create_menus()

Create the menus

create_other_widgets()

Create all other widgets for MainWindow

create_text()

Create all text for MainWindow

define_vars()

Defines some variables used elsewhere in this class/instance.

file_choice_handler(_type, user_selection, default_dir, wildcard, style)

Handle file dialogs for set_input_file, set_output_file, and set_map_file.

Args:

_type (string). The type of file we’re handling. “Input”,

“Output”, or “Map”.

user_selection (string): The option the user selected in the

choice box.

default_dir (string): The default directory any file dialogs

are to use.

wildcard (string): The wildcard that any file dialogs

are to use.

style (int): The style that any file dialogs are

to use.

focus_on_control_button(event=None)

Focus on the control button instead of the TextCtrl, and reset the insertion point back after 30 milliseconds, preventing the user from changing the insertion point and messing the formatting up.

get_confirm_text()

Generate recovery confirmation text to make doubly sure the right devices are selected. This can be logged and put in a message dialog.

Returns:

String. The confirmation text.

get_diskinfo(event=None)

Call the thread to get Disk info, disable the update button, and start the throbber

handle_no_mapfile(key, choice_box)

Handles when the user selects not to have a mapfile.

Args:

key (string): The unique key used to identify the output file. choice_box (wx.Choice): The output choice box.

handle_outputfile_special_cases(key, choice_box)

Handles special cases for the output choice box.

Args:

key (string): The unique key used to identify the output file. choice_box (wx.Choice): The output choice box.

handle_user_file_selection(_type, key, user_selection, paths, choice_box)

Handles user file selection for the main settings choiceboxes.

Args:

_type (string): The type of file we’re setting (Input, Output, or Map). key (string): The unique key used to identify the output file. user_selection (string): The user’s selected path/file. paths (dict): The custom paths defined for this type of file. choice_box (wx.Choice): The output choice box.

make_status_bar()

Create and set up a statusbar

on_abort()

Abort the recovery.

on_about(event=None)

Show the about box.

on_control_button(event=None)

Handle events from the control button, as its purpose changes during and after recovery. Call self.on_abort() when clicked during a recovery. Call self.on_start() otherwise.

on_detailed_info(event=None)

Show/Hide the detailed info, and rotate the arrow next to the text label.

on_exit(event=None, just_finished_recovery=False)

Exit DDRescue-GUI, if certain conditions are met (for example we aren’t in the middle of a recovery). Also offer to save the log file for debugging / error-reporting purposes.

Args:

just_finished_recovery (bool).

True - Display FinishedWindow if user cancels

the exit attempt.

False - The default, do nothing if user cancels

the exit attempt.

on_mount(event=None)

When the user asks to mount a file, handle this and show FinishedWindow in order to carry out the request.

on_recovery_ended(result, disk_capacity, recovered_data, return_code=None)

Called by the backend thread to show FinishedWindow and update the main window when a recovery is completed or aborted by the user, or when a recovery errors out for some reason.

Args:

result (string). The reason why the recovery ended. Used to

let the user know what is happening. Values are “NoInitialStatus”, “BadReturnCode”, and “Success”.

disk_capacity (string). The capacity of the input file or disk. recovered_data (string). The amount of data we recovered.

return_code[=None] (int). GNU ddrescue’s return code. Useful if

the recovery failed for some reason.

on_session_end(event)

Attempt to veto e.g. a shutdown/logout event if recovering data.

on_size(event=None)

Auto resize the list_ctrl columns when the window is resized.

on_start()

Check the settings, prepare to start ddrescue, unmount the input file if needed, and start the backend thread.

on_terminal_output(event=None)

Show/Hide the terminal output, and rotate the arrow next to the text label.

prompt_to_kill_ddrescue()

Prompts the user to try killing ddrescue again if it’s not exiting. This sometimes happens if the system is overloaded, or if a disk is taking a very long time to timeout/fail a read operation.

receive_diskinfo(info)

Get new Disk info, stop the throbber and call the function that updates the choiceboxes for input and output file selection.

restart()

Restart and reset MainWindow, so MainWindow is as it was when DDRescue-GUI was started.

save_debug_log(event=None)

Save DDRescue-GUI’s debug log.

set_input_file(event=None)

Get the input file/Disk by calling self.file_choice_handler.

set_map_file(event=None)

Get the map file position/name by calling self.file_choice_handler.

set_output_file(event=None)

Get the output file/Disk by calling self.file_choice_handler.

set_progress_bar_range(_range)

Set the progress bar’s range.

Args:

_range (int). The range to set the progress bar to use.

set_vars()

Set some essential variables

setup_sizers()

Setup sizers for MainWindow

show_dev_info(event=None)

Show the Disk Information Window.

show_inspector(event)

Shows the wxPython inspection tool.

show_privacy_policy(event=None)

Show the Privacy Policy Window

show_settings(event=None)

Show the settings Window, but only if input and output files have already been selected.

show_userguide(event=None)

Open a web browser and show the user guide.

update_average_read_rate(average_read_rate)

Update the average read rate info.

Args:

average_read_rate (string). The average read rate.

update_current_read_rate(current_read_rate)

Update the current read rate info.

Args:

current_rate_rate (string). The current read rate.

update_error_size(error_size)

Update the error size info.

Args:

error_size (string). The amount of unreadable data so far.

update_file_choices()

Update the disk entries in the choiceboxes

update_input_pos(input_pos)

Update the input position info.

Args:

input_pos (string). The current position in the input file

or device.

update_num_errors(num_errors)

Update the num errors info.

Args:

num_errors (string). The number of read errors so far.

update_output_pos(output_pos)

Update the output position info.

Args:

output_pos (string). The current position in the output file

or device.

update_progress(recovered_data, disk_capacity)

Update the progress bar and the title. Do nothing if disk capacity is unknown.

Args:

recovered_data (int). The amount of data currently recovered

(units vary based on disk size).

disk_capacity (int). The capacity (or size) of the input

file or disk.

update_recovered_data(recovered_data)

Update the recovered data info.

Args:

recovered_data (string). The amount of data recovered so far.

update_status_bar(message)

Update the status bar with a new message.

Args:

message (string). The message to set the status bar to.

update_time_elapsed(time_elapsed)

Update the time elapsed text.

Args:

time_elapsed (string). The label to use for the time elapsed

text.

update_time_remaining(time_left)

Update the time remaining text.

Args:

time_remaining (string). The label to use for the time remaining

text.

update_time_since_last_read(last_read)

Update the time since last successful read info.

Args:

last_read (string). The amount of time that has passed since

ddrescue successfully read any data from the input file.

class ddrescue_gui.DDRescue_GUI.MyApp(redirect=False, filename=None, useBestVisual=False, clearSigInt=True)

The wxPython app. Must be declared for application to work. This is how the application is started.

MacReopenApp()

Called when the doc icon is clicked, shows the top-level window again even if it’s minimised. Makes the GUI work in a more intuitive way on macOS.

OnInit()

Used to show the splash screen, which then starts the rest of the application.

class ddrescue_gui.DDRescue_GUI.PrivPolWindow(parent)

DDRescue-GUI’s privacy policy window.

bind_events()

Bind events so we can close this window.

create_widgets()

Create all widgets for PrivPolWindow

on_close(event=None)

Close PrivPolWindow.

setup_sizers()

Set up sizers for PrivPolWindow

class ddrescue_gui.DDRescue_GUI.SettingsWindow(parent)

DDRescue-GUI’s settings window

bind_events()

Bind all events for SettingsWindow.

create_buttons()

Create all buttons for SettingsWindow

create_check_boxes()

Create all CheckBoxes for SettingsWindow, and set their default states (all unchecked)

create_choice_boxes()

Create all ChoiceBoxes for SettingsWindow, and call self.set_default_recovery_settings()

create_text()

Create all text for SettingsWindow

save_options(event=None)

Save all options, and exit SettingsWindow.

set_best_recovery_settings(event=None)

Set selections for the Choiceboxes to best recovery settings.

set_default_recovery_settings(event=None)

Set selections for the Choiceboxes to default settings.

set_fast_recovery_settings(event=None)

Set selections for the Choiceboxes to fast recovery settings.

set_soft_run(event=None)

Set up SettingsWindow based on the value of self.no_split_check_box (the “do soft run” CheckBox).

setup_options()

Set all options in the window so we remember them if the user checks back

setup_sizers()

Set up all sizers for SettingsWindow.

class ddrescue_gui.DDRescue_GUI.ShowSplash(parent=None)

A simple class used to display the splash screen on startup. After that, it starts the rest of the application.

on_exit(event=None)

Close the splash screen and start MainWindow.

Args:

event[=None] (object). The event object passed by

wxPython when the splash times out.

ddrescue_gui.DDRescue_GUI.usage()

Outputs information on cmdline options for the user.