Commit 9246e99d authored by David Thompson's avatar David Thompson

Some more widget documentation.

parent cec68b85
......@@ -95,7 +95,9 @@ if (SPHINX_FOUND)
userguide/extension/index.rst
userguide/extension/paraview/index.rst
userguide/extension/paraview/representations.rst
userguide/extension/paraview/widgets.rst
userguide/extension/paraview/widgets/index.rst
userguide/extension/paraview/widgets/design.rst
userguide/extension/paraview/widgets/gallery.rst
userguide/extension/paraview/plugins.rst
userguide/extension/paraview/panels.rst
userguide/extension/paraview/lifecycle.rst
......
......@@ -15,4 +15,4 @@ These plugins form the core of the ModelBuilder application (version 6 and later
representations.rst
selection.rst
panels.rst
widgets.rst
widgets/index.rst
Design
------
Because SMTK is using ParaView, which is an application built on top of VTK,
designing new 3-d widgets for use with SMTK involves several API boundaries
and thus several classes.
VTK.
The basic concept of a 3-d widget is implemented in VTK without any
notion of a matching Qt user interface.
VTK provides 2 classes that new widgets should inherit: a representation class
which is responsible for generating renderable data to provide the visual
representation of the widget and
a widget class, which is responsible for user interaction related
to the visual appearance (i.e., translating mouse hover, click, drag, and
even keyboard events into parameter changes that affect the visual representation).
For some widgets, a third class is used to hold parameters that define an
implicit function which can be used to model related geometry.
A good example of these classes are :smtk:`vtkConeRepresentation` and :smtk:`vtkConeWidget`.
The implicit function representing the cone being modeled is
the :smtk:`vtkImplicitConeFrustum` class.
Frequently, these implicit functions are used to select cells, trim geometry,
or perform other editing actions as the user interacts with the widget.
ParaView.
ParaView uses VTK 3-d widgets. These widgets are rendered on the server
but must respond to user interaction that takes place on a desktop client.
ParaView uses its client-server protocol to distribute mouse and keyboard events
to the server and its client-server property system to retrieve updated parameters
from the server as needed (e.g., a sphere's center and radius might be updated
by a VTK widget+representation on the server and then transferred to the client
via two DoubleVector properties).
ParaView's widgets have both a 3-d appearance (obtained via VTK) and a 2-d Qt user
interface that allows users to inspect and enter exact numeric values when needed.
ParaView widgets inherit the pqInteractivePropertyWidget class.
A good example of a ParaView widget class is :smtk:`pqConePropertyWidget`, which
uses the VTK classes above, but indirectly via server-manager XML in the
plugin named smtkPVServerExtPlugin; when a pqConePropertyWidget is created on
the client process, it constructs a proxy object named ConeWidgetRepresentation.
This proxy object has subproxies named ConeWidget and ConeRepresentation that
are backed on the server process by the VTK classes above.
When users interact with the VTK classes in the render window, changes to those
classes are mapped to ParaView server-manager proxy property objects and
notifications are sent to the client that properties are updated.
Similarly, changes on the client change proxy properties that are transmitted
to the server and used to update the VTK classes.
SMTK.
SMTK maps ParaView properties back and forth between SMTK attribute items.
For example, the cone widget in ParaView requires properties for a generic
truncated cone (two points — to determine the axis — and two radii —
to determine the radius perpendicular to that axis at each endpoint).
However, an SMTK attribute may only want to accept cylinders (a single
radius for each point). The SMTK qtItem subclass maps between the items
available in the attribute and the properties in ParaView.
Each time a ParaView property is set, the updateItemFromWidgetInternal method
is invoked. Likewise, when the attribute is modified externally (for example,
by a Signal operation being performed), the updateWidgetFromItemInternal
method is invoked.
These methods both generally invoke a protected method specific to each
widget to fetch items from the attribute.
Based on the items available, these two methods synchronize values between
SMTK attribute items and ParaView properties.
A good example of an SMTK item widget is :smtk:`pqSMTKConeItemWidget`.
Widgets
Gallery
-------
SMTK provides special widgets for interacting with
model and mesh resources inside ParaView.
These qtItem subclasses may be used by specifying
them in an attribute's View configuration.
SMTK's existing widgets are listed below with instructions for their use.
Point
^^^^^
......
Widgets
-------
SMTK provides special widgets for interacting with
model and mesh resources inside ParaView.
These qtItem subclasses may be used by specifying
them in an attribute's View configuration.
.. toctree::
:maxdepth: 2
design.rst
gallery.rst
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment