dip.shell

The dip.shell module implements the infrastructure for defining and interfacing with a shell.

IDisplay

class dip.shell.IDisplay

Base class: Interface

The IDisplay interface defines the metadata that an object may provide so that it can be referred to in a GUI and be recognisable by the user. It’s use is usually optional, i.e. an application will normally try to use other information if an object does not implement this interface.

name = Str()
The full name of the object. This should uniquely identify the object to the user.
short_name = Str()
The optional short name of the object.

IShell

class dip.shell.IShell

Base class: Interface

The IShell interface defines the API of a shell.

The following action identifiers are considered to be well known. A shell would normally be expected to honour them.

dip.shell.actions.close dip.shell.actions.export dip.shell.actions.import dip.shell.actions.new dip.shell.actions.open dip.shell.actions.print dip.shell.actions.print_preview dip.shell.actions.printer_settings dip.shell.actions.quit dip.shell.actions.redo dip.shell.actions.save dip.shell.actions.save_as dip.shell.actions.undo dip.shell.actions.whats_this

The following action collection identifiers are considered to be well known. A shell, if it supports the concept of action collections, would normally be expected to honour them.

dip.shell.collections.edit dip.shell.collections.file dip.shell.collections.help dip.shell.collections.tools dip.shell.collections.view
actions = List(Instance(IAction))
The available actions.
id = Str()
The identifier of the shell. The shell’s object name will default to the identifier.
plugin_manager = Instance(IPluginManager)
The optional plugin manager. This is normally set by the plugin that publishes the shell as a service.
shell_manager = Instance(IShellManager)
The shell manager.
toolkit = Instance(IToolkit)
The toolkit.
widget = Instance(QWidget)
The QWidget instance that implements the shell.
__init__(**properties)

Initialise the shell.

Parameter:**properties – are keyword arguments used as property names and values that are applied to the shell widget.
add_tool(tool)

Add a tool to the shell.

Parameter:tool – is the tool to add.
perform_close(tool)

Close a tool asking the user for help where necessary.

Parameter:tool – is the tool to close.
perform_new()
Create a tool for a new shell object asking the user for help where necessary.
perform_open()
Create a tool for a shell object read from storage asking the user for help where necessary.
perform_quit()
Confirm that the user wants to quit given the state of any shell objects.
perform_save(tool)

Write a shell object to storage at its current location asking the user for help where necessary.

Parameter:tool – is the tool operating on the shell object to write.
perform_save_as(tool)

Write a shell object to storage at a new location asking the user for help where necessary.

Parameter:tool – is the tool operating on the shell object to write.

IShellAction

class dip.shell.IShellAction

Base class: IQActionAction

The IShellAction interface defines the API for an action that changes its state according to the user’s interaction with the containing shell.

enabled = Bool(True)
This is set if the action is enabled. If validate() returns False then the action will be disabled irrespective of this value.
handles = Instance(type)
This is used by the default implementation of validate() to specify the type of the active tool that is valid for the action. If it is not specified then the active tool, so long as there is one, will always be considered valid.
needs_tool = Bool(True)
This is set if the action requires there to be an active tool. If this is True then the action will be automatically disabled, and validate() will never be called, if there is no active tool.
on_perform = Callable()
The default implementation of perform() calls this with the shell’s active tool as its only argument.
shell = Instance(IShell)
The shell. This is normally set by the shell itself.
visible = Bool(True)
This is set if the action is visible.
perform(tool)

Perform the action (probably) on a tool. This will not be called if validate() returns False.

Parameter:tool – is the tool.
validate(tool)

Check if the action can be performed on a tool.

Parameter:tool – is the tool.
Returns:True if the action can be performed.

IShellManager

class dip.shell.IShellManager

Base class: Interface

The IShellManager interface defines the API for a shell manager.

active_tool = Instance(QWidget)
The currently active tool.
io_manager = Instance(IIOManager)
The IIOManager.
shell = Instance(dip.shell.IShell)
The shell.
shell_object_factories = List(IShellObjectFactory)
The available shell object factories.
tool_factories = List(IToolFactory)
The available tool factories.
close(tool)

Close a tool asking the user for help where necessary.

Parameter:tool – is the tool to close.
Returns:True if the user didn’t cancel.
new()

Create a tool for a new shell object asking the user for help where necessary.

Returns:the tool or None if the user cancelled.
open(location='')

Create a tool for a shell object read from storage asking the user for help where necessary.

Parameter:location – is the optional location of the object to open.
Returns:the object or None if the user cancelled.
quit()

Confirm that the user wants to quit given the state of any shell objects.

Returns:True if the user didn’t cancel.
save(tool)

Write a shell object to storage at its current location asking the user for help where necessary.

Parameter:tool – is the tool operating on the shell object to write.
save_as(tool)

Write a shell object to storage at a new location asking the user for help where necessary.

Parameter:tool – is the tool operating on the shell object to write.

IShellObject

class dip.shell.IShellObject

Base class: IDisplay

The IShellObject interface defines the API of a shell object.

dirty = Bool()
This is set if the object needs writing to storage if no changes are to be lost. It will be cleared automatically.
factory = Instance(IShellObjectFactory)
The factory that created the object. It will be set automatically.
location = Instance(IStorageLocation)
The storage location of the object. It will be None if it is not stored. It will be updated automatically.
valid = Bool(True)
This is set if the object is valid and can be written to storage.

IShellObjectFactory

class dip.shell.IShellObjectFactory

Base class: Interface

The IShellObjectFactory interface defines the API for factories of shell objects.

name = Str()
The name of the type of the shell object.
native_format = Str()
The identifier of the object’s native format.
__call__(shell)

Create an instance of the shell object.

Parameter:shell – is the shell.
Returns:the instance of the shell object which must implement IShellObject or be able to be adapted to it.

ITool

class dip.shell.ITool

Base class: Interface

The ITool interface defines the API of a tool than operates on a shell object and relies on a shell manager to manage the lifecycle of the object.

factory = Instance(IToolFactory)
The factory that created the tool.
obj = Any()
The shell object that the tool is operating on. This will be able to be adapted to IShellObject (or implement that interface explicitly).

IToolFactory

class dip.shell.IToolFactory

Base class: Interface

The IToolFactory interface defines the API for tool factories.

name = Str()
The name of the tool.
__call__(obj, toolkit)

Create an instance of the tool.

Parameters:
  • obj – is the obj on which the tool is to operate on.
  • toolkit – is the IToolkit implementation that can be used to create widgets.
Returns:

the instance of the tool. This must be a QWidget instance and, therefore, can be adapted to the ITool interface.

handles(obj)

Check if the tool can handle an object.

Parameter:obj – is the object.
Returns:True if the tool can handle the object.

IUnmanagedTool

class dip.shell.IUnmanagedTool

Base class: IQActionAction

The IUnmanagedTool interface defines the API of an unmanaged tool.

name = Str()
The name of the tool as it appears to the user.
widget = Instance(QWidget)
The QWidget sub-class that implements the tool.

ModelToolFactory

class dip.shell.ModelToolFactory

Base class: Model

The ModelToolFactory class is a tool factory for any tool that uses an automatically generated view to edit a model. It is not registered as a tool factory itself, instead it will normally be sub-classed and those sub-classes will be registered.

model_type = Instance(type)
The sub-class of Model that the tool can handle.
__call__(model, toolkit)

Create an instance of the tool.

Parameters:
  • model – is the model on which the tool is to operate on.
  • toolkit – is the IToolkit implementation used to create the view.
Returns:

the instance of the tool.

create_view_factory()
Create the view factory that will be used to create the view.
This default implementation creates a Form.
Returns:the view factory.
handles(obj)

Check if the object can be handled.

Parameter:obj – is the object.
Returns:True if the tool can handle the object.

Table Of Contents

Previous topic

dip.plugins

Next topic

dip.shell.plugins

This Page