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='140405673525840'>¶
-
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='140405673525840'>¶
-
-
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='140405673525840'>¶
-
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='140405673525840'>¶
-
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='140405673525840'>¶
-
-
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. IfNone
, 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 theoptions
parameter toDropdown.__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 beNone
. 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 toTrue
. 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, thehidden_changed
signal is emitted.
-
clear
()¶ Reset validity, sufficiency and the valid button state.
- Returns
None.
Whether the input’s component widgets are hidden.
- Returns
A boolean. If the input is not hideable, this will always return
False
.
-
valid
()¶ Check the validity of the input.
- Returns
The boolean validity of the input.
-
validity_changed
= <MagicMock name='mock.QtCore.Signal()' id='140405673525840'>¶
-
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 theself.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 theself.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, thevalue_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 InVESTModelInputinstance changes. Slots are called with the string value of the input as the one and only parameter.
interactivity_changed
(bool): Emitted when an element’sinteractivity 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 beTrue
.
sufficiency_changed
(bool). Emitted when the input’s sufficiencychanges. 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='140405673525840'>¶
-
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='140405673525840'>¶
-
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='140405673525840'>¶
-
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='140405672868928'>¶
-
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 callingself.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='140405673525840'>¶
-
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 signalself.finished
is emitted when processing finishes. If an exception is encountered, the exception object is saved toself.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='140405673525840'>¶
-
-
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='140405673525840'>¶
-
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='140405673525840'>¶
-
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.