-
Notifications
You must be signed in to change notification settings - Fork 262
WinForms Timeline Renderers, Controls, and Manipulators
These classes are responsible for drawing timelines in a control and providing extra capabilities. These classes use Direct2D to draw and work with timelines. These are for Windows® Forms, and reside in the Sce.Atf.Controls.Timelines.Direct2D
namespace and Atf.Gui.WinForms
assembly.
There are both Direct2D and GDI versions of all the classes. You should use the much faster Direct2D versions, because the GDI versions are obsolete.
The timeline renderers draw timeline objects on a canvas provided by a timeline control.
The abstract base class D2dTimelineRenderer
renders the timeline and objects in it using Direct2D. It works with a timeline control, such as D2dTimelineControl
.
D2dTimelineRenderer
provides most of the timeline rendering capabilities:
-
Init()
method to initialize the renderer. - Properties for various graphics objects used in rendering.
-
Dispose()
method for disposing of graphics objects. - Numerous properties to configure the rendering, such as
TrackIndent
for track indentation andHeaderWidth
for group and track header width. -
Draw()
andPrint()
methods to draw the timeline to the display. - Various private methods to draw timeline parts, such as sub-timelines, markers, groups, ghosts for moving and resizing objects, and so on.
-
Pick()
methods for getting a list of timeline objects hit in a rectangle. -
GetBounds()
methods to find the bounds of timeline objects, such as intervals, keys, and markers. - Abstract methods to draw particular objects, such as groups, tracks, and keys.
-
Context
class with useful information for laying out and drawing timeline elements, such as theD2dTimelineRenderer
andD2dGraphics
objects. This context is used as a parameter in several methods, such as theDraw()
methods.
Because D2dTimelineRenderer
is abstract, you must derive a class from it to produce an actual renderer, which is D2dDefaultTimelineRenderer
's role. A timeline application can use D2dDefaultTimelineRenderer
or a class like it.
D2dDefaultTimelineRenderer
has an Init()
method to initialize the graphic objects it uses to draw timeline objects.
D2dDefaultTimelineRenderer
also has properties to customize rendering, such as TrackHeight
for the track height, relative to a unit of time.
D2dDefaultTimelineRenderer
overrides the abstract Draw()
methods in D2dTimelineRenderer
to draw the following objects:
- Group
- Track
- Interval
- Key
- Marker
Timeline controls display the rendered timeline. There are two versions: D2dTimelineControl
for Direct2D and TimelineControl
for GDI. As already noted, you should use D2dTimelineControl
.
D2dTimelineControl
derives from CanvasControl
, a control for viewing and editing a 2D bounded canvas. The constructor with the most arguments is:
public D2dTimelineControl(
ITimelineDocument timelineDocument,
D2dTimelineRenderer timelineRenderer,
TimelineConstraints timelineConstraints,
bool createDefaultManipulators)
All constructors require the ITimelineDocument
argument. If D2dTimelineRenderer
or TimelineConstraints
are not supplied, default objects are constructed for them. The parameter createDefaultManipulators
indicates whether default manipulators should be constructed for the control. For details about these manipulators, see Timeline Manipulators.
D2dTimelineControl
provides the Direct2D graphics device used for drawing in its D2dGraphics
property. This value is used whenever drawing occurs.
D2dTimelineControl
has a set of Create()
methods to create these objects using an ITimelineObjectCreator
:
- Group
- Track
- Interval
- Key
- Marker
AllEvents
, AllMarkers
, AllTracks
, and AllGroups
.
The control also handles events, such as for mouse actions and painting.
Manipulators allow you to manipulate timeline objects in a timeline control. These function somewhat like control adapters, in that they add capabilities to a control. However, they do not derive from ControlAdapter
and the control they operate on, D2dTimelineControl
, is not an AdaptableControl
.
The manipulators all take a D2dTimelineControl
parameter to attach them to that control, as for D2dMoveManipulator
:
public D2dMoveManipulator(D2dTimelineControl owner)
This manipulator is created this way, for example, where m_timelineControl
holds a D2dTimelineControl
:
D2dMoveManipulator moveManipulator = new D2dMoveManipulator(m_timelineControl);
This table describes the Direct2D manipulators:
Manipulator | Description |
---|---|
D2dMoveManipulator
|
A timeline manipulator for moving IEvent objects, such as markers, keys, and intervals.
|
D2dScaleManipulator
|
Creates the scale manipulator, a horizontal bar on top of the scale bar. It has handles at each end, bracketing the selection set. It has two distinct modes:
|
D2dScrubberManipulator
|
Creates the scrubber manipulator, a vertical bar that can slide left and right by grabbing the handle on top. |
D2dSelectionManipulator
|
A timeline manipulator for implementing the selection logic. It should probably be attached first to the timeline control. The attachment is permanent and there must be one timeline control per ITimelineDocument .
|
D2dSnapManipulator
|
A timeline manipulator intended to be used by other manipulators to allow for snapping selected objects to non-selected events and give a visual indication of this. |
D2dSplitManipulator
|
A timeline manipulator for splitting intervals into two. When hovering the mouse over an interval, if the user holds down a modifier key (Alt by default), the cursor changes to indicate where a split will take place. On the MouseDown event, the interval is split.
|
The order in which these manipulators are attached to the D2dTimelineControl
matters. The order here determines the order of receiving Paint
events and is the reverse order of receiving picking events. For example, a custom control that is drawn on top of everything else and that can be clicked on should come last in this list, so that it is drawn last and is picked first.
This is the recommended order in which manipulators should be constructed.
D2dSelectionManipulator
D2dMoveManipulator
D2dScaleManipulator
D2dSplitManipulator
D2dSnapManipulator
D2dScrubberManipulator
Follow these steps to create a timeline with these classes.
- Construct the
D2dDefaultTimelineRenderer
. Its constructor takes no parameters, so it is easy:m_renderer = new D2dDefaultTimelineRenderer();
- Create the
D2dTimelineControl
, as in this statement:Recall that the first argument is anm_timelineControl = new D2dTimelineControl(null, m_renderer, new TimelineConstraints(), false);
ITimelineDocument
, which can benull
. The second argument is aD2dTimelineRenderer
; ifnull
, a newD2dDefaultTimelineRenderer
is constructed and used. The third argument is aTimelineConstraints
, which can be constructed in-line. For more information, see TimelineConstraints Class. - Set the
D2dTimelineControl
'sTimelineDocument
property to theITimelineDocument
, if there is one. - Attach manipulators to the control by constructing them with the
D2dTimelineControl
, as in:Construct manipulators in the recommended order. For more details, see Timeline Manipulators.D2dMoveManipulator moveManipulator = new D2dMoveManipulator(m_timelineControl);
- Initialize the
D2dDefaultTimelineRenderer
with theD2dGraphics
object from theD2dTimelineControl
, as in this code. Herem_renderer
contains the renderer,document
is theITimelineDocument
, which has aTimelineControl
property containing the timeline control:Them_renderer.Init(document.TimelineControl.D2dGraphics);
D2dGraphics
object is obtained from theD2dGraphics
property of the control.
The TimelineEditor
component and TimelineDocument
class of the ATF Timeline Editor Sample perform these steps. For more information on how these controls are used, see Timeline Editor Programming Discussion.
The classes discussed here are the Direct2D versions. There is an older set of classes with the same kind of functionality that use GDI drawing instead. For example, D2dTimelineRenderer
is the Direct2D version of the GDI TimelineRenderer
. As elsewhere, the Direct2D version of the classes have the prefix "D2d".
The GDI classes are obsolete. You should use the much faster classes in the Sce.Atf.Controls.Timelines.Direct2D
namespace.
- What is a Timeline in ATF: General description of timelines, describing their objects, the timeline sample, and namespaces and assemblies in which support resides.
- Timeline Interfaces: Describes general and timeline object specific interfaces.
-
WinForms Timeline Renderers, Controls, and Manipulators: Discusses the key objects in the
Sce.Atf.Controls.Timelines.Direct2D
namespace for timeline support of renderers, a canvas control, and manipulators for timelines. -
General Timeline Classes: Classes in the namespace
Sce.Atf.Controls.Timelines
that provide information needed for rendering and displaying timelines.
- Home
- Getting Started
- Features & Benefits
- Requirements & Dependencies
- Gallery
- Technology & Samples
- Adoption
- News
- Release Notes
- ATF Community
- Searching Documentation
- Using Documentation
- Videos
- Tutorials
- How To
- Programmer's Guide
- Reference
- Code Samples
- Documentation Files
© 2014-2015, Sony Computer Entertainment America LLC