The dip.ui module contains a collection of classes that allow a PyQt user interface, or just a part of a user interface, to be defined declaratively.
A user interface is declared as a hierachy of views that are containers for :term`editor` factories and other views. A particular view will arrange its editors or sub-views in a certain way. An editor allows a particular attribute of a model to be displayed and possibly updated.
Editors are testable, i.e. they can be controlled programmatically to simulate the actions of a user so that user interfaces can be automatically tested to ensure that the underlying model is changes as expected.
Views may also include ordinary Qt widgets and layouts and designs created with Qt Designer. Views may also be treated as ordinary Qt widgets and layouts in a larger user interface.
It is not the intention to enable any user interface to be defined declaratively, or to provide the same level of control provided by PyQt itself. The purpose of this module is to allow “boring” user interfaces (e.g. those used for data entry) to be created very easily, or to provide an initial user interface that will be replaced by something more specific at a later stage of an application’s development.
Base class: Model
The ActionCollection class represents a collection of actions or sub-collections.
Base class: LinkedViewFactory
The AddButton class implements a factory for a button for adding to a collection editor.
Create the view.
Parameters: |
|
---|---|
Returns: | the view which will be an instance of QAbstractButton. |
This is reimplemented to link the button view to the collection editor.
Parameters: |
|
---|
Base class: BaseViewAdapter
The BaseEditorAdapter class is a base class for adapters than implement the IEditor interface for Qt widgets.
Base class: Model
The BaseToolkit class is a base class for toolkits that implements the default mapping of dip.model types to the editors used to handle them.
Return an EditorFactory type object that will create a delegate factory to handle attributes of a particular type.
Parameter: | attribute_type – is the type of the attribute. |
---|---|
Returns: | the type object. |
Return an EditorFactory type object that will create an editor factory to handle attributes of a particular type.
Parameter: | attribute_type – is the type of the attribute. |
---|---|
Returns: | the type object. |
Base class: QValidator
The BaseValidator class is a base class for a QValidator that supplies a reason why the input is invalid. The reason is saved in the dip_invalid_reason attribute after validate() method is called.
Initialise the validator.
Parameter: | parent – is the optional parent object. |
---|
Base class: Adapter
The BaseViewAdapter class is a base class for adapters than implement the IView interface for Qt layouts and widgets.
The Bindings class represents set of bindings between widgets of a user interface and attributes of a model.
Initialise the bindings.
Parameter: | **bindings – the bindings specified as keyword arguments. The argument name is the object name of the widget that the attribute will be bound to. The argument value is the binding. If the argument value is a string then an EditorFactory instance will be automatically created for it. |
---|
Bind a view to a model.
Parameters: |
|
---|
Base class: LayoutFactory
The BoxLayoutFactory class is the base class for all factories that create views that are implemented as QBoxLayout instances.
Create additional content to be added to the list of sub-views.
Parameter: | content – the content from which additional content can be created. |
---|---|
Returns: | the additional content. |
Base class: EditorFactory
The CheckBox class implements a check box editor factory for bool attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: HBox
The CollectionButtons class contains the standard buttons used to manipulate a collection editor. Use the buttons separately if you want to lay them out differently.
Initialise the item.
Parameters: |
|
---|
Base class: EditorFactory
The ComboBox class implements a combo box editor factory for enum attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: ViewFactory
The CompositeViewFactory class is the base factory class for all views that can contain sub-views. A sub-class determines the layout of the sub-views.
Initialise the view.
Parameters: |
|
---|
Create additional content to be added to the list of sub-views. This default implementation will always raise an exception.
Parameter: | content – the content from which additional content can be created. |
---|---|
Returns: | the additional content. |
Return a list of QLayout and QWidget instances that implement the sub-views. A sub-class may include additional contents of different types, but these must be able to be handled by the view that the factory creates.
Parameters: |
|
---|---|
Returns: | the list of QLayout and QWidget instances. |
Reimplemented to finalize all sub-views.
Parameter: | item – is the view created by this factory. |
---|
Base class: Model
The Controller class is the default implementation of a controller.
Add an editor to the controller.
Parameter: | editor – is the editor. |
---|
This is called by an editor when the user has changed its value.
Parameter: | editor – is the editor. |
---|
Find the editor with a specific identifier.
Parameter: | id – is the identifier of the editor. |
---|---|
Returns: | the editor or None if the view has no such editor. |
Validate the data in the view. This implementation considers the view to be valid if all its editors have valid values.
Returns: | a string which will be empty if the view is valid, otherwise it will explain why the view is invalid. |
---|
Base class: ViewFactory
The Designer class allows any user interface created with Qt Designer to be used in a view.
Initialise the item.
Parameters: |
|
---|
Create the editor for the user interface.
Parameters: |
|
---|---|
Returns: | the editor that is the root of the user interface defined in the .ui file. |
Base class: SingleSubviewFactory
The Dialog class implements a QDialog based dialog.
Create an implementation of IController.
Returns: | the controller. |
---|
Base class: BaseValidator
The DirectoryValidator class is a validator that checks that the input is the name of an existing directory.
Validate the input.
Parameters: |
|
---|---|
Returns: | a 3-tuple of the state, possibly modified input and possibly modified position. |
Base class: LinkedViewFactory
The DownButton class implements a factory for a button for moving an item down a collection editor.
Create the view.
Parameters: |
|
---|---|
Returns: | the view which will be an instance of QAbstractButton. |
This is reimplemented to link the button view to the collection editor.
Parameters: |
|
---|
Base class: ViewFactory
The EditorFactory class is a factory for views that implement the IEditor interface.
Initialise the factory.
Parameters: |
|
---|
Reimplemented to bind an editor view to a model attribute and add it to a controller.
Parameters: |
|
---|
Configure an editor using the factory’s properties and any additional properties supplied when the factory was created.
Parameters: |
|
---|
Create the QLayout or QWidget that implements the editor and can be adapted to IEditor.
This must be reimplemented by a sub-class.
Parameters: |
|
---|---|
Returns: | the QLayout or QWidget that is the root of the editor’s implementation. |
Create the view.
Parameters: |
|
---|---|
Returns: | the view. |
Create an editor factory to be used as a delegate for a type.
Parameters: |
|
---|---|
Returns: | the editor factory. |
Get the label for an attribute. This will first try the factory itself, then the type’s meta-data and finally the type’s name.
Parameter: | attribute_type – is the attribute type. |
---|---|
Returns: | the label. |
Convert a name, typically of an attribute, to a more natural name.
Parameter: | name – is the original name. |
---|---|
Returns: | the more natural version. |
Create a delegate and set it for a column of a QAbstractItemView.
Parameters: |
|
---|
Base class: EditorFactory
The FileSelector class implements a file (and directory) selector editor factory.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: BaseValidator
The FileValidator class is a validator that checks that the input is the name of an existing file.
Validate the input.
Parameters: |
|
---|---|
Returns: | a 3-tuple of the state, possibly modified input and possibly modified position. |
Base class: EditorFactory
The FloatSpinBox class implements a spin box editor factory for float attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: LayoutFactory
The Form class arranges its contents as a form.
Base class: SingleSubviewFactory
The GroupBox class arranges its contents in a group box.
Create the view.
Parameters: |
|
---|---|
Returns: | the QLayout or QWidget that is the root of the view’s implementation. |
Base class: BoxLayoutFactory
The HBox class arranges its contents horizontally.
Base class: Interface
The IAction interface defines the API for an action that can be identified and positioned relative to another.
Base class: IEditor
The ICollectionEditor interface defines the API to be implemented (typically using adaptation) by an editor created by an EditorFactory that handles a collection type (e.g. a list).
Add a new item to the collection.
Parameters: |
|
---|
Update the invalid reason for an item in the collection.
Parameters: |
|
---|
Move an item down.
Parameter: | index – is the QModelIndex of the item. |
---|
Move an item up.
Parameter: | index – is the QModelIndex of the item. |
---|
Remove a number of items from the collection.
Parameter: | indexes – is the list of QModelIndex defining the items to be removed. |
---|
Base class: IView
The ICompositeView interface defines the API to be implemented (typically using adaptation) by a QLayout or QWidget created by a CompositeViewFactory.
Base class: Interface
The IController interface defines the API to be implemented by a view’s controller.
Add an editor to the controller.
Parameter: | editor – is the editor. |
---|
This is called by an editor when the user has changed its value.
Parameter: | editor – is the editor. |
---|
Find the editor with a specific identifier.
Parameter: | id – is the identifier of the editor. |
---|---|
Returns: | the editor or None if the view has no such editor. |
Validate the data in the view.
Returns: | a string which will be empty if the view is valid, otherwise it will explain why the view is invalid. |
---|
Base class: IView
The IEditor interface defines the API to be implemented (typically using adaptation) by a QWidget created by an EditorFactory.
Base class: IEditor
The IFileSelectorEditor interface defines the API to be implemented by an editor created by FileSelector. It is used as a marker to ensure the correct adapter is chosen.
Base class: IEditor
The IFloatSpinBoxEditor interface defines the API to be implemented by an editor created by FloatSpinBox. It is used as a marker to ensure the correct adapter is chosen.
Base class: ICollectionEditor
The IListWidgetEditor interface defines the API to be implemented by an editor created by ListWidget. It is used as a marker to ensure the correct adapter is chosen.
Base class: IView
The IMessageArea interface defines the API to be implemented by a view that is used as a message area and created by a MessageArea.
Base class: IEditor
The IPushButtonEditor interface defines the API to be implemented by an editor created by PushButton. It is used as a marker to ensure the correct adapter is chosen.
Base class: IAction
The IQActionAction interface defines the API for an action that is implemented as a QAction.
Base class: IEditor
The IRadioButtonsEditor interface defines the API to be implemented by an editor created by RadioButtons. It is used as a marker to ensure the correct adapter is chosen.
Base class: ICollectionEditor
The ITableWidgetEditor interface defines the API to be implemented by an editor created by TableWidget. It is used as a marker to ensure the correct adapter is chosen.
Base class: IEditor
The IToolButtonEditor interface defines the API to be implemented by an editor created by ToolButton. It is used as a marker to ensure the correct adapter is chosen.
Base class: Interface
The IToolkit interface defines the API to be implemented by a toolkit.
Create a button to add an item to a collection.
Parameters: |
|
---|---|
Returns: | the button which will be a QAbstractButton. |
Create an editor based on a check box.
Parameters: |
|
---|---|
Returns: | the editor. |
Create an editor based on a combo box.
Parameters: |
|
---|---|
Returns: | the editor. |
Return an EditorFactory type object that will create a delegate factory to handle attributes of a particular type.
Parameter: | attribute_type – is the type of the attribute. |
---|---|
Returns: | the type object. |
Create a dialog view.
Parameters: |
|
---|---|
Returns: | the view. |
Create a button to move an item in a collection down.
Parameters: |
|
---|---|
Returns: | the button which will be a QAbstractButton. |
Return an EditorFactory type object that will create an editor factory to handle attributes of a particular type.
Parameter: | attribute_type – is the type of the attribute. |
---|---|
Returns: | the type object. |
Return an EditorFactory type object that will create an editor factory that creates editors of a particular type.
Parameter: | widget_type – is the type of the widget. |
---|---|
Returns: | the type object. |
Create an editor that implements a file/directory selector.
Parameters: |
|
---|---|
Returns: | the editor. |
Create an editor for floats based on a spin box.
Parameters: |
|
---|---|
Returns: | the editor. |
Create a view to contain a number of items arranged as a form.
Parameters: |
|
---|---|
Returns: | the view. |
Get the name of an existing directory from the user.
Parameters: |
|
---|---|
Returns: | the name of the directory or an empty string if there was none. |
Get the name of a file to open from the user.
Parameters: |
|
---|---|
Returns: | the name of the file to open or an empty string if there was none. |
Get a list of names of files to open from the user.
Parameters: |
|
---|---|
Returns: | the list of names. |
Get the name of a file to save from the user.
Parameters: |
|
---|---|
Returns: | the name of the file to save or an empty string if there was none. |
Create a group box view.
Parameters: |
|
---|---|
Returns: | the view. |
Create a view to contain a number of items arranged horizontally.
Parameters: |
|
---|---|
Returns: | the view. |
Display a informational message to the user.
Parameters: |
|
---|
Create an editor based on a line editor.
Parameters: |
|
---|---|
Returns: | the editor. |
Create an editor for a list.
Parameters: |
|
---|---|
Returns: | the editor. |
Create a menu.
Parameters: |
|
---|---|
Returns: | the menu which will be an instance of QMenu. |
Create a menu bar.
Returns: | the menu bar which will be an instance of QMenuBar. |
---|
Create a message area.
Parameters: |
|
---|---|
Returns: | the message area which will be an instance of QLabel. |
Create an editor based on a push button.
Parameters: |
|
---|---|
Returns: | the editor. |
Ask the user a question with a yes or no answer.
Parameters: |
|
---|---|
Returns: | True if the answer was “yes”. |
Create an editor that implements a set of radio buttons.
Parameters: |
|
---|---|
Returns: | the editor. |
Create a button to add an item to a collection.
Parameters: |
|
---|---|
Returns: | the button which will be a QAbstractButton. |
Create an editor based on a spin box.
Parameters: |
|
---|---|
Returns: | the editor. |
Create a splitter view to contain a number of items.
Parameters: |
|
---|---|
Returns: | the view. |
Create an editor for a table.
Parameters: |
|
---|---|
Returns: | the editor which will be an instance of QTableWidget. The properties will be applied to the editor itself. |
Create an editor based on a text editor.
Parameters: |
|
---|---|
Returns: | the editor. |
Create an editor based on a tool button.
Parameters: |
|
---|---|
Returns: | the editor. |
Create a button to move an item in a collection up.
Parameters: |
|
---|---|
Returns: | the button which will be a QAbstractButton. |
Create a view to contain a number of items arranged vertically.
Parameters: |
|
---|---|
Returns: | the view. |
Display a warning message to the user.
Parameters: |
|
---|
Create a wizard view.
Parameters: |
|
---|---|
Returns: | the view. |
Create a wizard page view.
Parameters: |
|
---|---|
Returns: | the view. |
Base class: Interface
The IView interface defines the API to be implemented (typically using adaptation) by a QLayout or QWidget created by a ViewFactory.
Base class: CompositeViewFactory
The LayoutFactory class is the base class for all factories that create views that are implemented as QLayout instances.
Create the specific QLayout instance.
This must be reimplemented by a sub-class
Parameters: | |
---|---|
Returns: | the layout. |
Reimplemented to ensure the view is a QWidget.
Parameters: |
|
---|---|
Returns: | the QWidget that is the root of the view’s implementation. |
Base class: EditorFactory
The LineEdit class implements a line editor editor factory for string attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: ViewFactory
The LinkedViewFactory class is a base class for factories for views that are linked to editors and, in some way, supplement the behaviour of the editor being linked to.
Initialise the factory.
Parameters: |
|
---|
This is reimplemented to disable the view created by this factory if the linked editor is read-only.
Parameter: | item – is the view. |
---|
This is normally reimplemented to link the view created by this factory to an editor once everything else has been set up.
Parameters: |
|
---|
Base class: Model
The ListColumn class represents the meta-data of the column of a list.
Base class: EditorFactory
The ListWidget class implements a list widget editor factory for list attributes.
Configure the delegate for an editor created by the factory.
Parameters: |
|
---|
Configure a new widget item.
Parameters: |
|
---|
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Create a new item for the list.
Parameter: | attribute_type – is the list’s type. |
---|---|
Returns: | the new item. |
Base class: ViewFactory
The MessageArea class is a factory for a message area, which will be an implementation of, or something that be adapted to, IMessageArea to be used by a controller to display messages to the user.
Base class: EditorFactory
The PushButton class implements a push button editor factory for trigger attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: Model
The QObjectFactory class is the base class for all factories that can create a QObject whose properties can be configured and that support the concept of an identifier.
Initialize the item.
Parameter: | **properties – are keyword arguments used as property names and values that are applied to the QObject instances created by the factory. |
---|
Create the QObject instance. This should be reimplemented by a sub-class
Returns: | the object. |
---|
Configure an item’s properties.
Parameters: |
|
---|
This is called once all similar items have been created. This default implementation will set the item’s object name to the factory’s identifier if it doesn’t already have a name.
Parameter: | item – is the item that was created by this factory. |
---|
Base class: EditorFactory
The RadioButtons class implements a radio buttons editor factory for enum attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: LinkedViewFactory
The RemoveButton class implements a factory for a button for removing from a collection editor.
Create the view.
Parameters: |
|
---|---|
Returns: | the view which will be an instance of QAbstractButton. |
This is reimplemented to link the button view to the collection editor.
Parameters: |
|
---|
Base class: CompositeViewFactory
The SingleSubviewFactory class is a base class for composite views that can only have a single sub-view.
Initialise the view.
Parameters: |
|
---|
Base class: EditorFactory
The SpinBox class implements a spin box editor factory for integer attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: CompositeViewFactory
The Splitter class arranges its contents in a splitter.
Base class: Model
The TableColumn class represents the meta-data of a column of a table.
Base class: EditorFactory
The TableWidget class implements a table widget editor factory for list attributes.
Configure the delegate for a column of an editor created by the factory.
Parameters: |
|
---|
Configure a new widget item.
Parameters: |
|
---|
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Create a new row for the table.
Parameters: |
|
---|---|
Returns: | the new row. |
Return the list of TableColumn instances describing the columns of the table.
Parameters: |
|
---|---|
Returns: | the list of columns. |
Base class: EditorFactory
The TextEdit class implements a text editor editor factory for string attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: EditorFactory
The ToolButton class implements a tool button editor factory for trigger attributes.
Create the editor.
Parameters: | |
---|---|
Returns: | the editor. |
Base class: LinkedViewFactory
The UpButton class implements a factory for a button for moving an item up a collection editor.
Create the view.
Parameters: |
|
---|---|
Returns: | the view which will be an instance of QAbstractButton. |
This is reimplemented to link the button view to the collection editor.
Parameters: |
|
---|
Base class: BoxLayoutFactory
The VBox class arranges its contents vertically.
Base class: QObjectFactory
The ViewFactory class is the base class for all factories that create views, sub-views and editors.
Create a view for a model. This will always be a QWidget.
Parameters: |
|
---|---|
Returns: | the QWidget that is the root of the view’s implementation. |
Bind a view created by this factory.
Parameters: |
|
---|
Create an implementation of IController.
Returns: | the controller. |
---|
Create the view.
This must be reimplemented by a sub-class.
Parameters: |
|
---|---|
Returns: | the QLayout or QWidget that is the root of the view’s implementation. |
Base class: CompositeViewFactory
The Wizard class implements a QWizard based wizard.
Create an implementation of IController.
Returns: | the controller. |
---|
Base class: Controller
The WizardController class is a controller for handling wizards.
Validate the data in a page. This implementation considers the page to be valid if all its editors have valid values.
Parameter: | page_nr – is the number of the page. This is the index of the page in the wizard and is not the same as the identifier allocated by Qt. |
---|---|
Returns: | a string which will be empty if the page is valid, otherwise it will explain why the page is invalid. |
Validate the data in the view. This implementation considers the view to be valid if all its editors have valid values.
Returns: | a string which will be empty if the view is valid, otherwise it will explain why the view is invalid. |
---|
Base class: SingleSubviewFactory
The WizardPage class implements a QWizardPage based wizard page.
Create the view for a model.
Parameters: |
|
---|---|
Returns: | the QLayout or QWidget that is the root of the view’s implementation. |