natcap.invest.ui.inputs

Input classes for the InVEST UI, a Qt-based UI abstraction layer.

class natcap.invest.ui.inputs.Checkbox(label, helptext=None, interactive=True, args_key=None)

Bases: natcap.invest.ui.inputs.GriddedInput

An InVESTModelInput for boolean user input.

clear()

Clear the checkbox’s input by setting to unchecked.

Returns

None.

interactivity_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
set_value(value)

Set the value of the checkbox.

Parameters

value (bool) – The new check state of the checkbox. If True, the checkbox will be checked.

valid()

Check whether the checkbox’s input is valid.

Note

Unlike other inputs, the checkbox’s input is always valid.

Returns

Always returns True.

value()

Get the value of the checkbox.

Returns

A boolean, whether the checkbox is checked.

value_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
class natcap.invest.ui.inputs.Container(label, interactive=True, expandable=False, expanded=True, args_key=None)

Bases: MockQGroupBox, natcap.invest.ui.inputs.InVESTModelInput

An InVESTModelInput that contains other inputs within a QGridLayout.

add_input(input_obj)

Add an input to the Container.

The input must have an add_to method that handles how to add the InVESTModelInput and/or its component widgets to a QGridLayout that is owned by the Container.

Parameters

input_obj (InVESTModelInput) – An instance of Input to add to the Container’s layout.

Returns

None

add_to(layout)

Define how to add this Container to a QGridLayout.

The container will occupy all columns.

Parameters

layout (QGridLayout) – A QGridLayout to which this Container will be added.

Returns

None

clear()

Reset the container to unchecked if it is checkable.

If the container is not checkable, nothing is done.

Returns

None.

property expandable

Whether the container is expandable.

Returns

A boolean indicating whether the container is expandable.

property expanded

Whether the Container is expanded.

Returns

A boolean indicating whether the container is expanded.

interactivity_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
set_value(value)

Set the value of the Container.

This is the same as setting the value of self.expanded.

Parameters

value (bool) – The new expanded state of the Container.

showEvent(event)

Initialize hidden state of contained widgets when shown.

Reimplemented from QWidget.showEvent.

Parameters

event (QEvent) – The current QEvent. Ignored.

sufficiency_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
value()

Fetch the value of this container.

The value is the same as self.expanded.

Returns

A boolean, whether the Container is expanded.

value_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
class natcap.invest.ui.inputs.Dropdown(label, helptext=None, interactive=True, args_key=None, hideable=False, options=(), return_value_map=None)

Bases: natcap.invest.ui.inputs.GriddedInput

An InVESTModelInput for selecting one out of a set of defined options.

clear()

Reset the dropdown to a ‘blank’ state.

If the dropdown has options set, the menu will be reset to the item at index 0. If there are no options, validity and sufficiency is reset only.

Returns

None.

set_options(options, return_value_map=None)

Set the available options for this dropdown.

Parameters
  • options (iterable) – The new options for the dropdown.

  • return_value_map=None (dict or None) – If a dict, keys must exactly match the values of options. Values will be returned when the user selects the option indicated by the key. If None, the option selected by the user will be returned verbatim.

Returns

None

set_value(value)

Set the current index of the dropdown based on the value.

Parameters

value – The option to select in the dropdown. This value should match either a value in the options iterable set via Dropdown.set_options or the options parameter to Dropdown.__init__, or else must be the string text of the option.

Raises
  • ValueError – When the value provided cannot be found in either the

  • user-defined list of options or the list of options that has been

  • cast to a string.

Returns

None

value()

Get the text of the currently-selected option.

Returns

A string with the currently selected option. If options were provided that were not strings, the string version of the option is returned.

class natcap.invest.ui.inputs.File(label, helptext=None, interactive=True, args_key=None, hideable=False, validator=None)

Bases: natcap.invest.ui.inputs._Path

An InVESTModelInput for selecting a single file.

class natcap.invest.ui.inputs.FileDialog(parent=None)

Bases: object

A convenience wrapper for QtWidgets.QFileDialog.

open_file(title, start_dir=None, filters=())

Prompt the user for a file to open.

Parameters
  • title (string) – The title of the dialog.

  • start_dir=None (string) – The starting directory. If None, the last-accessed directory will be fetched from the invest settings.

  • filters= () (iterable) –

    an iterable of filter strings to use in the dialog. An example iterable would have the format:

    filters = (
        'Images (*.png *.xpm *.jpg)',
        'GeoTiffs (*.tif)'
    )
    

Returns

The absolute path to the selected file to open.

open_folder(title, start_dir=None)

Prompt the user for a directory to open.

Parameters
  • title (string) – The title of the dialog.

  • start_dir=None (string) – The starting directory. If None, the last-accessed directory will be fetched from the invest settings.

Returns

The absolute path to the directory selected.

save_file(title, start_dir=None, savefile=None)

Prompt the user to save a file.

Parameters
  • title (string) – The title of the save file dialog.

  • start_dir=None (string) – The starting directory. If None, the last-accessed directory will be fetched from the invest settings.

  • savefile=None (string) – The filename to use by default. If None, no default filename will be provided in the dialog, and the user will need to provide a filename.

Returns

The absolute path to the filename selected by the user.

class natcap.invest.ui.inputs.Folder(label, helptext=None, interactive=True, args_key=None, hideable=False, validator=None)

Bases: natcap.invest.ui.inputs._Path

An InVESTModelInput for selecting a folder.

class natcap.invest.ui.inputs.GriddedInput(label, helptext=None, interactive=True, args_key=None, hideable=False, validator=None)

Bases: natcap.invest.ui.inputs.InVESTModelInput

A subclass of InVESTModelInput that assumes it’s using a QGridLayout.

In addition to the core concepts of InVESTModelInput, GriddedInput adds a few:

  • Validity: A GriddedInput has a value that is either valid or invalid. The current validity may be accessed through self.valid(). If the input has never been validated, validity will be None. Otherwise, a bool will be returned. Validity is typically checked when the input’s value changes, but subclasses must manage how and when validation is triggered. When the validity of the input changes, validity_changed is emitted with the new validity.

  • Hidden: A GriddedInput may be initialized with the hideable parameter set to True. If this is the case, most of the component widgets are hidden from view until a checkbox is triggered to make the widgets visible again. This is useful in contexts where a single checkbox is needed to control whether an input should be interactive, and this approach reduces the code needed to implement this behavior within a UI window. When the state of this checkbox changes, the hidden_changed signal is emitted.

clear()

Reset validity, sufficiency and the valid button state.

Returns

None.

hidden()

Whether the input’s component widgets are hidden.

Returns

A boolean. If the input is not hideable, this will always return False.

hidden_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
set_hidden = <MagicMock name='mock.QtCore.Slot()()' id='140092338792384'>
valid()

Check the validity of the input.

Returns

The boolean validity of the input.

validity_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
class natcap.invest.ui.inputs.InVESTModelInput(label, helptext=None, interactive=True, args_key=None)

Bases: MockQObject

Base class for InVEST inputs.

Key concepts for the input class include:

  • Sufficiency: Whether an input has value and is interactive. When sufficiency changes, the sufficiency_changed signal is emitted with the new sufficiency. The current sufficiency may be accessed with the self.sufficient attribute.

  • Interactivity: Whether the component widgets may be interacted with by the user. When this changes, the interactivity_changed signal is emitted with the new interactivity. The current interactivity may be accessed with the self.interactive attribute.

  • Value: Every input has a value that can be set by interacting with the InVESTModelInput’s component widgets. How the value is changed by interacting with these widgets depends on the subclass. The current value can be fetched with self.value(). When the value changes, the value_changed signal is emitted.

  • Visibility: With Qt, visibility is actually controlled by containers and the parent window, among other things. Visibility here indicates whether the widgets should be considered by the package as being visible.

Subclasses of InVESTModelInput must implement these methods:

  • value(self)

  • set_value(self, value)

Signals used by this class:

  • value_changed (string): Emitted when the value of the InVESTModelInput

    instance changes. Slots are called with the string value of the input as the one and only parameter.

  • interactivity_changed (bool): Emitted when an element’s

    interactivity changes, as when set by set_interactive. The parameter passed to slots is the new interactivity of the input. So, if the input is becoming interactive, the parameter passed from interactivity_changed will be True.

  • sufficiency_changed (bool). Emitted when the input’s sufficiency

    changes. See note above on sufficiency. The parameter passed to slots indicates the new sufficiency.

add_to(layout)

Add the component widgets of this InVESTModelInput to a QGridLayout.

Parameters

layout (QtWidgets.QGridLayout) – A QGridLayout to which all component widgets should be added.

Returns

None

clear()

Reset the input to an initial, ‘blank’ state.

This method must be reimplemented for each subclass.

Returns

None.

Raises

NotImplementedError

interactivity_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
set_interactive(enabled)

Set the interactivity of the component widgets.

Emits the interactivity_changed signal if the interactivity changes.

Parameters

enabled (bool) – Whether inputs should be interactive.

Returns

None

set_value(value)

Set the value of this input.

Note

This method must be reimplemented by subclasses.

Parameters

value – The new value of the InVESTModelInput.

Raises

NotImplementedError

set_visible(visible_hint)

Set the visibility hint for the input.

Qt visibility is actually controlled by containers and the parent window. Visibility here indicates whether the widgets should be considered by the package as being visible.

Parameters

visible_hint (bool) – Whether the InVESTModelInput instance should be considered to be visible.

Returns

None

sufficiency_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
value()

Fetch the value of this InVESTModelInput.

Note

This method must be reimplemented by subclasses.

Raises

NotImplementedError

value_changed = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
visible()

Whether the input is supposed to be visible.

Note that the visibility of a Qt widget is dependent on many things, such as the visibility of the widget that contains this widget (as when there is a collapsed QGroupBox that contains this widget).

Returns

A bool of whether the input should be visible.

class natcap.invest.ui.inputs.QLogHandler(stream_widget)

Bases: logging.StreamHandler

A logging.StreamHandler subclass for writing to a stream widget.

class natcap.invest.ui.inputs.SaveFile(label, helptext=None, interactive=True, args_key=None, hideable=False, validator=None, default_savefile='new_file.txt')

Bases: natcap.invest.ui.inputs._Path

An InVESTModelInput for selecting a file to save to.

class natcap.invest.ui.inputs.Text(label, helptext=None, interactive=True, args_key=None, hideable=False, validator=None)

Bases: natcap.invest.ui.inputs.GriddedInput

A GriddedInput for handling single-line, text-based input.

TextField = <MagicMock spec='str' id='140092338829200'>
clear()

Reset the input to a ‘blank’ state.

Returns

None.

set_value(value)

Set the value of the textfield.

If this Text instance is hideable and value is not an empty string, the input will be shown. A hideable input shown in this way may be hidden again by calling self.set_hidden(True). Note that the value of the input will be preserved.

Parameters

value (string, int, or float) – The value to use for the new value of the textfield.

Returns

None

value()

Fetch the value of the textfield.

Returns

The string value of the textfield.

class natcap.invest.ui.inputs.ValidationWorker(target, args, limit_to=None)

Bases: MockQObject

A worker object for executing validation.

This object is implemented for use with a QThread, and is not started until the start() method is called.

finished = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
isFinished()

Check whether the validation callable has finished executing.

Returns

Whether validation has finished.

Return type

finished (bool)

run()

Execute the validation callable.

Warnings are saved to self.warnings. The signal self.finished is emitted when processing finishes. If an exception is encountered, the exception object is saved to self.error and the exception is logged.

Returns

None

start()

Begin execution of the validation callable.

This method is non-blocking.

Returns

None

started = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
class natcap.invest.ui.inputs.Validator(parent)

Bases: MockQObject

A class to manage validating in a separate Qt thread.

finished = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
in_progress()

Whether the validation thread is running.

Returns

Whether the validation thread is running.

Return type

is_running (bool)

started = <MagicMock name='mock.QtCore.Signal()' id='140092338957664'>
validate(target, args, limit_to=None)

Validate the provided args with the provided target.

Parameters
  • target (callable) – The validation callable. Must adhere to the InVEST validation API.

  • args (dict) – The arguments dictionary to validate.

  • limit_to=None (string or None) – Optional. If provided, this is the validation key that should be validated. All other keys will be excluded. Part of the InVEST Validation API.

Returns

None

natcap.invest.ui.inputs.center_window(window_ptr)

Center the provided window on the current screen.

Parameters

window_ptr (QtWidgets.QWidget) – a reference to a Qt window.

natcap.invest.ui.inputs.open_workspace(dirname)

Call the correct program to open a folder on disk.

The program called will depend on the operating system:

  • On mac: open

  • On Windows: explorer

  • On Linux: xdg-open

Parameters

dirname (string) – The folder to open.