`dip.shell`¶

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

Plugins must provide appropriate support for the following extension points:

dip.shell.model_factories: This must be supported by any plugin that configures an object implementing the dip.shell.IModelManagerTool interface. A contribution must be a callable.
dip.shell.tools: This must be supported by any plugin that configures an object implementing the dip.shell.IShell interface. A contribution must implement the dip.shell.ITool interface.

`BaseManagedModelTool`¶

class dip.shell.BaseManagedModelTool¶

Base class: Model

The BaseManagedModelTool class is a base class for tools that handle managed models. It automatically manages the different lists of views and provides a convenient interface to the changing of the active view and model.

create_views(model)¶

Create the views for a managed model.

This must be implemented by a sub-class.

Parameters:	model – is the model.
Returns:	the list of views.

open_model(location)¶

Open a model at a storage location.

Parameters:	location – is the storage location.

veto(view)¶

Determine if the view is to be prevented from being closed.

Parameters:	view – is the view.
Returns:	`True` if the close of the view is to be prevented.

`BaseShellAdapter`¶

class dip.shell.BaseShellAdapter¶

Base class: Adapter

The BaseShellAdapter class is a base class for adapters to the IShell interface. It implements housekeeping common to all shells.

__init__()¶: Initialise the adapter.

close_view(view=None)¶

Close a view if possible.

Parameters:	view – is the view. If it is not specified then the current view is closed.
Returns:	`True` if the view was closed.

new_view_allowed()¶

This determines if the main area policy allows for a new view to be added.

Returns:	`True` if a new view is allowed.

open(tool_id, location, format='')¶

Open the model at a location and add it to a tool.

Parameters:	tool_id – is the identifier of the tool to handle the model. location – is the location as a string. format – is the identifier of the optional format.

`BaseShellFactory`¶

class dip.shell.BaseShellFactory¶

Base class: ViewFactory

The BaseShellFactory class is a base class for shell factories. It creates views that can be adapted to the IShell interface.

id = 'dip.shell': The identifier of a shell.

main_area_policy = Enum('multi', 'on_demand', 'single'): This determines how multiple views placed in the main area of the shell are handled. ‘multi’ means that the area may contain any number of views and will visualise the area in the same way irrespective of the number of views. ‘on_demand’ means that the area may contain any number of views but it may visualise the area differently if it contains a single view. ‘single’ means that the area may only ever contain one view and an old view must be discarded before a new view is added.

tool_factories = List(Callable()): The tool factories. A factory should return an object that implements or can be adapted to ITool.

window_title_template = Str()

The template from which the window title is derived. Tokens in the template are replaced by their corresponding values:

[view] is replaced by the name of the active view.

Note that, as with window_title, [*] will be replaced with the application modification state by the toolkit.

create(model, controller, parent)¶

Create the shell view.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the view which can be adapted to the `IShell` interface.

create_shell(model, controller, parent)¶

Create the view that implements the shell. This should be reimplemented by a sub-class.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the shell.

`IActionHints`¶

class dip.shell.IActionHints¶

Base class: Interface

The IActionHints interface defines metadata that an object may provide for an action.

id = Str(): The identifier of the action.

within = Str(): The optional identifier of a collection of actions that this action will be placed within.

`IAreaHints`¶

class dip.shell.IAreaHints¶

Base class: Interface

The IAreaHints interface defines the metadata that an object may provide for an area.

area = Str(): The identifier of the area where the view should be placed. An empty string corresponds to the shell-specific default area.

`ICloseViewVeto`¶

class dip.shell.ICloseViewVeto¶

Base class: Interface

The ICloseViewVeto interface defines the API to be implemented by a tool that wants to exert control over whether or not a view can be closed.

veto(view)¶

Determine if the view is to be prevented from being closed.

Parameters:	view – is the view.
Returns:	`True` if the close of the view is to be prevented.

`IDirty`¶

class dip.shell.IDirty¶

Base class: Interface

The IDirty interface defines the API implemented by objects that need to maintain state to determine if the object has been modified.

dirty = Bool(False): This is set if the object has been modified.

`IManagedModel`¶

class dip.shell.IManagedModel¶

Base class: IDirty

The IManagedModel interface defines the API of a managed model.

location = Instance(IStorageLocation): The storage location of the model. It will be None if it is not stored. It will be updated automatically.

native_format = Str(): The identifier of the model’s native format.

invalid_reason = Str(): This explains why the model is invalid. It will be an empty string if the model is valid.

views = List(IView): The views that, when active, will cause the appropriate managed model actions to be enabled.

`IManagedModelTool`¶

class dip.shell.IManagedModelTool¶

Base class: ITool

The IManagedModelTool interface defines the API for a tool that handles one or more managed models.

manager = Instance(IModelManagerTool): The model manager that is managing this tool’s models.

model_policy = Enum('many', 'one', 'zero_or_one'): This defines how the tool handles multiple models. many means the tool can handle any number of models at a time. one means that the tool handles exactly one model at a time - this means a new model will be created automatically without user intervention. zero_or_one means that the tool handles no more than one model at time.

models = List(IManagedModel): The managed models the tool is handling.

new_tool = Bool(True): This is set if the tool is suitable for handling a model in the context of a “New” operation.

open_tool = Bool(True): This is set if the tool is suitable for handling a model in the context of an “Open” operation.

handles(model)¶

Check if the tool can handle a particular model.

Parameters:	model – is the model.
Returns:	`True` if a tool can handle the model.

`IModelManagerTool`¶

class dip.shell.IModelManagerTool¶

Base class: ITool

The IModelManagerTool interface defines the API made available to implementations of the IManagedModelTool interface.

model_factories = List(Callable()): The managed model factories. A factory should return an object that implements or can be adapted to IManagedModel. If an application may include more than one model type then the factory should implement the IDisplay interface.

open_model(location, tool)¶

This handles open_model() on behalf of an implementation of the IManagedModelTool interface.

Parameters:	location – is the storage location. tool – is the tool.

veto_close_view(view, tool)¶

This handles veto() on behalf of an implementation of the IManagedModelTool interface.

Parameters:	view – is the view. tool – is the tool.
Returns:	`True` if the close of the view is to be prevented.

`IOpenModel`¶

class dip.shell.IOpenModel¶

Base class: Interface

The IOpenModel interface defines the API to be implemented by a tool that can open a model typically from a location provided on the command line.

open_model(location)¶

Open a model at a storage location.

Parameters:	location – is the storage location.

`IQuitVeto`¶

class dip.shell.IQuitVeto¶

Base class: Interface

The IQuitVeto interface defines the API to be implemented by an object that is allowed to veto a user’s request to quit the application.

reasons = List(Str()): The list of separate reasons why the quit request should be vetoed. Each reason must be a short, properly punctuated, one line sentence. If the list is empty then the request will not be vetoed.

`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.ui.actions.close dip.ui.actions.export dip.ui.actions.import dip.ui.actions.new dip.ui.actions.open dip.ui.actions.quit dip.ui.actions.save dip.ui.actions.save_as dip.ui.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.ui.collections.edit dip.ui.collections.file dip.ui.collections.help dip.ui.collections.print dip.ui.collections.tools dip.ui.collections.undo dip.ui.collections.view

The following area identifiers, used to position views, are defined. A shell may interpret these in any way. An empty string implies the main area.

dip.shell.areas.left dip.shell.areas.right dip.shell.areas.bottom dip.shell.areas.top

current_view = Instance(IView): The current view. It is not necessarily the active view.

main_area_policy = Enum('multi', 'on_demand', 'single'): This determines how multiple views placed in the main area of the shell are handled. ‘multi’ means that the area may contain any number of views and will visualise the area in the same way irrespective of the number of views. ‘on_demand’ means that the area may contain any number of views but it may visualise the area differently if it contains a single view. ‘single’ means that the area may only ever contain one view and an old view must be discarded before a new view is added.

publication_manager = Instance(IPublicationManager): The publication manager.

tools = List(ITool): The list of the shell’s tools.

views = List(IView): The list of the shell’s views.

window_title_template = Str()

The template from which the window title is derived. Tokens in the template are replaced by their corresponding values:

[view] is replaced by the name of the active view.

Note that, as with window_title, [*] will be replaced with the application modification state by the toolkit.

close_view(view=None)¶

Close a view if possible.

Parameters:	view – is the view. If it is not specified then the current view is closed.
Returns:	`True` if the view was closed.

new_view_allowed()¶

This determines if the main area policy allows for a new view to be added.

Returns:	`True` if a new view is allowed. If not then the user will be informed.

open(tool_id, location, format='')¶

Open the model at a location and add it to a tool.

Parameters:	tool_id – is the identifier of the tool to handle the model. location – is the location as a string. format – is the identifier of the optional format.

`ITool`¶

class dip.shell.ITool¶

Base class: Interface

The ITool interface defines the API to be implemented by a tool.

actions = List(Instance(IAction, IActionCollection)): The tool’s actions. Any initial actions will be automatically added to the shell. If there are none then the tool is introspected for any ActionCollection attributes and then any Action attributes.

current_view = Instance(IView): The tool’s current view. It will be None if the shell’s current view does not belong to this tool.

id = Str(): The tool’s identifier.

shell = Instance(.IShell): The shell that the tool is attached to.

views = List(IView): The tool’s views. Any initial views will be automatically added to the shell.

`SimpleViewTool`¶

class dip.shell.SimpleViewTool¶

Base class: Model

The SimpleViewTool class is a base class for shell tools implemented as a single view and that allows for the use of an action that toggles the visibility of the view.

action_id = Str(): The identifier to use for any action.

area = Str('dip.shell.areas.left'): The identifier of the area where the view should be placed.

name = Str(): The tool’s name.

view = Instance(IView): The view implementation.

views = Tuple(IView): The tool’s views. Any initial views will be automatically added to the shell.

within = Str(): The optional identifier of a collection of actions that any action will be placed within.

`dip.shell`¶

`BaseManagedModelTool`¶

`BaseShellAdapter`¶

`BaseShellFactory`¶

`IActionHints`¶

`IAreaHints`¶

`ICloseViewVeto`¶

`IDirty`¶

`IManagedModel`¶

`IManagedModelTool`¶

`IModelManagerTool`¶

`IOpenModel`¶

`IQuitVeto`¶

`IShell`¶

`ITool`¶

`SimpleViewTool`¶

Table Of Contents

Previous topic

Next topic

This Page