DataViews Visual C++ Reference Manual. DataViews for Windows Version 2.0

Transcription

1 DataViews Visual C++ Reference Manual DataViews for Windows Version 2.0

2 GEFanuc DataViews Headquarters 47Pleasant Street Northampton, MA U.S.A. Telephone:(413) FAX:(413) web: GEFanuc DataViews JapanSales Office 16ParaleMitsui Bldg 8Higashida-cho Kawasaki-ku,Kawasaki Kanagawa, , Japan. Telephone: FAX: web: GEFanuc DataViews U.K.Sales Office Unit 1, MillSquare FeatherstoneRoad WolvertonMill South Miton Keynes, MK125BZ UnitedKingdom Telephone: FAX: web: Copyrights and Trademarks Copyright 2000GEFanucDataViews AllRights Reserved. This manual is subjecttocopyrightprotection. No portion of the contents of this book may be reproduced in any form or by any means without prior writtenconsentfromgefanucdataviews. DataViews,DV-Tools,andDV-Draw areregisteredtrademarks of GE FanucDataViews. DVX-Designer is atrademarks ofge FanucDataViews. Allother trademarks areacknowledgedas thepropertyof their respectiveowners. August 1999 SoftwareReleaseVersion2.0 Document Number Document Revision B

3 iii DataViews Visual C++ Reference Manual Table of Contents Chapter 1: DataViews C++ Class Reference...1 Introduction to the DataViews C++ Classes... 1 DataViews C++ Class Map... 2 Coordinate Systems... 3 CDVBlinkMgr... 5 CDVBaseInterface... 6 CDVBaseRuleEngine CDVBaseViewWrapper CDVCustomControl CDVGenericViewWrapper CDVInterface CDVScrollBar CDVScrollView CDVViewWrapper CDVWinInterface CDVWinViewWrapper Chapter 2: DataViews COM Object Type Library Reference - Visual C Introduction to the DataViews COM Objects DataViews COM Object Maps CDVViewHndl CDVArcHndl CDVAttributes CDVAXControlHndl CDVAxisHndl CDVBaseObjectHndl CDVBitmapHndl CDVCircleHndl CDVClosedSplineHndl CDVColorHndl CDVCustomAttributeHndl CDVEllipseHndl

4 iv DataViews Visual C++ Reference Manual CDVGraphHndl CDVHardwareTextHndl CDVLineHndl CDVListTicLabeller CDVMFCControlHndl CDVObjectHndl CDVOpenSplineHndl CDVPointHndl CDVPolygonHndl CDVPolylineHndl CDVRectangleHndl CDVSubdrawingHndl CDVTicLabeller CDVTimeStampTicLabeller CDVTrueTypeAttributes CDVTrueTypeTextHndl CDVVarDescHndl CDVVariableTicLabeller CDVVectorAttributes CDVVectorTextHndl CDVCustomDataSourceHndl CDVCustomDataVarHndl CDVDataArgHndl CDVDataSourceHndl CDVDataVarHndl CDVFunctionDataSourceHndl CDVFunctionDataVarHndl CDVCompareRuleCondition CDVControlRuleEvent CDVPickRuleCondition CDVRuleHndl CDVRuleAction CDVRuleCondition CDVRuleEvent CDVSetDataVarRuleAction CDVSimpleRuleAction CDVSimpleRuleCondition CDVSimpleRuleEvent CDVStringRuleAction

5 Table of Contents v CDVViewObjectRuleAction CDVViewRuleAction CDVArcDirectionDynamicHndl CDVArcDirectionThreshold CDVBasicDynamicHndl CDVBlinkDynamicHndl CDVBlinkThreshold CDVColorDynamicHndl CDVColorThreshold CDVCurveTypeThreshold CDVDynamicFeatureHndl CDVDynamicFeatureSetHndl CDVLineStyleDynamicHndl CDVLineStyleThreshold CDVLineWidthDynamicHndl CDVLineWidthThreshold CDVOutputThreshold CDVPolygonPathDynamic CDVSubdrawingDynamicHndl CDVSubdrawingThreshold CDVTextDynamic CDVThresholdDynamicHndl CDVVisibilityDynamicHndl CDVVisibilityThreshold Chapter 3: C++ Header Files Introduction to the C++ Header Files Defined Constants C++ Enumerated Types DataViews C++ Public Types Miscellaneous DataViews Public Types

6

7 1 Chapter 1 1 DataViews C++ Class Reference 1 Introduction to the DataViews C++ Classes This chapter gives descriptions of properties, methods, and events for the following classes: CDVBlinkMgr CDVBaseInterface CDVBaseRuleEngine CDVBaseViewWrapper CDVCustomControl CDVGenericViewWrapper CDVInterface CDVScrollBar CDVScrollView CDVViewWrapper CDVWinInterface CDVWinViewWrapper All properties are read/write unless otherwise noted. Methods that return return FALSE on failure. Failure usually results when the method requires a view to be attached to the interface but none is.

8 2 DataViews Visual C++ Reference Manual DataViews C++ Class Map The following figure illustrates the majority of the DataViews C++ classes and their relationships to each other. CDVBaseRuleEngine CDVBaseInterface CDVBaseViewWrapper CDVWinInterface CDVWinViewWrapper creates CDVInterface CDVViewWrapper wraps CDVCustomControl or a subclass of CDVSCrollView attaches DataViews View File

9 Chapter 1: DataViews C++ Class Reference 3 Coordinate Systems Some of the descriptions in this chapter refer to different coordinate systems. These coordinate systems work together to map drawing data structures to drawports and finally to the physical screen. To use the coordinate systems effectively, it helps to know which is which, and how to convert from one to another. The three coordinate systems mentioned in this chapter are described below. World Coordinate System The drawing viewport, the drawing object, and all graphical objects use the world coordinate system. Object position is specified in world coordinates. The full extent of the world coordinate system, and therefore of the drawing, is -16K to 16K ( to 16383) both horizontally and vertically. The center of the drawing is (0, 0) in world coordinates. The drawing space is square, as you can see in DV-Draw when you zoom out enough to see the whole drawing area. Device Coordinate System To draw a graphical object on a screen, you must convert the object s world coordinates to physical pixel-based coordinates. This step is complicated by the fact that physical screens and windows on those screens vary in their number of pixels. DataViews uses the device coordinate system, which is the usual Windows coordinate system. The origin (0, 0) is in the upper left corner of the screen. Since device coordinates are specified in pixels, the extent of the device coordinate system depends on the number of pixels in the horizontal and vertical dimension. Screen Coordinate System The window, which is represented in DV-Tools by the screen object, uses the screen coordinate system to display graphics. The screen coordinate system is a pixel-based coordinate system. It is the same as the device coordinates system, but with the origin (0, 0) at the lower left corner. The extent of the coordinate system depends on the number of pixels in the horizontal and vertical dimension. In a window system, such as X Window or Microsoft Windows, you can consider each window as an independent display device with its own origin. When you open the screen object representing the window, you set the extent of the window, and therefore the extent of the screen coordinate system.

10 4 DataViews Visual C++ Reference Manual If you are working in a non-windowing system, the physical device determines the extent of the screen coordinate system. Drawing Realm (16K, 16K) Physical Realm (32K, 32K) (800, 600) + (0,0) (-16K, -16K) World Coordinates + (16K, 16K) (400, 300) (0, 0) Device Coordinates (0, 0) Screen Coordinates The Three Coordinate Systems

11 Chapter 1: DataViews C++ Class Reference 5 CDVBlinkMgr This class manages blinking for DataViews objects with blink attributes or blink dynamics. An instance of this class is created internally, so you should not instantiate this class in your application. CDVBlinkMgr is intended primarily for internal use, but advanced programmers may find the following method useful. CDVBlinkMgr Methods GlobalUpdate Method static GlobalUpdate(UINT delta) Checks for objects with blinking and performs the blinking operations. This method is required only when you have to limit the number of timers in your application, and you want to set up your own timer instead of using the BlinkCheckPeriod property. In this situation, call this method in the your timer event handler. When you call this method, pass in delta, which specifies the amount of time, in milliseconds, since the last update. You can calculate delta using the system clock or by estimating the period between your timer events. CDVBlinkMgr Properties No properties for this object.

12 6 DataViews Visual C++ Reference Manual CDVBaseInterface The CDVBaseInterface class provides a common base of display functionality for a variety of programming environments. You use the methods on this class to display views, control how the view appears in the display area, manipulate objects within the view, and control the update rate of dynamic objects. This is an abstract class. The concrete class is CDVInterface. CDVBaseInterface Methods UpdateNamedObject Method AttachViewWrapper Method AttachViewWrapper(CDVViewHndl& vh) AttachViewWrapper(CString view_name) AttachViewWrapper( CString view_name, CDVViewHndl& vh) AttachViewWrapper makes the attachments between the view and the window. You can pass a pointer to a CDVBaseViewWrapper instance, a view name string, or a view name string together with a view handle. Most commonly, you pass a pointer to an instance of a class derived from CDVBaseViewWrapper. Each form of this method creates the drawport for you. In the cases where you pass a view_name string, it also creates an instance of CDVGenericViewWrapper. When you pass in just the view_name, without the view handle, the view is loaded for you as well. The drawport, the instance of CDVGenericViewWrapper, and any loaded views, are automatically destroyed for you. However, when you pass in a view handle, you must destroy the view handle yourself. If another view is already attached, this method calls SetDestroyOnDetach() automatically, so you do not have to call it explicitly. DetachViewWrapper Method DetachViewWrapper() Destroys the drawport created by AttachViewWrapper(). Also destroys the instance of CDVGenericViewWrapper if one was created by AttachViewWrapper(). Closes data sources and erases the screen automatically.

13 Chapter 1: DataViews C++ Class Reference 7 CheckStatus Method int CheckStatus(CString& errorstring) Returns the error code status for a given errorstring. Valid return values are: 0 - Screen was opened successfully. 1 - Reference to unknown device driver. 2 - Could not find the specified color table file. 3 - Unknown error from device driver. 4 - DataViews internal logical device table full. 5 - License failure -- Could not find a valid licence file. 6 - License failure -- Failed basic license check. 7 - License failure -- Failed to pass DataViews license check. 8 - License failure -- Error involving HP ID modules. 9 - License failure -- Could not acquire a floating license. Draw Method Draw() Performs the initial drawing of the view. Performed automatically if the DrawOnViewLoad property is set to TRUE. DrawNext Method DrawNext() Draws the next iteration of data in the view. Performed automatically if AutoUpdate is set to TRUE. DrawNextObject Method DrawNextObject(CDVObjectHndl& object) Draws the next iteration of a specific dynamic object in the view. This method takes an object. The preferred method is CDVObjectHndl::DrawNext().

14 8 DataViews Visual C++ Reference Manual DrawObject Method DrawObject(CDVObjectHndl& object) Performs the initial drawing of a specific object in the view. This method takes an object. EnableBlink Method EnableBlink( CDVObjectHndl& object, enable=true) EnableBlink( enable=true) Enables blinking for the specified object in the view. Use the BlinkCheckPeriod property to specify how often the application checks for objects that need to blink. Also see the EnableBlinkOnLoad property. When the object is not specified as a parameter, then the method enables blinking for all objects in the view. See also: CDVObjectHndl::EnableBlink(). Erase Method Erase() Erases the contents of the view. EraseObject Method EraseObject(CDVObjectHndl& object) Erases the specified object from the view. This method takes an object. This may not have the expected effect on an object that is dynamically updating. For instance, an object with movement dynamics would immediately reappear after it is erased. The preferred method is CDVObjectHdnl::Erase(). GetBaseRuleEngine Method CDVBaseRuleEngine* GetBaseRuleEngine() Returns a pointer to the CDVBaseRuleEngine class managing this interface.

15 Chapter 1: DataViews C++ Class Reference 9 GetBaseViewWrapper Method CDVBaseViewWrapper* GetBaseViewWrapper() Returns a pointer to the CDVBaseViewWrapper class. GetDlgItem Method CWnd* GetDlgItem(int nid) Returns a pointer to the specified control that is contained in the view. The pointer is usually cast to the type of control that corresponds with nid. GetDataVar Method CDVDataVarHndl GetDataVar(LPCTSTR varname) CDVDataVarHndl GetDataVar(LPCTSTR dsname, LPCTSTR dsvname) Returns the specified data source variable. You can specify the name of the data source variable either as a combination of the data source name and the variable name, such as default.dat/var1, orbyusingthedatasource name and the variable name separately, such as default.dat and Var1. GetHREF Method static GetHREF( CString& str, CString& href) Checks whether a string, usually an object name, is a reference to a URL address. If it is, returns TRUE and copies the URL address into href. Note that only the URL address is copied; angle brackets and the HREF= part of the string are stripped from the copy of the string. Returns FALSE if the string is not an HTML reference. For example, if the URL string, str, is <HREF= >,thenhref would then be GetNamedObject Method CDVObjectHndl GetNamedObject (LPCTSTR objname) Returns the DataViews object with the specified name.

16 10 DataViews Visual C++ Reference Manual This method takes the name of an object. GetObjectBounds Method GetObjectBounds( CDVObjectHndl& object, LONG& ll_x, LONG& ll_y, LONG& ur_x, LONG& ur_y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS) Gets the bounding box of the specified object. sys specifies the coordinate system to use in the coordinate values. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS The preferred method is CDVObjectHndl::GetBounds(). GetPointCoordinates Method GetPointCoordinates( CDVPointHndl& pt, LONG& x, LONG& y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS) Gets the coordinates of the specified point. sys specifies the coordinate system to use in the coordinate values. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS GetSelectedObject CDVObjectHndl GetSelectedObject() const for screen coordinates for world coordinates for device coordinates for screen coordinates for world coordinates for device coordinates Returns the object underneath the last mouse motion, mouse click, or keyboard event.

17 Chapter 1: DataViews C++ Class Reference 11 GetVariableNames Method GetVariableNames(CStringArray& array) const Gets all the variable names in the attached view and adds them to an array. GetView Method CDVViewHndl& GetView() const Gets the DataViews view object. IsDrawn Method IsDrawn() const Indicates whether the view has been drawn. MovePoint Method MovePoint( CDVPointHndl& pt, LONG x, LONG y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS, absolute = TRUE) Moves a point object to the specified coordinates. absolute specifies whether the specified coordinates are interpreted as absolute coordinates, which is the default, or as coordinates relative to the current position. sys specifies the coordinate system that x and y are specified in. Valid coordinate system options are: OpenData Method DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS OpenData () Opens the data sources for the current view. for screen coordinates for world coordinates for device coordinates

18 12 DataViews Visual C++ Reference Manual Pan Method Pan ( LONG x, LONG y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS) Centers the view around a point. sys specifies the coordinate system that x and y are specified in. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS The DV_DEVICE_COORDS option lets you pass coordinates from your mouse event handlers directly into the ZoomTo() method. PauseBlink Method PauseBlink( paused=true) When paused is TRUE, all currently blinking objects displayed in the view are frozen at their current colors. When paused is FALSE, all objects that were blinking before the blinking was paused will start blinking again. ReadData Method ReadData() Reads the next iteration of data into the data source variables. For instance, the next value from a file data source. Redraw Method Redraw( const RECTANGLE* rect =NULL, DV_COORD_SYSTEM sys = DV_WORLD_COORDS, erase=yes) for screen coordinates for world coordinates for device coordinates Redraws all or part of the view. If rect is specified, redraws this part of the view. If rect is NULL, redraws the entire view. sys specifies the coordinate system for the rectangular area. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS for screen coordinates for world coordinates

19 Chapter 1: DataViews C++ Class Reference 13 DV_DEVICE_COORDS If erase is TRUE, the specified portion is erased before being redrawn. If erase is FALSE, the objects in the specified portion are redrawn directly on top of the existing graphics. This is faster, but may not be clean enough for many situations. RedrawObject Method RedrawObject(CDVObjectHndl& object) Redraws the specified object in the view. This method takes an object. The preferred method is CDVObjectHndl::Redraw(). ScreenToWorldX Method LONG ScreenToWorldX(LONG x, LONG y) Converts the x component of a screen coordinate to a world value using pixels. One use for the ScreenToWorld* andworldtoscreen* methods is with the Zoom and Pan methods. The preferred method is CDVBaseInterface::TransformPoint(). ScreenToWorldY Method LONG ScreenToWorldY(LONG x, LONG y) for device coordinates Converts the y component of a screen coordinate to a world value using pixels. The preferred method is CDVBaseInterface::TransformPoint().

20 14 DataViews Visual C++ Reference Manual TransformPoint Method TransformPoint( LONG x1, LONG y1, DV_COORD_SYSTEM sys1, LONG& x2, LONG& y2, DV_COORD_SYSTEM sys2) TransformPoint( const DV_POINT pt1, DV_COORD_SYSTEM sys1, DV_POINT& pt2 DV_COORD_SYSTEM sys2) TransformPoint( const CPoint pt1, DV_COORD_SYSTEM sys1, CPoint& pt2, DV_COORD_SYSTEM sys2) Converts the coordinates of a point object from one coordinate system to another. You can specify the point object in any of the following ways: by x and y coordinates as a DataViews point object as an MFC point object sys1 and sys2 specify the starting and ending coordinate systems. Valid coordinate system options are: DV_SCREEN_COORDS for screen coordinates DV_WORLD_COORDS for world coordinates DV_DEVICE_COORDS for device coordinates

21 Chapter 1: DataViews C++ Class Reference 15 TransformRectangle Method TransformRectangle( LONG ll_x1, LONG ll_y1, LONG ur_x1, LONG ur_y1, DV_COORD_SYSTEM sys1, LONG& ll_x2, LONG& ll_y2, LONG& ur_x2, LONG& ur_y2, DV_COORD_SYSTEM sys2) TransformRectangle( const RECTANGLE& r1, DV_COORD_SYSTEM sys1, RECTANGLE& r2, DV_COORD_SYSTEM sys2) TransformRectangle( const CRect& r1, DV_COORD_SYSTEM sys1, CRect& r2, DV_COORD_SYSTEM sys2) Converts the coordinates of a rectangle object from one coordinate system to another. You can specify the rectangle in any of the following ways: with two points specified by x and y coordinates as a DataViews rectangle object as an MFC rectangle object sys1 and sys2 specify the starting and ending coordinate systems. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS Update Method Update() Updates and displays all the dynamic objects in the view. for screen coordinates for world coordinates for device coordinates

22 16 DataViews Visual C++ Reference Manual If the ReadDataOnUpdate property is set to TRUE, this method calls ReadData() and then calls DrawNext(). If the ReadDataOnUpdate property is set to FALSE, this method calls only DrawNext().If AutoUpdate is set to TRUE, this method is called in time intervals specified by the value of UpdatePeriod. UpdateNamedObject Method UpdateNamedObject(LPCTSTR objname) Updates the specified named object. If the view contains more than one object with the same name, only the first object found with that name is updated. This method takes the name of an object. If the ReadDataOnUpdate property is set to TRUE, opens the view s data sources if needed, and reads the data before updating the object. WorldToScreenX Method LONG WorldToScreenX(LONG x, LONG y) Converts the x component of a world coordinate to a screen value using pixels. One use for the ScreenToWorld* and WorldToScreen* methods is with the Zoom and Pan methods. The preferred method is CDVBaseInterface::TransformPoint(). WorldToScreenY Method LONG WorldToScreenY(LONG x, LONG y) Converts the y component of a world coordinate to a screen value using pixels. The preferred method is CDVBaseInterface::TransformPoint(). ZoomPanReset Method ZoomPanReset() Resets the zoom and pan settings to their original values. The display of the view is restored to the state it was in just after the view was loaded.

23 Chapter 1: DataViews C++ Class Reference 17 ZoomTo Method ZoomTo( LONG ll_x, LONG ll_y, LONG ur_x, LONG ur_y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS) Zooms the drawport to fit a rectangle defined by two points. sys specifies the coordinate system for the first four parameters. Valid coordinate system options are: DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS for screen coordinates for world coordinates for device coordinates The DV_DEVICE_COORDS option lets you pass coordinates from your mouse event handlers directly into the ZoomTo() method. CDVBaseInterface Properties EnableViewResTable Property LayerMask Property LevelOfDetail Property ViewResolution Property VisibilityMask Property VisibilityPriority Property

24 18 DataViews Visual C++ Reference Manual Anchor Property SetAnchor( DV_ANCHOR_TYPE value, RECTANGLE* wvp = 0) DV_ANCHOR_TYPE GetAnchor() Specifies the anchor type used for computing the drawing viewport when the drawport is created. Valid values are: DV_ANCHOR_NONE DV_ANCHOR_WORLD DV_ANCHOR_VIEW DV_ANCHOR_OBJECT DV_ANCHOR_RECTANGLE The default is DV_ANCHOR_NONE. You only need to pass a RECTANGLE* when DV_ANCHOR_TYPE is DV_ANCHOR_RECTANGLE. This property takes effect only when you load a view. For a more detailed discussion, see the Refining the View chapter in the DataViews C++ Programming Topics. AnchorName Property SetAnchorName(LPCTSTR value) CString GetAnchorName() Specifies the name of an object to use as the anchor when the Anchor property is set to DV_ANCHOR_OBJECT. If the name is not a valid name of an object in the view, the Anchor property is set to DV_ANCHOR_WORLD.

25 Chapter 1: DataViews C++ Class Reference 19 AnchorRectangle Property SetAnchorRectangle(const RECTANGLE* wvp) RECTANGLE GetAnchorRectangle() const Specifies the rectangular region of the view to be displayed when the drawport is created. The region is specified in world coordinates. This property is useful only when the Anchor property is DV_ANCHOR_RECTANGLE. AutoUpdate Property SetAutoUpdate( value) GetAutoUpdate() If set to TRUE, automatic updating occurs at the interval specified by the value of UpdatePeriod.IfsettoFALSE, automatic updating is discontinued. The update period value remains unaffected. The default is TRUE. BlinkCheckPeriod Property static SetBlinkCheckPeriod(ULONG millisec) static ULONG GetBlinkCheckPeriod() Specifies the interval, in milliseconds, between checking for objects that need to have their colors changed due to blinking. This method must be called before the call to AttachViewWrapper(), which attaches the view. ClickOnObjectFilter Property SetClickOnObjectFilter(DV_CLICK_FILTER value) DV_CLICK_FILTER GetClickOnObjectFilter() Determines whether a ClickOnObject event is generated by a mouse click.

26 20 DataViews Visual C++ Reference Manual Valid values are: Any object Named objects Name is HTML reference No objects The default is DV_NAMED_OBJECTS. When the user clicks with the mouse button in the window, either a Click or a ClickOnObject event occurs. Which event occurs depends partly on the ClickOnObjectFilter property. The user can click on a named object, on an unnamed object, on an object whose name is an HTML reference, or in the background area of the view. If a ClickOnObject event does not occur, a Click event does. The following table lists the placeswherethe usercan click (in theleft column), the ClickOnObjectFilter setting (across the top), and what kind of event occurs in each case. To turn off any reporting of ClickOnObject events, set this filter to DV_NO_OBJECTS. ClutFile Property SetClutFile(LPCTSTR value) CString GetClutFile() DV_ANY_ OBJECT DV_NAMED_ OBJECTS DV_ANY_OBJECT DV_NAMED_OBJECTS DV_HREF_OBJECTS DV_NO_OBJECTS DV_HREF_ OBJECTS DV_NO_ OBJECTS Named Objects ClickOnObject ClickOnObject Click Click Named Objects ClickOnObject ClickOnObject ClickOnObject Click (HREF) Unnamed ClickOnObject Click Click Click Objects View Background Click Click Click Click Specifies a color lookup table file. If this property is not set, the default color lookup table is used. You can change this property at any time in your program.

27 Chapter 1: DataViews C++ Class Reference 21 CommandHandler Property static SetCommandHandler(DVCOMMANDFUN set) static DVCOMMANDFUN GetCommandHandler() This property handles command functions that take an object handle, a view handle, and a command string. It is up to the application programmer to provide a command function handler by calling the SetCommandHandler() method. In this handler, the programmer can immediately pass the string to the system, but now the string can instead be interpreted in any way the application specifies (e.g. Tcl or VBscript commands). DrawMode Property SetDrawMode(DV_DRAW_MODE value) DV_DRAW_MODE GetDrawMode() const Specifies the drawing mode. Valid values are: Standard drawing XOR drawing Standard drawing is drawing the graphics onto a pixmap in preparation for displaying on the screen. This mode is similar to copying because the graphics are drawn as is, that is, they are copied. The XOR drawing mode draws the graphics by XORing the bits of their color with the color bits already being displayed. This advanced feature requires expert knowledge and setup. The default is DV_DRAW_MODE_COPY. DrawportStretch Property SetDrawportStretch( value) GetDrawportStretch() DV_DRAW_MODE_COPY DV_DRAW_MODE_XOR When this property is set to TRUE, stretches the display portion of the view to fit the window when the view is displayed. Objects in the view may be distorted. When FALSE, the display portion of the view is scaled to fit completely in the window; some additional area of the view may appear in the window. The default is TRUE. This property takes effect only when you load a view.

28 22 DataViews Visual C++ Reference Manual DrawportType Property SetDrawportType(DV_DRAWPORT_TYPE value) DV_DRAWPORT_TYPE GetDrawportType() Specifies the drawport style. Valid values are: Standard Fixed Scale The default is DV_STANDARD. DV_FIXED_SCALE is typically used in main application windows. This property takes effect only when you load a view. DrawViewOnLoad Property SetDrawViewOnLoad( value) GetDrawViewOnLoad() Specifies whether to automatically draw the view as soon as it has finished loading. The default is TRUE.IfFALSE, then the view is not drawn when it has finished loading, and you must use an explicit Draw() command to draw it. This lets advanced users rebind variables or add objects that are created programmatically. After performing these tasks, you can draw the view using the AfterViewLoaded event. DVPathPrefix Property SetDVPathPrefix(LPCTSTR path_string) const CString& GetDVPathPrefix() const DV_STANDARD DV_FIXED_SCALE Prepends directories to the path that DataViews searches when it is trying to locate view files, subdrawings, or file data sources. This path is also known as the DVPATH configuration variable. Since the directories specified here are searched before directories already in the path, use this property for higher priority directories. The directories specified in the string should be separated by semicolons.

29 Chapter 1: DataViews C++ Class Reference 23 DVPathSuffix Property SetDVPathSuffix(LPCTSTR path_string) const CString& GetDVPathSuffix() const Appends directories to the path that DataViews searches when it is trying to locate view files, subdrawings, or file data sources. This path is also known as the DVPATH configuration variable. Since the directories specified here are searched after directories already in the path, use this property for lower priority or alternative directories. The directories specified in the string should separated be by semicolons. EnableBlinkOnLoad Property SetEnableBlinkOnLoad( value) GetEnableBlinkOnLoad() This property enables blinking on all objects with blink attributes when the view is attached. It is an alternative to enabling blinking for objects on an individual basis. If set to TRUE, blinking starts automatically on all objects with blink attributes in the view. If set to FALSE, you must enable blinking explicitly for each object by calling EnableBlink(). TheFALSE setting makes the view display faster. The default is TRUE. This property takes effect only when you draw the view.

30 24 DataViews Visual C++ Reference Manual InitialScaleFactor Property SetInitialScaleFactor(double value) double GetInitialScaleFactor() const Sets the initial scale (or zoom) for the view. To be effective, this value must be set before the initial drawing of the view. The default value is 0.0. InputUsedFilter Property SetInputUsedFilter(DV_INPUTUSED_FILTER value) INPUTUSED_FILTER GetInputUsedFilter() Specifies the event filter for input objects in the view. Valid values are: Any input object Named input objects Name is HTML reference No input objects DV_ANY_INPUTOBJECT DV_NAMED_INPUTOBJECTS DV_HREF_INPUTOBJECTS DV_NO_INPUTOBJECTS The default is DV_NAMED_INPUTOBJECTS. When the user manipulates an input object, an InputUsed event may occur, depending partly on the value of this property. The user can click on a named input object, on an input object whose name is an HTML reference, on an unnamed input object, or anywhere in the view that is not an input object. The following table lists the places where the user can click (in the left column), the InputUsedFilter settings (across the top), and whether or not an InputUsed event occurs. DV_ANY_ INPUT- OBJECT DV_NAMED_ INPUT- OBJECTS DV_HREF_ INPUT- OBJECTS DV_NO_ INPUT- OBJECTS Named Input Objects Named Input Objects (HREF) InputUsed event InputUsed event InputUsed event InputUsed event no InputUsed event InputUsed event no InputUsed event no InputUsed event

31 Chapter 1: DataViews C++ Class Reference 25 Unnamed Input Objects Elsewhere in the View InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUs ed event no InputUsed event Remember that it may not be necessary to handle all input object interaction in your code. For example, if an input object s memory data source controls dynamic behavior in the view directly, all interaction with that input object is handled within the view and you do not need to handle its events in your code. In this case, you do not need to generate InputUsed events for that input object. You can either name the input object and set the InputUsedFilter property to DV_NO_INPUTOBJECTS, or leavethe input object unnamed and set the InputUsedFilter property to DV_NAMED_INPUTOBJECTS. The first case is only useful if you do not need to handle interaction from any input objects in the view; the second case is useful if you need to handle interaction from some input objects but not others. To turn off any reporting of InputUsed events, set this filter to DV_NO_INPUTOBJECTS. LevelOfDetail Property SetLevelOfDetail(ULONG value) ULONG GetLevelOfDetail() const Used mostly for zooming purposes. When you want to dictate the level of visibility on an object such that when you are zoomed in, certain objects are visible while others are invisible. As you zoom out, you can set the level of detail such that more and more objects are visible in the view. This property manages the object s visibility priority determined by the value parameter. A value of 1 is the highest visibility priority such that the object is always visible. A value of 7 is the lowest visibility priority.

32 26 DataViews Visual C++ Reference Manual LineStyleMode Property SetLineStyleMode(DV_LINESTYLE_MODE value) DV_LINESTYLE_MODE GetLineStyleMode() Since views created using DataViews on Unix platforms offer different line styles, these methods allows you to use Unix-based line styles in your C++ application. These methods handle a flag that indicates the line style mode: Valid values of the flag are DV_LINESTYLE_MODE_WINDOWS_ONLY for Window line style or DV_LINESTYLE_MODE_PORTABLE for Unix-based line style. MouseOverFilter Property SetMouseOverFilter(DV_MOUSEOVER_FILTER value) DV_MOUSEOVER_FILTER GetMouseOverFilter() const Determines whether a MouseOverChanged Event event is generated by a mouse motion. Valid values are: Any object Named objects Name is HTML reference No objects DV_MOUSEOVER_ANY_OBJECT DV_MOUSEOVER_NAMED_OBJECTS DV_MOUSEOVER_HREF_OBJECTS DV_MOUSEOVER_NO_OBJECTS Default is DV_MOUSEOVER_NO_OBJECTS, meaning that MouseOverChanged events are not generated. This is the default because it significantly increases the efficiency of the application. To turn onmouseoverchanged events, you must choose a different filter setting. When the user moves the mouse in the window, a MouseOverChanged event may occur, depending partly on this property. The MouseOverChanged event indicates that the mouse has crossed the boundary of an object in the view. This event can occur when the mouse crosses the boundary of an object, when it moves from being over one object to being over another object, or when it leaves the boundary of the object and is now over the background of the view. The boundaries that matter can be those for named objects, for unnamed objects, or for objects whose name is an HTML reference. The following table lists the kind of object whose boundary is crossed (in the left column), the MouseOverFilter setting (across the top), and whether an event occurs in each case.

33 Chapter 1: DataViews C++ Class Reference 27 Named Objects Named Objects (HREF) Unnamed Objects DV_ MOUSEOVER_A NY_ OBJECT MouseOver -Changed event MouseOver -Changed event MouseOver -Changed event DV_ MOUSEOVER_NA MED_ OBJECTS MouseOver- Changed event MouseOver- Changed event no MouseOver -Changed event DV_ MOUSEOVER_HR EF_ OBJECTS no MouseOver -Changed event MouseOver- Changed event no MouseOver -Changed event DV_ MOUSEOVER_NO _ OBJECTS no MouseOver -Changed event no MouseOver -Changed event no MouseOver -Changed event ReadDataOnUpdate Property SetReadDataOnUpdate( value) GetReadDataOnUpdate() If set to TRUE, data sources are opened, and data is read before each update. The default is FALSE, which does not initially open the data sources and does not read the data for each update. This property is effective only for File, Constant, and Function Data Source data sources. It has no effect for Memory data sources. ReportError Property static SetReportError(DV_GLOBAL_ERROR_ENUM set) static DV_GLOBAL_ERROR_ENUM GetReportError() Allows you to set or return the DV_GLOBAL_ERROR_ENUM enumerated type. The enum acts as an error notification system such that when set to 0, no errors are dispatched to the global error dialog. If set to 2, then every error is dispatched to the error dialog. When set to 1, objects that can handle error messages, such as the DVPlayer ActiveX control, are allowedtodoso.

34 28 DataViews Visual C++ Reference Manual ScaleFactor Property SetScaleFactor(double value) double GetScaleFactor() Specifies the drawport scale factor. The default is 1. This property is multiplied with the internal scale factor of the view. For example, a value of 0.5 displays the view at half its normal size, where normal size depends on the view s anchor setting. The scale factor is a relative scale. A factor of 1.0 is always defined to be the scale that the view appeared at when it was loaded. This is a relative scale as the same view may appear at two different sizes in two different Interfaces (due to different anchor types or drawport types) and yet in both cases ScaleFactor will be 1.0. It is useful when the user wants to make the view twice as large as it was when it appeared, or half the size, or exactly the same size, as they can simply set a value of 2.0, 0.5, or 1.0 without having to remember any other values. ShowCopyright Property SetShowCopyright( value) GetShowCopyright() If set to TRUE, displays the DataViews copyright screen during the initial screen creation. The default is TRUE. UpdatePeriod Property SetUpdatePeriod(int value) int GetUpdatePeriod() Specifies the time interval, in milliseconds, between automatic updates. An update period of 0 discontinues automatic updating and the previous update period value is lost. To stop/start automatic updating while preserving the same update period, toggle the AutoUpdate property. The default is 100.

35 Chapter 1: DataViews C++ Class Reference 29 ViewResolution ViewResolution

36 30 DataViews Visual C++ Reference Manual CDVBaseRuleEngine Manages rule objects. A rule object connects a graphical object to a description of an action that depends on a specified event and condition. For the action to occur, the application must be written to interpret the components of the rule. A rule has three components: an event, a condition, and an action. The event component specifies what type of event triggers the rule; the condition specifies the conditions under which the event triggers the action. The event is identified by a simple type flag: the condition and action descriptions are more complex and contain additional arguments. The rule object can be one of several rule objects in a table maintained by the graphical object, view, ActiveX control, or MFC control. The file dvrule.h defines the event, condition, and action constants that you can use to define rules in an application. The dvruletab.h file contains tables to help interpret conditions and actions. It is recommended to use DV-Draw to create and attach rules to objects in a view. The rules are saved as part of the view. CDVBaseRuleEngine Methods No methods for this object. CDVBaseRuleEngine Properties AllowSystemCall Property SetAllowSystemCall( value) GetAllowSystemCall() const Returns/sets a flag that is used to enable or disable the ExecuteCommandAction. This action allows you to make system level calls. The default value is TRUE.

37 Chapter 1: DataViews C++ Class Reference 31 AlwaysCheckViewRule Property SetAlwaysCheckViewRule( view_rule) GetAlwaysCheckViewRule() const Returns a boolean value that decides if a view rule should always get handled. If the value is TRUE, then the view rule always gets handled to see if an event triggers one of the rules. If the value is FALSE, then the view rule is handled only when an event did not trigger a rule on an object in the view. By default the value is FALSE. CheckAllRulesOnObject Property SetCheckAllRulesOnObject( all_rules_on_obj) GetCheckAllRulesOnObject() const Returns/sets a boolean value that determines whether to evaluate all of the rules on an object to see if they match an event. Returns TRUE when all the rules are to be evaluated, otherwise returns FALSE. Set all_rules_on_obj to TRUE to evaluates all of the rules, otherwise set to FALSE.When set to FALSE, only the first rule that matches the event is evaluated. By default, this is set to TRUE. Enabled Property SetEnabled( enabled) GetEnabled() const Returns a boolean flag that enables or disables the rule engine. Set enabled to TRUE to enable the engine, or set enabled to FALSE to disable the engine. The rule engine must be enabled for the events to trigger the rules on the objects in the view. The default value is TRUE.

38 32 DataViews Visual C++ Reference Manual EventUsed Property SetEventUsed( event_used) GetEventUsed() const Returns/sets the status of the previous event. Determines if the last event was used. UpdateRateFactor Property SetUpdateRateFactor(int update_rate_factor) int GetUpdateRateFactor() const Returns/sets the change in the update rate. By default, the update rate factor is 2. ViewChanged Property GetViewChanged() const Returns a boolean flag if a view has been changed due to a rule action. TRUE for a changed view, otherwise FALSE. CDVBaseRuleEngine Events No events for this object.

39 Chapter 1: DataViews C++ Class Reference 33 CDVBaseViewWrapper This class effectively acts as a wrapper around your view, creating a link between the DataViews view and any MFC controls in the application. The CDVBaseViewWrapper class allows you to implement message handlers in your DataViews view that are then accessible through DataViews and MFC classes and methods. This class also provides access to many of the properties, and methods found on the CDVBaseInterface class when the class is attached to an interface. You can use DV-Draw to generate C++ classes related to your views that are in turn derived from the CDVBaseViewWrapper class. CDVBaseViewWrapper Constructor CDVBaseViewWrapper(CString view_name, CDVViewHndl& vh) CDVBaseViewWrapper(CString view_name) This constructor allows you to pass a view name string, or a view name string together with a view handle. In the second case, the view handle is the parameter that is actually used, the view name is used as a reference. CDVBaseViewWrapper Methods DestroyView Method DestroyView() Destroys the DataViews view object. GetDVBaseInterface Method CDVBaseInterface* GetDVBaseInterface() Returns a pointer to the base interface class that was created when the window was created. GetOwner Method CWnd* GetOwner() const Returns the window handle of the container that is displaying the view, which is either a CDVCustomControl or a CDVScrollView, depending on the situation.

40 34 DataViews Visual C++ Reference Manual GetView Method CDVViewHndl& GetView() const Gets the DataViews view object, such as View1.v. GetViewName Method CString GetViewName() const Returns the filename of the DataViews view object. IsAttached Method IsAttached() const Indicates whether the view is attached to a window. CDVBaseViewWrapper Convenience Methods The following methods are provided as convenience, or pass-through methods. When you use them, you don t have to use GetDVInterface() to get the CDVInterface object and then use the corresponding CDVBaseInterface method. Note that pass-through methods do not work in the BeforeAttach() message handler. For descriptions of these methods, see the corresponding methods in the CDVBaseInterface section. CreatePoint Draw DrawNext DrawNextObject DrawObject EnableBlink Erase EraseObject GetDrawport GetDataVar GetHREF GetNamedObject GetObjectBounds

41 Chapter 1: DataViews C++ Class Reference 35 GetPointCoordinates GetScreen GetVariableNames IsDrawn MovePoint OpenData Pan PauseBlink ReadData RebindData Redraw RedrawObject ScreenToWorldX ScreenToWorldY TransformRectangle TransformPoint Update UpdateNamedObject WorldToScreenX WorldToScreenY ZoomPanReset ZoomTo CDVBaseViewWrapper Events Events are generated to communicate information to your application. The following descriptions include any parameters that your message handler will have, together with their parameter types. AfterAttach Event AfterAttach() This event occurs immediately after a view is attached to a window. You can use this event for view setup, such as accessing objects and Windows controls, and setting up data buffers for the dynamic objects.

42 36 DataViews Visual C++ Reference Manual AfterDrawNext Event AfterDrawNext() This event occurs immediately after all DataViews objects in the view have been updated. The event occurs whenever Update() or DrawNext() is called either explicitly or through the AutoUpdate property. Thisgives the application the opportunitytoperform any explicit updating on individual objects, particularly objects that are not updated by the Update() or DrawNext() call. This includes DataViews objects that are not in the drawing and thirdparty controls in the DataViews custom container. AfterInitialDraw Event AfterInitialDraw() This event occurs immediately after the DataViews view is drawn on the screen for the first time. AfterReadData Event AfterReadData() This event occurs immediately after the data sources are read, so the data source variable buffers contain the new data. This gives the application the opportunity to massage or filter data before displaying it. This event is called whenever ReadData() is called, either explicitly or through the AutoUpdate property. AfterResize Event AfterResize() This event occurs immediately after the window has been resized. BeforeDetach Event BeforeDetach() This event occurs before a view is detached from a window. If you have manually connected to a data base, you can close data connections here.

43 Chapter 1: DataViews C++ Class Reference 37 BeforeDrawNext Event BeforeDrawNext() This event occurs immediately before all DataViews objects in the view have been updated. The event occurs whenever Update() or DrawNext() is called either explicitly or through the AutoUpdate property. Thisgives the application the opportunitytoperform any explicit updating on individual objects, particularly objects that are not updated by the Update() or DrawNext() call. This includes DataViews objects that are not in the drawing and thirdparty controls in the DataViews custom container. BeforeReadData Event BeforeReadData() This event occurs immediately before the data sources are read. This gives the application the opportunity to act on the data sources before reading in their data. This event is called whenever ReadData() is called, either explicitly or through the AutoUpdate property. Click Event Click() This event may occur when the user clicks a mouse button. Whether the Click event occurs or the ClickOnObject event occurs depends on the value of the ClickOnObjectFilter property and the nature of the object if the user clicks on an object in the drawing. When the user clicks, the following results can occur: If the user clicks over an object, a ClickOnObject event can occur in place of a Click event. This depends on the value of the ClickOnObjectFilter Property property, so see the description of this property. IfClickOnObject does not occur, a Click event occurs.

44 38 DataViews Visual C++ Reference Manual ClickOnObject Event ClickOnObject( int button, long x, long y, CDVObjectHndl& object, CString objname) This event may occur when the user clicks a mouse button over any object. This event lets you build hot spots in your view. Whether the ClickOnObject event occurs or the Click event occurs depends on the value of the ClickOnObjectFilter property and the nature of the object if the user clicks on an object in the drawing. When the user clicks over an object, one the following happens: If the user clicks over an object, a ClickOnObject event can occur in place of a Click event. This depends on the value of the ClickOnObjectFilter Property property, so see the description of this property. IfClickOnObject does not occur, a Click event occurs. Note that the user must click the mouse button both down and up within the same object in order for a ClickOnObject event to occur on that object. The event includes an int indicating the button pressed, the event location, the object, and the object name if there is one. The event location is in world coordinates. Defined constants for buttons are discussed in the Defined Constants section. InputUsed Event InputUsed( int state, CDVObjectHndl& input, CString objname, CDVDataVarHndl&, double* value) This event occurs when an input object has been used. The event includes the event result, the object, the object name if there is one, the variable value, and the variable name. Possible values for the event result are defined in dvinteract.h. The variable value returns an array of doubles. The InputUsedFilter Property determines whether this event is generated. InputUsed events can be generated for any input object when the InputUsedFilter is set to DV_ANY_INPUTOBJECT, only for named input objects when set to DV_NAMED_INPUTOBJECTS, or for no objects when set to DV_NO_INPUTOBJECTS. The default is DV_NAMED_INPUTOBJECTS.

45 Chapter 1: DataViews C++ Class Reference 39 value must be cast to correspond to the type of value used by the input object. The correct type depends on what kind of input object was manipulated. MouseOverChanged Event MouseOverChanged( long x, long y, OBJECT object, CString object_name) This event may occur when the user moves the mouse over an object boundary, when it moves from one object to over another object, or when it leaves the boundary of the object and is over the background of the view. This event lets you build hot spots in your view that display information when the mouse moves over them. The generation of these events depends on the value of the MouseOverFilter Property property, so see the description of this property. By default, these events are not generated. You must set the MouseOverFilter property to a non-default value to receive events. The event contains the event coordinates, the object, and the object name if there is one. The event coordinates are in screen coordinates. Note that the event does not contain information about the prior object that the mouse was over. If you need this information, you must write the code that tracks it. CDVBaseViewWrapper Properties DestroyOnDetach Property GetDestroyOnDetach() SetDestroyOnDetach( value) Automatically destroys the instance of the view wrapper when a DetachViewWrapper() occurs. Do not set this property to TRUE if this view wrapper instance could be detached while executing one of its own handlers, since the DestroyOnDetach would then result in destroying the view wrapper that is currently executing the handler. The default is FALSE.